org.jivesoftware.smackx.omemo

Class OmemoManager

java.lang.Object

org.jivesoftware.smack.Manager

org.jivesoftware.smackx.omemo.OmemoManager

public final class OmemoManager
extends Manager

Manager that allows sending messages encrypted with OMEMO. This class also provides some methods useful for a client that implements OMEMO.

Method Summary

Modifier and Type	Method and Description
void	addOmemoMessageListener(OmemoMessageListener listener)
void	addOmemoMucMessageListener(OmemoMucMessageListener listener)
void	buildSessionsWith(BareJid contact) Build OMEMO sessions with devices of contact.
boolean	contactSupportsOmemo(BareJid contact) Returns true, if the contact has any active devices published in a deviceList.
OmemoVAxolotlElement	createKeyTransportElement(byte[] aesKey, byte[] iv, OmemoDevice... to) Create a new KeyTransportElement.
ClearTextMessage	decrypt(BareJid sender, Message omemoMessage) Decrypt an OMEMO message.
java.util.List<ClearTextMessage>	decryptMamQueryResult(MamManager.MamQueryResult mamQueryResult) Return a list of all OMEMO messages that were found in the MAM query result, that could be successfully decrypted.
void	distrustOmemoIdentity(OmemoDevice device, OmemoFingerprint fingerprint) Distrust the fingerprint/OmemoDevice tuple.
Message	encrypt(java.util.ArrayList<BareJid> recipients, java.lang.String message) OMEMO encrypt a cleartext message for multiple recipients.
Message	encrypt(BareJid to, java.lang.String message) OMEMO encrypt a cleartext message for a single recipient.
Message	encrypt(MultiUserChat muc, java.lang.String message) Encrypt a message for all recipients in the MultiUserChat.
Message	encryptForExistingSessions(CannotEstablishOmemoSessionException exception, java.lang.String message) Encrypt a message for all users we could build a session with successfully in a previous attempt.
java.util.HashMap<OmemoDevice,OmemoFingerprint>	getActiveFingerprints(BareJid contact) Return all fingerprints of active devices of a contact.
int	getDeviceId() Return the deviceId of this OmemoManager.
OmemoFingerprint	getFingerprint(OmemoDevice device)
static OmemoManager	getInstanceFor(XMPPConnection connection) Get an instance of the OmemoManager for the given connection.
static OmemoManager	getInstanceFor(XMPPConnection connection, java.lang.Integer deviceId) Get an instance of the OmemoManager for the given connection and deviceId.
OmemoFingerprint	getOurFingerprint() Return the fingerprint of our identity key.
OmemoDevice	getOwnDevice() Return the OmemoDevice of the user.
BareJid	getOwnJid() Return the BareJid of the user.
void	initialize() Initializes the OmemoManager.
boolean	isDecidedOmemoIdentity(OmemoDevice device, OmemoFingerprint fingerprint) Returns true, if the fingerprint/OmemoDevice tuple is decided by the user.
boolean	isTrustedOmemoIdentity(OmemoDevice device, OmemoFingerprint fingerprint) Returns true, if the fingerprint/OmemoDevice tuple is trusted, otherwise false.
boolean	multiUserChatSupportsOmemo(EntityBareJid multiUserChat) Returns true, if the MUC with the EntityBareJid multiUserChat is non-anonymous and members only (prerequisite for OMEMO encryption in MUC).
void	purgeDevices() Clear all other devices except this one from our device list and republish the list.
static int	randomDeviceId()
void	regenerate() Generate fresh identity keys and bundle and publish it to the server.
void	removeOmemoMessageListener(OmemoMessageListener listener)
void	removeOmemoMucMessageListener(OmemoMucMessageListener listener)
void	requestDeviceListUpdateFor(BareJid contact) Request a deviceList update from contact contact.
void	rotateSignedPreKey() Rotate the signedPreKey published in our OmemoBundle.
void	sendRatchetUpdateMessage(OmemoDevice recipient) Send a ratchet update message.
static boolean	serverSupportsOmemo(XMPPConnection connection, DomainBareJid server) Returns true, if the Server supports PEP.
void	shutdown() Remove all active stanza listeners of this manager from the connection.
static boolean	stanzaContainsOmemoElement(Stanza stanza) Return true, if the given Stanza contains an OMEMO element 'encrypted'.
void	trustOmemoIdentity(OmemoDevice device, OmemoFingerprint fingerprint) Trust that a fingerprint belongs to an OmemoDevice.

