org.jivesoftware.smackx.omemo

Class OmemoManager

java.lang.Object

org.jivesoftware.smack.Manager

org.jivesoftware.smackx.omemo.OmemoManager

public final class OmemoManager
extends org.jivesoftware.smack.Manager

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

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	OmemoManager.InitializationFinishedCallback Callback which can be used to get notified, when the OmemoManager finished initializing.
static class	OmemoManager.LoggedInOmemoManager Guard class which ensures that the wrapped OmemoManager knows its BareJid.

Method Summary

Modifier and Type	Method and Description
void	addOmemoMessageListener(OmemoMessageListener listener) Add an OmemoMessageListener.
void	addOmemoMucMessageListener(OmemoMucMessageListener listener) Add an OmemoMucMessageListener.
boolean	contactSupportsOmemo(org.jxmpp.jid.BareJid contact) Returns true, if the contact has any active devices published in a deviceList.
OmemoMessage.Received	decrypt(org.jxmpp.jid.BareJid sender, OmemoElement omemoElement) Manually decrypt an OmemoElement.
java.util.List<MessageOrOmemoMessage>	decryptMamQueryResult(org.jivesoftware.smackx.mam.MamManager.MamQuery mamQuery) Decrypt messages from a MAM query.
void	distrustOmemoIdentity(OmemoDevice device, OmemoFingerprint fingerprint) Distrust the fingerprint/OmemoDevice tuple.
OmemoMessage.Sent	encrypt(org.jxmpp.jid.BareJid recipient, java.lang.String message) OMEMO encrypt a cleartext message for a single recipient.
OmemoMessage.Sent	encrypt(org.jivesoftware.smackx.muc.MultiUserChat muc, java.lang.String message) Encrypt a message for all recipients in the MultiUserChat.
OmemoMessage.Sent	encrypt(java.util.Set<org.jxmpp.jid.BareJid> recipients, java.lang.String message) OMEMO encrypt a cleartext message for multiple recipients.
java.util.HashMap<OmemoDevice,OmemoFingerprint>	getActiveFingerprints(org.jxmpp.jid.BareJid contact) Return all OmemoFingerprints of active devices of a contact.
java.lang.Integer	getDeviceId() Return the deviceId of this OmemoManager.
java.util.Set<OmemoDevice>	getDevicesOf(org.jxmpp.jid.BareJid contact) Return a set of all OMEMO capable devices of a contact.
OmemoFingerprint	getFingerprint(OmemoDevice device) Get the fingerprint of a contacts device.
static OmemoManager	getInstanceFor(org.jivesoftware.smack.XMPPConnection connection) Returns an OmemoManager instance for the given connection.
static OmemoManager	getInstanceFor(org.jivesoftware.smack.XMPPConnection connection, java.lang.Integer deviceId) Return an OmemoManager instance for the given connection and deviceId.
OmemoDevice	getOwnDevice() Return the OmemoDevice of the user.
OmemoFingerprint	getOwnFingerprint() Return the fingerprint of our identity key.
org.jxmpp.jid.BareJid	getOwnJid() Return the BareJid of the user.
void	initialize() Initializes the OmemoManager.
void	initializeAsync(OmemoManager.InitializationFinishedCallback finishedCallback) Initialize the manager without blocking.
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(org.jivesoftware.smackx.muc.MultiUserChat multiUserChat) Returns true, if the MUC with the EntityBareJid multiUserChat is non-anonymous and members only (prerequisite for OMEMO encryption in MUC).
void	purgeDeviceList() Publish a new device list with just our own deviceId in it.
static int	randomDeviceId() Returns a pseudo random number from the interval [1, Integer.MAX_VALUE].
void	rebuildSessionWith(OmemoDevice contactsDevice) Build a fresh session with a contacts device.
void	removeOmemoMessageListener(OmemoMessageListener listener) Remove an OmemoMessageListener.
void	removeOmemoMucMessageListener(OmemoMucMessageListener listener) Remove an OmemoMucMessageListener.
void	requestDeviceListUpdateFor(org.jxmpp.jid.BareJid contact) Request a deviceList update from contact contact.
void	resumeStanzaAndPEPListeners() Register stanza listeners needed for OMEMO.
void	rotateSignedPreKey() Rotate the signedPreKey published in our OmemoBundle and republish it.
void	sendRatchetUpdateMessage(OmemoDevice recipient) Send a ratchet update message.
static boolean	serverSupportsOmemo(org.jivesoftware.smack.XMPPConnection connection, org.jxmpp.jid.DomainBareJid server) Returns true, if the Server supports PEP.
void	setTrustCallback(OmemoTrustCallback callback) Set a TrustCallback for this particular OmemoManager.
void	stopStanzaAndPEPListeners() Remove active stanza listeners needed for OMEMO.
void	trustOmemoIdentity(OmemoDevice device, OmemoFingerprint fingerprint) Trust that a fingerprint belongs to an OmemoDevice.

