From 92ec47ac99718bd7ecd2222295b8ec804dec2e6e Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Tue, 19 Dec 2023 20:54:27 +0100 Subject: [PATCH 01/11] change alt text --- book/source/signatures.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/signatures.md b/book/source/signatures.md index c1039b6..9fb654a 100644 --- a/book/source/signatures.md +++ b/book/source/signatures.md @@ -69,7 +69,7 @@ As outlined above, an {term}`OpenPGP signature` is a c ```{figure} plain_svg/OpenPGP_Signature_packet_2.svg :name: fig-signature-packet -:alt: Depicts a diagram with the title "OpenPGP signature packet". A box with green dotted frame and white background provides the title "Signature", while inside the box the text reads "Signature over; Input data, Signature metadata". The words "Signature metadata" serve as title for a yellow box at the lower half of the signature type box. The yellow box also bears the green cryptographic signature symbol. +:alt: Depicts a diagram with the title "OpenPGP signature packet." A plain white box with green-dotted borders is titled "Signature." Within that box is text that reads "Signature over: Input data, Signature metadata." The latter text ("Signature metadata") is the the title for a yellow box within which there are two lines of text that read "signature type" and "additional metadata," respectively. On the top right corner of the yellow box, the green cryptographic signature symbol ("sig") is visible. Structure and context of an {term}`OpenPGP signature packet` ``` From 857d3bd7579ae3e67afbf23f3f5a67124ce2a1d4 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Tue, 19 Dec 2023 22:03:31 +0100 Subject: [PATCH 02/11] edit section 20.2 of issue 253 --- book/source/adv/signatures.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/book/source/adv/signatures.md b/book/source/adv/signatures.md index daf2769..142f86d 100644 --- a/book/source/adv/signatures.md +++ b/book/source/adv/signatures.md @@ -16,30 +16,30 @@ SPDX-License-Identifier: CC-BY-SA-4.0 ## Choosing the hash algorithm for a signature -A central element of signature packets is the hash digest of the input data. Most OpenPGP software supports a set of different hash mechanisms, of which one is chosen for each signature packet (this is one aspect of OpenPGP's *cryptographic agility*), and used to calculate the hash digest. +A central element of signature packets is the hash digest of the input data. OpenPGP software typically supports a variety of hash mechanisms. This ability to choose from multiple options is part of what makes OpenPGP flexible in its cryptography, a feature known as *cryptographic agility*. The chosen mechanism is then used to calculate the hash digest. Different hash mechanisms offer different trade-offs: -- *Hash digest size*: Larger hash size tends to correspond with greater strength against cryptanalysis, and hash digests are relatively small: at the time of this writing, typical sizes are 32 to 64 bytes. However, for some use cases - especially where small messages are sent over a bandwidth-limited transport - larger hash sizes may unacceptably increase message size. -- *Computational cost*: Different hash algorithms may have different computational costs. Some OpenPGP users may prefer to limit this cost, for example on constrained computing environments. +- *Hash digest size*: The size of the hash digest is a crucial consideration. Generally, a larger hash size is more robust against cryptanalysis. Hash digests are relatively small – typically ranging in size from 32 to 64 bytes. However, in some cases - especially where messages are transmitted over bandwidth-limited networks - larger hash sizes may unacceptably increase message size. +- *Computational cost*: Different hash algorithms have different computational costs. Where computing environments are constrained, for example, some OpenPGP users may prefer to limit this cost. -The following sections discuss how the hash algorithm is chosen, based on preferences that are associated with the involved OpenPGP certificates. +Choosing the hash algorithm is not arbitrary but is guided by specific preferences associated with the OpenPGP certificates involved. The following sections discuss how these preferences influence which hash algorithm is chosen. -### Typically: Local determination +### General signature context, local algorithm choice -Often, signature creation isn't targeted at a specific receiver. Many signatures are issued for an indeterminate set of "anyone who receives the signature." +In many instances, the creation of a signature is not intended for a specific individual or entity. Instead, these signatures are designed to be valid for any recipient who might encounter them. -For example, self-signatures that form a certificate are aimed at everyone who interacts with that certificate. Similarly, when creating a data signature for a software package, this signature is aimed at "anyone who will check the signature," often over a long period of time, easily spanning years. +Take, for example, the self-signatures that are part of a certificate. These are intended for a wide audience — essentially, anyone who might interact with the certificate. Another example is the data signatures used for software packages. These signatures are not for a single recipient but for any user or system that verifies the signature, potentially spanning years. -In such cases, the issuer of that signature chooses the hash algorithm locally, without following preferences of a third party. +In such cases, where there isn't a specific recipient in mind, the issuer of the signature has the freedom to select the hash algorithm. This choice is made based on the issuer's own criteria or requirements, independent of any third party. -### With a specific recipient: "Negotiation" based on recipient's preferences +### Specific signature context, recipient-driven choice -In contrast, when a message is created for a specific recipient, the sender can - and should - choose the hash algorithm for the signature packet [based on the recipient's hash algorithm preference](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-hash-algorithm-preferences). +When a message is being prepared for a particular recipient, the selection of the hash algorithm for the signature packet should be guided by [the recipient's hash algorithm preference](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-hash-algorithm-preferences). -The recipient's hash algorithm preference is defined in metadata of their certificate, see {ref}`preferences-features` for more details. +The recipient's hash algorithm preference is defined in the metadata of their OpenPGP certificate. See {ref}`preferences-features` for more details. -In this workflow, the signed hash digest is created with a hash algorithm that follows the recipient's preferences, and its intersection with the sender's capabilities and preferences. +In this workflow, the signed hash digest is created with a hash algorithm representing the intersection of the recipient's preferences and the sender's capabilities and preferences. ## Signature versions From 300f98ec3e3fddb5bdc6a348105bd73f2f965e09 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Tue, 19 Dec 2023 22:16:05 +0100 Subject: [PATCH 03/11] improve the alt language of issue 251 --- book/source/signatures.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/signatures.md b/book/source/signatures.md index 9fb654a..e418431 100644 --- a/book/source/signatures.md +++ b/book/source/signatures.md @@ -69,7 +69,7 @@ As outlined above, an {term}`OpenPGP signature` is a c ```{figure} plain_svg/OpenPGP_Signature_packet_2.svg :name: fig-signature-packet -:alt: Depicts a diagram with the title "OpenPGP signature packet." A plain white box with green-dotted borders is titled "Signature." Within that box is text that reads "Signature over: Input data, Signature metadata." The latter text ("Signature metadata") is the the title for a yellow box within which there are two lines of text that read "signature type" and "additional metadata," respectively. On the top right corner of the yellow box, the green cryptographic signature symbol ("sig") is visible. +:alt: Depicts a diagram with the title "OpenPGP signature packet." A plain white rectangle with green-dotted borders is titled "Signature." Within that rectangle are three lines of text that reads "Signature over:", "Input data", and "Signature metadata." The latter text ("Signature metadata") is the the title for a yellow tag within which there are two lines of text that read "signature type" and "additional metadata" respectively. On the top right corner of the yellow tag, the green cryptographic signature symbol ("sig") is visible. Structure and context of an {term}`OpenPGP signature packet` ``` From 654b9739fdf9e97df2181f19b6c90162699819f5 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 9 Jan 2024 12:52:15 +0100 Subject: [PATCH 04/11] Fix section level --- book/source/adv/certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/adv/certificates.md b/book/source/adv/certificates.md index 0f44205..8ddd3d0 100644 --- a/book/source/adv/certificates.md +++ b/book/source/adv/certificates.md @@ -226,7 +226,7 @@ Disadvantages/risks of minimizing certificates: - Refreshing certificates from key servers may inflate the certificate again, since OpenPGP certificates tend to act as [append-only structures](append-only). - Some libraries, such as [anonaddy-sequoia](https://gitlab.com/willbrowning/anonaddy-sequoia/-/blob/master/src/sequoia.rs?ref_type=heads#L125) strip unusable encryption subkeys, but retain at least one subkey, even if all subkeys are expired. Although this may leave only an expired encryption subkey in the certificate, this presents a better UX for the end-user who potentially is still in possession of the private key for decryption. -## Guidelines +### Guidelines 1. Don't minimize certificates unless you have a good reason to. 2. When minimizing a certificate, minimize it in a way that suites your use-case. E.g., when minimizing a certificate for distribution alongside a signed software packet, make sure to include enough historical self-signatures as to not break the verification of the signed packet. From 59026d7e3c5ea5df978177945222c1d7750e527a Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Thu, 11 Jan 2024 16:51:13 +0100 Subject: [PATCH 05/11] Clarify target-audience --- book/source/about.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/book/source/about.md b/book/source/about.md index 07ea24c..9d46557 100644 --- a/book/source/about.md +++ b/book/source/about.md @@ -27,9 +27,11 @@ Three groups of people interact with OpenPGP: 2. Software developers who build applications that contain OpenPGP functionality 3. Implementers of OpenPGP libraries (or other software that directly handles the processing of internal OpenPGP data structures) -This document is not intended for end-users or implementers of OpenPGP libraries (or other software that directly handles internal OpenPGP data structures). +This document is not intended for end-users. -Instead, this document is focused on the second group, application developers, who use OpenPGP functionality in their software projects. It describes the properties of the OpenPGP system and its uses. It presupposes solid knowledge of software development concepts and of general cryptographic concepts. Thus, this text describes OpenPGP at the "library-level," teaching concepts that will help software developers get started as a user of any implementation (e.g., [OpenPGP.js](https://openpgpjs.org/), [Sequoia-PGP](https://sequoia-pgp.org/)). +Instead, this document is mainly aimed at the second group, application developers, who use OpenPGP functionality in their software projects. It describes the properties of the OpenPGP system and its uses. It presupposes solid knowledge of software development concepts and of general cryptographic concepts. Thus, this text describes OpenPGP at the "library-level," teaching concepts that will help software developers get started as a user of any implementation (e.g., [OpenPGP.js](https://openpgpjs.org/), [Sequoia-PGP](https://sequoia-pgp.org/)). + +The document may also serve as a useful supplement to the RFC for implementers of OpenPGP libraries (or other software that directly handles internal OpenPGP data structures). With the emergence of a new crop of modern, high-quality OpenPGP libraries, and the imminent release of the updated [OpenPGP version 6 specification](https://datatracker.ietf.org/doc/draft-ietf-openpgp-crypto-refresh/), we think that now is a great time to implement OpenPGP functionality in applications or to modernize existing OpenPGP subsystems. From cd2b2c6ab87e3e6e091af31483951cfa28d958c5 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Thu, 18 Jan 2024 22:38:09 +0100 Subject: [PATCH 06/11] Clarify "Key ID" --- book/source/glossary.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/book/source/glossary.md b/book/source/glossary.md index 6b6be3e..4479c35 100644 --- a/book/source/glossary.md +++ b/book/source/glossary.md @@ -292,8 +292,12 @@ Key Holder See {term}`Certificate Holder`. Key ID - The high-order (leftmost) 64 bits of an {term}`OpenPGP Fingerprint`. - Historically, this term refers to the low-order (rightmost) 64 bits of an {term}`OpenPGP Fingerprint`. + A Key ID is a shorthand identifier for OpenPGP certificates (or for individual subkeys). A Key ID is a shortened versions of a {term}`fingerprint`: + + - For OpenPGP v6 keys, the Key ID consists of the high-order (leftmost) 64 bits of their {term}`OpenPGP Fingerprint`. + - For OpenPGP v4 keys, the Key ID consists of the low-order (rightmost) 64 bits of their {term}`OpenPGP Fingerprint`. + + Note that since Key IDs are relatively short, they don't meaningfully guard against collisions. Applications must not assume that Key IDs are unique. Key Material May refer to {term}`Public Key Material` or {term}`Private Key Material`. From 38d9be0b41568c0531fb7c02dab6f91ce7c748cd Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Fri, 19 Jan 2024 17:47:00 +0100 Subject: [PATCH 07/11] change structure on data packet types --- book/source/signatures.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/book/source/signatures.md b/book/source/signatures.md index e418431..55371f5 100644 --- a/book/source/signatures.md +++ b/book/source/signatures.md @@ -74,10 +74,10 @@ As outlined above, an {term}`OpenPGP signature` is a c Structure and context of an {term}`OpenPGP signature packet` ``` -The input data packets differ between specific signature types. Also see {numref}`fig-signature-types`. For example: +The input data packets differ between specific signature types. Also see {numref}`fig-signature-types`. -- for a [*binary data signature*](data-signature-types), the input data packet is a *literal data packet*, while -- for a [*subkey binding signature*](bind-subkey), the input data packets consist of a primary and a subkey packet. +- [**Binary data signature**](data-signature-types): The input data packet is a {term}`literal data packet`. +- [**Subkey binding signature**](bind-subkey): The input data packets consist of a primary and a subkey packet. ### Creating an OpenPGP signature packet From e22e3cb4a7c656a4c6b770665aece129b75fe4f7 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Fri, 19 Jan 2024 17:48:36 +0100 Subject: [PATCH 08/11] restore for example --- book/source/signatures.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/book/source/signatures.md b/book/source/signatures.md index 55371f5..2c80b22 100644 --- a/book/source/signatures.md +++ b/book/source/signatures.md @@ -76,6 +76,8 @@ Structure and context of an {term}`OpenPGP signature packet` The input data packets differ between specific signature types. Also see {numref}`fig-signature-types`. +For example: + - [**Binary data signature**](data-signature-types): The input data packet is a {term}`literal data packet`. - [**Subkey binding signature**](bind-subkey): The input data packets consist of a primary and a subkey packet. From 4d70d1647fdb6ab73924f4a0fecfae7dc3e45973 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Fri, 19 Jan 2024 17:57:00 +0100 Subject: [PATCH 09/11] correct to end users --- book/source/about.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/source/about.md b/book/source/about.md index 9d46557..d585bf3 100644 --- a/book/source/about.md +++ b/book/source/about.md @@ -23,11 +23,11 @@ With OpenPGP, you can: Three groups of people interact with OpenPGP: -1. End-users, who use software that contains OpenPGP functionality (e.g., the Thunderbird email software) +1. End users, who use software that contains OpenPGP functionality (e.g., the Thunderbird email software) 2. Software developers who build applications that contain OpenPGP functionality 3. Implementers of OpenPGP libraries (or other software that directly handles the processing of internal OpenPGP data structures) -This document is not intended for end-users. +This document is not intended for end users. Instead, this document is mainly aimed at the second group, application developers, who use OpenPGP functionality in their software projects. It describes the properties of the OpenPGP system and its uses. It presupposes solid knowledge of software development concepts and of general cryptographic concepts. Thus, this text describes OpenPGP at the "library-level," teaching concepts that will help software developers get started as a user of any implementation (e.g., [OpenPGP.js](https://openpgpjs.org/), [Sequoia-PGP](https://sequoia-pgp.org/)). From d5144400718c0358ab7d97a10ed9929d27a6ef55 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Fri, 19 Jan 2024 17:55:08 +0100 Subject: [PATCH 10/11] Fix styling of "end user" (no dash) --- book/source/adv/certificates.md | 2 +- book/source/certificates.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/book/source/adv/certificates.md b/book/source/adv/certificates.md index 0f44205..0e2b750 100644 --- a/book/source/adv/certificates.md +++ b/book/source/adv/certificates.md @@ -224,7 +224,7 @@ Disadvantages/risks of minimizing certificates: - As the OpenPGP subsystem on a user's computer learns about more certificates, third-party certifications that were previously unusable may become usable. Dropping third-party certifications by unknown issuers as a part of minimization prevents this mechanism. - An OpenPGP implementation that minimizes a certificate might remove component keys that it cannot use itself (e.g. because it doesn't support the algorithm of that key), even if the *receiving* implementation supports them. - Refreshing certificates from key servers may inflate the certificate again, since OpenPGP certificates tend to act as [append-only structures](append-only). -- Some libraries, such as [anonaddy-sequoia](https://gitlab.com/willbrowning/anonaddy-sequoia/-/blob/master/src/sequoia.rs?ref_type=heads#L125) strip unusable encryption subkeys, but retain at least one subkey, even if all subkeys are expired. Although this may leave only an expired encryption subkey in the certificate, this presents a better UX for the end-user who potentially is still in possession of the private key for decryption. +- Some libraries, such as [anonaddy-sequoia](https://gitlab.com/willbrowning/anonaddy-sequoia/-/blob/master/src/sequoia.rs?ref_type=heads#L125) strip unusable encryption subkeys, but retain at least one subkey, even if all subkeys are expired. Although this may leave only an expired encryption subkey in the certificate, this presents a better UX for the end user who potentially is still in possession of the private key for decryption. ## Guidelines diff --git a/book/source/certificates.md b/book/source/certificates.md index 30e9744..51085dd 100644 --- a/book/source/certificates.md +++ b/book/source/certificates.md @@ -289,6 +289,6 @@ For example, Bob's OpenPGP software may issue a {term}`certification` that Bob h Take, for instance, a scenario where Bob's OpenPGP software issues a {term}`certification` confirming as legitimate the link between the {term}`User ID` `Alice Adams ` and the {term}`certificate` bearing the {term}`fingerprint` `AAA1 8CBB 2546 85C5 8358 3205 63FD 37B6 7F33 00F9 FB0E C457 378C D29F 1026 98B3`. -This process assumes that Bob knows the person known as `Alice Adams` and is confident that `alice@example.org` is indeed Alice's email address. Bob also verifies that the {term}`certificate` his OpenPGP software associates with Alice matches the one Alice uses. In essence, both users must have a {term}`certificate` for Alice with an identical {term}`fingerprint`. In OpenPGP version 6, manual {term}`fingerprint` comparison by end-users is discouraged, with a replacement {term}`verification` mechanism still under development. The {term}`verification` process must occur over a sufficiently secure channel, such as an end-to-end encrypted video call or a face-to-face meeting. +This process assumes that Bob knows the person known as `Alice Adams` and is confident that `alice@example.org` is indeed Alice's email address. Bob also verifies that the {term}`certificate` his OpenPGP software associates with Alice matches the one Alice uses. In essence, both users must have a {term}`certificate` for Alice with an identical {term}`fingerprint`. In OpenPGP version 6, manual {term}`fingerprint` comparison by end users is discouraged, with a replacement {term}`verification` mechanism still under development. The {term}`verification` process must occur over a sufficiently secure channel, such as an end-to-end encrypted video call or a face-to-face meeting. For more on third-party {term}`certifications`, see {ref}`third-party-certifications`. From 82d8f821df2242800094232e45d2889cd5e5aba5 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Fri, 19 Jan 2024 16:40:46 +0100 Subject: [PATCH 11/11] Minor adjustments for #256 - small message sizes can make the overhead of large hashes particularly dramatic - we often use "valid" to refer to the "validity of signatures", this might make the term's use potentially confusing here --- book/source/adv/signatures.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/book/source/adv/signatures.md b/book/source/adv/signatures.md index 142f86d..6e748c2 100644 --- a/book/source/adv/signatures.md +++ b/book/source/adv/signatures.md @@ -20,14 +20,14 @@ A central element of signature packets is the hash digest of the input data. Ope Different hash mechanisms offer different trade-offs: -- *Hash digest size*: The size of the hash digest is a crucial consideration. Generally, a larger hash size is more robust against cryptanalysis. Hash digests are relatively small – typically ranging in size from 32 to 64 bytes. However, in some cases - especially where messages are transmitted over bandwidth-limited networks - larger hash sizes may unacceptably increase message size. -- *Computational cost*: Different hash algorithms have different computational costs. Where computing environments are constrained, for example, some OpenPGP users may prefer to limit this cost. +- *Hash digest size*: The size of the hash digest is a crucial consideration. Generally, a larger hash size is more robust against cryptanalysis. Hash digests are relatively small – typically ranging in size from 32 to 64 bytes. However, in some cases - especially where small messages are transmitted over bandwidth-limited networks - larger hash sizes may unacceptably increase message size. +- *Computational cost*: Different hash algorithms have different computational costs. Where computing environments are constrained, some OpenPGP users may prefer to limit this cost. Choosing the hash algorithm is not arbitrary but is guided by specific preferences associated with the OpenPGP certificates involved. The following sections discuss how these preferences influence which hash algorithm is chosen. ### General signature context, local algorithm choice -In many instances, the creation of a signature is not intended for a specific individual or entity. Instead, these signatures are designed to be valid for any recipient who might encounter them. +In many instances, the creation of a signature is not intended for a specific individual or entity. Instead, these signatures are designed to be legible for any recipient who might encounter them. Take, for example, the self-signatures that are part of a certificate. These are intended for a wide audience — essentially, anyone who might interact with the certificate. Another example is the data signatures used for software packages. These signatures are not for a single recipient but for any user or system that verifies the signature, potentially spanning years.