Package org.jivesoftware.smackx.ox

Class OpenPgpManager

java.lang.Object

org.jivesoftware.smack.Manager

org.jivesoftware.smackx.ox.OpenPgpManager

public final class OpenPgpManager
extends 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:

XEP-0373: OpenPGP for XMPP

Method Summary

Modifier and Type	Method	Description
void	announceSupportAndPublish()	Generate a fresh OpenPGP key pair, given we don't have one already.
OpenPgpSecretKeyBackupPassphrase	backupSecretKeyToServer(SecretKeyBackupSelectionCallback selectKeyCallback)	Upload the encrypted secret key to a private PEP node.
void	backupSecretKeyToServer(SecretKeyBackupSelectionCallback selectKeyCallback, OpenPgpSecretKeyBackupPassphrase passphrase)	Upload the encrypted secret key to a private PEP node.
OpenPgpMessage	decryptOpenPgpElement(OpenPgpElement element, OpenPgpContact sender)	Decrypt and or verify an OpenPgpElement and return the decrypted OpenPgpMessage.
void	deleteSecretKeyServerBackup()	Delete the private LeafNode containing our secret key backup.
org.pgpainless.key.OpenPgpV4Fingerprint	generateAndImportKeyPair(BareJid ourJid)	Generate a fresh OpenPGP key pair and import it.
org.pgpainless.key.collection.PGPKeyRing	generateKeyRing(BareJid ourJid)
static OpenPgpManager	getInstanceFor(XMPPConnection connection)	Get the instance of the OpenPgpManager which belongs to the connection.
BareJid	getJidOrThrow()	Return our own BareJid.
OpenPgpContact	getOpenPgpContact(EntityBareJid jid)	Return an OpenPGP capable contact.
OpenPgpProvider	getOpenPgpProvider()
OpenPgpSelf	getOpenPgpSelf()	Get our OpenPGP self.
org.pgpainless.key.OpenPgpV4Fingerprint	getOurFingerprint()	Return the upper-case hex encoded OpenPGP v4 fingerprint of our key pair.
boolean	hasSecretKeysAvailable()	Return true, if we have a secret key available, otherwise false.
void	registerSigncryptReceivedListener(SigncryptElementReceivedListener listener)	Register a SigncryptElementReceivedListener on the OpenPgpManager.
org.pgpainless.key.OpenPgpV4Fingerprint	restoreSecretKeyServerBackup(AskForBackupCodeCallback codeCallback)	Fetch a secret key backup from the server and try to restore a selected secret key from it.
static boolean	serverSupportsSecretKeyBackups(XMPPConnection connection)	Determine, if we can sync secret keys using private PEP nodes as described in the XEP.
void	setOpenPgpProvider(OpenPgpProvider provider)	Set the OpenPgpProvider which will be used to process incoming OpenPGP elements, as well as to execute cryptographic operations.
void	stopMetadataListener()	Remove the metadata listener.

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

Method Detail

getInstanceFor

public static OpenPgpManager getInstanceFor(XMPPConnection connection)

Get the instance of the OpenPgpManager which belongs to the connection.

Parameters:

connection - xmpp connection.

Returns:

instance of the manager.

getJidOrThrow

public BareJid getJidOrThrow()
                      throws SmackException.NotLoggedInException

Return our own BareJid.

Returns:

our bareJid

Throws:

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 SmackException.NotLoggedInException

Get our OpenPGP self.

Returns:

self TODO javadoc me please

Throws:

SmackException.NotLoggedInException - if we are not logged in

announceSupportAndPublish

public void announceSupportAndPublish()
                               throws NoSuchAlgorithmException,
                                      NoSuchProviderException,
                                      InterruptedException,
                                      PubSubException.NotALeafNodeException,
                                      XMPPException.XMPPErrorException,
                                      SmackException.NotConnectedException,
                                      SmackException.NoResponseException,
                                      IOException,
                                      InvalidAlgorithmParameterException,
                                      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.

PubSubException.NotALeafNodeException - if one of the PubSub nodes is not a LeafNode.

XMPPException.XMPPErrorException - in case of an XMPP protocol error.

SmackException.NotConnectedException - if we are not connected.

SmackException.NoResponseException - if the server doesn't respond.

IOException - IO is dangerous.

