From fd32381839c5929649de63bde8abfcbb27c4f30c Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 15 Nov 2023 00:02:18 +0100 Subject: [PATCH 01/46] ch8: add link anchor --- book/source/08-signing_components.md | 1 + 1 file changed, 1 insertion(+) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index cfafa7f..e94f00b 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -190,6 +190,7 @@ In OpenPGP v6, a direct key signature is the [preferred mechanism](https://www.i In a certificate, one User ID serves as the [*primary* User ID](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-primary-user-id). The metadata in the binding self-signature on this User ID applies to the primary key of the certificate. +(self-revocations)= ### Revocation self-signatures: Invalidating components of a certificate One important class of self-signatures are revocations. From 999549dcc391704e39d4682fc335c2118072343e Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 14 Nov 2023 21:51:14 +0100 Subject: [PATCH 02/46] ch4: elaborate on split User IDs --- book/source/04-certificates.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 254afc9..d8255e1 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -167,11 +167,13 @@ A typical User ID identity is a UTF-8-encoded string composed of a name and an e For further conventions on User IDs, refer to the document [draft-dkg-openpgp-userid-conventions-00](https://datatracker.ietf.org/doc/draft-dkg-openpgp-userid-conventions/), dated 25 August 2023. -One proposed variant for encoding identities in User ID is to use ["split User IDs"](https://dkg.fifthhorseman.net/blog/2021-dkg-openpgp-transition.html#split-user-ids). +**Split User IDs** -```{admonition} Warning -Heiko, please clarify what the value is of this proposal or remove it. -``` +One proposed variant for encoding identities in User ID is to use ["split User IDs"](https://dkg.fifthhorseman.net/blog/2021-dkg-openpgp-transition.html#split-user-ids). This style of User IDs is currently uncommon, but there is no technical impediment to using this format right now. + +An argument for split User IDs is that a name and an email address are two distinct identities, which are easier to reason about separately. This is particularly relevant when third parties consider certifying that an identity is legitimately connected to a certificate. + +For example, some third party may be sure about the email identity of a contact, and happy to issue a certification for an email-based identity (such as ``). But they may not have any insight into a name based identity (such as `Alice Adams`), and thus not willing to certify such a name-based identity. (primary_user_id)= ### Implications of the Primary User ID From c6888559f5598a64eb2095f56c84169a9e731d6f Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 14 Nov 2023 23:03:48 +0100 Subject: [PATCH 03/46] ch4: restructure text about metadata Move "metadata" content into its own section. This section started out as a remark about key flags, and was part of the "component key" section. Generalizing it seems better, so it's now after the "linking" section, which introduces binding self-signatures. --- book/source/04-certificates.md | 73 ++++++++++++++++++---------------- 1 file changed, 39 insertions(+), 34 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index d8255e1..4d5fc61 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -113,40 +113,6 @@ While subkeys have the same structural attributes as the primary key, they fulfi OpenPGP certificates can contain multiple subkeys. ``` -#### Defining operational capabilities with key flags - -Each component key has a set of ["key flags"](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#key-flags) that delineate the operations a key can perform. - -Commonly used key flags include: - -- **Certification**: enables issuing third-party certifications -- **Signing**: allows the key to sign data -- **Encryption**: allows the key to encrypt data -- **Authentication**: primarily used for OpenPGP authentication - -```{note} -Distinct component keys handle specific operations. Only the primary key can be used for certification, although it can have additional capabilities. Subkeys can be used for signing, encryption, and authentication but cannot have the certification capability. It is considered good practice, however, to [use separate keys for each capability](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-10.1.5-7). - -Notably, in many algorithms, encryption and signing-related functionalities (i.e., certification, signing, authentication) are mutually exclusive, because the algorithms only support one of those two families of operations[^key-flag-sharing]). -``` - -[^key-flag-sharing]: With ECC algorithms, it's impossible to combine encryption functions with those intended for signing. For example, ed25519 is specifically used for signing; cv25519 is designated for encryption. - -### Component key metadata, including key flags - -The key flags for a component key are not stored within the component key directly. - -Instead, key flags, along with other metadata about that component key, such as the key expiration time, are stored using mechanisms that bind components into an OpenPGP certificate: - -- For the primary key, its key flags and other metadata can be defined in two ways: they can be linked with the [Primary User ID](primary_user_id) or through a [direct key signature](direct_key_signature). -- For subkeys, the key flags and other metadata are set using the mechanism that binds the subkey to the certificate, specifically through the primary key. Further details on [binding subkeys](binding_subkeys) are below. - -```{admonition} TODO -:class: warning - -Write a section about algorithm preference/feature signaling -``` - (identity_components)= ## Identity components @@ -208,6 +174,45 @@ In very abstract terms, the primary key of a certificate acts as a root of trust By binding components using digital signatures, recipients of an OpenPGP certificate need only validate the authenticity of the primary key to use for their communication partner. Traditionally, this is done by manually verifying the *fingerprint* of the primary key. Once the validity of the primary key is confirmed, the validity of the remaining components can be automatically assessed by the user's OpenPGP software. Generally, components are valid parts of a certificate if there is a statement signed by the certificate's primary key endorsing this validity. +## Metadata: capabilities, preferences, etc + +Much of the metadata in OpenPGP certificates is actually not stored inside the components that the metadata applies to. Instead, much of the metadata for certificates, component keys and identities is defined as a part of the signatures that join components into a certificate. + +For example, the capabilities of a component key (such as *signing* or *encryption*), or the expiration time of a component key, are not encoded as a part of the *packet* that encodes the data of that component key. + +Instead, are stored using mechanisms that bind components into an OpenPGP certificate: + +- For the primary key, its key flags and other metadata can be defined in two ways: they can be linked with the [Primary User ID](primary_user_id) or through a [direct key signature](direct_key_signature). +- For subkeys, the key flags and other metadata are set using the mechanism that binds the subkey to the certificate, specifically through the primary key. Further details on [binding subkeys](binding_subkeys) are below. +- For identity components, like User IDs, metadata is associated via the [certifying self-signature](bind_ident) that links the identity to the certificate. + +### Defining operational capabilities of component keys with key flags + +Each component key has a set of ["key flags"](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#key-flags) that delineate the operations a key can perform. + +Commonly used key flags include: + +- **Certification**: enables issuing third-party certifications +- **Signing**: allows the key to sign data +- **Encryption**: allows the key to encrypt data +- **Authentication**: primarily used for OpenPGP authentication + +```{note} +Distinct component keys handle specific operations. Only the primary key can be used for certification, although it can have additional capabilities. Subkeys can be used for signing, encryption, and authentication but cannot have the certification capability. It is considered good practice, however, to [use separate keys for each capability](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-10.1.5-7). + +Notably, in many algorithms, encryption and signing-related functionalities (i.e., certification, signing, authentication) are mutually exclusive, because the algorithms only support one of those two families of operations[^key-flag-sharing]). +``` + +[^key-flag-sharing]: With ECC algorithms, it's impossible to combine encryption functions with those intended for signing. For example, ed25519 is specifically used for signing; cv25519 is designated for encryption. + +### Algorithm preferences and feature signaling + +```{admonition} TODO +:class: warning + +Write a section about algorithm preference/feature signaling +``` + ## Revocations ```{admonition} TODO From 6f609c7f88cf0d523112fcf6fbc496db4e5cf871 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 14 Nov 2023 23:39:23 +0100 Subject: [PATCH 04/46] ch4: new text about preferences/features --- book/source/04-certificates.md | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 4d5fc61..ec3e9e1 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -207,11 +207,25 @@ Notably, in many algorithms, encryption and signing-related functionalities (i.e ### Algorithm preferences and feature signaling -```{admonition} TODO -:class: warning +OpenPGP has a lot of ["cryptographic agility"](https://en.wikipedia.org/wiki/Cryptographic_agility). That is, OpenPGP doesn't just use one fixed set of algorithms, but defines a suite of cryptographic primitives that users (or their applications) can pick from. -Write a section about algorithm preference/feature signaling -``` +This agility has the advantage that adoption of new cryptographic primitives into the standard is relatively easy, and can be done without disruption. Users can gradually migrate to using new cryptographic mechanisms. + +However, it also means that OpenPGP software needs to figure out which mechanisms a set of communication partners can handle and prefers. To do this, there are a number of mechanisms in OpenPGP that can be negotiated between sender and recipient. The sender interprets the preferences of the recipient: + +- [Preferred Hash Algorithms](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-hashes-subpacket) +- [Preferred Symmetric Ciphers for v1 SEIPD](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-v1-seipd) +- [Preferred AEAD Ciphersuites](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-v2-seipd) +- [Features](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#features-subpacket) +- [Preferred Compression Algorithms](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-compression-subpacket) + +In addition to these explicitly expressed preferences, implementations also deduce capabilities of communication partners based on the OpenPGP version of the certificate that they write to. + +#### User ID-specific preferences + +As a starting point, a certificate has a set of preferences that apply generally. These are defined either in a direct key signature, or via the primary User ID of the certificate. + +Additionally, OpenPGP allows modeling User ID-specific preferences. The idea is that a user may prefer a different suite of algorithms on their private email account compared to their work email account. Such identity-specific preferences can be expressed on the certifying signatures that bind User IDs to a certificate. ## Revocations From 441936eb98d62207f63017dc73e196635fed235b Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 15 Nov 2023 00:02:54 +0100 Subject: [PATCH 05/46] ch4: new text about revocations --- book/source/04-certificates.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index ec3e9e1..cd4bdb7 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -229,11 +229,11 @@ Additionally, OpenPGP allows modeling User ID-specific preferences. The idea is ## Revocations -```{admonition} TODO -:class: warning +When the owner of a certificate wants to invalidate some components of that certificate, or the entire certificate, they can do so by "revoking" the component in question. Revoking the primary key renders the entire certificate invalid. -This section needs to be written -``` +More on revoking components of a certificate in {ref}`self-revocations`. + +Note that there are other ways besides revocations in which components can become invalid. For example, the component's expiration time may have passed. ## Third-party (identity) certifications From 451b881c03b17e7d59cf274a4aa04a29eecaa75a Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 15 Nov 2023 00:03:13 +0100 Subject: [PATCH 06/46] ch4: new text about third-party certifications --- book/source/04-certificates.md | 21 +++++++-------------- 1 file changed, 7 insertions(+), 14 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index cd4bdb7..f3d3bbd 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -237,13 +237,15 @@ Note that there are other ways besides revocations in which components can becom ## Third-party (identity) certifications -```{admonition} TODO -:class: warning +Third-party identity certifications have been a pivotal mechanism in the OpenPGP ecosystem since the beginning. The designers of PGP, beginning with Phil Zimmermann, have favored decentralized trust models, which don't hinge on centralized authorities. -This section needs to be written -``` +Third-party certifications are statements by OpenPGP users who attest that they have confirmed that a particular OpenPGP certificate belongs to a user with a particular identity. -Third-party identity certifications have historically played a pivotal role in the OpenPGP ecosystem. +For example, Bob's OpenPGP software may issue a certification that Bob has checked that the User ID `Alice Adams ` and the certificate with the fingerprint `AAA1 8CBB 2546 85C5 8358 3205 63FD 37B6 7F33 00F9 FB0E C457 378C D29F 1026 98B3` are legitimately linked. + +This presupposes that Bob knows this person who goes by "Alice Adams", and is satisfied that Alice uses the email address `alice@example.org`. Further, that Bob has verified that the certificate his OpenPGP software uses for Alice matches the certificate that Alice is using. Effectively this verification must ensure that both users have a certificate for Alice with the same fingerprint. In OpenPGP version 6, manual comparison of the fingerprint by end users is discouraged. A replacement mechanism is still pending. The verification must use a sufficiently secure channel, for example an end-to-end encrypted video call, or an in-person meeting. + +For more on third-party certifications, see {ref}`third_party_cert`. ### Security considerations @@ -255,15 +257,6 @@ It also opens the door to potential denial-of-service attacks, rendering the cer The popular [SKS keyserver network experienced certificate flooding firsthand](https://dkg.fifthhorseman.net/blog/openpgp-certificate-flooding.html), causing it to shut down operations in 2019. -### Improved mechanisms in OpenPGP v6 - -```{admonition} TODO -:class: warning - -This section needs to be written -``` - - ## Advanced topics ```{admonition} TODO From f35044bd683f2a3a4eac9fd4350066c35d7b291d Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 15 Nov 2023 00:51:00 +0100 Subject: [PATCH 07/46] ch4: move certification flooding section to "advanced" part --- book/source/04-certificates.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index f3d3bbd..637b048 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -247,16 +247,6 @@ This presupposes that Bob knows this person who goes by "Alice Adams", and is sa For more on third-party certifications, see {ref}`third_party_cert`. -### Security considerations - -While a convenience for consumers, indiscriminately accepting and integrating third-party identity certifications comes with significant risks. - -Without any restrictions in place, malicious entities can flood a certificate with excessive certifications. Called "certificate flooding," this form of digital vandalism grossly expands the certificate size, making the certificate cumbersome and impractical for users. - -It also opens the door to potential denial-of-service attacks, rendering the certificate non-functional or significantly impeding its operation. - -The popular [SKS keyserver network experienced certificate flooding firsthand](https://dkg.fifthhorseman.net/blog/openpgp-certificate-flooding.html), causing it to shut down operations in 2019. - ## Advanced topics ```{admonition} TODO @@ -323,3 +313,13 @@ references/links missing ``` Some OpenPGP subsystems 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" to certificates, in this way). + +### Third-party certification flooding + +While a convenience for consumers, indiscriminately accepting and integrating third-party identity certifications comes with significant risks. + +Without any restrictions in place, malicious entities can flood a certificate with excessive certifications. Called "certificate flooding," this form of digital vandalism grossly expands the certificate size, making the certificate cumbersome and impractical for users. + +It also opens the door to potential denial-of-service attacks, rendering the certificate non-functional or significantly impeding its operation. + +The popular [SKS keyserver network experienced certificate flooding firsthand](https://dkg.fifthhorseman.net/blog/openpgp-certificate-flooding.html), causing it to shut down operations in 2019. From d157a4d1fc64e5f991b30280ef2425aa22e67a15 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 18 Nov 2023 17:44:01 +0100 Subject: [PATCH 08/46] move todo into advanced section branch, add link --- book/source/04-certificates.md | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 637b048..3064ea9 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -148,14 +148,7 @@ Within a certificate, a specific User ID is designated as the [Primary User ID]( Each User ID carries associated preference settings, such as preferred encryption algorithms, which is detailed in {numref}`zooming_in_user_id`). The preferences associated with the Primary User ID take precedence by default. -```{admonition} TODO -:class: warning - -i think crypto-refresh suggests that the direct key signature should hold the default preferences? -we might need to write a more nuanced text here, about how DKS and primary user id interact in v6, and mention the differences to v4? - -the primary User ID can also specify metadata about the primary key -``` +The primary User ID was historically sometimes used to store preferences that apply to the certificate as a whole. For more details on this, see {ref}`dks-puid`. ### User attributes in OpenPGP While From 26df966a2c8d4b1d9faf49d74eb825a6c3d28a9c Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 18 Nov 2023 18:54:03 +0100 Subject: [PATCH 09/46] clarify metadata section --- book/source/04-certificates.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 3064ea9..df5db9b 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -169,15 +169,17 @@ By binding components using digital signatures, recipients of an OpenPGP certifi ## Metadata: capabilities, preferences, etc -Much of the metadata in OpenPGP certificates is actually not stored inside the components that the metadata applies to. Instead, much of the metadata for certificates, component keys and identities is defined as a part of the signatures that join components into a certificate. +Much of the metadata for OpenPGP certificates, component keys, and identities, is not actually stored as part of the components that the metadata applies to. -For example, the capabilities of a component key (such as *signing* or *encryption*), or the expiration time of a component key, are not encoded as a part of the *packet* that encodes the data of that component key. +For example, the capabilities of a component key, such as *signing* or *encryption*, as well as its expiration time, are not stored as a part of the data of that component key. -Instead, are stored using mechanisms that bind components into an OpenPGP certificate: +Instead, this kind of metadata is stored as part of the signature packets that join components into an OpenPGP certificate: -- For the primary key, its key flags and other metadata can be defined in two ways: they can be linked with the [Primary User ID](primary_user_id) or through a [direct key signature](direct_key_signature). -- For subkeys, the key flags and other metadata are set using the mechanism that binds the subkey to the certificate, specifically through the primary key. Further details on [binding subkeys](binding_subkeys) are below. -- For identity components, like User IDs, metadata is associated via the [certifying self-signature](bind_ident) that links the identity to the certificate. +- For the primary key, its key flags and other metadata can be defined in two ways: + - With a [direct key signature](direct_key_signature) on the primary key, + - or by associating the metadata with the [Primary User ID](primary_user_id). +- For subkeys, metadata is defined with the [subkey binding signature](binding_subkeys) that links the subkey to the certificate. +- For identity components like User IDs, metadata is associated via the [certifying self-signature](bind_ident) that links the identity to the certificate. ### Defining operational capabilities of component keys with key flags From 15af2240acb1faabb442d3581ff0ea046bdf45a8 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Mon, 20 Nov 2023 15:27:19 +0100 Subject: [PATCH 10/46] ch4: minor edits from wiktor feedback --- book/source/04-certificates.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index df5db9b..abd5035 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -47,7 +47,7 @@ This documentation collectively refers to component keys and identity components Typical components in an OpenPGP certificate ``` -Every element in an OpenPGP certificate revolves around a central component: the *OpenPGP primary key*. The primary key acts as a personal CA (Certification Authority) for the certificate's owner, enabling cryptographic statements regarding subkeys, identities, expiration, revocation, and more. +Every element in an OpenPGP certificate revolves around a central component: the *OpenPGP primary key*. The primary key acts as a personal *certification authority* (CA) for the certificate's owner, enabling cryptographic statements regarding subkeys, identities, expiration, revocation, and more. ```{note} OpenPGP certificates tend to have a long lifespan, with the potential for modifications (typically by their owner) over time. Components may be added or invalidated throughout a certificate's lifetime. @@ -158,7 +158,7 @@ Currently, the OpenPGP standard prescribes only one format to be stored in user ## Linking the components -To form an OpenPGP certificate, individual components are interconnected by the certificate holder using their OpenPGP software. Within OpenPGP, this process is termed "binding," as in "a subkey is bound to the primary key." These bindings are realized using cryptographic signatures. An in-depth discussion of this topic can be found in {ref}`component_signatures_chapter`). +To form an OpenPGP certificate, individual components are interconnected by the certificate holder using their OpenPGP software. Within OpenPGP, this process is termed "binding," as in "a subkey is bound to the primary key." These bindings are realized using cryptographic signatures. An in-depth discussion of this topic can be found in {ref}`component_signatures_chapter`. In very abstract terms, the primary key of a certificate acts as a root of trust or "certification authority." It is responsible for: @@ -195,7 +195,7 @@ Commonly used key flags include: ```{note} Distinct component keys handle specific operations. Only the primary key can be used for certification, although it can have additional capabilities. Subkeys can be used for signing, encryption, and authentication but cannot have the certification capability. It is considered good practice, however, to [use separate keys for each capability](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-10.1.5-7). -Notably, in many algorithms, encryption and signing-related functionalities (i.e., certification, signing, authentication) are mutually exclusive, because the algorithms only support one of those two families of operations[^key-flag-sharing]). +Notably, in many algorithms, encryption and signing-related functionalities (i.e., certification, signing, authentication) are mutually exclusive, because the algorithms only support one of those two families of operations[^key-flag-sharing]. ``` [^key-flag-sharing]: With ECC algorithms, it's impossible to combine encryption functions with those intended for signing. For example, ed25519 is specifically used for signing; cv25519 is designated for encryption. From 1156d4987e1f7402c0adf06911888d39aa8faf02 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Mon, 20 Nov 2023 20:03:08 +0100 Subject: [PATCH 11/46] adjust User ID diagram description --- book/source/04-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index abd5035..d647e12 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -126,7 +126,7 @@ OpenPGP certificates can contain multiple [User IDs](https://www.ietf.org/archiv :name: fig-user-ids :alt: Depicts a diagram with white background and the title "User IDs". Inside, a public primary component key for certification and a User ID is shown. A green arrow points from component key to User ID and is annotated with a signature. -OpenPGP certificates can contain any number of User IDs +Relationship of User ID to primary component key in an OpenPGP certificate ``` A typical User ID identity is a UTF-8-encoded string composed of a name and an email address. By convention, User IDs align with the format described in [RFC2822](https://www.rfc-editor.org/rfc/rfc2822) as a *name-addr*. From 992c878fea254cef727275798cc2b4d1c2be87af Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 21 Nov 2023 10:02:39 +0100 Subject: [PATCH 12/46] This phrasing feels less confusing to me. I think this paragraph needs some more sharpening, but am still unsure about exactly how. --- book/source/04-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index d647e12..55c3d4b 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -26,7 +26,7 @@ In OpenPGP, the term "key" may refer to three distinct layers, each serving a un The following section will delve into the OpenPGP-specific layers (2 and 3) to provide a clearer understanding of their roles within OpenPGP certificates. -For a discussion of private key material in OpenPGP, see the chapter {ref}`private_key_chapter`. Bindings that connect the components of a certificate are discussed in our chapter {ref}`component_signatures_chapter`. For much more detail on the internal (packet) structure of certificates and keys refer to our chapter {ref}`zoom_certificates`. Additionally, managing certificates, and understanding their authentication and trust models are vital topics. While this document briefly touches upon these aspects, they are integral to working proficiently with OpenPGP. +For a discussion of private key material in OpenPGP, see the chapter {ref}`private_key_chapter`. Bindings that connect the components of a certificate are discussed in our chapter {ref}`component_signatures_chapter`. For much more detail on the internal (packet) structure of certificates and keys refer to our chapter {ref}`zoom_certificates`. Additionally, managing certificates, and understanding their authentication and trust models are vital topics. While this document only touches upon these aspects briefly, they are integral to working proficiently with OpenPGP. ## Structure of OpenPGP certificates From ff198a3413b2f6ea6a6b46b5ddec16c641d73ef0 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 21 Nov 2023 10:08:12 +0100 Subject: [PATCH 13/46] Clarify authentication key flag --- book/source/04-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 55c3d4b..2ceb0cc 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -190,7 +190,7 @@ Commonly used key flags include: - **Certification**: enables issuing third-party certifications - **Signing**: allows the key to sign data - **Encryption**: allows the key to encrypt data -- **Authentication**: primarily used for OpenPGP authentication +- **Authentication**: primarily used for SSH authentication ```{note} Distinct component keys handle specific operations. Only the primary key can be used for certification, although it can have additional capabilities. Subkeys can be used for signing, encryption, and authentication but cannot have the certification capability. It is considered good practice, however, to [use separate keys for each capability](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-10.1.5-7). From 42b9e98e211638b83935c3ab482fa556478abd5d Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 21 Nov 2023 10:13:32 +0100 Subject: [PATCH 14/46] clarify that "authentication" key flag is not about validating user ids --- book/source/04-certificates.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 2ceb0cc..f0220bb 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -190,7 +190,9 @@ Commonly used key flags include: - **Certification**: enables issuing third-party certifications - **Signing**: allows the key to sign data - **Encryption**: allows the key to encrypt data -- **Authentication**: primarily used for SSH authentication +- **Authentication**: primarily used for SSH authentication[^auth-flag] + +[^auth-flag]: Note that the capability offered by the [authentication](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-authentication-via-digital-) key flag is unrelated to "authentication" in the context of certifying and verifying OpenPGP identities and their connection to certificates. This key flag is about a mechanism that proves control of private key material to a remote system, using cryptographic signatures. ```{note} Distinct component keys handle specific operations. Only the primary key can be used for certification, although it can have additional capabilities. Subkeys can be used for signing, encryption, and authentication but cannot have the certification capability. It is considered good practice, however, to [use separate keys for each capability](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-10.1.5-7). From ade8edd697b628c040917830a21a1df3e3512e9e Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 21 Nov 2023 10:31:41 +0100 Subject: [PATCH 15/46] link to cryptographic hashes --- book/source/03-cryptography.md | 1 + book/source/04-certificates.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/book/source/03-cryptography.md b/book/source/03-cryptography.md index 560d24e..166e869 100644 --- a/book/source/03-cryptography.md +++ b/book/source/03-cryptography.md @@ -6,6 +6,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 (cryptography_chapter)= # Cryptographic concepts and terms +(crypto-hash)= ## Cryptographic hash functions [Cryptographic hash functions](https://en.wikipedia.org/wiki/Cryptographic_hash_function) take data strings of any length (like a text message or file) and output a fixed-size code, a "hash digest," which is often abbreviated as either "digest" or "hash." A hash digest acts like a unique identifier for the original data. diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index f0220bb..b0119ad 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -78,7 +78,7 @@ Each OpenPGP component key possesses an *OpenPGP fingerprint*. This fingerprint :name: fig-fingerprint :alt: Depicts a box with white background and the title "Fingerprint of an OpenPGP component key". Inside, another box with a green frame, the title "Component Key", the text "key creation time" on the lower left and a the green public key symbol on the lower right is shown. Below the component key box a fingerprint in a box with a light-yellow background and a yellow dotted line is depicted. The word "Fingerprint" is shown left of the box with the fingerprint and both are connected with a yellow dotted line. -Every OpenPGP component key is identifiable by a fingerprint. Although it's technically possible for different keys to share a fingerprint, cryptographic mechanisms make it exceedingly difficult, if not practically impossible with current technology, to find keys that share a fingerprint. +Every OpenPGP component key is identifiable by a fingerprint. Although it's technically possible for different keys to share a fingerprint, [cryptographic mechanisms](crypto-hash) make it exceedingly difficult, if not practically impossible with current technology, to find keys that share a fingerprint. ``` The fingerprint of our example OpenPGP component key is `C0A5 8384 A438 E5A1 4F73 7124 26A4 D45D BAEE F4A3 9E6B 30B0 9D55 13F9 78AC CA94`[^keyid]. From ae2c732730acb2691538aa950098560caaaa2cdf Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 21 Nov 2023 12:30:18 +0100 Subject: [PATCH 16/46] Note that DKS is preferred in v6 --- book/source/04-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index b0119ad..b99fe94 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -176,7 +176,7 @@ For example, the capabilities of a component key, such as *signing* or *encrypti Instead, this kind of metadata is stored as part of the signature packets that join components into an OpenPGP certificate: - For the primary key, its key flags and other metadata can be defined in two ways: - - With a [direct key signature](direct_key_signature) on the primary key, + - With a [direct key signature](direct_key_signature) on the primary key (preferred method in OpenPGP version 6), - or by associating the metadata with the [Primary User ID](primary_user_id). - For subkeys, metadata is defined with the [subkey binding signature](binding_subkeys) that links the subkey to the certificate. - For identity components like User IDs, metadata is associated via the [certifying self-signature](bind_ident) that links the identity to the certificate. From 4a39b205869276088a154cd098ece1809677eb43 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 22 Nov 2023 15:16:07 +0100 Subject: [PATCH 17/46] ch4: clarify primary user id section --- book/source/04-certificates.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index b99fe94..bdce127 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -146,9 +146,9 @@ For example, some third party may be sure about the email identity of a contact, Within a certificate, a specific User ID is designated as the [Primary User ID](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-primary-user-id). -Each User ID carries associated preference settings, such as preferred encryption algorithms, which is detailed in {numref}`zooming_in_user_id`). The preferences associated with the Primary User ID take precedence by default. +Each User ID carries associated preference settings, such as preferred encryption algorithms, which is detailed in {numref}`zooming_in_user_id`). When a certificate is used in the context of a specific identity, then the preferences associated with that identity component are used. When a certificate is used without reference to a specific identity, the preferences associated with the direct key signature, or the primary User ID take precedence by default. -The primary User ID was historically sometimes used to store preferences that apply to the certificate as a whole. For more details on this, see {ref}`dks-puid`. +The primary User ID was historically the main store for preferences that apply to the certificate as a whole. For more on this, see {ref}`primary-metadata`. ### User attributes in OpenPGP While From 2f4a794d1c29fed0b70b6634a372ab81c51b7c67 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 22 Nov 2023 16:26:17 +0100 Subject: [PATCH 18/46] ch8: add link anchor --- book/source/08-signing_components.md | 1 + 1 file changed, 1 insertion(+) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index e94f00b..8eda52e 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -302,6 +302,7 @@ For example, Alice could delegate trust decisions only for email addresses in th add diagrams? ``` +(wot)= ### Decentralized automated trust decisions; or, the "Web of Trust" The OpenPGP, the "Web of Trust" is a trust model that performs authentication decisions on a set of certifications and delegations. From 166ab7bc55b6ab890e3b3d59dc12f97897d453f6 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 22 Nov 2023 16:54:59 +0100 Subject: [PATCH 19/46] mention "wot" and link to ch8 section --- book/source/04-certificates.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index bdce127..9b328c9 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -234,13 +234,13 @@ Note that there are other ways besides revocations in which components can becom ## Third-party (identity) certifications -Third-party identity certifications have been a pivotal mechanism in the OpenPGP ecosystem since the beginning. The designers of PGP, beginning with Phil Zimmermann, have favored decentralized trust models, which don't hinge on centralized authorities. +Third-party identity certifications have been a pivotal mechanism in the OpenPGP ecosystem since the beginning. The designers of PGP, beginning with Phil Zimmermann, have favored decentralized trust models, which don't hinge on centralized authorities. OpenPGP's decentralized trust model is called the ["Web of Trust."](wot) Third-party certifications are statements by OpenPGP users who attest that they have confirmed that a particular OpenPGP certificate belongs to a user with a particular identity. For example, Bob's OpenPGP software may issue a certification that Bob has checked that the User ID `Alice Adams ` and the certificate with the fingerprint `AAA1 8CBB 2546 85C5 8358 3205 63FD 37B6 7F33 00F9 FB0E C457 378C D29F 1026 98B3` are legitimately linked. -This presupposes that Bob knows this person who goes by "Alice Adams", and is satisfied that Alice uses the email address `alice@example.org`. Further, that Bob has verified that the certificate his OpenPGP software uses for Alice matches the certificate that Alice is using. Effectively this verification must ensure that both users have a certificate for Alice with the same fingerprint. In OpenPGP version 6, manual comparison of the fingerprint by end users is discouraged. A replacement mechanism is still pending. The verification must use a sufficiently secure channel, for example an end-to-end encrypted video call, or an in-person meeting. +This presupposes that Bob knows this person who goes by "Alice Adams", and is satisfied that Alice uses the email address `alice@example.org`. Further, that Bob has verified that the certificate his OpenPGP software uses for Alice matches the certificate that Alice is using. Effectively, this verification must ensure that both users have a certificate for Alice with the same fingerprint. In OpenPGP version 6, manual comparison of the fingerprint by end users is discouraged. A replacement mechanism is still pending. The verification must use a sufficiently secure channel, for example an end-to-end encrypted video call, or an in-person meeting. For more on third-party certifications, see {ref}`third_party_cert`. From 6757b47f81e14ce48004d1f60e0d55a502f86a65 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 22 Nov 2023 17:03:55 +0100 Subject: [PATCH 20/46] ch4: minor edits --- book/source/04-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 9b328c9..8611056 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -240,7 +240,7 @@ Third-party certifications are statements by OpenPGP users who attest that they For example, Bob's OpenPGP software may issue a certification that Bob has checked that the User ID `Alice Adams ` and the certificate with the fingerprint `AAA1 8CBB 2546 85C5 8358 3205 63FD 37B6 7F33 00F9 FB0E C457 378C D29F 1026 98B3` are legitimately linked. -This presupposes that Bob knows this person who goes by "Alice Adams", and is satisfied that Alice uses the email address `alice@example.org`. Further, that Bob has verified that the certificate his OpenPGP software uses for Alice matches the certificate that Alice is using. Effectively, this verification must ensure that both users have a certificate for Alice with the same fingerprint. In OpenPGP version 6, manual comparison of the fingerprint by end users is discouraged. A replacement mechanism is still pending. The verification must use a sufficiently secure channel, for example an end-to-end encrypted video call, or an in-person meeting. +This presupposes that Bob knows this person who goes by "Alice Adams," and is satisfied that Alice uses the email address `alice@example.org`. Further, that Bob has verified that the certificate his OpenPGP software uses for Alice matches the certificate that Alice is using. Effectively, this verification must ensure that both users have a certificate for Alice with the same fingerprint. In OpenPGP version 6, manual comparison of the fingerprint by end users is discouraged. A replacement mechanism is still pending. The verification must use a sufficiently secure channel, for example, an end-to-end encrypted video call, or an in-person meeting. For more on third-party certifications, see {ref}`third_party_cert`. From c575165cd34997018907ae646635f9a3b4689a15 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 22 Nov 2023 17:09:14 +0100 Subject: [PATCH 21/46] ch4: clarify/link "certificates are effectively append-only" --- book/source/04-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 8611056..13f32b2 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -50,7 +50,7 @@ Typical components in an OpenPGP certificate Every element in an OpenPGP certificate revolves around a central component: the *OpenPGP primary key*. The primary key acts as a personal *certification authority* (CA) for the certificate's owner, enabling cryptographic statements regarding subkeys, identities, expiration, revocation, and more. ```{note} -OpenPGP certificates tend to have a long lifespan, with the potential for modifications (typically by their owner) over time. Components may be added or invalidated throughout a certificate's lifetime. +OpenPGP certificates tend to have a long lifespan, with the potential for modifications (typically by their owner) over time. Components may be added or invalidated throughout a certificate's lifetime. However, once published, components [cannot be removed](append-only) from certificates. ``` ## Component keys From 142250277fad219940864b0ab242171e766157be Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 22 Nov 2023 17:18:51 +0100 Subject: [PATCH 22/46] ch4: qualify split user id section with a footnote linking to dkg's 2019 blog outlining problems --- book/source/04-certificates.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 13f32b2..ce5996f 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -135,11 +135,13 @@ For further conventions on User IDs, refer to the document [draft-dkg-openpgp-us **Split User IDs** -One proposed variant for encoding identities in User ID is to use ["split User IDs"](https://dkg.fifthhorseman.net/blog/2021-dkg-openpgp-transition.html#split-user-ids). This style of User IDs is currently uncommon, but there is no technical impediment to using this format right now. +One proposed variant for encoding identities in User ID is to use ["split User IDs"](https://dkg.fifthhorseman.net/blog/2021-dkg-openpgp-transition.html#split-user-ids). This style of User IDs is currently uncommon, but there is no strong technical impediment to using this format right now[^dkg-split]. + +[^dkg-split]: Note that in the past, there were stumbling blocks in the OpenPGP ecosystem, see ["What were Separated User IDs"](https://dkg.fifthhorseman.net/blog/2019-dkg-openpgp-transition.html#what-were-separated-user-ids) from January 2019, by Daniel Kahn Gillmor. An argument for split User IDs is that a name and an email address are two distinct identities, which are easier to reason about separately. This is particularly relevant when third parties consider certifying that an identity is legitimately connected to a certificate. -For example, some third party may be sure about the email identity of a contact, and happy to issue a certification for an email-based identity (such as ``). But they may not have any insight into a name based identity (such as `Alice Adams`), and thus not willing to certify such a name-based identity. +For example, some third party may be sure about the email identity of a contact, and happy to issue a certification for an email-based identity (such as ``). But they may not have any insight into a name-based identity (such as `Alice Adams`), and thus not willing to certify such a name-based identity. (primary_user_id)= ### Implications of the Primary User ID From e0457bac6407c8cbdd6c601c9dfcfcf6bd1961a6 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 22 Nov 2023 17:24:29 +0100 Subject: [PATCH 23/46] ch4: clarify that user attribute images are JPEG --- book/source/04-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index ce5996f..f0b3e12 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -156,7 +156,7 @@ The primary User ID was historically the main store for preferences that apply t While [user attributes](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-user-attribute-packet-tag-1) are similar to User IDs, they are less commonly used. -Currently, the OpenPGP standard prescribes only one format to be stored in user attributes: an [image](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-the-image-attribute-subpack). Typically, this image represents the key owner, although it is not required. +Currently, the OpenPGP standard prescribes only one format to be stored in user attributes: an [image](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-the-image-attribute-subpack), in JPEG format. Typically, this image represents the key owner, although it is not required. ## Linking the components From fc665cb19738a4f0c03e95b0985d28f79e199e77 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 22 Nov 2023 17:34:53 +0100 Subject: [PATCH 24/46] ch4: clarification as suggested by wiktor --- book/source/04-certificates.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index f0b3e12..ef106aa 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -183,6 +183,8 @@ Instead, this kind of metadata is stored as part of the signature packets that j - For subkeys, metadata is defined with the [subkey binding signature](binding_subkeys) that links the subkey to the certificate. - For identity components like User IDs, metadata is associated via the [certifying self-signature](bind_ident) that links the identity to the certificate. +Note that the components of an OpenPGP certificate are themselves never changed, after their initial creation. By storing associated metadata in signatures, it can be modified at a later point in time by issuing a new signature that replaces the previous one. For example, the certificate holder can change the expiration time of a component of their certificate by issuing a new signature. + ### Defining operational capabilities of component keys with key flags Each component key has a set of ["key flags"](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#key-flags) that delineate the operations a key can perform. From 28ec86b4b68dde49bef9e8e9d5297c8a86806901 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 22 Nov 2023 17:36:31 +0100 Subject: [PATCH 25/46] ch4: fix flow/logic --- book/source/04-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index ef106aa..a89d21d 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -199,7 +199,7 @@ Commonly used key flags include: [^auth-flag]: Note that the capability offered by the [authentication](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-authentication-via-digital-) key flag is unrelated to "authentication" in the context of certifying and verifying OpenPGP identities and their connection to certificates. This key flag is about a mechanism that proves control of private key material to a remote system, using cryptographic signatures. ```{note} -Distinct component keys handle specific operations. Only the primary key can be used for certification, although it can have additional capabilities. Subkeys can be used for signing, encryption, and authentication but cannot have the certification capability. It is considered good practice, however, to [use separate keys for each capability](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-10.1.5-7). +Distinct component keys handle specific operations. Only the primary key can be used for certification, although it can have additional capabilities. Subkeys can be used for signing, encryption, and authentication but cannot have the certification capability. A component key can technically have multiple capabilities. It is considered good practice, however, to [use separate keys for each capability](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-10.1.5-7). Notably, in many algorithms, encryption and signing-related functionalities (i.e., certification, signing, authentication) are mutually exclusive, because the algorithms only support one of those two families of operations[^key-flag-sharing]. ``` From 7f90c71be472b65548e63e9934eff07724f1d23a Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 22 Nov 2023 17:49:08 +0100 Subject: [PATCH 26/46] ch4: clarification --- book/source/04-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index a89d21d..e0ddfaf 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -212,7 +212,7 @@ OpenPGP has a lot of ["cryptographic agility"](https://en.wikipedia.org/wiki/Cry This agility has the advantage that adoption of new cryptographic primitives into the standard is relatively easy, and can be done without disruption. Users can gradually migrate to using new cryptographic mechanisms. -However, it also means that OpenPGP software needs to figure out which mechanisms a set of communication partners can handle and prefers. To do this, there are a number of mechanisms in OpenPGP that can be negotiated between sender and recipient. The sender interprets the preferences of the recipient: +However, it also means that OpenPGP software needs to figure out which mechanisms a set of communication partners can handle and prefer. To do this, there are a number of mechanisms in OpenPGP that can be negotiated between sender and recipient. Note that OpenPGP is not an online scheme, so this negotiation is effectively one-way: The active party interprets the preferences that are expressed in the certificate of the passive party. - [Preferred Hash Algorithms](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-hashes-subpacket) - [Preferred Symmetric Ciphers for v1 SEIPD](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-v1-seipd) From b337068d612c31b5ef5f645652d98f0c0f397627 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 22 Nov 2023 21:08:22 +0100 Subject: [PATCH 27/46] ch4: process input from liw, in #113 --- book/source/04-certificates.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index e0ddfaf..c3b3ff1 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -6,7 +6,9 @@ SPDX-License-Identifier: CC-BY-SA-4.0 (certificates_chapter)= # Certificates -OpenPGP fundamentally hinges on the concept of "OpenPGP certificates," also known as "OpenPGP keys." These certificates are complex data structures essential for identity verification, data encryption, and digital signatures. Understanding their structure and function is pivotal to effectively applying the OpenPGP standard. +OpenPGP fundamentally hinges on the concept of "OpenPGP certificates," also known as "OpenPGP public keys." These certificates are complex data structures essential for identity verification, data encryption, and digital signatures. Understanding their structure and function is pivotal to effectively applying the OpenPGP standard. + +An OpenPGP certificate, by definition, does not contain private key material. ## Terminology: Understanding "keys" From 02b0785584a3e2b8fcc52bcbdc2bde3e2d5afa2c Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 22 Nov 2023 21:38:33 +0100 Subject: [PATCH 28/46] ch4: attempt at clarifying the kind-of-unique-but-technically-not property of fingerprints, to deal with #113 --- book/source/04-certificates.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index c3b3ff1..4f0e559 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -80,7 +80,7 @@ Each OpenPGP component key possesses an *OpenPGP fingerprint*. This fingerprint :name: fig-fingerprint :alt: Depicts a box with white background and the title "Fingerprint of an OpenPGP component key". Inside, another box with a green frame, the title "Component Key", the text "key creation time" on the lower left and a the green public key symbol on the lower right is shown. Below the component key box a fingerprint in a box with a light-yellow background and a yellow dotted line is depicted. The word "Fingerprint" is shown left of the box with the fingerprint and both are connected with a yellow dotted line. -Every OpenPGP component key is identifiable by a fingerprint. Although it's technically possible for different keys to share a fingerprint, [cryptographic mechanisms](crypto-hash) make it exceedingly difficult, if not practically impossible with current technology, to find keys that share a fingerprint. +Every OpenPGP component key is identifiable by a fingerprint. ``` The fingerprint of our example OpenPGP component key is `C0A5 8384 A438 E5A1 4F73 7124 26A4 D45D BAEE F4A3 9E6B 30B0 9D55 13F9 78AC CA94`[^keyid]. @@ -89,6 +89,12 @@ The fingerprint of our example OpenPGP component key is `C0A5 8384 A438 E5A1 4F7 For example, an OpenPGP version 4 certificate with the fingerprint `B3D2 7B09 FBA4 1235 2B41 8972 C8B8 6AC4 2455 4239` might be referenced by the 64-bit Key ID `C8B8 6AC4 2455 4239` or formatted as `0xC8B86AC424554239`. Historically, even shorter 32-bit identifiers were used, like this: `2455 4239`, or `0x24554239`. Such identifiers still appear in very old documents about PGP. However, [32-bit identifiers have been long deemed unfit for purpose](https://evil32.com/). At one point, 32-bit identifiers were called "short Key ID," while 64-bit identifiers were referred to as "long Key ID." +```{note} +In practice, the fingerprint of a component key is used like a unique identifier. + +However, formally, a fingerprint is not unique. For every component key, other component keys with the same fingerprint exist, in theory. But because fingerprints are calculated using a [cryptographic hash algorithm](crypto-hash), it is practically impossible to find two different component keys that have the same fingerprint. + ``` + ### Primary key The OpenPGP primary key is a component key that serves a distinct, central role in an OpenPGP certificate: From 10ce55fa77151e58b41d6c3c3eb5d1c558419425 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Sat, 25 Nov 2023 11:51:59 +0100 Subject: [PATCH 29/46] edits to #999549dcc3 --- book/source/04-certificates.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 4f0e559..f9e7ba6 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -143,13 +143,13 @@ For further conventions on User IDs, refer to the document [draft-dkg-openpgp-us **Split User IDs** -One proposed variant for encoding identities in User ID is to use ["split User IDs"](https://dkg.fifthhorseman.net/blog/2021-dkg-openpgp-transition.html#split-user-ids). This style of User IDs is currently uncommon, but there is no strong technical impediment to using this format right now[^dkg-split]. +One proposed variant for encoding identities in User IDs is to use ["split User IDs"](https://dkg.fifthhorseman.net/blog/2021-dkg-openpgp-transition.html#split-user-ids). Although currently uncommon, there are currently no significant technical barriers to implementing this format[^dkg-split]. -[^dkg-split]: Note that in the past, there were stumbling blocks in the OpenPGP ecosystem, see ["What were Separated User IDs"](https://dkg.fifthhorseman.net/blog/2019-dkg-openpgp-transition.html#what-were-separated-user-ids) from January 2019, by Daniel Kahn Gillmor. +[^dkg-split]: Historically, the OpenPGP ecosystem faced challenges in this context. For further details, refer to Daniel Kahn Gillmor's January 2019 article, ["What were Separated User IDs"](https://dkg.fifthhorseman.net/blog/2019-dkg-openpgp-transition.html#what-were-separated-user-ids). -An argument for split User IDs is that a name and an email address are two distinct identities, which are easier to reason about separately. This is particularly relevant when third parties consider certifying that an identity is legitimately connected to a certificate. +The rationale for split User IDs lies in the distinction between a name and an email address, which represent two separate facets of an individual's identity. Separating these elements simplifies the process for third parties tasked with certifying that an identity is legitimately connected to a certificate. -For example, some third party may be sure about the email identity of a contact, and happy to issue a certification for an email-based identity (such as ``). But they may not have any insight into a name-based identity (such as `Alice Adams`), and thus not willing to certify such a name-based identity. +Consider this scenario: A third party is confident about the email-based identity of an individual (e.g.,``) and is willing to certify it. However, they might not have sufficient knowledge about the person's name-based identity (e.g., `Alice Adams`), so are unwilling to extend the same level of certification. Split User IDs address this dichotomy by allowing distinct certification processes for each type of identity. (primary_user_id)= ### Implications of the Primary User ID From 50bdb0b72e6d4a6297475437179b8cb41792a1a8 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Sat, 25 Nov 2023 11:51:59 +0100 Subject: [PATCH 30/46] edits to commit 999549dcc391704e39d4682fc335c2118072343e --- book/source/04-certificates.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 4f0e559..f9e7ba6 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -143,13 +143,13 @@ For further conventions on User IDs, refer to the document [draft-dkg-openpgp-us **Split User IDs** -One proposed variant for encoding identities in User ID is to use ["split User IDs"](https://dkg.fifthhorseman.net/blog/2021-dkg-openpgp-transition.html#split-user-ids). This style of User IDs is currently uncommon, but there is no strong technical impediment to using this format right now[^dkg-split]. +One proposed variant for encoding identities in User IDs is to use ["split User IDs"](https://dkg.fifthhorseman.net/blog/2021-dkg-openpgp-transition.html#split-user-ids). Although currently uncommon, there are currently no significant technical barriers to implementing this format[^dkg-split]. -[^dkg-split]: Note that in the past, there were stumbling blocks in the OpenPGP ecosystem, see ["What were Separated User IDs"](https://dkg.fifthhorseman.net/blog/2019-dkg-openpgp-transition.html#what-were-separated-user-ids) from January 2019, by Daniel Kahn Gillmor. +[^dkg-split]: Historically, the OpenPGP ecosystem faced challenges in this context. For further details, refer to Daniel Kahn Gillmor's January 2019 article, ["What were Separated User IDs"](https://dkg.fifthhorseman.net/blog/2019-dkg-openpgp-transition.html#what-were-separated-user-ids). -An argument for split User IDs is that a name and an email address are two distinct identities, which are easier to reason about separately. This is particularly relevant when third parties consider certifying that an identity is legitimately connected to a certificate. +The rationale for split User IDs lies in the distinction between a name and an email address, which represent two separate facets of an individual's identity. Separating these elements simplifies the process for third parties tasked with certifying that an identity is legitimately connected to a certificate. -For example, some third party may be sure about the email identity of a contact, and happy to issue a certification for an email-based identity (such as ``). But they may not have any insight into a name-based identity (such as `Alice Adams`), and thus not willing to certify such a name-based identity. +Consider this scenario: A third party is confident about the email-based identity of an individual (e.g.,``) and is willing to certify it. However, they might not have sufficient knowledge about the person's name-based identity (e.g., `Alice Adams`), so are unwilling to extend the same level of certification. Split User IDs address this dichotomy by allowing distinct certification processes for each type of identity. (primary_user_id)= ### Implications of the Primary User ID From 6ada412e740ee2492b34a60a8e23d871148770ff Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Sat, 25 Nov 2023 13:42:41 +0100 Subject: [PATCH 31/46] clarify auth-flag of commit c6888559f5598a64eb2095f56c84169a9e731d6f --- book/source/04-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index f9e7ba6..d7de02b 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -204,7 +204,7 @@ Commonly used key flags include: - **Encryption**: allows the key to encrypt data - **Authentication**: primarily used for SSH authentication[^auth-flag] -[^auth-flag]: Note that the capability offered by the [authentication](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-authentication-via-digital-) key flag is unrelated to "authentication" in the context of certifying and verifying OpenPGP identities and their connection to certificates. This key flag is about a mechanism that proves control of private key material to a remote system, using cryptographic signatures. +[^auth-flag]: It's important to note that the function of the [authentication](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-authentication-via-digital-) key flag is unrelated to the authentication process used in certifying OpenPGP identities and linking them to certificates. Rather, this flag indicates a mechanism that uses cryptographic signatures to confirm control of private key material with a remote system. ```{note} Distinct component keys handle specific operations. Only the primary key can be used for certification, although it can have additional capabilities. Subkeys can be used for signing, encryption, and authentication but cannot have the certification capability. A component key can technically have multiple capabilities. It is considered good practice, however, to [use separate keys for each capability](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-10.1.5-7). From a914e60fa3f33e7d1564c118b1f0256f2132b5fe Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Sat, 25 Nov 2023 13:59:35 +0100 Subject: [PATCH 32/46] edit metadata capabilities of commit c6888559f5598a64eb2095f56c84169a9e731d6f --- book/source/04-certificates.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index d7de02b..119b790 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -177,21 +177,19 @@ In very abstract terms, the primary key of a certificate acts as a root of trust By binding components using digital signatures, recipients of an OpenPGP certificate need only validate the authenticity of the primary key to use for their communication partner. Traditionally, this is done by manually verifying the *fingerprint* of the primary key. Once the validity of the primary key is confirmed, the validity of the remaining components can be automatically assessed by the user's OpenPGP software. Generally, components are valid parts of a certificate if there is a statement signed by the certificate's primary key endorsing this validity. -## Metadata: capabilities, preferences, etc +## Metadata capabilities, preferences, and storage -Much of the metadata for OpenPGP certificates, component keys, and identities, is not actually stored as part of the components that the metadata applies to. +OpenPGP certificates, their component keys, and identities possess metadata that is not stored within the components it pertains to. Instead, this metadata is stored within signature packets, which are integral to the structure of an OpenPGP certificate. -For example, the capabilities of a component key, such as *signing* or *encryption*, as well as its expiration time, are not stored as a part of the data of that component key. +Key attributes, such as capabilities (like *signing* or *encryption*) and expiration times, are examples of metadata not stored in the component key data. How this metadata is stored depends on the component: -Instead, this kind of metadata is stored as part of the signature packets that join components into an OpenPGP certificate: +- **Primary key metadata** is defined either through a direct key signature on the primary key (preferred in OpenPGP version 6), or by associating the metadata with the [Primary User ID](primary_user_id). -- For the primary key, its key flags and other metadata can be defined in two ways: - - With a [direct key signature](direct_key_signature) on the primary key (preferred method in OpenPGP version 6), - - or by associating the metadata with the [Primary User ID](primary_user_id). -- For subkeys, metadata is defined with the [subkey binding signature](binding_subkeys) that links the subkey to the certificate. -- For identity components like User IDs, metadata is associated via the [certifying self-signature](bind_ident) that links the identity to the certificate. +- **Subkey metadata** is defined within the [subkey binding signature](binding_subkeys) that links the subkey to the certificate. -Note that the components of an OpenPGP certificate are themselves never changed, after their initial creation. By storing associated metadata in signatures, it can be modified at a later point in time by issuing a new signature that replaces the previous one. For example, the certificate holder can change the expiration time of a component of their certificate by issuing a new signature. +- **User ID metadata** is is associated via the [certifying self-signature](bind_ident) that links the identity to the certificate. + +It is crucial to note that the components of an OpenPGP certificate remain static after their creation. The use of signatures to store metadata allows for subsequent modifications without altering the original components. For instance, a certificate holder can update the expiration time of a component by issuing a new, superseding signature. ### Defining operational capabilities of component keys with key flags From d49cf0b7130664890693f7f1edb1320fad8fbca0 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Sat, 25 Nov 2023 14:12:09 +0100 Subject: [PATCH 33/46] Edit commit 6f609c7f88cf0d523112fcf6fbc496db4e5cf871 --- book/source/04-certificates.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 119b790..ce1a88f 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -214,19 +214,21 @@ Notably, in many algorithms, encryption and signing-related functionalities (i.e ### Algorithm preferences and feature signaling -OpenPGP has a lot of ["cryptographic agility"](https://en.wikipedia.org/wiki/Cryptographic_agility). That is, OpenPGP doesn't just use one fixed set of algorithms, but defines a suite of cryptographic primitives that users (or their applications) can pick from. +OpenPGP demonstrates significant ["cryptographic agility"](https://en.wikipedia.org/wiki/Cryptographic_agility). It doesn't rely on a single fixed set of algorithms. Instead, it defines a suite of cryptographic primitives from which users (or their applications) can choose. -This agility has the advantage that adoption of new cryptographic primitives into the standard is relatively easy, and can be done without disruption. Users can gradually migrate to using new cryptographic mechanisms. +This agility facilitates the easy adoption of new cryptographic primitives into the standard, allowing for a seamless transition. Users can gradually migrate to new cryptographic mechanisms without disruption. -However, it also means that OpenPGP software needs to figure out which mechanisms a set of communication partners can handle and prefer. To do this, there are a number of mechanisms in OpenPGP that can be negotiated between sender and recipient. Note that OpenPGP is not an online scheme, so this negotiation is effectively one-way: The active party interprets the preferences that are expressed in the certificate of the passive party. +However, this approach requires that OpenPGP software determine the cryptographic mechanisms that a set of communication partners can handle and prefer. OpenPGP employs several mechanisms for this purpose, which allow negotiation between sender and recipient. It's important to note that OpenPGP is not an online scheme; thus, this negotiation is effectively one-way. The active party interprets the preferences expressed in the certificate of the passive party. -- [Preferred Hash Algorithms](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-hashes-subpacket) -- [Preferred Symmetric Ciphers for v1 SEIPD](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-v1-seipd) -- [Preferred AEAD Ciphersuites](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-v2-seipd) -- [Features](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#features-subpacket) -- [Preferred Compression Algorithms](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-compression-subpacket) +Key negotiation mechanisms in OpenPGP include: -In addition to these explicitly expressed preferences, implementations also deduce capabilities of communication partners based on the OpenPGP version of the certificate that they write to. +- [Preferred hash algorithms](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-hashes-subpacket) +- [Preferred symmetric ciphers for v1 SEIPD](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-v1-seipd) +- [Preferred AEAD ciphersuites](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-v2-seipd) +- [Features subpacket](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#features-subpacket) +- [Preferred compression algorithms](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-compression-subpacket) + +Beyond these explicitly expressed preferences, implementations also deduce capabilities of communication partners based on the version of the OpenPGP certificate they possess. #### User ID-specific preferences From 018a6107c1e3d76a9a969640d65ab42710fc3bfa Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Sat, 25 Nov 2023 15:33:34 +0100 Subject: [PATCH 34/46] edit to commit 441936eb98 --- book/source/04-certificates.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index ce1a88f..ff98e44 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -238,11 +238,11 @@ Additionally, OpenPGP allows modeling User ID-specific preferences. The idea is ## Revocations -When the owner of a certificate wants to invalidate some components of that certificate, or the entire certificate, they can do so by "revoking" the component in question. Revoking the primary key renders the entire certificate invalid. +When a certificate owner needs to invalidate certain components of their certificate, or even the entire certificate, they accomplish this through "revocation." Revoking the primary key renders the entire certificate invalid. -More on revoking components of a certificate in {ref}`self-revocations`. +Notably, revocations are not the only means by which components can become invalid. Other factors, such as the passing of a component's expiration time, can also render components invalid. -Note that there are other ways besides revocations in which components can become invalid. For example, the component's expiration time may have passed. +For more detailed information on revoking specific components of a certificate, see the section on {ref}`self-revocations`. ## Third-party (identity) certifications From 7cb536008bf50d5998162c2181327af0d624a7ba Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Sat, 25 Nov 2023 16:03:52 +0100 Subject: [PATCH 35/46] edit commit 451b881c03 --- book/source/04-certificates.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index ff98e44..c4b0d55 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -246,13 +246,15 @@ For more detailed information on revoking specific components of a certificate, ## Third-party (identity) certifications -Third-party identity certifications have been a pivotal mechanism in the OpenPGP ecosystem since the beginning. The designers of PGP, beginning with Phil Zimmermann, have favored decentralized trust models, which don't hinge on centralized authorities. OpenPGP's decentralized trust model is called the ["Web of Trust."](wot) +Since its inception, third-party identity certifications have been a cornerstone of the OpenPGP ecosystem. The original PGP designers, starting with Phil Zimmermann, advocated for decentralized trust models over reliance on centralized authorities. This decentralized approach in OpenPGP is known as the ["Web of Trust."](wot) -Third-party certifications are statements by OpenPGP users who attest that they have confirmed that a particular OpenPGP certificate belongs to a user with a particular identity. +Third-party certifications are statements by OpenPGP users confirming that a user with a specific identity is the owner of a particular OpenPGP certificate. For example, Bob's OpenPGP software may issue a certification that Bob has checked that the User ID `Alice Adams ` and the certificate with the fingerprint `AAA1 8CBB 2546 85C5 8358 3205 63FD 37B6 7F33 00F9 FB0E C457 378C D29F 1026 98B3` are legitimately linked. -This presupposes that Bob knows this person who goes by "Alice Adams," and is satisfied that Alice uses the email address `alice@example.org`. Further, that Bob has verified that the certificate his OpenPGP software uses for Alice matches the certificate that Alice is using. Effectively, this verification must ensure that both users have a certificate for Alice with the same fingerprint. In OpenPGP version 6, manual comparison of the fingerprint by end users is discouraged. A replacement mechanism is still pending. The verification must use a sufficiently secure channel, for example, an end-to-end encrypted video call, or an in-person meeting. +Take, for instance, a scenario where Bob's OpenPGP software issues a certification confirming as legitimate the link between the User ID `Alice Adams ` and the certificate bearing the fingerprint `AAA1 8CBB 2546 85C5 8358 3205 63FD 37B6 7F33 00F9 FB0E C457 378C D29F 1026 98B3`. + +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 certificate his OpenPGP software associates with Alice matches the one Alice uses. In essence, both users must have a certificate for Alice with an identical fingerprint. In OpenPGP version 6, manual fingerprint comparison by end-users is discouraged, with a replacement verification mechanism still under development. The 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 certifications, see {ref}`third_party_cert`. From f0e5c00803997df829ed4a26dd31fca7ce67c3de Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Sat, 25 Nov 2023 16:17:31 +0100 Subject: [PATCH 36/46] reorganize and structure content to answer commit 992c878fea --- book/source/04-certificates.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index c4b0d55..a6219b5 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -28,7 +28,13 @@ In OpenPGP, the term "key" may refer to three distinct layers, each serving a un The following section will delve into the OpenPGP-specific layers (2 and 3) to provide a clearer understanding of their roles within OpenPGP certificates. -For a discussion of private key material in OpenPGP, see the chapter {ref}`private_key_chapter`. Bindings that connect the components of a certificate are discussed in our chapter {ref}`component_signatures_chapter`. For much more detail on the internal (packet) structure of certificates and keys refer to our chapter {ref}`zoom_certificates`. Additionally, managing certificates, and understanding their authentication and trust models are vital topics. While this document only touches upon these aspects briefly, they are integral to working proficiently with OpenPGP. +Fundamentally, the effective management of certificates and a thorough grasp of their authentication and trust models are crucial for proficient OpenPGP usage. Although this document offers just a brief overview of these aspects, they form a fundamental part of the broader OpenPGP framework and warrant further study. + +– For an in-depth exploration of OpenPGP's private key material, refer to {ref}`private_key_chapter`. This chapter provides essential insights into key management and security practices. + +– The bindings that unify the components of a certificate are comprehensively discussed in {ref}`component_signatures_chapter`, offering a deeper understanding of certificate structure and integrity. + +– For a detailed analysis of the internal (packet) structure of certificates and keys, our chapter {ref}`zoom_certificates` can serve as an invaluable resource. ## Structure of OpenPGP certificates From 4a2595c5f71ee1c72ef58bfd779b8efe2158ab70 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Sat, 25 Nov 2023 16:24:09 +0100 Subject: [PATCH 37/46] remove comma in commit e0457bac64 --- book/source/04-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index a6219b5..9550e3e 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -170,7 +170,7 @@ The primary User ID was historically the main store for preferences that apply t While [user attributes](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-user-attribute-packet-tag-1) are similar to User IDs, they are less commonly used. -Currently, the OpenPGP standard prescribes only one format to be stored in user attributes: an [image](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-the-image-attribute-subpack), in JPEG format. Typically, this image represents the key owner, although it is not required. +Currently, the OpenPGP standard prescribes only one format to be stored in user attributes: an [image](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-the-image-attribute-subpack) in JPEG format. Typically, this image represents the key owner, although it is not required. ## Linking the components From 8c8cf2ed50f6d546462e5a8c61d9c99c4ac8a843 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Sat, 25 Nov 2023 16:30:54 +0100 Subject: [PATCH 38/46] edit commit 02b0785584 on the not-exactly-unique fingerprint --- book/source/04-certificates.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 9550e3e..0e0fcc0 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -96,9 +96,7 @@ For example, an OpenPGP version 4 certificate with the fingerprint `B3D2 7B09 FB Historically, even shorter 32-bit identifiers were used, like this: `2455 4239`, or `0x24554239`. Such identifiers still appear in very old documents about PGP. However, [32-bit identifiers have been long deemed unfit for purpose](https://evil32.com/). At one point, 32-bit identifiers were called "short Key ID," while 64-bit identifiers were referred to as "long Key ID." ```{note} -In practice, the fingerprint of a component key is used like a unique identifier. - -However, formally, a fingerprint is not unique. For every component key, other component keys with the same fingerprint exist, in theory. But because fingerprints are calculated using a [cryptographic hash algorithm](crypto-hash), it is practically impossible to find two different component keys that have the same fingerprint. +In practice, the fingerprint of a component key, while not theoretically unique, functions effectively as a unique identifier. The use of a [cryptographic hash algorithm](crypto-hash) in generating fingerprints makes the occurrence of two different component keys with the same fingerprint extremely unlikely. ``` ### Primary key From 3b0dfd5cd76b5c4cd5b4c2ebeb693aa511cff909 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 25 Nov 2023 18:14:45 +0100 Subject: [PATCH 39/46] move contextualization paragraphs up to the first block --- book/source/04-certificates.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 0e0fcc0..17451ee 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -10,6 +10,14 @@ OpenPGP fundamentally hinges on the concept of "OpenPGP certificates," also know An OpenPGP certificate, by definition, does not contain private key material. +Fundamentally, the effective management of certificates and a thorough grasp of their authentication and trust models are crucial for proficient OpenPGP usage. Although this document offers just a brief overview of these aspects, they form a fundamental part of the broader OpenPGP framework and warrant further study. + +- For an in-depth exploration of OpenPGP's private key material, refer to {ref}`private_key_chapter`. This chapter provides essential insights into private key management and security practices. + +- The bindings that link the components of a certificate are comprehensively discussed in {ref}`component_signatures_chapter`, offering a deeper understanding of certificate structure and integrity. + +- For a detailed analysis of the internal (packet) structure of certificates and keys, our chapter {ref}`zoom_certificates` can serve as an invaluable resource. + ## Terminology: Understanding "keys" The term "(cryptographic) keys" is central to grasping the concept of OpenPGP certificates. However, it can refer to different entities, making it a potentially confusing term. Let's clarify those differences. @@ -28,14 +36,6 @@ In OpenPGP, the term "key" may refer to three distinct layers, each serving a un The following section will delve into the OpenPGP-specific layers (2 and 3) to provide a clearer understanding of their roles within OpenPGP certificates. -Fundamentally, the effective management of certificates and a thorough grasp of their authentication and trust models are crucial for proficient OpenPGP usage. Although this document offers just a brief overview of these aspects, they form a fundamental part of the broader OpenPGP framework and warrant further study. - -– For an in-depth exploration of OpenPGP's private key material, refer to {ref}`private_key_chapter`. This chapter provides essential insights into key management and security practices. - -– The bindings that unify the components of a certificate are comprehensively discussed in {ref}`component_signatures_chapter`, offering a deeper understanding of certificate structure and integrity. - -– For a detailed analysis of the internal (packet) structure of certificates and keys, our chapter {ref}`zoom_certificates` can serve as an invaluable resource. - ## Structure of OpenPGP certificates An OpenPGP certificate (or "OpenPGP key") is a collection of an arbitrary number of elements[^packets]: From a4318538326607078aee0d296e00cbaebedcb097 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 25 Nov 2023 18:24:36 +0100 Subject: [PATCH 40/46] zoom_certificates doesn't talk about private keys (anymore). de-emphasize the packet-level chapter (it's still very unclear to me how many readers should look at those chapters). --- book/source/04-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 17451ee..7359147 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -16,7 +16,7 @@ Fundamentally, the effective management of certificates and a thorough grasp of - The bindings that link the components of a certificate are comprehensively discussed in {ref}`component_signatures_chapter`, offering a deeper understanding of certificate structure and integrity. -- For a detailed analysis of the internal (packet) structure of certificates and keys, our chapter {ref}`zoom_certificates` can serve as an invaluable resource. +- Finally, our chapter {ref}`zoom_certificates` discusses the internal structure of certificates in detail. ## Terminology: Understanding "keys" From 111f6cca41dbd39520576986d14ad3b59e274c90 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 25 Nov 2023 18:38:30 +0100 Subject: [PATCH 41/46] attempt at footnote with more detail on fingerprint uniqueness. the exact content might need more tweaking. --- book/source/04-certificates.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 7359147..05901dc 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -96,9 +96,11 @@ For example, an OpenPGP version 4 certificate with the fingerprint `B3D2 7B09 FB Historically, even shorter 32-bit identifiers were used, like this: `2455 4239`, or `0x24554239`. Such identifiers still appear in very old documents about PGP. However, [32-bit identifiers have been long deemed unfit for purpose](https://evil32.com/). At one point, 32-bit identifiers were called "short Key ID," while 64-bit identifiers were referred to as "long Key ID." ```{note} -In practice, the fingerprint of a component key, while not theoretically unique, functions effectively as a unique identifier. The use of a [cryptographic hash algorithm](crypto-hash) in generating fingerprints makes the occurrence of two different component keys with the same fingerprint extremely unlikely. +In practice, the fingerprint of a component key, while not theoretically unique, functions effectively as a unique identifier. The use of a [cryptographic hash algorithm](crypto-hash) in generating fingerprints makes the occurrence of two different component keys with the same fingerprint extremely unlikely[^finger-unique]. ``` +[^finger-unique]: For both OpenPGP version 6 and version 4, the likelihood of accidental occurrence of duplicate fingerprints is negligible when 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 fingerprint as a given pre-existing 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 fingerprints of OpenPGP version 4 are considered insufficiently strong at protecting against the generation of pairs of key material with the same fingerprint. + ### Primary key The OpenPGP primary key is a component key that serves a distinct, central role in an OpenPGP certificate: From 4635d15ecec394571ffb984e2273028dea242184 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 25 Nov 2023 18:41:35 +0100 Subject: [PATCH 42/46] drop duplication --- book/source/04-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 05901dc..45e5d77 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -149,7 +149,7 @@ For further conventions on User IDs, refer to the document [draft-dkg-openpgp-us **Split User IDs** -One proposed variant for encoding identities in User IDs is to use ["split User IDs"](https://dkg.fifthhorseman.net/blog/2021-dkg-openpgp-transition.html#split-user-ids). Although currently uncommon, there are currently no significant technical barriers to implementing this format[^dkg-split]. +One proposed variant for encoding identities in User IDs is to use ["split User IDs"](https://dkg.fifthhorseman.net/blog/2021-dkg-openpgp-transition.html#split-user-ids). Although uncommon, there are currently no significant technical barriers to implementing this format[^dkg-split]. [^dkg-split]: Historically, the OpenPGP ecosystem faced challenges in this context. For further details, refer to Daniel Kahn Gillmor's January 2019 article, ["What were Separated User IDs"](https://dkg.fifthhorseman.net/blog/2019-dkg-openpgp-transition.html#what-were-separated-user-ids). From ee1e9d539618cfda0a26ff206fc6e269d5f76002 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 25 Nov 2023 19:20:00 +0100 Subject: [PATCH 43/46] simplify/clarify section title --- book/source/04-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 45e5d77..30f81b9 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -183,7 +183,7 @@ In very abstract terms, the primary key of a certificate acts as a root of trust By binding components using digital signatures, recipients of an OpenPGP certificate need only validate the authenticity of the primary key to use for their communication partner. Traditionally, this is done by manually verifying the *fingerprint* of the primary key. Once the validity of the primary key is confirmed, the validity of the remaining components can be automatically assessed by the user's OpenPGP software. Generally, components are valid parts of a certificate if there is a statement signed by the certificate's primary key endorsing this validity. -## Metadata capabilities, preferences, and storage +## Metadata in certificates OpenPGP certificates, their component keys, and identities possess metadata that is not stored within the components it pertains to. Instead, this metadata is stored within signature packets, which are integral to the structure of an OpenPGP certificate. From 0a2bccb380cd82c88a3e0d0a0a87fa6e75ae181a Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 25 Nov 2023 19:20:42 +0100 Subject: [PATCH 44/46] generalize: User Attributes are uncommon, but we should include them --- book/source/04-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 30f81b9..db334e6 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -193,7 +193,7 @@ Key attributes, such as capabilities (like *signing* or *encryption*) and expira - **Subkey metadata** is defined within the [subkey binding signature](binding_subkeys) that links the subkey to the certificate. -- **User ID metadata** is is associated via the [certifying self-signature](bind_ident) that links the identity to the certificate. +- **Identity component metadata** is associated via the [certifying self-signature](bind_ident) that links the identity (usually in the form of a User ID) to the certificate. It is crucial to note that the components of an OpenPGP certificate remain static after their creation. The use of signatures to store metadata allows for subsequent modifications without altering the original components. For instance, a certificate holder can update the expiration time of a component by issuing a new, superseding signature. From b121676a0de3ddb195251060a5eef3d50b04d7c5 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 25 Nov 2023 19:26:55 +0100 Subject: [PATCH 45/46] i think "demonstrate" gestures partly in the wrong direction. much agility is already built in. the point here is not that more agility can be built in on short notice (even though that is also true). but rather that OpenPGP already allows users to make a lot of decisions about which mechanisms to use, right now. --- book/source/04-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index db334e6..1a1660a 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -220,7 +220,7 @@ Notably, in many algorithms, encryption and signing-related functionalities (i.e ### Algorithm preferences and feature signaling -OpenPGP demonstrates significant ["cryptographic agility"](https://en.wikipedia.org/wiki/Cryptographic_agility). It doesn't rely on a single fixed set of algorithms. Instead, it defines a suite of cryptographic primitives from which users (or their applications) can choose. +OpenPGP incorporates significant ["cryptographic agility"](https://en.wikipedia.org/wiki/Cryptographic_agility). It doesn't rely on a single fixed set of algorithms. Instead, it defines a suite of cryptographic primitives from which users (or their applications) can choose. This agility facilitates the easy adoption of new cryptographic primitives into the standard, allowing for a seamless transition. Users can gradually migrate to new cryptographic mechanisms without disruption. From 5621dfa79cbf08606bf0542ffa8fc8780ef145d4 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 25 Nov 2023 19:29:18 +0100 Subject: [PATCH 46/46] avoid using the technical term "key" as a generic word --- book/source/04-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 1a1660a..47cc2f2 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -226,7 +226,7 @@ This agility facilitates the easy adoption of new cryptographic primitives into However, this approach requires that OpenPGP software determine the cryptographic mechanisms that a set of communication partners can handle and prefer. OpenPGP employs several mechanisms for this purpose, which allow negotiation between sender and recipient. It's important to note that OpenPGP is not an online scheme; thus, this negotiation is effectively one-way. The active party interprets the preferences expressed in the certificate of the passive party. -Key negotiation mechanisms in OpenPGP include: +Negotiation mechanisms in OpenPGP include: - [Preferred hash algorithms](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-hashes-subpacket) - [Preferred symmetric ciphers for v1 SEIPD](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-v1-seipd)