Package org.jivesoftware.smackx.omemo
Class OmemoManager
java.lang.Object
org.jivesoftware.smack.Manager
org.jivesoftware.smackx.omemo.OmemoManager
Manager that allows sending messages encrypted with OMEMO.
This class also provides some methods useful for a client that implements OMEMO.
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic interface
Callback which can be used to get notified, when the OmemoManager finished initializing.static class
Guard class which ensures that the wrapped OmemoManager knows its BareJid. -
Method Summary
Modifier and TypeMethodDescriptionvoid
addOmemoMessageListener
(OmemoMessageListener listener) Add an OmemoMessageListener.void
Add an OmemoMucMessageListener.boolean
contactSupportsOmemo
(BareJid contact) Returns true, if the contact has any active devices published in a deviceList.decrypt
(BareJid sender, OmemoElement omemoElement) Manually decrypt an OmemoElement.decryptMamQueryResult
(MamManager.MamQuery mamQuery) Decrypt messages from a MAM query.void
distrustOmemoIdentity
(OmemoDevice device, OmemoFingerprint fingerprint) Distrust the fingerprint/OmemoDevice tuple.OMEMO encrypt a cleartext message for multiple recipients.encrypt
(MultiUserChat muc, String message) Encrypt a message for all recipients in the MultiUserChat.OMEMO encrypt a cleartext message for a single recipient.getActiveFingerprints
(BareJid contact) Return all OmemoFingerprints of active devices of a contact.Return the deviceId of this OmemoManager.getDevicesOf
(BareJid contact) Return a set of all OMEMO capable devices of a contact.getFingerprint
(OmemoDevice device) Get the fingerprint of a contacts device.static OmemoManager
getInstanceFor
(XMPPConnection connection) Returns an OmemoManager instance for the given connection.static OmemoManager
getInstanceFor
(XMPPConnection connection, Integer deviceId) Return an OmemoManager instance for the given connection and deviceId.Return the OmemoDevice of the user.Return the fingerprint of our identity key.Return the BareJid of the user.void
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
(MultiUserChat multiUserChat) Returns true, if the MUC with the EntityBareJid multiUserChat is non-anonymous and members only (prerequisite for OMEMO encryption in MUC).void
Publish a new device list with just our own deviceId in it.static int
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
Remove an OmemoMessageListener.void
Remove an OmemoMucMessageListener.void
requestDeviceListUpdateFor
(BareJid contact) Request a deviceList update from contact contact.void
Register stanza listeners needed for OMEMO.void
Rotate the signedPreKey published in our OmemoBundle and republish it.void
sendRatchetUpdateMessage
(OmemoDevice recipient) Send a ratchet update message.static boolean
serverSupportsOmemo
(XMPPConnection connection, DomainBareJid server) Returns true, if the Server supports PEP.void
setTrustCallback
(OmemoTrustCallback callback) Set a TrustCallback for this particular OmemoManager.void
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, schedule, scheduleBlocking
-
Method Details
-
getInstanceFor
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:
- OmemoManager instance for the given connection and deviceId.
-
getInstanceFor
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:
- OmemoManager instance for the given connection and a determined deviceId.
-
setTrustCallback
Set a TrustCallback for this particular OmemoManager. TrustCallbacks are used to query and modify trust decisions.- Parameters:
callback
- trustCallback.
-
initialize
public void initialize() throws SmackException.NotLoggedInException, CorruptedOmemoKeyException, InterruptedException, SmackException.NoResponseException, SmackException.NotConnectedException, XMPPException.XMPPErrorException, PubSubException.NotALeafNodeException, IOExceptionInitializes the OmemoManager. This method must be called before the manager can be used.- Throws:
CorruptedOmemoKeyException
- if the OMEMO key is corrupted.InterruptedException
- if the calling thread was interrupted.SmackException.NoResponseException
- if there was no response from the remote entity.SmackException.NotConnectedException
- if the XMPP connection is not connected.XMPPException.XMPPErrorException
- if there was an XMPP error returned.SmackException.NotLoggedInException
- if the XMPP connection is not authenticated.PubSubException.NotALeafNodeException
- if a PubSub leaf node operation was attempted on a non-leaf node.IOException
- if an I/O error occurred.
-
initializeAsync
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
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.
- Throws:
IOException
- if an I/O error occurred.- See Also:
-
encrypt
public OmemoMessage.Sent encrypt(BareJid recipient, String message) throws CryptoFailedException, UndecidedOmemoIdentityException, InterruptedException, SmackException.NotConnectedException, SmackException.NoResponseException, SmackException.NotLoggedInException, IOException 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 bareJidmessage
- text to encrypt- Returns:
- encrypted message
- Throws:
CryptoFailedException
- when something crypto related failsUndecidedOmemoIdentityException
- When there are undecided devicesInterruptedException
- if the calling thread was interrupted.SmackException.NotConnectedException
- if the XMPP connection is not connected.SmackException.NoResponseException
- if there was no response from the remote entity.SmackException.NotLoggedInException
- if the XMPP connection is not authenticated.IOException
- if an I/O error occurred.
-
encrypt
public OmemoMessage.Sent encrypt(Set<BareJid> recipients, String message) throws CryptoFailedException, UndecidedOmemoIdentityException, InterruptedException, SmackException.NotConnectedException, SmackException.NoResponseException, SmackException.NotLoggedInException, IOException OMEMO encrypt a cleartext message for multiple recipients.- Parameters:
recipients
- recipients barejidsmessage
- text to encrypt- Returns:
- encrypted message.
- Throws:
CryptoFailedException
- When something crypto related failsUndecidedOmemoIdentityException
- When there are undecided devices.InterruptedException
- if the calling thread was interrupted.SmackException.NotConnectedException
- if the XMPP connection is not connected.SmackException.NoResponseException
- if there was no response from the remote entity.SmackException.NotLoggedInException
- if the XMPP connection is not authenticated.IOException
- if an I/O error occurred.
-
encrypt
public OmemoMessage.Sent encrypt(MultiUserChat muc, String message) throws UndecidedOmemoIdentityException, CryptoFailedException, XMPPException.XMPPErrorException, SmackException.NotConnectedException, InterruptedException, SmackException.NoResponseException, NoOmemoSupportException, SmackException.NotLoggedInException, IOException Encrypt a message for all recipients in the MultiUserChat.- Parameters:
muc
- multiUserChatmessage
- message to send- Returns:
- encrypted message
- Throws:
UndecidedOmemoIdentityException
- when there are undecided devices.CryptoFailedException
- if the OMEMO cryptography failed.XMPPException.XMPPErrorException
- if there was an XMPP error returned.SmackException.NotConnectedException
- if the XMPP connection is not connected.InterruptedException
- if the calling thread was interrupted.SmackException.NoResponseException
- if there was no response from the remote entity.NoOmemoSupportException
- When the muc doesn't support OMEMO.SmackException.NotLoggedInException
- if the XMPP connection is not authenticated.IOException
- if an I/O error occurred.
-
decrypt
public OmemoMessage.Received decrypt(BareJid sender, OmemoElement omemoElement) throws SmackException.NotLoggedInException, CorruptedOmemoKeyException, NoRawSessionException, CryptoFailedException, IOException 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 authenticatedCorruptedOmemoKeyException
- if our or their key is corruptedNoRawSessionException
- if the message was not a preKeyMessage, but we had no session with the contactCryptoFailedException
- if decryption failsIOException
- if an I/O error occurred.
-
decryptMamQueryResult
public List<MessageOrOmemoMessage> decryptMamQueryResult(MamManager.MamQuery mamQuery) throws SmackException.NotLoggedInException, IOException 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.IOException
- if an I/O error occurred.
-
trustOmemoIdentity
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
- devicefingerprint
- fingerprint
-
distrustOmemoIdentity
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
- devicefingerprint
- fingerprint
-
isTrustedOmemoIdentity
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
- devicefingerprint
- fingerprint- Returns:
true
if this is a trusted OMEMO identity.
-
isDecidedOmemoIdentity
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
- devicefingerprint
- fingerprint- Returns:
true
if the trust is decided for the identity.
-
sendRatchetUpdateMessage
public void sendRatchetUpdateMessage(OmemoDevice recipient) throws SmackException.NotLoggedInException, CorruptedOmemoKeyException, InterruptedException, SmackException.NoResponseException, NoSuchAlgorithmException, SmackException.NotConnectedException, CryptoFailedException, CannotEstablishOmemoSessionException, IOException 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 corruptedCryptoFailedException
- When something fails with the cryptoCannotEstablishOmemoSessionException
- When we can't establish a session with the recipientSmackException.NotLoggedInException
- if the XMPP connection is not authenticated.InterruptedException
- if the calling thread was interrupted.SmackException.NoResponseException
- if there was no response from the remote entity.NoSuchAlgorithmException
- if no such algorithm is available.SmackException.NotConnectedException
- if the XMPP connection is not connected.IOException
- if an I/O error occurred.
-
contactSupportsOmemo
public boolean contactSupportsOmemo(BareJid contact) throws InterruptedException, PubSubException.NotALeafNodeException, XMPPException.XMPPErrorException, SmackException.NotConnectedException, SmackException.NoResponseException, IOException 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
- if the XMPP connection is not connected.InterruptedException
- if the calling thread was interrupted.SmackException.NoResponseException
- if there was no response from the remote entity.PubSubException.NotALeafNodeException
- if a PubSub leaf node operation was attempted on a non-leaf node.XMPPException.XMPPErrorException
- if there was an XMPP error returned.IOException
- if an I/O error occurred.
-
multiUserChatSupportsOmemo
public boolean multiUserChatSupportsOmemo(MultiUserChat multiUserChat) throws XMPPException.XMPPErrorException, SmackException.NotConnectedException, 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
- MUC- Returns:
- true if chat supports OMEMO
- Throws:
XMPPException.XMPPErrorException
- if there was an XMPP protocol level errorSmackException.NotConnectedException
- if the connection is not connectedInterruptedException
- if the thread is interruptedSmackException.NoResponseException
- if the server does not respond
-
serverSupportsOmemo
public static boolean serverSupportsOmemo(XMPPConnection connection, DomainBareJid server) throws XMPPException.XMPPErrorException, SmackException.NotConnectedException, InterruptedException, SmackException.NoResponseException Returns true, if the Server supports PEP.- Parameters:
connection
- XMPPConnectionserver
- domainBareJid of the server to test- Returns:
- true if server supports pep
- Throws:
XMPPException.XMPPErrorException
- if there was an XMPP error returned.SmackException.NotConnectedException
- if the XMPP connection is not connected.InterruptedException
- if the calling thread was interrupted.SmackException.NoResponseException
- if there was no response from the remote entity.
-
getOwnFingerprint
public OmemoFingerprint getOwnFingerprint() throws SmackException.NotLoggedInException, CorruptedOmemoKeyException, IOExceptionReturn the fingerprint of our identity key.- Returns:
- our own OMEMO fingerprint
- Throws:
SmackException.NotLoggedInException
- if we don't know our bareJid yet.CorruptedOmemoKeyException
- if our identityKey is corrupted.IOException
- if an I/O error occurred.
-
getFingerprint
public OmemoFingerprint getFingerprint(OmemoDevice device) throws CannotEstablishOmemoSessionException, SmackException.NotLoggedInException, CorruptedOmemoKeyException, SmackException.NotConnectedException, InterruptedException, SmackException.NoResponseException, IOException Get the fingerprint of a contacts device.- Parameters:
device
- contacts OmemoDevice- Returns:
- fingerprint of the given OMEMO device.
- Throws:
CannotEstablishOmemoSessionException
- if we have no session yet, and are unable to create one.SmackException.NotLoggedInException
- if the XMPP connection is not authenticated.CorruptedOmemoKeyException
- if the copy of the fingerprint we have is corrupted.SmackException.NotConnectedException
- if the XMPP connection is not connected.InterruptedException
- if the calling thread was interrupted.SmackException.NoResponseException
- if there was no response from the remote entity.IOException
- if an I/O error occurred.
-
getActiveFingerprints
public Map<OmemoDevice,OmemoFingerprint> getActiveFingerprints(BareJid contact) throws SmackException.NotLoggedInException, CorruptedOmemoKeyException, CannotEstablishOmemoSessionException, SmackException.NotConnectedException, InterruptedException, SmackException.NoResponseException, IOException 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
- if the XMPP connection is not authenticated.CorruptedOmemoKeyException
- if the OMEMO key is corrupted.CannotEstablishOmemoSessionException
- if no OMEMO session could be established.SmackException.NotConnectedException
- if the XMPP connection is not connected.InterruptedException
- if the calling thread was interrupted.SmackException.NoResponseException
- if there was no response from the remote entity.IOException
- if an I/O error occurred.
-
addOmemoMessageListener
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
Remove an OmemoMessageListener.- Parameters:
listener
- OmemoMessageListener
-
addOmemoMucMessageListener
Add an OmemoMucMessageListener. This listener will be informed about incoming OMEMO encrypted MUC messages.- Parameters:
listener
- OmemoMessageListener.
-
removeOmemoMucMessageListener
Remove an OmemoMucMessageListener.- Parameters:
listener
- OmemoMucMessageListener
-
requestDeviceListUpdateFor
public void requestDeviceListUpdateFor(BareJid contact) throws InterruptedException, PubSubException.NotALeafNodeException, XMPPException.XMPPErrorException, SmackException.NotConnectedException, SmackException.NoResponseException, IOException Request a deviceList update from contact contact.- Parameters:
contact
- contact we want to obtain the deviceList from.- Throws:
InterruptedException
- if the calling thread was interrupted.PubSubException.NotALeafNodeException
- if a PubSub leaf node operation was attempted on a non-leaf node.XMPPException.XMPPErrorException
- if there was an XMPP error returned.SmackException.NotConnectedException
- if the XMPP connection is not connected.SmackException.NoResponseException
- if there was no response from the remote entity.IOException
- if an I/O error occurred.
-
purgeDeviceList
public void purgeDeviceList() throws SmackException.NotLoggedInException, InterruptedException, XMPPException.XMPPErrorException, SmackException.NotConnectedException, SmackException.NoResponseException, IOException, PubSubException.NotALeafNodeExceptionPublish a new device list with just our own deviceId in it.- Throws:
SmackException.NotLoggedInException
- if the XMPP connection is not authenticated.InterruptedException
- if the calling thread was interrupted.XMPPException.XMPPErrorException
- if there was an XMPP error returned.SmackException.NotConnectedException
- if the XMPP connection is not connected.SmackException.NoResponseException
- if there was no response from the remote entity.IOException
- if an I/O error occurred.PubSubException.NotALeafNodeException
- if a PubSub leaf node operation was attempted on a non-leaf node.
-
purgeEverything
public List<Exception> purgeEverything() throws SmackException.NotConnectedException, InterruptedException, IOException -
rotateSignedPreKey
public void rotateSignedPreKey() throws CorruptedOmemoKeyException, SmackException.NotLoggedInException, XMPPException.XMPPErrorException, SmackException.NotConnectedException, InterruptedException, SmackException.NoResponseException, IOException, PubSubException.NotALeafNodeExceptionRotate 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.InterruptedException
- XMPP errorXMPPException.XMPPErrorException
- XMPP errorSmackException.NotConnectedException
- XMPP errorSmackException.NoResponseException
- XMPP errorSmackException.NotLoggedInException
- if the XMPP connection is not authenticated.IOException
- if an I/O error occurred.PubSubException.NotALeafNodeException
- if a PubSub leaf node operation was attempted on a non-leaf node.
-
randomDeviceId
Returns a pseudo random number from the interval [1, Integer.MAX_VALUE].- Returns:
- a random deviceId.
-
getOwnJid
Return the BareJid of the user.- Returns:
- our own bare JID.
-
getDeviceId
Return the deviceId of this OmemoManager.- Returns:
- this OmemoManagers deviceId.
-
getOwnDevice
Return the OmemoDevice of the user.- Returns:
- our own OmemoDevice
-
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 afterstopStanzaAndPEPListeners()
was called. -
stopStanzaAndPEPListeners
Remove active stanza listeners needed for OMEMO. -
rebuildSessionWith
public void rebuildSessionWith(OmemoDevice contactsDevice) throws InterruptedException, SmackException.NoResponseException, CorruptedOmemoKeyException, SmackException.NotConnectedException, CannotEstablishOmemoSessionException, 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:
InterruptedException
- if the calling thread was interrupted.SmackException.NoResponseException
- if there was no response from the remote entity.CorruptedOmemoKeyException
- if our or their identityKey is corrupted.SmackException.NotConnectedException
- if the XMPP connection is not connected.CannotEstablishOmemoSessionException
- if no new session can be established.SmackException.NotLoggedInException
- if the connection is not authenticated.
-