From 1e3672fa266b9536cfeb9952eca3d68733369729 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 22 Nov 2023 15:05:17 +0100 Subject: [PATCH 01/39] Add anchor, and clarify intended meaning of section --- book/source/08-signing_components.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index e3d0ace..9e41e4e 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -155,12 +155,12 @@ Linking a User ID to an OpenPGP certificate This signature is calculated over the primary key, User ID and the metadata of the signature packet. - -### Adding metadata to the primary key +(primary-metadata)= +### Adding metadata to the primary key/certificate The signatures that bind subkeys and identity components to a certificate serve two different purposes: Linking components to the certificate and adding metadata to a component. -The primary key in a certificate doesn't need to be linked to the certificate. It acts as the anchor for linking, itself and thus doesn't require being linked. However, there is nevertheless a need to associate metadata with the primary key. +The primary key in a certificate doesn't need to be linked to the certificate. It acts as the anchor for linking, itself and thus doesn't require being linked. However, there is nevertheless a need to associate metadata with the primary key, which typically applies to the certificate as a whole. There are two mechanisms for adding metadata to the primary key: From fe8f92e99d778584a9ec84abb6c7b13ddcbe388b Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 22 Nov 2023 16:26:17 +0100 Subject: [PATCH 02/39] 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 9e41e4e..6958475 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -295,6 +295,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 1331e9bb5a2e64a76e877990f539a56735813c0e Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 22 Nov 2023 17:00:11 +0100 Subject: [PATCH 03/39] mention "strong set" concept --- book/source/08-signing_components.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index 6958475..ff6e123 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -298,7 +298,9 @@ 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. +The OpenPGP, the "Web of Trust" is a trust model that performs authentication decisions on a set of certifications and delegations[^strong-set]. + +[^strong-set]: In the context of the Web of Trust, the so-called [strong set](https://en.wikipedia.org/wiki/Web_of_trust#Strong_set) refers to a set of certificates that are strongly linked amongst each other via third-party certifications. The OpenPGP "Web of Trust" model assumes that every user makes their own choice about who they delegate authentication decisions to. Based on the available certificates and third-party signatures, the user's OpenPGP software uses the Web of Trust mechanism to determine which certificates are considered reliable for an identity. From 2340333f40cfb30f4fb9c0241c9d0bac103ffef3 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Thu, 23 Nov 2023 10:16:29 +0100 Subject: [PATCH 04/39] edit signatures on components intro, self-sig v 3rd party --- book/source/08-signing_components.md | 38 ++++++++++++++-------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index ff6e123..7cdbc3a 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -6,33 +6,33 @@ SPDX-License-Identifier: CC-BY-SA-4.0 (component_signatures_chapter)= # Signatures on components -In this chapter, we'll look at OpenPGP signatures that apply to components of certificates. That is, signatures that apply to: +This chapter examines OpenPGP signatures associated with certificate components, applying to: -- Component keys (primary keys or subkeys) and -- Identity components (User IDs or User attributes). +- component keys, encompassing primary keys and subkeys +- identity components, namely user IDs and user attributes Signatures on components are used to construct and maintain certificates, and to model the authentication of identities. -This chapter expands on topics we introduced in the {ref}`certificates_chapter` chapter. +This chapter expands on topics introduced in the {ref}`certificates_chapter` chapter. ## Self-signatures vs third-party signatures -There are two fundamentally different flavors of signatures on components: +Component signatures in OpenPGP are categorized into two distinct types: -- *Self-signatures*, which are issued by the certificate holder themselves using the primary key of the certificate, and -- *third-party signatures*, which are issued by a third party. +- **self-signatures**, which are issued by the certificate holder using the certificate's primary key +- **third-party signatures**, which are issued by an external entity, not the certificate holder ### Self-signatures -*Self-signatures* on components are a crucial mechanism for forming OpenPGP certificates (by binding the certificate's components into one combined data structure), as well as for life-cycle management of certificates (that is: performing changes to the certificate, over time). +Self-signatures are fundamental in creating and managing OpenPGP certificates. They bind the various components of a certificate into one combined data structure and facilitate the certificate's life-cycle management. -Life-cycle management operations on OpenPGP certificates and their components include: +Life-cycle management operations include: -- binding additional components to a certificate, -- changing the expiration date, or other metadata, of a component, and -- invalidating components or existing self-signatures using revocations. +- binding additional components to a certificate +- modifying expiration dates or other metadata of components +- revoking, and thus invalidating, components or existing self-signatures -Self-signatures are issued by the certificate's owner, using the primary key of the same certificate. +Self-signatures are issued by the certificate's owner using the certificate's primary key. ```{note} No [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags) is required to issue self-signatures. An OpenPGP primary key can issue self-signatures by default. @@ -40,16 +40,16 @@ No [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh- ### Third-party signatures -Third-party signatures on components form the basis for OpenPGP's decentralized authentication functionality (also known as the *Web of Trust*). They encode authentication-related statements about certificates and their associated identities. +Third-party signatures are pivotal in OpenPGP for decentralized authentication, forming the basis of the *Web of Trust*. They encode authentication-related statements about certificates and linked identities, establishing trustworthiness and verification. -Third-party OpenPGP signatures can be used to make the following types of statements: +Third-party signatures are used to make specific statements: -- Certification of identity claims, -- Delegation of authentication decisions, -- Invalidating previous third-party signature statements using revocations. +- certifying identity claims +- delegating authentication decisions +- revoking, and thus invalidating, prior third-party signature statements ```{note} -The **certify others** [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags) (`0x01`) is required to issue third-party signatures. Only the primary key of a certificate may hold this key flag. +The **certify others** [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags) (`0x01`) is required to issue third-party signatures. Only the certificate's primary holds this key flag. ``` ### Self-signatures and third-party signatures convey different meanings From 560f75d7034baedecaa4ca0a4ed8213bbf67a006 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Thu, 23 Nov 2023 10:35:13 +0100 Subject: [PATCH 05/39] edit ch8 section on distinct functions of self- v third-party sigs --- book/source/08-signing_components.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index 7cdbc3a..2cf9355 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -9,7 +9,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 This chapter examines OpenPGP signatures associated with certificate components, applying to: - component keys, encompassing primary keys and subkeys -- identity components, namely user IDs and user attributes +- identity components, namely User IDs and User attributes Signatures on components are used to construct and maintain certificates, and to model the authentication of identities. @@ -52,19 +52,17 @@ Third-party signatures are used to make specific statements: The **certify others** [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags) (`0x01`) is required to issue third-party signatures. Only the certificate's primary holds this key flag. ``` -### Self-signatures and third-party signatures convey different meanings +### Distinct functions of self-signatures and third-party signatures -The meaning of a signature depends in part on who issued it. A self-signature performs a different function than the same type of signature issued by a third party. +The meaning of an OpenPGP signature depends significantly on its issuer. Self-signatures and third-party signatures, even when of the same type, serve distinct functions. For example: -For example: +- Certifying self-signatures (type IDs `0x10` - `0x13`) bind a User ID to a certificate. +- Third-party signatures of the same type IDs endorses the authenticity of a User ID. -- Certifying self-signatures (type IDs `0x10` - `0x13`) are used to bind a User ID to a certificate, while -- third-party signatures of the same type IDs indicate that the signer endorses the authenticity of a User ID. +In another instance: -Or: - -- A [direct key signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-direct-key-signature-type-i) issued as a self-signature can be used to set preferences and advertise features that apply to the whole certificate, while -- a similar [direct key signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-direct-key-signature-type-i) issued by a third party delegates trust to the signed certificate, when it carries a [trust signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-trust-signature) subpacket. The issuer thereby configures the signed certificate as a trust root in the *Web of Trust*, for themselves. +- *When issued as a self-signature*, a [direct key signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-direct-key-signature-type-i) sets preferences and advertises features applicable to the entire certificate. +- *When issued by a third party*, especially when it carries a [trust signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-trust-signature) subpacket, a similar direct key signature delegates trust to the signed certificate. This designates the signed certificate as a trust root within the issuer's *Web of Trust*. ## Self-signatures: Forming certificates and life-cycle management From d3c1634ae09f3a63a64f6429b9f3885c2c4ea958 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Thu, 23 Nov 2023 13:12:30 +0100 Subject: [PATCH 06/39] edit ch8 self-sigs in cert formation and mgmt --- book/source/08-signing_components.md | 37 +++++++++++----------------- 1 file changed, 14 insertions(+), 23 deletions(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index 2cf9355..ff37d56 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -64,53 +64,44 @@ In another instance: - *When issued as a self-signature*, a [direct key signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-direct-key-signature-type-i) sets preferences and advertises features applicable to the entire certificate. - *When issued by a third party*, especially when it carries a [trust signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-trust-signature) subpacket, a similar direct key signature delegates trust to the signed certificate. This designates the signed certificate as a trust root within the issuer's *Web of Trust*. -## Self-signatures: Forming certificates and life-cycle management +## Self-signatures in certificate formation and management -The components in an OpenPGP certificate are bound together using signatures. These *binding signatures* join the components together, while also adding metadata to them. +Self-signatures play a crucial role in forming and managing the structure of OpenPGP certificates. These act as *binding signatures*, joining components and embedding metadata. -Internally, an OpenPGP certificate consists of a sequence of OpenPGP packets. These packets are just strung together, one after the other. When a certificate is stored in a file[^tpk], it's easy to remove some of these packets, or add new ones. +Internally, an OpenPGP certificate is essentially a series of packets strung sequentially. When a certificate is stored in a file format known as a [transferable public key](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-transferable-public-keys), packets can be easily added or removed. -[^tpk]: When stored in a file, OpenPGP certificates are in a format called [transferable public key](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-transferable-public-keys). - -However, the owner of a certificate doesn't want a third party to add subkeys or [identity components](identity_components) to their certificate, pretending that the certificate owner put those components there. - -To prevent malicious addition of components, OpenPGP uses cryptographic signatures. These signatures show that components have been added by the owner of the OpenPGP certificate. They are issued by the primary key of the certificate. - -So while anyone can still unilaterally store unrelated subkeys and [identity components](identity_components) in an OpenPGP certificate dataset, OpenPGP implementations that load a certificate can (and usually should) discard components that don't have a valid cryptographic connection with the certificate. +To safeguard against unauthorized additions, OpenPGP uses cryptographic signatures. These validate that any additions, such as subkeys or [identity components](identity_components), were made by the owner of the OpenPGP certificate using its primary key. While anyone can still store unrelated subkeys and identity components to a certificate dataset, OpenPGP implementations typically reject components lacking a valid cryptographic connection with the certificate. ```{note} -Conversely, it's easy for a third party to leave out packets, while handling an OpenPGP certificate dataset. An attacker can, for example, simply choose to omit revocation packets. The recipient of such a partial copy has no way to notice this omission, without access to a different source for the certificate that contains the revocation packet. +Conversely, omissions of packets by third parties can easily occur when handling an OpenPGP certificate dataset. This could pose a challenge, for example, when an attacker deliberately omits revocation packets. Without access to an alternative, complete certificate source, recipients might not detect these omissions. ``` -Note that there are some cases where third parties legitimately add "unbound" packets (that is: packets that are not signed by the certificate's owner) to a certificate: +However, there are instances – legitimate and malicious – in which third parties add "unbound" packets (i.e., not signed by the certificate's owner) to a certificate: -- [Third-party certifications](third_party_cert) are traditionally stored as part of the packet data of the certificate that they make a statement about (in systems that unconditionally accept and include such certifications, this can cause problems[^flooding]), -- OpenPGP software may add [unbound identity data](unbound_user_ids), locally. +- [Third-party certifications](third_party_cert) are often stored within the packet data of the certificate to which they are related.This is a standard practice that provides convenience for users by allowing easy access to all relevant certifications. However, in systems that unconditionally accept these certifications, it can lead to unintended consequences. Specifically, this approach has been exploited to cause denial-of-service attacks through [certificate flooding](https://dkg.fifthhorseman.net/blog/openpgp-certificate-flooding.html), a problem notably experienced by the SKS network of OpenPGP servers. +- OpenPGP software may locally append [unbound identity data](unbound_user_ids) to a certificate. -[^flooding]: Storing third-party identity certifications in the target OpenPGP certificate is convenient for consumers: it is easy to find all relevant certifications in one central location. However, when third parties can unilaterally add certifications, this opens an avenue for denial-of-service attacks by flooding. The SKS network of OpenPGP key servers [allowed and experienced this problem](https://dkg.fifthhorseman.net/blog/openpgp-certificate-flooding.html). (bind_subkey)= ### Binding subkeys to a certificate -Subkeys is linked to an OpenPGP certificate using a [subkey binding signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-subkey-binding) (type ID `0x18`). This signature type effectively signals that the "primary key wants to be associated with the subkey". +Subkeys are linked to OpenPGP certificates via a [subkey binding signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-subkey-binding) (type ID `0x18`). This signature type indicates the association of the primary key with the subkey. -A subkey binding signature binds a subkey to a primary key, and adds metadata in the signature packet. Once generated, the subkey binding signature packet is stored in the certificate, directly following the subkey it binds. +A subkey binding signature binds a subkey to a primary key, and it embeds metadata into the signature packet. Once generated, the subkey binding signature packet is stored in the certificate directly after the subkey it binds. -(Note that subkeys that have the *signing* [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags) are a special case, and are handled slightly differently. See {numref}`bind_subkey_sign`.) +Subkeys designated for signing purposes, identified by the *signing* [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags), represent a unique category and are handled differently. See {numref}`bind_subkey_sign`. ```{figure} diag/subkey_binding_signature.png Linking an OpenPGP subkey to the primary key with a binding signature ``` -To specify metadata for the subkey, such as the [*key expiration time*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#key-expiration-subpacket), or the capabilities that are set using [*key flags*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#key-flags), subpackets are included in the subkey binding signature packet. +Metadata for the subkey, such as the [*key expiration time*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#key-expiration-subpacket) and capabilities set by [*key flags*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#key-flags), are included in subpackets within the subkey binding signature packet. ```{note} -The validity of a subkey is bounded by that of the primary key, meaning that an expired primary key causes the subkey to be invalid, no matter the subkey expiration time. +The validity of a subkey is intrinsically linked to that of the primary key. An expired primary key renders any associated subkey invalid, regardless of the subkey’s own expiration setting. -It's legal for a subkey to not have an explicit expiry time. In that case, its expiration date is implicitly the same as the expiration date of the primary key. - -A subkey cannot be "older" than the primary key. The value of the subkeys creation date MUST be greater than that of the primary key. +Legally, a subkey may not have a specified expiry time. In such cases, its expiration aligns implicitly with that of the primary key. Additionally, the creation date of a subkey must always be more recent than that of the primary key. ``` (bind_subkey_sign)= From 7d1d69d372bbf755362de7bf02fece7ba7d82129 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Thu, 23 Nov 2023 13:34:17 +0100 Subject: [PATCH 07/39] edit ch8 binding signing subkeys --- book/source/08-signing_components.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index ff37d56..a4af29e 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -105,24 +105,23 @@ Legally, a subkey may not have a specified expiry time. In such cases, its expir ``` (bind_subkey_sign)= -### Special case: Binding signing subkeys to a certificate +### Special case: Binding signing subkeys -To bind subkeys with the "signing" key flag to a certificate is a special case. For the most part, it works the same as binding other types of subkeys, but there is one additional requirement: +Binding subkeys that possess the *signing* key flag to a certificate represents a unique scenario. While similar to the binding process of other subkeys, there is an additional, critical requirement: mutual association. -To bind a signing-capable subkey to a primary key, it is not sufficient that the "primary key wants to be associated with the subkey." In addition, the subkey must signal that it "wants to be associated with that primary key." +That is, to bind a signing-capable subkey to a primary key, it is insufficient that the "primary key wants to be associated with the subkey." The subkey must explicitly signal that it "wants to be associated with the primary key." -Otherwise, Alice could "adopt" Bob's signing subkey and convincingly claim that she made signatures that were in fact issued by Bob. -This is to prevent an attack where the attacker "adopts" the victims signing subkey as their own in order to claim ownership over documents which were in fact signed by the victim. -In contrast to the [subkey binding signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-subkey-binding) (type ID `0x18`), which is issued by the certificate's primary key, the [primary key binding signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#sigtype-primary-binding) (type ID `0x19`) is instead created by the subkey (informally also called an embedded "back signature"). +This mutual binding is crucial for security. Without it, an individual (e.g., Alice) could falsely claim a connection to another person’s (e.g., Bob's) signing subkey. To prevent such scenarios, where an attacker might wrongfully "adopt" a victim's signing subkey, a dual-layer of signatures is used: + +- the [subkey binding signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-subkey-binding) (type ID `0x18`), which is issued by the certificate's primary key +- the [primary key binding signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#sigtype-primary-binding) (type ID `0x19`), created by the subkey itself. This is informally known as an embedded "back signature," because the subkey's signature points back to the primary key. ```{figure} diag/subkey_binding_signatur_for_signing_sk.png Linking an OpenPGP signing subkey to the primary key with a binding signature, and an embedded primary key binding signature ``` -The additional [*primary key binding*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#sigtype-primary-binding) signature (type 0x19) is informally called a "back signature" (because the subkey uses the signature to point "back" to the primary key). - -The *primary key binding signature* is "embedded" as subpacket data in the *subkey binding signature* which connects the signing subkey to the primary key. +The back signature signifies the mutuality of the subkey's association with the primary key and is embedded within the subkey binding signature, reinforcing the authenticity of the binding. (bind_ident)= ### Binding identities to a certificate From 28a69fe3818498191f393b3fbb8b789e570ca43a Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Thu, 23 Nov 2023 14:02:13 +0100 Subject: [PATCH 08/39] edit ch8 binding identities --- book/source/08-signing_components.md | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index a4af29e..c01fa35 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -126,23 +126,19 @@ The back signature signifies the mutuality of the subkey's association with the (bind_ident)= ### Binding identities to a certificate -Another use-case for a self-signature is to link an identity component (such as a User ID that specifies a name and email address) to a certificate. +Self-signatures also play a vital role in binding identity components, such as User IDs or User Attributes, to an OpenPGP certificate. -User ID components are bound to an OpenPGP certificate by issuing a certifying self-signature. "User Attributes" work analogously. +Take for instance, the User ID `Alice Adams `. To link this User ID to her OpenPGP certificate (e.g., `AAA1 8CBB 2546 85C5 8358 3205 63FD 37B6 7F33 00F9 FB0E C457 378C D29F 1026 98B3`), Alice would use a cryptographic signature. -For example, the User ID `Alice Adams ` may be associated with Alice's certificate `AAA1 8CBB 2546 85C5 8358 3205 63FD 37B6 7F33 00F9 FB0E C457 378C D29F 1026 98B3`. +There are four types of *certifying self-signature*. The most commonly used type for binding User IDs is the [positive certification](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-positive-cert) (type ID `0x13`). Alternatively, types `0x10`, `0x11` or `0x12` might be used. This binding signature must be issued by the primary key. -Alice can link a User ID to her OpenPGP certificate with a cryptographic signature. To link a User ID, a *certifying self-signature* is created. There are four variant certifying self-signature types. Usually the signature type [positive certification](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-positive-cert) (type ID `0x13`) is used to bind User IDs to one's certificate (sometimes, type ID `0x10`, `0x11` or `0x12` may be used instead). This binding signature must be issued by the primary key. - -The resulting certifying self-signature packet is stored as part of the certificate, directly following the User ID packet. +The certifying self-signature packet – calculated over the primary key, User ID, and metadata of the signature packet – is then appended to the certificate, directly following the User ID packet. ```{figure} diag/user_id_certification.png Linking a User ID to an OpenPGP certificate ``` -This signature is calculated over the primary key, User ID and the metadata of the signature packet. - (primary-metadata)= ### Adding metadata to the primary key/certificate From 92d7d218fbdd017a279b77ee839cd23564d21283 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Thu, 23 Nov 2023 14:09:15 +0100 Subject: [PATCH 09/39] edit ch8 adding metadata --- book/source/08-signing_components.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index c01fa35..f40a34d 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -142,20 +142,20 @@ Linking a User ID to an OpenPGP certificate (primary-metadata)= ### Adding metadata to the primary key/certificate -The signatures that bind subkeys and identity components to a certificate serve two different purposes: Linking components to the certificate and adding metadata to a component. +The signatures that bind subkeys and identity components to a certificate serve dual purposes: linking components to the certificate and adding metadata to components. -The primary key in a certificate doesn't need to be linked to the certificate. It acts as the anchor for linking, itself and thus doesn't require being linked. However, there is nevertheless a need to associate metadata with the primary key, which typically applies to the certificate as a whole. +Unlike these components, the primary key of a certificate doesn't require a linking signature since it serves as the central anchor of the certificate. However, associating metadata with the primary key is still essential, as it generally applies to the entire certificate. -There are two mechanisms for adding metadata to the primary key: +Metadata can be added to the primary key via two mechanisms: -- Via a direct key signature on the primary key, or -- via a "primary User ID" binding signature. +- direct key signature on the primary key +- *primary User ID* binding signature -Relevant metadata for the primary key that is defined the above mechanisms includes: +The types of metadata typically associated with the primary key through these methods include: -- Key expiration, -- key flags, -- algorithm preference signaling. +- key expiration +- key flags +- algorithm preference signaling (direct_key_signature)= #### Direct key signature From b4954d7a14a31acaa0bfdf645d05cddc67effaf2 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Thu, 23 Nov 2023 14:11:39 +0100 Subject: [PATCH 10/39] edit ch8 dirct key signature --- book/source/08-signing_components.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index f40a34d..29415ac 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -160,7 +160,7 @@ The types of metadata typically associated with the primary key through these me (direct_key_signature)= #### Direct key signature -A [*direct key signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-direct-key-signature-type-i) is one mechanism to store information about the primary key, and about the entire certificate. +A [*direct key signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-direct-key-signature-type-i) serves as a key mechanism for storing information about the primary key and the entire certificate. In OpenPGP v6, a direct key signature is the [preferred mechanism](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-5.2.3.10-9). From 92948c6dda10fe7e0f03ac888d696a3c56c2d2d2 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Thu, 23 Nov 2023 14:14:19 +0100 Subject: [PATCH 11/39] edit ch8 self-sig binding to primary ID --- book/source/08-signing_components.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index 29415ac..ff62e06 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -164,9 +164,9 @@ A [*direct key signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-cr In OpenPGP v6, a direct key signature is the [preferred mechanism](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-5.2.3.10-9). -#### Primary User ID binding self-signature +#### Self-signature binding to primary User ID -In a certificate, one User ID serves as the [*primary* User ID](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-primary-user-id). The metadata in the binding self-signature on this User ID applies to the primary key of the certificate. +In an OpenPGP certificate, one User ID serves as the [*primary* User ID](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-primary-user-id). The metadata in the binding self-signature on this User ID applies to the certificate's primary key. ### Revocation self-signatures: Invalidating components of a certificate From f795da774dc5c0f87d26c2c79690aae792375a95 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Thu, 23 Nov 2023 14:24:05 +0100 Subject: [PATCH 12/39] edit ch8 Revocation self-signatures --- book/source/08-signing_components.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index ff62e06..7b5e4ff 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -168,22 +168,22 @@ In OpenPGP v6, a direct key signature is the [preferred mechanism](https://www.i In an OpenPGP certificate, one User ID serves as the [*primary* User ID](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-primary-user-id). The metadata in the binding self-signature on this User ID applies to the certificate's primary key. -### Revocation self-signatures: Invalidating components of a certificate +### Revocation self-signatures: Invalidating certificate components -One important class of self-signatures are revocations. +Revocation self-signatures represent an important class of self-signatures, used primarily to invalidate components or retract prior signature statements. -A revocation signature is used to invalidate a component, or retract the statement formed by a prior signature. +There are several types of revocation signatures, each serving a specific purpose: -- A [*key revocation signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-revocation-signature-ty) (type ID `0x20`) marks a primary key as revoked. -- a [*subkey revocation signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-subkey-revocation-signature) (type ID `0x28`) revokes a prior subkey binding signature, while -- a [*certification revocation*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-certification-revocation-si) (type ID `0x30`) revokes a certification signature. +- A [**key revocation signature**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-revocation-signature-ty) (type ID `0x20`) marks a primary key as revoked. +- A [**subkey revocation signature**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-subkey-revocation-signature) (type ID `0x28`) revokes a prior subkey binding signature. +- A [**certification revocation**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-certification-revocation-si) (type ID `0x30`) revokes a certification signature. -Typical use-cases for revocations are marking certificates or individual subkeys as unusable (for example, when the private key has been compromised or superseded), or marking User IDs as no longer used. +Common scenarios for using revocations include marking certificates or individual subkeys as unusable (e.g., when the private key has been compromised or replaced) or declaring User IDs as no longer valid. ```{note} -OpenPGP certificates act as append-only data structures, in practice. Elements of a certiciate can not be removed from the copies on key servers and the OpenPGP systems of third parties, once published. Implementations usually merge all available components and signatures. +OpenPGP certificates act as append-only data structures in practice. Once elements of a certificate are published, they cannot be removed from key servers or third-party OpenPGP systems. Implementations usually merge all available components and signatures. -Revocations are used as a mechanism to mark components or signatures as invalid. +Revocations are used to mark components or signatures as invalid. ``` Note: certification signatures [can be made irrevocable](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-revocable). From a8b17f8fe4fc95f39abba86fa47183185f007b30 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Thu, 23 Nov 2023 14:34:23 +0100 Subject: [PATCH 13/39] edit ch8 soft and hard revocations --- book/source/08-signing_components.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index 7b5e4ff..236bfa9 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -188,17 +188,15 @@ Revocations are used to mark components or signatures as invalid. Note: certification signatures [can be made irrevocable](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-revocable). -#### Hard vs. soft revocations +#### Hard vs soft revocations -A revocation signature can contain a subpacket indicating the [*reason for revocation*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-reason-for-revocation). The value of this subpacket contains a code that specifies why the revocation was issued. This code determines whether the revocation is considered a *soft revocation* or a *hard revocation*: +Revocation signatures often include a [*reason for revocation*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-reason-for-revocation) subpacket, with a code specifying why the revocation was issued. This code determines whether the revocation is considered *soft* or *hard*. -- A *soft revocation* is typically used for graceful or planned invalidation. Soft revocation of a component invalidates it from the revocation signature's creation time onwards. Uses of the component before the revocation time remain intact. Soft revocations can be reverted by re-validating the invalidated component with a new self-signature. -- A *hard revocation*, by contrast, invalidates the component retroactively, rendering all past and future uses invalid. Hard revocation of a component cannot be undone by re-validating the component. - -Soft revocations are typically used when a certificate, subkey or User ID is retired or superseded gracefully, while hard revocations are typically used to signal compromise of secret key material. +- **Soft revocation**: This is typically used for graceful or planned invalidation of components, such as retiring or updating components. It invalidates the component from the revocation signature's creation time, but earlier uses remain valid. Soft revocations can be reversed with a new self-signature. +- **Hard revocation**: This irrevocably invalidates the component, affecting all past and future uses. It is typically used to signal compromise of secret key material. ```{note} -A revocation signature that has no *reason for revocation* subpacket is interpreted as a hard revocation. +A revocation signature lacking a *reason for revocation* subpacket is interpreted as a hard revocation. ``` (third_party_cert)= From 94abcc34f71ccad1bbe637a19be776b8bb1bb6ff Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Thu, 23 Nov 2023 16:44:21 +0100 Subject: [PATCH 14/39] edit ch8 3rd party signatures --- book/source/08-signing_components.md | 80 +++++++++++----------------- 1 file changed, 31 insertions(+), 49 deletions(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index 236bfa9..a65fb4e 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -40,7 +40,7 @@ No [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh- ### Third-party signatures -Third-party signatures are pivotal in OpenPGP for decentralized authentication, forming the basis of the *Web of Trust*. They encode authentication-related statements about certificates and linked identities, establishing trustworthiness and verification. +Third-party signatures are pivotal in OpenPGP for decentralized authentication, forming the basis of the Web of Trust. They encode authentication-related statements about certificates and linked identities, establishing trustworthiness and verification. Third-party signatures are used to make specific statements: @@ -62,7 +62,7 @@ The meaning of an OpenPGP signature depends significantly on its issuer. Self-si In another instance: - *When issued as a self-signature*, a [direct key signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-direct-key-signature-type-i) sets preferences and advertises features applicable to the entire certificate. -- *When issued by a third party*, especially when it carries a [trust signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-trust-signature) subpacket, a similar direct key signature delegates trust to the signed certificate. This designates the signed certificate as a trust root within the issuer's *Web of Trust*. +- *When issued by a third party*, especially when it carries a [trust signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-trust-signature) subpacket, a similar direct key signature delegates trust to the signed certificate. This designates the signed certificate as a trust root within the issuer's Web of Trust. ## Self-signatures in certificate formation and management @@ -200,76 +200,60 @@ A revocation signature lacking a *reason for revocation* subpacket is interprete ``` (third_party_cert)= -## Third-party signatures: Authentication statements +## Authentication and delegation in third-party signatures -Signatures on components by third parties mainly encode authentication of identities and delegations of trust decisions. - -Third party signatures can be inspected and reasoned about manually by humans. More powerfully, though, they can also be used as machine-readable artifacts, by OpenPGP software, which can reason about the authenticity of certificates on behalf of its users, based on trust roots that the user has specified. +Third-party signatures in OpenPGP primarily encode authentication statements for identities and delegate trust decisions. These signatures can be manually inspected or processed as machine-readable artifacts by OpenPGP software, which evaluates the authenticity of certificates based on user-specified trust roots. ### Certifying identity components -By issuing a certifying signature on an identity, the signer expresses that he has verified that the identity and the certificate are meaningfully linked. The signer vouches for the connection between the certificate and the identity. +When a signer issues a certifying signature on an identity, it indicates a verified link between the identity and the certificate.That is, the signer vouches for the connection. -If Alice is certain that the identity `Bob Baker ` controls the certificate `0xB0B`, she can create a certification signature that binds Bob's User ID and Bob's certificate. Bob will usually distribute this certifying signature from Alice as part of his certificate. +For example, Alice can certify Bob's User ID `Bob Baker ` with his certificate `0xB0B`, by creating a certification signature that binds Bob's User ID and Bob's certificate. Bob then distributes Alice's certifying signature as part of his certificate. -Effectively, this is a way for Alice to broadcast the statement "I, Alice, have checked that `Bob Baker ` controls the certificate `0xB0B`." Other users may or may not decide to rely on this statement by Alice. +Other users may or may not decide to rely on Alice's statement. -### Delegating authentication: Trust signatures +### Trust signatures: delegating authentication -The OpenPGP standard specifies primitives to delegate authentication decisions to certificates. The standard uses the (somewhat confusing) term "trust" for this mechanism. Delegating authentication decisions to a certificate, using a [*trust signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#trust-signature-subpacket) subpacket, makes the target certificate a "trusted introducer." +OpenPGP uses [*trust signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#trust-signature-subpacket) subpackets to delegate authentication decisions, transforming the recipient certificate into a "trusted introducer" (or a trust root) for the user. This includes specifying trust depth (or level) for transitive delegations and quantifying trust with numerical values, indicating the extent of reliance on the introducer's certifications. -A "trusted introducer" acts as a trust root for the user. +Trust signature subpackets are applicable in: -[*Trust signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#trust-signature-subpacket) subpackets can be used in two types of signatures: +- identity certification signatures (type ID `0x10` - `0x13`) +- [direct key signatures](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-direct-key-signature-type-i) (type ID `0x1F`) -- On an identity certification signature (type ID `0x10` - `0x13`), or on a -- [*direct key signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-direct-key-signature-type-i) (type ID `0x1F`) +#### Trust depth/level -#### Trust depth (or "level") +The trust depth (or level) in OpenPGP signifies the extent of transitive delegation within the authentication process. It determines how far the trust can be extended from the original trusted introducer to subsequent intermediaries. Essentially, a certificate with a designated trust depth acts as a "meta-introducer," facilitating authentication decisions across multiple levels in the network. -OpenPGP's delegation mechanism allows specifying transitive delegation of trust: delegating authentication decisions across more than one hop. The standard refers to certificates as a "meta-introducer," when a "trust signature" subpacket defines it as a trusted introducer with a depth (or "level") of two or more. +For example, a trust depth of 1 means there is direct trust in the certifications made by the trusted introducer. In this case, the user's OpenPGP software will accept certifications made directly by the introducer for authenticating identities. -A trust signature subpacket with means that the target certificate may delegate to a second, intermediate, introducer, which in turn has issued a certification signature for an identity. +However, when the trust depth is set higher, it implies a chain of trust extending beyond the initial introducer. The user's software will recognize and accept certifications made not only by the primary introducer but also by other intermediaries whom the primary introducer trusts. -**Examples** - -When Alice delegates trust decisions to Trent, designating Trent as a trusted introducer with a *trust depth* of 1, then Alice's OpenPGP implementation will only accept direct certifications by Trent. For example, Trent may have certified that Bob's certificate with the fingerprint `0xB0B` is legitimately connected to Bob's User ID `Bob `. If Alice tries to communicate with Bob using his identity `Bob `, then Alice's OpenPGP software can automatically determine that the certificate `0xB0B` is appropriate to use. - -However, Alice's OpenPGP software wouldn't accept a series of delegations from Trent via Tristan to a certification of Carol's identity (let's imagine that Trent has designated Tristan a trusted introducer). For Alice's OpenPGP software to accept such a path, she needs to designate Trent as a trusted introducer with the `level` set to 2 or more. +This allows for a more extensive network of trusted certifications, enabling a broader and more interconnected Web of Trust. ```{admonition} VISUAL :class: warning -add diagrams? +Heiko, I found the example confusing. So more text is here AND I recommend adding a visual to illustrate it, using your former example. ``` -#### Trust amount +#### Trust amounts -A trust signature can quantify the degree to which the issuer wants to rely on a delegation. This "trust amount" has a numerical value between 0 and 255. +The trust amount, with a numerical value ranging from 0 to 255, quantifies the degree of trust in a delegation. -A trust amount of 120 indicates "complete trust," which means that a certification by that trusted introducer is considered sufficient to consider authentications by that introducer as sufficient. - -**Examples** - -If Alice designates Trent as a trusted introducer at a trust amount of 120, then Alice's OpenPGP software will consider Bob's identity fully authenticated if Trent has certified it. - -However, if Alice only assigns a trust amount of 60 (which indicates "partial trust") to Trent, then her software would not consider Bob's identity fully authenticated. Now let's imagine that Alice additionally assigns a trust amount of 60 to Tristan (a second, independent introducer), and Tristan also certified Bob's identity. In this case, Alice's OpenPGP software will consider Bob's identity fully authenticated, based on the combination of both delegations, and the certifications the two trusted introducers issued. +A higher value indicates greater trust, such as 120 for complete trust, while lower values suggest partial trust. This quantification aids OpenPGP software in determining the authentication level based on combined trust from multiple trusted introducers. ```{admonition} VISUAL :class: warning -add diagrams? +add diagrams? @heiko -- yes, using the examples that I removed ``` -#### Limiting the scope of delegations with regular expressions +#### Limiting delegation scope -When using *trust signature* subpackets, a delegation can be limited to identities that match a [*regular expression*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#regex-subpacket), for example, to limit the email address in a User ID to a specific domain name. +When using *trust signature* subpackets, a delegation can be limited to identities that match a [*regular expression*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#regex-subpacket). -With this mechanism, it is possible to delegate authentication decisions only for User IDs that match the email domain of an organization. - -**Example** - -For example, Alice could delegate trust decisions only for email addresses in the domain `bob.com` to Bob, if she considers Bob to be a reasonable source of identity certifications for that domain. +With this mechanism, for example, it is possible to delegate authentication decisions only for User IDs that match the email domain of an organization. ```{admonition} VISUAL :class: warning @@ -278,19 +262,17 @@ add diagrams? ``` (wot)= -### Decentralized automated trust decisions; or, the "Web of Trust" +### Web of Trust: Decentralized trust decisions -The OpenPGP, the "Web of Trust" is a trust model that performs authentication decisions on a set of certifications and delegations[^strong-set]. +The Web of Trust in OpenPGP is a trust model that facilitates authentication decisions through a network of certifications and delegations.[^strong-set] It is characterized by a so-called [strong set](https://en.wikipedia.org/wiki/Web_of_trust#Strong_set), which refers to a group of certificates that are robustly interconnected via third-party certifications. -[^strong-set]: In the context of the Web of Trust, the so-called [strong set](https://en.wikipedia.org/wiki/Web_of_trust#Strong_set) refers to a set of certificates that are strongly linked amongst each other via third-party certifications. +In this model, users independently delegate authentication decisions, choosing whom to trust among various certificate issuers. This delegation is based on the certificates and third-party signatures available to them, with their OpenPGP software applying the Web of Trust mechanism to discern the reliability of each certificate for an identity. -The OpenPGP "Web of Trust" model assumes that every user makes their own choice about who they delegate authentication decisions to. Based on the available certificates and third-party signatures, the user's OpenPGP software uses the Web of Trust mechanism to determine which certificates are considered reliable for an identity. +The OpenPGP RFC doesn't specify exactly how Web of Trust calculations are performed. It only defines the data formats on which these calculations can be performed. See external resources in {numref}`wot-resources`. -The OpenPGP RFC doesn't specify how exactly Web of Trust calculations are performed. It only defines the data formats that these calculations can be performed on. See external resources in {numref}`wot-resources`. +### Revoking third-party signatures -### Revoking third-party signatures: Undoing previous statements - -The issuer of a third-party signature can undo such a signature by issuing a [*certification revocation signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-certification-revocation-si) (type ID `0x30`). +To reverse a previously issued third-party signature, the issuer can generate a [*certification revocation signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-certification-revocation-si) (type ID `0x30`). The revocation must be issued by the same key that created the original signature or, in deprecated practice, by a designated Revocation Key. ## Advanced topics From 8d4c1748c71c820bce44f3bba7f4e2eaaa664b69 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Thu, 23 Nov 2023 17:39:31 +0100 Subject: [PATCH 15/39] edit ch8 advanced section up to line 358 --- book/source/08-signing_components.md | 114 +++++++++++++-------------- 1 file changed, 55 insertions(+), 59 deletions(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index a65fb4e..58bd40a 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -276,91 +276,87 @@ To reverse a previously issued third-party signature, the issuer can generate a ## Advanced topics -### Certification Recipes +### Certification recipes -As mentioned above, different signatures are used for different purposes. -In this section, we will try to give guidance on how to create certain signatures by example. +Different signatures in OpenPGP serve various specific purposes. This section provides practical guidance on creating these signatures, illustrating each with concrete examples. -#### Change Algorithm Preferences +#### Change algorithm preferences + +To modify the preferred symmetric, compression, hash, or AEAD algorithms for a key, the key owner needs to issue a direct-key signature (type `0x1F`) on the primary key. -In order to change what symmetric, compression, hash or AEAD algorithms are preferred by the key owner, they can issue a direct-key signature (type 0x1F) on the primary key. This signature should have the following structure: -| Subpacket | Area | Critical | Mandatory | Notes | -|-----------|------|----------|-----------|-------| -| Signature Creation Time | Hashed | True | True | Current time | -| Issuer Fingerprint | Hashed | True or false | Strongly recommended | The primary key is the issuer | -| Key Flags | Hashed | True | False | Carry over key flags from previous self-signature | -| Features | Hashed | True | False | Carry over features from previous self-signature | -| Key Expiration Time | Hashed | True | False | Carry over expiration time from previous self-signature, if present | -| Hash Alg. Pref. | Hashed | False | False | New preferences | -| Comp. Alg. Pref. | Hashed | False | False | New preferences | -| Symm. Alg. Pref. | Hashed | False | False | New preferences | -| AEAD Alg. Pref. | Hashed | False | False | New preferences | +| Subpacket | Area | Critical | Mandatory | Notes | +|---------------------------------|--------|----------------|-------------------|---------------------------| +| Signature Creation Time | Hashed | True | True | Should be the current time| +| Issuer Fingerprint | Hashed | True or False | Strongly Recommended | Identifies the primary key as the issuer | +| Key Flags | Hashed | True | False | Retain key flags from the previous self-signature | +| Features | Hashed | True | False | Retain features from the previous self-signature | +| Key Expiration Time | Hashed | True | False | If applicable, use expiration time from the previous self-signature | +| Hash Algorithm Preferences | Hashed | False | False | New preferences | +| Compression Algorithm Preferences | Hashed | False | False | New preferences | +| Symmetric Algorithm Preferences | Hashed | False | False | New preferences | +| AEAD Algorithm Preferences | Hashed | False | False | New preferences | -#### Change Expiration Time +#### Change expiration time -The recommended way to change the expiration time of a certificate is by issuing a new `DirectKey` signature (type 0x1F) with an adjusted Key Expiration Time subpacket. -The structure of such a signature is the same as in the section above. -It is also possible to change the expiration date of individual User IDs (see section below) or separate subkeys (see {numref}`bind_subkey`). +To adjust the expiration time of an OpenPGP certificate, issue a new `DirectKey` signature (type `0x1F`) with a modified Key Expiration Time subpacket. The structure of this signature is identical to the one outlined in the previous section on changing algorithm preferences. + +Additionally, the expiration date can be altered for individual User IDs (detailed below) or separate subkeys (see {numref}`bind_subkey`). #### Add User ID -A signature that binds a User ID to a certificate should have the following structure: +To bind a User ID to an OpenPGP certificate, the signature should have the following structure: -| Subpacket | Area | Critical | Mandatory | Notes | -|-----------|------|----------|-----------|-------| -| Signature Creation Time | Hashed | True | True | Current time | -| Issuer Fingerprint | Hashed | True or false | Strongly Recommended | The primary key is the issuer | -| Primary User ID | Hashed | True | False | Optional | -| Signature Expiration Time | Hashed | True | False | Optional | +| Subpacket | Area | Critical | Mandatory | Notes | +|-------------------------|--------|----------------|-------------------|---------------------------------------| +| Signature Creation Time | Hashed | True | True | Current time | +| Issuer Fingerprint | Hashed | True or False | Strongly Recommended | Identifies the primary key as the issuer | +| Primary User ID | Hashed | True | False | Optional | +| Signature Expiration Time | Hashed | True | False | Optional | -Self-certifications over User IDs can optionally carry the same subpackets as listed in the previous table (key flags, features, algorithm preferences). -This way, separate capabilities can be assigned to different identities. -#### Remove / Revoke User ID +In addition to these subpackets, self-certifications for User IDs can include others – such as key flags, features, and algorithm preferences – as shown in the previous table. This enables the specification of unique capabilities and preferences for each identity associated with the certificate. + +#### Remove or revoke a User ID Since OpenPGP certificates are often distributed by the means of key servers, new signatures on a certificate are often "merged" into existing copies of the certificate locally by the recipient. -This means, that it is not really possible to remove signatures / User IDs from a certificate, as there is no way to communicate the intention of packet deletion to the recipient. +This integration process means it is practically impossible to directly remove signatures or User IDs from a certificate, as there is no way to communicate the intention of packet deletion to the recipient. -So to mark a User ID as invalid, the user can publish a copy of their certificate with a `CertificationRevocation` (signature type 0x30) attached to the invalidated User ID. -This signature signals that the holder of the certificate no longer wants to be associated with that User ID. +To effectively mark a User ID as invalid, the user can publish a copy of their certificate with a *CertificationRevocation* signature(type `0x30`) attached to the invalidated User ID. This signature signals that the specified User ID is no longer valid or associated with the certificate holder. The structure of a certification revocation is as follows: -| Subpacket | Area | Critical | Mandatory | Notes | -|-----------|------|----------|-----------|-------| -| Signature Creation Time | Hashed | True | True | Current time | -| Issuer Fingerprint | Hashed | True or false | Strongly Recommended | The primary key is the issuer | -| Reason for Revocation | Hashed | True | False | Decides over soft / hard revocation | +| Subpacket | Area | Critical | Mandatory | Notes | +|---------------------|--------|----------------|-------------------|---------------------------------------------| +| Signature Creation Time | Hashed | True | True | Should be the current time | +| Issuer Fingerprint | Hashed | True or False | Strongly Recommended | Indicates the primary key as the issuer | +| Reason for Revocation | Hashed | True | False | Determines the nature of the revocation | -For User ID revocations, the value of the reason subpacket can either be `0` (no reason specified) or `32`, signaling that the User ID is no longer valid. -The latter would result in a soft revocation, while a reason code of `0` is considered a hard revocation. -Omitting the reason packet altogether is also equivalent to a hard revocation. -It is recommended to issue User ID revocations using a reason code `32`. +For User ID revocations, the `Reason for Revocation` subpacket is crucial. A value of `0` means no specific reason, leading to a hard revocation, while `32` indicates the User ID is no longer valid, resulting in a soft revocation. Omitting the reason subpacket is also equivalent to a hard revocation. + +It is generally advisable to use reason code `32` for revoking User IDs. (binding_subkeys)= -#### Add a Subkey +#### Add a subkey -A user might want to add a new subkey to their certificate, for example to replace an old subkey with one that uses a newer cryptographic algorithm. +Users may need to add a new subkey to their OpenPGP certificate, often for reasons such as upgrading to a subkey with more advanced cryptographic algorithms. The process involves creating a specific signature structure: -The structure is as follows: +| Subpacket | Area | Critical | Mandatory | Notes | +|-------------------------------|--------|----------------|-------------------|-----------------------------------------------------| +| Signature Creation Time | Hashed | True | True | Current time | +| Issuer Fingerprint | Hashed | True or False | Strongly Recommended | The primary key is the issuer | +| Key Flags | Hashed | True | Strongly Recommended | Determine the usage of the key | +| Key Expiration Time | Hashed | True | False | Specifies the expiration date of the subkey | +| Embedded Signature | Hashed | True | If Key Flags contains **S** | Signing subkeys require embedded *Primary Key Binding* signature | +| Hash Algorithm Preferences | Hashed | False | False | Per key preferences | +| Compression Algorithm Preferences | Hashed | False | False | Per key preferences | +| Symmetric Algorithm Preferences | Hashed | False | False | Per key preferences | +| AEAD Algorithm Preferences | Hashed | False | False | Per key preferences | -| Subpacket | Area | Critical | Mandatory | Notes | -|-----------|------|----------|-----------|-------| -| Signature Creation Time | Hashed | True | True | Current time | -| Issuer Fingerprint | Hashed | True or false | Strongly Recommended | The primary key is the issuer | -| Key Flags | Hashed | True | Strongly Recommended | Determine the usage of the key | -| Key Expiration Time | Hashed | True | False | Specifies the expiration date of the subkey | -| Embedded Signature | Hashed | True | If Key Flags contains **S** | Signing subkeys require embedded `PrimaryKeyBinding` signature | -| Hash Alg. Pref. | Hashed | False | False | Per key preferences | -| Comp. Alg. Pref. | Hashed | False | False | Per key preferences | -| Symm. Alg. Pref. | Hashed | False | False | Per key preferences | -| AEAD Alg. Pref. | Hashed | False | False | Per key preferences | +In addition to these subpackets, users can specify algorithm preferences for each subkey, distinct from those set in the certificate's *DirectKey* signature. -Optional algorithm preference subpackets can be used to signal per-subkey preferences that deviate from those set in the certificates `DirectKey` signature. - -#### Revoke a Subkey +#### Revoke a subkey Analogous to User IDs, subkeys can be revoked individually. This is done by issuing a `SubkeyRevocation` signature (type 0x28) using the primary key. From 14a95e19075b4a943e0001dd1a492f7222b71a6f Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Sat, 25 Nov 2023 10:56:24 +0100 Subject: [PATCH 16/39] push final edits of Ch8, clarify use of italics --- book/source/08-signing_components.md | 80 ++++++++++++++-------------- 1 file changed, 40 insertions(+), 40 deletions(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index 58bd40a..8fa627c 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -190,13 +190,13 @@ Note: certification signatures [can be made irrevocable](https://www.ietf.org/ar #### Hard vs soft revocations -Revocation signatures often include a [*reason for revocation*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-reason-for-revocation) subpacket, with a code specifying why the revocation was issued. This code determines whether the revocation is considered *soft* or *hard*. +Revocation signatures often include a [*Reason for Revocation* subpacket](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-reason-for-revocation), with a code specifying why the revocation was issued. This code determines whether the revocation is considered *soft* or *hard*. - **Soft revocation**: This is typically used for graceful or planned invalidation of components, such as retiring or updating components. It invalidates the component from the revocation signature's creation time, but earlier uses remain valid. Soft revocations can be reversed with a new self-signature. - **Hard revocation**: This irrevocably invalidates the component, affecting all past and future uses. It is typically used to signal compromise of secret key material. ```{note} -A revocation signature lacking a *reason for revocation* subpacket is interpreted as a hard revocation. +A revocation signature lacking a *Reason for Revocation* subpacket is interpreted as a hard revocation. ``` (third_party_cert)= @@ -300,7 +300,7 @@ This signature should have the following structure: #### Change expiration time -To adjust the expiration time of an OpenPGP certificate, issue a new `DirectKey` signature (type `0x1F`) with a modified Key Expiration Time subpacket. The structure of this signature is identical to the one outlined in the previous section on changing algorithm preferences. +To adjust the expiration time of an OpenPGP certificate, issue a new *DirectKey* signature (type `0x1F`) with a modified Key Expiration Time subpacket. The structure of this signature is identical to the one outlined in the previous section on changing algorithm preferences. Additionally, the expiration date can be altered for individual User IDs (detailed below) or separate subkeys (see {numref}`bind_subkey`). @@ -320,8 +320,7 @@ In addition to these subpackets, self-certifications for User IDs can include ot #### Remove or revoke a User ID -Since OpenPGP certificates are often distributed by the means of key servers, new signatures on a certificate are often "merged" into existing copies of the certificate locally by the recipient. -This integration process means it is practically impossible to directly remove signatures or User IDs from a certificate, as there is no way to communicate the intention of packet deletion to the recipient. +Since OpenPGP certificates are often distributed by the means of key servers, new signatures on a certificate are often "merged" into existing copies of the certificate locally by the recipient. This integration process means it is practically impossible to directly remove signatures or User IDs from a certificate, as there is no way to communicate the intention of packet deletion to the recipient. To effectively mark a User ID as invalid, the user can publish a copy of their certificate with a *CertificationRevocation* signature(type `0x30`) attached to the invalidated User ID. This signature signals that the specified User ID is no longer valid or associated with the certificate holder. @@ -333,7 +332,7 @@ The structure of a certification revocation is as follows: | Issuer Fingerprint | Hashed | True or False | Strongly Recommended | Indicates the primary key as the issuer | | Reason for Revocation | Hashed | True | False | Determines the nature of the revocation | -For User ID revocations, the `Reason for Revocation` subpacket is crucial. A value of `0` means no specific reason, leading to a hard revocation, while `32` indicates the User ID is no longer valid, resulting in a soft revocation. Omitting the reason subpacket is also equivalent to a hard revocation. +For User ID revocations, the *Reason for Revocation* subpacket is crucial. A value of `0` means no specific reason, leading to a hard revocation, while `32` indicates the User ID is no longer valid, resulting in a soft revocation. Omitting the reason subpacket is also equivalent to a hard revocation. It is generally advisable to use reason code `32` for revoking User IDs. @@ -358,57 +357,58 @@ In addition to these subpackets, users can specify algorithm preferences for eac #### Revoke a subkey -Analogous to User IDs, subkeys can be revoked individually. -This is done by issuing a `SubkeyRevocation` signature (type 0x28) using the primary key. -The structure of such a signature is rather minimal: +Subkeys, like User IDs, can be individually revoked in OpenPGP. +This is done by issuing a `SubkeyRevocation` signature (type `0x28`) using the primary key. -| Subpacket | Area | Critical | Mandatory | Notes | -|-----------|------|----------|-----------|-------| -| Signature Creation Time | Hashed | True | True | Current time | -| Issuer Fingerprint | Hashed | True or false | Strongly Recommended | The primary key is the issuer | -| Reason for Revocation | Hashed | True | False | Decides over soft / hard revocation | +The structure of such a signature is straightforward: -In `SubkeyRevocation` signatures, the [reason subpacket](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-reason-for-revocation) cannot have value `32`, but instead may be from the range of `0-3`. -Values `1` (key superseded) and `3` (key retired and no longer used) are soft reasons, while `0` (no reason) and `2` (key compromised) are considered hard. +| Subpacket | Area | Critical | Mandatory | Notes | +|-------------------------|--------|----------------|-------------------|-------------------------------------------------| +| Signature Creation Time | Hashed | True | True | Current time | +| Issuer Fingerprint | Hashed | True or False | Strongly Recommended | The primary key is the issuer | +| Reason for Revocation | Hashed | True | False | Determines soft or hard revocation | -#### Revoke a Certificate -A user might want to revoke their entire certificate, rendering it unusable. +In `SubkeyRevocation` signatures, the [reason for revocation](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-reason-for-revocation) subpacket is critical. The values `1` (key superseded) and `3` (key retired and no longer used) indicate soft revocations, whereas values `0` (no reason) and `2` (key compromised) indicate hard revocations. -Depending on the circumstances, they might either want to revoke it softly, e.g. in case of migration to a new certificate, or they want to issue a hard revocation, e.g. in case of secret key material compromise. A soft-revoked certificate can be re-validated at a later point in time, by issuing a new certification, while a hard revocation is typically permanent. +Note that a value of `32` is not applicable in these signatures. -The recommended way to revoke a certificate is by issuing a `KeyRevocation` signature (type 0x20). -The structure of a key revocation signature is similar to that of a `CertificationRevocation` signature. +#### Revoke a certificate -| Subpacket | Area | Critical | Mandatory | Notes | -|-----------|------|----------|-----------|-------| -| Signature Creation Time | Hashed | True | True | Current time | -| Issuer Fingerprint | Hashed | True or false | Strongly Recommended | The primary key is the issuer | -| Reason for Revocation | Hashed | True | False | Decides over soft / hard revocation | +Users may find themselves needing to revoke their entire OpenPGP certificate, rendering it unusable. This could be for various reasons, such as migrating to a new certificate or in response to a compromise of the certificate's secret key material. -For `KeyRevocation` signatures, the same constraints as for `SubkeyRevocation` signatures apply to the [reason subpacket](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-reason-for-revocation). +While a soft-revoked certificate can be re-validated at a later time with a new certification, a hard revocation is typically permanent. -#### Common Subpackets +The recommended way to revoke a certificate is by issuing a *KeyRevocation* signature (type `0x20`). Its structure is similar to that of a *CertificationRevocation* signature. -There are some subpackets that are expected to be included in all types of signatures. +| Subpacket | Area | Critical | Mandatory | Notes | +|-------------------------|--------|----------------|-------------------|-------------------------------------------------| +| Signature Creation Time | Hashed | True | True | Current time | +| Issuer Fingerprint | Hashed | True or False | Strongly Recommended | The primary key is the issuer | +| Reason for Revocation | Hashed | True | False | Determines soft or hard revocation | -* **Signature Creation Time**: Every OpenPGP signature MUST contain a Signature Creation Time subpacket (2) containing the timestamp at which the signature was made. This packet MUST be present in the hashed area of the signature and SHOULD be marked as critical. +For *KeyRevocation* signatures, the guidelines regarding the [*Reason for Revocation* subpacket] (https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-reason-for-revocation) are the same as those for *SubkeyRevocation* signatures. -* **Issuer Fingerprint**: To be able to verify a signature, the verifier needs to know which (sub-)key was used to issue the signature in the first place. Therefore, every OpenPGP v6 signature SHOULD contain an Issuer Fingerprint subpacket (33) containing the 32 byte fingerprint of the particular component key that was used to create the signature. +#### Common subpackets in OpenPGP signatures + +In OpenPGP, certain subpackets are universally expected across all types of signatures, serving fundamental roles in the signature's structure and verification: + +* **Signature Creation Time**: This is a mandatory subpacket in every OpenPGP signature. It contains the timestamp of when the signature was created. For security and integrity, this subpacket must be located in the hashed area of the signature and is recommended to be marked as critical. + +* **Issuer Fingerprint**: Essential for signature verification, this subpacket identifies the key (or subkey) used to create the signature. OpenPGP v6 signatures should include the Issuer Fingerprint subpacket, containing the 32-byte fingerprint of the key. ```{note} The issuer key might be a subkey. ``` -Since the issuer fingerprint subpacket is self-authenticating, it can either be included as a hashed or unhashed subpacket, but the authors of this book recommend to place it in the hashed area of the signature. +This subpacket can be placed in either the hashed or unhashed area due to its self-authenticating nature. However, it is recommended to include it in the signature's hashed area for enhanced security. -### Potential subpacket conflicts and duplication +### Managing subpacket conflicts and duplication -Since the hashed and unhashed areas of a signature are just lists of subpackets, in principle they allow duplicates of the same subpacket, which might lead to conflicts. -Therefore, packets in the hashed area take precedence over the unhashed area. -However, there may still be conflicts between packets in the same area, e.g., two conflicting expiration dates, etc. -The [specification recommends](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-notes-on-subpackets) that implementations favor the last occurrence of a conflicting packet in the hashed area (that is, the last entry for that subpacket type in the sequence of subpackets in the hashed area). +In OpenPGP signatures, both the hashed and unhashed areas are composed of lists of subpackets. Inherently, this structure permits the duplication of the same subpacket, which could lead to conflicts. To manage these potential conflicts: -In some cases, duplicate packets with conflicting content even make sense, e.g., if a signature was made by a version 4 issuer key whose key material was migrated from an older OpenPGP version such as v3. -In this case, either the v3 or v4 key could be used to validate the v4 signature, but since the key ID calculation scheme was changed between v3 and v4, these identifiers would differ. -Therefore, the signature could contain two issuer key ID subpackets with conflicting, but correct values. +- **Precedence of hashed area**: Subpackets within the hashed area of a signature take precedence over those in the unhashed area. This hierarchy helps resolve conflicts when the same subpacket appears in both areas. + +- **Handling conflicts within the same area**: Conflicts can still arise within the same area, such as when two subpackets have different expiration dates. In such cases, the [OpenPGP specification](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-notes-on-subpackets) advises that implementations should favor the last occurrence of a conflicting subpacket in the hashed area. + +In certain scenarios, having duplicate subpackets with conflicting content is logical and even necessary. For example, consider a signature created by a version 4 issuer key, which was upgraded from an older OpenPGP version (like v3). Since the key ID calculation scheme changed from v3 to v4, the identifiers for the same key would differ between these versions. Therefore, a v4 signature might contain two issuer key ID subpackets, each with different, yet correct values for v3 and v4 keys, respectively. This allows for backward compatibility and ensures the signature can be validated under both key ID calculation schemes. \ No newline at end of file From 8e81ed6b36037aa1185f4b32f36ccbb415ee68ab Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Sat, 25 Nov 2023 10:57:40 +0100 Subject: [PATCH 17/39] expand note for clarity --- book/source/08-signing_components.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index 8fa627c..350efdb 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -398,7 +398,7 @@ In OpenPGP, certain subpackets are universally expected across all types of sign * **Issuer Fingerprint**: Essential for signature verification, this subpacket identifies the key (or subkey) used to create the signature. OpenPGP v6 signatures should include the Issuer Fingerprint subpacket, containing the 32-byte fingerprint of the key. ```{note} -The issuer key might be a subkey. +The key used as the issuer in the signature might be a subkey of the primary key. ``` This subpacket can be placed in either the hashed or unhashed area due to its self-authenticating nature. However, it is recommended to include it in the signature's hashed area for enhanced security. From 8fe5dfcf3370b3b4ee625b4a1ff5384f1e09f99d Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Sat, 25 Nov 2023 11:04:59 +0100 Subject: [PATCH 18/39] restore language of table but fix layout --- book/source/08-signing_components.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index 350efdb..ca3a96d 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -308,12 +308,12 @@ Additionally, the expiration date can be altered for individual User IDs (detail To bind a User ID to an OpenPGP certificate, the signature should have the following structure: -| Subpacket | Area | Critical | Mandatory | Notes | -|-------------------------|--------|----------------|-------------------|---------------------------------------| -| Signature Creation Time | Hashed | True | True | Current time | -| Issuer Fingerprint | Hashed | True or False | Strongly Recommended | Identifies the primary key as the issuer | -| Primary User ID | Hashed | True | False | Optional | -| Signature Expiration Time | Hashed | True | False | Optional | +| Subpacket | Area | Critical | Mandatory | Notes | +|-------------------------|--------|----------------|-------------------|-------------------------------------------------| +| Signature Creation Time | Hashed | True | True | Current time | +| Issuer Fingerprint | Hashed | True or False | Strongly Recommended | The primary key is the issuer | +| Primary User ID | Hashed | True | False | Optional | +| Signature Expiration Time | Hashed | True | False | Optional | In addition to these subpackets, self-certifications for User IDs can include others – such as key flags, features, and algorithm preferences – as shown in the previous table. This enables the specification of unique capabilities and preferences for each identity associated with the certificate. From 78b276604993a2ee563b9180db8c7923214e4c6e Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Sat, 25 Nov 2023 11:09:11 +0100 Subject: [PATCH 19/39] correct CertificationRevocation section --- book/source/08-signing_components.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index ca3a96d..5d89d83 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -322,15 +322,16 @@ In addition to these subpackets, self-certifications for User IDs can include ot Since OpenPGP certificates are often distributed by the means of key servers, new signatures on a certificate are often "merged" into existing copies of the certificate locally by the recipient. This integration process means it is practically impossible to directly remove signatures or User IDs from a certificate, as there is no way to communicate the intention of packet deletion to the recipient. -To effectively mark a User ID as invalid, the user can publish a copy of their certificate with a *CertificationRevocation* signature(type `0x30`) attached to the invalidated User ID. This signature signals that the specified User ID is no longer valid or associated with the certificate holder. +To effectively mark a User ID as invalid, the user can publish a copy of their certificate with a *CertificationRevocation* signature (type `0x30`) attached to the invalidated User ID. This signature signals that the specified User ID is no longer valid or associated with the certificate holder. -The structure of a certification revocation is as follows: +The structure of a *CertificationRevocation* is as follows: + +| Subpacket | Area | Critical | Mandatory | Notes | +|-------------------------|--------|----------------|-------------------|-------------------------------------------------| +| Signature Creation Time | Hashed | True | True | Current time | +| Issuer Fingerprint | Hashed | True or False | Strongly Recommended | The primary key is the issuer | +| Reason for Revocation | Hashed | True | False | Determines soft or hard revocation | -| Subpacket | Area | Critical | Mandatory | Notes | -|---------------------|--------|----------------|-------------------|---------------------------------------------| -| Signature Creation Time | Hashed | True | True | Should be the current time | -| Issuer Fingerprint | Hashed | True or False | Strongly Recommended | Indicates the primary key as the issuer | -| Reason for Revocation | Hashed | True | False | Determines the nature of the revocation | For User ID revocations, the *Reason for Revocation* subpacket is crucial. A value of `0` means no specific reason, leading to a hard revocation, while `32` indicates the User ID is no longer valid, resulting in a soft revocation. Omitting the reason subpacket is also equivalent to a hard revocation. From 09efc3db67135741ccce2bb9dafab811113b041c Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Sat, 25 Nov 2023 11:09:32 +0100 Subject: [PATCH 20/39] correct CertificationRevocation section --- book/source/08-signing_components.md | 1 - 1 file changed, 1 deletion(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index 5d89d83..b307791 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -332,7 +332,6 @@ The structure of a *CertificationRevocation* is as follows: | Issuer Fingerprint | Hashed | True or False | Strongly Recommended | The primary key is the issuer | | Reason for Revocation | Hashed | True | False | Determines soft or hard revocation | - For User ID revocations, the *Reason for Revocation* subpacket is crucial. A value of `0` means no specific reason, leading to a hard revocation, while `32` indicates the User ID is no longer valid, resulting in a soft revocation. Omitting the reason subpacket is also equivalent to a hard revocation. It is generally advisable to use reason code `32` for revoking User IDs. From b8346285585b9d9fac7ec19386375abebbb0e43c Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Sat, 25 Nov 2023 11:19:56 +0100 Subject: [PATCH 21/39] restore language to table, clean up structure --- book/source/08-signing_components.md | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index b307791..052c341 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -286,17 +286,17 @@ To modify the preferred symmetric, compression, hash, or AEAD algorithms for a k This signature should have the following structure: -| Subpacket | Area | Critical | Mandatory | Notes | -|---------------------------------|--------|----------------|-------------------|---------------------------| -| Signature Creation Time | Hashed | True | True | Should be the current time| -| Issuer Fingerprint | Hashed | True or False | Strongly Recommended | Identifies the primary key as the issuer | -| Key Flags | Hashed | True | False | Retain key flags from the previous self-signature | -| Features | Hashed | True | False | Retain features from the previous self-signature | -| Key Expiration Time | Hashed | True | False | If applicable, use expiration time from the previous self-signature | -| Hash Algorithm Preferences | Hashed | False | False | New preferences | -| Compression Algorithm Preferences | Hashed | False | False | New preferences | -| Symmetric Algorithm Preferences | Hashed | False | False | New preferences | -| AEAD Algorithm Preferences | Hashed | False | False | New preferences | +| Subpacket | Area | Critical | Mandatory | Notes | +|---------------------------------|--------|----------------|-------------------|----------------------------------------------------| +| Signature Creation Time | Hashed | True | True | Current time | +| Issuer Fingerprint | Hashed | True or False | Strongly Recommended | The primary key is the issuer | +| Key Flags | Hashed | True | False | Retain key flags from the previous self-signature | +| Features | Hashed | True | False | Retain features from the previous self-signature | +| Key Expiration Time | Hashed | True | False | Retain expiration time from the previous self-signature, if applicable | +| Hash Algorithm Preferences | Hashed | False | False | New preferences | +| Compression Algorithm Preferences | Hashed | False | False | New preferences | +| Symmetric Algorithm Preferences | Hashed | False | False | New preferences | +| AEAD Algorithm Preferences | Hashed | False | False | New preferences | #### Change expiration time @@ -315,7 +315,6 @@ To bind a User ID to an OpenPGP certificate, the signature should have the follo | Primary User ID | Hashed | True | False | Optional | | Signature Expiration Time | Hashed | True | False | Optional | - In addition to these subpackets, self-certifications for User IDs can include others – such as key flags, features, and algorithm preferences – as shown in the previous table. This enables the specification of unique capabilities and preferences for each identity associated with the certificate. #### Remove or revoke a User ID From e66d5158a863bff15cd699360854d53a45dff3e1 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Sat, 25 Nov 2023 11:24:00 +0100 Subject: [PATCH 22/39] fix apostrophe format --- book/source/08-signing_components.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index 052c341..d132e01 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -99,7 +99,7 @@ Linking an OpenPGP subkey to the primary key with a binding signature Metadata for the subkey, such as the [*key expiration time*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#key-expiration-subpacket) and capabilities set by [*key flags*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#key-flags), are included in subpackets within the subkey binding signature packet. ```{note} -The validity of a subkey is intrinsically linked to that of the primary key. An expired primary key renders any associated subkey invalid, regardless of the subkey’s own expiration setting. +The validity of a subkey is intrinsically linked to that of the primary key. An expired primary key renders any associated subkey invalid, regardless of the subkey's own expiration setting. Legally, a subkey may not have a specified expiry time. In such cases, its expiration aligns implicitly with that of the primary key. Additionally, the creation date of a subkey must always be more recent than that of the primary key. ``` @@ -111,7 +111,7 @@ Binding subkeys that possess the *signing* key flag to a certificate represents That is, to bind a signing-capable subkey to a primary key, it is insufficient that the "primary key wants to be associated with the subkey." The subkey must explicitly signal that it "wants to be associated with the primary key." -This mutual binding is crucial for security. Without it, an individual (e.g., Alice) could falsely claim a connection to another person’s (e.g., Bob's) signing subkey. To prevent such scenarios, where an attacker might wrongfully "adopt" a victim's signing subkey, a dual-layer of signatures is used: +This mutual binding is crucial for security. Without it, an individual (e.g., Alice) could falsely claim a connection to another person's (e.g., Bob's) signing subkey. To prevent such scenarios, where an attacker might wrongfully "adopt" a victim's signing subkey, a dual-layer of signatures is used: - the [subkey binding signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-subkey-binding) (type ID `0x18`), which is issued by the certificate's primary key - the [primary key binding signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#sigtype-primary-binding) (type ID `0x19`), created by the subkey itself. This is informally known as an embedded "back signature," because the subkey's signature points back to the primary key. From 1a4ef8a9756ef628573c1dd067e62899047873eb Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 25 Nov 2023 13:04:21 +0100 Subject: [PATCH 23/39] clarify: the flag is not always set --- book/source/08-signing_components.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index d132e01..24b7d7f 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -49,7 +49,7 @@ Third-party signatures are used to make specific statements: - revoking, and thus invalidating, prior third-party signature statements ```{note} -The **certify others** [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags) (`0x01`) is required to issue third-party signatures. Only the certificate's primary holds this key flag. +The **certify others** [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags) (`0x01`) is required to issue third-party signatures. Only the certificate's primary can hold this key flag. ``` ### Distinct functions of self-signatures and third-party signatures From 2580ae317ddb9905cbb252bec65f4e99175c65cc Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 25 Nov 2023 13:05:51 +0100 Subject: [PATCH 24/39] typo fix --- book/source/08-signing_components.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index 24b7d7f..f946716 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -57,7 +57,7 @@ The **certify others** [key flag](https://www.ietf.org/archive/id/draft-ietf-ope The meaning of an OpenPGP signature depends significantly on its issuer. Self-signatures and third-party signatures, even when of the same type, serve distinct functions. For example: - Certifying self-signatures (type IDs `0x10` - `0x13`) bind a User ID to a certificate. -- Third-party signatures of the same type IDs endorses the authenticity of a User ID. +- Third-party signatures of the same type IDs endorse the authenticity of a User ID. In another instance: From e05f10497424e30ed3af03c9e02c7efb1af927e6 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 25 Nov 2023 14:01:50 +0100 Subject: [PATCH 25/39] clarify enumeration of legitimate unbound packets This is supposed to be a list of legitimate uses. I've removed the elaboration of the flooding problem, and replaced it with a link to an elaboration in ch4. --- book/source/08-signing_components.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index f946716..2cd900b 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -76,12 +76,11 @@ To safeguard against unauthorized additions, OpenPGP uses cryptographic signatur Conversely, omissions of packets by third parties can easily occur when handling an OpenPGP certificate dataset. This could pose a challenge, for example, when an attacker deliberately omits revocation packets. Without access to an alternative, complete certificate source, recipients might not detect these omissions. ``` -However, there are instances – legitimate and malicious – in which third parties add "unbound" packets (i.e., not signed by the certificate's owner) to a certificate: +However, there are legitimate instances in which third parties add "unbound" packets (i.e., not signed by the certificate's owner) to a certificate: -- [Third-party certifications](third_party_cert) are often stored within the packet data of the certificate to which they are related.This is a standard practice that provides convenience for users by allowing easy access to all relevant certifications. However, in systems that unconditionally accept these certifications, it can lead to unintended consequences. Specifically, this approach has been exploited to cause denial-of-service attacks through [certificate flooding](https://dkg.fifthhorseman.net/blog/openpgp-certificate-flooding.html), a problem notably experienced by the SKS network of OpenPGP servers. +- [Third-party certifications](third_party_cert) are often stored within the packet data of the certificate to which they are related. This is a standard practice that provides convenience for users by allowing easy access to all relevant certifications. (See {ref}`cert-flooding` for discussion of a related pitfall.) - OpenPGP software may locally append [unbound identity data](unbound_user_ids) to a certificate. - (bind_subkey)= ### Binding subkeys to a certificate From cdbf15e49a3643db01ec5e11e9d02e568494adc5 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 25 Nov 2023 14:47:34 +0100 Subject: [PATCH 26/39] clarify how the back signature is embedded --- book/source/08-signing_components.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index 2cd900b..50e3083 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -120,7 +120,7 @@ This mutual binding is crucial for security. Without it, an individual (e.g., Al Linking an OpenPGP signing subkey to the primary key with a binding signature, and an embedded primary key binding signature ``` -The back signature signifies the mutuality of the subkey's association with the primary key and is embedded within the subkey binding signature, reinforcing the authenticity of the binding. +The back signature signifies the mutuality of the subkey's association with the primary key and is embedded as subpacket data within the subkey binding signature, reinforcing the authenticity of the binding. (bind_ident)= ### Binding identities to a certificate From 97e413a3dd6665c21b232abebcb32979221f15e2 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 25 Nov 2023 14:53:00 +0100 Subject: [PATCH 27/39] in our text, this fingerprint represents Alice's certificate (and isn't an example) --- book/source/08-signing_components.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index 50e3083..0d59de1 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -127,7 +127,7 @@ The back signature signifies the mutuality of the subkey's association with the Self-signatures also play a vital role in binding identity components, such as User IDs or User Attributes, to an OpenPGP certificate. -Take for instance, the User ID `Alice Adams `. To link this User ID to her OpenPGP certificate (e.g., `AAA1 8CBB 2546 85C5 8358 3205 63FD 37B6 7F33 00F9 FB0E C457 378C D29F 1026 98B3`), Alice would use a cryptographic signature. +Take for instance, the User ID `Alice Adams `. To link this User ID to her OpenPGP certificate (`AAA1 8CBB 2546 85C5 8358 3205 63FD 37B6 7F33 00F9 FB0E C457 378C D29F 1026 98B3`), Alice would use a cryptographic signature. There are four types of *certifying self-signature*. The most commonly used type for binding User IDs is the [positive certification](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-positive-cert) (type ID `0x13`). Alternatively, types `0x10`, `0x11` or `0x12` might be used. This binding signature must be issued by the primary key. From 5faec16cb80571228fce678f544ac69e463858a1 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 25 Nov 2023 14:56:17 +0100 Subject: [PATCH 28/39] Improve on original text: "Elements" encompass both "components" and "signatures." Regarding malicious addition, we care about both. Additionally, "typically" reads confusingly weak to me, erring on the side of "maybe too strong" with "will" seems better. --- book/source/08-signing_components.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index 0d59de1..0c09153 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -70,7 +70,7 @@ Self-signatures play a crucial role in forming and managing the structure of Ope Internally, an OpenPGP certificate is essentially a series of packets strung sequentially. When a certificate is stored in a file format known as a [transferable public key](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-transferable-public-keys), packets can be easily added or removed. -To safeguard against unauthorized additions, OpenPGP uses cryptographic signatures. These validate that any additions, such as subkeys or [identity components](identity_components), were made by the owner of the OpenPGP certificate using its primary key. While anyone can still store unrelated subkeys and identity components to a certificate dataset, OpenPGP implementations typically reject components lacking a valid cryptographic connection with the certificate. +To safeguard against unauthorized additions, OpenPGP uses cryptographic signatures. These validate that any additions, such as subkeys or [identity components](identity_components), were made by the owner of the OpenPGP certificate using its primary key. While anyone can still store unrelated elements to a certificate dataset, OpenPGP implementations will reject them if they lack a valid cryptographic connection with the certificate. ```{note} Conversely, omissions of packets by third parties can easily occur when handling an OpenPGP certificate dataset. This could pose a challenge, for example, when an attacker deliberately omits revocation packets. Without access to an alternative, complete certificate source, recipients might not detect these omissions. From 5f694e8c23579d01b4f9dd3559b8b18bf41bcddd Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 25 Nov 2023 15:11:17 +0100 Subject: [PATCH 29/39] clarification: "append" implies "stored at the end of a file." this is not generally true for these two cases. I now realize that this is weird: we're claiming that certificates are "append only". However, the meaning of that term, in OpenPGP is ... not about the location of additions. Rather it just means "we only get to add packets, not remove them". Regardless of packet order. --- book/source/08-signing_components.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index 0c09153..0d404a5 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -79,7 +79,7 @@ Conversely, omissions of packets by third parties can easily occur when handling However, there are legitimate instances in which third parties add "unbound" packets (i.e., not signed by the certificate's owner) to a certificate: - [Third-party certifications](third_party_cert) are often stored within the packet data of the certificate to which they are related. This is a standard practice that provides convenience for users by allowing easy access to all relevant certifications. (See {ref}`cert-flooding` for discussion of a related pitfall.) -- OpenPGP software may locally append [unbound identity data](unbound_user_ids) to a certificate. +- OpenPGP software may locally add [unbound identity data](unbound_user_ids) to a certificate. (bind_subkey)= ### Binding subkeys to a certificate @@ -131,7 +131,7 @@ Take for instance, the User ID `Alice Adams `. To link this U There are four types of *certifying self-signature*. The most commonly used type for binding User IDs is the [positive certification](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-positive-cert) (type ID `0x13`). Alternatively, types `0x10`, `0x11` or `0x12` might be used. This binding signature must be issued by the primary key. -The certifying self-signature packet – calculated over the primary key, User ID, and metadata of the signature packet – is then appended to the certificate, directly following the User ID packet. +The certifying self-signature packet – calculated over the primary key, User ID, and metadata of the signature packet – is then added to the certificate, directly following the User ID packet. ```{figure} diag/user_id_certification.png From a3b5e263e31b243cee2a03076396fe809b33125f Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 25 Nov 2023 15:36:40 +0100 Subject: [PATCH 30/39] add missing space --- book/source/08-signing_components.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index 0d404a5..86318e8 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -205,7 +205,7 @@ Third-party signatures in OpenPGP primarily encode authentication statements for ### Certifying identity components -When a signer issues a certifying signature on an identity, it indicates a verified link between the identity and the certificate.That is, the signer vouches for the connection. +When a signer issues a certifying signature on an identity, it indicates a verified link between the identity and the certificate. That is, the signer vouches for the connection. For example, Alice can certify Bob's User ID `Bob Baker ` with his certificate `0xB0B`, by creating a certification signature that binds Bob's User ID and Bob's certificate. Bob then distributes Alice's certifying signature as part of his certificate. From 4b9c064a8bad876bc07382d98e4fe92007347d73 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 25 Nov 2023 15:43:24 +0100 Subject: [PATCH 31/39] it seems confusing to imply that bob will necessarily distribute a third-party certification, this is only true some of the time --- book/source/08-signing_components.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index 86318e8..25a4a6e 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -207,7 +207,7 @@ Third-party signatures in OpenPGP primarily encode authentication statements for When a signer issues a certifying signature on an identity, it indicates a verified link between the identity and the certificate. That is, the signer vouches for the connection. -For example, Alice can certify Bob's User ID `Bob Baker ` with his certificate `0xB0B`, by creating a certification signature that binds Bob's User ID and Bob's certificate. Bob then distributes Alice's certifying signature as part of his certificate. +For example, Alice can certify Bob's User ID `Bob Baker ` with his certificate `0xB0B`, by creating a certification signature that binds Bob's User ID and Bob's certificate. Bob can then distribute Alice's certifying signature as part of his certificate. Other users may or may not decide to rely on Alice's statement. From e49d1e69af7089d3c4a8769105a2286d2cf62edb Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 25 Nov 2023 15:57:00 +0100 Subject: [PATCH 32/39] clarify certification text And use Bob's real fingerprint. --- book/source/08-signing_components.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index 25a4a6e..b275a9d 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -207,7 +207,7 @@ Third-party signatures in OpenPGP primarily encode authentication statements for When a signer issues a certifying signature on an identity, it indicates a verified link between the identity and the certificate. That is, the signer vouches for the connection. -For example, Alice can certify Bob's User ID `Bob Baker ` with his certificate `0xB0B`, by creating a certification signature that binds Bob's User ID and Bob's certificate. Bob can then distribute Alice's certifying signature as part of his certificate. +For example, Alice can vouch that Bob's User ID `Bob Baker ` is legitimately linked with his certificate `BB28 9FB7 A68D BFA8 C384 CCCD E205 8E02 D9C6 CD2F 3C7C 56AE 7FB5 3D97 1170 BA83`, by creating a certification signature. Bob can then distribute Alice's certifying signature as part of his certificate. Other users may or may not decide to rely on Alice's statement. From 5887bcc8806c79e33d07b4c01461a362e275b603 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 25 Nov 2023 17:06:07 +0100 Subject: [PATCH 33/39] edit "trust signature" text - lean on the word "trust" as little as possible - some clarifications --- book/source/08-signing_components.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index b275a9d..9d62ff1 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -213,7 +213,7 @@ Other users may or may not decide to rely on Alice's statement. ### Trust signatures: delegating authentication -OpenPGP uses [*trust signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#trust-signature-subpacket) subpackets to delegate authentication decisions, transforming the recipient certificate into a "trusted introducer" (or a trust root) for the user. This includes specifying trust depth (or level) for transitive delegations and quantifying trust with numerical values, indicating the extent of reliance on the introducer's certifications. +OpenPGP uses [*trust signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#trust-signature-subpacket) subpackets to delegate authentication decisions, designating the recipient certificate as a "trusted introducer" (or a trust root) for the user. This includes specifying trust depth (or level) for transitive delegations and quantifying trust with numerical values, indicating the extent of reliance on the introducer's certifications. Trust signature subpackets are applicable in: @@ -222,11 +222,11 @@ Trust signature subpackets are applicable in: #### Trust depth/level -The trust depth (or level) in OpenPGP signifies the extent of transitive delegation within the authentication process. It determines how far the trust can be extended from the original trusted introducer to subsequent intermediaries. Essentially, a certificate with a designated trust depth acts as a "meta-introducer," facilitating authentication decisions across multiple levels in the network. +The "trust depth" (or level) in OpenPGP signifies the extent of transitive delegation within the authentication process. It determines how far a delegation can be extended from the original trusted introducer to subsequent intermediaries. Essentially, a certificate with a trust depth of more than one acts as a "meta-introducer," facilitating authentication decisions across multiple levels in the network. -For example, a trust depth of 1 means there is direct trust in the certifications made by the trusted introducer. In this case, the user's OpenPGP software will accept certifications made directly by the introducer for authenticating identities. +A trust depth of 1 means relying on certifications made directly by the trusted introducer. The user's OpenPGP software will accept certifications made directly by the introducer for authenticating identities. -However, when the trust depth is set higher, it implies a chain of trust extending beyond the initial introducer. The user's software will recognize and accept certifications made not only by the primary introducer but also by other intermediaries whom the primary introducer trusts. +However, when the trust depth is set higher, it implies a chain of delegation extending beyond the initial introducer. The user's software will recognize and accept certifications made not only by the primary introducer but also by other intermediaries whom the primary introducer designated as trusted introducers. This allows for a more extensive network of trusted certifications, enabling a broader and more interconnected Web of Trust. @@ -238,9 +238,9 @@ Heiko, I found the example confusing. So more text is here AND I recommend addin #### Trust amounts -The trust amount, with a numerical value ranging from 0 to 255, quantifies the degree of trust in a delegation. +The "trust amount," with a numerical value ranging from 0 to 255, quantifies the degree of reliance on a delegation. -A higher value indicates greater trust, such as 120 for complete trust, while lower values suggest partial trust. This quantification aids OpenPGP software in determining the authentication level based on combined trust from multiple trusted introducers. +A higher value indicates greater degree of reliance. This quantification aids OpenPGP software in determining an aggregate amount of reliance, based on combined certifications from multiple trusted introducers. ```{admonition} VISUAL :class: warning @@ -265,7 +265,7 @@ add diagrams? The Web of Trust in OpenPGP is a trust model that facilitates authentication decisions through a network of certifications and delegations.[^strong-set] It is characterized by a so-called [strong set](https://en.wikipedia.org/wiki/Web_of_trust#Strong_set), which refers to a group of certificates that are robustly interconnected via third-party certifications. -In this model, users independently delegate authentication decisions, choosing whom to trust among various certificate issuers. This delegation is based on the certificates and third-party signatures available to them, with their OpenPGP software applying the Web of Trust mechanism to discern the reliability of each certificate for an identity. +In this model, users independently delegate authentication decisions, choosing whose certification to rely on. This delegation is based on the certificates and third-party signatures available to them, with their OpenPGP software applying the Web of Trust mechanism to discern the reliability of each certificate for an identity. The OpenPGP RFC doesn't specify exactly how Web of Trust calculations are performed. It only defines the data formats on which these calculations can be performed. See external resources in {numref}`wot-resources`. From 127f36162c6cc4cda29cc72d6b4197220218cc04 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 25 Nov 2023 17:26:36 +0100 Subject: [PATCH 34/39] move example texts into diagram notes --- book/source/08-signing_components.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index 9d62ff1..a9ef9d1 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -233,7 +233,11 @@ This allows for a more extensive network of trusted certifications, enabling a b ```{admonition} VISUAL :class: warning -Heiko, I found the example confusing. So more text is here AND I recommend adding a visual to illustrate it, using your former example. +Illustrate with diagram(s). Notes for diagrams: + +When Alice delegates trust decisions to Trent, designating Trent as a trusted introducer with a *trust depth* of 1, then Alice's OpenPGP implementation will only accept direct certifications by Trent. For example, Trent may have certified that Bob's certificate with the fingerprint `0xB0B` is legitimately connected to Bob's User ID `Bob `. If Alice tries to communicate with Bob using his identity `Bob `, then Alice's OpenPGP software can automatically determine that the certificate `0xB0B` is appropriate to use. + +However, Alice's OpenPGP software wouldn't accept a series of delegations from Trent via Tristan to a certification of Carol's identity (let's imagine that Trent has designated Tristan a trusted introducer). For Alice's OpenPGP software to accept such a path, she needs to designate Trent as a trusted introducer with the `level` set to 2 or more. ``` #### Trust amounts @@ -245,7 +249,11 @@ A higher value indicates greater degree of reliance. This quantification aids Op ```{admonition} VISUAL :class: warning -add diagrams? @heiko -- yes, using the examples that I removed +Illustrate with diagram(s). Notes for diagrams: + +If Alice designates Trent as a trusted introducer at a trust amount of 120, then Alice's OpenPGP software will consider Bob's identity fully authenticated if Trent has certified it. + +However, if Alice only assigns a trust amount of 60 (which indicates "partial trust") to Trent, then her software would not consider Bob's identity fully authenticated. Now let's imagine that Alice additionally assigns a trust amount of 60 to Tristan (a second, independent introducer), and Tristan also certified Bob's identity. In this case, Alice's OpenPGP software will consider Bob's identity fully authenticated, based on the combination of both delegations, and the certifications the two trusted introducers issued. ``` #### Limiting delegation scope @@ -257,7 +265,9 @@ With this mechanism, for example, it is possible to delegate authentication deci ```{admonition} VISUAL :class: warning -add diagrams? +Illustrate with diagram(s). Notes for diagrams: + +For example, Alice could delegate trust decisions only for email addresses in the domain `bob.com` to Bob, if she considers Bob to be a reasonable source of identity certifications for that domain. ``` (wot)= From 887c5bf0e670421ee7d19e9a3145a8eb18b20f17 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 25 Nov 2023 17:32:17 +0100 Subject: [PATCH 35/39] remove dangling footnote syntax --- book/source/08-signing_components.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index a9ef9d1..cd1aa1b 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -273,7 +273,7 @@ For example, Alice could delegate trust decisions only for email addresses in th (wot)= ### Web of Trust: Decentralized trust decisions -The Web of Trust in OpenPGP is a trust model that facilitates authentication decisions through a network of certifications and delegations.[^strong-set] It is characterized by a so-called [strong set](https://en.wikipedia.org/wiki/Web_of_trust#Strong_set), which refers to a group of certificates that are robustly interconnected via third-party certifications. +The Web of Trust in OpenPGP is a trust model that facilitates authentication decisions through a network of certifications and delegations. It is characterized by a so-called [strong set](https://en.wikipedia.org/wiki/Web_of_trust#Strong_set), which refers to a group of certificates that are robustly interconnected via third-party certifications. In this model, users independently delegate authentication decisions, choosing whose certification to rely on. This delegation is based on the certificates and third-party signatures available to them, with their OpenPGP software applying the Web of Trust mechanism to discern the reliability of each certificate for an identity. From 993da3ccf4a7cadd05d5a3700790ade2aee3d26f Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 25 Nov 2023 17:39:47 +0100 Subject: [PATCH 36/39] don't use the generic word "critical" in a context where it has a technical meaning --- book/source/08-signing_components.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index cd1aa1b..ee336be 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -377,7 +377,7 @@ The structure of such a signature is straightforward: | Reason for Revocation | Hashed | True | False | Determines soft or hard revocation | -In `SubkeyRevocation` signatures, the [reason for revocation](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-reason-for-revocation) subpacket is critical. The values `1` (key superseded) and `3` (key retired and no longer used) indicate soft revocations, whereas values `0` (no reason) and `2` (key compromised) indicate hard revocations. +In `SubkeyRevocation` signatures, the [reason for revocation](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-reason-for-revocation) subpacket can only have values in the range of `0-3`. The values `1` (key superseded) and `3` (key retired and no longer used) indicate soft revocations, whereas values `0` (no reason) and `2` (key compromised) indicate hard revocations. Note that a value of `32` is not applicable in these signatures. From 77a0a69d781a342eaee3f72432c7cf9d4b858b2f Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 25 Nov 2023 17:43:22 +0100 Subject: [PATCH 37/39] clarify language --- book/source/08-signing_components.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index ee336be..2cb035a 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -385,7 +385,7 @@ Note that a value of `32` is not applicable in these signatures. Users may find themselves needing to revoke their entire OpenPGP certificate, rendering it unusable. This could be for various reasons, such as migrating to a new certificate or in response to a compromise of the certificate's secret key material. -While a soft-revoked certificate can be re-validated at a later time with a new certification, a hard revocation is typically permanent. +While a soft-revoked certificate can be re-validated at a later time with a new certification, a hard revocation is permanent. The recommended way to revoke a certificate is by issuing a *KeyRevocation* signature (type `0x20`). Its structure is similar to that of a *CertificationRevocation* signature. From 43b26012de63032f7c91dbe2f782b3be70479073 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 25 Nov 2023 17:46:07 +0100 Subject: [PATCH 38/39] minor tweak --- book/source/08-signing_components.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index 2cb035a..3e50354 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -406,7 +406,7 @@ In OpenPGP, certain subpackets are universally expected across all types of sign * **Issuer Fingerprint**: Essential for signature verification, this subpacket identifies the key (or subkey) used to create the signature. OpenPGP v6 signatures should include the Issuer Fingerprint subpacket, containing the 32-byte fingerprint of the key. ```{note} -The key used as the issuer in the signature might be a subkey of the primary key. +The key used as the issuer in the signature might be a subkey of the certificate. ``` This subpacket can be placed in either the hashed or unhashed area due to its self-authenticating nature. However, it is recommended to include it in the signature's hashed area for enhanced security. From 06c40b027561277192bb3210d2020cf71096b253 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 25 Nov 2023 17:48:10 +0100 Subject: [PATCH 39/39] i'm uncomfortable offering an explanation for this recommendation (i don't think security is a concern here. maybe interoperability?) --- book/source/08-signing_components.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index 3e50354..829dfde 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -409,7 +409,7 @@ In OpenPGP, certain subpackets are universally expected across all types of sign The key used as the issuer in the signature might be a subkey of the certificate. ``` -This subpacket can be placed in either the hashed or unhashed area due to its self-authenticating nature. However, it is recommended to include it in the signature's hashed area for enhanced security. +This subpacket can be placed in either the hashed or unhashed area due to its self-authenticating nature. However, we recommend including it in the signature's hashed area. ### Managing subpacket conflicts and duplication