vanitasvitae/openpgp-notes
1
0
Fork 0
mirror of https://codeberg.org/openpgp/notes.git synced 2024-11-27 01:52:06 +01:00
Code Issues Projects Releases Packages Wiki Activity

Merge pull request 'tammi-ch8' (#145) from tammi-ch8 into draft

Browse source 
Reviewed-on: https://codeberg.org/openpgp/notes/pulls/145
This commit is contained in:
heiko 2023-11-25 22:13:57 +00:00
commit a7abea94ee
1 changed files with 208 additions and 238 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

416
book/source/08-signing_components.md
View file

@ -6,33 +6,33 @@ SPDX-License-Identifier: CC-BY-SA-4.0
(component_signatures_chapter)= (component_signatures_chapter)=
# Signatures on components # Signatures on components
In this chapter, we'll look at OpenPGP signatures that apply to components of certificates. That is, signatures that apply to: This chapter examines OpenPGP signatures associated with certificate components, applying to:
- Component keys (primary keys or subkeys) and - component keys, encompassing primary keys and subkeys
- Identity components (User IDs or User attributes). - identity components, namely User IDs and User attributes
Signatures on components are used to construct and maintain certificates, and to model the authentication of identities. Signatures on components are used to construct and maintain certificates, and to model the authentication of identities.
This chapter expands on topics we introduced in the {ref}`certificates_chapter` chapter. This chapter expands on topics introduced in the {ref}`certificates_chapter` chapter.
## Self-signatures vs third-party signatures ## Self-signatures vs third-party signatures
There are two fundamentally different flavors of signatures on components: Component signatures in OpenPGP are categorized into two distinct types:
- *Self-signatures*, which are issued by the certificate holder themselves using the primary key of the certificate, and - **self-signatures**, which are issued by the certificate holder using the certificate's primary key
- *third-party signatures*, which are issued by a third party. - **third-party signatures**, which are issued by an external entity, not the certificate holder
### Self-signatures ### Self-signatures
*Self-signatures* on components are a crucial mechanism for forming OpenPGP certificates (by binding the certificate's components into one combined data structure), as well as for life-cycle management of certificates (that is: performing changes to the certificate, over time). Self-signatures are fundamental in creating and managing OpenPGP certificates. They bind the various components of a certificate into one combined data structure and facilitate the certificate's life-cycle management.
Life-cycle management operations on OpenPGP certificates and their components include: Life-cycle management operations include:
- binding additional components to a certificate, - binding additional components to a certificate
- changing the expiration date, or other metadata, of a component, and - modifying expiration dates or other metadata of components
- invalidating components or existing self-signatures using revocations. - revoking, and thus invalidating, components or existing self-signatures
Self-signatures are issued by the certificate's owner, using the primary key of the same certificate. Self-signatures are issued by the certificate's owner using the certificate's primary key.
```{note} ```{note}
No [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags) is required to issue self-signatures. An OpenPGP primary key can issue self-signatures by default. No [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags) is required to issue self-signatures. An OpenPGP primary key can issue self-signatures by default.
@ -40,65 +40,55 @@ No [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-
### Third-party signatures ### Third-party signatures
Third-party signatures on components form the basis for OpenPGP's decentralized authentication functionality (also known as the *Web of Trust*). They encode authentication-related statements about certificates and their associated identities. Third-party signatures are pivotal in OpenPGP for decentralized authentication, forming the basis of the Web of Trust. They encode authentication-related statements about certificates and linked identities, establishing trustworthiness and verification.
Third-party OpenPGP signatures can be used to make the following types of statements: Third-party signatures are used to make specific statements:
- Certification of identity claims, - certifying identity claims
- Delegation of authentication decisions, - delegating authentication decisions
- Invalidating previous third-party signature statements using revocations. - revoking, and thus invalidating, prior third-party signature statements
```{note} ```{note}
The **certify others** [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags) (`0x01`) is required to issue third-party signatures. Only the primary key of a certificate may hold this key flag. The **certify others** [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags) (`0x01`) is required to issue third-party signatures. Only the certificate's primary can hold this key flag.
``` ```
### Self-signatures and third-party signatures convey different meanings ### Distinct functions of self-signatures and third-party signatures
The meaning of a signature depends in part on who issued it. A self-signature performs a different function than the same type of signature issued by a third party. The meaning of an OpenPGP signature depends significantly on its issuer. Self-signatures and third-party signatures, even when of the same type, serve distinct functions. For example:
For example: - Certifying self-signatures (type IDs `0x10` - `0x13`) bind a User ID to a certificate.
- Third-party signatures of the same type IDs endorse the authenticity of a User ID.
- Certifying self-signatures (type IDs `0x10` - `0x13`) are used to bind a User ID to a certificate, while In another instance:
- third-party signatures of the same type IDs indicate that the signer endorses the authenticity of a User ID.
Or: - *When issued as a self-signature*, a [direct key signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-direct-key-signature-type-i) sets preferences and advertises features applicable to the entire certificate.
- *When issued by a third party*, especially when it carries a [trust signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-trust-signature) subpacket, a similar direct key signature delegates trust to the signed certificate. This designates the signed certificate as a trust root within the issuer's Web of Trust.
- A [direct key signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-direct-key-signature-type-i) issued as a self-signature can be used to set preferences and advertise features that apply to the whole certificate, while ## Self-signatures in certificate formation and management
- a similar [direct key signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-direct-key-signature-type-i) issued by a third party delegates trust to the signed certificate, when it carries a [trust signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-trust-signature) subpacket. The issuer thereby configures the signed certificate as a trust root in the *Web of Trust*, for themselves.
## Self-signatures: Forming certificates and life-cycle management Self-signatures play a crucial role in forming and managing the structure of OpenPGP certificates. These act as *binding signatures*, joining components and embedding metadata.
The components in an OpenPGP certificate are bound together using signatures. These *binding signatures* join the components together, while also adding metadata to them. Internally, an OpenPGP certificate is essentially a series of packets strung sequentially. When a certificate is stored in a file format known as a [transferable public key](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-transferable-public-keys), packets can be easily added or removed.
Internally, an OpenPGP certificate consists of a sequence of OpenPGP packets. These packets are just strung together, one after the other. When a certificate is stored in a file[^tpk], it's easy to remove some of these packets, or add new ones. To safeguard against unauthorized additions, OpenPGP uses cryptographic signatures. These validate that any additions, such as subkeys or [identity components](identity_components), were made by the owner of the OpenPGP certificate using its primary key. While anyone can still store unrelated elements to a certificate dataset, OpenPGP implementations will reject them if they lack a valid cryptographic connection with the certificate.
[^tpk]: When stored in a file, OpenPGP certificates are in a format called [transferable public key](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-transferable-public-keys).
However, the owner of a certificate doesn't want a third party to add subkeys or [identity components](identity_components) to their certificate, pretending that the certificate owner put those components there.
To prevent malicious addition of components, OpenPGP uses cryptographic signatures. These signatures show that components have been added by the owner of the OpenPGP certificate. They are issued by the primary key of the certificate.
So while anyone can still unilaterally store unrelated subkeys and [identity components](identity_components) in an OpenPGP certificate dataset, OpenPGP implementations that load a certificate can (and usually should) discard components that don't have a valid cryptographic connection with the certificate.
```{note} ```{note}
Conversely, it's easy for a third party to leave out packets, while handling an OpenPGP certificate dataset. An attacker can, for example, simply choose to omit revocation packets. The recipient of such a partial copy has no way to notice this omission, without access to a different source for the certificate that contains the revocation packet. Conversely, omissions of packets by third parties can easily occur when handling an OpenPGP certificate dataset. This could pose a challenge, for example, when an attacker deliberately omits revocation packets. Without access to an alternative, complete certificate source, recipients might not detect these omissions.
``` ```
Note that there are some cases where third parties legitimately add "unbound" packets (that is: packets that are not signed by the certificate's owner) to a certificate: However, there are legitimate instances in which third parties add "unbound" packets (i.e., not signed by the certificate's owner) to a certificate:
- [Third-party certifications](third_party_cert) are traditionally stored as part of the packet data of the certificate that they make a statement about (in systems that unconditionally accept and include such certifications, this can cause problems[^flooding]), - [Third-party certifications](third_party_cert) are often stored within the packet data of the certificate to which they are related. This is a standard practice that provides convenience for users by allowing easy access to all relevant certifications. (See {ref}`cert-flooding` for discussion of a related pitfall.)
- OpenPGP software may add [unbound identity data](unbound_user_ids), locally. - OpenPGP software may locally add [unbound identity data](unbound_user_ids) to a certificate.
[^flooding]: Storing third-party identity certifications in the target OpenPGP certificate is convenient for consumers: it is easy to find all relevant certifications in one central location. However, when third parties can unilaterally add certifications, this opens an avenue for denial-of-service attacks by flooding. The SKS network of OpenPGP key servers [allowed and experienced this problem](https://dkg.fifthhorseman.net/blog/openpgp-certificate-flooding.html).
(bind_subkey)= (bind_subkey)=
### Binding subkeys to a certificate ### Binding subkeys to a certificate
Subkeys is linked to an OpenPGP certificate using a [subkey binding signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-subkey-binding) (type ID `0x18`). This signature type effectively signals that the "primary key wants to be associated with the subkey". Subkeys are linked to OpenPGP certificates via a [subkey binding signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-subkey-binding) (type ID `0x18`). This signature type indicates the association of the primary key with the subkey.
A subkey binding signature binds a subkey to a primary key, and adds metadata in the signature packet. Once generated, the subkey binding signature packet is stored in the certificate, directly following the subkey it binds. A subkey binding signature binds a subkey to a primary key, and it embeds metadata into the signature packet. Once generated, the subkey binding signature packet is stored in the certificate directly after the subkey it binds.
(Note that subkeys that have the *signing* [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags) are a special case, and are handled slightly differently. See {numref}`bind_subkey_sign`.) Subkeys designated for signing purposes, identified by the *signing* [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags), represent a unique category and are handled differently. See {numref}`bind_subkey_sign`.
```{figure} diag/subkey_binding_signature.png ```{figure} diag/subkey_binding_signature.png
:name: fig-subkey-binding-signature :name: fig-subkey-binding-signature
@ -107,26 +97,25 @@ A subkey binding signature binds a subkey to a primary key, and adds metadata in
Linking an OpenPGP subkey to the primary key with a binding signature Linking an OpenPGP subkey to the primary key with a binding signature
``` ```
To specify metadata for the subkey, such as the [*key expiration time*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#key-expiration-subpacket), or the capabilities that are set using [*key flags*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#key-flags), subpackets are included in the subkey binding signature packet. Metadata for the subkey, such as the [*key expiration time*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#key-expiration-subpacket) and capabilities set by [*key flags*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#key-flags), are included in subpackets within the subkey binding signature packet.
```{note} ```{note}
The validity of a subkey is bounded by that of the primary key, meaning that an expired primary key causes the subkey to be invalid, no matter the subkey expiration time. The validity of a subkey is intrinsically linked to that of the primary key. An expired primary key renders any associated subkey invalid, regardless of the subkey's own expiration setting.
It's legal for a subkey to not have an explicit expiry time. In that case, its expiration date is implicitly the same as the expiration date of the primary key. Legally, a subkey may not have a specified expiry time. In such cases, its expiration aligns implicitly with that of the primary key. Additionally, the creation date of a subkey must always be more recent than that of the primary key.
A subkey cannot be "older" than the primary key. The value of the subkeys creation date MUST be greater than that of the primary key.
``` ```
(bind_subkey_sign)= (bind_subkey_sign)=
### Special case: Binding signing subkeys to a certificate ### Special case: Binding signing subkeys
To bind subkeys with the "signing" key flag to a certificate is a special case. For the most part, it works the same as binding other types of subkeys, but there is one additional requirement: Binding subkeys that possess the *signing* key flag to a certificate represents a unique scenario. While similar to the binding process of other subkeys, there is an additional, critical requirement: mutual association.
To bind a signing-capable subkey to a primary key, it is not sufficient that the "primary key wants to be associated with the subkey." In addition, the subkey must signal that it "wants to be associated with that primary key." That is, to bind a signing-capable subkey to a primary key, it is insufficient that the "primary key wants to be associated with the subkey." The subkey must explicitly signal that it "wants to be associated with the primary key."
Otherwise, Alice could "adopt" Bob's signing subkey and convincingly claim that she made signatures that were in fact issued by Bob. This mutual binding is crucial for security. Without it, an individual (e.g., Alice) could falsely claim a connection to another person's (e.g., Bob's) signing subkey. To prevent such scenarios, where an attacker might wrongfully "adopt" a victim's signing subkey, a dual-layer of signatures is used:
This is to prevent an attack where the attacker "adopts" the victims signing subkey as their own in order to claim ownership over documents which were in fact signed by the victim.
In contrast to the [subkey binding signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-subkey-binding) (type ID `0x18`), which is issued by the certificate's primary key, the [primary key binding signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#sigtype-primary-binding) (type ID `0x19`) is instead created by the subkey (informally also called an embedded "back signature"). - the [subkey binding signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-subkey-binding) (type ID `0x18`), which is issued by the certificate's primary key
- the [primary key binding signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#sigtype-primary-binding) (type ID `0x19`), created by the subkey itself. This is informally known as an embedded "back signature," because the subkey's signature points back to the primary key.
```{figure} diag/subkey_binding_signatur_for_signing_sk.png ```{figure} diag/subkey_binding_signatur_for_signing_sk.png
:name: fig-subkey-binding-signature-for-signing-subkeys :name: fig-subkey-binding-signature-for-signing-subkeys
@ -135,22 +124,18 @@ In contrast to the [subkey binding signature](https://www.ietf.org/archive/id/dr
Linking an OpenPGP signing subkey to the primary key with a binding signature, and an embedded primary key binding signature Linking an OpenPGP signing subkey to the primary key with a binding signature, and an embedded primary key binding signature
``` ```
The additional [*primary key binding*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#sigtype-primary-binding) signature (type 0x19) is informally called a "back signature" (because the subkey uses the signature to point "back" to the primary key). The back signature signifies the mutuality of the subkey's association with the primary key and is embedded as subpacket data within the subkey binding signature, reinforcing the authenticity of the binding.
The *primary key binding signature* is "embedded" as subpacket data in the *subkey binding signature* which connects the signing subkey to the primary key.
(bind_ident)= (bind_ident)=
### Binding identities to a certificate ### Binding identities to a certificate
Another use-case for a self-signature is to link an identity component (such as a User ID that specifies a name and email address) to a certificate. Self-signatures also play a vital role in binding identity components, such as User IDs or User Attributes, to an OpenPGP certificate.
User ID components are bound to an OpenPGP certificate by issuing a certifying self-signature. "User Attributes" work analogously. Take for instance, the User ID `Alice Adams <alice@example.org>`. To link this User ID to her OpenPGP certificate (`AAA1 8CBB 2546 85C5 8358 3205 63FD 37B6 7F33 00F9 FB0E C457 378C D29F 1026 98B3`), Alice would use a cryptographic signature.
For example, the User ID `Alice Adams <alice@example.org>` may be associated with Alice's certificate `AAA1 8CBB 2546 85C5 8358 3205 63FD 37B6 7F33 00F9 FB0E C457 378C D29F 1026 98B3`. There are four types of *certifying self-signature*. The most commonly used type for binding User IDs is the [positive certification](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-positive-cert) (type ID `0x13`). Alternatively, types `0x10`, `0x11` or `0x12` might be used. This binding signature must be issued by the primary key.
Alice can link a User ID to her OpenPGP certificate with a cryptographic signature. To link a User ID, a *certifying self-signature* is created. There are four variant certifying self-signature types. Usually the signature type [positive certification](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-positive-cert) (type ID `0x13`) is used to bind User IDs to one's certificate (sometimes, type ID `0x10`, `0x11` or `0x12` may be used instead). This binding signature must be issued by the primary key. The certifying self-signature packet – calculated over the primary key, User ID, and metadata of the signature packet – is then added to the certificate, directly following the User ID packet.
The resulting certifying self-signature packet is stored as part of the certificate, directly following the User ID packet.
```{figure} diag/user_id_certification.png ```{figure} diag/user_id_certification.png
:name: fig-user-id-certification :name: fig-user-id-certification
@ -159,301 +144,286 @@ The resulting certifying self-signature packet is stored as part of the certific
Linking a User ID to an OpenPGP certificate Linking a User ID to an OpenPGP certificate
``` ```
This signature is calculated over the primary key, User ID and the metadata of the signature packet.
(primary-metadata)= (primary-metadata)=
### Adding metadata to the primary key/certificate ### Adding metadata to the primary key/certificate
The signatures that bind subkeys and identity components to a certificate serve two different purposes: Linking components to the certificate and adding metadata to a component. The signatures that bind subkeys and identity components to a certificate serve dual purposes: linking components to the certificate and adding metadata to components.
The primary key in a certificate doesn't need to be linked to the certificate. It acts as the anchor for linking, itself and thus doesn't require being linked. However, there is nevertheless a need to associate metadata with the primary key, which typically applies to the certificate as a whole. Unlike these components, the primary key of a certificate doesn't require a linking signature since it serves as the central anchor of the certificate. However, associating metadata with the primary key is still essential, as it generally applies to the entire certificate.
There are two mechanisms for adding metadata to the primary key: Metadata can be added to the primary key via two mechanisms:
- Via a direct key signature on the primary key, or - direct key signature on the primary key
- via a "primary User ID" binding signature. - *primary User ID* binding signature
Relevant metadata for the primary key that is defined the above mechanisms includes: The types of metadata typically associated with the primary key through these methods include:
- Key expiration, - key expiration
- key flags, - key flags
- algorithm preference signaling. - algorithm preference signaling
(direct_key_signature)= (direct_key_signature)=
#### Direct key signature #### Direct key signature
A [*direct key signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-direct-key-signature-type-i) is one mechanism to store information about the primary key, and about the entire certificate. A [*direct key signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-direct-key-signature-type-i) serves as a key mechanism for storing information about the primary key and the entire certificate.
In OpenPGP v6, a direct key signature is the [preferred mechanism](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-5.2.3.10-9). In OpenPGP v6, a direct key signature is the [preferred mechanism](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-5.2.3.10-9).
#### Primary User ID binding self-signature #### Self-signature binding to primary User ID
In a certificate, one User ID serves as the [*primary* User ID](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-primary-user-id). The metadata in the binding self-signature on this User ID applies to the primary key of the certificate. In an OpenPGP certificate, one User ID serves as the [*primary* User ID](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-primary-user-id). The metadata in the binding self-signature on this User ID applies to the certificate's primary key.
(self-revocations)= (self-revocations)=
### Revocation self-signatures: Invalidating components of a certificate ### Revocation self-signatures: Invalidating certificate components
One important class of self-signatures are revocations. Revocation self-signatures represent an important class of self-signatures, used primarily to invalidate components or retract prior signature statements.
A revocation signature is used to invalidate a component, or retract the statement formed by a prior signature. There are several types of revocation signatures, each serving a specific purpose:
- A [*key revocation signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-revocation-signature-ty) (type ID `0x20`) marks a primary key as revoked. - A [**key revocation signature**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-revocation-signature-ty) (type ID `0x20`) marks a primary key as revoked.
- a [*subkey revocation signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-subkey-revocation-signature) (type ID `0x28`) revokes a prior subkey binding signature, while - A [**subkey revocation signature**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-subkey-revocation-signature) (type ID `0x28`) revokes a prior subkey binding signature.
- a [*certification revocation*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-certification-revocation-si) (type ID `0x30`) revokes a certification signature. - A [**certification revocation**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-certification-revocation-si) (type ID `0x30`) revokes a certification signature.
Typical use-cases for revocations are marking certificates or individual subkeys as unusable (for example, when the private key has been compromised or superseded), or marking User IDs as no longer used. Common scenarios for using revocations include marking certificates or individual subkeys as unusable (e.g., when the private key has been compromised or replaced) or declaring User IDs as no longer valid.
```{note} ```{note}
OpenPGP certificates act as append-only data structures, in practice. Elements of a certiciate can not be removed from the copies on key servers and the OpenPGP systems of third parties, once published. Implementations usually merge all available components and signatures. OpenPGP certificates act as append-only data structures in practice. Once elements of a certificate are published, they cannot be removed from key servers or third-party OpenPGP systems. Implementations usually merge all available components and signatures.
Revocations are used as a mechanism to mark components or signatures as invalid. Revocations are used to mark components or signatures as invalid.
``` ```
Note: certification signatures [can be made irrevocable](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-revocable). Note: certification signatures [can be made irrevocable](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-revocable).
#### Hard vs. soft revocations #### Hard vs soft revocations
A revocation signature can contain a subpacket indicating the [*reason for revocation*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-reason-for-revocation). The value of this subpacket contains a code that specifies why the revocation was issued. This code determines whether the revocation is considered a *soft revocation* or a *hard revocation*: Revocation signatures often include a [*Reason for Revocation* subpacket](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-reason-for-revocation), with a code specifying why the revocation was issued. This code determines whether the revocation is considered *soft* or *hard*.
- A *soft revocation* is typically used for graceful or planned invalidation. Soft revocation of a component invalidates it from the revocation signature's creation time onwards. Uses of the component before the revocation time remain intact. Soft revocations can be reverted by re-validating the invalidated component with a new self-signature. - **Soft revocation**: This is typically used for graceful or planned invalidation of components, such as retiring or updating components. It invalidates the component from the revocation signature's creation time, but earlier uses remain valid. Soft revocations can be reversed with a new self-signature.
- A *hard revocation*, by contrast, invalidates the component retroactively, rendering all past and future uses invalid. Hard revocation of a component cannot be undone by re-validating the component. - **Hard revocation**: This irrevocably invalidates the component, affecting all past and future uses. It is typically used to signal compromise of secret key material.
Soft revocations are typically used when a certificate, subkey or User ID is retired or superseded gracefully, while hard revocations are typically used to signal compromise of secret key material.
```{note} ```{note}
A revocation signature that has no *reason for revocation* subpacket is interpreted as a hard revocation. A revocation signature lacking a *Reason for Revocation* subpacket is interpreted as a hard revocation.
``` ```
(third_party_cert)= (third_party_cert)=
## Third-party signatures: Authentication statements ## Authentication and delegation in third-party signatures
Signatures on components by third parties mainly encode authentication of identities and delegations of trust decisions. Third-party signatures in OpenPGP primarily encode authentication statements for identities and delegate trust decisions. These signatures can be manually inspected or processed as machine-readable artifacts by OpenPGP software, which evaluates the authenticity of certificates based on user-specified trust roots.
Third party signatures can be inspected and reasoned about manually by humans. More powerfully, though, they can also be used as machine-readable artifacts, by OpenPGP software, which can reason about the authenticity of certificates on behalf of its users, based on trust roots that the user has specified.
### Certifying identity components ### Certifying identity components
By issuing a certifying signature on an identity, the signer expresses that he has verified that the identity and the certificate are meaningfully linked. The signer vouches for the connection between the certificate and the identity. When a signer issues a certifying signature on an identity, it indicates a verified link between the identity and the certificate. That is, the signer vouches for the connection.
If Alice is certain that the identity `Bob Baker <bob@example.com>` controls the certificate `0xB0B`, she can create a certification signature that binds Bob's User ID and Bob's certificate. Bob will usually distribute this certifying signature from Alice as part of his certificate. For example, Alice can vouch that Bob's User ID `Bob Baker <bob@example.com>` is legitimately linked with his certificate `BB28 9FB7 A68D BFA8 C384 CCCD E205 8E02 D9C6 CD2F 3C7C 56AE 7FB5 3D97 1170 BA83`, by creating a certification signature. Bob can then distribute Alice's certifying signature as part of his certificate.
Effectively, this is a way for Alice to broadcast the statement "I, Alice, have checked that `Bob Baker <bob@example.com>` controls the certificate `0xB0B`." Other users may or may not decide to rely on this statement by Alice. Other users may or may not decide to rely on Alice's statement.
### Delegating authentication: Trust signatures ### Trust signatures: delegating authentication
The OpenPGP standard specifies primitives to delegate authentication decisions to certificates. The standard uses the (somewhat confusing) term "trust" for this mechanism. Delegating authentication decisions to a certificate, using a [*trust signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#trust-signature-subpacket) subpacket, makes the target certificate a "trusted introducer." OpenPGP uses [*trust signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#trust-signature-subpacket) subpackets to delegate authentication decisions, designating the recipient certificate as a "trusted introducer" (or a trust root) for the user. This includes specifying trust depth (or level) for transitive delegations and quantifying trust with numerical values, indicating the extent of reliance on the introducer's certifications.
A "trusted introducer" acts as a trust root for the user. Trust signature subpackets are applicable in:
[*Trust signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#trust-signature-subpacket) subpackets can be used in two types of signatures: - identity certification signatures (type ID `0x10` - `0x13`)
- [direct key signatures](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-direct-key-signature-type-i) (type ID `0x1F`)
- On an identity certification signature (type ID `0x10` - `0x13`), or on a #### Trust depth/level
- [*direct key signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-direct-key-signature-type-i) (type ID `0x1F`)
#### Trust depth (or "level") The "trust depth" (or level) in OpenPGP signifies the extent of transitive delegation within the authentication process. It determines how far a delegation can be extended from the original trusted introducer to subsequent intermediaries. Essentially, a certificate with a trust depth of more than one acts as a "meta-introducer," facilitating authentication decisions across multiple levels in the network.
OpenPGP's delegation mechanism allows specifying transitive delegation of trust: delegating authentication decisions across more than one hop. The standard refers to certificates as a "meta-introducer," when a "trust signature" subpacket defines it as a trusted introducer with a depth (or "level") of two or more. A trust depth of 1 means relying on certifications made directly by the trusted introducer. The user's OpenPGP software will accept certifications made directly by the introducer for authenticating identities.
A trust signature subpacket with means that the target certificate may delegate to a second, intermediate, introducer, which in turn has issued a certification signature for an identity. However, when the trust depth is set higher, it implies a chain of delegation extending beyond the initial introducer. The user's software will recognize and accept certifications made not only by the primary introducer but also by other intermediaries whom the primary introducer designated as trusted introducers.
**Examples** This allows for a more extensive network of trusted certifications, enabling a broader and more interconnected Web of Trust.
```{admonition} VISUAL
:class: warning
Illustrate with diagram(s). Notes for diagrams:
When Alice delegates trust decisions to Trent, designating Trent as a trusted introducer with a *trust depth* of 1, then Alice's OpenPGP implementation will only accept direct certifications by Trent. For example, Trent may have certified that Bob's certificate with the fingerprint `0xB0B` is legitimately connected to Bob's User ID `Bob <bob@example.org>`. If Alice tries to communicate with Bob using his identity `Bob <bob@example.org>`, then Alice's OpenPGP software can automatically determine that the certificate `0xB0B` is appropriate to use. When Alice delegates trust decisions to Trent, designating Trent as a trusted introducer with a *trust depth* of 1, then Alice's OpenPGP implementation will only accept direct certifications by Trent. For example, Trent may have certified that Bob's certificate with the fingerprint `0xB0B` is legitimately connected to Bob's User ID `Bob <bob@example.org>`. If Alice tries to communicate with Bob using his identity `Bob <bob@example.org>`, then Alice's OpenPGP software can automatically determine that the certificate `0xB0B` is appropriate to use.
However, Alice's OpenPGP software wouldn't accept a series of delegations from Trent via Tristan to a certification of Carol's identity (let's imagine that Trent has designated Tristan a trusted introducer). For Alice's OpenPGP software to accept such a path, she needs to designate Trent as a trusted introducer with the `level` set to 2 or more. However, Alice's OpenPGP software wouldn't accept a series of delegations from Trent via Tristan to a certification of Carol's identity (let's imagine that Trent has designated Tristan a trusted introducer). For Alice's OpenPGP software to accept such a path, she needs to designate Trent as a trusted introducer with the `level` set to 2 or more.
```
#### Trust amounts
The "trust amount," with a numerical value ranging from 0 to 255, quantifies the degree of reliance on a delegation.
A higher value indicates greater degree of reliance. This quantification aids OpenPGP software in determining an aggregate amount of reliance, based on combined certifications from multiple trusted introducers.
```{admonition} VISUAL ```{admonition} VISUAL
:class: warning :class: warning
add diagrams? Illustrate with diagram(s). Notes for diagrams:
```
#### Trust amount
A trust signature can quantify the degree to which the issuer wants to rely on a delegation. This "trust amount" has a numerical value between 0 and 255.
A trust amount of 120 indicates "complete trust," which means that a certification by that trusted introducer is considered sufficient to consider authentications by that introducer as sufficient.
**Examples**
If Alice designates Trent as a trusted introducer at a trust amount of 120, then Alice's OpenPGP software will consider Bob's identity fully authenticated if Trent has certified it. If Alice designates Trent as a trusted introducer at a trust amount of 120, then Alice's OpenPGP software will consider Bob's identity fully authenticated if Trent has certified it.
However, if Alice only assigns a trust amount of 60 (which indicates "partial trust") to Trent, then her software would not consider Bob's identity fully authenticated. Now let's imagine that Alice additionally assigns a trust amount of 60 to Tristan (a second, independent introducer), and Tristan also certified Bob's identity. In this case, Alice's OpenPGP software will consider Bob's identity fully authenticated, based on the combination of both delegations, and the certifications the two trusted introducers issued. However, if Alice only assigns a trust amount of 60 (which indicates "partial trust") to Trent, then her software would not consider Bob's identity fully authenticated. Now let's imagine that Alice additionally assigns a trust amount of 60 to Tristan (a second, independent introducer), and Tristan also certified Bob's identity. In this case, Alice's OpenPGP software will consider Bob's identity fully authenticated, based on the combination of both delegations, and the certifications the two trusted introducers issued.
```{admonition} VISUAL
:class: warning
add diagrams?
``` ```
#### Limiting the scope of delegations with regular expressions #### Limiting delegation scope
When using *trust signature* subpackets, a delegation can be limited to identities that match a [*regular expression*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#regex-subpacket), for example, to limit the email address in a User ID to a specific domain name. When using *trust signature* subpackets, a delegation can be limited to identities that match a [*regular expression*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#regex-subpacket).
With this mechanism, it is possible to delegate authentication decisions only for User IDs that match the email domain of an organization. With this mechanism, for example, it is possible to delegate authentication decisions only for User IDs that match the email domain of an organization.
**Example**
For example, Alice could delegate trust decisions only for email addresses in the domain `bob.com` to Bob, if she considers Bob to be a reasonable source of identity certifications for that domain.
```{admonition} VISUAL ```{admonition} VISUAL
:class: warning :class: warning
add diagrams? Illustrate with diagram(s). Notes for diagrams:
For example, Alice could delegate trust decisions only for email addresses in the domain `bob.com` to Bob, if she considers Bob to be a reasonable source of identity certifications for that domain.
``` ```
(wot)= (wot)=
### Decentralized automated trust decisions; or, the "Web of Trust" ### Web of Trust: Decentralized trust decisions
The OpenPGP, the "Web of Trust" is a trust model that performs authentication decisions on a set of certifications and delegations. The Web of Trust in OpenPGP is a trust model that facilitates authentication decisions through a network of certifications and delegations. It is characterized by a so-called [strong set](https://en.wikipedia.org/wiki/Web_of_trust#Strong_set), which refers to a group of certificates that are robustly interconnected via third-party certifications.
The OpenPGP "Web of Trust" model assumes that every user makes their own choice about who they delegate authentication decisions to. Based on the available certificates and third-party signatures, the user's OpenPGP software uses the Web of Trust mechanism to determine which certificates are considered reliable for an identity. In this model, users independently delegate authentication decisions, choosing whose certification to rely on. This delegation is based on the certificates and third-party signatures available to them, with their OpenPGP software applying the Web of Trust mechanism to discern the reliability of each certificate for an identity.
The OpenPGP RFC doesn't specify how exactly Web of Trust calculations are performed. It only defines the data formats that these calculations can be performed on. See external resources in {numref}`wot-resources`. The OpenPGP RFC doesn't specify exactly how Web of Trust calculations are performed. It only defines the data formats on which these calculations can be performed. See external resources in {numref}`wot-resources`.
### Revoking third-party signatures: Undoing previous statements ### Revoking third-party signatures
The issuer of a third-party signature can undo such a signature by issuing a [*certification revocation signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-certification-revocation-si) (type ID `0x30`). To reverse a previously issued third-party signature, the issuer can generate a [*certification revocation signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-certification-revocation-si) (type ID `0x30`). The revocation must be issued by the same key that created the original signature or, in deprecated practice, by a designated Revocation Key.
## Advanced topics ## Advanced topics
### Certification Recipes ### Certification recipes
As mentioned above, different signatures are used for different purposes. Different signatures in OpenPGP serve various specific purposes. This section provides practical guidance on creating these signatures, illustrating each with concrete examples.
In this section, we will try to give guidance on how to create certain signatures by example.
#### 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: This signature should have the following structure:
| Subpacket | Area | Critical | Mandatory | Notes | | Subpacket | Area | Critical | Mandatory | Notes |
|-----------|------|----------|-----------|-------| |---------------------------------|--------|----------------|-------------------|----------------------------------------------------|
| Signature Creation Time | Hashed | True | True | Current time | | Signature Creation Time | Hashed | True | True | Current time |
| Issuer Fingerprint | Hashed | True or false | Strongly recommended | The primary key is the issuer | | 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 | | Key Flags | Hashed | True | False | Retain key flags from the previous self-signature |
| Features | Hashed | True | False | Carry over features from previous self-signature | | Features | Hashed | True | False | Retain features from the previous self-signature |
| Key Expiration Time | Hashed | True | False | Carry over expiration time from previous self-signature, if present | | Key Expiration Time | Hashed | True | False | Retain expiration time from the previous self-signature, if applicable |
| Hash Alg. Pref. | Hashed | False | False | New preferences | | Hash Algorithm Preferences | Hashed | False | False | New preferences |
| Comp. Alg. Pref. | Hashed | False | False | New preferences | | Compression Algorithm Preferences | Hashed | False | False | New preferences |
| Symm. Alg. Pref. | Hashed | False | False | New preferences | | Symmetric Algorithm Preferences | Hashed | False | False | New preferences |
| AEAD Alg. Pref. | 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. 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.
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`). Additionally, the expiration date can be altered for individual User IDs (detailed below) or separate subkeys (see {numref}`bind_subkey`).
#### Add User ID #### 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 | | Subpacket | Area | Critical | Mandatory | Notes |
|-----------|------|----------|-----------|-------| |-------------------------|--------|----------------|-------------------|-------------------------------------------------|
| Signature Creation Time | Hashed | True | True | Current time | | Signature Creation Time | Hashed | True | True | Current time |
| Issuer Fingerprint | Hashed | True or false | Strongly Recommended | The primary key is the issuer | | Issuer Fingerprint | Hashed | True or False | Strongly Recommended | The primary key is the issuer |
| Primary User ID | Hashed | True | False | Optional | | Primary User ID | Hashed | True | False | Optional |
| Signature Expiration Time | 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). 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.
This way, separate capabilities can be assigned to different identities.
#### Remove / Revoke User ID #### 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. 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.
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.
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. 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.
This signature signals that the holder of the certificate no longer wants to be associated with that User ID.
The structure of a certification revocation is as follows: The structure of a *CertificationRevocation* is as follows:
| Subpacket | Area | Critical | Mandatory | Notes | | Subpacket | Area | Critical | Mandatory | Notes |
|-----------|------|----------|-----------|-------| |-------------------------|--------|----------------|-------------------|-------------------------------------------------|
| Signature Creation Time | Hashed | True | True | Current time | | Signature Creation Time | Hashed | True | True | Current time |
| Issuer Fingerprint | Hashed | True or false | Strongly Recommended | The primary key is the issuer | | 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 | | Reason for Revocation | Hashed | True | False | Determines soft or hard 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. 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.
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 generally advisable to use reason code `32` for revoking User IDs.
It is recommended to issue User ID revocations using a reason code `32`.
(binding_subkeys)= (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 | | Subpacket | Area | Critical | Mandatory | Notes |
|-----------|------|----------|-----------|-------| |-------------------------------|--------|----------------|-------------------|-----------------------------------------------------|
| Signature Creation Time | Hashed | True | True | Current time | | Signature Creation Time | Hashed | True | True | Current time |
| Issuer Fingerprint | Hashed | True or false | Strongly Recommended | The primary key is the issuer | | 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 Flags | Hashed | True | Strongly Recommended | Determine the usage of the key |
| Key Expiration Time | Hashed | True | False | Specifies the expiration date of the subkey | | 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 | | Embedded Signature | Hashed | True | If Key Flags contains **S** | Signing subkeys require embedded *Primary Key Binding* signature |
| Hash Alg. Pref. | Hashed | False | False | Per key preferences | | Hash Algorithm Preferences | Hashed | False | False | Per key preferences |
| Comp. Alg. Pref. | Hashed | False | False | Per key preferences | | Compression Algorithm Preferences | Hashed | False | False | Per key preferences |
| Symm. Alg. Pref. | Hashed | False | False | Per key preferences | | Symmetric Algorithm Preferences | Hashed | False | False | Per key preferences |
| AEAD Alg. Pref. | Hashed | False | False | Per key preferences | | AEAD Algorithm Preferences | Hashed | False | False | Per key preferences |
Optional algorithm preference subpackets can be used to signal per-subkey preferences that deviate from those set in the certificates `DirectKey` signature. In addition to these subpackets, users can specify algorithm preferences for each subkey, distinct from those set in the certificate's *DirectKey* signature.
#### Revoke a Subkey #### Revoke a subkey
Analogous to User IDs, subkeys can be revoked individually. Subkeys, like User IDs, can be individually revoked in OpenPGP.
This is done by issuing a `SubkeyRevocation` signature (type 0x28) using the primary key. This is done by issuing a `SubkeyRevocation` signature (type `0x28`) using the primary key.
The structure of such a signature is rather minimal:
The structure of such a signature is straightforward:
| Subpacket | Area | Critical | Mandatory | Notes | | Subpacket | Area | Critical | Mandatory | Notes |
|-----------|------|----------|-----------|-------| |-------------------------|--------|----------------|-------------------|-------------------------------------------------|
| Signature Creation Time | Hashed | True | True | Current time | | Signature Creation Time | Hashed | True | True | Current time |
| Issuer Fingerprint | Hashed | True or false | Strongly Recommended | The primary key is the issuer | | 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 | | Reason for Revocation | Hashed | True | False | Determines soft or hard revocation |
In `SubkeyRevocation` signatures, the [reason subpacket](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-reason-for-revocation) cannot have value `32`, but instead may be from the range of `0-3`.
Values `1` (key superseded) and `3` (key retired and no longer used) are soft reasons, while `0` (no reason) and `2` (key compromised) are considered hard.
#### Revoke a Certificate In `SubkeyRevocation` signatures, the [reason for revocation](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-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.
A user might want to revoke their entire certificate, rendering it unusable. Note that a value of `32` is not applicable in these signatures.
Depending on the circumstances, they might either want to revoke it softly, e.g. in case of migration to a new certificate, or they want to issue a hard revocation, e.g. in case of secret key material compromise. A soft-revoked certificate can be re-validated at a later point in time, by issuing a new certification, while a hard revocation is typically permanent. #### Revoke a certificate
The recommended way to revoke a certificate is by issuing a `KeyRevocation` signature (type 0x20). 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.
The structure of a key revocation signature is similar to that of a `CertificationRevocation` signature.
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 *KeyRevocation* signature (type `0x20`). Its structure is similar to that of a *CertificationRevocation* signature.
| Subpacket | Area | Critical | Mandatory | Notes | | Subpacket | Area | Critical | Mandatory | Notes |
|-----------|------|----------|-----------|-------| |-------------------------|--------|----------------|-------------------|-------------------------------------------------|
| Signature Creation Time | Hashed | True | True | Current time | | Signature Creation Time | Hashed | True | True | Current time |
| Issuer Fingerprint | Hashed | True or false | Strongly Recommended | The primary key is the issuer | | 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 | | Reason for Revocation | Hashed | True | False | Determines soft or hard revocation |
For `KeyRevocation` signatures, the same constraints as for `SubkeyRevocation` signatures apply to the [reason subpacket](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-reason-for-revocation). For *KeyRevocation* signatures, the guidelines regarding the [*Reason for Revocation* subpacket] (https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-reason-for-revocation) are the same as those for *SubkeyRevocation* signatures.
#### Common Subpackets #### Common subpackets in OpenPGP signatures
There are some subpackets that are expected to be included in all types of signatures. In OpenPGP, certain subpackets are universally expected across all types of signatures, serving fundamental roles in the signature's structure and verification:
* **Signature Creation Time**: Every OpenPGP signature MUST contain a Signature Creation Time subpacket (2) containing the timestamp at which the signature was made. This packet MUST be present in the hashed area of the signature and SHOULD be marked as critical. * **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**: To be able to verify a signature, the verifier needs to know which (sub-)key was used to issue the signature in the first place. Therefore, every OpenPGP v6 signature SHOULD contain an Issuer Fingerprint subpacket (33) containing the 32 byte fingerprint of the particular component key that was used to create the signature. * **Issuer Fingerprint**: Essential for signature verification, this subpacket identifies the key (or subkey) used to create the signature. OpenPGP v6 signatures should include the Issuer Fingerprint subpacket, containing the 32-byte fingerprint of the key.
```{note} ```{note}
The issuer key might be a subkey. The key used as the issuer in the signature might be a subkey of the certificate.
``` ```
Since the issuer fingerprint subpacket is self-authenticating, it can either be included as a hashed or unhashed subpacket, but the authors of this book recommend to place it in the hashed area of the signature. This subpacket can be placed in either the hashed or unhashed area due to its self-authenticating nature. However, we recommend including it in the signature's hashed area.
### Potential subpacket conflicts and duplication ### Managing subpacket conflicts and duplication
Since the hashed and unhashed areas of a signature are just lists of subpackets, in principle they allow duplicates of the same subpacket, which might lead to conflicts. 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:
Therefore, packets in the hashed area take precedence over the unhashed area.
However, there may still be conflicts between packets in the same area, e.g., two conflicting expiration dates, etc.
The [specification recommends](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-notes-on-subpackets) that implementations favor the last occurrence of a conflicting packet in the hashed area (that is, the last entry for that subpacket type in the sequence of subpackets in the hashed area).
In some cases, duplicate packets with conflicting content even make sense, e.g., if a signature was made by a version 4 issuer key whose key material was migrated from an older OpenPGP version such as v3. - **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.
In this case, either the v3 or v4 key could be used to validate the v4 signature, but since the key ID calculation scheme was changed between v3 and v4, these identifiers would differ.
Therefore, the signature could contain two issuer key ID subpackets with conflicting, but correct values. - **Handling conflicts within the same area**: Conflicts can still arise within the same area, such as when two subpackets have different expiration dates. In such cases, the [OpenPGP specification](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-notes-on-subpackets) 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.