org.whispersystems.libsignal

Class SessionCipher

java.lang.Object

org.whispersystems.libsignal.SessionCipher

public class SessionCipher
extends java.lang.Object

The main entry point for Signal Protocol encrypt/decrypt operations. Once a session has been established with SessionBuilder, this class can be used for all encrypt/decrypt operations within that session.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.Object	SESSION_LOCK

Constructor Summary

Constructors

Constructor and Description
SessionCipher(SessionStore sessionStore, PreKeyStore preKeyStore, SignedPreKeyStore signedPreKeyStore, IdentityKeyStore identityKeyStore, SignalProtocolAddress remoteAddress) Construct a SessionCipher for encrypt/decrypt operations on a session.
SessionCipher(SignalProtocolStore store, SignalProtocolAddress remoteAddress)

Method Summary

Modifier and Type	Method and Description
byte[]	decrypt(PreKeySignalMessage ciphertext) Decrypt a message.
byte[]	decrypt(PreKeySignalMessage ciphertext, DecryptionCallback callback) Decrypt a message.
byte[]	decrypt(SignalMessage ciphertext) Decrypt a message.
byte[]	decrypt(SignalMessage ciphertext, DecryptionCallback callback) Decrypt a message.
CiphertextMessage	encrypt(byte[] paddedMessage) Encrypt a message.
int	getRemoteRegistrationId()
int	getSessionVersion()

Methods inherited from class java.lang.Object

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

Field Detail

SESSION_LOCK

public static final java.lang.Object SESSION_LOCK

Constructor Detail

SessionCipher

public SessionCipher(SessionStore sessionStore,
                     PreKeyStore preKeyStore,
                     SignedPreKeyStore signedPreKeyStore,
                     IdentityKeyStore identityKeyStore,
                     SignalProtocolAddress remoteAddress)

Construct a SessionCipher for encrypt/decrypt operations on a session. In order to use SessionCipher, a session must have already been created and stored using SessionBuilder.

Parameters:

sessionStore - The SessionStore that contains a session for this recipient.

remoteAddress - The remote address that messages will be encrypted to or decrypted from.

SessionCipher

public SessionCipher(SignalProtocolStore store,
                     SignalProtocolAddress remoteAddress)

Method Detail

encrypt

public CiphertextMessage encrypt(byte[] paddedMessage)
                          throws UntrustedIdentityException

Encrypt a message.

Parameters:

paddedMessage - The plaintext message bytes, optionally padded to a constant multiple.

Returns:

A ciphertext message encrypted to the recipient+device tuple.

Throws:

UntrustedIdentityException

decrypt

public byte[] decrypt(PreKeySignalMessage ciphertext)
               throws DuplicateMessageException,
                      LegacyMessageException,
                      InvalidMessageException,
                      InvalidKeyIdException,
                      InvalidKeyException,
                      UntrustedIdentityException

Decrypt a message.

Parameters:

ciphertext - The PreKeySignalMessage to decrypt.

Returns:

The plaintext.

Throws:

InvalidMessageException - if the input is not valid ciphertext.

DuplicateMessageException - if the input is a message that has already been received.

LegacyMessageException - if the input is a message formatted by a protocol version that is no longer supported.

InvalidKeyIdException - when there is no local PreKeyRecord that corresponds to the PreKey ID in the message.

InvalidKeyException - when the message is formatted incorrectly.

UntrustedIdentityException - when the IdentityKey of the sender is untrusted.

decrypt

public byte[] decrypt(PreKeySignalMessage ciphertext,
                      DecryptionCallback callback)
               throws DuplicateMessageException,
                      LegacyMessageException,
                      InvalidMessageException,
                      InvalidKeyIdException,
                      InvalidKeyException,
                      UntrustedIdentityException

Decrypt a message.

Parameters:

ciphertext - The PreKeySignalMessage to decrypt.

callback - A callback that is triggered after decryption is complete, but before the updated session state has been committed to the session DB. This allows some implementations to store the committed plaintext to a DB first, in case they are concerned with a crash happening between the time the session state is updated but before they're able to store the plaintext to disk.

Returns:

The plaintext.

Throws:

InvalidMessageException - if the input is not valid ciphertext.

DuplicateMessageException - if the input is a message that has already been received.

LegacyMessageException - if the input is a message formatted by a protocol version that is no longer supported.

InvalidKeyIdException - when there is no local PreKeyRecord that corresponds to the PreKey ID in the message.

InvalidKeyException - when the message is formatted incorrectly.

UntrustedIdentityException - when the IdentityKey of the sender is untrusted.

decrypt

public byte[] decrypt(SignalMessage ciphertext)
               throws InvalidMessageException,
                      DuplicateMessageException,
                      LegacyMessageException,
                      NoSessionException,
                      UntrustedIdentityException

Decrypt a message.

Parameters:

ciphertext - The SignalMessage to decrypt.

Returns:

The plaintext.

Throws:

InvalidMessageException - if the input is not valid ciphertext.

DuplicateMessageException - if the input is a message that has already been received.

LegacyMessageException - if the input is a message formatted by a protocol version that is no longer supported.

NoSessionException - if there is no established session for this contact.

UntrustedIdentityException

decrypt

public byte[] decrypt(SignalMessage ciphertext,
                      DecryptionCallback callback)
               throws InvalidMessageException,
                      DuplicateMessageException,
                      LegacyMessageException,
                      NoSessionException,
                      UntrustedIdentityException

Decrypt a message.

Parameters:

ciphertext - The SignalMessage to decrypt.

callback - A callback that is triggered after decryption is complete, but before the updated session state has been committed to the session DB. This allows some implementations to store the committed plaintext to a DB first, in case they are concerned with a crash happening between the time the session state is updated but before they're able to store the plaintext to disk.

Returns:

The plaintext.

Throws:

InvalidMessageException - if the input is not valid ciphertext.

DuplicateMessageException - if the input is a message that has already been received.

LegacyMessageException - if the input is a message formatted by a protocol version that is no longer supported.

NoSessionException - if there is no established session for this contact.

UntrustedIdentityException

getRemoteRegistrationId

public int getRemoteRegistrationId()

getSessionVersion

public int getSessionVersion()