#1747 Document Signature Subpacket classes

gefeili · gefeili · commit 7e59f96843aa · 2024-09-04T13:27:26.000+09:30
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/UserAttributeSubpacketTags.java b/pg/src/main/java/org/bouncycastle/bcpg/UserAttributeSubpacketTags.java
@@ -2,8 +2,16 @@
 
 /**
  * Basic PGP user attribute sub-packet tag types.
+ *
+ * @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.12">
+ *     RFC4880 - User Attribute Packet</a>
+ * @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-user-attribute-packet-type-">
+ *     RFC9580 - User Attribute Packet</a>
  */
 public interface UserAttributeSubpacketTags 
 {
+    /**
+     * Tag for an {@link org.bouncycastle.bcpg.attr.ImageAttribute}.
+     */
     int IMAGE_ATTRIBUTE = 1;
 }
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/UserDataPacket.java b/pg/src/main/java/org/bouncycastle/bcpg/UserDataPacket.java
@@ -1,5 +1,9 @@
 package org.bouncycastle.bcpg;
 
+/**
+ * Superclass for user identities ({@link UserIDPacket}, {@link UserAttributePacket}).
+ * The superclass is used to hold different user identity objects in the same collection.
+ */
 public interface UserDataPacket
 {
 
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.rfc-editor.org/rfc/rfc9580.html#name-the-image-attribute-subpack">
+ *     RFC9580 - 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.rfc-editor.org/rfc/rfc9580.html#name-embedded-signature">
+ *     RFC9580 - 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">
+ *     RFC4880 - Exportable Certification</a>
+ * @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-exportable-certification">
+ *     RFC9580 - 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.rfc-editor.org/rfc/rfc9580.html#name-features">
+ *     RFC9580 - 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.rfc-editor.org/rfc/rfc9580.html#name-intended-recipient-fingerpr">
+ *     RFC9580 - 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.rfc-editor.org/rfc/rfc9580.html#name-issuer-fingerprint">
+ *     RFC9580 - 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.rfc-editor.org/rfc/rfc9580.html#name-issuer-key-id">
+ *     RFC9580 - 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.rfc-editor.org/rfc/rfc9580.html#name-key-expiration-time">
+ *     RFC9580 - 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.rfc-editor.org/rfc/rfc9580.html#name-key-flags">
+ *     RFC9580 - 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.rfc-editor.org/rfc/rfc9580.html#name-notation-data">
+ *     RFC9580 - 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.rfc-editor.org/rfc/rfc9580.html#name-policy-uri">
+ *     RFC9580 - 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.rfc-editor.org/rfc/rfc9580.html#name-preferred-aead-ciphersuites">
+ *     OpenPGP - Preferred AEAD Ciphersuites</a>
+ */
 public class PreferredAEADCiphersuites
     extends PreferredAlgorithms
 {
@@ -13,8 +20,8 @@ public class PreferredAEADCiphersuites
     /**
      * AES-128 + OCB is a MUST implement and is therefore implicitly supported.
      *
-     * @see <a href="https://openpgp-wg.gitlab.io/rfc4880bis/#name-preferred-aead-ciphersuites">
-     * Crypto-Refresh § 5.2.3.15. Preferred AEAD Ciphersuites</a>
+     * @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html">
+     * OpenPGP - Preferred AEAD Ciphersuites</a>
      */
     private static final Combination AES_128_OCB = new Combination(SymmetricKeyAlgorithmTags.AES_128, AEADAlgorithmTags.OCB);
 
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://www.rfc-editor.org/rfc/rfc9580.html#name-preferred-symmetric-ciphers">
+ *     RFC9580 - Preferred Symmetric Ciphers for v1 SEIPD</a>
+ * @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-preferred-hash-algorithms">
+ *     RFC9580 - Preferred Hash Algorithms</a>
+ * @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-preferred-compression-algor">
+ *     RFC9580 - Preferred Compression Algorithms</a>
+ * @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.7">
+ *     RFC4880 - Preferred Symmetric Algorithms</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://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.9">
+ *     RFC4880 - 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.rfc-editor.org/rfc/rfc9580.html#name-primary-user-id">
+ *     RFC9580 - 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.rfc-editor.org/rfc/rfc9580.html#name-regular-expression">
+ *     RFC9580 - 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.rfc-editor.org/rfc/rfc9580.html#name-revocable">
+ *     RFC9580 - 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.rfc-editor.org/rfc/rfc9580.html#name-revocation-key">
+ *     RFC9580 - 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.rfc-editor.org/rfc/rfc9580.html#name-revocation-key">
+ *     RFC9580 - 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.rfc-editor.org/rfc/rfc9580.html#name-reason-for-revocation">
+ *     RFC9580 - 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.rfc-editor.org/rfc/rfc9580.html#name-reason-for-revocation">
+ *     RFC9580 - 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
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/sig/SignatureExpirationTime.java b/pg/src/main/java/org/bouncycastle/bcpg/sig/SignatureExpirationTime.java
diff --git a/pg/src/main/java/org/bouncycastle/bcpg/sig/SignatureTarget.java b/pg/src/main/java/org/bouncycastle/bcpg/sig/SignatureTarget.java
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

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,9 @@`
`1`	`1`	`package org.bouncycastle.bcpg;`
`2`	`2`
	`3`	`+/**`
	`4`	`+ * Superclass for user identities ({@link UserIDPacket}, {@link UserAttributePacket}).`
	`5`	`+ * The superclass is used to hold different user identity objects in the same collection.`
	`6`	`+ */`
`3`	`7`	`public interface UserDataPacket`
`4`	`8`	`{`
`5`	`9`