vanitasvitae/openpgp-notes
1
0
Fork 0
mirror of https://codeberg.org/openpgp/notes.git synced 2025-09-09 11:19:41 +02:00
Code Issues Projects Releases Packages Wiki Activity

Merge pull request 'Add glossary links for chapter 7 and 8' (#177) from dvzrv/glossary_links_7_8 into draft

Browse source 
Reviewed-on: https://codeberg.org/openpgp/notes/pulls/177
This commit is contained in:
heiko 2023-12-10 19:35:18 +00:00
commit aa5999ff35
5 changed files with 547 additions and 268 deletions
Download patch file Download diff file Expand all files Collapse all files

3
book/source/04-certificates.md
View file

@ -172,6 +172,7 @@ Each {term}`User ID` carries associated preference settings, such as preferred e
The {term}`primary User ID` was historically the main store for preferences that apply to the {term}`certificate<OpenPGP Certificate>` as a whole. For more on this, see {ref}`primary-metadata`.
(user_attributes)=
### User attributes in OpenPGP
While
[user attributes](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-user-attribute-packet-tag-1) are similar to {term}`User IDs<User ID>`, they are less commonly used.
@ -283,7 +284,7 @@ For more detailed information on {term}`revoking<Revocation>` specific {term}`co
Since its inception, {term}`third-party identity certifications<Third-party Identity Certification>` have been a cornerstone of the OpenPGP ecosystem. The original PGP designers, starting with Phil Zimmermann, advocated for decentralized {term}`trust models<Trust Model>` over reliance on centralized authorities. This decentralized approach in OpenPGP is known as the ["Web of Trust."](wot)
Third-party {term}`certifications<Certification>` are statements by OpenPGP users confirming that a user with a specific {term}`identity` is the owner of a particular {term}`OpenPGP certificate`.
{term}`Third-party certifications<Third-party Identity Certification>` are statements by OpenPGP users confirming that a user with a specific {term}`identity` is the owner of a particular {term}`OpenPGP certificate`.
For example, Bob's OpenPGP software may issue a {term}`certification` that Bob has checked that the {term}`User ID` `Alice Adams <alice@example.org>` and the {term}`certificate<OpenPGP Certificate>` with the {term}`fingerprint<OpenPGP Fingerprint>` `AAA1 8CBB 2546 85C5 8358 3205 63FD 37B6 7F33 00F9 FB0E C457 378C D29F 1026 98B3` are legitimately linked.

4
book/source/06-signatures.md
View file

@ -32,7 +32,7 @@ The OpenPGP standard defines a set of [Signature types](https://www.ietf.org/arc
{term}`Signature types<OpenPGP Signature Type>` can be predominantly classified in two ways:
- **{term}`Signatures over data<Signature Over Data>`**: These signatures are denoted by {term}`type IDs<Type ID>` `0x00` for binary documents and `0x01` for canonical text documents. The {term}`signer` uses these {term}`signatures<OpenPGP Signature Packet>` to claim ownership, assert creation, or certify the immutability of the document.
- **{term}`Signatures over data<Data Signature>`**: These signatures are denoted by {term}`type IDs<Type ID>` `0x00` for binary documents and `0x01` for canonical text documents. The {term}`signer` uses these {term}`signatures<OpenPGP Signature Packet>` to claim ownership, assert creation, or certify the immutability of the document.
- **{term}`Signatures on components<Signature On Component>`**: These are {term}`signatures<OpenPGP Signature Packet>` that are associated with {term}`component keys<Component Key>` or {term}`identity components<Identity Component>` of a {term}`certificate<OpenPGP Certificate>`.
{term}`Signatures on components<Signature On Component>` are a complex topic, and we discuss them in depth in {ref}`component_signatures_chapter`. They are grouped based on two criteria:
@ -140,7 +140,7 @@ In the OpenPGP protocol, each {term}`signature subpacket<OpenPGP Signature Subpa
This mechanism accounts for different {term}`OpenPGP implementations<OpenPGP Implementation>` that may support only certain subsets of the standard. Moreover, it anticipates the evolution of the standard, including the addition of new {term}`subpacket types<OpenPGP Signature Subpacket Type>`.
Consider a scenario where an {term}`implementation<OpenPGP Implementation>` does not recognize a {term}`subpacket<OpenPGP Signature Subpacket>` indicating {term}`signature<OpenPGP Signature Packet>` {term}`expiration`. Without understanding this concept, the {term}`implementation<OpenPGP Implementation>` might erroneously accept an already {term}`expired<Expiration>` {term}`signature<OpenPGP Signature Packet>`. By marking the {term}`expiration date subpacket` as {term}`critical<Criticality Flag>`, the creator of the {term}`signature<OpenPGP Signature Packet>` ensures that any recipient who cannot process this {term}`subpacket<OpenPGP Signature Subpacket>` will reject the {term}`signature<OpenPGP Signature Packet>` as {term}`invalid<Validation>`.
Consider a scenario where an {term}`implementation<OpenPGP Implementation>` does not recognize a {term}`subpacket<OpenPGP Signature Subpacket>` indicating {term}`signature<OpenPGP Signature Packet>` {term}`expiration`. Without understanding this concept, the {term}`implementation<OpenPGP Implementation>` might erroneously accept an already {term}`expired<Expiration>` {term}`signature<OpenPGP Signature Packet>`. By marking the {term}`signature expiration time subpacket` as {term}`critical<Criticality Flag>`, the creator of the {term}`signature<OpenPGP Signature Packet>` ensures that any recipient who cannot process this {term}`subpacket<OpenPGP Signature Subpacket>` will reject the {term}`signature<OpenPGP Signature Packet>` as {term}`invalid<Validation>`.
For specific guidelines on which {term}`subpackets<OpenPGP Signature Subpacket>` should be marked as {term}`critical<Criticality Flag>`, refer to the {term}`RFC` sections [5.2.3.11](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-signature-creation-time) to [5.2.3.36](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-intended-recipient-fingerpr).

85
book/source/07-signing_data.md
View file

@ -6,67 +6,68 @@ SPDX-License-Identifier: CC-BY-SA-4.0
(signing_data)=
# Signatures over data
In OpenPGP, a *data signature* guarantees the authenticity and, implicitly, the integrity of certain data. Typical use cases of data signatures include the authentication of software packages and emails.
In OpenPGP, a *{term}`data signature`* guarantees the {term}`authenticity<Authentication>` and, implicitly, the integrity of certain data. Typical use cases of {term}`data signatures<Data Signature>` include the {term}`authentication` of software packages and emails.
"Authenticity" in this context means that the data signature was issued by the entity controlling the signing key material. However,
it does not automatically signal if the expected party indeed controls the signer certificate. OpenPGP does offer mechanisms for *strong authentication*, connecting certificates to specific identities. This verifies that the intended communication partner is indeed associated with the cryptographic identity behind the signature[^sign-auth].
"{term}`Authenticity<Authentication>`" in this context means that the {term}`data signature` was issued by {term}`the entity controlling the signing key material<Certificate Holder>`. However,
it does not automatically signal if the expected party indeed controls the {term}`signer` {term}`certificate<OpenPGP Certificate>`. OpenPGP does offer mechanisms for *strong {term}`authentication`*, connecting {term}`certificates<OpenPGP Certificate>` to specific {term}`identities<Identity>`. This verifies that the intended communication partner is indeed associated with the cryptographic {term}`identity` behind the {term}`signature<OpenPGP Signature Packet>`[^sign-auth].
[^sign-auth]: Other signing solutions, like [signify](https://flak.tedunangst.com/post/signify), focus on pure signing without strong authentication of the signer's identity.
[^sign-auth]: Other signing solutions, like [signify](https://flak.tedunangst.com/post/signify), focus on pure signing without strong {term}`authentication` of the {term}`signer`'s {term}`identity`.
Data signatures can only be issued by component keys with the *signing* [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags).
{term}`Data signatures<Data Signature>` can only be issued by {term}`component keys<Component Key>` with the *{term}`signing<Signing Key Flag>`* [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags).
Note that data signatures are distinct from {ref}`component_signatures_chapter`, which are used to form and maintain certificates, as well as to certify identities on certificates.
Note that {term}`data signatures<Data Signature>` are distinct from {ref}`component_signatures_chapter`, which are used to form and maintain {term}`certificates<OpenPGP Certificate>`, as well as to {term}`certify<Certification>` {term}`identities<Identity>` on {term}`certificates<OpenPGP Certificate>`.
(data_signature_types)=
## Signature types
OpenPGP data signatures use one of two [signature types](signature_types):
{term}`OpenPGP data signatures<Data Signature>` use one of two [signature types](signature_types):
- [**Binary signature**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#sigtype-binary) (type ID `0x00`): This is the standard signature type for binary data and is typically used for files or data streams. Binary signatures are calculated over the data without any modifications or transformations.
- [**Text signature**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-signature-of-a-canonical-te) (type ID `0x01`): Used for textual data, such as email bodies. When calculating a text signature, the data is first normalized by converting line endings into a canonical form (`<CR><LF>`). This approach mitigates issues caused by platform-specific text encodings. This is especially important for detached and cleartext signatures, where the message file might undergo re-encoding between the creation and verification of the signature.
- [**Binary signature**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#sigtype-binary) ({term}`type ID<Signature Type ID>` `0x00`): This is the standard {term}`signature type` for binary data and is typically used for files or data streams. {term}`Binary signatures<Binary Signature>` are calculated over the data without any modifications or transformations.
- [**Text signature**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-signature-of-a-canonical-te) ({term}`type ID<Signature Type ID>` `0x01`): Used for textual data, such as email bodies. When calculating a {term}`text signature`, the data is first normalized by converting line endings into a canonical form (`<CR><LF>`). This approach mitigates issues caused by platform-specific text encodings. This is especially important for detached and {term}`cleartext signatures<Cleartext Signature>`, where the message file might undergo re-encoding between the creation and {term}`verification` of the {term}`signature<OpenPGP Signature Packet>`.
Data signatures are generated by hashing the message content along with the metadata in the OpenPGP signature packet, and calculating a cryptographic signature over that hash. The resulting cryptographic signature is stored in the signature packet.
{term}`Data signatures<Data Signature>` are generated by {term}`hashing<Hash Digest>` the message content along with the {term}`metadata` in the {term}`OpenPGP signature packet`, and calculating a {term}`cryptographic signature` over that {term}`hash<Hash Digest>`. The resulting {term}`cryptographic signature` is stored in the {term}`signature packet<OpenPGP Signature Packet>`.
Data signature packets manifest in three distinct forms, which will be detailed in the subsequent section.
{term}`Data signature packets<Data Signature Packet>` manifest in three distinct forms, which will be detailed in the subsequent section.
(forms_of_openpgp_data_signatures)=
## Forms of OpenPGP data signatures
OpenPGP data signatures can be applied in three distinct forms[^sign-modes-gpg]:
{term}`OpenPGP data signatures<Data Signature>` can be applied in three distinct forms[^sign-modes-gpg]:
- **Detached**: The OpenPGP signature exists as a separate entity, independent of the signed data.
- **Inline**: Both the original data and its corresponding OpenPGP signature are encapsulated within an OpenPGP container.
- **Cleartext signature**: A plaintext message and its OpenPGP signature coexist in a combined text format, preserving the readability of the original message.
- **{term}`Detached<Detached Signature>`**: The OpenPGP signature exists as a separate entity, independent of the signed data.
- **{term}`Inline<Inline Signature>`**: Both the original data and its corresponding {term}`OpenPGP signature<OpenPGP Signature Packet>` are encapsulated within an {term}`OpenPGP message`.
- **{term}`Cleartext signature`**: A plaintext message and its {term}`OpenPGP signature<OpenPGP Signature Packet>` coexist in a combined text format, preserving the readability of the original message.
[^sign-modes-gpg]: These three forms of signature application align with GnuPG's `--detach-sign`, `--sign`, and `--clearsign` command options.
[^sign-modes-gpg]: These three forms of {term}`signature<OpenPGP Signature Packet>` application align with GnuPG's `--detach-sign`, `--sign`, and `--clearsign` command options.
### Detached signatures
A detached signature is produced by calculating an OpenPGP signature over the data intended for signing. The original data remains unchanged, and the OpenPGP signature is stored as a standalone file. A detached signature file can be distributed alongside or independent of the original data. The authenticity and integrity of the original data file can be verified by using the detached signature file.
A {term}`detached signature` is produced by calculating an {term}`OpenPGP signature<OpenPGP Signature Packet>` over the data intended for signing. The original data remains unchanged, and the {term}`OpenPGP signature<OpenPGP Signature Packet>` is stored as a standalone file. A {term}`detached signature` file can be distributed alongside or independent of the original data. The {term}`authenticity<Authentication>` and integrity of the original data file can be {term}`verified<Verification>` by using the {term}`detached signature` file.
This signature format is especially useful for signing software releases and other files where it is imperative that the content remains unaltered during the signing process.
This {term}`signature<OpenPGP Signature Packet>` format is especially useful for signing software releases and other files where it is imperative that the content remains unaltered during the signing process.
(inline_signature)=
### Inline signatures
An inline signature joins the signed data and its corresponding data signature into a single OpenPGP message.
An {term}`inline signature` joins the signed data and its corresponding {term}`data signature` into a single {term}`OpenPGP message`.
This method is commonly used for signing or encrypting emails. Most email software capable of handling OpenPGP communications typically uses inline signatures.
This method is commonly used for signing or encrypting emails. Most email software capable of handling OpenPGP communications typically uses {term}`inline signatures<Inline Signature>`.
#### Structure
An inline-signed OpenPGP message consists of three segments:
An {term}`inline-signed<Inline Signature>` {term}`OpenPGP message` consists of three segments:
1. [**One-pass signature packets**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#one-pass-sig): These one or more packets precede the signed data and enable signature computation in one pass.
1. [**One-pass signature packets**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#one-pass-sig): These one or more {term}`packets<Packet>` precede the signed data and enable {term}`signature<OpenPGP Signature Packet>` computation in one pass.
2. [**Literal data packet**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#lit): This contains the original data (e.g., the body of a message), without additional interpretation or conversion.
3. **Data signature packets**: These contain the cryptographic signature corresponding to the original data.
3. **{term}`Data signature packets<OpenPGP Signature Packet>`**: These contain the {term}`cryptographic signature` corresponding to the original data.
#### Creation
To produce an inline signature, the signer processes the entirety of the data by reading from an input file and writing into an output OpenPGP message file. As the data is processed, the signer simultaneously calculates a cryptographic signature. This procedure results in the appending of a data signature packet to the output OpenPGP message file, where it can be efficiently stored.
To produce an {term}`inline signature`, the {term}`signer` processes the entirety of the data by reading from an input file and writing into an output {term}`OpenPGP message` file. As the data is processed, the {term}`signer` simultaneously calculates a {term}`cryptographic signature`. This procedure results in the appending of a {term}`data signature packet` to the output {term}`OpenPGP message` file, where it can be efficiently stored.
For efficient verification, an application must understand how to handle the literal data prior to its reading. This requirement is addressed by the one-pass signature packets located at the beginning of inline-signed messages. These packets include essential information such as the fingerprint of the signing key and the hash algorithm used for computing the signature's hash digest. This setup enables the verifier to process the data correctly and efficiently.
For efficient {term}`verification`, an application must understand how to handle the {term}`literal data<Literal Data Packet>` prior to its reading. This requirement is addressed by the {term}`one-pass signature packets<One-pass Signature Packet>` located at the beginning of {term}`inline-signed<Inline Signature>` messages. These {term}`packets<Packet>` include essential information such as the {term}`fingerprint<OpenPGP Fingerprint>` of the {term}`signing key<OpenPGP Component Key>` and the {term}`hash<Hash Digest>` algorithm used for computing the {term}`signature<OpenPGP Signature Packet>`'s {term}`hash digest`. This setup enables the verifier to process the data correctly and efficiently.
```{admonition} TODO
:class: warning
@ -78,23 +79,23 @@ Realization: It's probably useful to know the fingerprints right away, to first
#### Verification
Inline-signed messages enable efficient verification in *one pass*, structured as follows:
{term}`Inline-signed<Inline Signature>` messages enable efficient {term}`verification` in *one pass*, structured as follows:
1. **Initiation with one-pass signature packets**: These packets begin the verification process. They include the signer's key ID/fingerprint, essential for identifying the appropriate public key for signature validation.
1. **Initiation with {term}`one-pass signature packets<One-pass Signature Packet>`**: These {term}`packets<Packet>` begin the {term}`verification` process. They include the {term}`signer`'s {term}`key ID`/{term}`fingerprint<OpenPGP Fingerprint>`, essential for identifying the appropriate {term}`public key<OpenPGP Certificate>` for signature {term}`validation`.
2. **Processing the literal data packet**: This step involves hashing the literal data, preparing it for signature verification.
2. **Processing the {term}`literal data packet`**: This step involves {term}`hashing<Hash Digest>` the literal data, preparing it for {term}`signature<OpenPGP Signature Packet>` {term}`verification`.
3. **Verifying signature packets**: Located at the end of the message, these packets are checked against the previously calculated hash digest.
3. **{term}`Verifying<Verification>` {term}`signature packets<OpenPGP Signature Packet>`**: Located at the end of the message, these {term}`packets<Packet>` are checked against the previously calculated {term}`hash digest`.
Important to note, the signer's public key, critical for the final verification step, is not embedded in the message. Verifiers must acquire this key externally (e.g., from a key server) to authenticate the signature successfully.
Important to note, the {term}`signer`'s {term}`public key<OpenPGP Certificate>`, critical for the final {term}`verification` step, is not embedded in the message. Verifiers must acquire this {term}`key` externally (e.g., from a {term}`key server`) to authenticate the {term}`signature<OpenPGP Signature Packet>` successfully.
(cleartext-sig)=
### Cleartext signatures
The *Cleartext Signature Framework* (CSF) in OpenPGP accomplishes two primary objectives:
The *{term}`Cleartext Signature Framework`* (CSF) in OpenPGP accomplishes two primary objectives:
- maintaining the message in a human-readable cleartext format, accessible without OpenPGP-specific software
- incorporating an OpenPGP signature for authentication by users with OpenPGP-compatible software
- incorporating an {term}`OpenPGP signature<OpenPGP Signature Packet>` for {term}`authentication` by users with OpenPGP-compatible software
#### Example
@ -115,31 +116,31 @@ r13/eqMN8kfCDw==
-----END PGP SIGNATURE-----
```
This signature consists of two parts: a message ("hello world") and an ASCII-armored OpenPGP signature. The message is immediately comprehensible to a human reader, while the signature block allows for the message's authenticity verification via OpenPGP software.
This {term}`signature<Cleartext Signature>` consists of two parts: a message ("hello world") and an ASCII-armored {term}`OpenPGP signature<OpenPGP Signature Packet>`. The message is immediately comprehensible to a human reader, while the {term}`signature<OpenPGP Signature Packet>` block allows for the message's {term}`authenticity<Authentication>` {term}`verification` via OpenPGP software.
#### Use case
Clear text signatures combine the advantages of both detached and inline signatures:
{term}`Cleartext signatures<Cleartext Signature>` combine the advantages of both {term}`detached<Detached Signature>` and {term}`inline signatures<Inline Signature>`:
- **Self-contained format**: Cleartext signatures enable the message and its signature to be stored as a single file.
- **Self-contained format**: {term}`Cleartext signatures<Cleartext signature>` enable the message and its {term}`signature<OpenPGP Signature Packet>` to be stored as a single file.
- **Human readability**: The message within a cleartext signature remains accessible in a plain text format. This eliminates the need for specialized software to read the message content.
- **Human readability**: The message within a {term}`cleartext signature` remains accessible in a plain text format. This eliminates the need for specialized software to read the message content.
These features are particularly beneficial in scenarios where signed messages are managed semi-manually and where existing system infrastructure offers limited or no native support for OpenPGP in the workflow[^arch-certifications].
[^arch-certifications]: An illustrative example is the workflow adopted by Arch Linux to certify User IDs of new packagers. This process relies on [cleartext signed statements from existing packagers](https://gitlab.archlinux.org/archlinux/archlinux-keyring/-/blob/master/.gitlab/issue_templates/New%20Packager%20Key.md?ref_type=heads&plain=1#L33-46). These signed statements are stored as attachments in an issue tracking system for later inspection. The advantage of this approach lies in the convenience of having the message and signature in a single file, which simplifies manual handling. Based on the vouches in these cleartext signed messages and an [email confirmation from the new packager](https://gitlab.archlinux.org/archlinux/archlinux-keyring/-/wikis/workflows/verify-a-packager-key), the main key operators can issue OpenPGP third-party certifications.
[^arch-certifications]: An illustrative example is the workflow adopted by Arch Linux to {term}`certify<Certification>` {term}`User IDs<User ID>` of new packagers. This process relies on [cleartext signed statements from existing packagers](https://gitlab.archlinux.org/archlinux/archlinux-keyring/-/blob/master/.gitlab/issue_templates/New%20Packager%20Key.md?ref_type=heads&plain=1#L33-46). These signed statements are stored as attachments in an issue tracking system for later inspection. The advantage of this approach lies in the convenience of having the message and signature in a single file, which simplifies manual handling. Based on the vouches in these {term}`cleartext signed<Cleartext Signature>` messages and an [email confirmation from the new packager](https://gitlab.archlinux.org/archlinux/archlinux-keyring/-/wikis/workflows/verify-a-packager-key), the main key operators can issue {term}`OpenPGP third-party certifications<Third-party Identity Certification>`.
#### Text transformations for cleartext signatures
The cleartext signature framework includes specific text normalization procedures to ensure the integrity and clarity of the message:
The {term}`cleartext signature framework` includes specific text normalization procedures to ensure the integrity and clarity of the message:
- **Escaping dashes**: The framework implements a method of [dash-escaped text](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-dash-escaped-text) within the message. Dash-escaping ensures that the parser correctly distinguishes between the armor headers, which are part of the signature's structure, and any lines in the message that happen to start with a dash.
- **Escaping dashes**: The framework implements a method of [dash-escaped text](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-dash-escaped-text) within the message. Dash-escaping ensures that the parser correctly distinguishes between the armor headers, which are part of the {term}`signature<OpenPGP Signature Packet>`'s structure, and any lines in the message that happen to start with a dash.
- **Normalization of line endings**: Consistent with the approach for any other [text signature](data_signature_types), a cleartext signature is calculated on the text with normalized line endings (`<CR><LF>`). This ensures that the signature remains valid regardless of the text format of the receiving implementation.
- **Normalization of line endings**: Consistent with the approach for any other [text signature](data_signature_types), a {term}`cleartext signature` is calculated on the text with normalized line endings (`<CR><LF>`). This ensures that the {term}`signature<OpenPGP Signature Packet>` remains valid regardless of the text format of the receiving {term}`implementation<OpenPGP Implementation>`.
#### Pitfalls
Despite their widespread adoption, cleartext signatures have their limitations and are sometimes viewed as a "legacy method"[^csf-gnupg]. The RFC details the [pitfalls of cleartext signatures](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-issues-with-the-cleartext-s), such as incompatibility with semantically meaningful whitespace, challenges with large messages, and security vulnerabilities related to misleading Hash header manipulations. Given these issues, safer alternatives like inline and detached signature forms are advised.
Despite their widespread adoption, {term}`cleartext signatures<Cleartext Signature>` have their limitations and are sometimes viewed as a "legacy method"[^csf-gnupg]. The {term}`RFC` details the [pitfalls of cleartext signatures](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-issues-with-the-cleartext-s), such as incompatibility with semantically meaningful whitespace, challenges with large messages, and security vulnerabilities related to misleading Hash header manipulations. Given these issues, safer alternatives like {term}`inline<Inline Signature>` and {term}`detached signature` forms are advised.
[^csf-gnupg]: https://lists.gnupg.org/pipermail/gnupg-devel/2023-November/035428.html
@ -151,4 +152,4 @@ Despite their widespread adoption, cleartext signatures have their limitations a
:class: warning
Write
```
```

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

@ -6,198 +6,200 @@ SPDX-License-Identifier: CC-BY-SA-4.0
(component_signatures_chapter)=
# Signatures on components
This chapter examines OpenPGP signatures associated with certificate components, applying to:
This chapter examines {term}`OpenPGP signatures<OpenPGP Signature Packet>` associated with {term}`certificate components<Component>`, applying to:
- component keys, encompassing primary keys and subkeys
- identity components, namely User IDs and User attributes
- {term}`component keys<Component Key>`, encompassing {term}`primary keys<OpenPGP Primary Key>` and {term}`subkeys<OpenPGP Subkey>`
- {term}`identity components<Identity Component>`, namely {term}`User IDs<User ID>` and {term}`User attributes<User attribute>`
Signatures on components are used to construct and maintain certificates, and to model the authentication of identities.
{term}`Signatures on components<Signature On Component>` are used to construct and maintain {term}`certificates<OpenPGP Certificate>`, and to model the {term}`authentication` of {term}`identities<Identity>`.
This chapter expands on topics introduced in the {ref}`certificates_chapter` chapter.
## Self-signatures vs third-party signatures
Component signatures in OpenPGP are categorized into two distinct types:
{term}`Component signatures<Signature On Component>` in OpenPGP are categorized into two distinct types:
- **self-signatures**, which are issued by the certificate holder using the certificate's primary key
- **third-party signatures**, which are issued by an external entity, not the certificate holder
- **{term}`self-signatures<Self-Signature>`**, which are issued by the {term}`certificate holder` using the {term}`certificate<OpenPGP Certificate>`'s {term}`primary key<OpenPGP Primary Key>`
- **{term}`third-party signatures<Third-party Signature>`**, which are issued by an external entity, not the {term}`certificate holder`
(self-signatures)=
### Self-signatures
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.
{term}`Self-signatures<Self-signature>` are fundamental in creating and managing {term}`OpenPGP certificates<OpenPGP Certificate>`. They bind the various {term}`components<Component>` of a {term}`certificate<OpenPGP Certificate>` into one combined data structure and facilitate the {term}`certificate<OpenPGP Certificate>`'s {term}`life-cycle management`.
Life-cycle management operations include:
{term}`Life-cycle management` operations include:
- binding additional components to a certificate
- modifying expiration dates or other metadata of components
- revoking, and thus invalidating, components or existing self-signatures
- {term}`binding<Binding Signature>` additional {term}`components<Component>` to a {term}`certificate<OpenPGP Certificate>`
- modifying {term}`expiration time` or other {term}`metadata` of `components<Component>`
- revoking, and thus invalidating, {term}`components<Component>` or existing {term}`self-signatures<Self-signature>`
Self-signatures are issued by the certificate's owner using the certificate's primary key.
{term}`Self-signatures<Self-signature>` are issued by the {term}`certificate's owner<Certificate Holder>` using the {term}`certificate<OpenPGP Certificate>`'s {term}`primary key<OpenPGP Primary Key>`.
```{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 {term}`self-signatures<Self-signature>`. An {term}`OpenPGP primary key` can issue {term}`self-signatures<Self-signature>` by default.
```
### Third-party signatures
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 of identity claims.
{term}`Third-party signatures<Third-party Signature>` are pivotal in OpenPGP for decentralized {term}`authentication`, forming the basis of the {term}`Web of Trust`. They encode {term}`authentication`-related statements about {term}`certificates<OpenPGP Certificate>` and linked {term}`identities<Identity>`, establishing trustworthiness of {term}`identity claims<Identity Claim>`.
Third-party signatures are used to make specific statements:
- certifying identity claims
- delegating authentication decisions
- revoking, and thus invalidating, prior third-party signature statements
- {term}`certifying<Certification>` {term}`identity claims<Identity Claim>`
- {term}`delegating<Delegation>` {term}`authentication` decisions
- {term}`revoking<Revocation>`, and thus {term}`invalidating<Validation>`, prior {term}`third-party signature` statements
```{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. By convention[^primary-certification], only the certificate's primary key can hold this key flag.
The **{term}`certify others<Certification Key Flag>`** [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags) (`0x01`) is required to issue {term}`third-party signatures<Third-party Signature>`. By convention[^primary-certification], only the {term}`certificate<OpenPGP Certificate>`'s {term}`primary key<OpenPGP Primary Key>` can hold this {term}`key flag`.
```
[^primary-certification]: Most current implementations assume that only the primary key may hold the *certify others* key flag, although this is not specified in the RFC.
[^primary-certification]: Most current {term}`implementations<OpenPGP Implementation>` assume that only the {term}`primary key<OpenPGP Primary Key>` may hold the *{term}`certify others<Certification Key Flag>`* {term}`key flag`, although this is not specified in the {term}`RFC`.
### Distinct functions of self-signatures and third-party signatures
The meaning of an OpenPGP signature depends significantly on its issuer. Self-signatures and third-party signatures, even when of the same [signature type](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-signature-types), serve distinct functions. For example:
The meaning of an {term}`OpenPGP signature<OpenPGP Signature Packet>` depends significantly on its {term}`issuer`. {term}`Self-signatures<Self-signature>` and {term}`third-party signatures<Third-party Signature>`, even when of the same [signature type](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-signature-types), serve distinct functions. 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 on another user's certificate.
- {term}`Certifying self-signatures<Certifying Self-signature>` ({term}`type IDs<Signature Type ID>` `0x10` - `0x13`) bind a {term}`User ID` to a {term}`certificate<OpenPGP Certificate>`.
- {term}`Third-party signatures<Third-party Signature>` of the same {term}`type IDs<Signature Type ID>` endorse the {term}`authenticity<Authentication>` of a {term}`User ID` on another user's {term}`certificate<OpenPGP Certificate>`.
In another instance:
- *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 may designate the signed certificate as a trust root within the issuer's Web of Trust.
- *When issued as a {term}`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 {term}`preferences<Algorithm Preferences>` and advertises {term}`features<Features Subpacket>` applicable to the entire {term}`certificate<OpenPGP Certificate>`.
- *When issued by a {term}`third party<Third-party Signature>`*, especially when it carries a [trust signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-trust-signature) {term}`subpacket<OpenPGP Signature Subpacket>`, a similar {term}`direct key signature` {term}`delegates<Delegation>` trust to the signed {term}`certificate<OpenPGP Certificate>`. This may designate the signed {term}`certificate<OpenPGP Certificate>` as a {term}`trust anchor` within the {term}`issuer`'s {term}`Web of Trust`.
(binding_sigs)=
## Self-signatures in certificate formation and 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.
{term}`Self-signatures<Self-signature>` play a crucial role in forming and managing the structure of {term}`OpenPGP certificates<OpenPGP certificate>`. These act as *{term}`binding signatures<Binding Signature>`*, joining {term}`components<Component>` and embedding {term}`metadata`.
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 {term}`OpenPGP certificate` is essentially a series of {term}`packets<Packet>` strung sequentially. When a {term}`certificate<OpenPGP 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), {term}`packets<Packet>` can be easily added or removed.
To safeguard against unauthorized additions or alterations of components, OpenPGP uses cryptographic signatures. These validate that all components, such as subkeys or [identity components](identity_components), were linked to the OpenPGP certificate by its owner, using the 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.
To safeguard against unauthorized additions or alterations of {term}`components<Component>`, OpenPGP uses {term}`cryptographic signatures<Cryptographic Signature>`. These validate that all {term}`components<Component>`, such as {term}`subkeys<OpenPGP Subkey>` or [identity components](identity_components), were linked to the {term}`OpenPGP certificate` by its {term}`owner<Certificate Holder>`, using the {term}`primary key<OpenPGP Primary Key>`. While anyone can still store unrelated elements to a {term}`certificate<OpenPGP Certificate>` dataset, {term}`OpenPGP implementations<OpenPGP implementation>` will reject them if they lack a {term}`valid<Validation>` cryptographic connection with the {term}`certificate<OpenPGP Certificate>`.
```{note}
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.
Conversely, omissions of {term}`packets<Packet>` by third parties can easily occur when handling an {term}`OpenPGP certificate` dataset. This could pose a challenge, for example, when an attacker deliberately omits {term}`revocation` {term}`packets<Packet>`. Without access to an alternative, complete {term}`certificate<OpenPGP Certificate>` source, recipients might not detect these omissions.
```
However, there are legitimate instances in which third parties add "unbound" packets (i.e., not signed by the certificate's owner) to a certificate:
However, there are legitimate instances in which third parties add "unbound" {term}`packets<Packet>` (i.e., not signed by the {term}`certificate<OpenPGP Certificate>`'s {term}`owner<Certificate Holder>`) to a {term}`certificate<OpenPGP Certificate>`:
- [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 locally add [unbound identity data](unbound_user_ids) to a certificate.
- [Third-party certifications](third_party_cert) are often stored within the {term}`packet` data of the {term}`certificate<OpenPGP Certificate>` to which they are related. This is a standard practice that provides convenience for users by allowing easy access to all relevant {term}`certifications<Certification>`. (See {ref}`cert-flooding` for discussion of a related pitfall.)
- {term}`OpenPGP software<OpenPGP Implementation>` may locally add [unbound identity data](unbound_user_ids) to a {term}`certificate<OpenPGP Certificate>`.
(bind_subkey)=
### Binding subkeys to a certificate
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.
{term}`Subkeys<OpenPGP Subkey>` are linked to {term}`OpenPGP certificates<OpenPGP certificate>` via a [subkey binding signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-subkey-binding) ({term}`type ID<Signature Type ID>` `0x18`). This {term}`signature type<OpenPGP Signature Type>` indicates the association of the {term}`primary key<OpenPGP Primary Key>` with the {term}`subkey<OpenPGP Subkey>`.
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.
A {term}`subkey binding signature` binds a {term}`subkey<OpenPGP Subkey>` to a {term}`primary key<OpenPGP Primary Key>`, and it embeds {term}`metadata` into the {term}`signature packet<OpenPGP Signature Packet>`. Once generated, the {term}`subkey binding signature` {term}`packet` is stored in the {term}`certificate<OpenPGP Certificate>` directly after the {term}`subkey<OpenPGP Subkey>` it binds.
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`.
{term}`Subkeys<OpenPGP Subkey>` designated for signing purposes, identified by the *{term}`signing<Signing Key Flag>`* [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_converted/subkey_binding_signature.svg
:name: fig-subkey-binding-signature
:alt: Depicts a diagram on white background with the title "Subkey binding signature". At the top left the symbol of a primary component key with certification capability is shown. At the bottom left the symbol of a component key with encryption capability is shown. The primary component key points at the lower component key with a full green arrow line. In the middle of the connection the small symbol of a signature packet is shown. On the right side of the diagram a detailed version of the signature packet can be found in a box with the title "Subkey binding signature". The text reads "Signature over Primary key, Subkey" and the box with "Signature metadata" contains the list "signature creation time", "key expiration time", "key flags" and "issuer fingerprint". The primary component key points at the detailed signature packet with a dotted green arrow line and the text "Primary key creates a subkey binding signature to bind the subkey to the primary key".
Linking an OpenPGP subkey to the primary key with a binding signature
Linking an {term}`OpenPGP subkey` to the {term}`primary key<OpenPGP Primary Key>` with a {term}`binding signature`
```
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.
{term}`Metadata` for the {term}`subkey`, such as the [*key expiration time*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#key-expiration-subpacket) and {term}`capabilities<Capability>` set by [*key flags*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#key-flags), are included in {term}`subpackets<OpenPGP Signature Subpacket>` within the {term}`subkey binding signature` {term}`packet`.
```{note}
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.
The {term}`validity<Validation>` of a {term}`subkey<OpenPGP Subkey>` is intrinsically linked to that of the {term}`primary key<OpenPGP Primary Key>`. An {term}`expired<Expiration>` {term}`primary key<OpenPGP Primary Key>` renders any associated {term}`subkey<OpenPGP Subkey>` {term}`invalid<Validation>`, regardless of the {term}`subkey<OpenPGP Subkey>`'s own {term}`expiration` setting.
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.
Legally, a {term}`subkey<OpenPGP Subkey>` may not have a specified {term}`expiration time`. In such cases, its {term}`expiration` aligns implicitly with that of the {term}`primary key<OpenPGP Primary Key>`. Additionally, the {term}`creation time` of a {term}`subkey<OpenPGP Subkey>` must always be more recent than that of the {term}`primary key<OpenPGP Primary Key>`.
```
(bind_subkey_sign)=
### Special case: Binding signing subkeys
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.
{term}`Binding` {term}`subkeys<OpenPGP Subkey>` that possess the *{term}`signing<Signing Key Flag>`* {term}`key flag` to a {term}`certificate<OpenPGP Certificate>` represents a unique scenario. While similar to the {term}`binding process<Binding>` of other {term}`subkeys<OpenPGP Subkey>`, there is an additional, critical requirement: mutual association.
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."
That is, to bind a {term}`signing-capable<Signing Key Flag>` {term}`subkey<OpenPGP Subkey>` to a {term}`primary key<OpenPGP Primary Key>`, it is insufficient that the "{term}`primary key<OpenPGP Primary Key>` wants to be associated with the {term}`subkey<OpenPGP Subkey>`." The {term}`subkey<OpenPGP Subkey>` must explicitly signal that it "wants to be associated with the {term}`primary key<OpenPGP Primary Key>`."
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.
Alice could thus claim to have issued signatures which were actually issued by Bob.
To prevent such scenarios, where an attacker might wrongfully "adopt" a victim's signing subkey, a dual-layer of signatures is used:
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) {term}`signing subkey<OpenPGP Signing Subkey>`.
Alice could thus claim to have issued {term}`signatures<OpenPGP Signature Packet>` which were actually issued by Bob.
To prevent such scenarios, where an attacker might wrongfully "adopt" a victim's {term}`signing subkey<OpenPGP Signing Subkey>`, a dual-layer of {term}`signatures<OpenPGP Signature Packet>` is used:
- 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.
- the [subkey binding signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-subkey-binding) ({term}`type ID<Signature Type ID>` `0x18`), which is issued by the {term}`certificate<OpenPGP Certificate>`'s {term}`primary key<OpenPGP Primary Key>`
- the [primary key binding signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#sigtype-primary-binding) ({term}`type ID<Signature Type ID>` `0x19`), created by the {term}`subkey<OpenPGP Subkey>` itself. This is informally known as an embedded "{term}`back signature<Primary Key Binding Signature>`," because the {term}`subkey<OpenPGP Subkey>`'s {term}`signature<OpenPGP Signature Packet>` points back to the {term}`primary key<OpenPGP Primary Key>`.
```{figure} diag_converted/subkey_binding_signatur_for_signing_sk.svg
:name: fig-subkey-binding-signature-for-signing-subkeys
:alt: Depicts a diagram on white background with the title "Subkey binding signature for signing subkeys". At the top left the symbol of a primary component key with certification capability is shown. At the bottom left the symbol of a component key with signing capability is shown. The primary component key points at the lower component key with a full green arrow line. In the middle of the connection the small symbol of a signature packet is shown. On the right side of the diagram a detailed version of the signature packet can be found in a box with the title "Subkey binding signature". The text reads "Signature over Primary key, Subkey" and the box with "Signature metadata" in it contains the list "signature creation time", "key expiration time", "key flags" and "issuer fingerprint". Within the signature metadata a box with a green dotted frame extends the list with an inlined signature packet with the title "Embedded Signature; Primary key binding". Its inner text reads "Signature over Primary Key, Signing Subkey". The signature metadata area of this embedded signature holds the list "signature creation time" and "issuer fingerprint". The cryptographic signature symbol overlaps both metadata and general section of the embedded signature. From the signing component key a green dotted arrow line points to the embedded signature in the subkey binding signature with the text "Signing key creates a primary binding signature to associate itself with the primary key" ("primary binding signature" in bold). At the top of the diagram, the primary component key points at the detailed signature packet with a dotted green arrow line and the text "Primary key creates a subkey binding signature to bind the subkey to the primary key".
Linking an OpenPGP signing subkey to the primary key with a binding signature, and an embedded primary key binding signature
Linking an {term}`OpenPGP signing subkey` to the {term}`primary key<OpenPGP Primary Key>` with a {term}`binding signature`, and an embedded {term}`primary key binding signature`
```
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 {term}`back signature<Primary Key Binding Signature>` signifies the mutuality of the {term}`subkey<OpenPGP Subkey>`'s association with the {term}`primary key<OpenPGP Primary Key>` and is embedded as {term}`subpacket<OpenPGP Signature Subpacket>` data within the {term}`subkey binding signature`, reinforcing the {term}`authenticity<Authentication>` of the {term}`binding`.
(bind_ident)=
### Binding identities 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.
{term}`Self-signatures<Self-signature>` also play a vital role in {term}`binding` {term}`identity components<Identity Component>`, such as {term}`User IDs<User ID>` or {term}`User Attributes<User Attribute>`, to an {term}`OpenPGP certificate`.
To bind the User ID `Alice Adams <alice@example.org>` to her OpenPGP certificate (`AAA1 8CBB 2546 85C5 8358 3205 63FD 37B6 7F33 00F9 FB0E C457 378C D29F 1026 98B3`), Alice would use a certification signature.
To bind the {term}`User ID` `Alice Adams <alice@example.org>` to her {term}`OpenPGP certificate` (`AAA1 8CBB 2546 85C5 8358 3205 63FD 37B6 7F33 00F9 FB0E C457 378C D29F 1026 98B3`), Alice would use a {term}`certification signature<Certifying Self-signature>`.
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, type `0x10`, `0x11`, or `0x12` might be used. This binding signature must be issued by the primary key.
There are four types of *{term}`certifying self-signature`*. The most commonly used {term}`type<Signature Type ID>` for {term}`binding` {term}`User IDs<User ID>` is the [positive certification](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-positive-cert) ({term}`type ID<Signature Type ID>` `0x13`). Alternatively, {term}`type<Signature Type ID>` `0x10`, `0x11`, or `0x12` might be used. This {term}`binding signature` must be issued by the {term}`primary key<OpenPGP Primary Key>`.
The certifying self-signature packet – calculated over the primary key, User ID, and metadata of the signature packet – is added to the certificate, directly following the User ID packet.
The {term}`certifying self-signature` {term}`packet` – calculated over the {term}`primary key<OpenPGP Primary Key>`, {term}`User ID`, and {term}`metadata` of the {term}`signature packet<OpenPGP Signature Packet>` – is added to the {term}`certificate<OpenPGP Certificate>`, directly following the {term}`User ID` {term}`packet`.
```{figure} diag_converted/user_id_certification.svg
:name: fig-user-id-certification
:alt: Depicts a diagram on white background with the title "User ID binding signature". At the top left the symbol of a primary component key with certification capability is shown. At the bottom left the symbol of a User ID reads "Alice Adams <alice@example.org>". The primary component key points at the User ID with a full green arrow line. In the middle of the connection the small symbol of a signature packet is shown. On the right side of the diagram a detailed version of the signature packet can be found in a box with the title "User ID binding signature". The text reads "Signature over Primary key, User ID" and the box with "Signature metadata" in it contains the list "signature creation time", "key expiration time", "primary User ID flag", "algorithm preferences", "key expiration time (primary key)" and "key flags (primary key)". At the top of the diagram, the primary component key points at the detailed signature packet with a dotted green arrow line and the text "Primary key creates a User ID binding signature to associate the User ID with the primary key".
Linking a User ID to an OpenPGP certificate
Linking a {term}`User ID` to an {term}`OpenPGP certificate`
```
(primary-metadata)=
### Adding global metadata to a certificate
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 {term}`signatures<OpenPGP Signature Packet>` that {term}`bind<Binding>` {term}`subkeys<OpenPGP Subkey>` and {term}`identity components<Identity Component>` to a {term}`certificate<OpenPGP Certificate>` serve dual purposes: linking {term}`components<Component>` to the {term}`certificate<OpenPGP Certificate>` and adding {term}`metadata` to {term}`components<Component>`.
While it is essential to add metadata that pertains to the entire certificate, this does not require binding any component to the certificate. In this case, the signature mechanism is used just to associate metadata with the certificate globally.
While it is essential to add {term}`metadata` that pertains to the entire {term}`certificate<OpenPGP Certificate>`, this does not require {term}`binding` any {term}`component` to the {term}`certificate<OpenPGP Certificate>`. In this case, the {term}`signature<OpenPGP Signature Packet>` mechanism is used just to associate {term}`metadata` with the {term}`certificate<OpenPGP Certificate>` globally.
Two signature types can perform this function:
Two {term}`signature types<OpenPGP Signature Type>` can perform this function:
- direct key signature on the primary key
- *primary User ID* binding signature
- {term}`direct key signature` on the {term}`primary key<OpenPGP Primary Key>`
- {term}`primary User ID binding signature`
The types of metadata typically associated with the certificate through these methods include:
The types of {term}`metadata` typically associated with the {term}`certificate<OpenPGP Certificate>` through these methods include:
- key expiration
- key flags (capabilities)
- features
- algorithm preference signaling
- {term}`key` {term}`expiration`
- {term}`key flags<Key Flag>` ({term}`capabilities<Capability>`)
- {term}`features<Features Subpacket>`
- {term}`algorithm preferences` signaling
(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) serves as 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 for defining metadata for the entire certificate, by associating it with the primary key.
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 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 for defining {term}`metadata` for the entire {term}`certificate<OpenPGP Certificate>`, by associating it with the {term}`primary key<OpenPGP Primary Key>`.
(self_signature_binding_to_primary_user_id)=
#### Self-signature binding to primary User ID
In OpenPGP v4, another mechanism was often used for metadata management: integrating global certificate metadata within a User ID binding signature. This is specifically evident in the binding signature of the [*primary* User ID](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-primary-user-id) of the OpenPGP certificate.
In OpenPGP v4, another mechanism was often used for {term}`metadata` management: integrating global {term}`certificate<OpenPGP Certificate>` {term}`metadata` within a {term}`User ID binding signature`. This is specifically evident in the {term}`binding signature` of the [*primary* User ID](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-primary-user-id) of the {term}`OpenPGP certificate`.
This method results in the primary User ID binding signature containing a mix of metadata: some specific to that User ID and some applicable to the certificate globally.
This method results in the {term}`primary User ID binding signature` containing a mix of {term}`metadata`: some specific to that {term}`User ID` and some applicable to the {term}`certificate` globally.
Given the widespread adoption of this mechanism in existing OpenPGP certificates, it is crucial that OpenPGP applications recognize and manage it.
Given the widespread adoption of this mechanism in existing {term}`OpenPGP certificates<OpenPGP certificate>`, it is crucial that {term}`OpenPGP applications<OpenPGP Implementation>` recognize and manage it.
(self-revocations)=
### Revocation self-signatures: Invalidating certificate components
Revocation self-signatures represent an important class of self-signatures, used primarily to invalidate components or retract prior signature statements.
{term}`Revocation self-signatures<Revocation Self-signature>` represent an important class of {term}`self-signatures<Self-signature>`, used primarily to invalidate {term}`components<Component>` or retract prior {term}`signature<OpenPGP Signature Packet>` statements.
There are several types of revocation signatures, each serving a specific purpose:
There are several types of {term}`revocation signatures<Revocation Self-signature>`, 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 [**subkey revocation signature**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-subkey-revocation-signature) (type ID `0x28`) invalidates the binding of a subkey.
- A [**certification revocation**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-certification-revocation-si) (type ID `0x30`) invalidates the binding of a User ID or User Attribute.
- A [**key revocation signature**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-revocation-signature-ty) ({term}`type ID<Signature Type ID>` `0x20`) marks a {term}`primary key<OpenPGP Primary Key>` as {term}`revoked<Revocation>`.
- A [**subkey revocation signature**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-subkey-revocation-signature) ({term}`type ID<Signature Type ID>` `0x28`) {term}`invalidates<Validation>` the {term}`binding of a subkey<Subkey Binding Signature>`.
- A [**certification revocation**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-certification-revocation-si) ({term}`type ID<Signature Type ID>` `0x30`) {term}`invalidates<Validation>` the {term}`binding` of a {term}`User ID` or {term}`User Attribute`.
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.
Common scenarios for using {term}`revocations<Revocation>` include marking {term}`certificates<OpenPGP Certificate>` or individual {term}`subkeys<OpenPGP Subkey>` as unusable (e.g., when the {term}`private key<Transferable Secret Key>` has been compromised or replaced) or declaring {term}`User IDs<User ID>` as no longer {term}`valid<Validation>`.
```{note}
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.
{term}`OpenPGP certificates<OpenPGP Certificate>` act as append-only data structures in practice. Once elements of a {term}`certificate<OpenPGP Certificate>` are published, they cannot be removed from {term}`key servers<Key Server>` or third-party OpenPGP systems. {term}`Implementations<OpenPGP Implementation>` usually merge all available {term}`components<Component>` and {term}`signatures<OpenPGP Signature Packet>`.
Revocations are used to mark components or signatures as invalid.
{term}`Revocations<Revocation>` are used to mark {term}`components<Component>` or {term}`signatures<OpenPGP Signature Packet>` as {term}`invalid<Validation>`.
```
```{admonition} TODO
@ -206,151 +208,128 @@ Revocations are used to mark components or signatures as invalid.
Research, under what circumstances revocations revoke individual signatures, and when they instead "unbind" components.
```
Note: certification signatures [can be made irrevocable](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-revocable).
Note: {term}`certification signatures<Certification>` [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
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*.
{term}`Revocation signatures<Revocation Self-signature>` 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 {term}`revocation<Revocation Self-signature>` was issued. This code determines whether the {term}`revocation` is considered *soft* or *hard*.
- **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.
- **Hard revocation**: This irrevocably invalidates the component, affecting all past and future uses. It is typically used to signal compromise of secret key material.
- **{term}`Soft revocation`**: This is typically used for graceful or planned {term}`invalidation<Validation>` of {term}`components<Component>`, such as retiring or updating {term}`components<Component>`. It {term}`invalidates<Validation>` the {term}`component` from the {term}`revocation signature<Revocation Self-signature>`'s {term}`creation time`, but earlier uses remain {term}`valid<Validation>`. Soft revocations can be reversed with a new {term}`self-signature`.
- **{term}`Hard revocation`**: This irrevocably invalidates the {term}`component`, affecting all past and future uses. It is typically used to signal compromise of {term}`secret key material<Private Key Material>`.
```{note}
A revocation signature lacking a *Reason for Revocation* subpacket is interpreted as a hard revocation.
A {term}`revocation signature packet` lacking a {term}`Reason for Revocation subpacket` is interpreted as a {term}`hard revocation`.
```
(third_party_cert)=
## Authentication and delegation in third-party signatures
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.
{term}`Third-party signatures<Third-party Signature>` in OpenPGP primarily encode {term}`authentication` statements for {term}`identities<Identity>` and {term}`delegate<Delegation>` trust decisions. These {term}`signatures<OpenPGP Signature Packet>` can be manually inspected or processed as machine-readable artifacts by {term}`OpenPGP software<OpenPGP Implementation>`, which evaluates the {term}`authenticity<Authentication>` of {term}`certificates<OpenPGP Certificate>` based on user-specified {term}`trust anchors<Trust Anchor>`.
### Certifying identity components
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 identity claim.
When a {term}`signer` issues a {term}`certifying signature<Certification>` on an {term}`identity`, it indicates a verified link between the {term}`identity` and the {term}`certificate<OpenPGP Certificate>`. That is, the {term}`signer` vouches for the {term}`identity claim`.
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.
For example, Alice can vouch that Bob's {term}`User ID` `Bob Baker <bob@example.com>` is legitimately linked with his {term}`certificate<OpenPGP Certificate>` `BB28 9FB7 A68D BFA8 C384 CCCD E205 8E02 D9C6 CD2F 3C7C 56AE 7FB5 3D97 1170 BA83`, by creating a {term}`certification signature<Certification>`. Bob can then distribute Alice's `certifying signature<Certification>` as part of his {term}`certificate<OpenPGP Certificate>`.
Other users may or may not decide to rely on Alice's statement to determine the authenticity of Bob's certificate.
Other users may or may not decide to rely on Alice's statement to determine the {term}`authenticity<Authentication>` of Bob's {term}`certificate<OpenPGP Certificate>`.
(delegation)=
### Trust signatures: delegating authentication
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.
OpenPGP uses [*trust signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#trust-signature-subpacket) {term}`subpackets<OpenPGP Signature Subpacket>` to {term}`delegate<Delegation>` {term}`authentication` decisions, designating the recipient {term}`certificate<OpenPGP Certificate>` as a "{term}`trusted introducer`" (or a {term}`trust anchor`) for the user. This includes specifying {term}`trust depth` (or level) for transitive {term}`delegations<Delegation>` and quantifying trust with numerical values, indicating the extent of reliance on the {term}`introducer<Trusted Introducer>`'s {term}`certifications<Certification>`.
Trust signature subpackets are applicable in *third-party* signatures, more specifically:
{term}`Trust signature` {term}`subpackets<OpenPGP Signature Subpacket>` are applicable in {term}`third-party signatures<Third-party Signature>`, more specifically:
- 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`)
- {term}`identity certification signatures<Identity Certification>` ({term}`type ID<Signature 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) ({term}`type ID<Signature Type ID>` `0x1F`)
(trust_depth_level)=
#### Trust depth/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.
The "{term}`trust depth`" (or {term}`level<Trust Depth>`) in OpenPGP signifies the extent of transitive {term}`delegation` within the {term}`authentication` process. It determines how far a {term}`delegation` can be extended from the original {term}`trusted introducer` to subsequent intermediaries. Essentially, a {term}`certificate<OpenPGP Certificate>` with a {term}`trust depth` of more than one acts as a "{term}`meta-introducer`," facilitating {term}`authentication` decisions across multiple levels in the network.
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 {term}`trust depth` of 1 means relying on {term}`certifications<Certification>` made directly by the {term}`trusted introducer`. The user's OpenPGP software will accept {term}`certifications<Certification>` made directly by the {term}`introducer<Trusted Introducer>` for {term}`authenticating<Authentication>` identities.
However, when the trust depth is set higher, it implies a chain of delegation may extend 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.
However, when the {term}`trust depth` is set higher, it implies a chain of {term}`delegation` may extend beyond the {term}`initial introducer`. The user's software will recognize and accept {term}`certifications<Certification>` made not only by the {term}`primary introducer<Initial Introducer>` but also by other intermediaries whom the {term}`primary introducer<Initial Introducer>` designated as {term}`trusted introducers<Trusted Introducer>`.
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.
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.
```
This allows for a more extensive network of trusted {term}`certifications<Certification>`, enabling a broader and more interconnected {term}`Web of Trust`.
(trust_amounts)=
#### Trust amounts
The "trust amount," with a numerical value ranging from 0 to 255, quantifies the degree of reliance on a delegation.
The "{term}`trust amount`," with a numerical value ranging from `0` to `255`, quantifies the degree of reliance on a {term}`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
:class: warning
Illustrate with diagram(s). Notes for diagrams:
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.
```
A higher value indicates greater degree of reliance. This quantification aids {term}`OpenPGP software<OpenPGP Implementation>` in determining an aggregate amount of reliance, based on combined {term}`certifications<Certification>` from multiple {term}`trusted introducers<Trusted Introducer>`.
(limiting_delegation_scope)=
#### 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).
When using *{term}`trust signature`* {term}`subpackets<OpenPGP Signature Subpacket>`, a {term}`delegation` can be limited to {term}`identities<Identity>` that match a [*regular expression*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#regex-subpacket).
With this mechanism, for example, it is possible to delegate authentication decisions only for User IDs that match the email domain of an organization.
```{admonition} VISUAL
:class: warning
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.
```
With this mechanism, for example, it is possible to {term}`delegate<Delegation>` {term}`authentication` decisions only for {term}`User IDs<User ID>` that match the email domain of an organization.
(wot)=
### Web of Trust: Decentralized trust decisions
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 {term}`Web of Trust` in OpenPGP is a {term}`trust model` that facilitates {term}`authentication` decisions through a network of {term}`certifications<Certification>` and {term}`delegations<Delegation>`. 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 {term}`certificates<OpenPGP Certificate>` that are robustly interconnected via `third-party certifications<Third-party Identity Certification>`.
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.
In this model, users independently {term}`delegate<Delegation>` {term}`authentication` decisions, choosing whose {term}`certification` to rely on. This {term}`delegation` is based on the {term}`certificates<OpenPGP Certificate>` and {term}`third-party signatures<Third-party Signature>` available to them, with their {term}`OpenPGP software<OpenPGP Implementation>` applying the {term}`Web of Trust` mechanism to discern the reliability of each {term}`certificate<OpenPGP Certificate>` for an {term}`identity`.
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`.
The {term}`OpenPGP RFC<RFC>` doesn't specify exactly how {term}`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
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](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-revocation-key).
To reverse a previously issued {term}`third-party signature`, the {term}`issuer` can generate a [*certification revocation signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-certification-revocation-si) ({term}`type ID<Signature Type ID>` `0x30`). The {term}`revocation` must be issued by the same {term}`key<Component Key>` that created the original {term}`signature<OpenPGP Signature Packet>` or, in deprecated practice, by a designated [Revocation Key](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-revocation-key).
## Advanced topics
### Certification recipes
Different signatures in OpenPGP serve various specific purposes. This section provides practical guidance on creating these signatures, illustrating each with concrete examples.
Different {term}`signatures<OpenPGP Signature Packet>` in OpenPGP serve various specific purposes. This section provides practical guidance on creating these {term}`signatures<OpenPGP Signature Packet>`, 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.
To modify the preferred {term}`symmetric<Symmetric Cryptography>`, compression, {term}`hash<Hash Function>`, or {term}`AEAD algorithms<Authenticated Encryption With Associated Data>` for a {term}`key<Transferable Secret Key>`, the {term}`key owner<Certificate Holder>` needs to issue a {term}`direct key signature` ({term}`type ID<Signature Type ID>` `0x1F`) on the {term}`primary key<OpenPGP Primary Key>`.
This signature should have the following structure:
This {term}`signature<OpenPGP Signature Packet>` 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 |
| {term}`Subpacket<OpenPGP Signature Subpacket>` | Area | {term}`Critical<Criticality Flag>` | Mandatory | Notes |
|---------------------------------------------------------------------------------------------|-----------------------------|------------------------------------------|----------------------|----------------------------------------------------------------------------------------|
| {term}`Signature Creation Time<Signature Creation Time Subpacket>` | {term}`Hashed<Hashed Area>` | True | True | Current time |
| {term}`Issuer Fingerprint<Issuer Fingerprint Subpacket>` | {term}`Hashed<Hashed Area>` | True or False | Strongly Recommended | The {term}`primary key` is the {term}`issuer` |
| {term}`Key Flags<Key Flag>` | {term}`Hashed<Hashed Area>` | True | False | Retain {term}`key flags<Key Flag>` from the previous {term}`self-signature` |
| {term}`Features<Features Subpacket>` | {term}`Hashed<Hashed Area>` | True | False | Retain {term}`features<Features Subpacket>` from the previous {term}`self-signature` |
| {term}`Key Expiration Time<Key Expiration Time Subpacket>` | {term}`Hashed<Hashed Area>` | True | False | Retain {term}`expiration time` from the previous {term}`self-signature`, if applicable |
| {term}`Hash Algorithm Preferences<Preferred Hash Algorithms Subpacket>` | {term}`Hashed<Hashed Area>` | False | False | New {term}`preferences<Algorithm Preferences>` |
| {term}`Compression Algorithm Preferences<Preferred Compression Algorithms Subpacket>` | {term}`Hashed<Hashed Area>` | False | False | New {term}`preferences<Algorithm Preferences>` |
| {term}`Symmetric Algorithm Preferences<Preferred Symmetric Ciphers for v1 SEIPD Subpacket>` | {term}`Hashed<Hashed Area>` | False | False | New {term}`preferences<Algorithm Preferences>` |
| {term}`AEAD Algorithm Preferences<Preferred AEAD Ciphersuites Subpacket>` | {term}`Hashed<Hashed Area>` | False | False | New {term}`preferences<Algorithm Preferences>` |
#### Change expiration time
To adjust the expiration time of an OpenPGP certificate, a new *DirectKey* signature (type `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.
To adjust the {term}`expiration time` of an {term}`OpenPGP certificate`, a new *{term}`DirectKey<Direct Key Signature>`* {term}`signature<OpenPGP Signature Packet>` ({term}`type ID<Signature Type ID>` `0x1F`) with a modified {term}`Key Expiration Time subpacket` must be issued. The structure of this {term}`signature<OpenPGP Signature Packet>` is identical to the one outlined in the previous section on changing {term}`algorithm preferences`.
Additionally, the expiration date can be altered for individual User IDs (detailed below) or separate subkeys (see {numref}`bind_subkey`).
Additionally, the {term}`expiration time` can be altered for individual {term}`User IDs<User ID>` (detailed below) or separate {term}`subkeys<OpenPGP Subkey>` (see {numref}`bind_subkey`).
#### Add User ID
To bind a User ID to an OpenPGP certificate a certification signature (type `0x10`-`0x13`) is used which should have the following structure:
To {term}`bind<Binding>` a {term}`User ID` to an {term}`OpenPGP certificate` a {term}`certification signature<Certification>` ({term}`type ID<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 |
| {term}`Subpacket<OpenPGP Signature Subpacket>` | Area | {term}`Critical<Criticality Flag>` | Mandatory | Notes |
|------------------------------------------------------------------------|-----------------------------|------------------------------------------|----------------------|-------------------------------------------------------------------------------------|
| {term}`Signature Creation Time<Signature Creation Time Subpacket>` | {term}`Hashed<Hashed Area>` | True | True | Current time |
| {term}`Issuer Fingerprint<Issuer Fingerprint Subpacket>` | {term}`Hashed<Hashed Area>` | True or False | Strongly Recommended | The {term}`primary key<OpenPGP Primary Key>` is the {term}`issuer` |
| {term}`Primary User ID<Primary User ID Subpacket>` | {term}`Hashed<Hashed Area>` | True | False | Optional |
| {term}`Signature Expiration Time<Signature Expiration Time Subpacket>` | {term}`Hashed<Hashed Area>` | 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.
In addition to these {term}`subpackets<OpenPGP Signature Subpacket>`, {term}`self-certifications<Self-certification>` for {term}`User IDs<User ID>` can include others – such as {term}`key flags<Key Flag>`, {term}`features<Features Subpacket>`, and {term}`algorithm preferences` – as shown in the previous table. This enables the specification of unique capabilities and {term}`preferences<Algorithm Preferences>` for each {term}`identity` associated with the {term}`certificate<OpenPGP 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.
Since {term}`OpenPGP certificates<OpenPGP certificate>` are often distributed by the means of {term}`key servers<Key Server>`, new {term}`signatures<OpenPGP Signature Packet>` on a {term}`certificate<OpenPGP Certificate>` are often "merged" into existing copies of the {term}`certificate<OpenPGP Certificate>` locally by the recipient.
```{admonition} TODO
:class: warning
@ -358,58 +337,58 @@ Since OpenPGP certificates are often distributed by the means of key servers, ne
Link to the "Merging" section in chapter 4, once merged.
```
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 integration process means it is practically impossible to directly remove {term}`signatures<OpenPGP Signature Packet>` or {term}`User IDs<User ID>` from a {term}`certificate<OpenPGP Certificate>`, as there is no way to communicate the intention of {term}`packet<OpenPGP Signature Packet>` deletion to the recipient.
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.
To effectively mark a {term}`User ID` as invalid, the user can publish a copy of their {term}`certificate<OpenPGP Certificate>` with a {term}`Certification Revocation signature<Certification Revocation Signature Packet>` ({term}`type ID<Signature Type ID>` `0x30`) attached to the invalidated {term}`User ID`. This {term}`signature<OpenPGP Signature Packet>` signals that the specified {term}`User ID` is no longer valid or associated with the {term}`certificate holder`.
The structure of a *CertificationRevocation* is as follows:
The structure of a {term}`Certification Revocation signature<Certification Revocation Signature Packet>` 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 |
| {term}`Subpacket<OpenPGP Signature Subpacket>` | Area | {term}`Critical<Criticality Flag>` | Mandatory | Notes |
|--------------------------------------------------------------------|-----------------------------|------------------------------------------|----------------------|-------------------------------------------------------------------------------------|
| {term}`Signature Creation Time<Signature Creation Time Subpacket>` | {term}`Hashed<Hashed Area>` | True | True | Current time |
| {term}`Issuer Fingerprint<Issuer Fingerprint Subpacket>` | {term}`Hashed<Hashed Area>` | True or False | Strongly Recommended | The {term}`primary key<OpenPGP Primary Key>` is the {term}`issuer` |
| {term}`Reason for Revocation<Reason for Revocation Subpacket>` | {term}`Hashed<Hashed Area>` | True | False | Determines {term}`soft<Soft Revocation>` or {term}`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.
For {term}`User ID` {term}`revocations<Revocation>`, the *{term}`Reason for Revocation<Reason for Revocation Subpacket>`* {term}`subpacket<OpenPGP Signature Subpacket>` is crucial. A value of `0` means no specific reason, leading to a {term}`hard revocation`, while `32` indicates the {term}`User ID` is no longer valid, resulting in a {term}`soft revocation`. Omitting the {term}`reason subpacket<Reason For Revocation Subpacket>` is also equivalent to a {term}`hard revocation`.
It is generally advisable to use reason code `32` for revoking User IDs.
It is generally advisable to use reason code `32` for revoking {term}`User IDs<User ID>`.
(binding_subkeys)=
#### Add a subkey
As part of lifecycle 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:
As part of {term}`life-cycle management`, users may need to add a new {term}`subkey<OpenPGP Subkey>` to their {term}`OpenPGP certificate`, often for reasons such as upgrading to a {term}`subkey<OpenPGP Subkey>` with more advanced cryptographic algorithms. The process involves creating a specific {term}`signature<OpenPGP Signature Packet>` 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 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 |
| {term}`Subpacket<OpenPGP Signature Subpacket>` | Area | {term}`Critical<Criticality Flag>` | Mandatory | Notes |
|---------------------------------------------------------------------------------------------|-----------------------------|------------------------------------------|-------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| {term}`Signature Creation Time<Signature Creation Time Subpacket>` | {term}`Hashed<Hashed Area>` | True | True | Current time |
| {term}`Issuer Fingerprint<Issuer Fingerprint Subpacket>` | {term}`Hashed<Hashed Area>` | True or False | Strongly Recommended | The {term}`primary key<OpenPGP Primary Key>` is the {term}`issuer` |
| {term}`Key Flags<Key Flag>` | {term}`Hashed<Hashed Area>` | True | Strongly Recommended | Determine the usage of the {term}`key<OpenPGP Subkey>` |
| {term}`Key Expiration Time<Key Expiration Time Subpacket>` | {term}`Hashed<Hashed Area>` | True | False | Specifies the {term}`expiration time` of the {term}`subkey<OpenPGP Subkey>` |
| {term}`Embedded Signature<Embedded Signature Subpacket>` | {term}`Hashed<Hashed Area>` | True | If {term}`Key Flags<Key Flag>` contains **{term}`S<Signing Key Flag>`** | {term}`Signing subkeys<OpenPGP Signing Subkey>` require embedded *{term}`Primary Key Binding<Primary Key Binding Signature>`* {term}`signature<OpenPGP Signature Packet>` |
| {term}`Hash Algorithm Preferences<Preferred Hash Algorithms Subpacket>` | {term}`Hashed<Hashed Area>` | False | False | Per {term}`key<Component Key>` {term}`preferences<Algorithm Preferences>` |
| {term}`Compression Algorithm Preferences<Preferred Compression Algorithms Subpacket>` | {term}`Hashed<Hashed Area>` | False | False | Per {term}`key<Component Key>` {term}`preferences<Algorithm Preferences>` |
| {term}`Symmetric Algorithm Preferences<Preferred Symmetric Ciphers for v1 SEIPD Subpacket>` | {term}`Hashed<Hashed Area>` | False | False | Per {term}`key<Component Key>` {term}`preferences<Algorithm Preferences>` |
| {term}`AEAD Algorithm Preferences<Preferred AEAD Ciphersuites Subpacket>` | {term}`Hashed<Hashed Area>` | False | False | Per {term}`key<Component Key>` {term}`preferences<Algorithm Preferences>` |
In addition to these subpackets, users can specify algorithm preferences for each subkey, distinct from those set in the certificate's *DirectKey* signature.
In addition to these {term}`subpackets<OpenPGP Signature Subpacket>`, users can specify {term}`algorithm preferences` for each {term}`subkey<OpenPGP Subkey>`, distinct from those set in the {term}`certificate<OpenPGP Certificate>`'s *{term}`Direct Key<Direct Key Signature>`* {term}`signature<OpenPGP Signature Packet>`.
#### Revoke a subkey
Subkeys, like User IDs, can be individually revoked in OpenPGP.
This is done by issuing a `SubkeyRevocation` signature (type `0x28`) using the primary key.
{term}`Subkeys<OpenPGP subkey>`, like {term}`User IDs<User ID>`, can be individually revoked in OpenPGP.
This is done by issuing a {term}`Subkey Revocation signature<Subkey Revocation Signature Packet>` ({term}`type ID<Signature Type ID>` `0x28`) using the {term}`primary key<OpenPGP Primary Key>`.
The structure of such a signature is straightforward:
The structure of such a {term}`signature<OpenPGP Signature Packet>` 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 |
| {term}`Subpacket<OpenPGP Signature Subpacket>` | Area | {term}`Critical<Criticality Flag>` | Mandatory | Notes |
|--------------------------------------------------------------------|-----------------------------|------------------------------------------|----------------------|-------------------------------------------------------------------------------------|
| {term}`Signature Creation Time<Signature Creation Time Subpacket>` | {term}`Hashed<Hashed Area>` | True | True | Current time |
| {term}`Issuer Fingerprint<Issuer Fingerprint Subpacket>` | {term}`Hashed<Hashed Area>` | True or False | Strongly Recommended | The {term}`primary key<OpenPGP Primary Key>` is the {term}`issuer` |
| {term}`Reason for Revocation<Reason For Revocation Subpacket>` | {term}`Hashed<Hashed Area>` | True | False | Determines {term}`soft<Soft Revocation>` or {term}`hard revocation` |
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.
In {term}`Subkey Revocation signatures<Subkey Revocation Signature Packet>`, the [reason for revocation](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-reason-for-revocation) {term}`subpacket<OpenPGP Signature Subpacket>` can only have values in the range of `0-3`. The values `1` ({term}`key<OpenPGP Subkey>` superseded) and `3` ({term}`key<OpenPGP Subkey>` retired and no longer used) indicate {term}`soft revocations<Soft Revocation>`, whereas values `0` (no reason) and `2` ({term}`key<OpenPGP Subkey>` compromised) indicate {term}`hard revocations<Hard Revocation>`.
Note that a value of `32` is not applicable in these signatures.
Note that a value of `32` is not applicable in these {term}`signatures<OpenPGP Signature Packet>`.
```{admonition} TODO
:class: warning
@ -419,40 +398,40 @@ Research and explain hardness in the context of subkey revocations. What does a
#### 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.
Users may find themselves needing to revoke their entire {term}`OpenPGP certificate`, rendering it unusable. This could be for various reasons, such as migrating to a new {term}`certificate<OpenPGP certificate>` or in response to a compromise of the {term}`certificate<OpenPGP certificate>`'s {term}`secret key material<Private Key Material>`.
While a soft-revoked certificate can be re-validated at a later time with a new certification, a hard revocation is permanent.
While a {term}`soft-revoked<Soft Revocation>` {term}`certificate<OpenPGP Certificate>` can be re-validated at a later time with a new {term}`certification`, a {term}`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.
The recommended way to {term}`revoke<Revocation>` a {term}`certificate<OpenPGP Certificate>` is by issuing a {term}`Key Revocation signature<Key Revocation Signature Packet>` ({term}`type ID<Signature Type ID>` `0x20`). Its structure is similar to that of a {term}`Certification Revocation signature<Certification Revocation Signature Packet>`.
| 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 |
| {term}`Subpacket<OpenPGP Signature Subpacket>` | Area | {term}`Critical<Criticality Flag>` | Mandatory | Notes |
|--------------------------------------------------------------------|-----------------------------|------------------------------------------|----------------------|-------------------------------------------------------------------------------------|
| {term}`Signature Creation Time<Signature Creation Time Subpacket>` | {term}`Hashed<Hashed Area>` | True | True | Current time |
| {term}`Issuer Fingerprint<Issuer Fingerprint Subpacket>` | {term}`Hashed<Hashed Area>` | True or False | Strongly Recommended | The {term}`primary key<OpenPGP Primary Key>` is the {term}`issuer` |
| {term}`Reason for Revocation<Reason For Revocation Subpacket>` | {term}`Hashed<Hashed Area>` | True | False | Determines {term}`soft<Soft Revocation>` or {term}`hard 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.
For {term}`Key Revocation signatures<Key Revocation Signature Packet>`, 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 {term}`Subkey Revocation signatures<Subkey Revocation Signature Packet>`.
#### 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 and verification:
In OpenPGP, certain {term}`subpackets<OpenPGP Signature Subpacket>` are universally expected across all types of {term}`signatures<OpenPGP Signature Packet>`, serving fundamental roles in the {term}`signature<OpenPGP Signature Packet>`'s structure, {term}`verification` and {term}`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.
* **{term}`Signature Creation Time<Signature Creation Time Subpacket>`**: This is a mandatory {term}`subpacket<OpenPGP Signature Subpacket>` in every {term}`OpenPGP signature<OpenPGP Signature Packet>`. It contains the timestamp of when the {term}`signature<OpenPGP Signature Packet>` was created. For security and integrity, this {term}`subpacket<OpenPGP Signature Subpacket>` must be located in the {term}`hashed area` of the {term}`signature<OpenPGP Signature Packet>` and is recommended to be marked as {term}`critical<Criticality Flag>`.
* **Issuer Fingerprint**: Essential for signature verification, 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.
* **{term}`Issuer Fingerprint<Issuer Fingerprint Subpacket>`**: Essential for {term}`signature<OpenPGP Signature Packet>` {term}`validation`, this {term}`subpacket<OpenPGP Signature Subpacket>` identifies the {term}`key<OpenPGP Primary Key>` (or {term}`subkey<OpenPGP Subkey>`) that was used to create the {term}`signature<OpenPGP Signature Packet>`. OpenPGP v6 {term}`signatures<OpenPGP Signature Packet>` should include the {term}`Issuer Fingerprint subpacket`, containing the 32-byte {term}`fingerprint<OpenPGP Fingerprint>` of the {term}`key<Component Key>`.
```{note}
The key used as the issuer in the signature might be a subkey of the certificate.
The {term}`key<Component Key>` used as the {term}`issuer` in the {term}`signature<OpenPGP Signature Packet>` might be a {term}`subkey<OpenPGP Subkey>` of the {term}`certificate<OpenPGP Certificate>`.
```
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.
These {term}`subpackets<OpenPGP Signature Subpacket>` can be placed in either the {term}`hashed<Hashed Area>` or {term}`unhashed area` due to its self-{term}`authenticating<Authentication>` nature. However, we recommend including them in the {term}`signature<OpenPGP Signature Packet>`'s {term}`hashed area`.
### 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:
In {term}`OpenPGP signatures<OpenPGP Signature Packet>`, both the {term}`hashed<Hashed Area>` and {term}`unhashed areas<Unhashed Area>` are composed of lists of {term}`subpackets<OpenPGP Signature Subpacket>`. Inherently, this structure permits the duplication of the same {term}`subpacket<OpenPGP Signature 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.
- **Precedence of {term}`hashed area`**: {term}`Subpackets<OpenPGP Signature Subpacket>` within the {term}`hashed area` of a {term}`signature<OpenPGP Signature Packet>` take precedence over those in the {term}`unhashed area`. This hierarchy helps resolve conflicts when the same {term}`subpacket<OpenPGP Signature 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 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.
- **Handling conflicts within the same area**: Conflicts can still arise within the same area, such as when two {term}`subpackets<OpenPGP Signature Subpacket>` have different {term}`expiration times<Expiration Time>`. 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 {term}`implementations<OpenPGP Implementation>` should favor the last occurrence of a conflicting {term}`subpacket<OpenPGP Signature Subpacket>` in the {term}`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.
In certain scenarios, having duplicate {term}`subpackets<OpenPGP Signature Subpacket>` with conflicting content is logical and even necessary. For example, consider a {term}`signature<OpenPGP Signature Packet>` created by a version 4 {term}`issuer` {term}`key<Component Key>`, which was upgraded from an older OpenPGP version (like v3). Since the {term}`key ID` calculation scheme changed from v3 to v4, the identifiers for the same {term}`key<Component Key>` would differ between these versions. Therefore, a v4 signature might contain two {term}`issuer key ID subpackets<Issuer Fingerprint Subpacket>`, each with different, yet correct values for v3 and v4 {term}`keys<Component Key>`, respectively. This allows for backward compatibility and ensures the {term}`signature<OpenPGP Signature Packet>` can be {term}`validated<Validation>` under both {term}`key ID` calculation schemes.

336
book/source/23-glossary.md
View file

@ -8,9 +8,25 @@ SPDX-License-Identifier: CC-BY-SA-4.0
```{glossary}
:sorted:
AEAD
See {term}`Authenticated Encryption With Associated Data`.
AEAD Algorithm
See {term}`Authenticated Encryption With Associated Data`.
Algorithm Preferences
The preferences for {term}`hash algorithms<Hash Function>`, {term}`compression algorithms<Data Compression>`, {term}`symmetric algorithms<Symmetric Cryptography>` and {term}`AEAD algorithms<Authenticated Encryption With Associated Data>` are set using {term}`direct key signatures<Direct Key Signature>` or {term}`primary User ID` {term}`binding signatures<Binding Signature>`.
See [](change_algorithm_preferences).
Asymmetric Cryptography
Asymmetric cryptography is used in OpenPGP. For a more detailed discussion see [](public_key_asymmetric_cryptography).
Authenticated Encryption With Associated Data
Short AEAD, refers to an encryption scheme that ensures confidentiality of a message. Additionally, additional data, which is not confidential, may be associated with the message.
See Wikipedia on [Authenticated Encryption](https://en.wikipedia.org/wiki/Authenticated_encryption).
Authentication
The process of {term}`validiting<Validation>` an {term}`identity claim`.
The term "authentication" here is semantically different from the one used in {term}`Authentication Key Flag`.
@ -24,8 +40,19 @@ Authentication Tag
Authenticity
See {term}`Authentication`.
Back Signature
See {term}`Primary Key Binding Signature`.
Binary Signature
A {term}`Data Signature` with the {term}`Signature Type ID` `0x00`, which is used for binary data.
Binding
The process of creating a {term}`Binding Signature` for a {term}`Component`, or the resulting {term}`Binding Signature`.
See {ref}`binding_sigs` for more.
Binding Signature
A {term}`signature` on a {term}`component` which links that {term}`component` to a {term}`certificate<OpenPGP Certificate>`.
A {term}`self-signature` on a {term}`component` which associates that {term}`component` to the issuing {term}`component key` in a {term}`certificate<OpenPGP Certificate>`.
See {ref}`binding_sigs` for more.
@ -41,9 +68,6 @@ Certificate
Certificate Authority
See {term}`Certification Authority`
Certification Authority
Also known as [Certificate authority](https://en.wikipedia.org/wiki/Certificate_authority), this is an entity that handles digital certificates, especially by signing or issuing them.
Certificate Holder
A person or other entity, that holds an {term}`Transferable Secret Key` and thus is able to modify the accompanying {term}`OpenPGP Certificate`.
@ -52,18 +76,45 @@ Certification
Most commonly, the term is applied to "[third-party certifications](third_party_cert)," in which an external actor indicates that they have {term}`validated<Validation>` the link between an {term}`identity` and a {term}`certificate<OpenPGP Certificate>`. However, the term is also used for [self-signatures that bind identity components](bind_ident) to a {term}`certificate<OpenPGP Certificate>`.
Certification Authority
Also known as [Certificate authority](https://en.wikipedia.org/wiki/Certificate_authority), this is an entity that handles digital certificates, especially by signing or issuing them.
Certification Key Flag
A {term}`Key Flag`, indicating that a {term}`Component Key` can be used for issuing third-party {term}`certifications<Certification>`. See [](capabilities_key_flags).
Certification Revocation Signature Packet
An {term}`OpenPGP Signature Packet` to {term}`revoke<Revocation>` an earlier {term}`self-certification` of a {term}`User ID`.
[RFC 5.2.1.13](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-certification-revocation-si)
Certification Signature
See {term}`Certification`.
Certifying Self-signature
An {term}`OpenPGP Signature Packet` by the {term}`Certificate Holder` on an {term}`Identity Component` of their own {term}`Certificate`.
Certifying Signature
See {term}`Certification`.
Cipher Type Byte
This historical term was defined in [RFC 1991](https://datatracker.ietf.org/doc/html/rfc1991#section-4.1) and was subsequently superseded by {term}`Packet Tag` in [RFC 2440](https://datatracker.ietf.org/doc/html/rfc2440#section-4.2), which is in turn superseded by {term}`Packet Type ID` in the new [RFC](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-packet-headers).
Cleartext Signature
A {term}`Data Signature` which exists in a combined text format, encapsulating the (readable) text input it was created for. See [](cleartext-sig).
Cleartext Signature Framework
A framework for creating {term}`cleartext signatures<Cleartext Signature>`.
See [RFC 7](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#cleartext-signature).
Component
An element in an {term}`OpenPGP Certificate`, that represents a {term}`component key` or {term}`identity component`.
Component Key
See {term}`OpenPGP Component Key`.
Compression
See {term}`Data Compression`.
Creation Time
The point in time at which e.g. an {term}`OpenPGP Certificate`, or one of its {term}`component<Component>` is created.
@ -82,13 +133,33 @@ Cryptographic Signature
CTB
See {term}`Cipher Type Byte`.
Data Compression
The process of encoding information using fewer bits than the original representation.
In OpenPGP data compression is used to reduce the size required for encrypted messages.
See Wikipedia on [Data Compression](https://en.wikipedia.org/wiki/Data_compression).
Data Signature
{term}`Cryptographic signature` over binary documents or canonical text documents. See [](/07-signing_data).
Data Signature Packet
An {term}`OpenPGP Signature Packet` which describes a {term}`Data Signature`. See [](/07-signing_data).
Delegation
OpenPGP users can [delegate authentication decisions](delegation) to third parties, and thus rely on {term}`certifications<Certification>` they issue. The remote party is then called a "{term}`trusted introducer`".
This kind of delegation involves {term}`certifications<Certification>` that include the {term}`trust signature` subpacket.
Detached Signature
A {term}`Data Signature` which exists as a separate file to the file it was created for. See [](forms_of_openpgp_data_signatures).
Direct Key Signature
A {term}`Signature` that sets preferences and advertises features applicable to an entire {term}`Certificate`. See [](direct_key_signature).
A {term}`Signature` that sets preferences and advertises {term}`features<Features Subpacket>` applicable to an entire {term}`Certificate`. See [](direct_key_signature).
Embedded Signature Subpacket
An {term}`OpenPGP Signature Subpacket` which contains a complete {term}`OpenPGP Signature Packet`.
See [RFC 5.2.3.34](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-embedded-signature)
Encryption Key Flag
A {term}`Key Flag`, indicating that a {term}`Component Key` can be used for encrypting data. See [](capabilities_key_flags).
@ -96,18 +167,35 @@ Encryption Key Flag
Expiration
A mechanism by which a {term}`Component` is invalidated due to the {term}`Expiration Time` of its {term}`binding signature` being older than the {term}`Reference Time` by which it is validated.
Expiration Date Subpacket
An {term}`OpenPGP Signature Subpacket Type` which defines the {term}`Expiration Time` for an {term}`OpenPGP Signature Packet`.
Expiration Time
The time of expiry of an {term}`OpenPGP Signature Packet`.
Features Subpacket
A {term}`OpenPGP Signature Subpacket`, which denotes advanced OpenPGP features an {term}`implementation<OpenPGP Implementation>` supports.
For an in-depth view on these {term}`subpackets<OpenPGP Signature Subpacket>` see [](zooming_in_dks).
See [RFC 5.2.3.32](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-features)
Fingerprint
See {term}`OpenPGP Fingerprint`.
Hard Revocation
A {term}`Revocation Signature Packet` for a {term}`Certification` or a {term}`Component Key`, which either includes a {term}`Reason For Revocation Subpacket` with a {term}`Revocation Code`, that signifies the target being compromised (e.g., `0` or `2`), or has no {term}`Reason For Revocation Subpacket` at all.
See [](hard_vs_soft_revocations).
See [RFC 5.2.3.31](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-reason-for-revocation).
Hash Algorithm
See {term}`Hash Function`.
Hash Digest
Output of a cryptographic hash function for a string of data of any length. See [](crypto-hash).
Hash Function
A function used to map data of arbitrary size to fixed-size values (see {term}`Hash Digest`).
Hashed Area
An area in an {term}`OpenPGP Signature Packet` containing {term}`OpenPGP Signature Subpacket`s, that is covered by the {term}`Hash Digest` a {term}`Cryptographic Signature` is created for. See [](hashed_and_unhashed_signature_subpackets).
@ -120,6 +208,9 @@ Hybrid Cryptosystem
Identity
An identity of a {term}`Certificate Holder`. It is represented by an {term}`Identity Component`, which may be certified using {term}`third-party identity certifications<Third-party Identity Certification>`, or by a {term}`Notation`.
Identity Certification
An {term}`OpenPGP Signature Packet` on an {term}`Identity Component` which {term}`certifies<Certification>` its {term}`authenticity<Authentication>`.
Identity Claim
A {term}`Certificate Holder` may use {term}`Identity Components<Identity Component>` or {term}`Notations<Notation>` to state a claim about their {term}`Identity`.
@ -129,12 +220,20 @@ Identity Component
Identity Verification
A process by which the {term}`Identity Claim` of a {term}`Certificate Holder` is verified. See also {term}`Signature Verification`.
Initial Introducer
An {term}`OpenPGP Certificate` explicitly {term}`delegated<Delegation>` to from a {term}`Trust Anchor`.
Inline Signature
A {term}`Data Signature` which exists encapsulated alongside the data it was created for in an OpenPGP container. See [](forms_of_openpgp_data_signatures).
Issuer
An entity, that created an {term}`OpenPGP Signature Packet` using an {term}`Transferable Secret Key`.
Issuer Fingerprint Subpacket
A {term}`Subpacket` specifying the {term}`Fingerprint` of an {term}`Issuer Key`.
See [RFC 5.2.3.35](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-issuer-fingerprint)
Issuer Key
The {term}`OpenPGP Component Key` of an {term}`Issuer`, used to create an {term}`OpenPGP Signature Packet`.
@ -153,9 +252,17 @@ Key
- OpenPGP component key
- {term}`OpenPGP key` (which in turn refers to either an {term}`OpenPGP Certificate` or a {term}`Transferable Secret Key`
Key Expiration Time Subpacket
An {term}`OpenPGP Signature Subpacket Type` which defines the {term}`Expiration Time` for an {term}`OpenPGP Signature Packet` on a {term}`key<Component Key>`.
See [RFC 5.2.3.13](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-expiration-time)
Key Flag
A preference encoded in an {term}`OpenPGP Signature Subpacket`, that defines the {term}`Capability` a {term}`OpenPGP Component Key` has. See [](signature_subpackets).
Key Holder
See {term}`Certificate Holder`.
Key ID
The high-order (leftmost) 64 bits of an {term}`OpenPGP Fingerprint`.
Historically, this term refers to the low-order (rightmost) 64 bits of an {term}`OpenPGP Fingerprint`.
@ -163,12 +270,24 @@ Key ID
Key Material
May refer to {term}`Public Key Material` or {term}`Private Key Material`.
Key Holder
See {term}`Certificate Holder`.
Key Owner
See {term}`Certificate Holder`.
Key Revocation Signature Packet
A {term}`Revocation Self-signature` for an entire {term}`OpenPGP Certificate`.
Key Server
A piece of software available over the network, which provides access to {term}`OpenPGP Certificates<OpenPGP Certificate>` e.g., by searching for an {term}`OpenPGP Fingerprint` or {term}`User ID`, via the `HKP` and/ or `HKPS` protocols.
Several implementations such as [hagrid](https://gitlab.com/keys.openpgp.org/hagrid/), or [hockeypuck](https://github.com/hockeypuck/hockeypuck) exist.
Life-cycle Management
In OpenPGP several actions are necessary for the prolonged use of an {term}`OpenPGP Certificate` or adapting its {term}`components<Component>` to the requirements of the {term}`Certificate Holder`.
These are for example changes to {term}`binding signatures<Binding Signature>` (adding or {term}`revocation` of {term}`component keys<Component Key>` or {term}`direct key signature<Direct Key Signature>`), modification of {term}`expiration time` or other {term}`metadata` for {term}`components<Component>`.
See [](self-signatures).
Literal Data Packet
A {term}`packet<OpenPGP Signature Packet>` in a {term}`Data Signature` which contains data, that has been signed using a {term}`cryptographic signature`. See [RFC 5.9](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#lit) for more details.
MAC
See {term}`Message Authentication Code`.
@ -178,6 +297,9 @@ Master Key
Message Authentication Code
A piece of information used for integrity and {term}`authenticity<Authentication>` verification of a message. See [](message_authentication_codes).
Meta-Introducer
An {term}`OpenPGP Certificate` with a {term}`Trust Depth` greater than one.
Metadata
Data related to preferences of an {term}`OpenPGP Certificate` or its {term}`Certificate Holder`, that can be found in {term}`signature` {term}`packets<Packet>`. See [](metadata_in_certificates).
@ -190,6 +312,9 @@ Notation Signature Subpacket
Notation Tag
Part of a {term}`Notation` name.
One-pass Signature Packet
One or more {term}`packets<OpenPGP Signature Packet>` before the actual data in a {term}`Data Signature` which contain information to allow a receiving {term}`implementation<OpenPGP Implementation>` to create {term}`hashes<Hash Digest>` required for signature verification. See [RFC 5.4](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#one-pass-sig) for more details.
OpenPGP Certificate
An OpenPGP certificate contains public key material, identity claims and third party certifications (but no private key material)
@ -207,6 +332,9 @@ OpenPGP Implementation
OpenPGP Key
Used either for an {term}`OpenPGP Certificate` (containing public key material and metadata), or for an {term}`OpenPGP Private Key`. See [](/04-certificates) for an in-depth discussion.
OpenPGP Message
A data structure, which contains OpenPGP components such as {term}`OpenPGP Certificate` or {term}`OpenPGP Signature Packet` and plaintext or encrypted data.
OpenPGP Public Key
See {term}`OpenPGP Certificate`.
@ -231,6 +359,9 @@ OpenPGP Signature Subpacket Type
OpenPGP Signature Type
The type of an {term}`OpenPGP Signature Packet` is defined by its {term}`Signature Type ID`. See [](signature_types).
OpenPGP Signing Subkey
An {term}`OpenPGP Subkey` with the {term}`Signing Key Flag`.
OpenPGP Subkey
An {term}`OpenPGP Component Key` that is used in the subkey role, in an {term}`OpenPGP Certificate`. For a more detailed discussion, see [](subkeys).
@ -249,14 +380,62 @@ Packet Tag
Packet Type ID
A numerical value encoded in the first octet of a {term}`Packet Header`, defining a {term}`Packet`'s type.
Positive Certification
An {term}`OpenPGP Signature Type` with the {term}`Signature Type ID` `0x13`, which is used in {term}`binding signatures<Binding Signature>` for {term}`User IDs<User ID>`. This {term}`OpenPGP Signature Type` implies that the {term}`issuer` has done substantial {term}`verification` of the {term}`Identity Claim`.
See [](bind_ident).
Preferred Compression Algorithms Subpacket
An {term}`OpenPGP Signature Subpacket Type` which defines the preferred {term}`compression algorithms<Data Compression>` for an {term}`OpenPGP Signature Packet`. This defines which {term}`algorithms<Data Compression>` the {term}`key holder<Certificate Holder>` prefers to use.
See [RFC 5.2.3.17](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-preferred-compression-algor).
Preferred Hash Algorithms Subpacket
An {term}`OpenPGP Signature Subpacket Type` which defines the preferred {term}`hash algorithm<Hash Function>` for an {term}`OpenPGP Signature Packet`. This defines which algorithms the {term}`key holder<Certificate Holder>` prefers to receive.
See [RFC 5.2.3.16](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-preferred-hash-algorithms).
Preferred Symmetric Ciphers for v1 SEIPD Subpacket
An {term}`OpenPGP Signature Subpacket Type` which defines the preferred version 1 {term}`SEIPD<Symmetrically Encrypted Integrity Protected Data>` algorithms for an {term}`OpenPGP Signature Packet`. This defines which algorithms the {term}`key holder<Certificate Holder>` prefers to receive and implicitly signifies the supported algorithms of the {term}`key holder<Certificate Holder>`'s {term}`implementation<OpenPGP Implementation>`.
See [RFC 5.2.3.14](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-preferred-symmetric-ciphers).
Preferred AEAD Ciphersuites Subpacket
An {term}`OpenPGP Signature Subpacket Type` which defines the preferred version 2 {term}`SEIPD<Symmetrically Encrypted Integrity Protected Data>` algorithms for an {term}`OpenPGP Signature Packet`. This defines which algorithms the {term}`key holder<Certificate Holder>` prefers to receive and implicitly signifies the supported algorithms of the {term}`key holder<Certificate Holder>`'s {term}`implementation<OpenPGP Implementation>`.
See [RFC 5.2.3.15](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-preferred-aead-ciphersuites)
Primary Component Key
See {term}`OpenPGP Primary Key`.
Primary Introducer
See {term}`Initial Introducer`.
Primary Key
See {term}`OpenPGP Primary Key`.
Primary Key Binding Signature
A {term}`Binding Signature`, which is created by a {term}`OpenPGP Signing Subkey` on the {term}`OpenPGP Primary Key` of an {term}`OpenPGP Certificate` and stored in an {term}`Embedded Signature Subpacket` in the {term}`Binding Signature` for the {term}`OpenPGP Signing Subkey`.
This special case is explained in more detail in [](bind_subkey_sign).
Primary User ID
A {term}`User ID` which carries the default preferences for {term}`identity components<Identity Component>` without preferences. See [](primary_user_id).
A {term}`User ID` which carries the default preferences for {term}`identity components<Identity Component>` without preferences.
See [](primary_user_id).
Primary User ID Subpacket
An {term}`OpenPGP Signature Subpacket` used in {term}`User ID self-signatures<User ID Binding Signature>` which allows to signify whether the {term}`User ID` in question is considered a {term}`Primary User ID`.
See [RFC 5.2.3.27](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#primary-user-id-subpacket)
Primary User ID Binding Signature
A {term}`Binding Signature`, which is created by an {term}`OpenPGP Primary Key` to bind a {term}`User ID` to its {term}`OpenPGP Certificate` and marking it as the {term}`Primary User ID`.
This {term}`Binding Signature` may carry {term}`metadata` specific to the {term}`User ID` at hand as well as some applicable to the entire {term}`OpenPGP Certificate`.
See [](self_signature_binding_to_primary_user_id).
Private Key
See {term}`Transferable Secret Key`.
@ -276,32 +455,88 @@ Public Key Cryptography
Public Key Material
See {term}`OpenPGP Certificate`.
Reason For Revocation Subpacket
An {term}`OpenPGP Signature Subpacket`, which is used in {term}`Certification Revocation Signature Packet` and {term}`key revocation signature packets<Key Revocation Signature Packet>` to describe a reason for the {term}`revocation`.
See [RFC 5.2.3.31](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-reason-for-revocation)
Reference Time
A point in time at which an {term}`OpenPGP Certificate` is evaluated.
Revocation
Mechanism to invalidate a {term}`component` or an entire {term}`OpenPGP Certificate`. See [](revocations).
Regular Expression Subpacket
An {term}`OpenPGP Signature Subpacket` which allows for limiting {term}`delegations<Delegation>` to {term}`identities<Identity>` matching a regular expression.
Revocation certificate
A type of {term}`signature` that invalidates a previous statement made via a {term}`signature`
Revocation
Mechanism to invalidate a {term}`component` or an entire {term}`OpenPGP Certificate` using a {term}`Revocation Self-signature`. See [](revocations).
Revocation Certificate
A {term}`Revocation Self-signature` for an {term}`OpenPGP Primary Key` distributed alongside the plain {term}`OpenPGP Primary Key`.
See [RFC 10.1.2](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-openpgp-v6-revocation-certi)
Note that in [OpenPGP v4 this term is typically used](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-10.1.3-6) for a bare {term}`Revocation Self-signature` {term}`packet<OpenPGP Signature Packet>`.
Revocation Code
A number in a {term}`Reason For Revocation Subpacket` which represents the reason for a {term}`Revocation`.
Revocation Self-signature
A class of {term}`self-signatures<Self-signature>` to {term}`revoke<Revocation>` {term}`primary keys<OpenPGP Primary Key>`, {term}`User IDs<User ID>` or {term}`User Attributes<User Attribute>` and invalidate {term}`subkey binding signatures<Subkey Binding Signature>`.
See [](self-revocations).
Revocation Signature
See {term}`Revocation Signature Packet`.
Revocation Signature Packet
An {term}`OpenPGP Signature Packet` used for the {term}`revocation` of a {term}`certification` or {term}`binding`.
Revocation signatures are often {term}`self-signatures<Self-signature>`, more specifically {term}`revocation self-signatures<Revocation Self-signature>`.
However, *{term}`certification revocations<Certification Revocation Signature Packet>`* can be both {term}`self-signatures<Self-signature>` or {term}`third-party signatures<Third-party Signature>`.
Additionally, with the deprecated *Revocation Key* mechanism, {term}`third-party<Third-party Signature>` *Key-* and *Subkey revocations* also exist.
RFC
This document, unless noted otherwise, refers to the [OpenPGP version 6 specification](https://datatracker.ietf.org/doc/draft-ietf-openpgp-crypto-refresh/) when referring to *RFC*.
SEIPD
See {term}`Symmetrically Encrypted Integrity Protected Data`.
Self-certification
A {term}`certification` on a {term}`component` of an {term}`OpenPGP Certificate` issued by a {term}`component key` of the same {term}`OpenPGP certificate`.
Secret Key Material
See {term}`Private Key Material`.
Self-signature
An {term}`OpenPGP Signature Packet` by the {term}`Certificate Holder` on a {term}`Component` of their own {term}`Certificate`.
Session Key
A unique shared secret used in encryption in a {term}`Hybrid Cryptosystem`. See {ref}`encryption_chapter` and {ref}`decryption_chapter`.
Soft Revocation
A {term}`Revocation Signature Packet` for a {term}`Certification` or a {term}`Component Key`, which includes a {term}`Reason For Revocation Subpacket` with a {term}`Revocation Code`, that does not signify the target being compromised (e.g., `0` or `2`).
See [](hard_vs_soft_revocations).
See [RFC 5.2.3.31](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-reason-for-revocation).
Signature
See {term}`OpenPGP Signature Packet`.
Signature Creation Time Subpacket
An {term}`OpenPGP Signature Subpacket Type` which defines the {term}`Creation Time` for an {term}`OpenPGP Signature Packet`.
See [RFC 5.2.3.11](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-signature-creation-time)
Signature Expiration Time Subpacket
An {term}`OpenPGP Signature Subpacket Type` which defines the {term}`Expiration Time` for an {term}`OpenPGP Signature Packet`.
See [RFC 5.2.3.18](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-signature-expiration-time)
Signature On Component
{term}`Cryptographic signature` associated with {term}`Component Keys<Component Key>` or {term}`Identity Components<Identity Component>`. See [](/08-signing_components).
Signature Over Data
{term}`Cryptographic signature` over binary documents or canonical text documents. See [](/07-signing_data).
See {term}`Data Signature`.
Signature Packet
See {term}`OpenPGP Signature Packet`.
@ -324,12 +559,35 @@ Signature Verification
Signer
A {term}`Certificate Holder`, that is able to create {term}`self-signatures<Self-signature>` and {term}`third-party signatures<Third-party Signature>`.
Signing-capable
See {term}`Signing Key Flag`.
Signing Key Flag
A {term}`Key Flag`, indicating that a {term}`Component Key` can be used for signing data. See [](capabilities_key_flags).
Signing Subkey
See {term}`OpenPGP Signing Subkey`.
Strong Authentication
"Strong Authentication" in this text refers to having ascertained that a {term}`certificate<OpenPGP Certificate>` and an {term}`identity claim` on it are legitimately linked. That is, that the person who controls the {term}`certificate<OpenPGP Certificate>` is correctly represented by the {term}`identity component`.
Strong authentication in OpenPGP is typically encoded with a {term}`certification signature`.
Ascertaining strong authentication requires an out-of-band check: Either via a manual {term}`verification` process, or an automated system that can {term}`certify<Certification>` that a user has identified to the system that issues the {term}`identity` in question (e.g. an email provider can {term}`certify<Certification>` email-based {term}`identities<Identity>` that it issues to the user).
Also see {term}`Authentication`.
Subkey
See {term}`OpenPGP Subkey`.
Subkey Binding Signature
A {term}`Self-signature` to associate an {term}`OpenPGP Subkey` with an {term}`OpenPGP Primary Key`. See [](bind_subkey).
Subkey Revocation Signature Packet
A {term}`Self-signature` to {term}`revoke<Revocation>` an {term}`OpenPGP Subkey` in an {term}`OpenPGP Certificate`.
See [RFC 5.2.1.12](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-subkey-revocation-signature)
Subpacket
See {term}`OpenPGP Signature Subpacket`.
@ -339,9 +597,17 @@ Subpacket Type
Symmetric Cryptography
Symmetric cryptography is used in OpenPGP. For a more detailed discussion see [](symmetric_key_cryptography).
Symmetrically Encrypted Integrity Protected Data
Short *SEIPD*, this refers to {term}`Symmetric Cryptography` based encrypted data, which is used in a Symmetrically Encrypted Integrity Protected Data Packet.
See [RFC 5.13](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-symmetrically-encrypted-int).
Symmetric Secret Key
The {term}`Private Key Material` used in {term}`Symmetric Cryptography`.
Text Signature
A {term}`signature packet<OpenPGP signature packet>` with the {term}`Signature Type ID` `0x01`, which is used for textual data.
Third-party Identity Certification
{term}`Certification` by third-parties to confirm ownership of an {term}`OpenPGP Certificate` by a {term}`Certificate Holder`. See [](third_party_identity_certifications).
@ -351,11 +617,34 @@ Third-party Signature
Transferable Secret Key
A Transferable Secret Key (TSK) is the combination of an {term}`OpenPGP Certificate` and the associated {term}`private key material`. Also often referred to as an "OpenPGP private key". It is discussed in detail in [](/05-private).
Trust Amount
A numerical value between `0` and `255`, stored in {term}`trust signatures<Trust Signature>` used for indicating the degree of reliance on the {term}`delegation`.
Values less than `120` indicate partial trust, values equal to or greater than `120` indicate complete trust.
See [](trust_amounts).
See [RFC 5.2.3.21](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-trust-signature)
Trust Anchor
An entity in a {term}`Trust Model` for which trust is assumed and not derived.
Trust Depth
This numerical value is part of a {term}`Trust Signature` and describes the extent of trustworthiness of a {term}`Certification`, that the {term}`signer` assigns to it.
See [](trust_depth_level).
Trust Level
See {term}`Trust Depth`.
Trust Model
A model by which trust between {term}`identities<Identity>` associated with different {term}`OpenPGP Certificates<OpenPGP Certificate>` is created. See [](third_party_identity_certifications).
Trust signature
The *trust signature* subpacket on a certifying {term}`signature<OpenPGP Signature Packet>` is used for {term}`delegation` of {term}`authentication` decisions. With this feature, an OpenPGP user can designate a {term}`certificate<OpenPGP Certificate>` as a "{term}`trusted introducer`" and opt to rely on {term}`certifications<Certification>` they issue.
Trust Root
See {term}`Trust Anchor`.
Trust Signature
The *trust signature* {term}`subpacket<OpenPGP Signature Subpacket>` on a {term}`certifying signature<Certification>` is used for {term}`delegation` of {term}`authentication` decisions. With this feature, an OpenPGP user can designate a {term}`certificate<OpenPGP Certificate>` as a "{term}`trusted introducer`" and opt to rely on {term}`certifications<Certification>` they issue.
See [RFC 5.2.3.21](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-trust-signature)
Trusted introducer
OpenPGP users can choose to rely on {term}`certifications<Certification>` issued by a third party. The remote party of such a {term}`delegation` is called a "trusted introducer".
@ -377,9 +666,15 @@ Unhashed Area
Unhashed Subpacket
A {term}`Signature Subpacket` residing in the {term}`Unhashed Area` of a {term}`Signature Packet`.
User Attribute
An {term}`Identity Component`, which may hold a single JPEG image. See [](user_attributes).
User ID
An {term}`Identity Component`, which describes an {term}`Identity` of a {term}`Certificate Holder`. See [](user_ids_in_openpgp_certificates).
User ID Binding Signature
A {term}`Binding Signature`, which is created by an {term}`OpenPGP Primary Key` to bind a {term}`User ID` to an {term}`OpenPGP Certificate`.
Validation
A mechanism by which the [operational needs of a use-case are met](https://en.wikipedia.org/wiki/Verification_and_validation#Validation).
In OpenPGP terminology this may refer to processes such as ensuring, that an {term}`OpenPGP Signature Packet` has been created after a {term}`Transferable Secret Key`'s {term}`Creation Time`, but before its {term}`Expiration Time`.
@ -390,4 +685,7 @@ Validity
Verification
A mechanism by which the [compliance with design specifications are met](https://en.wikipedia.org/wiki/Verification_and_validation#Verification).
In OpenPGP terminology this may refer to e.g. {term}`Signature Verification` or {term}`Identity Verification`.
Web Of Trust
A {term}`trust model` which is based on a network of {term}`certifications<Certification>` and {term}`delegations<Delegation>`, that can be used to discern the reliability of {term}`certificates<Certificate>` and their associated {term}`identities<Identity>`. See [](wot).
```