diff --git a/pgpainless-core/src/main/java/org/pgpainless/algorithm/CompressionAlgorithm.java b/pgpainless-core/src/main/java/org/pgpainless/algorithm/CompressionAlgorithm.java
index 2b531f49..970f1cf1 100644
--- a/pgpainless-core/src/main/java/org/pgpainless/algorithm/CompressionAlgorithm.java
+++ b/pgpainless-core/src/main/java/org/pgpainless/algorithm/CompressionAlgorithm.java
@@ -20,6 +20,11 @@ import java.util.concurrent.ConcurrentHashMap;
import org.bouncycastle.bcpg.CompressionAlgorithmTags;
+/**
+ * Enumeration of possible compression algorithms.
+ *
+ * @see RFC4880: Compression Algorithm Tags
+ */
public enum CompressionAlgorithm {
UNCOMPRESSED (CompressionAlgorithmTags.UNCOMPRESSED),
@@ -36,6 +41,13 @@ public enum CompressionAlgorithm {
}
}
+ /**
+ * Return the {@link CompressionAlgorithm} value that corresponds to the provided numerical id.
+ * If an invalid id is provided, null is returned.
+ *
+ * @param id id
+ * @return compression algorithm
+ */
public static CompressionAlgorithm fromId(int id) {
return MAP.get(id);
}
@@ -46,6 +58,10 @@ public enum CompressionAlgorithm {
this.algorithmId = id;
}
+ /**
+ * Return the numerical algorithm tag corresponding to this compression algorithm.
+ * @return id
+ */
public int getAlgorithmId() {
return algorithmId;
}
diff --git a/pgpainless-core/src/main/java/org/pgpainless/algorithm/Feature.java b/pgpainless-core/src/main/java/org/pgpainless/algorithm/Feature.java
index 8bcf0369..77f7ae65 100644
--- a/pgpainless-core/src/main/java/org/pgpainless/algorithm/Feature.java
+++ b/pgpainless-core/src/main/java/org/pgpainless/algorithm/Feature.java
@@ -20,6 +20,11 @@ import java.util.concurrent.ConcurrentHashMap;
import org.bouncycastle.bcpg.sig.Features;
+/**
+ * An enumeration of features that may be set in the {@link Features} subpacket.
+ *
+ * @see RFC4880: Features
+ */
public enum Feature {
/**
diff --git a/pgpainless-core/src/main/java/org/pgpainless/algorithm/HashAlgorithm.java b/pgpainless-core/src/main/java/org/pgpainless/algorithm/HashAlgorithm.java
index caf2364d..1c432fd9 100644
--- a/pgpainless-core/src/main/java/org/pgpainless/algorithm/HashAlgorithm.java
+++ b/pgpainless-core/src/main/java/org/pgpainless/algorithm/HashAlgorithm.java
@@ -20,8 +20,13 @@ import java.util.concurrent.ConcurrentHashMap;
import org.bouncycastle.bcpg.HashAlgorithmTags;
+/**
+ * An enumeration of different hashing algorithms.
+ *
+ * @see RFC4880: Hash Algorithms
+ */
public enum HashAlgorithm {
-
+ @Deprecated
MD5 (HashAlgorithmTags.MD5),
SHA1 (HashAlgorithmTags.SHA1),
RIPEMD160 (HashAlgorithmTags.RIPEMD160),
@@ -43,6 +48,13 @@ public enum HashAlgorithm {
}
}
+ /**
+ * Return the {@link HashAlgorithm} value that corresponds to the provided algorithm id.
+ * If an invalid algorithm id was provided, null is returned.
+ *
+ * @param id numeric id
+ * @return enum value
+ */
public static HashAlgorithm fromId(int id) {
return MAP.get(id);
}
@@ -53,6 +65,11 @@ public enum HashAlgorithm {
this.algorithmId = id;
}
+ /**
+ * Return the numeric algorithm id of the hash algorithm.
+ *
+ * @return numeric id
+ */
public int getAlgorithmId() {
return algorithmId;
}
diff --git a/pgpainless-core/src/main/java/org/pgpainless/algorithm/KeyFlag.java b/pgpainless-core/src/main/java/org/pgpainless/algorithm/KeyFlag.java
index be12f41e..0ef093aa 100644
--- a/pgpainless-core/src/main/java/org/pgpainless/algorithm/KeyFlag.java
+++ b/pgpainless-core/src/main/java/org/pgpainless/algorithm/KeyFlag.java
@@ -20,14 +20,47 @@ import java.util.List;
import org.bouncycastle.bcpg.sig.KeyFlags;
+/**
+ * Enumeration of different key flags.
+ * Key flags denote different capabilities of a key pair.
+ *
+ * @see RFC4880: Key Flags
+ */
public enum KeyFlag {
+ /**
+ * This key may be used to certify other keys.
+ */
CERTIFY_OTHER (KeyFlags.CERTIFY_OTHER),
+
+ /**
+ * This key may be used to sign data.
+ */
SIGN_DATA (KeyFlags.SIGN_DATA),
+
+ /**
+ * This key may be used to encrypt communications.
+ */
ENCRYPT_COMMS (KeyFlags.ENCRYPT_COMMS),
+
+ /**
+ * This key may be used to encrypt storage.
+ */
ENCRYPT_STORAGE(KeyFlags.ENCRYPT_STORAGE),
+
+ /**
+ * The private component of this key may have been split by a secret-sharing mechanism.
+ */
SPLIT (KeyFlags.SPLIT),
+
+ /**
+ * This key may be used for authentication.
+ */
AUTHENTICATION (KeyFlags.AUTHENTICATION),
+
+ /**
+ * The private component of this key may be in the possession of more than one person.
+ */
SHARED (KeyFlags.SHARED),
;
@@ -37,10 +70,21 @@ public enum KeyFlag {
this.flag = flag;
}
+ /**
+ * Return the numeric id of the {@link KeyFlag}.
+ *
+ * @return numeric id
+ */
public int getFlag() {
return flag;
}
+ /**
+ * Convert a bitmask into a list of {@link KeyFlag KeyFlags}.
+ *
+ * @param bitmask bitmask
+ * @return list of key flags encoded by the bitmask
+ */
public static List fromBitmask(int bitmask) {
List flags = new ArrayList<>();
for (KeyFlag f : KeyFlag.values()) {
@@ -51,6 +95,12 @@ public enum KeyFlag {
return flags;
}
+ /**
+ * Encode a list of {@link KeyFlag KeyFlags} into a bitmask.
+ *
+ * @param flags list of flags
+ * @return bitmask
+ */
public static int toBitmask(KeyFlag... flags) {
int mask = 0;
for (KeyFlag f : flags) {
@@ -59,6 +109,14 @@ public enum KeyFlag {
return mask;
}
+ /**
+ * Return true if the provided bitmask has the bit for the provided flag set.
+ * Return false if the mask does not contain the flag.
+ *
+ * @param mask bitmask
+ * @param flag flag to be tested for
+ * @return true if flag is set, false otherwise
+ */
public static boolean hasKeyFlag(int mask, KeyFlag flag) {
return (mask & flag.getFlag()) == flag.getFlag();
}
diff --git a/pgpainless-core/src/main/java/org/pgpainless/algorithm/PublicKeyAlgorithm.java b/pgpainless-core/src/main/java/org/pgpainless/algorithm/PublicKeyAlgorithm.java
index a7536973..1b940551 100644
--- a/pgpainless-core/src/main/java/org/pgpainless/algorithm/PublicKeyAlgorithm.java
+++ b/pgpainless-core/src/main/java/org/pgpainless/algorithm/PublicKeyAlgorithm.java
@@ -20,6 +20,11 @@ import java.util.concurrent.ConcurrentHashMap;
import org.bouncycastle.bcpg.PublicKeyAlgorithmTags;
+/**
+ * Enumeration of public key algorithms as defined in RFC4880.
+ *
+ * @see RFC4880: Public-Key Algorithms
+ */
public enum PublicKeyAlgorithm {
/**
@@ -32,6 +37,7 @@ public enum PublicKeyAlgorithm {
*
* @deprecated see https://tools.ietf.org/html/rfc4880#section-13.5
*/
+ @Deprecated
RSA_ENCRYPT (PublicKeyAlgorithmTags.RSA_ENCRYPT),
/**
@@ -39,6 +45,7 @@ public enum PublicKeyAlgorithm {
*
* @deprecated see https://tools.ietf.org/html/rfc4880#section-13.5
*/
+ @Deprecated
RSA_SIGN (PublicKeyAlgorithmTags.RSA_SIGN),
/**
@@ -55,6 +62,7 @@ public enum PublicKeyAlgorithm {
* EC is deprecated.
* @deprecated use {@link #ECDH} instead.
*/
+ @Deprecated
EC (PublicKeyAlgorithmTags.EC),
/**
@@ -94,6 +102,13 @@ public enum PublicKeyAlgorithm {
}
}
+ /**
+ * Return the {@link PublicKeyAlgorithm} that corresponds to the provided algorithm id.
+ * If an invalid id is provided, null is returned.
+ *
+ * @param id numeric algorithm id
+ * @return algorithm
+ */
public static PublicKeyAlgorithm fromId(int id) {
return MAP.get(id);
}
@@ -104,6 +119,11 @@ public enum PublicKeyAlgorithm {
this.algorithmId = algorithmId;
}
+ /**
+ * Return the numeric identifier of the public key algorithm.
+ *
+ * @return id
+ */
public int getAlgorithmId() {
return algorithmId;
}
diff --git a/pgpainless-core/src/main/java/org/pgpainless/algorithm/SignatureSubpacket.java b/pgpainless-core/src/main/java/org/pgpainless/algorithm/SignatureSubpacket.java
index 981aa197..5c3a71bd 100644
--- a/pgpainless-core/src/main/java/org/pgpainless/algorithm/SignatureSubpacket.java
+++ b/pgpainless-core/src/main/java/org/pgpainless/algorithm/SignatureSubpacket.java
@@ -49,6 +49,11 @@ import java.util.List;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;
+/**
+ * Enumeration of possible subpackets that might be found in the hashed and unhashed area of an OpenPGP signature.
+ *
+ * @see RFC4880: Signature Subpacket Specification
+ */
public enum SignatureSubpacket {
/**
@@ -408,10 +413,20 @@ public enum SignatureSubpacket {
this.code = code;
}
+ /**
+ * Return the numerical identifier of the {@link SignatureSubpacket}.
+ * @return id
+ */
public int getCode() {
return code;
}
+ /**
+ * Return the {@link SignatureSubpacket} that corresponds to the provided id.
+ *
+ * @param code id
+ * @return signature subpacket
+ */
public static SignatureSubpacket fromCode(int code) {
SignatureSubpacket tag = MAP.get(code);
if (tag == null) {
@@ -420,6 +435,12 @@ public enum SignatureSubpacket {
return tag;
}
+ /**
+ * Convert an array of signature subpacket tags into a list of {@link SignatureSubpacket SignatureSubpackets}.
+ *
+ * @param codes array of codes
+ * @return list of subpackets
+ */
public static List fromCodes(int[] codes) {
List tags = new ArrayList<>();
for (int code : codes) {
diff --git a/pgpainless-core/src/main/java/org/pgpainless/algorithm/SignatureType.java b/pgpainless-core/src/main/java/org/pgpainless/algorithm/SignatureType.java
index a77e5405..e8689155 100644
--- a/pgpainless-core/src/main/java/org/pgpainless/algorithm/SignatureType.java
+++ b/pgpainless-core/src/main/java/org/pgpainless/algorithm/SignatureType.java
@@ -173,6 +173,12 @@ public enum SignatureType {
}
}
+ /**
+ * Convert a numerical id into a {@link SignatureType}.
+ *
+ * @param code numeric id
+ * @return signature type enum
+ */
public static SignatureType valueOf(int code) {
SignatureType type = map.get(code);
if (type != null) {
@@ -187,6 +193,11 @@ public enum SignatureType {
this.code = code;
}
+ /**
+ * Return the numeric id of the signature type enum.
+ *
+ * @return numeric id
+ */
public int getCode() {
return code;
}
diff --git a/pgpainless-core/src/main/java/org/pgpainless/algorithm/StreamEncoding.java b/pgpainless-core/src/main/java/org/pgpainless/algorithm/StreamEncoding.java
index 7b75bf80..56dd7afa 100644
--- a/pgpainless-core/src/main/java/org/pgpainless/algorithm/StreamEncoding.java
+++ b/pgpainless-core/src/main/java/org/pgpainless/algorithm/StreamEncoding.java
@@ -21,14 +21,33 @@ import java.util.concurrent.ConcurrentHashMap;
import org.bouncycastle.openpgp.PGPLiteralData;
/**
- * Encoding of the stream.
+ * Enumeration of possible encoding formats of the content of the literal data packet.
*
* @see RFC4880: Literal Data Packet
*/
public enum StreamEncoding {
+
+ /**
+ * The Literal packet contains binary data.
+ */
BINARY(PGPLiteralData.BINARY),
+
+ /**
+ * The Literal packet contains text data, and thus may need line ends converted to local form, or other
+ * text-mode changes.
+ */
TEXT(PGPLiteralData.TEXT),
+
+ /**
+ * Indication that the implementation believes that the literal data contains UTF-8 text.
+ */
UTF8(PGPLiteralData.UTF8),
+
+ /**
+ * Early versions of PGP also defined a value of 'l' as a 'local' mode for machine-local conversions.
+ * RFC 1991 [RFC1991] incorrectly stated this local mode flag as '1' (ASCII numeral one).
+ * Both of these local modes are deprecated.
+ */
@Deprecated
LOCAL('l'),
;
@@ -40,6 +59,7 @@ public enum StreamEncoding {
for (StreamEncoding f : StreamEncoding.values()) {
MAP.put(f.code, f);
}
+ // RFC 1991 [RFC1991] incorrectly stated local mode flag as '1', see doc of LOCAL.
MAP.put('1', LOCAL);
}
@@ -47,10 +67,21 @@ public enum StreamEncoding {
this.code = code;
}
+ /**
+ * Return the code identifier of the encoding.
+ *
+ * @return identifier
+ */
public char getCode() {
return code;
}
+ /**
+ * Return the {@link StreamEncoding} corresponding to the provided code identifier.
+ *
+ * @param code identifier
+ * @return encoding enum
+ */
public static StreamEncoding fromCode(int code) {
return MAP.get((char) code);
}
diff --git a/pgpainless-core/src/main/java/org/pgpainless/algorithm/SymmetricKeyAlgorithm.java b/pgpainless-core/src/main/java/org/pgpainless/algorithm/SymmetricKeyAlgorithm.java
index e69a8fa4..899b61ec 100644
--- a/pgpainless-core/src/main/java/org/pgpainless/algorithm/SymmetricKeyAlgorithm.java
+++ b/pgpainless-core/src/main/java/org/pgpainless/algorithm/SymmetricKeyAlgorithm.java
@@ -20,25 +20,85 @@ import java.util.concurrent.ConcurrentHashMap;
import org.bouncycastle.bcpg.SymmetricKeyAlgorithmTags;
+/**
+ * Enumeration of possible symmetric encryption algorithms.
+ *
+ * @see RFC4880: Symmetric-Key Algorithms
+ */
public enum SymmetricKeyAlgorithm {
+ /**
+ * Plaintext or unencrypted data.
+ */
NULL (SymmetricKeyAlgorithmTags.NULL),
+
/**
* IDEA is deprecated.
* @deprecated use a different algorithm.
*/
+ @Deprecated
IDEA (SymmetricKeyAlgorithmTags.IDEA),
+
+ /**
+ * TripleDES (DES-EDE - 168 bit key derived from 192).
+ */
TRIPLE_DES (SymmetricKeyAlgorithmTags.TRIPLE_DES),
+
+ /**
+ * CAST5 (128 bit key, as per RFC2144).
+ */
CAST5 (SymmetricKeyAlgorithmTags.CAST5),
+
+ /**
+ * Blowfish (128 bit key, 16 rounds).
+ */
BLOWFISH (SymmetricKeyAlgorithmTags.BLOWFISH),
+
+ /**
+ * Reserved in RFC4880.
+ * SAFER-SK128 (13 rounds)
+ */
SAFER (SymmetricKeyAlgorithmTags.SAFER),
+
+ /**
+ * Reserved in RFC4880.
+ * Reserved for DES/SK
+ */
DES (SymmetricKeyAlgorithmTags.DES),
+
+ /**
+ * AES with 128-bit key.
+ */
AES_128 (SymmetricKeyAlgorithmTags.AES_128),
+
+ /**
+ * AES with 192-bit key.
+ */
AES_192 (SymmetricKeyAlgorithmTags.AES_192),
+
+ /**
+ * AES with 256-bit key.
+ */
AES_256 (SymmetricKeyAlgorithmTags.AES_256),
+
+ /**
+ * Twofish with 256-bit key.
+ */
TWOFISH (SymmetricKeyAlgorithmTags.TWOFISH),
+
+ /**
+ * Reserved for Camellia with 128-bit key.
+ */
CAMELLIA_128 (SymmetricKeyAlgorithmTags.CAMELLIA_128),
+
+ /**
+ * Reserved for Camellia with 192-bit key.
+ */
CAMELLIA_192 (SymmetricKeyAlgorithmTags.CAMELLIA_192),
+
+ /**
+ * Reserved for Camellia with 256-bit key.
+ */
CAMELLIA_256 (SymmetricKeyAlgorithmTags.CAMELLIA_256),
;
@@ -50,6 +110,13 @@ public enum SymmetricKeyAlgorithm {
}
}
+ /**
+ * Return the {@link SymmetricKeyAlgorithm} enum that corresponds to the provided numeric id.
+ * If an invalid id is provided, null is returned.
+ *
+ * @param id numeric algorithm id
+ * @return symmetric key algorithm enum
+ */
public static SymmetricKeyAlgorithm fromId(int id) {
return MAP.get(id);
}
@@ -60,6 +127,11 @@ public enum SymmetricKeyAlgorithm {
this.algorithmId = algorithmId;
}
+ /**
+ * Return the numeric algorithm id of the enum.
+ *
+ * @return numeric id
+ */
public int getAlgorithmId() {
return algorithmId;
}