Package org.jivesoftware.smackx.ox_im
Class OXInstantMessagingManager
java.lang.Object
org.jivesoftware.smack.Manager
org.jivesoftware.smackx.ox_im.OXInstantMessagingManager
Entry point of Smacks API for XEP-0374: OpenPGP for XMPP: Instant Messaging.
Acquire an
Setup
In order to set up OX Instant Messaging, please first follow the setup routines of theOpenPgpManager
, then
do the following steps:
Acquire an OXInstantMessagingManager
instance.
OXInstantMessagingManager instantManager = OXInstantMessagingManager.getInstanceFor(connection);
Listen for OX messages
In order to listen for incoming OX:IM messages, you have to register a listener.
instantManager.addOxMessageListener(
new OxMessageListener() {
void newIncomingOxMessage(OpenPgpContact contact,
Message originalMessage,
SigncryptElement decryptedPayload) {
Message.Body body = decryptedPayload.<Message.Body>getExtension(Message.Body.ELEMENT, Message.Body.NAMESPACE);
...
}
});
Finally, announce support for OX:IM
In order to let your contacts know, that you support message encrypting using the OpenPGP for XMPP: Instant Messaging profile, you have to announce support for OX:IM.
instantManager.announceSupportForOxInstantMessaging();
Sending messages
In order to send an OX:IM message, just do
instantManager.sendOxMessage(openPgpManager.getOpenPgpContact(contactsJid), "Hello World");
Note, that you have to decide, whether to trust the contacts keys prior to sending a message, otherwise undecided
keys are not included in the encryption process. You can trust keys by calling
OpenPgpContact.trust(OpenPgpV4Fingerprint)
. Same goes for your own keys! In order to determine, whether
there are undecided keys, call OpenPgpContact.hasUndecidedKeys()
. The trust state of a single key can be
determined using OpenPgpContact.getTrust(OpenPgpV4Fingerprint)
.
Note: This implementation does not yet have support for sending/receiving messages to/from MUCs.-
Field Summary
-
Method Summary
Modifier and TypeMethodDescriptionorg.pgpainless.encryption_signing.EncryptionResult
addOxMessage
(MessageBuilder messageBuilder, Set<OpenPgpContact> recipients, List<ExtensionElement> payload) Add an OX-IM message element to a message.org.pgpainless.encryption_signing.EncryptionResult
addOxMessage
(MessageBuilder messageBuilder, OpenPgpContact contact, List<ExtensionElement> payload) Add an OX-IM message element to a message.boolean
addOxMessageListener
(OxMessageListener listener) Add anOxMessageListener
.void
Add the OX:IM namespace as a feature to our disco features.boolean
Determine, whether a contact announces support for XEP-0374: OpenPGP for XMPP: Instant Messaging.boolean
Determine, whether a contact announces support for XEP-0374: OpenPGP for XMPP: Instant Messaging.decryptAndVerify
(OpenPgpElement element, OpenPgpContact sender) Manually decrypt and verify anOpenPgpElement
.static OXInstantMessagingManager
getInstanceFor
(XMPPConnection connection) Return an instance of theOXInstantMessagingManager
that belongs to the givenconnection
.boolean
removeOxMessageListener
(OxMessageListener listener) Remove anOxMessageListener
.org.pgpainless.encryption_signing.EncryptionResult
sendOxMessage
(OpenPgpContact contact, CharSequence body) Send an OX message to aOpenPgpContact
.signAndEncrypt
(Set<OpenPgpContact> contacts, List<ExtensionElement> payload) Methods inherited from class org.jivesoftware.smack.Manager
connection, getAuthenticatedConnectionOrThrow, schedule, schedule, scheduleBlocking
-
Field Details
-
NAMESPACE_0
- See Also:
-
-
Method Details
-
getInstanceFor
Return an instance of theOXInstantMessagingManager
that belongs to the givenconnection
.- Parameters:
connection
- XMPP connection- Returns:
- manager instance
-
announceSupportForOxInstantMessaging
Add the OX:IM namespace as a feature to our disco features. -
contactSupportsOxInstantMessaging
public boolean contactSupportsOxInstantMessaging(BareJid jid) throws XMPPException.XMPPErrorException, SmackException.NotConnectedException, InterruptedException, SmackException.NoResponseException Determine, whether a contact announces support for XEP-0374: OpenPGP for XMPP: Instant Messaging.- Parameters:
jid
-BareJid
of the contact in question.- Returns:
- true if contact announces support, otherwise false.
- Throws:
XMPPException.XMPPErrorException
- in case of an XMPP protocol errorSmackException.NotConnectedException
- if we are not connectedInterruptedException
- if the thread gets interruptedSmackException.NoResponseException
- if the server doesn't respond
-
contactSupportsOxInstantMessaging
public boolean contactSupportsOxInstantMessaging(OpenPgpContact contact) throws XMPPException.XMPPErrorException, SmackException.NotConnectedException, InterruptedException, SmackException.NoResponseException Determine, whether a contact announces support for XEP-0374: OpenPGP for XMPP: Instant Messaging.- Parameters:
contact
-OpenPgpContact
in question.- Returns:
- true if contact announces support, otherwise false.
- Throws:
XMPPException.XMPPErrorException
- in case of an XMPP protocol errorSmackException.NotConnectedException
- if we are not connectedInterruptedException
- if the thread is interruptedSmackException.NoResponseException
- if the server doesn't respond
-
addOxMessageListener
Add anOxMessageListener
. The listener gets notified about incomingOpenPgpMessage
s which contained an OX-IM message.- Parameters:
listener
- listener- Returns:
- true if the listener gets added, otherwise false.
-
removeOxMessageListener
Remove anOxMessageListener
. The listener will no longer be notified about OX-IM messages.- Parameters:
listener
- listener- Returns:
- true, if the listener gets removed, otherwise false
-
sendOxMessage
public org.pgpainless.encryption_signing.EncryptionResult sendOxMessage(OpenPgpContact contact, CharSequence body) throws InterruptedException, IOException, SmackException.NotConnectedException, SmackException.NotLoggedInException, org.bouncycastle.openpgp.PGPException Send an OX message to aOpenPgpContact
. The message will be encrypted to all active keys of the contact, as well as all of our active keys. The message is also signed with our key.- Parameters:
contact
- contact capable of OpenPGP for XMPP: Instant Messaging.body
- message body.- Returns:
EncryptionResult
containing metadata about the messages encryption + signatures.- Throws:
InterruptedException
- if the thread is interruptedIOException
- IO is dangerousSmackException.NotConnectedException
- if we are not connectedSmackException.NotLoggedInException
- if we are not logged inorg.bouncycastle.openpgp.PGPException
- PGP is brittle
-
addOxMessage
public org.pgpainless.encryption_signing.EncryptionResult addOxMessage(MessageBuilder messageBuilder, OpenPgpContact contact, List<ExtensionElement> payload) throws SmackException.NotLoggedInException, org.bouncycastle.openpgp.PGPException, IOException Add an OX-IM message element to a message.- Parameters:
messageBuilder
- a message builder.contact
- recipient of the messagepayload
- payload which will be encrypted and signed- Returns:
EncryptionResult
containing metadata about the messages encryption + metadata.- Throws:
SmackException.NotLoggedInException
- in case we are not logged inorg.bouncycastle.openpgp.PGPException
- in case something goes wrong during encryptionIOException
- IO is dangerous (we need to read keys)
-
addOxMessage
public org.pgpainless.encryption_signing.EncryptionResult addOxMessage(MessageBuilder messageBuilder, Set<OpenPgpContact> recipients, List<ExtensionElement> payload) throws SmackException.NotLoggedInException, IOException, org.bouncycastle.openpgp.PGPException Add an OX-IM message element to a message.- Parameters:
messageBuilder
- messagerecipients
- recipients of the messagepayload
- payload which will be encrypted and signed- Returns:
EncryptionResult
containing metadata about the messages encryption + signatures.- Throws:
SmackException.NotLoggedInException
- in case we are not logged inorg.bouncycastle.openpgp.PGPException
- in case something goes wrong during encryptionIOException
- IO is dangerous (we need to read keys)
-
signAndEncrypt
public OpenPgpElementAndMetadata signAndEncrypt(Set<OpenPgpContact> contacts, List<ExtensionElement> payload) throws SmackException.NotLoggedInException, IOException, org.bouncycastle.openpgp.PGPException - Parameters:
contacts
- recipients of the messagepayload
- payload which will be encrypted and signed- Returns:
- encrypted and signed
OpenPgpElement
, along withOpenPgpMetadata
about the encryption + signatures. - Throws:
SmackException.NotLoggedInException
- in case we are not logged inIOException
- IO is dangerous (we need to read keys)org.bouncycastle.openpgp.PGPException
- in case encryption goes wrong
-
decryptAndVerify
public OpenPgpMessage decryptAndVerify(OpenPgpElement element, OpenPgpContact sender) throws SmackException.NotLoggedInException, org.bouncycastle.openpgp.PGPException, IOException, XmlPullParserException Manually decrypt and verify anOpenPgpElement
.- Parameters:
element
- encrypted, signedOpenPgpElement
.sender
- sender of the message.- Returns:
- decrypted, verified message
- Throws:
SmackException.NotLoggedInException
- In case we are not logged in (we need our jid to access our keys)org.bouncycastle.openpgp.PGPException
- in case of an PGP errorIOException
- in case of an IO error (reading keys, streams etc)XmlPullParserException
- in case that the content of theOpenPgpElement
is not a validOpenPgpContentElement
or broken XML.IllegalArgumentException
- if the elements content is not aSigncryptElement
. This happens, if the element likely is not an OX message.
-