Class 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
    • 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:
        org.jivesoftware.smack.XMPPException.XMPPErrorException - in case of an XMPP protocol error
        org.jivesoftware.smack.SmackException.NotConnectedException - if we are not connected
        java.lang.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,
                                                         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:
        org.jivesoftware.smack.XMPPException.XMPPErrorException - in case of an XMPP protocol error
        org.jivesoftware.smack.SmackException.NotConnectedException - if we are not connected
        java.lang.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.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
        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.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:
        org.jivesoftware.smack.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:
        org.jivesoftware.smack.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:
        org.jivesoftware.smack.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:
        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
        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.