Methods inherited from class org.jivesoftware.smack.Manager

connection, getAuthenticatedConnectionOrThrow, schedule

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(org.jivesoftware.smack.XMPPConnection connection,
                                          java.lang.Integer deviceId)

Return an OmemoManager instance for the given connection and deviceId. If there was an OmemoManager for the connection and id before, return it. Otherwise create a new OmemoManager instance and return it.

Parameters:

connection - XmppConnection.

deviceId - MUST NOT be null and MUST be greater than 0.

Returns:

manager

getInstanceFor

public static OmemoManager getInstanceFor(org.jivesoftware.smack.XMPPConnection connection)

Returns an OmemoManager instance for the given connection. If there was one manager for the connection before, return it. If there were multiple managers before, return the one with the lowest deviceId. If there was no manager before, return a new one. As soon as the connection gets authenticated, the manager will look for local deviceIDs and select the lowest one as its id. If there are not local deviceIds, the manager will assign itself a random id.

Parameters:

connection - XmppConnection.

Returns:

manager

setTrustCallback

public void setTrustCallback(OmemoTrustCallback callback)

Set a TrustCallback for this particular OmemoManager. TrustCallbacks are used to query and modify trust decisions.

Parameters:

callback - trustCallback.

initialize

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

Initializes the OmemoManager. This method must be called before the manager can be used.

Throws:

CorruptedOmemoKeyException

java.lang.InterruptedException

SmackException.NoResponseException

SmackException.NotConnectedException

XMPPException.XMPPErrorException

SmackException.NotLoggedInException

PubSubException.NotALeafNodeException

initializeAsync

public void initializeAsync(OmemoManager.InitializationFinishedCallback finishedCallback)

Initialize the manager without blocking. Once the manager is successfully initialized, the finishedCallback will be notified. It will also get notified, if an error occurs.

Parameters:

finishedCallback - callback that gets called once the manager is initialized.

getDevicesOf

public java.util.Set<OmemoDevice> getDevicesOf(org.jxmpp.jid.BareJid contact)

Return a set of all OMEMO capable devices of a contact. Note, that this method does not explicitly refresh the device list of the contact, so it might be outdated.

Parameters:

contact - contact we want to get a set of device of.

Returns:

set of known devices of that contact.

See Also:

requestDeviceListUpdateFor(BareJid)

encrypt

public OmemoMessage.Sent encrypt(org.jxmpp.jid.BareJid recipient,
                                 java.lang.String message)
                          throws CryptoFailedException,
                                 UndecidedOmemoIdentityException,
                                 java.lang.InterruptedException,
                                 org.jivesoftware.smack.SmackException.NotConnectedException,
                                 org.jivesoftware.smack.SmackException.NoResponseException,
                                 org.jivesoftware.smack.SmackException.NotLoggedInException

OMEMO encrypt a cleartext message for a single recipient. Note that this method does NOT set the 'to' attribute of the message.

Parameters:

recipient - recipients bareJid

message - text to encrypt

Returns:

encrypted message

Throws:

