org.jivesoftware.smackx.omemo.internal

Class OmemoSession<T_IdKeyPair,T_IdKey,T_PreKey,T_SigPreKey,T_Sess,T_Addr,T_ECPub,T_Bundle,T_Ciph>

java.lang.Object

org.jivesoftware.smackx.omemo.internal.OmemoSession<T_IdKeyPair,T_IdKey,T_PreKey,T_SigPreKey,T_Sess,T_Addr,T_ECPub,T_Bundle,T_Ciph>

Type Parameters:

T_IdKeyPair - IdentityKeyPair class

T_IdKey - IdentityKey class

T_PreKey - PreKey class

T_SigPreKey - SignedPreKey class

T_Sess - Session class

T_Addr - Address class

T_ECPub - Elliptic Curve PublicKey class

T_Bundle - Bundle class

T_Ciph - Cipher class

Direct Known Subclasses:

SignalOmemoSession

public abstract class OmemoSession<T_IdKeyPair,T_IdKey,T_PreKey,T_SigPreKey,T_Sess,T_Addr,T_ECPub,T_Bundle,T_Ciph>
extends Object

This class represents a OMEMO session between us and another device.

Field Summary

Fields

Modifier and Type	Field and Description
protected T_Ciph	cipher
protected T_IdKey	identityKey
protected OmemoManager	omemoManager
protected OmemoStore<T_IdKeyPair,T_IdKey,T_PreKey,T_SigPreKey,T_Sess,T_Addr,T_ECPub,T_Bundle,T_Ciph>	omemoStore
protected int	preKeyId
protected OmemoDevice	remoteDevice

Constructor Summary

Constructors

Constructor and Description
OmemoSession(OmemoManager omemoManager, OmemoStore<T_IdKeyPair,T_IdKey,T_PreKey,T_SigPreKey,T_Sess,T_Addr,T_ECPub,T_Bundle,T_Ciph> omemoStore, OmemoDevice remoteDevice) Another constructor used when they establish the session with us.
OmemoSession(OmemoManager omemoManager, OmemoStore<T_IdKeyPair,T_IdKey,T_PreKey,T_SigPreKey,T_Sess,T_Addr,T_ECPub,T_Bundle,T_Ciph> omemoStore, OmemoDevice remoteDevice, T_IdKey identityKey) Constructor used when we establish the session.

Method Summary

Modifier and Type	Method and Description
abstract T_Ciph	createCipher(OmemoDevice contact) Create a new SessionCipher used to encrypt/decrypt keys.
static Message	decryptMessageElement(OmemoElement element, CipherAndAuthTag cipherAndAuthTag) Use the symmetric key in cipherAndAuthTag to decrypt the payload of the omemoMessage.
Message	decryptMessageElement(OmemoElement element, int keyId) Try to decrypt the message.
abstract byte[]	decryptMessageKey(byte[] encryptedKey) Decrypt a messageKey using our sessionCipher.
CipherAndAuthTag	decryptTransportedKey(OmemoElement element, int keyId) Try to decrypt the transported message key using the double ratchet session.
abstract CiphertextTuple	encryptMessageKey(byte[] messageKey) Encrypt a message key for the recipient.
OmemoFingerprint	getFingerprint() Return the fingerprint of the contacts identityKey.
T_IdKey	getIdentityKey() Return the identityKey of the session.
int	getPreKeyId() Get the id of the preKey used to establish the session.
void	setIdentityKey(T_IdKey identityKey) Set the identityKey of the remote device.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

cipher

protected final T_Ciph cipher

omemoStore

protected final OmemoStore<T_IdKeyPair,T_IdKey,T_PreKey,T_SigPreKey,T_Sess,T_Addr,T_ECPub,T_Bundle,T_Ciph> omemoStore

remoteDevice

protected final OmemoDevice remoteDevice

omemoManager

protected final OmemoManager omemoManager

identityKey

protected T_IdKey identityKey

preKeyId

protected int preKeyId

Constructor Detail

OmemoSession

public OmemoSession(OmemoManager omemoManager,
                    OmemoStore<T_IdKeyPair,T_IdKey,T_PreKey,T_SigPreKey,T_Sess,T_Addr,T_ECPub,T_Bundle,T_Ciph> omemoStore,
                    OmemoDevice remoteDevice,
                    T_IdKey identityKey)

