org.jivesoftware.smackx.ox_im

Class OXInstantMessagingManager

java.lang.Object

org.jivesoftware.smack.Manager

org.jivesoftware.smackx.ox_im.OXInstantMessagingManager

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

Entry point of Smacks API for XEP-0374: OpenPGP for XMPP: Instant Messaging.

Setup

In order to set up OX Instant Messaging, please first follow the setup routines of the OpenPgpManager, 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.

See Also:

XEP-0374: OpenPGP for XMPP: Instant Messaging

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	NAMESPACE_0

Method Summary

Modifier and Type	Method and Description
org.pgpainless.decryption_verification.OpenPgpMetadata	addOxMessage(org.jivesoftware.smack.packet.MessageBuilder messageBuilder, OpenPgpContact contact, java.util.List<org.jivesoftware.smack.packet.ExtensionElement> payload) Add an OX-IM message element to a message.
org.pgpainless.decryption_verification.OpenPgpMetadata	addOxMessage(org.jivesoftware.smack.packet.MessageBuilder messageBuilder, java.util.Set<OpenPgpContact> recipients, java.util.List<org.jivesoftware.smack.packet.ExtensionElement> payload) Add an OX-IM message element to a message.
boolean	addOxMessageListener(OxMessageListener listener) Add an OxMessageListener.
void	announceSupportForOxInstantMessaging() Add the OX:IM namespace as a feature to our disco features.
boolean	contactSupportsOxInstantMessaging(org.jxmpp.jid.BareJid jid) Determine, whether a contact announces support for XEP-0374: OpenPGP for XMPP: Instant Messaging.
boolean	contactSupportsOxInstantMessaging(OpenPgpContact contact) Determine, whether a contact announces support for XEP-0374: OpenPGP for XMPP: Instant Messaging.
OpenPgpMessage	decryptAndVerify(OpenPgpElement element, OpenPgpContact sender) Manually decrypt and verify an OpenPgpElement.
static OXInstantMessagingManager	getInstanceFor(org.jivesoftware.smack.XMPPConnection connection) Return an instance of the OXInstantMessagingManager that belongs to the given connection.
boolean	removeOxMessageListener(OxMessageListener listener) Remove an OxMessageListener.
org.pgpainless.decryption_verification.OpenPgpMetadata	sendOxMessage(OpenPgpContact contact, java.lang.CharSequence body) Send an OX message to a OpenPgpContact.
OpenPgpElementAndMetadata	signAndEncrypt(java.util.Set<OpenPgpContact> contacts, java.util.List<org.jivesoftware.smack.packet.ExtensionElement> payload) Wrap some payload into a SigncryptElement, sign and encrypt it for contacts and ourselves.

Methods inherited from class org.jivesoftware.smack.Manager

connection, getAuthenticatedConnectionOrThrow, schedule, schedule, scheduleBlocking

Methods inherited from class java.lang.Object

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

Field Detail

NAMESPACE_0

public static final java.lang.String NAMESPACE_0

See Also:

Constant Field Values

Method Detail

getInstanceFor

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

Return an instance of the OXInstantMessagingManager that belongs to the given connection.

Parameters:

connection - XMPP connection

Returns:

manager instance

announceSupportForOxInstantMessaging

public void announceSupportForOxInstantMessaging()

Add the OX:IM namespace as a feature to our disco features.

contactSupportsOxInstantMessaging

public boolean contactSupportsOxInstantMessaging(org.jxmpp.jid.BareJid jid)
                                          throws org.jivesoftware.smack.XMPPException.XMPPErrorException,
                                                 org.jivesoftware.smack.SmackException.NotConnectedException,
                                                 java.lang.InterruptedException,
                                                 org.jivesoftware.smack.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 error

SmackException.NotConnectedException - if we are not connected

java.lang.InterruptedException - if the thread gets interrupted

SmackException.NoResponseException - if the server doesn't respond

contactSupportsOxInstantMessaging

public boolean contactSupportsOxInstantMessaging(OpenPgpContact contact)
                                          throws org.jivesoftware.smack.XMPPException.XMPPErrorException,
                                                 org.jivesoftware.smack.SmackException.NotConnectedException,
                                                 java.lang.InterruptedException,
                                                 org.jivesoftware.smack.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 error

SmackException.NotConnectedException - if we are not connected

java.lang.InterruptedException - if the thread is interrupted

SmackException.NoResponseException - if the server doesn't respond

addOxMessageListener

public boolean addOxMessageListener(OxMessageListener listener)