CryptoFailedException - when something crypto related fails

UndecidedOmemoIdentityException - When there are undecided devices

java.lang.InterruptedException

SmackException.NotConnectedException

SmackException.NoResponseException

SmackException.NotLoggedInException

encrypt

public OmemoMessage.Sent encrypt(java.util.Set<org.jxmpp.jid.BareJid> recipients,
                                 java.lang.String message)
                          throws CryptoFailedException,
                                 UndecidedOmemoIdentityException,
                                 java.lang.InterruptedException,
                                 org.jivesoftware.smack.SmackException.NotConnectedException,
                                 org.jivesoftware.smack.SmackException.NoResponseException,
                                 org.jivesoftware.smack.SmackException.NotLoggedInException

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.lang.InterruptedException

SmackException.NotConnectedException

SmackException.NoResponseException

SmackException.NotLoggedInException

encrypt

public OmemoMessage.Sent encrypt(org.jivesoftware.smackx.muc.MultiUserChat muc,
                                 java.lang.String message)
                          throws UndecidedOmemoIdentityException,
                                 CryptoFailedException,
                                 org.jivesoftware.smack.XMPPException.XMPPErrorException,
                                 org.jivesoftware.smack.SmackException.NotConnectedException,
                                 java.lang.InterruptedException,
                                 org.jivesoftware.smack.SmackException.NoResponseException,
                                 NoOmemoSupportException,
                                 org.jivesoftware.smack.SmackException.NotLoggedInException

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.

CryptoFailedException

XMPPException.XMPPErrorException

SmackException.NotConnectedException

java.lang.InterruptedException

SmackException.NoResponseException

NoOmemoSupportException - When the muc doesn't support OMEMO.

SmackException.NotLoggedInException

decrypt

public OmemoMessage.Received decrypt(org.jxmpp.jid.BareJid sender,
                                     OmemoElement omemoElement)
                              throws org.jivesoftware.smack.SmackException.NotLoggedInException,
                                     CorruptedOmemoKeyException,
                                     NoRawSessionException,
                                     CryptoFailedException

Manually decrypt an OmemoElement. This method should only be used for use-cases, where the internal listeners don't pick up on an incoming message. (for example MAM query results).

Parameters:

sender - bareJid of the message sender (must be the jid of the contact who sent the message)

omemoElement - omemoElement

Returns:

decrypted OmemoMessage

Throws:

SmackException.NotLoggedInException - if the Manager is not authenticated

CorruptedOmemoKeyException - if our or their key is corrupted

NoRawSessionException - if the message was not a preKeyMessage, but we had no session with the contact

CryptoFailedException - if decryption fails

decryptMamQueryResult

public java.util.List<MessageOrOmemoMessage> decryptMamQueryResult(org.jivesoftware.smackx.mam.MamManager.MamQuery mamQuery)
                                                            throws org.jivesoftware.smack.SmackException.NotLoggedInException

Decrypt messages from a MAM query.

Parameters:

mamQuery - The MAM query

Returns:

list of decrypted OmemoMessages

Throws:

SmackException.NotLoggedInException - if the Manager is not authenticated.

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:

sendRatchetUpdateMessage

public void sendRatchetUpdateMessage(OmemoDevice recipient)
                              throws org.jivesoftware.smack.SmackException.NotLoggedInException,
                                     CorruptedOmemoKeyException,
                                     java.lang.InterruptedException,
                                     org.jivesoftware.smack.SmackException.NoResponseException,
                                     java.security.NoSuchAlgorithmException,
                                     org.jivesoftware.smack.SmackException.NotConnectedException,
                                     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:

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

SmackException.NotLoggedInException

java.lang.InterruptedException

SmackException.NoResponseException

java.security.NoSuchAlgorithmException

SmackException.NotConnectedException

contactSupportsOmemo