Constructor used when we establish the session.

Parameters:

omemoManager - OmemoManager of our device

omemoStore - OmemoStore where we want to store the session and get key information from

remoteDevice - the OmemoDevice we want to establish the session with

identityKey - identityKey of the recipient

OmemoSession

public OmemoSession(OmemoManager omemoManager,
                    OmemoStore<T_IdKeyPair,T_IdKey,T_PreKey,T_SigPreKey,T_Sess,T_Addr,T_ECPub,T_Bundle,T_Ciph> omemoStore,
                    OmemoDevice remoteDevice)

Another constructor used when they establish the session with us.

Parameters:

omemoManager - OmemoManager of our device

omemoStore - OmemoStore we want to store the session and their key in

remoteDevice - identityKey of the partner

Method Detail

decryptTransportedKey

public CipherAndAuthTag decryptTransportedKey(OmemoElement element,
                                              int keyId)
                                       throws CryptoFailedException,
                                              NoRawSessionException

Try to decrypt the transported message key using the double ratchet session.

Parameters:

element - omemoElement

keyId - our keyId

Returns:

tuple of cipher generated from the unpacked message key and the authtag

Throws:

CryptoFailedException - if decryption using the double ratchet fails

NoRawSessionException - if we have no session, but the element was NOT a PreKeyMessage

decryptMessageElement

public static Message decryptMessageElement(OmemoElement element,
                                            CipherAndAuthTag cipherAndAuthTag)
                                     throws CryptoFailedException

Use the symmetric key in cipherAndAuthTag to decrypt the payload of the omemoMessage. The decrypted payload will be the body of the returned Message.

Parameters:

element - omemoElement containing a payload.

cipherAndAuthTag - cipher and authentication tag.

Returns:

Message containing the decrypted payload in its body.

Throws:

CryptoFailedException

decryptMessageElement

public Message decryptMessageElement(OmemoElement element,
                                     int keyId)
                              throws CryptoFailedException,
                                     NoRawSessionException

Try to decrypt the message. First decrypt the message key using our session with the sender. Second use the decrypted key to decrypt the message. The decrypted content of the 'encrypted'-element becomes the body of the clear text message.

Parameters:

element - OmemoElement

keyId - the key we want to decrypt (usually our own device id)

Returns:

message as plaintext

Throws:

CryptoFailedException

NoRawSessionException

createCipher

public abstract T_Ciph createCipher(OmemoDevice contact)

Create a new SessionCipher used to encrypt/decrypt keys. The cipher typically implements the ratchet and KDF-chains.

Parameters:

contact - OmemoDevice

Returns:

SessionCipher

getPreKeyId

public int getPreKeyId()

Get the id of the preKey used to establish the session.

Returns:

id

encryptMessageKey

public abstract CiphertextTuple encryptMessageKey(byte[] messageKey)
                                           throws CryptoFailedException

Encrypt a message key for the recipient. This key can be deciphered by the recipient with its corresponding session cipher. The key is then used to decipher the message.

Parameters:

messageKey - serialized key to encrypt

Returns:

A CiphertextTuple containing the ciphertext and the messageType

Throws:

CryptoFailedException

decryptMessageKey

public abstract byte[] decryptMessageKey(byte[] encryptedKey)
                                  throws CryptoFailedException,
                                         NoRawSessionException

Decrypt a messageKey using our sessionCipher. We can use that key to decipher the actual message. Same as encryptMessageKey, just the other way round.

Parameters:

encryptedKey - encrypted key

Returns:

serialized decrypted key or null

Throws:

CryptoFailedException - when decryption fails.

NoRawSessionException - when no session was found in the double ratchet library

getIdentityKey

public T_IdKey getIdentityKey()

Return the identityKey of the session.

Returns:

identityKey

setIdentityKey

public void setIdentityKey(T_IdKey identityKey)

Set the identityKey of the remote device.

Parameters:

identityKey - identityKey

getFingerprint

public OmemoFingerprint getFingerprint()

Return the fingerprint of the contacts identityKey.

Returns:

fingerprint or null