Methods inherited from class org.jivesoftware.smack.Manager

connection, getAuthenticatedConnectionOrThrow

Methods inherited from class java.lang.Object

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

Method Detail

getInstanceFor

public static OmemoManager getInstanceFor(XMPPConnection connection,
                                          java.lang.Integer deviceId)

Get an instance of the OmemoManager for the given connection and deviceId.

Parameters:

connection - Connection

deviceId - deviceId of the Manager. If the deviceId is null, a random id will be generated.

Returns:

an OmemoManager

getInstanceFor

public static OmemoManager getInstanceFor(XMPPConnection connection)

Get an instance of the OmemoManager for the given connection. This method creates the OmemoManager for the stored defaultDeviceId of the connections user. If there is no such id is stored, it uses a fresh deviceId and sets that as defaultDeviceId instead.

Parameters:

connection - connection

Returns:

OmemoManager

initialize

public void initialize()
                throws CorruptedOmemoKeyException,
                       java.lang.InterruptedException,
                       SmackException.NoResponseException,
                       SmackException.NotConnectedException,
                       XMPPException.XMPPErrorException,
                       SmackException.NotLoggedInException,
                       PubSubException.NotALeafNodeException

Initializes the OmemoManager. This method is called automatically once the client logs into the server successfully.

Throws:

CorruptedOmemoKeyException

java.lang.InterruptedException

SmackException.NoResponseException

SmackException.NotConnectedException

XMPPException.XMPPErrorException

SmackException.NotLoggedInException

PubSubException.NotALeafNodeException

encrypt

public Message encrypt(BareJid to,
                       java.lang.String message)
                throws CryptoFailedException,
                       UndecidedOmemoIdentityException,
                       java.security.NoSuchAlgorithmException,
                       java.lang.InterruptedException,
                       CannotEstablishOmemoSessionException,
                       SmackException.NotConnectedException,
                       SmackException.NoResponseException

OMEMO encrypt a cleartext message for a single recipient.

Parameters:

to - recipients barejid

message - text to encrypt

Returns:

encrypted message

Throws:

CryptoFailedException - when something crypto related fails

UndecidedOmemoIdentityException - When there are undecided devices

java.security.NoSuchAlgorithmException

java.lang.InterruptedException

CannotEstablishOmemoSessionException - when we could not create session withs all of the recipients devices.

SmackException.NotConnectedException

SmackException.NoResponseException

encrypt

public Message encrypt(java.util.ArrayList<BareJid> recipients,
                       java.lang.String message)
                throws CryptoFailedException,
                       UndecidedOmemoIdentityException,
                       java.security.NoSuchAlgorithmException,
                       java.lang.InterruptedException,
                       CannotEstablishOmemoSessionException,
                       SmackException.NotConnectedException,
                       SmackException.NoResponseException

OMEMO encrypt a cleartext message for multiple recipients.

Parameters:

recipients - recipients barejids

message - text to encrypt

Returns:

encrypted message.

Throws:

CryptoFailedException - When something crypto related fails

UndecidedOmemoIdentityException - When there are undecided devices.

java.security.NoSuchAlgorithmException

java.lang.InterruptedException

CannotEstablishOmemoSessionException - When there is one recipient, for whom we failed to create a session with every one of their devices.

SmackException.NotConnectedException

SmackException.NoResponseException

encrypt

public Message encrypt(MultiUserChat muc,
                       java.lang.String message)
                throws UndecidedOmemoIdentityException,
                       java.security.NoSuchAlgorithmException,
                       CryptoFailedException,
                       XMPPException.XMPPErrorException,
                       SmackException.NotConnectedException,
                       java.lang.InterruptedException,
                       SmackException.NoResponseException,
                       NoOmemoSupportException,
                       CannotEstablishOmemoSessionException

