vanitasvitae/Smack
1
0
Fork 0
mirror of https://github.com/vanitasvitae/Smack.git synced 2024-11-23 20:42:06 +01:00
Code Issues Releases Wiki Activity

Add missing javadoc

Browse source
This commit is contained in:
Paul Schaub 2018-07-05 14:25:29 +02:00
parent cf4129f932
commit 9d0d639255
Signed by: vanitasvitae
GPG key ID: 62BEE9264BF17311
7 changed files with 160 additions and 61 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

50
smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/OXInstantMessagingManager.java
View file

@ -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 {

26
smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/OpenPgpContact.java
View file

@ -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 {

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

@ -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)

66
smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/OpenPgpProvider.java
View file

@ -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
* @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();
}

5
smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/OpenPgpStore.java
View file

@ -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
* {@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.

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

@ -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);
}

63
smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/util/PubSubDelegate.java
View file

@ -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 <a href="https://xmpp.org/extensions/xep-0373.html#annoucning-pubkey">XEP-0373 §4.1</a>
*
* @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 <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");
}