22. Advanced material: Signatures on components¶

22.1. Certification recipes¶

Different signatures in OpenPGP serve various specific purposes. This section provides practical guidance on creating these signatures, illustrating each with concrete examples.

22.1.1. Change algorithm preferences¶

To modify the preferred symmetric, compression, hash, or AEAD algorithms for a key, the key owner needs to issue a direct key signature (type ID 0x1F) on the primary key.

This signature should have the following structure:

Subpacket	Area	Critical	Mandatory	Notes
Signature Creation Time	Hashed	True	True	Current time
Issuer Fingerprint	Hashed	True or False	Strongly Recommended	The primary key is the issuer
Key Flags	Hashed	True	False	Retain key flags from the previous self-signature
Features	Hashed	True	False	Retain features from the previous self-signature
Key Expiration Time	Hashed	True	False	Retain expiration time from the previous self-signature, if applicable
Hash Algorithm Preferences	Hashed	False	False	New preferences
Compression Algorithm Preferences	Hashed	False	False	New preferences
Symmetric Algorithm Preferences	Hashed	False	False	New preferences
AEAD Algorithm Preferences	Hashed	False	False	New preferences

22.1.2. Change expiration time¶

To adjust the expiration time of an OpenPGP certificate, a new DirectKey signature (type ID 0x1F) with a modified Key Expiration Time subpacket must be issued. The structure of this signature is identical to the one outlined in the previous section on changing algorithm preferences.

Additionally, the expiration time can be altered for individual User IDs (detailed below) or separate subkeys (see Section 8.2.1).

22.1.3. Add User ID¶

To bind a User ID to an OpenPGP certificate a certification signature (type ID 0x10-0x13) is used which should have the following structure:

Subpacket	Area	Critical	Mandatory	Notes
Signature Creation Time	Hashed	True	True	Current time
Issuer Fingerprint	Hashed	True or False	Strongly Recommended	The primary key is the issuer
Primary User ID	Hashed	True	False	Optional
Signature Expiration Time	Hashed	True	False	Optional

In addition to these subpackets, self-certifications for User IDs can include others – such as key flags, features, and algorithm preferences – as shown in the previous table. This enables the specification of unique capabilities and preferences for each identity associated with the certificate.

22.1.4. Remove or revoke a User ID¶

Since OpenPGP certificates are often distributed by the means of key servers, new signatures on a certificate are often “merged” into existing copies of the certificate locally by the recipient.

This integration process means it is practically impossible to directly remove signatures or User IDs from a certificate, as there is no way to communicate the intention of packet deletion to the recipient.

To effectively mark a User ID as invalid, the user can publish a copy of their certificate with a Certification Revocation signature (type ID 0x30) attached to the invalidated User ID. This signature signals that the specified User ID is no longer valid or associated with the certificate holder.

The structure of a Certification Revocation signature is as follows:

Subpacket	Area	Critical	Mandatory	Notes
Signature Creation Time	Hashed	True	True	Current time
Issuer Fingerprint	Hashed	True or False	Strongly Recommended	The primary key is the issuer
Reason for Revocation	Hashed	True	False	Determines soft or hard revocation

For User ID revocations, the Reason for Revocation subpacket is crucial. A value of 0 means no specific reason, leading to a hard revocation, while 32 indicates the User ID is no longer valid, resulting in a soft revocation. Omitting the reason subpacket is also equivalent to a hard revocation.

It is generally advisable to use reason code 32 for revoking User IDs.

22.1.5. Add a subkey¶

As part of life-cycle management, users may need to add a new subkey to their OpenPGP certificate, often for reasons such as upgrading to a subkey with more advanced cryptographic algorithms. The process involves creating a specific signature structure:

Subpacket	Area	Critical	Mandatory	Notes
Signature Creation Time	Hashed	True	True	Current time
Issuer Fingerprint	Hashed	True or False	Strongly Recommended	The primary key is the issuer
Key Flags	Hashed	True	Strongly Recommended	Determine the usage of the key
Key Expiration Time	Hashed	True	False	Specifies the expiration time of the subkey
Embedded Signature	Hashed	True	If Key Flags contains S	Signing subkeys require embedded Primary Key Binding signature
Hash Algorithm Preferences	Hashed	False	False	Per key preferences
Compression Algorithm Preferences	Hashed	False	False	Per key preferences
Symmetric Algorithm Preferences	Hashed	False	False	Per key preferences
AEAD Algorithm Preferences	Hashed	False	False	Per key preferences

