Document Signature Subpacket classes

vanitasvitae · vanitasvitae · commit 2df605e156c4 · 2024-08-08T12:37:19.000+02:00
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/attr/ImageAttribute.java b/pg/src/main/java/org/bouncycastle/bcpg/attr/ImageAttribute.java
@@ -7,7 +7,12 @@
 import org.bouncycastle.bcpg.UserAttributeSubpacketTags;
 
 /**
- * Basic type for a image attribute packet.
+ * User-Attribute Subpacket used to encode an image, e.g. the user's avatar.
+ *
+ * @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.12.1">
+ *     RFC4880 - Image Attribute Subpacket</a>
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-the-image-attribute-subpack">
+ *     C-R - Image Attribute Subpacket</a>
  */
 public class ImageAttribute 
     extends UserAttributeSubpacket
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/sig/EmbeddedSignature.java b/pg/src/main/java/org/bouncycastle/bcpg/sig/EmbeddedSignature.java
@@ -4,7 +4,15 @@
 import org.bouncycastle.bcpg.SignatureSubpacketTags;
 
 /**
- * Packet embedded signature
+ * Signature Subpacket for embedding one Signature into another.
+ * This packet is used e.g. for embedding a primary-key binding signature
+ * ({@link org.bouncycastle.openpgp.PGPSignature#PRIMARYKEY_BINDING}) into a subkey-binding signature
+ * ({@link org.bouncycastle.openpgp.PGPSignature#SUBKEY_BINDING}) for a signing-capable subkey.
+ *
+ * @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.26">
+ *     RFC4880 - Embedded Signature</a>
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-embedded-signature">
+ *     C-R: Embedded Signature</a>
  */
 public class EmbeddedSignature
     extends SignatureSubpacket
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/sig/Exportable.java b/pg/src/main/java/org/bouncycastle/bcpg/sig/Exportable.java
@@ -4,7 +4,13 @@
 import org.bouncycastle.bcpg.SignatureSubpacketTags;
 
 /**
- * packet giving signature creation time.
+ * Signature Subpacket for marking a signature as exportable or non-exportable.
+ * Non-exportable signatures are not intended to be published.
+ *
+ * @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.11">
+ *     Exportable Certification</a>
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-exportable-certification">
+ *     C-R - Exportable Certification</a>
  */
 public class Exportable 
     extends SignatureSubpacket
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/sig/Features.java b/pg/src/main/java/org/bouncycastle/bcpg/sig/Features.java
@@ -3,6 +3,14 @@
 import org.bouncycastle.bcpg.SignatureSubpacket;
 import org.bouncycastle.bcpg.SignatureSubpacketTags;
 
