Add missing javadoc

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 XMPPException.XMPPErrorException in case of an XMPP protocol error
-     * @throws SmackException.NotConnectedException
+     * @throws SmackException.NotConnectedException if we are not connected
-     * @throws InterruptedException
+     * @throws InterruptedException if the connection gets interrupted
-     * @throws SmackException.NoResponseException
+     * @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 XMPPException.XMPPErrorException in case of an XMPP protocol error
-     * @throws SmackException.NotConnectedException
+     * @throws SmackException.NotConnectedException if we are not connected
-     * @throws InterruptedException
+     * @throws InterruptedException if the connection is interrupted
-     * @throws SmackException.NoResponseException
+     * @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 {

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 InterruptedException if the connection is interrupted
-     * @throws XMPPException.XMPPErrorException
+     * @throws XMPPException.XMPPErrorException in case of an XMPP protocol error
-     * @throws SmackException
+     * @throws SmackException in case of an error in Smack
-     * @throws SmackOpenPgpException
+     * @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 InterruptedException if the connection is interrupted
-     * @throws XMPPException.XMPPErrorException
+     * @throws XMPPException.XMPPErrorException in case of an XMPP protocol error
-     * @throws SmackException
+     * @throws SmackException in case of an exception in Smack
-     * @throws IOException
+     * @throws IOException IO is dangerous
-     * @throws MissingUserIdOnKeyException
+     * @throws MissingUserIdOnKeyException if the key is missing a user id with the contacts jid
-     * @throws SmackOpenPgpException
+     * @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 SmackOpenPgpException in case of an OpenPGP error
-     * @throws MissingUserIdOnKeyException
+     * @throws MissingUserIdOnKeyException if the key is missing a user id with the contacts jid
-     * @throws IOException
+     * @throws IOException IO is dangerous
      */
     private OpenPgpV4Fingerprint importPublicKey(byte[] data)
             throws SmackOpenPgpException, MissingUserIdOnKeyException, IOException {

smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/OpenPgpManager.java

@@ -268,7 +268,7 @@ public final class OpenPgpManager extends Manager {
      *
      * @see <a href="https://xmpp.org/extensions/xep-0373.html#synchro-pep">XEP-0373 §5</a>
      *
-     * @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)

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<BareJid, OpenPgpV4Fingerprint> encryptionKeyFingerprints)
             throws MissingOpenPgpPublicKeyException, IOException, SmackOpenPgpException;
@@ -111,14 +117,25 @@ public interface OpenPgpProvider {
      * @see <a href="https://xmpp.org/extensions/xep-0373.html#exchange">XEP-0373 §3.1</a>
      *
      * @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
+     * @param owner owner of the public key
-     * @return
+     * @param bytes byte representation of the publick key
-     * @throws MissingUserIdOnKeyException
+     *
-     * @throws IOException
+     * @return fingerprint of the imported public key
-     * @throws SmackOpenPgpException
+     *
+     * @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();
 }

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<OpenPgpV4Fingerprint> 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.
      * <br>
-     * Note: This returns a {@link Map} that might be different from the result of
+     * Note: This returns a {@link Map} that might be different from the result of (BareJid)}.
-     * {@link #getAvailableKeysFingerprints(BareJid)} (BareJid)}.
      * Messages should be encrypted to the intersection of both key sets.
      *
      * @param contact contact.

smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/callback/DisplayBackupCodeCallback.java

@@ -26,7 +26,7 @@ public interface DisplayBackupCodeCallback {
      * @see <a href="https://xmpp.org/extensions/xep-0373.html#sect-idm139662753819792">
      *     XEP-0373 §5.3 about the format of the backup code</a>
      *
-     *  @param backupCode
+     *  @param backupCode backup code
      */
     void displayBackupCode(String backupCode);
 }

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 XMPPException.XMPPErrorException in case of an XMPP protocol error.
-     * @throws SmackException.NotConnectedException
+     * @throws SmackException.NotConnectedException if we are not connected.
-     * @throws InterruptedException
+     * @throws InterruptedException if the connection is interrupted.
-     * @throws SmackException.NoResponseException
+     * @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 <a href="https://xmpp.org/extensions/xep-0373.html#annoucning-pubkey">XEP-0373 §4.1</a>
      *
-     * @throws InterruptedException
+     * @throws InterruptedException if the connection gets interrupted.
-     * @throws PubSubException.NotALeafNodeException
+     * @throws PubSubException.NotALeafNodeException if either the metadata node or the public key node is not a
-     * @throws XMPPException.XMPPErrorException
+     *                                               {@link LeafNode}.
-     * @throws SmackException.NotConnectedException
+     * @throws XMPPException.XMPPErrorException in case of an XMPP protocol error.
-     * @throws SmackException.NoResponseException
+     * @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 InterruptedException if the connection gets interrupted.
-     * @throws SmackException
+     * @throws SmackException in case of an error in Smack.
-     * @throws XMPPException.XMPPErrorException
+     * @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 InterruptedException if the connection gets interrupted.
-     * @throws SmackException
+     * @throws SmackException in case of an exception in Smack.
-     * @throws XMPPException.XMPPErrorException
+     * @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
+     * @param connection XMPP connection
-     * @throws SmackException.NotConnectedException
+     * @throws XMPPException.XMPPErrorException in case of an XMPP protocol error.
-     * @throws InterruptedException
+     * @throws SmackException.NotConnectedException if we are not connected.
-     * @throws SmackException.NoResponseException
+     * @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 connection XMPP connection
-     * @param fingerprint
+     * @param fingerprint fingerprint of the key we want to delete
-     * @throws XMPPException.XMPPErrorException
+     * @throws XMPPException.XMPPErrorException in case of an XMPP protocol error.
-     * @throws SmackException.NotConnectedException
+     * @throws SmackException.NotConnectedException if we are not connected.
-     * @throws InterruptedException
+     * @throws InterruptedException if the connection gets interrupted.
-     * @throws SmackException.NoResponseException
+     * @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 <a href="https://xmpp.org/extensions/xep-0373.html#discover-pubkey">XEP-0373 §4.3</a>
      *
+     * @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");
         }