diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index a65fb4e..58bd40a 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -276,91 +276,87 @@ To reverse a previously issued third-party signature, the issuer can generate a ## Advanced topics -### Certification Recipes +### Certification recipes -As mentioned above, different signatures are used for different purposes. -In this section, we will try to give guidance on how to create certain signatures by example. +Different signatures in OpenPGP serve various specific purposes. This section provides practical guidance on creating these signatures, illustrating each with concrete examples. -#### Change Algorithm Preferences +#### 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 `0x1F`) on the primary key. -In order to change what symmetric, compression, hash or AEAD algorithms are preferred by the key owner, they can issue a direct-key signature (type 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 | Carry over key flags from previous self-signature | -| Features | Hashed | True | False | Carry over features from previous self-signature | -| Key Expiration Time | Hashed | True | False | Carry over expiration time from previous self-signature, if present | -| Hash Alg. Pref. | Hashed | False | False | New preferences | -| Comp. Alg. Pref. | Hashed | False | False | New preferences | -| Symm. Alg. Pref. | Hashed | False | False | New preferences | -| AEAD Alg. Pref. | Hashed | False | False | New preferences | +| Subpacket | Area | Critical | Mandatory | Notes | +|---------------------------------|--------|----------------|-------------------|---------------------------| +| Signature Creation Time | Hashed | True | True | Should be the current time| +| Issuer Fingerprint | Hashed | True or False | Strongly Recommended | Identifies the primary key as 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 | If applicable, use expiration time from the previous self-signature | +| 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 | -#### Change Expiration Time +#### Change expiration time -The recommended way to change the expiration time of a certificate is by issuing a new `DirectKey` signature (type 0x1F) with an adjusted Key Expiration Time subpacket. -The structure of such a signature is the same as in the section above. -It is also possible to change the expiration date of individual User IDs (see section below) or separate subkeys (see {numref}`bind_subkey`). +To adjust the expiration time of an OpenPGP certificate, issue a new `DirectKey` signature (type `0x1F`) with a modified Key Expiration Time subpacket. The structure of this signature is identical to the one outlined in the previous section on changing algorithm preferences. + +Additionally, the expiration date can be altered for individual User IDs (detailed below) or separate subkeys (see {numref}`bind_subkey`). #### Add User ID -A signature that binds a User ID to a certificate should have the following structure: +To bind a User ID to an OpenPGP certificate, the 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 | -| Primary User ID | Hashed | True | False | Optional | -| Signature Expiration Time | Hashed | True | False | Optional | +| Subpacket | Area | Critical | Mandatory | Notes | +|-------------------------|--------|----------------|-------------------|---------------------------------------| +| Signature Creation Time | Hashed | True | True | Current time | +| Issuer Fingerprint | Hashed | True or False | Strongly Recommended | Identifies the primary key as the issuer | +| Primary User ID | Hashed | True | False | Optional | +| Signature Expiration Time | Hashed | True | False | Optional | -Self-certifications over User IDs can optionally carry the same subpackets as listed in the previous table (key flags, features, algorithm preferences). -This way, separate capabilities can be assigned to different identities. -#### Remove / Revoke User ID +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. + +#### 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 means, that it is not really possible to remove signatures / User IDs from a certificate, as there is no way to communicate the intention of packet deletion to 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. -So to mark a User ID as invalid, the user can publish a copy of their certificate with a `CertificationRevocation` (signature type 0x30) attached to the invalidated User ID. -This signature signals that the holder of the certificate no longer wants to be associated with that User ID. +To effectively mark a User ID as invalid, the user can publish a copy of their certificate with a *CertificationRevocation* signature(type `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 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 | Decides over soft / hard revocation | +| Subpacket | Area | Critical | Mandatory | Notes | +|---------------------|--------|----------------|-------------------|---------------------------------------------| +| Signature Creation Time | Hashed | True | True | Should be the current time | +| Issuer Fingerprint | Hashed | True or False | Strongly Recommended | Indicates the primary key as the issuer | +| Reason for Revocation | Hashed | True | False | Determines the nature of the revocation | -For User ID revocations, the value of the reason subpacket can either be `0` (no reason specified) or `32`, signaling that the User ID is no longer valid. -The latter would result in a soft revocation, while a reason code of `0` is considered a hard revocation. -Omitting the reason packet altogether is also equivalent to a hard revocation. -It is recommended to issue User ID revocations using a reason code `32`. +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. (binding_subkeys)= -#### Add a Subkey +#### Add a subkey -A user might want to add a new subkey to their certificate, for example to replace an old subkey with one that uses a newer cryptographic algorithm. +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: -The structure 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 | +| Key Flags | Hashed | True | Strongly Recommended | Determine the usage of the key | +| Key Expiration Time | Hashed | True | False | Specifies the expiration date 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 | -| 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 date of the subkey | -| Embedded Signature | Hashed | True | If Key Flags contains **S** | Signing subkeys require embedded `PrimaryKeyBinding` signature | -| Hash Alg. Pref. | Hashed | False | False | Per key preferences | -| Comp. Alg. Pref. | Hashed | False | False | Per key preferences | -| Symm. Alg. Pref. | Hashed | False | False | Per key preferences | -| AEAD Alg. Pref. | 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 *DirectKey* signature. -Optional algorithm preference subpackets can be used to signal per-subkey preferences that deviate from those set in the certificates `DirectKey` signature. - -#### Revoke a Subkey +#### Revoke a subkey Analogous to User IDs, subkeys can be revoked individually. This is done by issuing a `SubkeyRevocation` signature (type 0x28) using the primary key.