Mercury-IM/Smack
Mercury-IM/Smack
1
0
Fork 0
mirror of https://codeberg.org/Mercury-IM/Smack synced 2024-12-22 20:47:57 +01:00
Code Issues Releases Wiki Activity

Add more javadoc

Browse source
This commit is contained in:
Paul Schaub 2018-08-02 17:33:55 +02:00
parent f3b65f3dc8
commit b530727539
Signed by: vanitasvitae
GPG key ID: 62BEE9264BF17311
4 changed files with 75 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -140,6 +140,15 @@ import org.xmlpull.v1.XmlPullParserException;
* {@link OpenPgpSelf}, which encapsulates your own OpenPGP identity. Both classes can be used to acquire information
* about the OpenPGP keys of a user.
*
* <h2>Elements</h2>
*
* OpenPGP for XMPP defines multiple different element classes which contain the users messages.
* The outermost element is the {@link OpenPgpElement}, which contains an OpenPGP encrypted content element.
*
* The content can be either a {@link SignElement}, {@link CryptElement} or {@link SigncryptElement}, depending on the use-case.
* Those content elements contain the actual payload. If an {@link OpenPgpElement} is decrypted, it will be returned in
* form of an {@link OpenPgpMessage}, which represents the decrypted message + metadata.
*
* @see <a href="https://xmpp.org/extensions/xep-0373.html">
* XEP-0373: OpenPGP for XMPP</a>
*/
@ -518,8 +527,21 @@ public final class OpenPgpManager extends Manager {
}
}
public OpenPgpMessage decryptOpenPgpElement(OpenPgpElement element, OpenPgpContact contact) throws SmackException.NotLoggedInException, IOException, PGPException {
return provider.decryptAndOrVerify(element, getOpenPgpSelf(), contact);
/**
* Decrypt and or verify an {@link OpenPgpElement} and return the decrypted {@link OpenPgpMessage}.
*
* @param element {@link OpenPgpElement} containing the message.
* @param sender {@link OpenPgpContact} who sent the message.
*
* @return decrypted and/or verified message
*
* @throws SmackException.NotLoggedInException in case we aren't logged in (we need to know our jid)
* @throws IOException IO error (reading keys, streams etc)
* @throws PGPException in case of an PGP error
*/
public OpenPgpMessage decryptOpenPgpElement(OpenPgpElement element, OpenPgpContact sender)
throws SmackException.NotLoggedInException, IOException, PGPException {
return provider.decryptAndOrVerify(element, getOpenPgpSelf(), sender);
}
private final IncomingChatMessageListener incomingOpenPgpMessageListener =

13
smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/OpenPgpMessage.java
View file

@ -31,7 +31,18 @@ import org.pgpainless.decryption_verification.OpenPgpMetadata;
import org.xmlpull.v1.XmlPullParserException;
/**
* This class embodies a decrypted {@link OpenPgpElement}.
* This class embodies a decrypted and/or verified {@link OpenPgpElement}.
* <br>
* The content can be one of the following three {@link OpenPgpContentElement}s:
* <br><br>
* {@link SignElement}: The content is expected to be signed with the senders key, but unencrypted.<br>
* {@link CryptElement}: The content is expected to be encrypted, but not signed.<br>
* {@link SigncryptElement}: The content is expected to be signed with the senders key and encrypted.<br>
* <br>
* To determine, of which nature the content of the message is, use {@link #getState()}. You should utilize this
* information to cast the return value of {@link #getOpenPgpContentElement()} correctly.
* <br>
* Use {@link #getMetadata()} in order to get information about the messages encryption status, its signatures etc.
*/
public class OpenPgpMessage {

10
smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/OpenPgpSelf.java
View file

@ -30,8 +30,18 @@ import org.jxmpp.jid.BareJid;
import org.pgpainless.key.OpenPgpV4Fingerprint;
import org.pgpainless.util.BCUtil;
/**
* This class acts as our own OpenPGP identity. It can be seen as a special view on the {@link OpenPgpStore}, giving
* access to our own encryption keys etc.
*/
public class OpenPgpSelf extends OpenPgpContact {
/**
* Constructor.
*
* @param jid our own {@link BareJid}. This is needed to access our keys in the store.
* @param store the store.
*/
OpenPgpSelf(BareJid jid, OpenPgpStore store) {
super(jid, store);
}

29
smack-openpgp/src/main/java/org/jivesoftware/smackx/ox_im/OXInstantMessagingManager.java
View file

@ -38,6 +38,7 @@ import org.jivesoftware.smackx.ox.OpenPgpContact;
import org.jivesoftware.smackx.ox.OpenPgpManager;
import org.jivesoftware.smackx.ox.OpenPgpMessage;
import org.jivesoftware.smackx.ox.crypto.OpenPgpElementAndMetadata;
import org.jivesoftware.smackx.ox.element.OpenPgpContentElement;
import org.jivesoftware.smackx.ox.element.OpenPgpElement;
import org.jivesoftware.smackx.ox.element.SigncryptElement;
import org.jivesoftware.smackx.ox.listener.SigncryptElementReceivedListener;
@ -47,6 +48,7 @@ import org.jxmpp.jid.BareJid;
import org.jxmpp.jid.Jid;
import org.pgpainless.decryption_verification.OpenPgpMetadata;
import org.pgpainless.key.OpenPgpV4Fingerprint;
import org.xmlpull.v1.XmlPullParserException;
/**
* Entry point of Smacks API for XEP-0374: OpenPGP for XMPP: Instant Messaging.
@ -314,6 +316,33 @@ public final class OXInstantMessagingManager extends Manager {
return encrypted;
}
/**
* Manually decrypt and verify an {@link OpenPgpElement}.
*
* @param element encrypted, signed {@link OpenPgpElement}.
* @param sender sender of the message.
*
* @return decrypted, verified message
*
* @throws SmackException.NotLoggedInException In case we are not logged in (we need our jid to access our keys)
* @throws PGPException in case of an PGP error
* @throws IOException in case of an IO error (reading keys, streams etc)
* @throws XmlPullParserException in case that the content of the {@link OpenPgpElement} is not a valid
* {@link OpenPgpContentElement} or broken XML.
* @throws IllegalArgumentException if the elements content is not a {@link SigncryptElement}. This happens, if the
* element likely is not an OX message.
*/
public OpenPgpMessage decryptAndVerify(OpenPgpElement element, OpenPgpContact sender)
throws SmackException.NotLoggedInException, PGPException, IOException, XmlPullParserException {
OpenPgpMessage decrypted = openPgpManager.decryptOpenPgpElement(element, sender);
if (decrypted.getState() != OpenPgpMessage.State.signcrypt) {
throw new IllegalArgumentException("Decrypted message does appear to not be an OX message. (State: " + decrypted.getState() + ")");
}
return decrypted;
}
/**
* Set a hint about the message being OX-IM encrypted as body of the message.
*