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