In addition to these subpackets, users can specify algorithm preferences for each subkey, distinct from those set in the certificate’s Direct Key signature.

22.1.6. Revoke a subkey¶

Subkeys, like User IDs, can be individually revoked in OpenPGP. This is done by issuing a Subkey Revocation signature (type ID 0x28) using the primary key.

The structure of such a signature is straightforward:

Subpacket	Area	Critical	Mandatory	Notes
Signature Creation Time	Hashed	True	True	Current time
Issuer Fingerprint	Hashed	True or False	Strongly Recommended	The primary key is the issuer
Reason for Revocation	Hashed	True	False	Determines soft or hard revocation

In Subkey Revocation signatures, the reason for revocation subpacket can only have values in the range of 0-3. The values 1 (key superseded) and 3 (key retired and no longer used) indicate soft revocations, whereas values 0 (no reason) and 2 (key compromised) indicate hard revocations.

Note that a value of 32 is not applicable in these signatures.

22.1.7. Revoke a certificate¶

Users may find themselves needing to revoke their entire OpenPGP certificate, rendering it unusable. This could be for various reasons, such as migrating to a new certificate or in response to a compromise of the certificate’s secret key material.

While a soft-revoked certificate can be re-validated at a later time with a new certification, a hard revocation is permanent.

The recommended way to revoke a certificate is by issuing a Key Revocation signature (type ID 0x20). Its structure is similar to that of a Certification Revocation signature.

Subpacket	Area	Critical	Mandatory	Notes
Signature Creation Time	Hashed	True	True	Current time
Issuer Fingerprint	Hashed	True or False	Strongly Recommended	The primary key is the issuer
Reason for Revocation	Hashed	True	False	Determines soft or hard revocation

For Key Revocation signatures, the guidelines regarding the Reason for Revocation subpacket are the same as those for Subkey Revocation signatures.

22.1.8. Common subpackets in OpenPGP signatures¶

In OpenPGP, certain subpackets are universally expected across all types of signatures, serving fundamental roles in the signature’s structure, verification and validation:

Signature Creation Time: This is a mandatory subpacket in every OpenPGP signature. It contains the timestamp of when the signature was created. For security and integrity, this subpacket must be located in the hashed area of the signature and is recommended to be marked as critical.
Issuer Fingerprint: Essential for signature validation, this subpacket identifies the key (or subkey) that was used to create the signature. OpenPGP v6 signatures should include the Issuer Fingerprint subpacket, containing the 32-byte fingerprint of the key.

Note

The key used as the issuer in the signature might be a subkey of the certificate.

These subpackets can be placed in either the hashed or unhashed area due to its self-authenticating nature. However, we recommend including them in the signature’s hashed area.

22.2. Managing subpacket conflicts and duplication¶

In OpenPGP signatures, both the hashed and unhashed areas are composed of lists of subpackets. Inherently, this structure permits the duplication of the same subpacket, which could lead to conflicts. To manage these potential conflicts, the following strategies are used:

Precedence of hashed area: Subpackets within the hashed area of a signature take precedence over those in the unhashed area. This hierarchy helps resolve conflicts when the same subpacket appears in both areas.
Handling conflicts within the same area: Conflicts can still arise within the same area, such as when two subpackets have different expiration times. In such cases, the OpenPGP specification advises that implementations should favor the last occurrence of a conflicting subpacket in the hashed area.

In certain scenarios, having duplicate subpackets with conflicting content is logical and even necessary. For example, consider a signature created by a version 4 issuer key, which was upgraded from an older OpenPGP version (like v3). Since the key ID calculation scheme changed from v3 to v4, the identifiers for the same key would differ between these versions. Therefore, a v4 signature might contain two issuer key ID subpackets, each with different, yet correct values for v3 and v4 keys, respectively. This allows for backward compatibility and ensures the signature can be validated under both key ID calculation schemes.