public boolean contactSupportsOmemo(org.jxmpp.jid.BareJid contact)
                             throws java.lang.InterruptedException,
                                    org.jivesoftware.smackx.pubsub.PubSubException.NotALeafNodeException,
                                    org.jivesoftware.smack.XMPPException.XMPPErrorException,
                                    org.jivesoftware.smack.SmackException.NotConnectedException,
                                    org.jivesoftware.smack.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

PubSubException.NotALeafNodeException

XMPPException.XMPPErrorException

multiUserChatSupportsOmemo

public boolean multiUserChatSupportsOmemo(org.jivesoftware.smackx.muc.MultiUserChat multiUserChat)
                                   throws org.jivesoftware.smack.XMPPException.XMPPErrorException,
                                          org.jivesoftware.smack.SmackException.NotConnectedException,
                                          java.lang.InterruptedException,
                                          org.jivesoftware.smack.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 - 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(org.jivesoftware.smack.XMPPConnection connection,
                                          org.jxmpp.jid.DomainBareJid server)
                                   throws org.jivesoftware.smack.XMPPException.XMPPErrorException,
                                          org.jivesoftware.smack.SmackException.NotConnectedException,
                                          java.lang.InterruptedException,
                                          org.jivesoftware.smack.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

getOwnFingerprint

public OmemoFingerprint getOwnFingerprint()
                                   throws org.jivesoftware.smack.SmackException.NotLoggedInException,
                                          CorruptedOmemoKeyException

Return the fingerprint of our identity key.

Returns:

fingerprint

Throws:

SmackException.NotLoggedInException - if we don't know our bareJid yet.

CorruptedOmemoKeyException - if our identityKey is corrupted.

getFingerprint

public OmemoFingerprint getFingerprint(OmemoDevice device)
                                throws CannotEstablishOmemoSessionException,
                                       org.jivesoftware.smack.SmackException.NotLoggedInException,
                                       CorruptedOmemoKeyException,
                                       org.jivesoftware.smack.SmackException.NotConnectedException,
                                       java.lang.InterruptedException,
                                       org.jivesoftware.smack.SmackException.NoResponseException

Get the fingerprint of a contacts device.

Parameters:

device - contacts OmemoDevice

Returns:

fingerprint

Throws:

CannotEstablishOmemoSessionException - if we have no session yet, and are unable to create one.

SmackException.NotLoggedInException

CorruptedOmemoKeyException - if the copy of the fingerprint we have is corrupted.

SmackException.NotConnectedException

java.lang.InterruptedException

SmackException.NoResponseException

getActiveFingerprints

public java.util.HashMap<OmemoDevice,OmemoFingerprint> getActiveFingerprints(org.jxmpp.jid.BareJid contact)
                                                                      throws org.jivesoftware.smack.SmackException.NotLoggedInException,
                                                                             CorruptedOmemoKeyException,
                                                                             CannotEstablishOmemoSessionException,
                                                                             org.jivesoftware.smack.SmackException.NotConnectedException,
                                                                             java.lang.InterruptedException,
                                                                             org.jivesoftware.smack.SmackException.NoResponseException

Return all OmemoFingerprints of active devices of a contact. TODO: Make more fail-safe

Parameters:

contact - contact

Returns:

Map of all active devices of the contact and their fingerprints.

Throws:

SmackException.NotLoggedInException

CorruptedOmemoKeyException

CannotEstablishOmemoSessionException

SmackException.NotConnectedException

java.lang.InterruptedException

SmackException.NoResponseException

addOmemoMessageListener

public void addOmemoMessageListener(OmemoMessageListener listener)

Add an OmemoMessageListener. This listener will be informed about incoming OMEMO messages (as well as KeyTransportMessages) and OMEMO encrypted message carbons.

Parameters:

listener - OmemoMessageListener

removeOmemoMessageListener

public void removeOmemoMessageListener(OmemoMessageListener listener)

Remove an OmemoMessageListener.

Parameters:

listener - OmemoMessageListener

addOmemoMucMessageListener

public void addOmemoMucMessageListener(OmemoMucMessageListener listener)

Add an OmemoMucMessageListener. This listener will be informed about incoming OMEMO encrypted MUC messages.

