Skip to content

Commit 7e59f96

Browse files
author
gefeili
committed
#1747 Document Signature Subpacket classes
2 parents d9e2c2e + 176731e commit 7e59f96

27 files changed

+230
-23
lines changed

‎pg/src/main/java/org/bouncycastle/bcpg/UserAttributeSubpacketTags.java

+8
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,16 @@
22

33
/**
44
* Basic PGP user attribute sub-packet tag types.
5+
*
6+
* @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.12">
7+
* RFC4880 - User Attribute Packet</a>
8+
* @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-user-attribute-packet-type-">
9+
* RFC9580 - User Attribute Packet</a>
510
*/
611
public interface UserAttributeSubpacketTags
712
{
13+
/**
14+
* Tag for an {@link org.bouncycastle.bcpg.attr.ImageAttribute}.
15+
*/
816
int IMAGE_ATTRIBUTE = 1;
917
}

‎pg/src/main/java/org/bouncycastle/bcpg/UserDataPacket.java

+4
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
package org.bouncycastle.bcpg;
22

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+
*/
37
public interface UserDataPacket
48
{
59

‎pg/src/main/java/org/bouncycastle/bcpg/attr/ImageAttribute.java

+6-1
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,12 @@
77
import org.bouncycastle.bcpg.UserAttributeSubpacketTags;
88

99
/**
10-
* Basic type for a image attribute packet.
10+
* User-Attribute Subpacket used to encode an image, e.g. the user's avatar.
11+
*
12+
* @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.12.1">
13+
* RFC4880 - Image Attribute Subpacket</a>
14+
* @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-the-image-attribute-subpack">
15+
* RFC9580 - Image Attribute Subpacket</a>
1116
*/
1217
public class ImageAttribute
1318
extends UserAttributeSubpacket

‎pg/src/main/java/org/bouncycastle/bcpg/sig/EmbeddedSignature.java

+9-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,15 @@
44
import org.bouncycastle.bcpg.SignatureSubpacketTags;
55

66
/**
7-
* Packet embedded signature
7+
* Signature Subpacket for embedding one Signature into another.
8+
* This packet is used e.g. for embedding a primary-key binding signature
9+
* ({@link org.bouncycastle.openpgp.PGPSignature#PRIMARYKEY_BINDING}) into a subkey-binding signature
10+
* ({@link org.bouncycastle.openpgp.PGPSignature#SUBKEY_BINDING}) for a signing-capable subkey.
11+
*
12+
* @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.26">
13+
* RFC4880 - Embedded Signature</a>
14+
* @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-embedded-signature">
15+
* RFC9580 - Embedded Signature</a>
816
*/
917
public class EmbeddedSignature
1018
extends SignatureSubpacket

‎pg/src/main/java/org/bouncycastle/bcpg/sig/Exportable.java

+7-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,13 @@
44
import org.bouncycastle.bcpg.SignatureSubpacketTags;
55

66
/**
7-
* packet giving signature creation time.
7+
* Signature Subpacket for marking a signature as exportable or non-exportable.
8+
* Non-exportable signatures are not intended to be published.
9+
*
10+
* @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.11">
11+
* RFC4880 - Exportable Certification</a>
12+
* @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-exportable-certification">
13+
* RFC9580 - Exportable Certification</a>
814
*/
915
public class Exportable
1016
extends SignatureSubpacket

‎pg/src/main/java/org/bouncycastle/bcpg/sig/Features.java

+8
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,14 @@
33
import org.bouncycastle.bcpg.SignatureSubpacket;
44
import org.bouncycastle.bcpg.SignatureSubpacketTags;
55

6+
/**
7+
* Signature Subpacket encoding, which features are supported by the key-holders implementation.
8+
*
9+
* @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.24">
10+
* RFC4880 - Features</a>
11+
* @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-features">
12+
* RFC9580 - Features</a>
13+
*/
614
public class Features
715
extends SignatureSubpacket
816
{

‎pg/src/main/java/org/bouncycastle/bcpg/sig/IntendedRecipientFingerprint.java

+5-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,11 @@
55
import org.bouncycastle.util.Arrays;
66

77
/**
8-
* packet giving the intended recipient fingerprint.
8+
* Signature Subpacket containing the fingerprint of the intended recipients primary key.
9+
* This packet can be used to prevent malicious forwarding/replay attacks.
10+
*
11+
* @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-intended-recipient-fingerpr">
12+
* RFC9580 - Intended Recipient Fingerprint</a>
913
*/
1014
public class IntendedRecipientFingerprint
1115
extends SignatureSubpacket

‎pg/src/main/java/org/bouncycastle/bcpg/sig/IssuerFingerprint.java

+5-1
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,11 @@
77
import org.bouncycastle.util.Arrays;
88

99
/**
10-
* packet giving the issuer key fingerprint.
10+
* Signature Subpacket containing the fingerprint of the issuers signing (sub-) key.
11+
* This packet supersedes the {@link IssuerKeyID} subpacket.
12+
*
13+
* @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-issuer-fingerprint">
14+
* RFC9580 - Issuer Fingerprint</a>
1115
*/
1216
public class IssuerFingerprint
1317
extends SignatureSubpacket

‎pg/src/main/java/org/bouncycastle/bcpg/sig/IssuerKeyID.java

+8-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,14 @@
55
import org.bouncycastle.bcpg.SignatureSubpacketTags;
66

77
/**
8-
* packet giving the issuer key ID.
8+
* Signature Subpacket containing the key-id of the issuers signing (sub-) key.
9+
* If the version of that key is greater than 4, this subpacket MUST NOT be included in the signature.
10+
* For these keys, consider the {@link IssuerFingerprint} subpacket instead.
11+
*
12+
* @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.5">
13+
* RFC4880 - Issuer</a>
14+
* @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-issuer-key-id">
15+
* RFC9580 - Issuer Key ID</a>
916
*/
1017
public class IssuerKeyID
1118
extends SignatureSubpacket

‎pg/src/main/java/org/bouncycastle/bcpg/sig/KeyExpirationTime.java

+7-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,13 @@
44
import org.bouncycastle.bcpg.SignatureSubpacketTags;
55

66
/**
7-
* packet giving time after creation at which the key expires.
7+
* Signature Subpacket containing the number of seconds after the key's creation date, after which the key expires.
8+
* The special value of {@code 0} means that the key never expires.
9+
*
10+
* @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.6">
11+
* RFC4880 - Key Expiration Time</a>
12+
* @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-key-expiration-time">
13+
* RFC9580 - Key Expiration Time</a>
814
*/
915
public class KeyExpirationTime
1016
extends SignatureSubpacket

‎pg/src/main/java/org/bouncycastle/bcpg/sig/KeyFlags.java

+34-1
Original file line numberDiff line numberDiff line change
@@ -4,17 +4,50 @@
44
import org.bouncycastle.bcpg.SignatureSubpacketTags;
55

66
/**
7-
* Packet holding the key flag values.
7+
* Signature Subpacket encoding the capabilities / intended uses of a key.
8+
*
9+
* @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.21">
10+
* RFC4880 - Key Flags</a>
11+
* @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-key-flags">
12+
* RFC9580 - Key Flags</a>
813
*/
914
public class KeyFlags
1015
extends SignatureSubpacket
1116
{
17+
/**
18+
* This key may be used to make User ID certifications (signature type IDs 0x10-0x13)
19+
* or direct key signatures (signature type ID 0x1F) over other peoples keys.
20+
*/
1221
public static final int CERTIFY_OTHER = 0x01;
22+
23+
/**
24+
* This key may be used to sign data.
25+
*/
1326
public static final int SIGN_DATA = 0x02;
27+
28+
/**
29+
* This key may be used to encrypt communications.
30+
*/
1431
public static final int ENCRYPT_COMMS = 0x04;
32+
33+
/**
34+
* This key may be used to encrypt storage.
35+
*/
1536
public static final int ENCRYPT_STORAGE = 0x08;
37+
38+
/**
39+
* The private component of this key may have been split by a secret-sharing mechanism.
40+
*/
1641
public static final int SPLIT = 0x10;
42+
43+
/**
44+
* This key may be used for authentication.
45+
*/
1746
public static final int AUTHENTICATION = 0x20;
47+
48+
/**
49+
* The private component of this key may be in the possession of more than one person.
50+
*/
1851
public static final int SHARED = 0x80;
1952

2053
private static byte[] intToByteArray(

‎pg/src/main/java/org/bouncycastle/bcpg/sig/NotationData.java

+7-2
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,13 @@
77
import org.bouncycastle.util.Strings;
88

99
/**
10-
* Class provided a NotationData object according to
11-
* RFC2440, Chapter 5.2.3.15. Notation Data
10+
* Signature Subpacket encoding custom notations.
11+
* Notations are key-value pairs.
12+
*
13+
* @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.16">
14+
* RFC4880 - Notation Data</a>
15+
* @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-notation-data">
16+
* RFC9580 - Notation Data</a>
1217
*/
1318
public class NotationData
1419
extends SignatureSubpacket

‎pg/src/main/java/org/bouncycastle/bcpg/sig/PolicyURI.java

+9
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,15 @@
55
import org.bouncycastle.util.Arrays;
66
import org.bouncycastle.util.Strings;
77

8+
/**
9+
* Signature Subpacket for encoding a URI pointing to a document containing the policy under which the
10+
* signature was created.
11+
*
12+
* @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.20">
13+
* RFC4880 - Policy URI</a>
14+
* @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-policy-uri">
15+
* RFC9580 - Policy URI</a>
16+
*/
817
public class PolicyURI
918
extends SignatureSubpacket
1019
{

‎pg/src/main/java/org/bouncycastle/bcpg/sig/PreferredAEADCiphersuites.java

+9-2
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,13 @@
44
import org.bouncycastle.bcpg.SignatureSubpacketTags;
55
import org.bouncycastle.bcpg.SymmetricKeyAlgorithmTags;
66

7+
/**
8+
* Signature Subpacket containing the AEAD cipher suites (AEAD algorithm, Symmetric Key Algorithm pairs)
9+
* preferred by the key holder's implementation.
10+
*
11+
* @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-preferred-aead-ciphersuites">
12+
* OpenPGP - Preferred AEAD Ciphersuites</a>
13+
*/
714
public class PreferredAEADCiphersuites
815
extends PreferredAlgorithms
916
{
@@ -13,8 +20,8 @@ public class PreferredAEADCiphersuites
1320
/**
1421
* AES-128 + OCB is a MUST implement and is therefore implicitly supported.
1522
*
16-
* @see <a href="https://openpgp-wg.gitlab.io/rfc4880bis/#name-preferred-aead-ciphersuites">
17-
* Crypto-Refresh § 5.2.3.15. Preferred AEAD Ciphersuites</a>
23+
* @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html">
24+
* OpenPGP - Preferred AEAD Ciphersuites</a>
1825
*/
1926
private static final Combination AES_128_OCB = new Combination(SymmetricKeyAlgorithmTags.AES_128, AEADAlgorithmTags.OCB);
2027

‎pg/src/main/java/org/bouncycastle/bcpg/sig/PreferredAlgorithms.java

+20-1
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,26 @@
33
import org.bouncycastle.bcpg.SignatureSubpacket;
44

55
/**
6-
* packet giving signature creation time.
6+
* Signature Subpacket containing algorithm preferences of the key holder's implementation.
7+
* This class is used to implement:
8+
* <ul>
9+
* <li>Preferred Hash Algorithms</li>
10+
* <li>Preferred Symmetric Key Algorithms</li>
11+
* <li>Preferred Compression Algorithms</li>
12+
* </ul>
13+
*
14+
* @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-preferred-symmetric-ciphers">
15+
* RFC9580 - Preferred Symmetric Ciphers for v1 SEIPD</a>
16+
* @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-preferred-hash-algorithms">
17+
* RFC9580 - Preferred Hash Algorithms</a>
18+
* @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-preferred-compression-algor">
19+
* RFC9580 - Preferred Compression Algorithms</a>
20+
* @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.7">
21+
* RFC4880 - Preferred Symmetric Algorithms</a>
22+
* @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.8">
23+
* RFC4880 - Preferred Hash Algorithms</a>
24+
* @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.9">
25+
* RFC4880 - Preferred Compression Algorithms</a>
726
*/
827
public class PreferredAlgorithms
928
extends SignatureSubpacket

‎pg/src/main/java/org/bouncycastle/bcpg/sig/PrimaryUserID.java

+6-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,12 @@
44
import org.bouncycastle.bcpg.SignatureSubpacketTags;
55

66
/**
7-
* packet giving whether or not the signature is signed using the primary user ID for the key.
7+
* Signature Subpacket marking a User ID as primary.
8+
*
9+
* @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.19">
10+
* RFC4880 - Primary User ID</a>
11+
* @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-primary-user-id">
12+
* RFC9580 - Primary User ID</a>
813
*/
914
public class PrimaryUserID
1015
extends SignatureSubpacket

‎pg/src/main/java/org/bouncycastle/bcpg/sig/RegularExpression.java

+7-1
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,13 @@
66
import org.bouncycastle.util.Strings;
77

88
/**
9-
* Regexp Packet - RFC 4880 5.2.3.14. Note: the RFC says the byte encoding is to be null terminated.
9+
* Signature Subpacket containing a regular expression limiting the scope of the signature.
10+
* Note: the RFC says the byte encoding is to be null terminated.
11+
*
12+
* @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.14">
13+
* RFC4880 - Regular Expression</a>
14+
* @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-regular-expression">
15+
* RFC9580 - Regular Expression</a>
1016
*/
1117
public class RegularExpression
1218
extends SignatureSubpacket

‎pg/src/main/java/org/bouncycastle/bcpg/sig/Revocable.java

+6-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,12 @@
44
import org.bouncycastle.bcpg.SignatureSubpacketTags;
55

66
/**
7-
* packet giving whether or not is revocable.
7+
* Signature Subpacket marking a signature as non-revocable.
8+
*
9+
* @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.12">
10+
* RFC4880 - Revocable</a>
11+
* @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-revocable">
12+
* RFC9580 - Revocable</a>
813
*/
914
public class Revocable
1015
extends SignatureSubpacket

‎pg/src/main/java/org/bouncycastle/bcpg/sig/RevocationKey.java

+8-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,14 @@
44
import org.bouncycastle.bcpg.SignatureSubpacketTags;
55

66
/**
7-
* Represents revocation key OpenPGP signature sub packet.
7+
* Signature Subpacket containing the algorithm and fingerprint of a separate version 4 key which is allowed to issue
8+
* revocation signatures for this key.
9+
* This mechanism is deprecated.
10+
*
11+
* @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.15">
12+
* RFC4880 - Revocation Key</a>
13+
* @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-revocation-key">
14+
* RFC9580 - Revocation Key</a>
815
*/
916
public class RevocationKey extends SignatureSubpacket
1017
{

‎pg/src/main/java/org/bouncycastle/bcpg/sig/RevocationKeyTags.java

+12
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,20 @@
11
package org.bouncycastle.bcpg.sig;
22

3+
/**
4+
* Revocation Key Class values.
5+
*
6+
* @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.15">
7+
* RFC4880 - Revocation Key</a>
8+
* @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-revocation-key">
9+
* RFC9580 - Revocation Key</a>
10+
*/
311
public interface RevocationKeyTags
412
{
513
byte CLASS_DEFAULT = (byte)0x80;
14+
15+
/**
16+
* The revocation information is sensitive.
17+
*/
618
byte CLASS_SENSITIVE = (byte)0x40;
719

820
}

‎pg/src/main/java/org/bouncycastle/bcpg/sig/RevocationReason.java

+6-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,12 @@
55
import org.bouncycastle.util.Strings;
66

77
/**
8-
* Represents revocation reason OpenPGP signature sub packet.
8+
* Signature Subpacket for encoding the reason why a key was revoked.
9+
*
10+
* @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.23">
11+
* RFC4880 - Reason for Revocation</a>
12+
* @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-reason-for-revocation">
13+
* RFC9580 - Reason for Revocation</a>
914
*/
1015
public class RevocationReason extends SignatureSubpacket
1116
{

‎pg/src/main/java/org/bouncycastle/bcpg/sig/RevocationReasonTags.java

+8
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,13 @@
11
package org.bouncycastle.bcpg.sig;
22

3+
/**
4+
* Revocation reason tags.
5+
*
6+
* @see <a href="https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.23">
7+
* RFC4880 - Reason for Revocation</a>
8+
* @see <a href="https://www.rfc-editor.org/rfc/rfc9580.html#name-reason-for-revocation">
9+
* RFC9580 - Reason for Revocation</a>
10+
*/
311
public interface RevocationReasonTags
412
{
513
byte NO_REASON = 0; // No reason specified (key revocations or cert revocations)

0 commit comments

Comments
 (0)