Encrypt a message for all recipients in the MultiUserChat.

Parameters:

muc - multiUserChat

message - message to send

Returns:

encrypted message

Throws:

UndecidedOmemoIdentityException - when there are undecided devices.

java.security.NoSuchAlgorithmException

CryptoFailedException

XMPPException.XMPPErrorException

SmackException.NotConnectedException

java.lang.InterruptedException

SmackException.NoResponseException

NoOmemoSupportException - When the muc doesn't support OMEMO.

CannotEstablishOmemoSessionException - when there is a user for whom we could not create a session with any of their devices.

encryptForExistingSessions

public Message encryptForExistingSessions(CannotEstablishOmemoSessionException exception,
                                          java.lang.String message)
                                   throws CryptoFailedException,
                                          UndecidedOmemoIdentityException

Encrypt a message for all users we could build a session with successfully in a previous attempt. This method can come in handy as a fallback when encrypting a message fails due to devices we cannot build a session with.

Parameters:

exception - CannotEstablishSessionException from a previous encrypt(user(s), message) call.

message - message we want to send.

Returns:

encrypted message

Throws:

CryptoFailedException

UndecidedOmemoIdentityException - when there are undecided identities.

decrypt

public ClearTextMessage decrypt(BareJid sender,
                                Message omemoMessage)
                         throws java.lang.InterruptedException,
                                SmackException.NoResponseException,
                                SmackException.NotConnectedException,
                                CryptoFailedException,
                                XMPPException.XMPPErrorException,
                                CorruptedOmemoKeyException,
                                NoRawSessionException

Decrypt an OMEMO message. This method comes handy when dealing with messages that were not automatically decrypted by smack-omemo, eg. MAM query messages.

Parameters:

sender - sender of the message

omemoMessage - message

Returns:

decrypted message

Throws:

java.lang.InterruptedException - Exception

SmackException.NoResponseException - Exception

SmackException.NotConnectedException - Exception

CryptoFailedException - When decryption fails

XMPPException.XMPPErrorException - Exception

CorruptedOmemoKeyException - When the used keys are invalid

NoRawSessionException - When there is no double ratchet session found for this message

decryptMamQueryResult

public java.util.List<ClearTextMessage> decryptMamQueryResult(MamManager.MamQueryResult mamQueryResult)
                                                       throws java.lang.InterruptedException,
                                                              XMPPException.XMPPErrorException,
                                                              SmackException.NotConnectedException,
                                                              SmackException.NoResponseException

Return a list of all OMEMO messages that were found in the MAM query result, that could be successfully decrypted. Normal cleartext messages are also added to this list.

Parameters:

mamQueryResult - mamQueryResult

Returns:

list of decrypted OmemoMessages

Throws:

java.lang.InterruptedException - Exception

XMPPException.XMPPErrorException - Exception

SmackException.NotConnectedException - Exception

SmackException.NoResponseException - Exception

trustOmemoIdentity

public void trustOmemoIdentity(OmemoDevice device,
                               OmemoFingerprint fingerprint)

Trust that a fingerprint belongs to an OmemoDevice. The fingerprint must be the lowercase, hexadecimal fingerprint of the identityKey of the device and must be of length 64.

Parameters:

device - device

fingerprint - fingerprint

distrustOmemoIdentity

public void distrustOmemoIdentity(OmemoDevice device,
                                  OmemoFingerprint fingerprint)

Distrust the fingerprint/OmemoDevice tuple. The fingerprint must be the lowercase, hexadecimal fingerprint of the identityKey of the device and must be of length 64.

Parameters:

device - device

fingerprint - fingerprint

isTrustedOmemoIdentity

public boolean isTrustedOmemoIdentity(OmemoDevice device,
                                      OmemoFingerprint fingerprint)

Returns true, if the fingerprint/OmemoDevice tuple is trusted, otherwise false. The fingerprint must be the lowercase, hexadecimal fingerprint of the identityKey of the device and must be of length 64.

Parameters:

device - device

fingerprint - fingerprint

Returns:

isDecidedOmemoIdentity

public boolean isDecidedOmemoIdentity(OmemoDevice device,
                                      OmemoFingerprint fingerprint)

Returns true, if the fingerprint/OmemoDevice tuple is decided by the user. The fingerprint must be the lowercase, hexadecimal fingerprint of the identityKey of the device and must be of length 64.

Parameters:

device - device

fingerprint - fingerprint

Returns:

purgeDevices

public void purgeDevices()
                  throws SmackException,
                         java.lang.InterruptedException,
                         XMPPException.XMPPErrorException,
                         CorruptedOmemoKeyException

Clear all other devices except this one from our device list and republish the list.

Throws:

java.lang.InterruptedException

SmackException

XMPPException.XMPPErrorException

CorruptedOmemoKeyException

regenerate

public void regenerate()
                throws SmackException,
                       java.lang.InterruptedException,
                       XMPPException.XMPPErrorException,
                       CorruptedOmemoKeyException

Generate fresh identity keys and bundle and publish it to the server.

Throws:

SmackException

java.lang.InterruptedException

XMPPException.XMPPErrorException

CorruptedOmemoKeyException

sendRatchetUpdateMessage

public void sendRatchetUpdateMessage(OmemoDevice recipient)
                              throws CorruptedOmemoKeyException,
                                     UndecidedOmemoIdentityException,
                                     CryptoFailedException,
                                     CannotEstablishOmemoSessionException

Send a ratchet update message. This can be used to advance the ratchet of a session in order to maintain forward secrecy.

Parameters:

recipient - recipient

Throws:

UndecidedOmemoIdentityException - When the trust of session with the recipient is not decided yet

CorruptedOmemoKeyException - When the used identityKeys are corrupted

CryptoFailedException - When something fails with the crypto

CannotEstablishOmemoSessionException - When we can't establish a session with the recipient

createKeyTransportElement

public OmemoVAxolotlElement createKeyTransportElement(byte[] aesKey,
                                                      byte[] iv,
                                                      OmemoDevice... to)
                                               throws UndecidedOmemoIdentityException,
                                                      CorruptedOmemoKeyException,
                                                      CryptoFailedException,
                                                      CannotEstablishOmemoSessionException

Create a new KeyTransportElement. This message will contain the AES-Key and IV that can be used eg. for encrypted Jingle file transfer.

Parameters:

aesKey - AES key to transport

iv - Initialization vector

to - list of recipient devices

Returns:

KeyTransportMessage

Throws:

UndecidedOmemoIdentityException - When the trust of session with the recipient is not decided yet

CorruptedOmemoKeyException - When the used identityKeys are corrupted

CryptoFailedException - When something fails with the crypto

CannotEstablishOmemoSessionException - When we can't establish a session with the recipient

contactSupportsOmemo

public boolean contactSupportsOmemo(BareJid contact)
                             throws SmackException.NotConnectedException,
                                    java.lang.InterruptedException,
                                    SmackException.NoResponseException

Returns true, if the contact has any active devices published in a deviceList.

Parameters:

contact - contact

Returns:

true if contact has at least one OMEMO capable device.

Throws:

SmackException.NotConnectedException

java.lang.InterruptedException

SmackException.NoResponseException

multiUserChatSupportsOmemo

public boolean multiUserChatSupportsOmemo(EntityBareJid multiUserChat)
                                   throws XMPPException.XMPPErrorException,
                                          SmackException.NotConnectedException,
                                          java.lang.InterruptedException,
                                          SmackException.NoResponseException

Returns true, if the MUC with the EntityBareJid multiUserChat is non-anonymous and members only (prerequisite for OMEMO encryption in MUC).

Parameters:

multiUserChat - EntityBareJid of the MUC

Returns:

true if chat supports OMEMO

Throws:

XMPPException.XMPPErrorException - if

SmackException.NotConnectedException - something

java.lang.InterruptedException - goes

SmackException.NoResponseException - wrong

serverSupportsOmemo

