diff --git a/smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/OXInstantMessagingManager.java b/smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/OXInstantMessagingManager.java index b7e3fb4f2..e3d082c96 100644 --- a/smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/OXInstantMessagingManager.java +++ b/smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/OXInstantMessagingManager.java @@ -62,6 +62,13 @@ public final class OXInstantMessagingManager extends Manager implements Signcryp announceSupportForOxInstantMessaging(); } + /** + * Return an instance of the {@link OXInstantMessagingManager} that belongs to the given {@code connection}. + * + * @param connection XMPP connection + * + * @return manager instance + */ public static OXInstantMessagingManager getInstanceFor(XMPPConnection connection) { OXInstantMessagingManager manager = INSTANCES.get(connection); @@ -73,6 +80,9 @@ public final class OXInstantMessagingManager extends Manager implements Signcryp return manager; } + /** + * Add the OX:IM namespace as a feature to our disco features. + */ public void announceSupportForOxInstantMessaging() { ServiceDiscoveryManager.getInstanceFor(connection()) .addFeature(NAMESPACE_0); @@ -83,10 +93,10 @@ public final class OXInstantMessagingManager extends Manager implements Signcryp * * @param jid {@link BareJid} of the contact in question. * @return true if contact announces support, otherwise false. - * @throws XMPPException.XMPPErrorException - * @throws SmackException.NotConnectedException - * @throws InterruptedException - * @throws SmackException.NoResponseException + * @throws XMPPException.XMPPErrorException in case of an XMPP protocol error + * @throws SmackException.NotConnectedException if we are not connected + * @throws InterruptedException if the connection gets interrupted + * @throws SmackException.NoResponseException if the server doesn't respond */ public boolean contactSupportsOxInstantMessaging(BareJid jid) throws XMPPException.XMPPErrorException, SmackException.NotConnectedException, InterruptedException, @@ -99,10 +109,10 @@ public final class OXInstantMessagingManager extends Manager implements Signcryp * * @param contact {@link OpenPgpContact} in question. * @return true if contact announces support, otherwise false. - * @throws XMPPException.XMPPErrorException - * @throws SmackException.NotConnectedException - * @throws InterruptedException - * @throws SmackException.NoResponseException + * @throws XMPPException.XMPPErrorException in case of an XMPP protocol error + * @throws SmackException.NotConnectedException if we are not connected + * @throws InterruptedException if the connection is interrupted + * @throws SmackException.NoResponseException if the server doesn't respond */ public boolean contactSupportsOxInstantMessaging(OpenPgpContact contact) throws XMPPException.XMPPErrorException, SmackException.NotConnectedException, InterruptedException, @@ -110,10 +120,21 @@ public final class OXInstantMessagingManager extends Manager implements Signcryp return contactSupportsOxInstantMessaging(contact.getJid()); } + /** + * Add an {@link OxMessageListener}. The listener gets notified about incoming {@link OpenPgpMessage}s which + * contained an OX-IM message. + * @param listener listener + * @return true if the listener gets added, otherwise false. + */ public boolean addOxMessageListener(OxMessageListener listener) { return oxMessageListeners.add(listener); } + /** + * Remove an {@link OxMessageListener}. The listener will no longer be notified about OX-IM messages. + * @param listener listener + * @return true, if the listener gets removed, otherwise false + */ public boolean removeOxMessageListener(OxMessageListener listener) { return oxMessageListeners.remove(listener); } @@ -125,6 +146,19 @@ public final class OXInstantMessagingManager extends Manager implements Signcryp } } + /** + * Send an OX message to a {@link 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. + * + * @param contact contact capable of OpenPGP for XMPP: Instant Messaging. + * @param body message body. + * @throws InterruptedException if the connection is interrupted + * @throws MissingOpenPgpKeyPairException if we cannot access our signing key + * @throws IOException IO is dangerous + * @throws SmackException.NotConnectedException if we are not connected + * @throws SmackOpenPgpException in case of an OpenPGP error + * @throws SmackException.NotLoggedInException if we are not logged in + */ public void sendOxMessage(OpenPgpContact contact, CharSequence body) throws InterruptedException, MissingOpenPgpKeyPairException, IOException, SmackException.NotConnectedException, SmackOpenPgpException, SmackException.NotLoggedInException { diff --git a/smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/OpenPgpContact.java b/smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/OpenPgpContact.java index 4ba9df4d4..70dde4bc7 100644 --- a/smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/OpenPgpContact.java +++ b/smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/OpenPgpContact.java @@ -140,10 +140,10 @@ public class OpenPgpContact { /** * Fetch the metadata node to get a {@link PublicKeysListElement} and update any missing or outdated keys. * - * @throws InterruptedException - * @throws XMPPException.XMPPErrorException - * @throws SmackException - * @throws SmackOpenPgpException + * @throws InterruptedException if the connection is interrupted + * @throws XMPPException.XMPPErrorException in case of an XMPP protocol error + * @throws SmackException in case of an error in Smack + * @throws SmackOpenPgpException in case of an OpenPGP exception */ public void updateKeys() throws InterruptedException, XMPPException.XMPPErrorException, SmackException, SmackOpenPgpException { @@ -182,12 +182,12 @@ public class OpenPgpContact { * Update the key identified by the {@code fingerprint}. * * @param fingerprint fingerprint of the key - * @throws InterruptedException - * @throws XMPPException.XMPPErrorException - * @throws SmackException - * @throws IOException - * @throws MissingUserIdOnKeyException - * @throws SmackOpenPgpException + * @throws InterruptedException if the connection is interrupted + * @throws XMPPException.XMPPErrorException in case of an XMPP protocol error + * @throws SmackException in case of an exception in Smack + * @throws IOException IO is dangerous + * @throws MissingUserIdOnKeyException if the key is missing a user id with the contacts jid + * @throws SmackOpenPgpException in case of an OpenPGP exception */ public void updateKey(OpenPgpV4Fingerprint fingerprint) throws InterruptedException, XMPPException.XMPPErrorException, SmackException, IOException, @@ -212,9 +212,9 @@ public class OpenPgpContact { * * @param data OpenPgp keys byte representation. * @return the fingerprint of the imported key. - * @throws SmackOpenPgpException - * @throws MissingUserIdOnKeyException - * @throws IOException + * @throws SmackOpenPgpException in case of an OpenPGP error + * @throws MissingUserIdOnKeyException if the key is missing a user id with the contacts jid + * @throws IOException IO is dangerous */ private OpenPgpV4Fingerprint importPublicKey(byte[] data) throws SmackOpenPgpException, MissingUserIdOnKeyException, IOException { diff --git a/smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/OpenPgpManager.java b/smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/OpenPgpManager.java index 5a56354d5..77407cf76 100644 --- a/smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/OpenPgpManager.java +++ b/smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/OpenPgpManager.java @@ -268,7 +268,7 @@ public final class OpenPgpManager extends Manager { * * @see XEP-0373 §5 * - * @param connection + * @param connection XMPP connection * @return true, if the server supports secret key backups, otherwise false. * @throws XMPPException.XMPPErrorException in case of an XMPP protocol error. * @throws SmackException.NotConnectedException if we are not connected. @@ -341,6 +341,9 @@ public final class OpenPgpManager extends Manager { * * @param codeCallback callback for prompting the user to provide the secret backup code. * @param selectionCallback callback allowing the user to select a secret key which will be restored. + * + * @return fingerprint of the restored secret key + * * @throws InterruptedException if the connection gets interrupted. * @throws PubSubException.NotALeafNodeException if the private node is not a {@link LeafNode}. * @throws XMPPException.XMPPErrorException in case of an XMPP protocol error. @@ -348,6 +351,10 @@ public final class OpenPgpManager extends Manager { * @throws SmackException.NoResponseException if the server doesn't respond. * @throws SmackOpenPgpException if something goes wrong while restoring the secret key. * @throws InvalidBackupCodeException if the user-provided backup code is invalid. + * @throws SmackException.NotLoggedInException if we are not logged in + * @throws IOException IO is dangerous + * @throws MissingUserIdOnKeyException if the key that is to be imported is missing a user-id with our jid + * @throws NoBackupFoundException if no secret key backup has been found */ public OpenPgpV4Fingerprint restoreSecretKeyServerBackup(AskForBackupCodeCallback codeCallback, SecretKeyRestoreSelectionCallback selectionCallback) diff --git a/smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/OpenPgpProvider.java b/smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/OpenPgpProvider.java index 58baeabdc..f3eff598d 100644 --- a/smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/OpenPgpProvider.java +++ b/smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/OpenPgpProvider.java @@ -55,8 +55,10 @@ public interface OpenPgpProvider { * * @throws MissingOpenPgpKeyPairException if the OpenPGP key pair with the given {@link OpenPgpV4Fingerprint} * is not available. - * @throws MissingOpenPgpKeyPairException if any of the OpenPGP public keys whose {@link OpenPgpV4Fingerprint} + * @throws MissingOpenPgpPublicKeyException if any of the OpenPGP public keys whose {@link OpenPgpV4Fingerprint} * is listed in {@code encryptionKeys} is not available. + * @throws SmackOpenPgpException in case of an OpenPGP error + * @throws IOException IO is dangerous */ byte[] signAndEncrypt(SigncryptElement element, OpenPgpV4Fingerprint signingKey, @@ -76,6 +78,8 @@ public interface OpenPgpProvider { * * @throws MissingOpenPgpKeyPairException if we don't have the key pair for the * {@link OpenPgpV4Fingerprint} available. + * @throws IOException IO is dangerous + * @throws SmackOpenPgpException in case of an OpenPGP error */ byte[] sign(SignElement element, OpenPgpV4Fingerprint singingKeyFingerprint) throws MissingOpenPgpKeyPairException, IOException, SmackOpenPgpException; @@ -97,6 +101,8 @@ public interface OpenPgpProvider { * @throws MissingOpenPgpPublicKeyException if any of the OpenPGP public keys whose * {@link OpenPgpV4Fingerprint} is listed in {@code encryptionKeys} * is not available. + * @throws IOException IO is dangerous + * @throws SmackOpenPgpException in case of an OpenPGP error */ byte[] encrypt(CryptElement element, MultiMap encryptionKeyFingerprints) throws MissingOpenPgpPublicKeyException, IOException, SmackOpenPgpException; @@ -111,14 +117,25 @@ public interface OpenPgpProvider { * @see XEP-0373 §3.1 * * @param bytes byte array which contains the encrypted {@link OpenPgpContentElement}. + * @param sender sender of the message + * @param missingPublicKeyCallback callback to handle missing public keys * @return byte array which contains the decrypted {@link OpenPgpContentElement}, as well as metadata. * * @throws MissingOpenPgpKeyPairException if we don't have an OpenPGP key pair available that to decrypt * the message. + * @throws SmackOpenPgpException in case of an OpenPGP error */ DecryptedBytesAndMetadata decrypt(byte[] bytes, BareJid sender, SmackMissingOpenPgpPublicKeyCallback missingPublicKeyCallback) throws MissingOpenPgpKeyPairException, SmackOpenPgpException; + /** + * Encrypt some data symmetrically using a password. + * @param bytes data + * @param password password + * @return encrypted data + * @throws SmackOpenPgpException in case of an OpenPGP error + * @throws IOException IO is dangerous + */ byte[] symmetricallyEncryptWithPassword(byte[] bytes, String password) throws SmackOpenPgpException, IOException; /** @@ -137,6 +154,11 @@ public interface OpenPgpProvider { * * @param owner JID of the keys owner. * @return byte array representation + {@link OpenPgpV4Fingerprint} of the generated key pair. + * @throws SmackOpenPgpException in case of an OpenPGP error + * @throws InvalidAlgorithmParameterException if invalid algorithm parameters are used for crypto + * @throws NoSuchAlgorithmException if the JVM is lacking support for a used algorithm + * @throws NoSuchProviderException if the JVM is missing a security provider + * @throws IOException IO is dangerous */ KeyBytesAndFingerprint generateOpenPgpKeyPair(BareJid owner) throws SmackOpenPgpException, InvalidAlgorithmParameterException, NoSuchAlgorithmException, @@ -144,21 +166,51 @@ public interface OpenPgpProvider { /** * Import a public key. The bytes are expected to be decoded from base64. - * @param owner - * @param bytes - * @return - * @throws MissingUserIdOnKeyException - * @throws IOException - * @throws SmackOpenPgpException + * + * @param owner owner of the public key + * @param bytes byte representation of the publick key + * + * @return fingerprint of the imported public key + * + * @throws MissingUserIdOnKeyException if the key is missing a user id with {@code owner}. + * @throws IOException IO is dangerous + * @throws SmackOpenPgpException if an OpenPGP error occurs */ OpenPgpV4Fingerprint importPublicKey(BareJid owner, byte[] bytes) throws MissingUserIdOnKeyException, IOException, SmackOpenPgpException; + /** + * Import a secret key. The bytes are expected to be decoded from base64. + * + * @param owner owner of the secret key + * @param bytes byte representation of the secret key + * + * @return fingerprint of the imported secret key + * + * @throws MissingUserIdOnKeyException if the key is missing a user-id of {@code owner} + * @throws SmackOpenPgpException in case of an OpenPGP error + * @throws IOException IO is dangerous + */ OpenPgpV4Fingerprint importSecretKey(BareJid owner, byte[] bytes) throws MissingUserIdOnKeyException, SmackOpenPgpException, IOException; + /** + * Import a secret key that belong to ourselves. + * + * @param bytes byte representation of the secret key. + * + * @return fingerprint of the imported secret key. + * + * @throws MissingUserIdOnKeyException if the secret key is missing a user-id with our jid + * @throws SmackOpenPgpException in case of an OpenPGP error + * @throws IOException IO is dangerous + */ OpenPgpV4Fingerprint importSecretKey(byte[] bytes) throws MissingUserIdOnKeyException, SmackOpenPgpException, IOException; + /** + * Return the underlying {@link OpenPgpStore}. + * @return store + */ OpenPgpStore getStore(); } diff --git a/smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/OpenPgpStore.java b/smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/OpenPgpStore.java index 6623f8d18..ecabcd5a4 100644 --- a/smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/OpenPgpStore.java +++ b/smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/OpenPgpStore.java @@ -54,7 +54,7 @@ public interface OpenPgpStore { * @param owner owner. * @return set of fingerprints of available OpenPGP key pairs master keys. * - * @throws SmackOpenPgpException + * @throws SmackOpenPgpException in case of an OpenPGP error */ Set getAvailableKeyPairFingerprints(BareJid owner) throws SmackOpenPgpException; @@ -62,8 +62,7 @@ public interface OpenPgpStore { * Return a {@link Map} containing the {@link OpenPgpV4Fingerprint}s of all OpenPGP public keys of a * contact, which we have locally available, as well as the date, those keys had been published on. *
- * Note: This returns a {@link Map} that might be different from the result of - * {@link #getAvailableKeysFingerprints(BareJid)} (BareJid)}. + * Note: This returns a {@link Map} that might be different from the result of (BareJid)}. * Messages should be encrypted to the intersection of both key sets. * * @param contact contact. diff --git a/smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/callback/DisplayBackupCodeCallback.java b/smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/callback/DisplayBackupCodeCallback.java index ed1ef7595..a3bade488 100644 --- a/smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/callback/DisplayBackupCodeCallback.java +++ b/smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/callback/DisplayBackupCodeCallback.java @@ -26,7 +26,7 @@ public interface DisplayBackupCodeCallback { * @see * XEP-0373 §5.3 about the format of the backup code * - * @param backupCode + * @param backupCode backup code */ void displayBackupCode(String backupCode); } diff --git a/smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/util/PubSubDelegate.java b/smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/util/PubSubDelegate.java index 27adc933c..17623a1e6 100644 --- a/smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/util/PubSubDelegate.java +++ b/smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/util/PubSubDelegate.java @@ -90,10 +90,10 @@ public class PubSubDelegate { * * @param node {@link LeafNode} whose PubSub access model we want to change * @param accessModel new access model. - * @throws XMPPException.XMPPErrorException - * @throws SmackException.NotConnectedException - * @throws InterruptedException - * @throws SmackException.NoResponseException + * @throws XMPPException.XMPPErrorException in case of an XMPP protocol error. + * @throws SmackException.NotConnectedException if we are not connected. + * @throws InterruptedException if the connection is interrupted. + * @throws SmackException.NoResponseException if the server doesn't respond. */ public static void changeAccessModelIfNecessary(LeafNode node, AccessModel accessModel) throws XMPPException.XMPPErrorException, SmackException.NotConnectedException, InterruptedException, @@ -110,13 +110,17 @@ public class PubSubDelegate { * Publish the users OpenPGP public key to the public key node if necessary. * Also announce the key to other users by updating the metadata node. * + * @param connection XMPP connection + * @param pubkeyElement {@link PubkeyElement} containing the public key + * @param fingerprint fingerprint of the public key * @see XEP-0373 §4.1 * - * @throws InterruptedException - * @throws PubSubException.NotALeafNodeException - * @throws XMPPException.XMPPErrorException - * @throws SmackException.NotConnectedException - * @throws SmackException.NoResponseException + * @throws InterruptedException if the connection gets interrupted. + * @throws PubSubException.NotALeafNodeException if either the metadata node or the public key node is not a + * {@link LeafNode}. + * @throws XMPPException.XMPPErrorException in case of an XMPP protocol error. + * @throws SmackException.NotConnectedException if we are not connected. + * @throws SmackException.NoResponseException if the server doesn't respond. */ public static void publishPublicKey(XMPPConnection connection, PubkeyElement pubkeyElement, OpenPgpV4Fingerprint fingerprint) throws InterruptedException, PubSubException.NotALeafNodeException, @@ -160,10 +164,11 @@ public class PubSubDelegate { * Consult the public key metadata node and fetch a list of all of our published OpenPGP public keys. * TODO: Add @see which points to the (for now missing) respective example in XEP-0373. * + * @param connection XMPP connection * @return content of our metadata node. - * @throws InterruptedException - * @throws SmackException - * @throws XMPPException.XMPPErrorException + * @throws InterruptedException if the connection gets interrupted. + * @throws SmackException in case of an error in Smack. + * @throws XMPPException.XMPPErrorException in case of an XMPP protocol exception. */ public static PublicKeysListElement fetchPubkeysList(XMPPConnection connection) throws InterruptedException, SmackException, @@ -176,11 +181,12 @@ public class PubSubDelegate { * Consult the public key metadata node of {@code contact} to fetch the list of their published OpenPGP public keys. * TODO: Add @see which points to the (for now missing) respective example in XEP-0373. * + * @param connection XMPP connection * @param contact {@link BareJid} of the user we want to fetch the list from. * @return content of {@code contact}'s metadata node. - * @throws InterruptedException - * @throws SmackException - * @throws XMPPException.XMPPErrorException + * @throws InterruptedException if the connection gets interrupted. + * @throws SmackException in case of an exception in Smack. + * @throws XMPPException.XMPPErrorException in case of an XMPP protocol exception. */ public static PublicKeysListElement fetchPubkeysList(XMPPConnection connection, BareJid contact) throws InterruptedException, SmackException, @@ -200,10 +206,11 @@ public class PubSubDelegate { /** * Delete our metadata node. * - * @throws XMPPException.XMPPErrorException - * @throws SmackException.NotConnectedException - * @throws InterruptedException - * @throws SmackException.NoResponseException + * @param connection XMPP connection + * @throws XMPPException.XMPPErrorException in case of an XMPP protocol error. + * @throws SmackException.NotConnectedException if we are not connected. + * @throws InterruptedException if the connection is interrupted. + * @throws SmackException.NoResponseException if the server doesn't respond. */ public static void deletePubkeysListNode(XMPPConnection connection) throws XMPPException.XMPPErrorException, SmackException.NotConnectedException, InterruptedException, @@ -223,12 +230,12 @@ public class PubSubDelegate { /** * Delete the public key node of the key with fingerprint {@code fingerprint}. * - * @param connection - * @param fingerprint - * @throws XMPPException.XMPPErrorException - * @throws SmackException.NotConnectedException - * @throws InterruptedException - * @throws SmackException.NoResponseException + * @param connection XMPP connection + * @param fingerprint fingerprint of the key we want to delete + * @throws XMPPException.XMPPErrorException in case of an XMPP protocol error. + * @throws SmackException.NotConnectedException if we are not connected. + * @throws InterruptedException if the connection gets interrupted. + * @throws SmackException.NoResponseException if the server doesn't respond. */ public static void deletePublicKeyNode(XMPPConnection connection, OpenPgpV4Fingerprint fingerprint) throws XMPPException.XMPPErrorException, SmackException.NotConnectedException, InterruptedException, @@ -251,13 +258,14 @@ public class PubSubDelegate { * * @see XEP-0373 §4.3 * + * @param connection XMPP connection * @param contact {@link BareJid} of the contact we want to fetch a key from. * @param v4_fingerprint upper case, hex encoded v4 fingerprint of the contacts key. * @return {@link PubkeyElement} containing the requested public key. * * @throws InterruptedException if we get interrupted. * @throws SmackException in case the node cannot be fetched. - * @throws XMPPException.XMPPErrorException + * @throws XMPPException.XMPPErrorException in case of an XMPP protocol error. */ public static PubkeyElement fetchPubkey(XMPPConnection connection, BareJid contact, OpenPgpV4Fingerprint v4_fingerprint) throws InterruptedException, SmackException, XMPPException.XMPPErrorException { @@ -287,13 +295,12 @@ public class PubSubDelegate { * @throws XMPPException.XMPPErrorException in case of an protocol related error * @throws SmackException.NotConnectedException if we are not connected * @throws SmackException.NoResponseException /watch?v=0peBq89ZTrc - * @throws SmackException.NotLoggedInException if we are not logged in * @throws SmackException.FeatureNotSupportedException if the Server doesn't support the whitelist access model */ public static void depositSecretKey(XMPPConnection connection, SecretkeyElement element) throws InterruptedException, PubSubException.NotALeafNodeException, XMPPException.XMPPErrorException, SmackException.NotConnectedException, SmackException.NoResponseException, - SmackException.NotLoggedInException, SmackException.FeatureNotSupportedException { + SmackException.FeatureNotSupportedException { if (!OpenPgpManager.serverSupportsSecretKeyBackups(connection)) { throw new SmackException.FeatureNotSupportedException("http://jabber.org/protocol/pubsub#access-whitelist"); }