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

Standardize on kebab case for explicit targets

Browse source 
Signed-off-by: David Runge <dave@sleepmap.de>
This commit is contained in:
David Runge 2023-12-12 16:12:57 +01:00
parent 76c70d85ec
commit 144f10a526
No known key found for this signature in database
GPG key ID: 90D4B9641E092971
23 changed files with 140 additions and 140 deletions
Download patch file Download diff file Expand all files Collapse all files

4
book/source/about.md
View file

@ -11,7 +11,7 @@ This documentation project seeks to introduce all OpenPGP concepts and functiona
## What is OpenPGP?
OpenPGP is an open standard for cryptographic operations. It is a system based on well-understood [cryptographic building blocks](/cryptography). OpenPGP supports the secure delivery of files and messages between a sender and a recipient. It also addresses identities and their verification. OpenPGP is an outgrowth of the ["Pretty Good Privacy (PGP)"](https://en.wikipedia.org/wiki/Pretty_Good_Privacy) encryption program and has many widely used and [interoperable implementations](interop_section).
OpenPGP is an open standard for cryptographic operations. It is a system based on well-understood [cryptographic building blocks](/cryptography). OpenPGP supports the secure delivery of files and messages between a sender and a recipient. It also addresses identities and their verification. OpenPGP is an outgrowth of the ["Pretty Good Privacy (PGP)"](https://en.wikipedia.org/wiki/Pretty_Good_Privacy) encryption program and has many widely used and [interoperable implementations](interop-section).
With OpenPGP, you can:
@ -48,4 +48,4 @@ This documentation encompasses the core aspects of modern OpenPGP practices, app
While using version 6 as a reference for current standards, we include insights derived from earlier versions, particularly version 4, which continues to be widely used in ongoing projects.
Where differences between OpenPGP versions are relevant to application development, we provide focused insights to ensure the content remains as version-agnostic as possible and, thus, broadly applicable for developers working with various iterations of OpenPGP.
Where differences between OpenPGP versions are relevant to application development, we provide focused insights to ensure the content remains as version-agnostic as possible and, thus, broadly applicable for developers working with various iterations of OpenPGP.

6
book/source/adv/certificates.md
View file

@ -102,7 +102,7 @@ When thinking about edge cases, it's useful to "assume the worst." For example:
Another way to think about this discussion is that different OpenPGP users may have a different view of any certificate. There is a notional "canonical" version of the certificate, but we cannot assume that every user has exactly this copy. Besides propagation of elements that the certificate holder has linked to a certificate, third-party certifications are by design a distributed mechanism. A third-party certification is issued by a third party, and may or may not be distributed widely by them, or by the certificate holder. Not distributing third-party certifications widely is a workflow that may be entirely appropriate for some use cases[^tpc-privacy].
[^tpc-privacy]: The two parties to a certification (the issuer and the target of the certification) may prefer not to publish their mutual association. Also see {ref}`metadata_graph`.
[^tpc-privacy]: The two parties to a certification (the issuer and the target of the certification) may prefer not to publish their mutual association. Also see {ref}`metadata-graph`.
As a general tendency, it is desirable for OpenPGP users to have the most complete possible view of all certificates that they interact with.
@ -290,7 +290,7 @@ Once the expiration time is reached, third parties, or ideally their OpenPGP sof
After the update, the updated copy of the certificate will usually have a fresh expiration time. The same procedure will repeat once that new expiration time has been reached.
(metadata_graph)=
(metadata-graph)=
## Metadata leak of Social Graph
Third-party certifications are signatures over identity components made by other users.
@ -308,7 +308,7 @@ So, there is some tension between the goals of
- a decentralized system where every participant can access certification information and perform analysis on it locally,
- privacy related goals (also see {ref}`email-lookup`, for a comparison of certificate distribution mechanisms, which also touches on this theme).
(unbound_user_ids)=
(unbound-user-ids)=
## Adding unbound, local User IDs to a certificate
Some OpenPGP software may add User IDs to a certificate, which are not bound to the primary key by the certificate's owner. This can be useful to store local identity information (e.g., Sequoia's public store attaches ["pet-names"][PET] to certificates, in this way).

4
book/source/adv/decryption.md
View file

@ -5,7 +5,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0
# Advanced material: Decryption
(decryption_seipd_quick_check)=
(decryption-seipd-quick-check)=
## Verify successful session key decryption
SEIPDv1 packets might make use of a "quick check" mechanism to quickly verify that the correct session key was used without the need to decrypt the whole SEIPD packet.
@ -16,7 +16,7 @@ Since the chance to accidentally end up with matching quick check bytes albeit t
The standard [warns against](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-risks-of-a-quick-check-orac) using the quick check mechanism, as it introduces the risk of a decryption oracle. Instead, the use of SEIPDv2 is recommended, as the AEAD mechanism automatically detects use of the wrong session key early on after the first chunk has been decrypted.
(decryption_anonymous_recipient)=
(decryption-anonymous-recipient)=
## Anonymous recipients
Having all recipients keys listed as part of the PKESK packets presents a metadata leakage. An observer can easily enumerate recipients of a message by comparing the PKESKs with certificates of potential recipients.

2
book/source/adv/private_keys.md
View file

@ -75,7 +75,7 @@ Understanding KO attacks is crucial due to their potential to compromise the int
Private keys that are protected with [S2K usage mode 253 (AEAD)](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-secret-key-encryption), are not vulnerable to KO attacks. This mode ensures the integrity of the private key by using its unencrypted fields (including the algorithm field) as the *authentication tag* for integrity verification in the decryption process. When an attacker alters the unencrypted part of the packet, then decryption of the private key material will fail, and the user is prevented from e.g. accidentally using the key material with an altered attacker-controlled algorithm.
Note that while S2K usage mode 253 (AEAD) has been introduced in the OpenPGP version 6 specification, it can also be applied to OpenPGP version 4 key material (also see {ref}`migration_s2k`).
Note that while S2K usage mode 253 (AEAD) has been introduced in the OpenPGP version 6 specification, it can also be applied to OpenPGP version 4 key material (also see {ref}`migration-s2k`).
#### Resources

4
book/source/adv/signatures.md
View file

@ -5,7 +5,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0
# Advanced material: Signatures
(notation_signature_subpackets)=
(notation-signature-subpackets)=
## Notation signature subpackets
[Notation signature subpackets](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#notation-data) can be used to effectively extend the otherwise limited set of {term}`signature subpacket types<OpenPGP Signature Subpacket Type>` in OpenPGP with user-defined {term}`notations<Notation>`. {term}`Issuers<Issuer>` can use these {term}`notations<Notation>` to add name-value pairs to an {term}`OpenPGP signature<OpenPGP Signature Packet>`.
@ -52,4 +52,4 @@ That is:
Note that some historical version 3 signature packets may still be relevant for applications that handle old OpenPGP data[^sig-v3]. These version 3 signature packets will have been generated by version 4 keys.
[sig-v3]Version 4 signature packets were introduced in [RFC 2440](https://datatracker.ietf.org/doc/html/rfc2440#section-5.2) in 1998, which specifies that applications SHOULD generate v4 signature, however generation of v3 signature packets has remained allowed through [RFC 4880](https://www.rfc-editor.org/rfc/rfc4880.html#section-5.2).
[sig-v3]Version 4 signature packets were introduced in [RFC 2440](https://datatracker.ietf.org/doc/html/rfc2440#section-5.2) in 1998, which specifies that applications SHOULD generate v4 signature, however generation of v3 signature packets has remained allowed through [RFC 4880](https://www.rfc-editor.org/rfc/rfc4880.html#section-5.2).

6
book/source/adv/signing_components.md
View file

@ -9,7 +9,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0
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)=
### Change algorithm preferences
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>`.
@ -32,7 +32,7 @@ This {term}`signature<OpenPGP Signature Packet>` should have the following struc
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 {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`).
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
@ -73,7 +73,7 @@ For {term}`User ID` {term}`revocations<Revocation>`, the *{term}`Reason for Revo
It is generally advisable to use reason code `32` for revoking {term}`User IDs<User ID>`.
(binding_subkeys)=
(binding-subkeys)=
### Add a subkey
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:

6
book/source/artifacts.md
View file

@ -5,7 +5,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0
# Appendix A: OpenPGP artifacts
(alice_priv)=
(alice-priv)=
## Alice's OpenPGP key
```text
@ -46,7 +46,7 @@ FcsHp6K860qG87pDlk2saQIwzXPmQcQvLokbeQMB
-----END PGP PRIVATE KEY BLOCK-----
```
(bob_priv)=
(bob-priv)=
## Bob's OpenPGP key
Bob uses passphrase-protected secret key packets. His passphrase is `password`:
@ -92,4 +92,4 @@ wVXtKDX+MOKJM4xz7RvBWErH2xWyqikNZQVuzz/WqOVH/nT+BcqmLWAe3yjrTE4B
hSfrR38Nk23E4Bu4HobVrg7rlMU6SKHRWKeX/iSUmr6GDA==
=UZBq
-----END PGP PRIVATE KEY BLOCK-----
```
```

36
book/source/certificates.md
View file

@ -25,12 +25,12 @@ The term "{term}`(cryptographic) keys<Cryptographic Key>`" is central to graspin
The term "{term}`key`," without additional context, can refer to either public or private {term}`asymmetric<Asymmetric Cryptography>` key material. Additionally, {term}`symmetric<Symmetric Cryptography>` keys may be used in OpenPGP to encrypt {term}`private key material`, adding a layer of security and complexity.
(layers_of_keys_in_openpgp)=
(layers-of-keys-in-openpgp)=
### Layers of keys in OpenPGP
In OpenPGP, the term "{term}`key`" may refer to three distinct layers, each serving a unique purpose:
1. A (bare) ["cryptographic key"](asymmetric_key_pair) comprises the private and/or public parameters forming a key. For instance, in the case of an RSA {term}`private key<Transferable Secret Key>`, the key consists of the exponent `d` along with the prime numbers `p` and `q`.
1. A (bare) ["cryptographic key"](asymmetric-key-pair) comprises the private and/or public parameters forming a key. For instance, in the case of an RSA {term}`private key<Transferable Secret Key>`, the key consists of the exponent `d` along with the prime numbers `p` and `q`.
2. An OpenPGP *{term}`component key<OpenPGP Component Key>`* includes either an "{term}`OpenPGP primary key`" or an "{term}`OpenPGP subkey`." It is a building block of an {term}`OpenPGP certificate`, consisting of a cryptographic keypair coupled with some invariant {term}`metadata`, such as key {term}`creation time`.
3. An "{term}`OpenPGP certificate`" (or "OpenPGP key") consists of several {term}`component keys<OpenPGP Component Key>`, {term}`identity components<Identity Component>`, and other elements. These {term}`certificates<Certificate>` are dynamic, evolving over time as {term}`components<Component>` are added, {term}`expire<Expiration>`, or are marked as {term}`invalid<Validation>`.
@ -61,12 +61,12 @@ Every element in an {term}`OpenPGP certificate` revolves around a central {term}
{term}`OpenPGP certificates<OpenPGP Certificate>` tend to have a long lifespan, with the potential for modifications (typically by their owner) over time. {term}`Components<Component>` may be added or {term}`invalidated<Validation>` throughout a {term}`certificate<OpenPGP Certificate>`'s lifetime. However, once published, {term}`components<Component>` [cannot be removed](append-only) from {term}`certificates<OpenPGP Certificate>`.
```
(component_keys)=
(component-keys)=
## Component keys
An {term}`OpenPGP certificate` usually contains multiple {term}`component keys<OpenPGP Component Key>`. {term}`Component keys<OpenPGP Component Key>` serve in one of two roles: either as an "{term}`OpenPGP primary key`" or as an "{term}`OpenPGP subkey`."
{term}`OpenPGP component keys<OpenPGP Component Key>` logically consist of an [asymmetric cryptographic keypair](asymmetric_key_pair) and a creation timestamp. Once created, these attributes of a {term}`component key<OpenPGP Component Key>` remain fixed (for ECDH keys, two additional parameters are part of a {term}`component key`'s constitutive data[^ecdh-parameters]).
{term}`OpenPGP component keys<OpenPGP Component Key>` logically consist of an [asymmetric cryptographic keypair](asymmetric-key-pair) and a creation timestamp. Once created, these attributes of a {term}`component key<OpenPGP Component Key>` remain fixed (for ECDH keys, two additional parameters are part of a {term}`component key`'s constitutive data[^ecdh-parameters]).
[^ecdh-parameters]: For [ECDH](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-algorithm-specific-part-for-ecd) {term}`component keys<OpenPGP Component Key>`, two additional algorithm parameters are integral to the {term}`component key<OpenPGP Component Key>`'s constitutive and immutable properties. Those parameters specify a hash function and a {term}`symmetric<Symmetric Cryptography>` encryption algorithm.
@ -103,7 +103,7 @@ In practice, the {term}`fingerprint<OpenPGP Fingerprint>` of a {term}`component
[^finger-unique]: For both {term}`OpenPGP version 6<RFC>` and version 4, the likelihood of accidental occurrence of duplicate {term}`fingerprints<OpenPGP Fingerprint>` is negligible when {term}`key material` is generated based on an acceptable source of entropy. A separate question is if an attacker can purposely craft a second key with the same {term}`fingerprint<OpenPGP Fingerprint>` as a given pre-existing {term}`component key<OpenPGP Component Key>`. With the current state of the art, this is not possible for OpenPGP version 6 and version 4 keys. However, at the time of this writing, the SHA-1-based {term}`fingerprints<OpenPGP Fingerprint>` of OpenPGP version 4 are considered insufficiently strong at protecting against the generation of pairs of {term}`key material` with the same {term}`fingerprint<OpenPGP Fingerprint>`.
(primary_key)=
(primary-key)=
### Primary key
The {term}`OpenPGP primary key` is a {term}`component key<OpenPGP Component Key>` that serves a distinct, central role in an {term}`OpenPGP certificate`:
@ -122,7 +122,7 @@ In the {term}`RFC`, the {term}`OpenPGP primary key` is occasionally referred to
Modern {term}`OpenPGP certificates<OpenPGP Certificate>` typically include several {term}`subkeys<OpenPGP Subkey>` in addition to the {term}`primary key<OpenPGP Primary Key>`, although these {term}`subkeys<OpenPGP Subkey>` are optional.
While {term}`subkeys<OpenPGP Subkey>` have the same structural attributes as the {term}`primary key<OpenPGP Primary Key>`, they fulfill different roles. {term}`Subkeys<OpenPGP Subkey>` are cryptographically linked with the {term}`primary key<OpenPGP Primary Key>`, a relationship further discussed in {numref}`binding_subkeys`.
While {term}`subkeys<OpenPGP Subkey>` have the same structural attributes as the {term}`primary key<OpenPGP Primary Key>`, they fulfill different roles. {term}`Subkeys<OpenPGP Subkey>` are cryptographically linked with the {term}`primary key<OpenPGP Primary Key>`, a relationship further discussed in {numref}`binding-subkeys`.
```{figure} plain_svg/Binding_Subkeys.svg
:name: fig-subkeys
@ -131,12 +131,12 @@ While {term}`subkeys<OpenPGP Subkey>` have the same structural attributes as the
{term}`OpenPGP certificates<OpenPGP Certificate>` can contain multiple {term}`subkeys<OpenPGP Subkey>`.
```
(identity_components)=
(identity-components)=
## Identity components
{term}`Identity components<Identity Component>` in an {term}`OpenPGP certificate` are used by the {term}`certificate holder` to state that they are known by a certain identifier (like a name, or an email address).
(user_ids_in_openpgp_certificates)=
(user-ids-in-openpgp-certificates)=
### User IDs in OpenPGP certificates
{term}`OpenPGP certificates<OpenPGP Certificate>` can contain multiple [User IDs](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#uid). Each {term}`User ID` associates the {term}`certificate<OpenPGP Certificate>` with an {term}`identity`.
@ -162,16 +162,16 @@ The rationale for split {term}`User IDs<User ID>` lies in the distinction betwee
Consider this scenario: A third party is confident about the email-based {term}`identity` of an individual (e.g.,`<alice@example.org>`) and is willing to certify it. However, they might not have sufficient knowledge about the person's name-based {term}`identity` (e.g., `Alice Adams`), so are unwilling to extend the same level of {term}`certification`. Split {term}`User IDs<User ID>` address this dichotomy by allowing distinct {term}`certification` processes for each type of {term}`identity`.
(primary_user_id)=
(primary-user-id)=
### Implications of the Primary User ID
Within a {term}`certificate<OpenPGP Certificate>`, a specific {term}`User ID` is designated as the [Primary User ID](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-primary-user-id).
Each {term}`User ID` carries associated preference settings, such as preferred encryption algorithms, which is detailed in {numref}`zooming_in_user_id`). When a {term}`certificate<OpenPGP Certificate>` is used in the context of a specific {term}`identity`, then the preferences associated with that {term}`identity component` are used. When a {term}`certificate<OpenPGP Certificate>` is used without reference to a specific {term}`identity`, the preferences associated with the {term}`direct key signature`, or the {term}`primary User ID` take precedence by default.
Each {term}`User ID` carries associated preference settings, such as preferred encryption algorithms, which is detailed in {numref}`zooming-in-user-id`). When a {term}`certificate<OpenPGP Certificate>` is used in the context of a specific {term}`identity`, then the preferences associated with that {term}`identity component` are used. When a {term}`certificate<OpenPGP Certificate>` is used without reference to a specific {term}`identity`, the preferences associated with the {term}`direct key signature`, or the {term}`primary User ID` take precedence by default.
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)=
### User attributes in OpenPGP
While
[user attributes](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#user-attribute-packet) are similar to {term}`User IDs<User ID>`, they are less commonly used.
@ -189,18 +189,18 @@ In very abstract terms, the {term}`primary key<OpenPGP Primary Key>` of a {term}
By binding {term}`components<Component>` using digital {term}`signatures<OpenPGP Signature Packet>`, recipients of an {term}`OpenPGP certificate` need only {term}`validate<Validation>` the {term}`authenticity<Authentication>` of the {term}`primary key` to use for their communication partner. Traditionally, this is done by manually verifying the *{term}`fingerprint<OpenPGP Fingerprint>`* of the {term}`primary key<OpenPGP Primary Key>`. Once the {term}`validity<Validation>` of the {term}`primary key<OpenPGP Primary Key>` is confirmed, the {term}`validity<Validation>` of the remaining {term}`components<Component>` can be automatically assessed by the user's OpenPGP software. Generally, {term}`components<Component>` are {term}`valid<Validation>` parts of a {term}`certificate<OpenPGP Certificate>` if there is a statement signed by the {term}`certificate<OpenPGP Certificate>`'s {term}`primary key<OpenPGP Primary Key>` endorsing this {term}`validity<Validation>`.
(metadata_in_certificates)=
(metadata-in-certificates)=
## Metadata in certificates
{term}`OpenPGP certificates<OpenPGP Certificate>`, their {term}`component keys<Component Key>`, and {term}`identities<Identity>` possess {term}`metadata` that is not stored within the {term}`components<Component>` it pertains to. Instead, this {term}`metadata` is stored within signature packets, which are integral to the structure of an OpenPGP certificate.
Key attributes, such as {term}`capabilities<Capability>` (like *signing* or *encryption*) and {term}`expiration times<Expiration Time>`, are examples of {term}`metadata` not stored in the {term}`component key` data. How this {term}`metadata` is stored depends on the {term}`component`:
- **{term}`Primary key<OpenPGP Primary Key>` {term}`metadata`** is defined either through a {term}`direct key signature` on the {term}`primary key<OpenPGP Primary Key>` (preferred in OpenPGP version 6), or by associating the {term}`metadata` with the [Primary User ID](primary_user_id).
- **{term}`Primary key<OpenPGP Primary Key>` {term}`metadata`** is defined either through a {term}`direct key signature` on the {term}`primary key<OpenPGP Primary Key>` (preferred in OpenPGP version 6), or by associating the {term}`metadata` with the [Primary User ID](primary-user-id).
- **{term}`Subkey<OpenPGP Subkey>` {term}`metadata`** is defined within the [subkey binding signature](binding_subkeys) that links the {term}`subkey<OpenPGP Subkey>` to the {term}`certificate<OpenPGP Certificate>`.
- **{term}`Subkey<OpenPGP Subkey>` {term}`metadata`** is defined within the [subkey binding signature](binding-subkeys) that links the {term}`subkey<OpenPGP Subkey>` to the {term}`certificate<OpenPGP Certificate>`.
- **{term}`Identity component` {term}`metadata`** is associated via the [certifying self-signature](bind_ident) that links the {term}`identity` (usually in the form of a {term}`User ID`) to the {term}`certificate<OpenPGP Certificate>`.
- **{term}`Identity component` {term}`metadata`** is associated via the [certifying self-signature](bind-ident) that links the {term}`identity` (usually in the form of a {term}`User ID`) to the {term}`certificate<OpenPGP Certificate>`.
It is crucial to note that the {term}`components<Component>` of an {term}`OpenPGP certificate` remain static after their creation. The use of {term}`signatures<OpenPGP Signature Packet>` to store {term}`metadata` allows for subsequent modifications without altering the original {term}`component<Component>`. For instance, a {term}`certificate holder` can update the {term}`expiration time` of a {term}`component` by issuing a new, superseding {term}`signature<OpenPGP Signature Packet>`.
@ -211,7 +211,7 @@ It is crucial to note that the {term}`components<Component>` of an {term}`OpenPG
{term}`Metadata` can be associated with the {term}`primary key<OpenPGP Primary Key>` using a *{term}`direct key signature`*.
```
(capabilities_key_flags)=
(capabilities-key-flags)=
### Defining operational capabilities of component keys with key flags
Each {term}`component key` has a set of ["key flags"](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#key-flags) that delineate the operations a key can perform.
@ -278,7 +278,7 @@ Notably, {term}`revocations<Revocation>` are not the only means by which {term}`
For more detailed information on {term}`revoking<Revocation>` specific {term}`components<Component>` of a {term}`certificate<OpenPGP Certificate>`, see the section on {ref}`self-revocations`.
(third_party_identity_certifications)=
(third-party-identity-certifications)=
## Third-party (identity) certifications
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)
@ -291,4 +291,4 @@ Take, for instance, a scenario where Bob's OpenPGP software issues a {term}`cert
This process assumes that Bob knows the person known as `Alice Adams` and is confident that `alice@example.org` is indeed Alice's email address. Bob also verifies that the {term}`certificate<OpenPGP Certificate>` his OpenPGP software associates with Alice matches the one Alice uses. In essence, both users must have a {term}`certificate<OpenPGP Certificate>` for Alice with an identical {term}`fingerprint<OpenPGP Fingerprint>`. In OpenPGP version 6, manual {term}`fingerprint<OpenPGP Fingerprint>` comparison by end-users is discouraged, with a replacement {term}`verification` mechanism still under development. The {term}`verification` process must occur over a sufficiently secure channel, such as an end-to-end encrypted video call or a face-to-face meeting.
For more on third-party {term}`certifications<Certification>`, see {ref}`third_party_cert`.
For more on third-party {term}`certifications<Certification>`, see {ref}`third-party-cert`.

2
book/source/compression.md
View file

@ -22,7 +22,7 @@ The series of OpenPGP packets inside the Compressed Data packet can be handled l
## Typical usage
Compressed data packets are often used inside [encrypted data packets](/encryption), or wrapping the data of an [inline-signed message](inline_signature).
Compressed data packets are often used inside [encrypted data packets](/encryption), or wrapping the data of an [inline-signed message](inline-signature).
---

14
book/source/cryptography.md
View file

@ -15,7 +15,7 @@ Cryptographic hash functions have two important properties:
- [**Pre-image resistance**](https://en.wikipedia.org/wiki/Preimage_attack): Given a hash digest, it should be very difficult to determine any data that matches this hash digest (including, but not limited to, the original data the hash represents). This property embodies the concept of a [one-way function](https://en.wikipedia.org/wiki/One-way_function) – a calculation that is easy to perform, but very hard to reverse.
- [**Collision resistance**](https://en.wikipedia.org/wiki/Collision_resistance): It should be very difficult to find two distinct pieces of data that map to the same hash digest.
(message_authentication_codes)=
(message-authentication-codes)=
## Message authentication codes
A [message authentication code](https://en.wikipedia.org/wiki/Message_authentication_code) (MAC), also known as an {term}`authentication tag`, is a small piece of information used to verify the integrity and authenticity of a message.
@ -31,9 +31,9 @@ One application of KDFs is to generate symmetric key material from a password by
A notable KDF for the OpenPGP specification is the [HKDF](https://en.wikipedia.org/wiki/HKDF), which is a key derivation function based on the HMAC.
For detailed information on KDFs and their role in the OpenPGP protocol, see the [encrypted secrets](encrypted_secrets) chapter and the [SEIPDv2](SEIPDv2) section of the encryption chapter.
For detailed information on KDFs and their role in the OpenPGP protocol, see the [encrypted secrets](encrypted-secrets) chapter and the [SEIPDv2](SEIPDv2) section of the encryption chapter.
(symmetric_key_cryptography)=
(symmetric-key-cryptography)=
## Symmetric-key cryptography
[Symmetric-key cryptography](https://en.wikipedia.org/wiki/Symmetric-key_algorithm) uses the same cryptographic key for both encryption and decryption, unlike asymmetric cryptography where a pair of keys is used: a public key for encryption and a corresponding private key for decryption. Symmetric-key cryptographic systems support *encryption/decryption* operations.
@ -55,7 +55,7 @@ Symmetric-key cryptography has major benefits: It is much faster than public-key
However, exchanging the required shared secret is a problem that needs to be solved separately.
[Hybrid cryptosystems](hybrid_cryptosystems) combine the advantages of symmetric-key cryptography with a separate mechanism for managing the shared secret, using public-key cryptography.
[Hybrid cryptosystems](hybrid-cryptosystems) combine the advantages of symmetric-key cryptography with a separate mechanism for managing the shared secret, using public-key cryptography.
### Symmetric-key cryptography in OpenPGP
@ -81,14 +81,14 @@ By addressing the malleability problem, AEAD also counters a variation of the EF
[^efail]: A variation of the [EFAIL](https://en.wikipedia.org/wiki/EFAIL) attack can be prevented by both the MDC and AEAD mechanisms. Also see ["No, PGP is not broken, not even with the Efail vulnerabilities,"](https://proton.me/blog/pgp-vulnerability-efail) especially the section "Malleability Gadget Exfiltration Channel Attack."
(public_key_asymmetric_cryptography)=
(public-key-asymmetric-cryptography)=
## Public-key (asymmetric) cryptography
[Public-key cryptography](https://en.wikipedia.org/wiki/Public-key_cryptography) uses asymmetric pairs of related keys. Each pair consists of a public key and a private key. These systems support encryption, decryption, and digital signature operations.
Unlike symmetric cryptography, participants are not required to pre-arrange a shared secret. In public-key cryptography, the public key material is shared openly for certain cryptographic operations, such as encryption and signature verification, while the private key, kept confidential, is used for operations like decryption and signature creation.
(asymmetric_key_pair)=
(asymmetric-key-pair)=
### Asymmetric cryptographic key pairs
Throughout this document, we will frequently reference asymmetric cryptographic key pairs:
@ -134,7 +134,7 @@ In OpenPGP, digital signatures have diverse applications, extending beyond mere
- [Data signatures](signing_data)
- [Signatures on components](/signing_components)
(hybrid_cryptosystems)=
(hybrid-cryptosystems)=
## Hybrid cryptosystems
[Hybrid cryptosystems](https://en.wikipedia.org/wiki/Hybrid_cryptosystem) combine the use of {term}`symmetric<Symmetric Cryptography>` and {term}`asymmetric (public-key)<Asymmetric Cryptography>` cryptography to capitalize on the strengths of each, namely {term}`symmetric cryptography`'s speed and efficiency and {term}`public-key cryptography<Asymmetric Cryptography>`'s mechanism for secure key exchange.

6
book/source/decryption.md
View file

@ -14,7 +14,7 @@ Typically, all \*ESK packets leading a SEIPD packet contain the same *session ke
```{note}
Anonymous-recipient PKESK packets contain a recipient-Key ID of `0`, so if no suitable non-anonymous PKESK was found, any anonymous PKESKs are tried with any available decryption (sub-) keys (see [](decryption_anonymous_recipient)).
Anonymous-recipient PKESK packets contain a recipient-Key ID of `0`, so if no suitable non-anonymous PKESK was found, any anonymous PKESKs are tried with any available decryption (sub-) keys (see [](decryption-anonymous-recipient)).
```
If no suitable PKESK packets were found, SKESK packets are tried next, meaning the user is typically prompted to enter a decryption passphrase.
@ -64,7 +64,7 @@ When the direct method is used, the symmetric cipher algorithm ID of the SKESK p
Otherwise, the cipher algorithm ID to decrypt the SEIPD packet was prefixed to the decrypted session key.
Sanitizing this algorithm ID of the decrypted session key acts as a very early quick check to verify that the used passphrase was correct. For further validation of the session key, see [](decryption_seipd_quick_check).
Sanitizing this algorithm ID of the decrypted session key acts as a very early quick check to verify that the used passphrase was correct. For further validation of the session key, see [](decryption-seipd-quick-check).
### SKESK v6
@ -92,7 +92,7 @@ More common than SKESK packets are PKESK packets which are used to protect the s
### PKESK v3
With version 3 PKESKs, the recipient's secret encryption (sub-) key is directly used to decrypt the encrypted *session key*.
The Key ID of the subkey to be used is recorded in the PKESKs key-id field. A value of `0` indicates an anonymous recipient (see [](decryption_anonymous_recipient)).
The Key ID of the subkey to be used is recorded in the PKESKs key-id field. A value of `0` indicates an anonymous recipient (see [](decryption-anonymous-recipient)).
To detect, which symmetric cipher is used to decrypt the SEIPDv1 packet later on, each public key algorithm uses a slightly different encoding to unpack the symmetric algorithm tag from the decrypted session key. See the respective sections[^rsa-spec] [^elgamal-spec] [^ecdh-spec] [^x25519-spec] [^x448-spec] of the standard. Typically, the cipher algorithm ID is prefixed to the actual session key.

4
book/source/encryption.md
View file

@ -54,7 +54,7 @@ SEIPD packets are used in combination with two mechanisms that store *session ke
- [Public-Key Encrypted Session Key](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-public-key-encrypted-sessio) (PKESK) packets and
- [Symmetric-Key Encrypted Session Key](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#skesk) (SKESK) packets.
The typical combination of mechanisms for encryption in OpenPGP is a [hybrid cryptosystem](hybrid_cryptosystems), consisting of one or more [Public-Key Encrypted Session Key](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-public-key-encrypted-sessio) packets (PKESK), followed by a [Symmetrically Encrypted Integrity Protected Data](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-symmetrically-encrypted-int) (SEIPD) packet.
The typical combination of mechanisms for encryption in OpenPGP is a [hybrid cryptosystem](hybrid-cryptosystems), consisting of one or more [Public-Key Encrypted Session Key](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-public-key-encrypted-sessio) packets (PKESK), followed by a [Symmetrically Encrypted Integrity Protected Data](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-symmetrically-encrypted-int) (SEIPD) packet.
In this combination, an asymmetric cryptographic mechanism is used to protect a *session key* inside PKESK packets. The *session key*, in turn, is used to protect the plaintext using symmetric-key encryption in a SEIPD packet.
@ -123,7 +123,7 @@ When communicating with a mix of recipients, some of whose OpenPGP software only
With SEIPDv1, the session key is directly used as message key to encrypt the payload
```
(SEIPDv2)=
(seipdv2)=
### v2 SEIPD, based on AEAD
The [version 2 SEIPD](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#version-two-seipd) mechanism was introduced in OpenPGP version 6. Consequently, it can only be used for encryption when all recipients explicitly announce support for it using a *Feature* signature subpacket.

86
book/source/glossary.md
View file

@ -17,10 +17,10 @@ AEAD Algorithm
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).
See [](change-algorithm-preferences).
Asymmetric Cryptography
Asymmetric cryptography is used in OpenPGP. For a more detailed discussion see [](public_key_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.
@ -32,7 +32,7 @@ Authentication
The term "authentication" here is semantically different from the one used in {term}`Authentication Key Flag`.
Authentication Key Flag
A {term}`Key Flag`, which indicates that a {term}`Component Key` can be used to confirm control over {term}`private key material` against a remote system. The term "authentication" here is semantically different from {term}`Authentication`. See [](capabilities_key_flags).
A {term}`Key Flag`, which indicates that a {term}`Component Key` can be used to confirm control over {term}`private key material` against a remote system. The term "authentication" here is semantically different from {term}`Authentication`. See [](capabilities-key-flags).
Authentication Tag
See {term}`Message Authentication Code`.
@ -49,18 +49,18 @@ Binary Signature
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.
See {ref}`binding-sigs` for more.
Binding Signature
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.
See {ref}`binding-sigs` for more.
CA
See {term}`Certification Authority`.
Capability
The operations an {term}`OpenPGP Component Key` can perform. See [](capabilities_key_flags).
The operations an {term}`OpenPGP Component Key` can perform. See [](capabilities-key-flags).
Certificate
See {term}`OpenPGP Certificate`
@ -74,13 +74,13 @@ Certificate Holder
Certification
A certification, in OpenPGP, is a signature that makes a statement about an {term}`identity` in a {term}`certificate<OpenPGP Certificate>`, or an entire {term}`certificate<OpenPGP Certificate>`.
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>`.
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).
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`.
@ -122,7 +122,7 @@ Creator
See {term}`Issuer`.
Criticality Flag
A flag on {term}`Subpacket`s, that defines their criticality, which is used for validation. See [](criticality_of_subpackets).
A flag on {term}`Subpacket`s, that defines their criticality, which is used for validation. See [](criticality-of-subpackets).
Cryptographic Key
A {term}`symmetric<Symmetric Cryptography>` or {term}`asymmetric<Asymmetric Cryptography>` cryptographic key is used for signing and encryption operations. See [](cryptography).
@ -151,10 +151,10 @@ Delegation
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).
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 {term}`features<Features Subpacket>` 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`.
@ -162,7 +162,7 @@ Embedded Signature Subpacket
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).
A {term}`Key Flag`, indicating that a {term}`Component Key` can be used for encrypting data. See [](capabilities-key-flags).
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.
@ -173,7 +173,7 @@ Expiration Time
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).
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)
@ -183,7 +183,7 @@ 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 [](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).
@ -197,13 +197,13 @@ 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).
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).
Hashed Subpacket
An {term}`OpenPGP Signature Subpacket` residing in the {term}`Hashed Area` of an {term}`OpenPGP Signature Packet`.
Hybrid Cryptosystem
A cryptographic system that employs both {term}`Asymmetric Cryptography` and {term}`Symmetric Cryptography`. See [](hybrid_cryptosystems).
A cryptographic system that employs both {term}`Asymmetric Cryptography` and {term}`Symmetric Cryptography`. See [](hybrid-cryptosystems).
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`.
@ -215,7 +215,7 @@ 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`.
Identity Component
Part of an {term}`OpenPGP Certificate`, that is used to associate data about the {term}`Certificate Holder` with it. See [](identity_components) for further details.
Part of an {term}`OpenPGP Certificate`, that is used to associate data about the {term}`Certificate Holder` with it. See [](identity-components) for further details.
Identity Verification
A process by which the {term}`Identity Claim` of a {term}`Certificate Holder` is verified. See also {term}`Signature Verification`.
@ -224,7 +224,7 @@ 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).
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`.
@ -246,7 +246,7 @@ Key
- asymmetric private key
- {term}`Symmetric Secret Key`
Additionally, in OpenPGP, asymmetric cryptographic keys are used on [three different layers](layers_of_keys_in_openpgp) of abstraction:
Additionally, in OpenPGP, asymmetric cryptographic keys are used on [three different layers](layers-of-keys-in-openpgp) of abstraction:
- cryptographic key
- OpenPGP component key
@ -258,7 +258,7 @@ Key Expiration Time Subpacket
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).
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`.
@ -295,19 +295,19 @@ Master Key
See {term}`OpenPGP Primary Key`.
Message Authentication Code
A piece of information used for integrity and {term}`authenticity<Authentication>` verification of a message. See [](message_authentication_codes).
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).
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).
Notation
A mechanism for a {term}`Certificate Holder` to provide user-defined data using a {term}`Notation Signature Subpacket`.
Notation Signature Subpacket
An {term}`OpenPGP Signature Subpacket` which is used to add user-defined data to a {term}`Certificate`. See [](notation_signature_subpackets).
An {term}`OpenPGP Signature Subpacket` which is used to add user-defined data to a {term}`Certificate`. See [](notation-signature-subpackets).
Notation Tag
Part of a {term}`Notation` name.
@ -319,7 +319,7 @@ OpenPGP Certificate
An OpenPGP certificate contains public key material, identity claims and third party certifications (but no private key material)
OpenPGP Component Key
An {term}`OpenPGP Primary Key` or {term}`OpenPGP Subkey`. For an in-depth discussion see [](component_keys).
An {term}`OpenPGP Primary Key` or {term}`OpenPGP Subkey`. For an in-depth discussion see [](component-keys).
OpenPGP Fingerprint
An OpenPGP Fingerprint is a shorthand representation of an {term}`OpenPGP Component Key`. Fingerprints effectively act as unique identifiers. See [](fingerprint).
@ -342,7 +342,7 @@ OpenPGP Private Key
See {term}`Transferable Secret Key`.
OpenPGP Primary Key
An {term}`OpenPGP Component Key` that is used in the primary key role of an {term}`OpenPGP Certificate`. For a more detailed discussion, see [](primary_key).
An {term}`OpenPGP Component Key` that is used in the primary key role of an {term}`OpenPGP Certificate`. For a more detailed discussion, see [](primary-key).
OpenPGP Signature
See {term}`OpenPGP Signature Packet`.
@ -351,13 +351,13 @@ OpenPGP Signature Packet
A {term}`packet` that contains a raw {term}`cryptographic signature`, a {term}`Signature Type ID` and additional {term}`metadata`. See [](/signatures). Basic concepts are introduced in [](/signatures) and more detailed use-cases are explained in [](/signing_data) and [](/signing_components).
OpenPGP Signature Subpacket
A data structure in a {term}`Signature Packet`, that describes {term}`metadata` and preferences. See [](signature_subpackets).
A data structure in a {term}`Signature Packet`, that describes {term}`metadata` and preferences. See [](signature-subpackets).
OpenPGP Signature Subpacket Type
An {term}`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).
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`.
@ -383,7 +383,7 @@ Packet Type ID
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).
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.
@ -418,12 +418,12 @@ 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).
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).
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`.
@ -435,7 +435,7 @@ Primary User ID Binding Signature
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).
See [](self-signature-binding-to-primary-user-id).
Private Key
See {term}`Transferable Secret Key`.
@ -447,7 +447,7 @@ Public Key
See {term}`OpenPGP Public Key`.
Public Key Algorithm
An {term}`asymmetric cryptographic<Asymmetric Cryptography>` algorithm. See [](public_key_asymmetric_cryptography).
An {term}`asymmetric cryptographic<Asymmetric Cryptography>` algorithm. See [](public-key-asymmetric-cryptography).
Public Key Cryptography
See {term}`Asymmetric Cryptography`.
@ -515,7 +515,7 @@ Session Key
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 [](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).
@ -563,7 +563,7 @@ 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).
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`.
@ -581,7 +581,7 @@ 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).
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`.
@ -595,7 +595,7 @@ Subpacket Type
See {term}`OpenPGP Signature Subpacket Type`.
Symmetric Cryptography
Symmetric cryptography is used in OpenPGP. For a more detailed discussion see [](symmetric_key_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.
@ -609,7 +609,7 @@ 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).
{term}`Certification` by third-parties to confirm ownership of an {term}`OpenPGP Certificate` by a {term}`Certificate Holder`. See [](third-party-identity-certifications).
Third-party Signature
A {term}`Signature` by a third-party on a {term}`Component` of a {term}`Certificate`.
@ -621,7 +621,7 @@ 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 [](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
@ -630,13 +630,13 @@ Trust Anchor
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).
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).
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 Root
See {term}`Trust Anchor`.
@ -661,16 +661,16 @@ Type ID
See {term}`Signature Type ID`.
Unhashed Area
An area in a {term}`Signature Packet` containing {term}`Signature Subpacket`s, that is *not* covered by the {term}`Hash Digest` a {term}`Cryptographic Signature` is created for. See [](hashed_and_unhashed_signature_subpackets).
An area in a {term}`Signature Packet` containing {term}`Signature Subpacket`s, that is *not* covered by the {term}`Hash Digest` a {term}`Cryptographic Signature` is created for. See [](hashed-and-unhashed-signature-subpackets).
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).
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).
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`.