public static boolean serverSupportsOmemo(XMPPConnection connection,
                                          DomainBareJid server)
                                   throws XMPPException.XMPPErrorException,
                                          SmackException.NotConnectedException,
                                          java.lang.InterruptedException,
                                          SmackException.NoResponseException

Returns true, if the Server supports PEP.

Parameters:

connection - XMPPConnection

server - domainBareJid of the server to test

Returns:

true if server supports pep

Throws:

XMPPException.XMPPErrorException

SmackException.NotConnectedException

java.lang.InterruptedException

SmackException.NoResponseException

getOurFingerprint

public OmemoFingerprint getOurFingerprint()

Return the fingerprint of our identity key.

Returns:

fingerprint

getFingerprint

public OmemoFingerprint getFingerprint(OmemoDevice device)
                                throws CannotEstablishOmemoSessionException

Throws:

CannotEstablishOmemoSessionException

getActiveFingerprints

public java.util.HashMap<OmemoDevice,OmemoFingerprint> getActiveFingerprints(BareJid contact)

Return all fingerprints of active devices of a contact.

Parameters:

contact - contact

Returns:

HashMap of deviceIds and corresponding fingerprints.

addOmemoMessageListener

public void addOmemoMessageListener(OmemoMessageListener listener)

removeOmemoMessageListener

public void removeOmemoMessageListener(OmemoMessageListener listener)

addOmemoMucMessageListener

public void addOmemoMucMessageListener(OmemoMucMessageListener listener)

removeOmemoMucMessageListener

public void removeOmemoMucMessageListener(OmemoMucMessageListener listener)

buildSessionsWith

public void buildSessionsWith(BareJid contact)
                       throws java.lang.InterruptedException,
                              CannotEstablishOmemoSessionException,
                              SmackException.NotConnectedException,
                              SmackException.NoResponseException

Build OMEMO sessions with devices of contact.

Parameters:

contact - contact we want to build session with.

Throws:

java.lang.InterruptedException

CannotEstablishOmemoSessionException

SmackException.NotConnectedException

SmackException.NoResponseException

requestDeviceListUpdateFor

public void requestDeviceListUpdateFor(BareJid contact)
                                throws SmackException.NotConnectedException,
                                       java.lang.InterruptedException,
                                       SmackException.NoResponseException

Request a deviceList update from contact contact.

Parameters:

contact - contact we want to obtain the deviceList from.

Throws:

SmackException.NotConnectedException

java.lang.InterruptedException

SmackException.NoResponseException

rotateSignedPreKey

public void rotateSignedPreKey()
                        throws CorruptedOmemoKeyException,
                               java.lang.InterruptedException,
                               XMPPException.XMPPErrorException,
                               SmackException.NotConnectedException,
                               SmackException.NoResponseException,
                               PubSubException.NotALeafNodeException

Rotate the signedPreKey published in our OmemoBundle. This should be done every now and then (7-14 days). The old signedPreKey should be kept for some more time (a month or so) to enable decryption of messages that have been sent since the key was changed.

Throws:

CorruptedOmemoKeyException - When the IdentityKeyPair is damaged.

java.lang.InterruptedException - XMPP error

XMPPException.XMPPErrorException - XMPP error

SmackException.NotConnectedException - XMPP error

SmackException.NoResponseException - XMPP error

PubSubException.NotALeafNodeException - if the bundle node on the server is a CollectionNode

stanzaContainsOmemoElement

public static boolean stanzaContainsOmemoElement(Stanza stanza)

Return true, if the given Stanza contains an OMEMO element 'encrypted'.

Parameters:

stanza - stanza

Returns:

true if stanza has extension 'encrypted'

randomDeviceId

public static int randomDeviceId()

getOwnJid

public BareJid getOwnJid()

Return the BareJid of the user.

Returns:

bareJid

getDeviceId

public int getDeviceId()

Return the deviceId of this OmemoManager.

Returns:

deviceId

getOwnDevice

public OmemoDevice getOwnDevice()

Return the OmemoDevice of the user.

Returns:

omemoDevice

shutdown

public void shutdown()

Remove all active stanza listeners of this manager from the connection. This is somewhat the counterpart of initialize().