InvalidAlgorithmParameterException - if illegal algorithm parameters are used for key generation.

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(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.pgpainless.key.collection.PGPKeyRing generateKeyRing(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 SmackException.NotLoggedInException,
                                                                 IOException,
                                                                 org.bouncycastle.openpgp.PGPException

Return the upper-case hex encoded OpenPGP v4 fingerprint of our key pair.

Returns:

fingerprint.

Throws:

SmackException.NotLoggedInException - in case we are not logged in.

IOException - IO is dangerous.

org.bouncycastle.openpgp.PGPException - PGP is brittle.

getOpenPgpContact

public OpenPgpContact getOpenPgpContact(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 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:

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(XMPPConnection connection)
                                              throws XMPPException.XMPPErrorException,
                                                     SmackException.NotConnectedException,
                                                     InterruptedException,
                                                     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:

XMPPException.XMPPErrorException - in case of an XMPP protocol error.

SmackException.NotConnectedException - if we are not connected.

InterruptedException - if the thread is interrupted.

SmackException.NoResponseException - if the server doesn't respond.

See Also:

XEP-0373 §5

stopMetadataListener

public void stopMetadataListener()

Remove the metadata listener. This method is mainly used in tests.

backupSecretKeyToServer

public OpenPgpSecretKeyBackupPassphrase backupSecretKeyToServer(SecretKeyBackupSelectionCallback selectKeyCallback)
                                                         throws InterruptedException,
                                                                PubSubException.NotALeafNodeException,
                                                                XMPPException.XMPPErrorException,
                                                                SmackException.NotConnectedException,
                                                                SmackException.NoResponseException,
                                                                SmackException.NotLoggedInException,
                                                                IOException,
                                                                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.

PubSubException.NotALeafNodeException - if the private node is not a LeafNode.

XMPPException.XMPPErrorException - in case of an XMPP protocol error.

SmackException.NotConnectedException - if we are not connected.

SmackException.NoResponseException - if the server doesn't respond.

SmackException.NotLoggedInException - if we are not logged in.

IOException - IO is dangerous.

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:

XEP-0373 §5

backupSecretKeyToServer

public void backupSecretKeyToServer(SecretKeyBackupSelectionCallback selectKeyCallback,
                                    OpenPgpSecretKeyBackupPassphrase passphrase)
                             throws InterruptedException,
                                    PubSubException.NotALeafNodeException,
                                    XMPPException.XMPPErrorException,
                                    SmackException.NotConnectedException,
                                    SmackException.NoResponseException,
                                    SmackException.NotLoggedInException,
                                    IOException,
                                    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. @param selectKeyCallback

passphrase - secret key passphrase

Throws:

InterruptedException - if the thread is interrupted.

PubSubException.NotALeafNodeException - if the private node is not a LeafNode.

XMPPException.XMPPErrorException - in case of an XMPP protocol error.

SmackException.NotConnectedException - if we are not connected.

SmackException.NoResponseException - if the server doesn't respond.

SmackException.NotLoggedInException - if we are not logged in.

IOException - IO is dangerous.

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:

XEP-0373 §5

deleteSecretKeyServerBackup

public void deleteSecretKeyServerBackup()
                                 throws XMPPException.XMPPErrorException,
                                        SmackException.NotConnectedException,
                                        InterruptedException,
                                        SmackException.NoResponseException,
                                        SmackException.NotLoggedInException

Delete the private LeafNode containing our secret key backup.

Throws:

XMPPException.XMPPErrorException - in case of an XMPP protocol error.

SmackException.NotConnectedException - if we are not connected.

InterruptedException - if the thread gets interrupted.

SmackException.NoResponseException - if the server doesn't respond.

SmackException.NotLoggedInException - if we are not logged in.

restoreSecretKeyServerBackup

public org.pgpainless.key.OpenPgpV4Fingerprint restoreSecretKeyServerBackup(AskForBackupCodeCallback codeCallback)
                                                                     throws InterruptedException,
                                                                            PubSubException.NotALeafNodeException,
                                                                            XMPPException.XMPPErrorException,
                                                                            SmackException.NotConnectedException,
                                                                            SmackException.NoResponseException,
                                                                            InvalidBackupCodeException,
                                                                            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.

PubSubException.NotALeafNodeException - if the private node is not a LeafNode.

XMPPException.XMPPErrorException - in case of an XMPP protocol error.

SmackException.NotConnectedException - if we are not connected.

SmackException.NoResponseException - if the server doesn't respond.

InvalidBackupCodeException - if the user-provided backup code is invalid.

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

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