Parameters:

listener - OmemoMessageListener.

removeOmemoMucMessageListener

public void removeOmemoMucMessageListener(OmemoMucMessageListener listener)

Remove an OmemoMucMessageListener.

Parameters:

listener - OmemoMucMessageListener

requestDeviceListUpdateFor

public void requestDeviceListUpdateFor(org.jxmpp.jid.BareJid contact)
                                throws java.lang.InterruptedException,
                                       org.jivesoftware.smackx.pubsub.PubSubException.NotALeafNodeException,
                                       org.jivesoftware.smack.XMPPException.XMPPErrorException,
                                       org.jivesoftware.smack.SmackException.NotConnectedException,
                                       org.jivesoftware.smack.SmackException.NoResponseException

Request a deviceList update from contact contact.

Parameters:

contact - contact we want to obtain the deviceList from.

Throws:

java.lang.InterruptedException

PubSubException.NotALeafNodeException

XMPPException.XMPPErrorException

SmackException.NotConnectedException

SmackException.NoResponseException

purgeDeviceList

public void purgeDeviceList()
                     throws org.jivesoftware.smack.SmackException.NotLoggedInException,
                            java.lang.InterruptedException,
                            org.jivesoftware.smack.XMPPException.XMPPErrorException,
                            org.jivesoftware.smack.SmackException.NotConnectedException,
                            org.jivesoftware.smack.SmackException.NoResponseException

Publish a new device list with just our own deviceId in it.

Throws:

SmackException.NotLoggedInException

java.lang.InterruptedException

XMPPException.XMPPErrorException

SmackException.NotConnectedException

SmackException.NoResponseException

rotateSignedPreKey

public void rotateSignedPreKey()
                        throws CorruptedOmemoKeyException,
                               org.jivesoftware.smack.SmackException.NotLoggedInException,
                               org.jivesoftware.smack.XMPPException.XMPPErrorException,
                               org.jivesoftware.smack.SmackException.NotConnectedException,
                               java.lang.InterruptedException,
                               org.jivesoftware.smack.SmackException.NoResponseException

Rotate the signedPreKey published in our OmemoBundle and republish it. 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

SmackException.NotLoggedInException

randomDeviceId

public static int randomDeviceId()

Returns a pseudo random number from the interval [1, Integer.MAX_VALUE].

Returns:

deviceId

getOwnJid

public org.jxmpp.jid.BareJid getOwnJid()

Return the BareJid of the user.

Returns:

bareJid

getDeviceId

public java.lang.Integer getDeviceId()

Return the deviceId of this OmemoManager.

Returns:

deviceId

getOwnDevice

public OmemoDevice getOwnDevice()

Return the OmemoDevice of the user.

Returns:

omemoDevice

resumeStanzaAndPEPListeners

public void resumeStanzaAndPEPListeners()

Register stanza listeners needed for OMEMO. This method is called automatically in the constructor and should only be used to restore the previous state after stopStanzaAndPEPListeners() was called.

stopStanzaAndPEPListeners

public void stopStanzaAndPEPListeners()

Remove active stanza listeners needed for OMEMO.

rebuildSessionWith

public void rebuildSessionWith(OmemoDevice contactsDevice)
                        throws java.lang.InterruptedException,
                               org.jivesoftware.smack.SmackException.NoResponseException,
                               CorruptedOmemoKeyException,
                               org.jivesoftware.smack.SmackException.NotConnectedException,
                               CannotEstablishOmemoSessionException,
                               org.jivesoftware.smack.SmackException.NotLoggedInException

Build a fresh session with a contacts device. This might come in handy if a session is broken.

Parameters:

contactsDevice - OmemoDevice of a contact.

Throws:

java.lang.InterruptedException

SmackException.NoResponseException

CorruptedOmemoKeyException - if our or their identityKey is corrupted.

SmackException.NotConnectedException

CannotEstablishOmemoSessionException - if no new session can be established.

SmackException.NotLoggedInException - if the connection is not authenticated.