Package 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:

  • Field Details

  • Method Details

    • 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, 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:
      org.jivesoftware.smack.XMPPException.XMPPErrorException - in case of an XMPP protocol error
      org.jivesoftware.smack.SmackException.NotConnectedException - if we are not connected
      InterruptedException - if the thread gets interrupted
      org.jivesoftware.smack.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, 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:
      org.jivesoftware.smack.XMPPException.XMPPErrorException - in case of an XMPP protocol error
      org.jivesoftware.smack.SmackException.NotConnectedException - if we are not connected
      InterruptedException - if the thread is interrupted
      org.jivesoftware.smack.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.encryption_signing.EncryptionResult sendOxMessage(OpenPgpContact contact, CharSequence body) throws InterruptedException, 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:
      EncryptionResult containing metadata about the messages encryption + signatures.
      Throws:
      InterruptedException - if the thread is interrupted
      IOException - IO is dangerous
      org.jivesoftware.smack.SmackException.NotConnectedException - if we are not connected
      org.jivesoftware.smack.SmackException.NotLoggedInException - if we are not logged in
      org.bouncycastle.openpgp.PGPException - PGP is brittle

    • addOxMessage

      public org.pgpainless.encryption_signing.EncryptionResult addOxMessage(org.jivesoftware.smack.packet.MessageBuilder messageBuilder, OpenPgpContact contact, List<org.jivesoftware.smack.packet.ExtensionElement> payload) throws org.jivesoftware.smack.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 message
      payload - payload which will be encrypted and signed
      Returns:
      EncryptionResult containing metadata about the messages encryption + metadata.
      Throws:
      org.jivesoftware.smack.SmackException.NotLoggedInException - in case we are not logged in
      org.bouncycastle.openpgp.PGPException - in case something goes wrong during encryption
      IOException - IO is dangerous (we need to read keys)

    • addOxMessage

      public org.pgpainless.encryption_signing.EncryptionResult addOxMessage(org.jivesoftware.smack.packet.MessageBuilder messageBuilder, Set<OpenPgpContact> recipients, List<org.jivesoftware.smack.packet.ExtensionElement> payload) throws org.jivesoftware.smack.SmackException.NotLoggedInException, 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:
      EncryptionResult containing metadata about the messages encryption + signatures.
      Throws:
      org.jivesoftware.smack.SmackException.NotLoggedInException - in case we are not logged in
      org.bouncycastle.openpgp.PGPException - in case something goes wrong during encryption
      IOException - IO is dangerous (we need to read keys)

    • signAndEncrypt

      public OpenPgpElementAndMetadata signAndEncrypt(Set<OpenPgpContact> contacts, List<org.jivesoftware.smack.packet.ExtensionElement> payload) throws org.jivesoftware.smack.SmackException.NotLoggedInException, 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:
      org.jivesoftware.smack.SmackException.NotLoggedInException - in case we are not logged in
      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, 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:
      org.jivesoftware.smack.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
      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.
      IllegalArgumentException - if the elements content is not a SigncryptElement. This happens, if the element likely is not an OX message.