Add an OxMessageListener. The listener gets notified about incoming OpenPgpMessages which contained an OX-IM message.

Parameters:

listener - listener

Returns:

true if the listener gets added, otherwise false.

removeOxMessageListener

public boolean removeOxMessageListener(OxMessageListener listener)

Remove an OxMessageListener. 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.decryption_verification.OpenPgpMetadata sendOxMessage(OpenPgpContact contact,
                                                                            java.lang.CharSequence body)
                                                                     throws java.lang.InterruptedException,
                                                                            java.io.IOException,
                                                                            org.jivesoftware.smack.SmackException.NotConnectedException,
                                                                            org.jivesoftware.smack.SmackException.NotLoggedInException,
                                                                            org.bouncycastle.openpgp.PGPException

Send an OX message to a OpenPgpContact. 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:

OpenPgpMetadata about the messages encryption + signatures.

Throws:

java.lang.InterruptedException - if the thread is interrupted

java.io.IOException - IO is dangerous

SmackException.NotConnectedException - if we are not connected

SmackException.NotLoggedInException - if we are not logged in

org.bouncycastle.openpgp.PGPException - PGP is brittle

addOxMessage

public org.pgpainless.decryption_verification.OpenPgpMetadata addOxMessage(org.jivesoftware.smack.packet.MessageBuilder messageBuilder,
                                                                           OpenPgpContact contact,
                                                                           java.util.List<org.jivesoftware.smack.packet.ExtensionElement> payload)
                                                                    throws org.jivesoftware.smack.SmackException.NotLoggedInException,
                                                                           org.bouncycastle.openpgp.PGPException,
                                                                           java.io.IOException

Add an OX-IM message element to a message.

Parameters:

messageBuilder - a message builder.

contact - recipient of the message

payload - payload which will be encrypted and signed

Returns:

OpenPgpMetadata about the messages encryption + metadata.

Throws:

SmackException.NotLoggedInException - in case we are not logged in

org.bouncycastle.openpgp.PGPException - in case something goes wrong during encryption

java.io.IOException - IO is dangerous (we need to read keys)

addOxMessage

public org.pgpainless.decryption_verification.OpenPgpMetadata addOxMessage(org.jivesoftware.smack.packet.MessageBuilder messageBuilder,
                                                                           java.util.Set<OpenPgpContact> recipients,
                                                                           java.util.List<org.jivesoftware.smack.packet.ExtensionElement> payload)
                                                                    throws org.jivesoftware.smack.SmackException.NotLoggedInException,
                                                                           java.io.IOException,
                                                                           org.bouncycastle.openpgp.PGPException

Add an OX-IM message element to a message.

Parameters:

messageBuilder - message

recipients - recipients of the message

payload - payload which will be encrypted and signed

Returns:

metadata about the messages encryption + signatures.

Throws:

SmackException.NotLoggedInException - in case we are not logged in

org.bouncycastle.openpgp.PGPException - in case something goes wrong during encryption

java.io.IOException - IO is dangerous (we need to read keys)

signAndEncrypt

public OpenPgpElementAndMetadata signAndEncrypt(java.util.Set<OpenPgpContact> contacts,
                                                java.util.List<org.jivesoftware.smack.packet.ExtensionElement> payload)
                                         throws org.jivesoftware.smack.SmackException.NotLoggedInException,
                                                java.io.IOException,
                                                org.bouncycastle.openpgp.PGPException

Wrap some payload into a SigncryptElement, sign and encrypt it for contacts and ourselves.

Parameters:

contacts - recipients of the message

payload - payload which will be encrypted and signed

Returns:

encrypted and signed OpenPgpElement, along with OpenPgpMetadata about the encryption + signatures.

Throws:

SmackException.NotLoggedInException - in case we are not logged in

java.io.IOException - 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 org.jivesoftware.smack.SmackException.NotLoggedInException,
                                       org.bouncycastle.openpgp.PGPException,
                                       java.io.IOException,
                                       org.jivesoftware.smack.xml.XmlPullParserException

Manually decrypt and verify an OpenPgpElement.

Parameters:

element - encrypted, signed OpenPgpElement.

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 error

java.io.IOException - in case of an IO error (reading keys, streams etc)

org.jivesoftware.smack.xml.XmlPullParserException - in case that the content of the OpenPgpElement is not a valid OpenPgpContentElement or broken XML.

java.lang.IllegalArgumentException - if the elements content is not a SigncryptElement. This happens, if the element likely is not an OX message.