2
book/source/migration.md
View file

@ -28,7 +28,7 @@ Existing OpenPGP v4 keys can simply announce support for SEIPD v2 via a *Feature
Senders who can produce this new encryption mode can then opt to use it when encrypting to this recipient.
(migration_s2k)=
(migration-s2k)=
### S2K usage mode AEAD
Another good example is the S2K mechanism for secret-key encryption.

6
book/source/openpgp.md
View file

@ -59,7 +59,7 @@ An extension for Elliptic Curve Cryptography was defined in [RFC 6637](https://w
Some implementations explored other non-standardized extensions. Notably, algorithms based on Curve 25519 were tentatively defined in the [rfc4880bis](https://www.ietf.org/archive/id/draft-ietf-openpgp-rfc4880bis-10.html#name-elliptic-curve-cryptography) document. These algorithms are widely used, even though rfc4880bis has never been finalized as a new version of the standard.
(major_implementations)=
(major-implementations)=
### Major implementations of OpenPGP
Today, multiple implementations of OpenPGP play important roles:
@ -69,10 +69,10 @@ Today, multiple implementations of OpenPGP play important roles:
- Proton Mail, which provides email encryption services for a large number of users, uses and maintains [OpenPGP.js](https://openpgpjs.org/) as well as [GopenPGP](https://gopenpgp.org/), an OpenPGP wrapper library written in golang.
- The RPM Package Manager software includes an OpenPGP backend based on [Sequoia PGP](https://sequoia-pgp.org/), a modern OpenPGP implementation written in Rust. The Fedora Linux operating system [uses Sequoia PGP in rpm](https://sequoia-pgp.org/blog/2023/04/27/rpm-sequoia/) since version 38.
(interop_section)=
(interop-section)=
### Interoperability
OpenPGP was standardized in 1997 to encourage development of interoperable implementations. This has already been a success early on, but in recent years, there has been [much development of new implementations](major_implementations).
OpenPGP was standardized in 1997 to encourage development of interoperable implementations. This has already been a success early on, but in recent years, there has been [much development of new implementations](major-implementations).
Historically, interoperability has only been tested in an adhoc manner. Since 2019, the Sequoia project is maintaining and operating the ["OpenPGP interoperability test suite"](https://tests.sequoia-pgp.org/), for more rigorous and systematic testing. The test suite has identified numerous [issues](https://gitlab.com/sequoia-pgp/openpgp-interoperability-test-suite#hall-of-fame).

2
book/source/private_keys.md
View file

@ -54,7 +54,7 @@ Transferable secret keys are sometimes colloquially referred to as "OpenPGP priv
Historically, the concept of TSKs, which combine all elements of an OpenPGP certificate with the associated private key material, has sometimes been conflated with OpenPGP private key operations. However, TSKs are primarily a format for storage and transport; it is generally considered inappropriate as a data structure for use in a private keystore. For further details, see {ref}`key-store-design`.
(encrypted_secrets)=
(encrypted-secrets)=
## Protecting keys with passphrases
In the OpenPGP format, private key material can be optionally protected with a [passphrase](https://en.wikipedia.org/wiki/Passphrase).

14
book/source/signatures.md
View file

@ -33,7 +33,7 @@ An "{term}`OpenPGP Signature Packet`"
In this document, "{term}`signature<OpenPGP Signature Packet>`" will refer to {term}`OpenPGP signature packets<OpenPGP signature packet>`.
(signature_types)=
(signature-types)=
## Signature types in OpenPGP
The OpenPGP standard defines a set of [Signature types](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-signature-types), each identified by a numerical *{term}`signature type ID`*. {term}`Signature types<OpenPGP Signature Type>` define the purpose of a {term}`signature packet<OpenPGP Signature Packet>` and how it should be interpreted.
@ -64,7 +64,7 @@ For more detail about specific {term}`types of signatures<OpenPGP Signature Type
As outlined above, an {term}`OpenPGP signature<OpenPGP Signature Packet>` is a composite data structure, which combines:
- **{term}`Signature type ID`**: specifies the {term}`signature<OpenPGP Signature Packet>`'s intended meaning, as detailed above
- **{term}`Metadata`**: varies based, in part, on the {term}`signature type ID`; mostly encoded as "{term}`subpackets<OpenPGP Signature Subpacket>`" (see {ref}`signature_subpackets`)
- **{term}`Metadata`**: varies based, in part, on the {term}`signature type ID`; mostly encoded as "{term}`subpackets<OpenPGP Signature Subpacket>`" (see {ref}`signature-subpackets`)
- **Raw {term}`cryptographic signature`**
```{figure} plain_svg/OpenPGP_Signature_packet_2.svg
@ -76,8 +76,8 @@ Structure and context of an {term}`OpenPGP signature packet`
The input data packets differ between specific signature types. Also see {numref}`fig-signature-types`. For example:
- for a [*binary data signature*](data_signature_types), the input data packet is a *literal data packet*, while
- for a [*subkey binding signature*](bind_subkey), the input data packets consist of a primary and a subkey packet.
- for a [*binary data signature*](data-signature-types), the input data packet is a *literal data packet*, while
- for a [*subkey binding signature*](bind-subkey), the input data packets consist of a primary and a subkey packet.
### Creating an OpenPGP signature packet
@ -122,7 +122,7 @@ After calculating the {term}`hash digest` from the input data, a {term}`signatur
Verifying a {term}`signature<OpenPGP Signature Packet>` in OpenPGP
```
(signature_subpackets)=
(signature-subpackets)=
## Signature subpackets
In the OpenPGP protocol, {term}`signature subpackets<OpenPGP Signature Subpacket>` enhance the expressiveness of a {term}`signature<OpenPGP Signature Packet>` beyond what is conveyed by just the bare {term}`cryptographic signature` and the {term}`signature type ID`. These {term}`subpackets<OpenPGP Signature Subpacket>`, introduced in [RFC 2440](https://datatracker.ietf.org/doc/html/rfc2440), are essential for embedding additional {term}`metadata` within {term}`signature packets<OpenPGP Signature Packet>`.
@ -134,7 +134,7 @@ They are formatted as key-value pairs, where the keys are defined as [subpacket
- The [*issuer fingerprint*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#issuer-fingerprint-subpacket) {term}`subpacket<OpenPGP Signature Subpacket>` encodes the {term}`fingerprint<OpenPGP Fingerprint>` of the {term}`component key` that issued the {term}`signature<OpenPGP Signature Packet>`.
- The [*key flags*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags) {term}`subpacket<OpenPGP Signature Subpacket>` defines the {term}`capabilities<capability>` that are assigned to a {term}`component key` within a {term}`certificate<OpenPGP Certificate>`.
(hashed_and_unhashed_signature_subpackets)=
(hashed-and-unhashed-signature-subpackets)=
### Hashed and unhashed signature subpackets
{term}`Signature subpackets<OpenPGP Signature Subpacket>` within OpenPGP can reside in one of two distinct areas of a {term}`signature packet<OpenPGP Signature Packet>`, each serving a different purpose.
@ -146,7 +146,7 @@ The majority of {term}`signature subpackets<OpenPGP Signature Subpacket>` are st
For detailed information and specifications, refer to [Hashed vs. Unhashed Subpackets](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-hashed-vs-unhashed-subpacke) in the OpenPGP {term}`RFC`.
(criticality_of_subpackets)=
(criticality-of-subpackets)=
### Criticality of subpackets
In the OpenPGP protocol, each {term}`signature subpacket<OpenPGP Signature Subpacket>` can be marked with a *{term}`criticality flag`*. This flag plays a pivotal role in the interpretation and {term}`validation` of the {term}`signature<OpenPGP Signature Packet>`. When set, it instructs any receiving {term}`implementation<OpenPGP Implementation>` encountering an unrecognized {term}`subpacket type<OpenPGP Signature Subpacket Type>` to treat this as a significant error and to {term}`invalidate<Validation>` the {term}`signature<OpenPGP Signature Packet>`.

30
book/source/signing_components.md
View file

@ -66,14 +66,14 @@ In another instance:
- *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)=
(binding-sigs)=
## Self-signatures in certificate formation and management
{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 {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-12.html#name-transferable-public-keys), {term}`packets<Packet>` can be easily added or removed.
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>`.
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 {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.
@ -81,17 +81,17 @@ Conversely, omissions of {term}`packets<Packet>` by third parties can easily occ
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 {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>`.
- [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)=
(bind-subkey)=
### Binding subkeys to a certificate
{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-12.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 {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.
{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`.
{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} plain_svg/subkey_binding_signature.svg
:name: fig-subkey-binding-signature
@ -108,7 +108,7 @@ The {term}`validity<Validation>` of a {term}`subkey<OpenPGP Subkey>` is intrinsi
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)=
(bind-subkey-sign)=
### Special case: Binding signing subkeys
{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.
@ -131,7 +131,7 @@ Linking an {term}`OpenPGP signing subkey` to the {term}`primary key<OpenPGP Prim
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)=
(bind-ident)=
### Binding identities to a 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`.
@ -168,12 +168,12 @@ The types of {term}`metadata` typically associated with the {term}`certificate<O
- {term}`features<Features Subpacket>`
- {term}`algorithm preferences` signaling
(direct_key_signature)=
(direct-key-signature)=
#### Direct key signature
A [*direct key signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-direct-key-signature-type-i) 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)=
#### Self-signature binding to primary User ID
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`.
@ -209,7 +209,7 @@ Research, under what circumstances revocations revoke individual signatures, and
Note: {term}`certification signatures<Certification>` [can be made irrevocable](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-revocable).
(hard_vs_soft_revocations)=
(hard-vs-soft-revocations)=
#### Hard vs soft revocations
{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*.
@ -221,7 +221,7 @@ Note: {term}`certification signatures<Certification>` [can be made irrevocable](
A {term}`revocation signature packet` lacking a {term}`Reason for Revocation subpacket` is interpreted as a {term}`hard revocation`.
```
(third_party_cert)=
(third-party-cert)=
## Authentication and delegation in third-party signatures
{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>`.
@ -244,7 +244,7 @@ OpenPGP uses [*trust signature*](https://www.ietf.org/archive/id/draft-ietf-open
- {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)=
#### Trust depth/level
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.
@ -255,14 +255,14 @@ However, when the {term}`trust depth` is set higher, it implies a chain of {term
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)=
#### Trust amounts
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 {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)=
#### Limiting delegation scope
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).

10
book/source/signing_data.md
View file

@ -16,10 +16,10 @@ it does not automatically signal if the expected party indeed controls the {term
Note that {term}`data signatures<Data Signature>` are distinct from [](/signing_components), 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)=
(data-signature-types)=
## Signature types
{term}`OpenPGP data signatures<Data Signature>` 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) ({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>`.
@ -28,7 +28,7 @@ Note that {term}`data signatures<Data Signature>` are distinct from [](/signing_
{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)=
## Forms of OpenPGP data signatures
{term}`OpenPGP data signatures<Data Signature>` can be applied in three distinct forms[^sign-modes-gpg]:
@ -45,7 +45,7 @@ A {term}`detached signature` is produced by calculating an {term}`OpenPGP signat
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-signature)=
### Inline signatures
An {term}`inline signature` joins the signed data and its corresponding {term}`data signature` into a single {term}`OpenPGP message`.
@ -129,7 +129,7 @@ The {term}`cleartext signature framework` includes specific text normalization p
- **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 {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>`.
- **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

24
book/source/zoom/certificates.md
View file

@ -9,17 +9,17 @@ Now that we've established the concepts and components that make up OpenPGP cert
## A very minimal OpenPGP certificate
In this section, we will examine a very minimal version of a "public key" variant of [Alice's OpenPGP key](alice_priv), specifically an OpenPGP certificate that excludes private key material.
In this section, we will examine a very minimal version of a "public key" variant of [Alice's OpenPGP key](alice-priv), specifically an OpenPGP certificate that excludes private key material.
To achieve this, we will use the Sequoia-PGP tool `sq` to handle and transform our example OpenPGP key, as well as to inspect internal OpenPGP packet data.
Starting from [Alice's OpenPGP private key](alice_priv), we first produce the corresponding public key/certificate using the following command:
Starting from [Alice's OpenPGP private key](alice-priv), we first produce the corresponding public key/certificate using the following command:
```text
$ sq key extract-cert alice.priv > alice.pub
```
(split_alice)=
(split-alice)=
### Splitting the OpenPGP certificate into packets
To create a very minimal version of Alice's certificate, we will split the data in `alice.pub` into its component packets and reassemble only the relevant ones back into a new variant.
@ -119,7 +119,7 @@ $ sq packet dump --hex alice_minimal.pub
This will allow us to gain a detailed understanding of the packet contents.
(public_key)=
(public-key)=
### Public-Key packet
The output begins with a (primary) [Public-Key packet](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-public-key-packet-formats):
@ -179,7 +179,7 @@ Note that the *Public-Key packet* contains only the public part of the key.
Structure of a Public-Key packet.
```
(zooming_in_dks)=
(zooming-in-dks)=
### Direct Key Signature
The next packet in the certificate is a [*Direct Key Signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#sigtype-direct-key), which plays a crucial role in binding specific information to the primary key. This signature is contained within the file `alice.pub-1--Signature`.
@ -371,7 +371,7 @@ The signature is calculated from this hash digest.
Structure of a direct key signature packet.
```
(zoom_enc_subkey)=
(zoom-enc-subkey)=
## Encryption subkey
Let's now look at a subkey in Alice's OpenPGP certificate. A subkey, when linked to an OpenPGP certificate via its primary key, consists of two elements:
@ -388,7 +388,7 @@ It's common to look at a packet dump for a full OpenPGP certificate as shown bel
$ sq packet dump --hex alice.pub
```
This command shows the details for the full series of packets in an OpenPGP certificate (refer to the list of [packets of Alice's certificate](split_alice)). Finding a particular packet in that list can take a bit of focus and practice though.
This command shows the details for the full series of packets in an OpenPGP certificate (refer to the list of [packets of Alice's certificate](split-alice)). Finding a particular packet in that list can take a bit of focus and practice though.
In the following sections,we make it easier for ourselves by directly examining individual packets from the files we created with `sq packet split` above.
````
@ -418,7 +418,7 @@ Public-Subkey Packet, new CTB, 2 header bytes + 42 bytes
00000020 35 2a 46 01 f3 cc 00 f5 4a 09 3e 3f
```
Notice that the structure of this *Public-Subkey packet* mirrors the primary key's [*Public-Key packet*](public_key) above. However, there are notable differences between the two packets:
Notice that the structure of this *Public-Subkey packet* mirrors the primary key's [*Public-Key packet*](public-key) above. However, there are notable differences between the two packets:
- The packet type ID (`CTB`) in this packet shows type 14 ([*Public-Subkey packet*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-public-subkey-packet-type-i)).
@ -646,12 +646,12 @@ Signature Packet, new CTB, 3 header bytes + 325 bytes
00000140 a6 73 c8 33 5a 9c d9 0a
```
(zooming_in_user_id)=
(zooming-in-user-id)=
## Adding an identity component
In this section, we'll look at an identity associated with Alice's certificate.
User IDs are a mechanism for connecting [identities](identity_components) with an OpenPGP certificate. Typically, a User ID is a string combining a name and an email address.
User IDs are a mechanism for connecting [identities](identity-components) with an OpenPGP certificate. Typically, a User ID is a string combining a name and an email address.
To understand the internal packet structure of this identity and its connection to the OpenPGP certificate, we'll examine two packets that constitute the identity component. One is the [User ID packet](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#uid), located in the file `alice.pub-2--UserID`, which contains identity information. The other is a certifying self-signature, specifically a [Positive certification of a User ID and Public-Key packet](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-positive-certification-of-a) located in the file `alice.pub-3--Signature`. This certification, issued after substantial verification of the identity claim, validates the association between the User ID and the certificate's public key. These packets are snippets from Alice's full OpenPGP certificate.
@ -680,7 +680,7 @@ Essentially, a User ID packet is just a string marked as a User ID by the packet
### Linking the User ID with a certification self-signature
Similar to [linking a subkey](zoom_enc_subkey) to the OpenPGP certificate, a self-signature is used to connect this new component to the certificate.
Similar to [linking a subkey](zoom-enc-subkey) to the OpenPGP certificate, a self-signature is used to connect this new component to the certificate.
To bind identities to a certificate with a self-signature, signature types `0x10` - `0x13` can be used. Here, the signature type `0x13` (*positive certification*) is used.
@ -757,7 +757,7 @@ Signature Packet, new CTB, 2 header bytes + 185 bytes
```
Because this packet structure closely mirrors the [Direct Key Signature](zooming_in_dks) discussed above, we will cover this succinctly.
Because this packet structure closely mirrors the [Direct Key Signature](zooming-in-dks) discussed above, we will cover this succinctly.
We're again looking at a Signature packet. Its `type` is `0x13` ([corresponding to a *positive certification* signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-signature-types)).

2
book/source/zoom/encryption.md
View file

@ -9,7 +9,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0
### Encrypt
We encrypt a short message to Alice, using a public certificate version of {ref}`alice_priv`:
We encrypt a short message to Alice, using a public certificate version of {ref}`alice-priv`:
```text
$ echo "hello world" | sq encrypt --recipient-file alice.pub

8
book/source/zoom/private_keys.md
View file

@ -7,7 +7,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0
## A look at Alice's (unencrypted) private key packets
Let's take a look at the key material packets of [Alice's key](alice_priv).
Let's take a look at the key material packets of [Alice's key](alice-priv).
To inspect the internal structure of Alice's key, we run the Sequoia-PGP tool `sq` (using the `packet dump` subcommand). The output of `sq` is one big block of text. To discuss the relevant content, we'll only show the output for the packets that contain key data, here:
@ -58,7 +58,7 @@ Secret-Key Packet, new CTB, 2 header bytes + 75 bytes
00000040 bd 42 dd 4b e9 a3 36 81 3b a5 cc cf fb
```
The Secret-Key packet consists in large part of the actual cryptographic key data. Notice that its content is almost entirely the same as the Public-Key packet [seen in the previous chapter](public_key). Let's look at the packet field by field:
The Secret-Key packet consists in large part of the actual cryptographic key data. Notice that its content is almost entirely the same as the Public-Key packet [seen in the previous chapter](public-key). Let's look at the packet field by field:
- `CTB: 0xc5`[^CTB]: The [packet type ID](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-packet-headers) for this packet. The binary representation of the value `0xc5` is `11000101`. Bits 7 and 6 show that the packet is in *OpenPGP packet format* (as opposed to in *Legacy packet format*). The remaining 6 bits encode the type ID's value: "5". This is the value for a Secret-Key packet, as shown in the list of [packet type IDs](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-packet-types).
- `length: 0x4b`: The remaining length of this packet.
@ -90,7 +90,7 @@ Note that the *Secret-Key packet* contains both the private and the public part
### Secret-Subkey packet
Further down in the "packet dump" of Alice's key, we see the encryption subkey, which we already inspected in its Public-Subkey packet format, [above](zoom_enc_subkey):
Further down in the "packet dump" of Alice's key, we see the encryption subkey, which we already inspected in its Public-Subkey packet format, [above](zoom-enc-subkey):
```text
Secret-Subkey Packet, new CTB, 2 header bytes + 75 bytes
@ -129,7 +129,7 @@ As with the public key material, the difference between the format of this subke
## Bob's (encrypted) private key material
Now we look at the primary key material packet of [Bob's key](bob_priv), which uses passphrase protection.
Now we look at the primary key material packet of [Bob's key](bob-priv), which uses passphrase protection.
```text
Secret-Key Packet, new CTB, 2 header bytes + 134 bytes

2
book/source/zoom/signatures.md
View file

@ -5,7 +5,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0
# Zooming in: Packet structure of data signatures
In this chapter, we'll create signatures using [Alice's private key](alice_priv) material, and inspect the packet structure of those signatures.
In this chapter, we'll create signatures using [Alice's private key](alice-priv) material, and inspect the packet structure of those signatures.
In some examples, we'll use a test-message that contains the string `hello world` followed by one line feed (`0x0a`) character: