Package org.jivesoftware.smackx.ox

Class OpenPgpManager

java.lang.Object
org.jivesoftware.smack.Manager
org.jivesoftware.smackx.ox.OpenPgpManager
public final class OpenPgpManager extends org.jivesoftware.smack.Manager
Entry point for Smacks API for OpenPGP for XMPP.

Setup

In order to use OpenPGP for XMPP in Smack, just follow the following procedure.

First, acquire an instance of the OpenPgpManager for your XMPPConnection using getInstanceFor(XMPPConnection). 
 
 OpenPgpManager openPgpManager = OpenPgpManager.getInstanceFor(connection);
You also need an OpenPgpProvider, as well as an OpenPgpStore. The provider must be registered using setOpenPgpProvider(OpenPgpProvider). 
 
 OpenPgpStore store = new FileBasedOpenPgpStore(storePath);
 OpenPgpProvider provider = new PainlessOpenPgpProvider(connection, store);
 openPgpManager.setOpenPgpProvider(provider);
It is also advised to register a custom SecretKeyRingProtector using OpenPgpStore.setKeyRingProtector(SecretKeyRingProtector) in order to be able to handle password protected secret keys.

Speaking of keys, you can now check, if you have any keys available in your OpenPgpStore by doing hasSecretKeysAvailable().

If you do, you can now announce support for OX and publish those keys using announceSupportAndPublish().

Otherwise, you can either generate fresh keys using generateAndImportKeyPair(BareJid), or try to restore a secret key backup from your private PubSub node by doing restoreSecretKeyServerBackup(AskForBackupCodeCallback).

In any case you should still do an announceSupportAndPublish() afterwards.

Contacts are represented by OpenPgpContacts in the context of OpenPGP for XMPP. You can get those by using getOpenPgpContact(EntityBareJid). The main function of OpenPgpContacts is to bundle information about the OpenPGP capabilities of a contact in one spot. The pendant to the OpenPgpContact is the OpenPgpSelf, which encapsulates your own OpenPGP identity. Both classes can be used to acquire information about the OpenPGP keys of a user.

Elements

OpenPGP for XMPP defines multiple different element classes which contain the users messages. The outermost element is the OpenPgpElement, which contains an OpenPGP encrypted content element. The content can be either a SignElement, CryptElement or SigncryptElement, depending on the use-case. Those content elements contain the actual payload. If an OpenPgpElement is decrypted, it will be returned in form of an OpenPgpMessage, which represents the decrypted message + metadata.
See Also:

  • Method Details

    • getInstanceFor

      public static OpenPgpManager getInstanceFor(org.jivesoftware.smack.XMPPConnection connection)
      Get the instance of the OpenPgpManager which belongs to the connection.
      Parameters:
      connection - xmpp connection.
      Returns:
      instance of the manager.

    • getJidOrThrow

      public org.jxmpp.jid.BareJid getJidOrThrow() throws org.jivesoftware.smack.SmackException.NotLoggedInException
      Return our own BareJid.
      Returns:
      our bareJid
      Throws:
      org.jivesoftware.smack.SmackException.NotLoggedInException - in case our connection is not logged in, which means our BareJid is unknown.

    • setOpenPgpProvider

      public void setOpenPgpProvider(OpenPgpProvider provider)
      Set the OpenPgpProvider which will be used to process incoming OpenPGP elements, as well as to execute cryptographic operations.
      Parameters:
      provider - OpenPgpProvider.

    • getOpenPgpProvider

      public OpenPgpProvider getOpenPgpProvider()

    • getOpenPgpSelf

      public OpenPgpSelf getOpenPgpSelf() throws org.jivesoftware.smack.SmackException.NotLoggedInException
      Get our OpenPGP self.
      Returns:
      self TODO javadoc me please
      Throws:
      org.jivesoftware.smack.SmackException.NotLoggedInException - if we are not logged in

    • announceSupportAndPublish

      public void announceSupportAndPublish() throws NoSuchAlgorithmException, NoSuchProviderException, InterruptedException, org.jivesoftware.smackx.pubsub.PubSubException.NotALeafNodeException, org.jivesoftware.smack.XMPPException.XMPPErrorException, org.jivesoftware.smack.SmackException.NotConnectedException, org.jivesoftware.smack.SmackException.NoResponseException, IOException, InvalidAlgorithmParameterException, org.jivesoftware.smack.SmackException.NotLoggedInException, org.bouncycastle.openpgp.PGPException
      Generate a fresh OpenPGP key pair, given we don't have one already. Publish the public key to the Public Key Node and update the Public Key Metadata Node with our keys fingerprint. Lastly register a PepListener which listens for updates to Public Key Metadata Nodes.
      Throws:
      NoSuchAlgorithmException - if we are missing an algorithm to generate a fresh key pair.
      NoSuchProviderException - if we are missing a suitable Provider.
      InterruptedException - if the thread gets interrupted.
      org.jivesoftware.smackx.pubsub.PubSubException.NotALeafNodeException - if one of the PubSub nodes is not a LeafNode.
      org.jivesoftware.smack.XMPPException.XMPPErrorException - in case of an XMPP protocol error.
      org.jivesoftware.smack.SmackException.NotConnectedException - if we are not connected.
      org.jivesoftware.smack.SmackException.NoResponseException - if the server doesn't respond.
      IOException - IO is dangerous.
      InvalidAlgorithmParameterException - if illegal algorithm parameters are used for key generation.
      org.jivesoftware.smack.SmackException.NotLoggedInException - if we are not logged in.
      org.bouncycastle.openpgp.PGPException - if something goes wrong during key loading/generating

    • generateAndImportKeyPair

      public org.pgpainless.key.OpenPgpV4Fingerprint generateAndImportKeyPair(org.jxmpp.jid.BareJid ourJid) throws NoSuchAlgorithmException, InvalidAlgorithmParameterException, NoSuchProviderException, org.bouncycastle.openpgp.PGPException, IOException
      Generate a fresh OpenPGP key pair and import it.
      Parameters:
      ourJid - our BareJid.
      Returns:
      OpenPgpV4Fingerprint of the generated key.
      Throws:
      NoSuchAlgorithmException - if the JVM doesn't support one of the used algorithms.
      InvalidAlgorithmParameterException - if the used algorithm parameters are invalid.
      NoSuchProviderException - if we are missing a cryptographic provider.
      org.bouncycastle.openpgp.PGPException - PGP is brittle.
      IOException - IO is dangerous.

    • generateKeyRing

      public org.bouncycastle.openpgp.PGPSecretKeyRing generateKeyRing(org.jxmpp.jid.BareJid ourJid) throws org.bouncycastle.openpgp.PGPException, NoSuchAlgorithmException, NoSuchProviderException, InvalidAlgorithmParameterException
      Throws:
      org.bouncycastle.openpgp.PGPException
      NoSuchAlgorithmException
      NoSuchProviderException
      InvalidAlgorithmParameterException

    • getOurFingerprint

      public org.pgpainless.key.OpenPgpV4Fingerprint getOurFingerprint() throws org.jivesoftware.smack.SmackException.NotLoggedInException, IOException, org.bouncycastle.openpgp.PGPException
      Return the upper-case hex encoded OpenPGP v4 fingerprint of our key pair.
      Returns:
      fingerprint.
      Throws:
      org.jivesoftware.smack.SmackException.NotLoggedInException - in case we are not logged in.
      IOException - IO is dangerous.
      org.bouncycastle.openpgp.PGPException - PGP is brittle.

    • getOpenPgpContact

      public OpenPgpContact getOpenPgpContact(org.jxmpp.jid.EntityBareJid jid)
      Return an OpenPGP capable contact. This object can be used as an entry point to OpenPGP related API.
      Parameters:
      jid - BareJid of the contact.
      Returns:
      OpenPgpContact.

    • hasSecretKeysAvailable

      public boolean hasSecretKeysAvailable() throws org.jivesoftware.smack.SmackException.NotLoggedInException, org.bouncycastle.openpgp.PGPException, IOException
      Return true, if we have a secret key available, otherwise false.
      Returns:
      true if secret key available
      Throws:
      org.jivesoftware.smack.SmackException.NotLoggedInException - If we are not logged in (we need to know our jid in order to look up our keys in the key store.
      org.bouncycastle.openpgp.PGPException - in case the keys in the store are damaged somehow.
      IOException - IO is dangerous.

    • serverSupportsSecretKeyBackups

      public static boolean serverSupportsSecretKeyBackups(org.jivesoftware.smack.XMPPConnection connection) throws org.jivesoftware.smack.XMPPException.XMPPErrorException, org.jivesoftware.smack.SmackException.NotConnectedException, InterruptedException, org.jivesoftware.smack.SmackException.NoResponseException
      Determine, if we can sync secret keys using private PEP nodes as described in the XEP. Requirements on the server side are support for PEP and support for the whitelist access model of PubSub.
      Parameters:
      connection - XMPP connection
      Returns:
      true, if the server supports secret key backups, 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.
      See Also:

    • stopMetadataListener

      public void stopMetadataListener()
      Remove the metadata listener. This method is mainly used in tests.

    • backupSecretKeyToServer

      public OpenPgpSecretKeyBackupPassphrase backupSecretKeyToServer(SecretKeyBackupSelectionCallback selectKeyCallback) throws InterruptedException, org.jivesoftware.smackx.pubsub.PubSubException.NotALeafNodeException, org.jivesoftware.smack.XMPPException.XMPPErrorException, org.jivesoftware.smack.SmackException.NotConnectedException, org.jivesoftware.smack.SmackException.NoResponseException, org.jivesoftware.smack.SmackException.NotLoggedInException, IOException, org.jivesoftware.smack.SmackException.FeatureNotSupportedException, org.bouncycastle.openpgp.PGPException, MissingOpenPgpKeyException
      Upload the encrypted secret key to a private PEP node.
      Parameters:
      selectKeyCallback - callback, which will receive the users choice of which keys will be backed up.
      Returns:
      secret key passphrase used to encrypt the backup.
      Throws:
      InterruptedException - if the thread is interrupted.
      org.jivesoftware.smackx.pubsub.PubSubException.NotALeafNodeException - if the private node is not a LeafNode.
      org.jivesoftware.smack.XMPPException.XMPPErrorException - in case of an XMPP protocol error.
      org.jivesoftware.smack.SmackException.NotConnectedException - if we are not connected.
      org.jivesoftware.smack.SmackException.NoResponseException - if the server doesn't respond.
      org.jivesoftware.smack.SmackException.NotLoggedInException - if we are not logged in.
      IOException - IO is dangerous.
      org.jivesoftware.smack.SmackException.FeatureNotSupportedException - if the server doesn't support the PubSub whitelist access model.
      org.bouncycastle.openpgp.PGPException - PGP is brittle
      MissingOpenPgpKeyException - in case we have no OpenPGP key pair to back up.
      See Also:

    • backupSecretKeyToServer

      public void backupSecretKeyToServer(SecretKeyBackupSelectionCallback selectKeyCallback, OpenPgpSecretKeyBackupPassphrase passphrase) throws InterruptedException, org.jivesoftware.smackx.pubsub.PubSubException.NotALeafNodeException, org.jivesoftware.smack.XMPPException.XMPPErrorException, org.jivesoftware.smack.SmackException.NotConnectedException, org.jivesoftware.smack.SmackException.NoResponseException, org.jivesoftware.smack.SmackException.NotLoggedInException, IOException, org.jivesoftware.smack.SmackException.FeatureNotSupportedException, org.bouncycastle.openpgp.PGPException, MissingOpenPgpKeyException
      Upload the encrypted secret key to a private PEP node. The backup is encrypted using the provided secret key passphrase.
      Parameters:
      selectKeyCallback - callback, which will receive the users choice of which keys will be backed up.
      passphrase - secret key passphrase
      Throws:
      InterruptedException - if the thread is interrupted.
      org.jivesoftware.smackx.pubsub.PubSubException.NotALeafNodeException - if the private node is not a LeafNode.
      org.jivesoftware.smack.XMPPException.XMPPErrorException - in case of an XMPP protocol error.
      org.jivesoftware.smack.SmackException.NotConnectedException - if we are not connected.
      org.jivesoftware.smack.SmackException.NoResponseException - if the server doesn't respond.
      org.jivesoftware.smack.SmackException.NotLoggedInException - if we are not logged in.
      IOException - IO is dangerous.
      org.jivesoftware.smack.SmackException.FeatureNotSupportedException - if the server doesn't support the PubSub whitelist access model.
      org.bouncycastle.openpgp.PGPException - PGP is brittle
      MissingOpenPgpKeyException - in case we have no OpenPGP key pair to back up.
      See Also:

    • deleteSecretKeyServerBackup

      public void deleteSecretKeyServerBackup() throws org.jivesoftware.smack.XMPPException.XMPPErrorException, org.jivesoftware.smack.SmackException.NotConnectedException, InterruptedException, org.jivesoftware.smack.SmackException.NoResponseException, org.jivesoftware.smack.SmackException.NotLoggedInException
      Delete the private LeafNode containing our secret key backup.
      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.
      org.jivesoftware.smack.SmackException.NotLoggedInException - if we are not logged in.

    • restoreSecretKeyServerBackup

      public org.pgpainless.key.OpenPgpV4Fingerprint restoreSecretKeyServerBackup(AskForBackupCodeCallback codeCallback) throws InterruptedException, org.jivesoftware.smackx.pubsub.PubSubException.NotALeafNodeException, org.jivesoftware.smack.XMPPException.XMPPErrorException, org.jivesoftware.smack.SmackException.NotConnectedException, org.jivesoftware.smack.SmackException.NoResponseException, InvalidBackupCodeException, org.jivesoftware.smack.SmackException.NotLoggedInException, IOException, MissingUserIdOnKeyException, NoBackupFoundException, org.bouncycastle.openpgp.PGPException
      Fetch a secret key backup from the server and try to restore a selected secret key from it.
      Parameters:
      codeCallback - callback for prompting the user to provide the secret backup code.
      Returns:
      fingerprint of the restored secret key
      Throws:
      InterruptedException - if the thread gets interrupted.
      org.jivesoftware.smackx.pubsub.PubSubException.NotALeafNodeException - if the private node is not a LeafNode.
      org.jivesoftware.smack.XMPPException.XMPPErrorException - in case of an XMPP protocol error.
      org.jivesoftware.smack.SmackException.NotConnectedException - if we are not connected.
      org.jivesoftware.smack.SmackException.NoResponseException - if the server doesn't respond.
      InvalidBackupCodeException - if the user-provided backup code is invalid.
      org.jivesoftware.smack.SmackException.NotLoggedInException - if we are not logged in
      IOException - IO is dangerous
      MissingUserIdOnKeyException - if the key that is to be imported is missing a user-id with our jid
      NoBackupFoundException - if no secret key backup has been found
      org.bouncycastle.openpgp.PGPException - in case the restored secret key is damaged.

    • decryptOpenPgpElement

      public OpenPgpMessage decryptOpenPgpElement(OpenPgpElement element, OpenPgpContact sender) throws org.jivesoftware.smack.SmackException.NotLoggedInException, IOException, org.bouncycastle.openpgp.PGPException
      Decrypt and or verify an OpenPgpElement and return the decrypted OpenPgpMessage.
      Parameters:
      element - OpenPgpElement containing the message.
      sender - OpenPgpContact who sent the message.
      Returns:
      decrypted and/or verified message
      Throws:
      org.jivesoftware.smack.SmackException.NotLoggedInException - in case we aren't logged in (we need to know our jid)
      IOException - IO error (reading keys, streams etc)
      org.bouncycastle.openpgp.PGPException - in case of an PGP error

    • registerSigncryptReceivedListener

      public void registerSigncryptReceivedListener(SigncryptElementReceivedListener listener)
      Register a SigncryptElementReceivedListener on the OpenPgpManager. That listener will get informed whenever a SigncryptElement has been received and successfully decrypted. Note: This method is not intended for clients to listen for incoming SigncryptElements. Instead its purpose is to allow easy extension of XEP-0373 for custom OpenPGP profiles such as OpenPGP for XMPP: Instant Messaging.
      Parameters:
      listener - listener that gets registered