+/**
+ * Signature Subpacket encoding, which features are supported by the key-holders implementation.
+ *
+ * @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.24">
+ *     RFC4880 - Features</a>
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-features">
+ *     C-R - Features</a>
+ */
 public class Features
     extends SignatureSubpacket
 {
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/sig/IntendedRecipientFingerprint.java b/pg/src/main/java/org/bouncycastle/bcpg/sig/IntendedRecipientFingerprint.java
@@ -5,7 +5,11 @@
 import org.bouncycastle.util.Arrays;
 
 /**
- * packet giving the intended recipient fingerprint.
+ * Signature Subpacket containing the fingerprint of the intended recipients primary key.
+ * This packet can be used to prevent malicious forwarding/replay attacks.
+ *
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-intended-recipient-fingerpr">
+ *     C-R - Intended Recipient Fingerprint</a>
  */
 public class IntendedRecipientFingerprint
     extends SignatureSubpacket
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/sig/IssuerFingerprint.java b/pg/src/main/java/org/bouncycastle/bcpg/sig/IssuerFingerprint.java
@@ -7,7 +7,11 @@
 import org.bouncycastle.util.Arrays;
 
 /**
- * packet giving the issuer key fingerprint.
+ * Signature Subpacket containing the fingerprint of the issuers signing (sub-) key.
+ * This packet supersedes the {@link IssuerKeyID} subpacket.
+ *
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-issuer-fingerprint">
+ *     C-R - Issuer Fingerprint</a>
  */
 public class IssuerFingerprint
     extends SignatureSubpacket
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/sig/IssuerKeyID.java b/pg/src/main/java/org/bouncycastle/bcpg/sig/IssuerKeyID.java
@@ -5,7 +5,14 @@
 import org.bouncycastle.bcpg.SignatureSubpacketTags;
 
 /**
- * packet giving the issuer key ID.
+ * Signature Subpacket containing the key-id of the issuers signing (sub-) key.
+ * If the version of that key is greater than 4, this subpacket MUST NOT be included in the signature.
+ * For these keys, consider the {@link IssuerFingerprint} subpacket instead.
+ *
+ * @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.5">
+ *     RFC4880 - Issuer</a>
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-issuer-key-id">
+ *     C-R - Issuer Key ID</a>
  */
 public class IssuerKeyID 
     extends SignatureSubpacket
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/sig/KeyExpirationTime.java b/pg/src/main/java/org/bouncycastle/bcpg/sig/KeyExpirationTime.java
@@ -4,7 +4,13 @@
 import org.bouncycastle.bcpg.SignatureSubpacketTags;
 
 /**
- * packet giving time after creation at which the key expires.
+ * Signature Subpacket containing the number of seconds after the key's creation date, after which the key expires.
+ * The special value of {@code 0} means that the key never expires.
+ *
+ * @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.6">
+ *     RFC4880 - Key Expiration Time</a>
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-key-expiration-time">
+ *     C-R - Key Expiration Time</a>
  */
 public class KeyExpirationTime 
     extends SignatureSubpacket
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/sig/KeyFlags.java b/pg/src/main/java/org/bouncycastle/bcpg/sig/KeyFlags.java
@@ -4,17 +4,50 @@
 import org.bouncycastle.bcpg.SignatureSubpacketTags;
 
 /**
- * Packet holding the key flag values.
+ * Signature Subpacket encoding the capabilities / intended uses of a key.
+ *
+ * @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.21">
+ *     RFC4880 - Key Flags</a>
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-key-flags">
+ *     C-R - Key Flags</a>
  */
 public class KeyFlags 
     extends SignatureSubpacket
 {
+    /**
+     * This key may be used to make User ID certifications (signature type IDs 0x10-0x13)
+     * or direct key signatures (signature type ID 0x1F) over other peoples keys.
+     */
     public static final int CERTIFY_OTHER = 0x01;
+
+    /**
+     * This key may be used to sign data.
+     */
     public static final int SIGN_DATA = 0x02;
+
+    /**
+     * This key may be used to encrypt communications.
+     */
     public static final int ENCRYPT_COMMS = 0x04;
+
+    /**
+     * This key may be used to encrypt storage.
+     */
     public static final int ENCRYPT_STORAGE = 0x08;
+
+    /**
+     * The private component of this key may have been split by a secret-sharing mechanism.
+     */
     public static final int SPLIT = 0x10;
+
+    /**
+     * This key may be used for authentication.
+     */
     public static final int AUTHENTICATION = 0x20;
+
+    /**
+     * The private component of this key may be in the possession of more than one person.
+     */
     public static final int SHARED = 0x80;
     
     private static byte[] intToByteArray(
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/sig/NotationData.java b/pg/src/main/java/org/bouncycastle/bcpg/sig/NotationData.java
@@ -7,8 +7,13 @@
 import org.bouncycastle.util.Strings;
 
 /**
- * Class provided a NotationData object according to
- * RFC2440, Chapter 5.2.3.15. Notation Data
+ * Signature Subpacket encoding custom notations.
+ * Notations are key-value pairs.
+ *
+ * @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.16">
+ *     RFC4880 - Notation Data</a>
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-notation-data">
+ *     C-R - Notation Data</a>
  */
 public class NotationData
     extends SignatureSubpacket
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/sig/PolicyURI.java b/pg/src/main/java/org/bouncycastle/bcpg/sig/PolicyURI.java
@@ -5,6 +5,15 @@
 import org.bouncycastle.util.Arrays;
 import org.bouncycastle.util.Strings;
 
+/**
+ * Signature Subpacket for encoding a URI pointing to a document containing the policy under which the
+ * signature was created.
+ *
+ * @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.20">
+ *     RFC4880 - Policy URI</a>
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-policy-uri">
+ *     C-R - Policy URI</a>
+ */
 public class PolicyURI
     extends SignatureSubpacket
 {
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/sig/PreferredAEADCiphersuites.java b/pg/src/main/java/org/bouncycastle/bcpg/sig/PreferredAEADCiphersuites.java
@@ -4,6 +4,13 @@
 import org.bouncycastle.bcpg.SignatureSubpacketTags;
 import org.bouncycastle.bcpg.SymmetricKeyAlgorithmTags;
 
+/**
+ * Signature Subpacket containing the AEAD cipher suites (AEAD algorithm, Symmetric Key Algorithm pairs)
+ * preferred by the key holder's implementation.
+ *
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-preferred-aead-ciphersuites">
+ *     C-R - Preferred AEAD Ciphersuites</a>
+ */
 public class PreferredAEADCiphersuites
     extends PreferredAlgorithms
 {
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/sig/PreferredAlgorithms.java b/pg/src/main/java/org/bouncycastle/bcpg/sig/PreferredAlgorithms.java
@@ -3,7 +3,26 @@
 import org.bouncycastle.bcpg.SignatureSubpacket;
 
 /**
- * packet giving signature creation time.
+ * Signature Subpacket containing algorithm preferences of the key holder's implementation.
+ * This class is used to implement:
+ * <ul>
+ *     <li>Preferred Hash Algorithms</li>
+ *     <li>Preferred Symmetric Key Algorithms</li>
+ *     <li>Preferred Compression Algorithms</li>
+ * </ul>
+ *
+ * @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.7">
+ *     RFC4880 - Preferred Symmetric Algorithms</a>
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-preferred-symmetric-ciphers">
+ *     C-R - Preferred Symmetric Ciphers for v1 SEIPD</a>
+ * @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.8">
+ *     RFC4880 - Preferred Hash Algorithms</a>
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-preferred-hash-algorithms">
+ *     C-R - Preferred Hash Algorithms</a>
+ * @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.9">
+ *     RFC4880 - Preferred Compression Algorithms</a>
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-preferred-compression-algor">
+ *     C-R - Preferred Compression Algorithms</a>
  */
 public class PreferredAlgorithms 
     extends SignatureSubpacket
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/sig/PrimaryUserID.java b/pg/src/main/java/org/bouncycastle/bcpg/sig/PrimaryUserID.java
@@ -4,7 +4,12 @@
 import org.bouncycastle.bcpg.SignatureSubpacketTags;
 
 /**
- * packet giving whether or not the signature is signed using the primary user ID for the key.
+ * Signature Subpacket marking a User ID as primary.
+ *
+ * @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.19">
+ *     RFC4880 - Primary User ID</a>
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-primary-user-id">
+ *     C-R - Primary User ID</a>
  */
 public class PrimaryUserID 
     extends SignatureSubpacket
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/sig/RegularExpression.java b/pg/src/main/java/org/bouncycastle/bcpg/sig/RegularExpression.java
@@ -6,7 +6,13 @@
 import org.bouncycastle.util.Strings;
 
 /**
- * Regexp Packet - RFC 4880 5.2.3.14. Note: the RFC says the byte encoding is to be null terminated.
+ * Signature Subpacket containing a regular expression limiting the scope of the signature.
+ * Note: the RFC says the byte encoding is to be null terminated.
+ *
+ * @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.14">
+ *     RFC4880 - Regular Expression</a>
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-regular-expression">
+ *     C-R - Regular Expression</a>
  */
 public class RegularExpression
     extends SignatureSubpacket
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/sig/Revocable.java b/pg/src/main/java/org/bouncycastle/bcpg/sig/Revocable.java
@@ -4,7 +4,12 @@
 import org.bouncycastle.bcpg.SignatureSubpacketTags;
 
 /**
- * packet giving whether or not is revocable.
+ * Signature Subpacket marking a signature as non-revocable.
+ *
+ * @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.12">
+ *     RFC4880 - Revocable</a>
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-revocable">
+ *     C-R - Revocable</a>
  */
 public class Revocable 
     extends SignatureSubpacket
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/sig/RevocationKey.java b/pg/src/main/java/org/bouncycastle/bcpg/sig/RevocationKey.java
@@ -4,7 +4,14 @@
 import org.bouncycastle.bcpg.SignatureSubpacketTags;
 
 /**
- * Represents revocation key OpenPGP signature sub packet.
+ * Signature Subpacket containing the algorithm and fingerprint of a separate version 4 key which is allowed to issue
+ * revocation signatures for this key.
+ * This mechanism is deprecated.
+ *
+ * @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.15">
+ *     RFC4880 - Revocation Key</a>
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-revocation-key">
+ *     C-R - Revocation Key</a>
  */
 public class RevocationKey extends SignatureSubpacket
 {
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/sig/RevocationKeyTags.java b/pg/src/main/java/org/bouncycastle/bcpg/sig/RevocationKeyTags.java
@@ -1,8 +1,20 @@
 package org.bouncycastle.bcpg.sig;
 
+/**
+ * Revocation Key Class values.
+ *
+ * @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.15">
+ *     RFC4880 - Revocation Key</a>
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-revocation-key">
+ *     C-R - Revocation Key</a>
+ */
 public interface RevocationKeyTags
 {
     byte CLASS_DEFAULT = (byte)0x80;
+
+    /**
+     * The revocation information is sensitive.
+     */
     byte CLASS_SENSITIVE = (byte)0x40;
 
 }
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/sig/RevocationReason.java b/pg/src/main/java/org/bouncycastle/bcpg/sig/RevocationReason.java
@@ -5,7 +5,12 @@
 import org.bouncycastle.util.Strings;
 
 /**
- * Represents revocation reason OpenPGP signature sub packet.
+ * Signature Subpacket for encoding the reason why a key was revoked.
+ *
+ * @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.23">
+ *     RFC4880 - Reason for Revocation</a>
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-reason-for-revocation">
+ *     C-R - Reason for Revocation</a>
  */
 public class RevocationReason extends SignatureSubpacket
 {
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/sig/RevocationReasonTags.java b/pg/src/main/java/org/bouncycastle/bcpg/sig/RevocationReasonTags.java
@@ -1,5 +1,13 @@
 package org.bouncycastle.bcpg.sig;
 
+/**
+ * Revocation reason tags.
+ *
+ * @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.23">
+ *     RFC4880 - Reason for Revocation</a>
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-reason-for-revocation">
+ *     C-R - Reason for Revocation</a>
+ */
 public interface RevocationReasonTags
 {
     byte NO_REASON = 0;              // No reason specified (key revocations or cert revocations)
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/sig/SignatureCreationTime.java b/pg/src/main/java/org/bouncycastle/bcpg/sig/SignatureCreationTime.java
@@ -6,7 +6,12 @@
 import org.bouncycastle.bcpg.SignatureSubpacketTags;
 
 /**
- * packet giving signature creation time.
+ * Signature Subpacket containing the time at which the signature was created.
+ *
+ * @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.4">
+ *     RFC4880 - Signature Creation Time</a>
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-signature-creation-time">
+ *     C-R - Signature Creation Time</a>
  */
 public class SignatureCreationTime 
     extends SignatureSubpacket
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/sig/SignatureExpirationTime.java b/pg/src/main/java/org/bouncycastle/bcpg/sig/SignatureExpirationTime.java
@@ -4,7 +4,13 @@
 import org.bouncycastle.bcpg.SignatureSubpacketTags;
 
 /**
- * packet giving signature expiration time.
+ * Signature Subpacket containing the number of seconds after the signatures creation
+ * time after which the signature expires.
+ *
+ * @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.10">
+ *     RFC4880 - Signature Expiration Time</a>
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-signature-expiration-time">
+ *     C-R - Signature Expiration Time</a>
  */
 public class SignatureExpirationTime 
     extends SignatureSubpacket
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/sig/SignatureTarget.java b/pg/src/main/java/org/bouncycastle/bcpg/sig/SignatureTarget.java
@@ -5,7 +5,12 @@
 import org.bouncycastle.util.Arrays;
 
 /**
- * RFC 4880, Section 5.2.3.25 - Signature Target subpacket.
+ * Signature Subpacket containing the hash value of another signature to which this signature applies to.
+ *
+ * @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.25">
+ *     RFC4880 - Signature Target</a>
+ * @see <a href="https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-13.html#name-signature-target">
+ *     C-R - Signature Target</a>
  */
 public class SignatureTarget
     extends SignatureSubpacket
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/sig/SignerUserID.java b/pg/src/main/java/org/bouncycastle/bcpg/sig/SignerUserID.java
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/sig/TrustSignature.java b/pg/src/main/java/org/bouncycastle/bcpg/sig/TrustSignature.java
