From 6d633424556efdd9997e2429d3b84ae81179883d Mon Sep 17 00:00:00 2001 From: Paul Schaub Date: Thu, 14 Dec 2023 12:33:39 +0100 Subject: [PATCH 01/33] Fix glossary entry of Packet --- book/source/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/glossary.md b/book/source/glossary.md index 76d7fed..b9e75ca 100644 --- a/book/source/glossary.md +++ b/book/source/glossary.md @@ -369,7 +369,7 @@ Owner See {term}`Certificate Holder`. Packet - An element in an {term}`OpenPGP Certificate`, which represents {term}`components` or {term}`signatures`. + An element in an {term}`OpenPGP Certificate` or {term}`message`. Packet Header A section of variable length at the beginning of a {term}`Packet`, which encodes for example the {term}`Packet Type ID`. See the relevant [section in the RFC](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-packet-headers), which explains this section in more detail. From 01e18a835b1bf069ede360c874c7aed5cf82927d Mon Sep 17 00:00:00 2001 From: Paul Schaub Date: Thu, 14 Dec 2023 12:35:23 +0100 Subject: [PATCH 02/33] Differentiate inline-signed messages between one-pass-signed and prefix-signed messages --- book/source/glossary.md | 7 ++++++- book/source/signing_data.md | 9 ++++++++- 2 files changed, 14 insertions(+), 2 deletions(-) diff --git a/book/source/glossary.md b/book/source/glossary.md index b9e75ca..01fc23f 100644 --- a/book/source/glossary.md +++ b/book/source/glossary.md @@ -313,7 +313,10 @@ Notation Tag Part of a {term}`Notation` name. One-pass Signature Packet - One or more {term}`packets` before the actual data in a {term}`Data Signature` which contain information to allow a receiving {term}`implementation` to create {term}`hashes` required for signature verification. See [RFC 5.4](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#one-pass-sig) for more details. + One or more {term}`packets` before the actual data in a {term}`Data Signature` which contain information to allow a receiving {term}`implementation` to create {term}`hashes` required for signature verification. See [RFC 5.4](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#one-pass-sig) for more details. + +One-pass-signed Message + A {term}`OpenPGP Message` signed using one or more {term}`One-pass signatures`. OpenPGP Certificate An OpenPGP certificate contains public key material, identity claims and third party certifications (but no private key material) @@ -405,6 +408,8 @@ Preferred AEAD Ciphersuites Subpacket See [RFC 5.2.3.15](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-preferred-aead-ciphersuites) +Prefixed-Signed Message + An {term}`OpenPGP Message` with one or more prefixed {term}`signature packets`. Primary Component Key See {term}`OpenPGP Primary Key`. diff --git a/book/source/signing_data.md b/book/source/signing_data.md index ca174b3..7979400 100644 --- a/book/source/signing_data.md +++ b/book/source/signing_data.md @@ -54,7 +54,12 @@ This method is commonly used for signing or encrypting emails. Most email softwa #### Structure -An {term}`inline-signed` {term}`OpenPGP message` consists of three segments: +There are two different constructions available to generate inline-signed messages: + +* {term}`One-pass-signed messages` are signed using one ore more {term}`one-pass signatures` +* {term}`Prefixed-signed messages` have the actual signature(s) prefixed to the {term}`OpenPGP message`. + +A {term}`one-pass-signed` {term}`OpenPGP message` consists of three segments: 1. [**One-pass signature packets**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#one-pass-sig): These one or more {term}`packets` precede the signed data and enable {term}`signature` computation in one pass. @@ -62,6 +67,8 @@ An {term}`inline-signed` {term}`OpenPGP message` consists of t 3. **{term}`Data signature packets`**: These contain the {term}`cryptographic signature` corresponding to the original data. +Less commonly used are {term}`prefixed-signed messages`, where the {term}`signature packet(s)` are simply prepended to the message. + #### Creation To produce an {term}`inline signature`, the {term}`signer` processes the entirety of the data by reading from an input file and writing into an output {term}`OpenPGP message` file. As the data is processed, the {term}`signer` simultaneously calculates a {term}`cryptographic signature`. This procedure results in the appending of a {term}`data signature packet` to the output {term}`OpenPGP message` file, where it can be efficiently stored. From a174779c1dde225b620cae47c6d298717e7084fb Mon Sep 17 00:00:00 2001 From: Paul Schaub Date: Thu, 14 Dec 2023 12:38:55 +0100 Subject: [PATCH 03/33] Fix typo --- book/source/signing_data.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/signing_data.md b/book/source/signing_data.md index 7979400..6ae7953 100644 --- a/book/source/signing_data.md +++ b/book/source/signing_data.md @@ -56,7 +56,7 @@ This method is commonly used for signing or encrypting emails. Most email softwa There are two different constructions available to generate inline-signed messages: -* {term}`One-pass-signed messages` are signed using one ore more {term}`one-pass signatures` +* {term}`One-pass-signed messages` are signed using one or more {term}`one-pass signatures` * {term}`Prefixed-signed messages` have the actual signature(s) prefixed to the {term}`OpenPGP message`. A {term}`one-pass-signed` {term}`OpenPGP message` consists of three segments: From 819d5e686875ac4f9c4aa94c997b9f3f908e71ee Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Mon, 18 Dec 2023 19:07:19 +0100 Subject: [PATCH 04/33] Adjust glossary link I think this sentence is more about the higher level concept of "data signatures" than about signature packets. --- book/source/signing_data.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/signing_data.md b/book/source/signing_data.md index 6ae7953..d5eafe4 100644 --- a/book/source/signing_data.md +++ b/book/source/signing_data.md @@ -26,7 +26,7 @@ Note that {term}`data signatures` are distinct from [](/signing_ {term}`Data signatures` are generated by {term}`hashing` the message content along with the {term}`metadata` in the {term}`OpenPGP signature packet`, and calculating a {term}`cryptographic signature` over that {term}`hash`. The resulting {term}`cryptographic signature` is stored in the {term}`signature packet`. -{term}`Data signature packets` manifest in three distinct forms, which will be detailed in the subsequent section. +{term}`Data signatures` manifest in three distinct forms, which will be detailed in the subsequent section. (forms-of-data-signatures)= ## Forms of OpenPGP data signatures From 16c6d0c265d660c22e11487e8e066cd0515ebb45 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Mon, 18 Dec 2023 19:36:48 +0100 Subject: [PATCH 05/33] Complete unfinished sentence --- book/source/signing_data.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/signing_data.md b/book/source/signing_data.md index d5eafe4..76436b8 100644 --- a/book/source/signing_data.md +++ b/book/source/signing_data.md @@ -75,7 +75,7 @@ To produce an {term}`inline signature`, the {term}`signer` processes the entiret For efficient {term}`verification`, an application must understand how to handle the {term}`literal data` prior to its reading. This requirement is addressed by the {term}`one-pass signature packets` located at the beginning of {term}`inline-signed` messages. These {term}`packets` include essential information such as the {term}`fingerprint` of the {term}`signing key` and the {term}`hash` algorithm used for computing the {term}`signature`'s {term}`hash digest`. This setup enables the verifier to process the data correctly and efficiently. -Strictly speaking, knowing just the hash algorithm would be sufficient to begin the verification process. However, having efficient access to the signer's fingerprint or key ID upfront allows OpenPGP software to fetch the signer's certificates before processing the entirety of the - potentially large - signed data, and . +Strictly speaking, knowing just the hash algorithm would be sufficient to begin the verification process. However, having efficient access to the signer's fingerprint or key ID upfront allows OpenPGP software to fetch the signer's certificate(s) before processing the entirety of the - potentially large - signed data. This may, for example, involve downloading the certificate from a keyserver. In case fetching the signer's certificate(s) fails, or requires additional input from the user, it is better to signal the user about this before processing the data. #### Verification From 7ef91f4d057c047c4127eabdd03e14ac3a5b1381 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Mon, 18 Dec 2023 18:28:46 +0100 Subject: [PATCH 06/33] Structure: separate sections for One-pass-signed and Prefixed-signed messages --- book/source/signing_data.md | 33 +++++++++++++++++++++++++-------- 1 file changed, 25 insertions(+), 8 deletions(-) diff --git a/book/source/signing_data.md b/book/source/signing_data.md index 76436b8..b9a43fb 100644 --- a/book/source/signing_data.md +++ b/book/source/signing_data.md @@ -52,12 +52,16 @@ An {term}`inline signature` joins the signed data and its corresponding {term}`d This method is commonly used for signing or encrypting emails. Most email software capable of handling OpenPGP communications typically uses {term}`inline signatures`. -#### Structure +OpenPGP defines two different forms of inline-signed messages: -There are two different constructions available to generate inline-signed messages: +1. **{term}`One-pass-signed messages`** are signed using one or more {term}`one-pass signatures` +2. **{term}`Prefixed-signed messages`** have the actual signature(s) prefixed to the {term}`OpenPGP message`. -* {term}`One-pass-signed messages` are signed using one or more {term}`one-pass signatures` -* {term}`Prefixed-signed messages` have the actual signature(s) prefixed to the {term}`OpenPGP message`. +While the latter is conceptually slightly simpler, it has no strong benefits over {term}`one-pass-signed messages` and is rarely used. + +#### One-pass-signed message + +##### Structure A {term}`one-pass-signed` {term}`OpenPGP message` consists of three segments: @@ -67,9 +71,7 @@ A {term}`one-pass-signed` {term}`OpenPGP message` consi 3. **{term}`Data signature packets`**: These contain the {term}`cryptographic signature` corresponding to the original data. -Less commonly used are {term}`prefixed-signed messages`, where the {term}`signature packet(s)` are simply prepended to the message. - -#### Creation +##### Creation To produce an {term}`inline signature`, the {term}`signer` processes the entirety of the data by reading from an input file and writing into an output {term}`OpenPGP message` file. As the data is processed, the {term}`signer` simultaneously calculates a {term}`cryptographic signature`. This procedure results in the appending of a {term}`data signature packet` to the output {term}`OpenPGP message` file, where it can be efficiently stored. @@ -77,7 +79,7 @@ For efficient {term}`verification`, an application must understand how to handle Strictly speaking, knowing just the hash algorithm would be sufficient to begin the verification process. However, having efficient access to the signer's fingerprint or key ID upfront allows OpenPGP software to fetch the signer's certificate(s) before processing the entirety of the - potentially large - signed data. This may, for example, involve downloading the certificate from a keyserver. In case fetching the signer's certificate(s) fails, or requires additional input from the user, it is better to signal the user about this before processing the data. -#### Verification +##### Verification {term}`Inline-signed` messages enable efficient {term}`verification` in *one pass*, structured as follows: @@ -89,6 +91,21 @@ Strictly speaking, knowing just the hash algorithm would be sufficient to begin Important to note, the {term}`signer`'s {term}`public key`, critical for the final {term}`verification` step, is not embedded in the message. Verifiers must acquire this {term}`key` externally (e.g., from a {term}`key server`) to authenticate the {term}`signature` successfully. +#### Prefixed-signed message + +A {term}`prefixed-signed message` serves the same function as a {term}`one-pass-signed message`. However, this form is less commonly used. +In a {term}`prefixed-signed message`, the {term}`signature packet(s)` are simply prepended to the message. + +Especially for longer messages, it takes a bit more work to generate an inline signed OpenPGP message in this format. + +##### Structure + +1. **{term}`Data signature packets`**: These contain the {term}`cryptographic signature` corresponding to the original data. + +2. [**Literal data packet**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#lit): This contains the original data (e.g., the body of a message), without additional interpretation or conversion. + +Note that the signature packet(s) is/are stored ahead of the message itself, in this format. For verification, this is equally convenient as the one-pass signed message form. However, to create this form, the data must be processed twice: one time reading it to calculate the cryptographic signature, and one time to copy the data into the OpenPGP message after the signature packet(s). + (cleartext-signature)= ### Cleartext signatures From 3d89f0124672a0a5bb7a1a0ad05f4b3cafc6d08c Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Mon, 18 Dec 2023 18:54:11 +0100 Subject: [PATCH 07/33] Add note: a one-pass signature packet is not a type of signature --- book/source/signing_data.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/book/source/signing_data.md b/book/source/signing_data.md index b9a43fb..c505dc6 100644 --- a/book/source/signing_data.md +++ b/book/source/signing_data.md @@ -71,6 +71,12 @@ A {term}`one-pass-signed` {term}`OpenPGP message` consi 3. **{term}`Data signature packets`**: These contain the {term}`cryptographic signature` corresponding to the original data. +```{note} +Despite its name, a {term}`one-pass signature packet` is not a type of {term}`signature packet`. + +Instead, it's a type of auxiliary packet that can be used in conjunction with {term}`signature packets`. Its use allows storing the {term}`signature packets` after the message body. +``` + ##### Creation To produce an {term}`inline signature`, the {term}`signer` processes the entirety of the data by reading from an input file and writing into an output {term}`OpenPGP message` file. As the data is processed, the {term}`signer` simultaneously calculates a {term}`cryptographic signature`. This procedure results in the appending of a {term}`data signature packet` to the output {term}`OpenPGP message` file, where it can be efficiently stored. From e9a21f1d2da435ece88a9b36d96b1b2b11f6edd4 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Mon, 18 Dec 2023 19:39:23 +0100 Subject: [PATCH 08/33] Partially flatten section hierarchy for less depth --- book/source/signing_data.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/book/source/signing_data.md b/book/source/signing_data.md index c505dc6..eaf7177 100644 --- a/book/source/signing_data.md +++ b/book/source/signing_data.md @@ -39,14 +39,14 @@ Note that {term}`data signatures` are distinct from [](/signing_ [^sign-modes-gpg]: These three forms of {term}`signature` application align with GnuPG's `--detach-sign`, `--sign`, and `--clearsign` command options. -### Detached signatures +## Detached signatures A {term}`detached signature` is produced by calculating an {term}`OpenPGP signature` over the data intended for signing. The original data remains unchanged, and the {term}`OpenPGP signature` is stored as a standalone file. A {term}`detached signature` file can be distributed alongside or independent of the original data. The {term}`authenticity` and integrity of the original data file can be {term}`verified` by using the {term}`detached signature` file. This {term}`signature` format is especially useful for signing software releases and other files where it is imperative that the content remains unaltered during the signing process. (inline-signature)= -### Inline signatures +## Inline signatures An {term}`inline signature` joins the signed data and its corresponding {term}`data signature` into a single {term}`OpenPGP message`. @@ -59,9 +59,9 @@ OpenPGP defines two different forms of inline-signed messages: While the latter is conceptually slightly simpler, it has no strong benefits over {term}`one-pass-signed messages` and is rarely used. -#### One-pass-signed message +### One-pass-signed message -##### Structure +#### Structure A {term}`one-pass-signed` {term}`OpenPGP message` consists of three segments: @@ -77,7 +77,7 @@ Despite its name, a {term}`one-pass signature packet` is not a type of {term}`si Instead, it's a type of auxiliary packet that can be used in conjunction with {term}`signature packets`. Its use allows storing the {term}`signature packets` after the message body. ``` -##### Creation +#### Creation To produce an {term}`inline signature`, the {term}`signer` processes the entirety of the data by reading from an input file and writing into an output {term}`OpenPGP message` file. As the data is processed, the {term}`signer` simultaneously calculates a {term}`cryptographic signature`. This procedure results in the appending of a {term}`data signature packet` to the output {term}`OpenPGP message` file, where it can be efficiently stored. @@ -85,7 +85,7 @@ For efficient {term}`verification`, an application must understand how to handle Strictly speaking, knowing just the hash algorithm would be sufficient to begin the verification process. However, having efficient access to the signer's fingerprint or key ID upfront allows OpenPGP software to fetch the signer's certificate(s) before processing the entirety of the - potentially large - signed data. This may, for example, involve downloading the certificate from a keyserver. In case fetching the signer's certificate(s) fails, or requires additional input from the user, it is better to signal the user about this before processing the data. -##### Verification +#### Verification {term}`Inline-signed` messages enable efficient {term}`verification` in *one pass*, structured as follows: @@ -97,14 +97,14 @@ Strictly speaking, knowing just the hash algorithm would be sufficient to begin Important to note, the {term}`signer`'s {term}`public key`, critical for the final {term}`verification` step, is not embedded in the message. Verifiers must acquire this {term}`key` externally (e.g., from a {term}`key server`) to authenticate the {term}`signature` successfully. -#### Prefixed-signed message +### Prefixed-signed message A {term}`prefixed-signed message` serves the same function as a {term}`one-pass-signed message`. However, this form is less commonly used. In a {term}`prefixed-signed message`, the {term}`signature packet(s)` are simply prepended to the message. Especially for longer messages, it takes a bit more work to generate an inline signed OpenPGP message in this format. -##### Structure +#### Structure 1. **{term}`Data signature packets`**: These contain the {term}`cryptographic signature` corresponding to the original data. @@ -113,14 +113,14 @@ Especially for longer messages, it takes a bit more work to generate an inline s Note that the signature packet(s) is/are stored ahead of the message itself, in this format. For verification, this is equally convenient as the one-pass signed message form. However, to create this form, the data must be processed twice: one time reading it to calculate the cryptographic signature, and one time to copy the data into the OpenPGP message after the signature packet(s). (cleartext-signature)= -### Cleartext signatures +## Cleartext signatures The *{term}`Cleartext Signature Framework`* (CSF) in OpenPGP accomplishes two primary objectives: - maintaining the message in a human-readable cleartext format, accessible without OpenPGP-specific software - incorporating an {term}`OpenPGP signature` for {term}`authentication` by users with OpenPGP-compatible software -#### Example +### Example The following is a detailed example of a {numref}`cleartext` signature: @@ -141,7 +141,7 @@ r13/eqMN8kfCDw== This {term}`signature` consists of two parts: a message ("hello world") and an ASCII-armored {term}`OpenPGP signature`. The message is immediately comprehensible to a human reader, while the {term}`signature` block allows for the message's {term}`authenticity` {term}`verification` via OpenPGP software. -#### Use case +### Use case {term}`Cleartext signatures` combine the advantages of both {term}`detached` and {term}`inline signatures`: @@ -153,7 +153,7 @@ These features are particularly beneficial in scenarios where signed messages ar [^arch-certifications]: An illustrative example is the workflow adopted by Arch Linux to {term}`certify` {term}`User IDs` of new packagers. This process relies on [cleartext signed statements from existing packagers](https://gitlab.archlinux.org/archlinux/archlinux-keyring/-/blob/master/.gitlab/issue_templates/New%20Packager%20Key.md?ref_type=heads&plain=1#L33-46). These signed statements are stored as attachments in an issue tracking system for later inspection. The advantage of this approach lies in the convenience of having the message and signature in a single file, which simplifies manual handling. Based on the vouches in these {term}`cleartext signed` messages and an [email confirmation from the new packager](https://gitlab.archlinux.org/archlinux/archlinux-keyring/-/wikis/workflows/verify-a-packager-key), the main key operators can issue {term}`OpenPGP third-party certifications`. -#### Text transformations for cleartext signatures +### Text transformations for cleartext signatures The {term}`cleartext signature framework` includes specific text normalization procedures to ensure the integrity and clarity of the message: @@ -161,7 +161,7 @@ The {term}`cleartext signature framework` includes specific text normalization p - **Normalization of line endings**: Consistent with the approach for any other [text signature](data-signature-types), a {term}`cleartext signature` is calculated on the text with normalized line endings (``). This ensures that the {term}`signature` remains valid regardless of the text format of the receiving {term}`implementation`. -#### Pitfalls +### Pitfalls Despite their widespread adoption, {term}`cleartext signatures` have their limitations and are sometimes viewed as a "legacy method"[^csf-gnupg]. The {term}`RFC` details the [pitfalls of cleartext signatures](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-issues-with-the-cleartext-s), such as incompatibility with semantically meaningful whitespace, challenges with large messages, and security vulnerabilities related to misleading Hash header manipulations. Given these issues, safer alternatives like {term}`inline` and {term}`detached signature` forms are advised. From b2199d95c5bf2080bbf81a61152b9df17a8366e9 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 19 Dec 2023 11:01:15 +0100 Subject: [PATCH 09/33] Adjust styling of "One-pass signed" to use only one dash, and "Prefixed Signed" accordingly (This mirrors section 10.3 in c-r) --- book/source/glossary.md | 4 ++-- book/source/signing_data.md | 16 ++++++++-------- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/book/source/glossary.md b/book/source/glossary.md index 01fc23f..d07f4dc 100644 --- a/book/source/glossary.md +++ b/book/source/glossary.md @@ -315,7 +315,7 @@ Notation Tag One-pass Signature Packet One or more {term}`packets` before the actual data in a {term}`Data Signature` which contain information to allow a receiving {term}`implementation` to create {term}`hashes` required for signature verification. See [RFC 5.4](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#one-pass-sig) for more details. -One-pass-signed Message +One-pass signed Message A {term}`OpenPGP Message` signed using one or more {term}`One-pass signatures`. OpenPGP Certificate @@ -408,7 +408,7 @@ Preferred AEAD Ciphersuites Subpacket See [RFC 5.2.3.15](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-preferred-aead-ciphersuites) -Prefixed-Signed Message +Prefixed signed Message An {term}`OpenPGP Message` with one or more prefixed {term}`signature packets`. Primary Component Key diff --git a/book/source/signing_data.md b/book/source/signing_data.md index eaf7177..bdb21a7 100644 --- a/book/source/signing_data.md +++ b/book/source/signing_data.md @@ -54,16 +54,16 @@ This method is commonly used for signing or encrypting emails. Most email softwa OpenPGP defines two different forms of inline-signed messages: -1. **{term}`One-pass-signed messages`** are signed using one or more {term}`one-pass signatures` -2. **{term}`Prefixed-signed messages`** have the actual signature(s) prefixed to the {term}`OpenPGP message`. +1. **{term}`One-pass signed messages`** are signed using one or more {term}`one-pass signatures` +2. **{term}`Prefixed signed messages`** have the actual signature(s) prefixed to the {term}`OpenPGP message`. -While the latter is conceptually slightly simpler, it has no strong benefits over {term}`one-pass-signed messages` and is rarely used. +While {term}`prefixed signed messages` are conceptually slightly simpler, they have no strong benefits over {term}`one-pass signed messages` and are rarely used. -### One-pass-signed message +### One-pass signed message #### Structure -A {term}`one-pass-signed` {term}`OpenPGP message` consists of three segments: +A {term}`one-pass signed` {term}`OpenPGP message` consists of three segments: 1. [**One-pass signature packets**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#one-pass-sig): These one or more {term}`packets` precede the signed data and enable {term}`signature` computation in one pass. @@ -97,10 +97,10 @@ Strictly speaking, knowing just the hash algorithm would be sufficient to begin Important to note, the {term}`signer`'s {term}`public key`, critical for the final {term}`verification` step, is not embedded in the message. Verifiers must acquire this {term}`key` externally (e.g., from a {term}`key server`) to authenticate the {term}`signature` successfully. -### Prefixed-signed message +### Prefixed signed message -A {term}`prefixed-signed message` serves the same function as a {term}`one-pass-signed message`. However, this form is less commonly used. -In a {term}`prefixed-signed message`, the {term}`signature packet(s)` are simply prepended to the message. +A {term}`prefixed signed message` serves the same function as a {term}`one-pass signed message`. However, this form is less commonly used. +In a {term}`prefixed signed message`, the {term}`signature packet(s)` are simply prepended to the message. Especially for longer messages, it takes a bit more work to generate an inline signed OpenPGP message in this format. From 864ed59a645611089d90514fe1e3d4c92ade1457 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 19 Dec 2023 13:27:04 +0100 Subject: [PATCH 10/33] Edits for clarity --- book/source/signing_data.md | 30 +++++++++++++++++++----------- 1 file changed, 19 insertions(+), 11 deletions(-) diff --git a/book/source/signing_data.md b/book/source/signing_data.md index bdb21a7..b844be7 100644 --- a/book/source/signing_data.md +++ b/book/source/signing_data.md @@ -52,15 +52,17 @@ An {term}`inline signature` joins the signed data and its corresponding {term}`d This method is commonly used for signing or encrypting emails. Most email software capable of handling OpenPGP communications typically uses {term}`inline signatures`. -OpenPGP defines two different forms of inline-signed messages: +OpenPGP defines two variant forms of inline-signed messages: -1. **{term}`One-pass signed messages`** are signed using one or more {term}`one-pass signatures` -2. **{term}`Prefixed signed messages`** have the actual signature(s) prefixed to the {term}`OpenPGP message`. +1. **{term}`One-pass signed messages`** This is the commonly used format for inline-signed messages. A signer can produce this format in one pass. +2. **{term}`Prefixed signed messages`** This format predates[^inline-signature-formats] {term}`one-pass signed messages` and is conceptually slightly simpler. However, it has no strong benefits and is now rarely used. -While {term}`prefixed signed messages` are conceptually slightly simpler, they have no strong benefits over {term}`one-pass signed messages` and are rarely used. +[^inline-signature-formats]: One-pass signing was first specified in RFC 2440. The format was not supported in PGP 2.6.x. ### One-pass signed message +This is the commonly used format for inline signed messages. + #### Structure A {term}`one-pass signed` {term}`OpenPGP message` consists of three segments: @@ -90,7 +92,7 @@ Strictly speaking, knowing just the hash algorithm would be sufficient to begin {term}`Inline-signed` messages enable efficient {term}`verification` in *one pass*, structured as follows: 1. **Initiation with {term}`one-pass signature packets`**: These {term}`packets` begin the {term}`verification` process. They include the {term}`signer`'s {term}`key ID`/{term}`fingerprint`, essential for identifying the appropriate {term}`public key` for signature {term}`validation`. - + 2. **Processing the {term}`literal data packet`**: This step involves {term}`hashing` the literal data, preparing it for {term}`signature` {term}`verification`. 3. **{term}`Verifying` {term}`signature packets`**: Located at the end of the message, these {term}`packets` are checked against the previously calculated {term}`hash digest`. @@ -99,18 +101,24 @@ Important to note, the {term}`signer`'s {term}`public key`, ### Prefixed signed message -A {term}`prefixed signed message` serves the same function as a {term}`one-pass signed message`. However, this form is less commonly used. -In a {term}`prefixed signed message`, the {term}`signature packet(s)` are simply prepended to the message. - -Especially for longer messages, it takes a bit more work to generate an inline signed OpenPGP message in this format. +A {term}`prefixed signed message` consists of {term}`signature packet(s)` followed by the message. This inline signature format serves the same function as a {term}`one-pass signed message`. For the verifier, the two formats are equally convenient. However, on the signer's side, it takes more computational work to generate a {term}`prefixed signed message`. #### Structure -1. **{term}`Data signature packets`**: These contain the {term}`cryptographic signature` corresponding to the original data. +In this format, the signature packets are stored ahead of the message itself: + +1. **{term}`Data signature packets`**: These one or more packets contain the {term}`cryptographic signature` corresponding to the original data. 2. [**Literal data packet**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#lit): This contains the original data (e.g., the body of a message), without additional interpretation or conversion. -Note that the signature packet(s) is/are stored ahead of the message itself, in this format. For verification, this is equally convenient as the one-pass signed message form. However, to create this form, the data must be processed twice: one time reading it to calculate the cryptographic signature, and one time to copy the data into the OpenPGP message after the signature packet(s). +Compared to a {term}`one-pass signed message`, there are no {term}`one-pass signature packets` in this format, and the (otherwise equivalent) {term}`signature packet(s)` are stored ahead of the signed data. + +For verification, this is equally convenient as the one-pass signed message form. + +However, when a signer creates a {term}`prefixed signed message`, the signed data must be processed twice: + +- once reading it to calculate the cryptographic signature, and +- once more to store the data in the generated OpenPGP message, after the signature packet(s). (cleartext-signature)= ## Cleartext signatures From cf765f0b446c09ccfcaac4de9c668d55326e6f13 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 19 Dec 2023 13:37:05 +0100 Subject: [PATCH 11/33] Add link target headers --- book/source/signing_data.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/book/source/signing_data.md b/book/source/signing_data.md index b844be7..3fe97eb 100644 --- a/book/source/signing_data.md +++ b/book/source/signing_data.md @@ -59,6 +59,7 @@ OpenPGP defines two variant forms of inline-signed messages: [^inline-signature-formats]: One-pass signing was first specified in RFC 2440. The format was not supported in PGP 2.6.x. +(one-pass-signature)= ### One-pass signed message This is the commonly used format for inline signed messages. @@ -99,6 +100,7 @@ Strictly speaking, knowing just the hash algorithm would be sufficient to begin Important to note, the {term}`signer`'s {term}`public key`, critical for the final {term}`verification` step, is not embedded in the message. Verifiers must acquire this {term}`key` externally (e.g., from a {term}`key server`) to authenticate the {term}`signature` successfully. +(prefixed-signature)= ### Prefixed signed message A {term}`prefixed signed message` consists of {term}`signature packet(s)` followed by the message. This inline signature format serves the same function as a {term}`one-pass signed message`. For the verifier, the two formats are equally convenient. However, on the signer's side, it takes more computational work to generate a {term}`prefixed signed message`. From 99e2ea7cdd89d389c6c66eea3aa86a3db0ab1180 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 19 Dec 2023 15:45:07 +0100 Subject: [PATCH 12/33] Expand glossary entries for inline signatures forms. --- book/source/glossary.md | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/book/source/glossary.md b/book/source/glossary.md index d07f4dc..e804683 100644 --- a/book/source/glossary.md +++ b/book/source/glossary.md @@ -224,7 +224,14 @@ Initial Introducer An {term}`OpenPGP Certificate` explicitly {term}`delegated` to from a {term}`Trust Anchor`. Inline Signature - A {term}`Data Signature` which exists encapsulated alongside the data it was created for in an OpenPGP container. See [](forms-of-data-signatures). + An [inline signature](inline-signature) is a type of {term}`OpenPGP message` which stores a {term}`Data Signature` alongside the message it signs. Both the message and the signature are stored in a shared OpenPGP container. + + The standard defines two variant formats for inline signatures: + + - {term}`One-pass signed Message`: This format is now commonly used. + - {term}`Prefixed signed Message`: This is a historical format. It is still supported, but rarely used. + + For more context, see [](forms-of-data-signatures). Issuer An entity, that created an {term}`OpenPGP Signature Packet` using an {term}`Transferable Secret Key`. @@ -316,7 +323,9 @@ One-pass Signature Packet One or more {term}`packets` before the actual data in a {term}`Data Signature` which contain information to allow a receiving {term}`implementation` to create {term}`hashes` required for signature verification. See [RFC 5.4](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#one-pass-sig) for more details. One-pass signed Message - A {term}`OpenPGP Message` signed using one or more {term}`One-pass signatures`. + The commonly used form of an OpenPGP {term}`Inline Signature`. It combines an {term}`OpenPGP Message` with {term}`signature packets` and accompanying auxiliary {term}`One-pass signatures`. + + For details see [](one-pass-signature). OpenPGP Certificate An OpenPGP certificate contains public key material, identity claims and third party certifications (but no private key material) @@ -409,7 +418,9 @@ Preferred AEAD Ciphersuites Subpacket See [RFC 5.2.3.15](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-preferred-aead-ciphersuites) Prefixed signed Message - An {term}`OpenPGP Message` with one or more prefixed {term}`signature packets`. + A type of {term}`Inline Signature`. This form of {term}`Inline Signature` is historical and now rarely used. Superseded by {term}`One-pass signed Message`. + + For details see [](prefixed-signature). Primary Component Key See {term}`OpenPGP Primary Key`. From b338286947bf385e38bd227b6279210a386955c8 Mon Sep 17 00:00:00 2001 From: Paul Schaub Date: Tue, 19 Dec 2023 17:25:12 +0100 Subject: [PATCH 13/33] Clarify the reason for OPS sigs more and tweak the text structure --- book/source/signing_data.md | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/book/source/signing_data.md b/book/source/signing_data.md index 3fe97eb..24e2c75 100644 --- a/book/source/signing_data.md +++ b/book/source/signing_data.md @@ -41,7 +41,7 @@ Note that {term}`data signatures` are distinct from [](/signing_ ## Detached signatures -A {term}`detached signature` is produced by calculating an {term}`OpenPGP signature` over the data intended for signing. The original data remains unchanged, and the {term}`OpenPGP signature` is stored as a standalone file. A {term}`detached signature` file can be distributed alongside or independent of the original data. The {term}`authenticity` and integrity of the original data file can be {term}`verified` by using the {term}`detached signature` file. +A {term}`detached signature` is produced by calculating an {term}`OpenPGP signature` over the data intended for signing. The original data remains unchanged, and the {term}`OpenPGP signature` is stored separately, e.g. as a standalone file. A {term}`detached signature` file can be distributed alongside or independent of the original data. The {term}`authenticity` and integrity of the original data file can be {term}`verified` by using the {term}`detached signature` file. This {term}`signature` format is especially useful for signing software releases and other files where it is imperative that the content remains unaltered during the signing process. @@ -54,7 +54,7 @@ This method is commonly used for signing or encrypting emails. Most email softwa OpenPGP defines two variant forms of inline-signed messages: -1. **{term}`One-pass signed messages`** This is the commonly used format for inline-signed messages. A signer can produce this format in one pass. +1. **{term}`One-pass signed messages`** This is the commonly used format for inline-signed messages. A signer can produce and a verifier verify this format in one pass. 2. **{term}`Prefixed signed messages`** This format predates[^inline-signature-formats] {term}`one-pass signed messages` and is conceptually slightly simpler. However, it has no strong benefits and is now rarely used. [^inline-signature-formats]: One-pass signing was first specified in RFC 2440. The format was not supported in PGP 2.6.x. @@ -68,7 +68,7 @@ This is the commonly used format for inline signed messages. A {term}`one-pass signed` {term}`OpenPGP message` consists of three segments: -1. [**One-pass signature packets**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#one-pass-sig): These one or more {term}`packets` precede the signed data and enable {term}`signature` computation in one pass. +1. [**One-pass signature packets**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#one-pass-sig): These one or more {term}`packets` precede the signed data and enable {term}`signature` computation (both creation and verification) in a single pass. 2. [**Literal data packet**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#lit): This contains the original data (e.g., the body of a message), without additional interpretation or conversion. @@ -77,14 +77,20 @@ A {term}`one-pass signed` {term}`OpenPGP message` consi ```{note} Despite its name, a {term}`one-pass signature packet` is not a type of {term}`signature packet`. -Instead, it's a type of auxiliary packet that can be used in conjunction with {term}`signature packets`. Its use allows storing the {term}`signature packets` after the message body. +Instead, it's a type of auxiliary packet that can be used in conjunction with {term}`signature packets`. Its use allows storing the {term}`signature packets` after the message body. + +The position of the signature packet within the OpenPGP message is important for efficient data processing. The plaintext data might be large in size, and memory might be constrained. +The producer of a signed OpenPGP message wants to streamline the signature calculation process in such a way that allows to emit the data to be signed while calculating the signature. The signature itself is therefore appended to the data. +The verifier on the other hand needs to know the hash algorithm used to calculate the signature before starting the verification process. As a consequence, either the producer would need to pass the plaintext data twice, once to calculate the signature and a second time to emit the signed data (the result is a prefixed-signed message), or the verifier needs to process (and cache) the whole OpenPGP message to reach the signature packets at the end in order to determine the hash algorithm, to then re-process the whole message, verifying the signature. + +The one-pass signature solves this issue, by allowing both the creation and verification of a signed message in a single pass. ``` #### Creation -To produce an {term}`inline signature`, the {term}`signer` processes the entirety of the data by reading from an input file and writing into an output {term}`OpenPGP message` file. As the data is processed, the {term}`signer` simultaneously calculates a {term}`cryptographic signature`. This procedure results in the appending of a {term}`data signature packet` to the output {term}`OpenPGP message` file, where it can be efficiently stored. +To produce an {term}`inline signature`, the {term}`signer` decides on a hash algorithm and emits a {term}`one-pass signature packet` into the destination {term}`OpenPGP message`. This contains essential information such as the {term}`fingerprint` of the {term}`signing key` and the {term}`hash` algorithm used for computing the {term}`signature`'s {term}`hash digest`. The signer then processes the entirety of the plaintext data, emitting it as a {term}`literal data` into the message as well. Once the data is processed, the {term}`signer` calculates a {term}`cryptographic signature` using the calculated hash value. Lastly, the result is emitted as a {term}`data signature packet` to the output message, and the whole packet sequence can be efficiently stored or transmitted. -For efficient {term}`verification`, an application must understand how to handle the {term}`literal data` prior to its reading. This requirement is addressed by the {term}`one-pass signature packets` located at the beginning of {term}`inline-signed` messages. These {term}`packets` include essential information such as the {term}`fingerprint` of the {term}`signing key` and the {term}`hash` algorithm used for computing the {term}`signature`'s {term}`hash digest`. This setup enables the verifier to process the data correctly and efficiently. +For efficient {term}`verification`, an application must understand how to handle the {term}`literal data` prior to reading from it. This requirement is addressed by the {term}`one-pass signature packets` located at the beginning of {term}`inline-signed` messages. This setup enables the verifier to process the data correctly and efficiently in only a single pass. Strictly speaking, knowing just the hash algorithm would be sufficient to begin the verification process. However, having efficient access to the signer's fingerprint or key ID upfront allows OpenPGP software to fetch the signer's certificate(s) before processing the entirety of the - potentially large - signed data. This may, for example, involve downloading the certificate from a keyserver. In case fetching the signer's certificate(s) fails, or requires additional input from the user, it is better to signal the user about this before processing the data. @@ -103,7 +109,7 @@ Important to note, the {term}`signer`'s {term}`public key`, (prefixed-signature)= ### Prefixed signed message -A {term}`prefixed signed message` consists of {term}`signature packet(s)` followed by the message. This inline signature format serves the same function as a {term}`one-pass signed message`. For the verifier, the two formats are equally convenient. However, on the signer's side, it takes more computational work to generate a {term}`prefixed signed message`. +A {term}`prefixed signed message` consists of {term}`signature packet(s)` followed by the message. For the verifier, processing one-pass-signed and prefixed-signed messages are equally convenient. However, on the signer's side, it takes more resources to generate a {term}`prefixed signed message`. #### Structure From 23d97d691266e0447809584292379581cedfbc3d Mon Sep 17 00:00:00 2001 From: Paul Schaub Date: Tue, 19 Dec 2023 18:34:22 +0100 Subject: [PATCH 14/33] Incorporate diagram of OPS-signed message --- book/assets/drawio/ops-signed-message.drawio | 74 ++++++++++++++++++++ book/assets/drawio/ops-signed-message.svg | 3 + book/source/signing_data.md | 7 ++ 3 files changed, 84 insertions(+) create mode 100644 book/assets/drawio/ops-signed-message.drawio create mode 100644 book/assets/drawio/ops-signed-message.svg diff --git a/book/assets/drawio/ops-signed-message.drawio b/book/assets/drawio/ops-signed-message.drawio new file mode 100644 index 0000000..bedff83 --- /dev/null +++ b/book/assets/drawio/ops-signed-message.drawio @@ -0,0 +1,74 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/book/assets/drawio/ops-signed-message.svg b/book/assets/drawio/ops-signed-message.svg new file mode 100644 index 0000000..1079fa3 --- /dev/null +++ b/book/assets/drawio/ops-signed-message.svg @@ -0,0 +1,3 @@ + + +
One-Pass-Signature
Hash: SHA512
Fingerprint: 0xB0B0
One-Pass-Signature...
Literal Data
"Hello World!"
Literal Data...
Signature
Hash: SHA512
Issuer: B0B0
Signature...
One-Pass-Signature
Hash: SHA384
Fingerprint: 0xB0B1
One-Pass-Signature...
Signature
Hash: SHA512
Issuer: B0B1
Signature...
"Hello World!" is hashed
"Hello World!" is hashed
SHA512 Hash
SHA512 Hash
SHA384 Hash
SHA384 HashText is not SVG - cannot display \ No newline at end of file diff --git a/book/source/signing_data.md b/book/source/signing_data.md index 24e2c75..43cf0ed 100644 --- a/book/source/signing_data.md +++ b/book/source/signing_data.md @@ -74,6 +74,13 @@ A {term}`one-pass signed` {term}`OpenPGP message` consi 3. **{term}`Data signature packets`**: These contain the {term}`cryptographic signature` corresponding to the original data. +```{figure} plain_svg/ops-signed-message.svg +:name: fig-ops-signed-message +:alt: Depicts the structure of a one-pass-signed message. + +The structure of a one-pass signed message. +``` + ```{note} Despite its name, a {term}`one-pass signature packet` is not a type of {term}`signature packet`. From 70b6bd2f439dc1bde82bcaf495df707676f562b3 Mon Sep 17 00:00:00 2001 From: Paul Schaub Date: Tue, 19 Dec 2023 18:53:53 +0100 Subject: [PATCH 15/33] Fix diagrams --- book/assets/drawio/ops-signed-message.drawio | 38 ++++++++++---------- book/assets/drawio/ops-signed-message.svg | 2 +- 2 files changed, 20 insertions(+), 20 deletions(-) diff --git a/book/assets/drawio/ops-signed-message.drawio b/book/assets/drawio/ops-signed-message.drawio index bedff83..deaec9a 100644 --- a/book/assets/drawio/ops-signed-message.drawio +++ b/book/assets/drawio/ops-signed-message.drawio @@ -1,30 +1,30 @@ - + - + - + - + - + - + - + - + - + @@ -32,40 +32,40 @@ - + - + - + - + - + - + - + - + - + - + diff --git a/book/assets/drawio/ops-signed-message.svg b/book/assets/drawio/ops-signed-message.svg index 1079fa3..da6b370 100644 --- a/book/assets/drawio/ops-signed-message.svg +++ b/book/assets/drawio/ops-signed-message.svg @@ -1,3 +1,3 @@ -
One-Pass-Signature
Hash: SHA512
Fingerprint: 0xB0B0
One-Pass-Signature...
Literal Data
"Hello World!"
Literal Data...
Signature
Hash: SHA512
Issuer: B0B0
Signature...
One-Pass-Signature
Hash: SHA384
Fingerprint: 0xB0B1
One-Pass-Signature...
Signature
Hash: SHA512
Issuer: B0B1
Signature...
"Hello World!" is hashed
"Hello World!" is hashed
SHA512 Hash
SHA512 Hash
SHA384 Hash
SHA384 HashText is not SVG - cannot display \ No newline at end of file +
One-Pass-Signature
Hash: SHA512
Fingerprint: 0xB0B0
One-Pass-Signature...
Literal Data
"Hello World!"
Literal Data...
Signature
Hash: SHA512
Issuer: B0B0
Signature...
One-Pass-Signature
Hash: SHA384
Fingerprint: 0xB0B1
One-Pass-Signature...
Signature
Hash: SHA384
Issuer: B0B1
Signature...
"Hello World!" is hashed
"Hello World!" is hashed
SHA512 Hash
SHA512 Hash
SHA384 Hash
SHA384 HashText is not SVG - cannot display \ No newline at end of file From edc2c8322ddbb4b8000145e12f3f260c52c715b2 Mon Sep 17 00:00:00 2001 From: Paul Schaub Date: Tue, 19 Dec 2023 18:54:05 +0100 Subject: [PATCH 16/33] Add diagram for prefixed-signed message --- .../drawio/prefixed-signed-message.drawio | 63 +++++++++++++++++++ .../assets/drawio/prefixed-signed-message.svg | 3 + book/source/signing_data.md | 9 ++- 3 files changed, 74 insertions(+), 1 deletion(-) create mode 100644 book/assets/drawio/prefixed-signed-message.drawio create mode 100644 book/assets/drawio/prefixed-signed-message.svg diff --git a/book/assets/drawio/prefixed-signed-message.drawio b/book/assets/drawio/prefixed-signed-message.drawio new file mode 100644 index 0000000..aea991e --- /dev/null +++ b/book/assets/drawio/prefixed-signed-message.drawio @@ -0,0 +1,63 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/book/assets/drawio/prefixed-signed-message.svg b/book/assets/drawio/prefixed-signed-message.svg new file mode 100644 index 0000000..1ee49bf --- /dev/null +++ b/book/assets/drawio/prefixed-signed-message.svg @@ -0,0 +1,3 @@ + + +
Literal Data
"Hello World!"
Literal Data...
Signature
Hash: SHA384
Issuer: B0B0
Signature...
Signature
Hash: SHA512
Issuer: B0B1
Signature...
"Hello World!" is hashed
"Hello World!" is hashed
SHA512 Hash
SHA512 Hash
SHA384 Hash
SHA384 HashText is not SVG - cannot display \ No newline at end of file diff --git a/book/source/signing_data.md b/book/source/signing_data.md index 43cf0ed..4921348 100644 --- a/book/source/signing_data.md +++ b/book/source/signing_data.md @@ -76,7 +76,7 @@ A {term}`one-pass signed` {term}`OpenPGP message` consi ```{figure} plain_svg/ops-signed-message.svg :name: fig-ops-signed-message -:alt: Depicts the structure of a one-pass-signed message. +:alt: Depicts the structure of a one-pass-signed message. Two one-pass-signatures lead the literal data packet, followed by two signature packets. Arrows show, how the hash-algorithm field of the one-pass-signatures is inspected in order to initiate the hashing procedure. The structure of a one-pass signed message. ``` @@ -126,6 +126,13 @@ In this format, the signature packets are stored ahead of the message itself: 2. [**Literal data packet**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#lit): This contains the original data (e.g., the body of a message), without additional interpretation or conversion. +```{figure} plain_svg/prefixed-signed-message.svg +:name: fig-prefixed-signed-message +:alt: Depicts the structure of a prefixed-signed message. As an example, two signature packets lead a literal data packet. Arrows show, how the signatures hash algorithm field is inspected to start the hashing procedure. + +Structure of a prefixed-signed message. +``` + Compared to a {term}`one-pass signed message`, there are no {term}`one-pass signature packets` in this format, and the (otherwise equivalent) {term}`signature packet(s)` are stored ahead of the signed data. For verification, this is equally convenient as the one-pass signed message form. From 0ba4461f3b25dfb5751bbc54af079919fc01bd53 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 20 Dec 2023 11:58:20 +0100 Subject: [PATCH 17/33] Normalize dash styling (Mirroring styling in c-r) --- book/source/signing_data.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/book/source/signing_data.md b/book/source/signing_data.md index 4921348..16e93fc 100644 --- a/book/source/signing_data.md +++ b/book/source/signing_data.md @@ -54,7 +54,7 @@ This method is commonly used for signing or encrypting emails. Most email softwa OpenPGP defines two variant forms of inline-signed messages: -1. **{term}`One-pass signed messages`** This is the commonly used format for inline-signed messages. A signer can produce and a verifier verify this format in one pass. +1. **{term}`One-pass signed messages`** This is the commonly used format for inline-signed messages. A signer can produce and a verifier can verify this format in one pass. 2. **{term}`Prefixed signed messages`** This format predates[^inline-signature-formats] {term}`one-pass signed messages` and is conceptually slightly simpler. However, it has no strong benefits and is now rarely used. [^inline-signature-formats]: One-pass signing was first specified in RFC 2440. The format was not supported in PGP 2.6.x. @@ -76,7 +76,7 @@ A {term}`one-pass signed` {term}`OpenPGP message` consi ```{figure} plain_svg/ops-signed-message.svg :name: fig-ops-signed-message -:alt: Depicts the structure of a one-pass-signed message. Two one-pass-signatures lead the literal data packet, followed by two signature packets. Arrows show, how the hash-algorithm field of the one-pass-signatures is inspected in order to initiate the hashing procedure. +:alt: Depicts the structure of a one-pass signed message. Two one-pass signatures lead the literal data packet, followed by two signature packets. Arrows show, how the hash-algorithm field of the one-pass signatures is inspected in order to initiate the hashing procedure. The structure of a one-pass signed message. ``` @@ -88,7 +88,7 @@ Instead, it's a type of auxiliary packet that can be used in conjunction with {t The position of the signature packet within the OpenPGP message is important for efficient data processing. The plaintext data might be large in size, and memory might be constrained. The producer of a signed OpenPGP message wants to streamline the signature calculation process in such a way that allows to emit the data to be signed while calculating the signature. The signature itself is therefore appended to the data. -The verifier on the other hand needs to know the hash algorithm used to calculate the signature before starting the verification process. As a consequence, either the producer would need to pass the plaintext data twice, once to calculate the signature and a second time to emit the signed data (the result is a prefixed-signed message), or the verifier needs to process (and cache) the whole OpenPGP message to reach the signature packets at the end in order to determine the hash algorithm, to then re-process the whole message, verifying the signature. +The verifier on the other hand needs to know the hash algorithm used to calculate the signature before starting the verification process. As a consequence, either the producer would need to pass the plaintext data twice, once to calculate the signature and a second time to emit the signed data (the result is a prefixed signed message), or the verifier needs to process (and cache) the whole OpenPGP message to reach the signature packets at the end in order to determine the hash algorithm, to then re-process the whole message, verifying the signature. The one-pass signature solves this issue, by allowing both the creation and verification of a signed message in a single pass. ``` @@ -116,7 +116,7 @@ Important to note, the {term}`signer`'s {term}`public key`, (prefixed-signature)= ### Prefixed signed message -A {term}`prefixed signed message` consists of {term}`signature packet(s)` followed by the message. For the verifier, processing one-pass-signed and prefixed-signed messages are equally convenient. However, on the signer's side, it takes more resources to generate a {term}`prefixed signed message`. +A {term}`prefixed signed message` consists of {term}`signature packet(s)` followed by the message. For the verifier, processing one-pass signed and prefixed signed messages are equally convenient. However, on the signer's side, it takes more resources to generate a {term}`prefixed signed message`. #### Structure @@ -128,9 +128,9 @@ In this format, the signature packets are stored ahead of the message itself: ```{figure} plain_svg/prefixed-signed-message.svg :name: fig-prefixed-signed-message -:alt: Depicts the structure of a prefixed-signed message. As an example, two signature packets lead a literal data packet. Arrows show, how the signatures hash algorithm field is inspected to start the hashing procedure. +:alt: Depicts the structure of a prefixed signed message. As an example, two signature packets lead a literal data packet. Arrows show, how the signatures hash algorithm field is inspected to start the hashing procedure. -Structure of a prefixed-signed message. +Structure of a prefixed signed message. ``` Compared to a {term}`one-pass signed message`, there are no {term}`one-pass signature packets` in this format, and the (otherwise equivalent) {term}`signature packet(s)` are stored ahead of the signed data. From ad68dc83dad204f318b0feacec2ca25d9b5b0d24 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 20 Dec 2023 14:28:08 +0100 Subject: [PATCH 18/33] Additional elaboration on one-pass signature packet --- book/source/signing_data.md | 26 ++++++++++++++++++++------ 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/book/source/signing_data.md b/book/source/signing_data.md index 16e93fc..15b137b 100644 --- a/book/source/signing_data.md +++ b/book/source/signing_data.md @@ -85,14 +85,28 @@ The structure of a one-pass signed message. Despite its name, a {term}`one-pass signature packet` is not a type of {term}`signature packet`. Instead, it's a type of auxiliary packet that can be used in conjunction with {term}`signature packets`. Its use allows storing the {term}`signature packets` after the message body. - -The position of the signature packet within the OpenPGP message is important for efficient data processing. The plaintext data might be large in size, and memory might be constrained. -The producer of a signed OpenPGP message wants to streamline the signature calculation process in such a way that allows to emit the data to be signed while calculating the signature. The signature itself is therefore appended to the data. -The verifier on the other hand needs to know the hash algorithm used to calculate the signature before starting the verification process. As a consequence, either the producer would need to pass the plaintext data twice, once to calculate the signature and a second time to emit the signed data (the result is a prefixed signed message), or the verifier needs to process (and cache) the whole OpenPGP message to reach the signature packets at the end in order to determine the hash algorithm, to then re-process the whole message, verifying the signature. - -The one-pass signature solves this issue, by allowing both the creation and verification of a signed message in a single pass. ``` +#### The function of the one-pass signature packet + +To understand the purpose of this packet, consider that without it, the position of signature packets within an inline signed OpenPGP message constitutes a trade-off for efficient data processing. In particular when plaintext data is large and exceeds available memory in size. + +The producer of a signed OpenPGP message wants to streamline the signature calculation process in such a way that allows to emit a copy of the signed data while calculating the cryptographic signature. On the signer's side, the signature packet is therefore easy to store after the signed data. + +The verifier, on the other hand, needs some information from the signature packet in order to perform the signature verification process. In particular, the verifier needs to know which hash algorithm was used to calculate the signature, in order to perform the same hashing operation on the message data. + +As a consequence, without a {term}`one-pass signature packet`, either: +- the producer would need to process the signed data twice: + - once to calculate the signature, and + - a second time to emit the signed data (the result is a prefixed signed message), or +- the verifier would need to process the OpenPGP message twice: + - once to read the signature packets at the end in order to determine the hash algorithm, and + - a second time to process the body of the message, and calculate the hash verifying the signature. + +The one-pass signature packet solves this issue, by allowing both the creation and verification of a signed message in a single pass. It effectively contains a copy of the data in a signature packet, but without the cryptographic signature data. + +The signer can easily emit this metadata before processing the full message, and for the verifier, this metadata enables processing of the message body. Both signer and verifier can efficiently generate or check a one-pass signed message. + #### Creation To produce an {term}`inline signature`, the {term}`signer` decides on a hash algorithm and emits a {term}`one-pass signature packet` into the destination {term}`OpenPGP message`. This contains essential information such as the {term}`fingerprint` of the {term}`signing key` and the {term}`hash` algorithm used for computing the {term}`signature`'s {term}`hash digest`. The signer then processes the entirety of the plaintext data, emitting it as a {term}`literal data` into the message as well. Once the data is processed, the {term}`signer` calculates a {term}`cryptographic signature` using the calculated hash value. Lastly, the result is emitted as a {term}`data signature packet` to the output message, and the whole packet sequence can be efficiently stored or transmitted. From 7d756c77ee527dc83c71a6b828059adb98e42eef Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 20 Dec 2023 15:20:21 +0100 Subject: [PATCH 19/33] Shift away from "plaintext" term for the signed data Talking about "plaintext" seems potentially confusing, especially when signing an encrypted message. --- book/source/signing_data.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/book/source/signing_data.md b/book/source/signing_data.md index 15b137b..a7ac8e1 100644 --- a/book/source/signing_data.md +++ b/book/source/signing_data.md @@ -35,7 +35,7 @@ Note that {term}`data signatures` are distinct from [](/signing_ - **{term}`Detached`**: The OpenPGP signature exists as a separate entity, independent of the signed data. - **{term}`Inline`**: Both the original data and its corresponding {term}`OpenPGP signature` are encapsulated within an {term}`OpenPGP message`. -- **{term}`Cleartext signature`**: A plaintext message and its {term}`OpenPGP signature` coexist in a combined text format, preserving the readability of the original message. +- **{term}`Cleartext signature`**: A plain text message and its {term}`OpenPGP signature` coexist in a combined text format, preserving the readability of the original message. [^sign-modes-gpg]: These three forms of {term}`signature` application align with GnuPG's `--detach-sign`, `--sign`, and `--clearsign` command options. @@ -89,7 +89,7 @@ Instead, it's a type of auxiliary packet that can be used in conjunction with {t #### The function of the one-pass signature packet -To understand the purpose of this packet, consider that without it, the position of signature packets within an inline signed OpenPGP message constitutes a trade-off for efficient data processing. In particular when plaintext data is large and exceeds available memory in size. +To understand the purpose of this packet, consider that without it, the position of signature packets within an inline signed OpenPGP message constitutes a trade-off for efficient data processing. In particular when signed data is large and exceeds available memory in size. The producer of a signed OpenPGP message wants to streamline the signature calculation process in such a way that allows to emit a copy of the signed data while calculating the cryptographic signature. On the signer's side, the signature packet is therefore easy to store after the signed data. @@ -109,7 +109,7 @@ The signer can easily emit this metadata before processing the full message, and #### Creation -To produce an {term}`inline signature`, the {term}`signer` decides on a hash algorithm and emits a {term}`one-pass signature packet` into the destination {term}`OpenPGP message`. This contains essential information such as the {term}`fingerprint` of the {term}`signing key` and the {term}`hash` algorithm used for computing the {term}`signature`'s {term}`hash digest`. The signer then processes the entirety of the plaintext data, emitting it as a {term}`literal data` into the message as well. Once the data is processed, the {term}`signer` calculates a {term}`cryptographic signature` using the calculated hash value. Lastly, the result is emitted as a {term}`data signature packet` to the output message, and the whole packet sequence can be efficiently stored or transmitted. +To produce a {term}`one-pass inline signature`, the {term}`signer` decides on a hash algorithm and emits a {term}`one-pass signature packet` into the destination {term}`OpenPGP message`. This contains essential information such as the {term}`fingerprint` of the {term}`signing key` and the {term}`hash` algorithm used for computing the {term}`signature`'s {term}`hash digest`. The signer then processes the entirety of the signed data, emitting it as a {term}`literal data` into the message as well. Once the data is processed, the {term}`signer` calculates a {term}`cryptographic signature` using the calculated hash value. Lastly, the result is emitted as a {term}`data signature packet` to the output message, and the whole packet sequence can be efficiently stored or transmitted. For efficient {term}`verification`, an application must understand how to handle the {term}`literal data` prior to reading from it. This requirement is addressed by the {term}`one-pass signature packets` located at the beginning of {term}`inline-signed` messages. This setup enables the verifier to process the data correctly and efficiently in only a single pass. From 7bd0e5599ec1fd57de1e51433ed67c58bf322250 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 20 Dec 2023 18:09:36 +0100 Subject: [PATCH 20/33] Add glossary entries about OpenPGP messages, to generalize the data signatures chapter --- book/source/glossary.md | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/book/source/glossary.md b/book/source/glossary.md index e804683..28eec83 100644 --- a/book/source/glossary.md +++ b/book/source/glossary.md @@ -112,6 +112,9 @@ Component Component Key See {term}`OpenPGP Component Key`. +Compressed Data Packet + A {term}`packet` that contains compressed data. It represents a "compressed message". The uncompressed data in turn consists of an {term}`OpenPGP message`, made up of a series of {term}`packets`. + Compression See {term}`Data Compression`. @@ -293,7 +296,7 @@ Life-cycle Management See [](self-signatures). Literal Data Packet - A {term}`packet` in a {term}`Data Signature` which contains data, that has been signed using a {term}`cryptographic signature`. See [RFC 5.9](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#lit) for more details. + A {term}`packet` which contains a payload of data. It represents a "literal message". A literal data packet can for example store data that has been signed using a {term}`cryptographic signature`. See [RFC 5.9](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#lit) for more details. MAC See {term}`Message Authentication Code`. @@ -333,6 +336,9 @@ OpenPGP Certificate OpenPGP Component Key An {term}`OpenPGP Primary Key` or {term}`OpenPGP Subkey`. For an in-depth discussion see [](component-keys). +OpenPGP data + Any data in OpenPGP format, represented as a series of OpenPGP packets. The data could for example represent an {term}`OpenPGP Certificate`, or an {term}`OpenPGP Signature Packet` combined with plaintext or encrypted data. + OpenPGP Fingerprint An OpenPGP Fingerprint is a shorthand representation of an {term}`OpenPGP Component Key`. Fingerprints effectively act as unique identifiers. See [](fingerprint). @@ -345,7 +351,14 @@ OpenPGP Key Used either for an {term}`OpenPGP Certificate` (containing public key material and metadata), or for an {term}`OpenPGP Private Key`. See [](/certificates) for an in-depth discussion. OpenPGP Message - A data structure, which contains OpenPGP components such as {term}`OpenPGP Certificate` or {term}`OpenPGP Signature Packet` and plaintext or encrypted data. + A series of OpenPGP packets that represents one of the following formats: + + - an encrypted message + - a signed message + - a {term}`compressed message` + - a {term}`literal message` + + Also see [RFC 10.3](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-openpgp-messages). OpenPGP Public Key See {term}`OpenPGP Certificate`. From c4d1d05be92b01c8e15127278b62c15ccdfa36d4 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 20 Dec 2023 19:55:05 +0100 Subject: [PATCH 21/33] Generalize the text: the data that gets signed in an OpenPGP message, not necessarily a literal data packet --- book/source/signing_data.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/book/source/signing_data.md b/book/source/signing_data.md index a7ac8e1..3c0a866 100644 --- a/book/source/signing_data.md +++ b/book/source/signing_data.md @@ -70,13 +70,13 @@ A {term}`one-pass signed` {term}`OpenPGP message` consi 1. [**One-pass signature packets**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#one-pass-sig): These one or more {term}`packets` precede the signed data and enable {term}`signature` computation (both creation and verification) in a single pass. -2. [**Literal data packet**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#lit): This contains the original data (e.g., the body of a message), without additional interpretation or conversion. +2. [**{term}`OpenPGP message`**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#lit): This contains the original data (e.g., the body of a message), which is signed without additional interpretation or conversion. Internally, a signed [message](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-openpgp-messages) consists of one or more OpenPGP packets. The message that gets signed could for example consist of a {term}`Literal Data Packet`, or a {term}`Compressed Data Packet`. 3. **{term}`Data signature packets`**: These contain the {term}`cryptographic signature` corresponding to the original data. ```{figure} plain_svg/ops-signed-message.svg :name: fig-ops-signed-message -:alt: Depicts the structure of a one-pass signed message. Two one-pass signatures lead the literal data packet, followed by two signature packets. Arrows show, how the hash-algorithm field of the one-pass signatures is inspected in order to initiate the hashing procedure. +:alt: Depicts the structure of a one-pass signed message. Two one-pass signatures lead a literal data packet, followed by two signature packets. Arrows show, how the hash-algorithm field of the one-pass signatures is inspected in order to initiate the hashing procedure. The structure of a one-pass signed message. ``` @@ -109,9 +109,9 @@ The signer can easily emit this metadata before processing the full message, and #### Creation -To produce a {term}`one-pass inline signature`, the {term}`signer` decides on a hash algorithm and emits a {term}`one-pass signature packet` into the destination {term}`OpenPGP message`. This contains essential information such as the {term}`fingerprint` of the {term}`signing key` and the {term}`hash` algorithm used for computing the {term}`signature`'s {term}`hash digest`. The signer then processes the entirety of the signed data, emitting it as a {term}`literal data` into the message as well. Once the data is processed, the {term}`signer` calculates a {term}`cryptographic signature` using the calculated hash value. Lastly, the result is emitted as a {term}`data signature packet` to the output message, and the whole packet sequence can be efficiently stored or transmitted. +To produce a {term}`one-pass inline signature`, the {term}`signer` decides on a hash algorithm and emits a {term}`one-pass signature packet` into the destination {term}`OpenPGP message`. This contains essential information such as the {term}`fingerprint` of the {term}`signing key` and the {term}`hash` algorithm used for computing the {term}`signature`'s {term}`hash digest`. The signer then processes the entirety of the signed message, emitting it as a series of one or more {term}`packets` into the message as well. Once the data is processed, the {term}`signer` calculates a {term}`cryptographic signature` using the calculated hash value. Lastly, the result is emitted as a {term}`data signature packet` to the output message, and the whole packet sequence can be efficiently stored or transmitted. -For efficient {term}`verification`, an application must understand how to handle the {term}`literal data` prior to reading from it. This requirement is addressed by the {term}`one-pass signature packets` located at the beginning of {term}`inline-signed` messages. This setup enables the verifier to process the data correctly and efficiently in only a single pass. +For efficient {term}`verification`, an application must understand how to handle the {term}`OpenPGP message` prior to reading from it. This requirement is addressed by the {term}`one-pass signature packets` located at the beginning of {term}`inline-signed` messages. This setup enables the verifier to process the data correctly and efficiently in a single pass. Strictly speaking, knowing just the hash algorithm would be sufficient to begin the verification process. However, having efficient access to the signer's fingerprint or key ID upfront allows OpenPGP software to fetch the signer's certificate(s) before processing the entirety of the - potentially large - signed data. This may, for example, involve downloading the certificate from a keyserver. In case fetching the signer's certificate(s) fails, or requires additional input from the user, it is better to signal the user about this before processing the data. @@ -121,7 +121,7 @@ Strictly speaking, knowing just the hash algorithm would be sufficient to begin 1. **Initiation with {term}`one-pass signature packets`**: These {term}`packets` begin the {term}`verification` process. They include the {term}`signer`'s {term}`key ID`/{term}`fingerprint`, essential for identifying the appropriate {term}`public key` for signature {term}`validation`. -2. **Processing the {term}`literal data packet`**: This step involves {term}`hashing` the literal data, preparing it for {term}`signature` {term}`verification`. +2. **Processing the {term}`OpenPGP message`**: This step involves {term}`hashing` its data, preparing it for {term}`signature` {term}`verification`. 3. **{term}`Verifying` {term}`signature packets`**: Located at the end of the message, these {term}`packets` are checked against the previously calculated {term}`hash digest`. @@ -138,7 +138,7 @@ In this format, the signature packets are stored ahead of the message itself: 1. **{term}`Data signature packets`**: These one or more packets contain the {term}`cryptographic signature` corresponding to the original data. -2. [**Literal data packet**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#lit): This contains the original data (e.g., the body of a message), without additional interpretation or conversion. +2. [**{term}`OpenPGP message`**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#lit): This contains the original data (e.g., the body of a message), without additional interpretation or conversion. ```{figure} plain_svg/prefixed-signed-message.svg :name: fig-prefixed-signed-message From ecf0bc1c7b49fa8976d2671a80b6a0d21ac3940d Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Fri, 22 Dec 2023 19:39:04 +0100 Subject: [PATCH 22/33] Move technical details about inline signatures into the "advanced" chapter --- book/source/adv/signing_data.md | 113 +++++++++++++++++++++++++++++++- book/source/signing_data.md | 104 +---------------------------- 2 files changed, 112 insertions(+), 105 deletions(-) diff --git a/book/source/adv/signing_data.md b/book/source/adv/signing_data.md index f031233..d89250e 100644 --- a/book/source/adv/signing_data.md +++ b/book/source/adv/signing_data.md @@ -5,6 +5,115 @@ SPDX-License-Identifier: CC-BY-SA-4.0 # Advanced material: Signatures over data +(adv-inline-signature)= +## Internals of inline signed messages + +Inline-signed messages are one of the forms of [OpenPGP data signatures](forms-of-data-signatures). An {term}`inline-signed message ` joins the signed data and its corresponding {term}`data signature` into a single {term}`OpenPGP message`. + +OpenPGP defines two variant forms of inline-signed messages: + +1. **{term}`One-pass signed messages`** This is the commonly used format for inline-signed messages. A signer can produce and a verifier can verify this format in one pass. +2. **{term}`Prefixed signed messages`** This format predates[^inline-signature-formats] {term}`one-pass signed messages` and is conceptually slightly simpler. However, it has no strong benefits and is now rarely used. + +[^inline-signature-formats]: One-pass signing was first specified in RFC 2440. The format was not supported in PGP 2.6.x. + +(one-pass-signature)= +### One-pass signed message + +This is the commonly used format for inline signed messages. + +#### Structure + +A {term}`one-pass signed` {term}`OpenPGP message` consists of three segments: + +1. [**One-pass signature packets**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#one-pass-sig): These one or more {term}`packets` precede the signed data and enable {term}`signature` computation (both creation and verification) in a single pass. + +2. [**{term}`OpenPGP message`**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#lit): This contains the original data (e.g., the body of a message), which is signed without additional interpretation or conversion. Internally, a signed [message](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-openpgp-messages) consists of one or more OpenPGP packets. The message that gets signed could, for example, consist of a {term}`Literal Data Packet`, or a {term}`Compressed Data Packet`. + +3. **{term}`Data signature packets`**: These contain the {term}`cryptographic signature` corresponding to the original data. + +```{figure} ../plain_svg/ops-signed-message.svg +:name: fig-ops-signed-message +:alt: Depicts the structure of a one-pass signed message. Two one-pass signatures lead a literal data packet, followed by two signature packets. Arrows show, how the hash-algorithm field of the one-pass signatures is inspected in order to initiate the hashing procedure. + +The structure of a one-pass signed message. +``` + +```{note} +Despite its name, a {term}`one-pass signature packet` is not a type of {term}`signature packet`. + +Instead, it's a type of auxiliary packet that can be used in conjunction with {term}`signature packets`. Its use allows storing the {term}`signature packets` after the message body. +``` + +#### The function of the one-pass signature packet + +To understand the purpose of this packet, consider that without it, the position of signature packets within an inline signed OpenPGP message constitutes a trade-off for efficient data processing. In particular when signed data is large and exceeds available memory in size. + +The producer of a signed OpenPGP message wants to streamline the signature calculation process in such a way that allows to emit a copy of the signed data while calculating the cryptographic signature. On the signer's side, the signature packet is therefore easy to store after the signed data. + +The verifier, on the other hand, needs some information from the signature packet in order to perform the signature verification process. In particular, the verifier needs to know which hash algorithm was used to calculate the signature, in order to perform the same hashing operation on the message data. + +As a consequence, without a {term}`one-pass signature packet`, either: +- the producer would need to process the signed data twice: + - once to calculate the signature, and + - a second time to emit the signed data (the result is a prefixed signed message), or +- the verifier would need to process the OpenPGP message twice: + - once to read the signature packets at the end in order to determine the hash algorithm, and + - a second time to process the body of the message, and calculate the hash verifying the signature. + +The one-pass signature packet solves this issue, by allowing both the creation and verification of a signed message in a single pass. It effectively contains a copy of the data in a signature packet, but without the cryptographic signature data. + +The signer can easily emit this metadata before processing the full message, and for the verifier, this metadata enables processing of the message body. Both signer and verifier can efficiently generate or check a one-pass signed message. + +#### Creation + +To produce a {term}`one-pass inline signature`, the {term}`signer` decides on a hash algorithm and emits a {term}`one-pass signature packet` into the destination {term}`OpenPGP message`. This contains essential information such as the {term}`fingerprint` of the {term}`signing key` and the {term}`hash` algorithm used for computing the {term}`signature`'s {term}`hash digest`. The signer then processes the entirety of the signed message, emitting it as a series of one or more {term}`packets` into the message as well. Once the data is processed, the {term}`signer` calculates a {term}`cryptographic signature` using the calculated hash value. Lastly, the result is emitted as a {term}`data signature packet` to the output message, and the whole packet sequence can be efficiently stored or transmitted. + +For efficient {term}`verification`, an application must understand how to handle the {term}`OpenPGP message` prior to reading from it. This requirement is addressed by the {term}`one-pass signature packets` located at the beginning of {term}`inline-signed` messages. This setup enables the verifier to process the data correctly and efficiently in a single pass. + +Strictly speaking, knowing just the hash algorithm would be sufficient to begin the verification process. However, having efficient access to the signer's fingerprint or key ID upfront allows OpenPGP software to fetch the signer's certificate(s) before processing the entirety of the - potentially large - signed data. This may, for example, involve downloading the certificate from a keyserver. In case fetching the signer's certificate(s) fails, or requires additional input from the user, it is better to signal the user about this before processing the data. + +#### Verification + +{term}`Inline-signed` messages enable efficient {term}`verification` in *one pass*, structured as follows: + +1. **Initiation with {term}`one-pass signature packets`**: These {term}`packets` begin the {term}`verification` process. They include the {term}`signer`'s {term}`key ID`/{term}`fingerprint`, essential for identifying the appropriate {term}`public key` for signature {term}`validation`. + +2. **Processing the {term}`OpenPGP message`**: This step involves {term}`hashing` its data, preparing it for {term}`signature` {term}`verification`. + +3. **{term}`Verifying` {term}`signature packets`**: Located at the end of the message, these {term}`packets` are checked against the previously calculated {term}`hash digest`. + +Important to note, the {term}`signer`'s {term}`public key`, critical for the final {term}`verification` step, is not embedded in the message. Verifiers must acquire this {term}`key` externally (e.g., from a {term}`key server`) to authenticate the {term}`signature` successfully. + +(prefixed-signature)= +### Prefixed signed message + +A {term}`prefixed signed message` consists of {term}`signature packet(s)` followed by the message. For the verifier, processing one-pass signed and prefixed signed messages are equally convenient. However, on the signer's side, it takes more resources to generate a {term}`prefixed signed message`. + +#### Structure + +In this format, the signature packets are stored ahead of the message itself: + +1. **{term}`Data signature packets`**: These one or more packets contain the {term}`cryptographic signature` corresponding to the original data. + +2. [**{term}`OpenPGP message`**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#lit): This contains the original data (e.g., the body of a message), without additional interpretation or conversion. + +```{figure} ../plain_svg/prefixed-signed-message.svg +:name: fig-prefixed-signed-message +:alt: Depicts the structure of a prefixed signed message. As an example, two signature packets lead a literal data packet. Arrows show, how the signatures hash algorithm field is inspected to start the hashing procedure. + +Structure of a prefixed signed message. +``` + +Compared to a {term}`one-pass signed message`, there are no {term}`one-pass signature packets` in this format, and the (otherwise equivalent) {term}`signature packet(s)` are stored ahead of the signed data. + +For verification, this is equally convenient as the one-pass signed message form. + +However, when a signer creates a {term}`prefixed signed message`, the signed data must be processed twice: + +- once reading it to calculate the cryptographic signature, and +- once more to store the data in the generated OpenPGP message, after the signature packet(s). + ## Nesting of one-pass signatures Signing a message using the one-pass mechanism involves prepending a *One-Pass-Signature* (OPS) packet to the message and appending the corresponding signature, sandwiching the signed content. @@ -16,9 +125,9 @@ One-Pass-Signatures are nested, meaning the outermost One-Pass-Signature packet ``` When a message is signed, the signature is always calculated over the contents of the literal data packet, not the literal data packet itself. -This means, that if a message, which is compressed using a compressed data packet is wrapped using a one-pass-signature, the signature is still being calculated over the plaintext inside the literal data packet. +This means that if a message, which is compressed using a compressed data packet is wrapped using a one-pass-signature, the signature is still being calculated over the plaintext inside the literal data packet. -There is one exception though. +There is one exception, though. ```{note} Of course there is. ``` diff --git a/book/source/signing_data.md b/book/source/signing_data.md index 3c0a866..a9817ec 100644 --- a/book/source/signing_data.md +++ b/book/source/signing_data.md @@ -52,109 +52,7 @@ An {term}`inline signature` joins the signed data and its corresponding {term}`d This method is commonly used for signing or encrypting emails. Most email software capable of handling OpenPGP communications typically uses {term}`inline signatures`. -OpenPGP defines two variant forms of inline-signed messages: - -1. **{term}`One-pass signed messages`** This is the commonly used format for inline-signed messages. A signer can produce and a verifier can verify this format in one pass. -2. **{term}`Prefixed signed messages`** This format predates[^inline-signature-formats] {term}`one-pass signed messages` and is conceptually slightly simpler. However, it has no strong benefits and is now rarely used. - -[^inline-signature-formats]: One-pass signing was first specified in RFC 2440. The format was not supported in PGP 2.6.x. - -(one-pass-signature)= -### One-pass signed message - -This is the commonly used format for inline signed messages. - -#### Structure - -A {term}`one-pass signed` {term}`OpenPGP message` consists of three segments: - -1. [**One-pass signature packets**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#one-pass-sig): These one or more {term}`packets` precede the signed data and enable {term}`signature` computation (both creation and verification) in a single pass. - -2. [**{term}`OpenPGP message`**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#lit): This contains the original data (e.g., the body of a message), which is signed without additional interpretation or conversion. Internally, a signed [message](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-openpgp-messages) consists of one or more OpenPGP packets. The message that gets signed could for example consist of a {term}`Literal Data Packet`, or a {term}`Compressed Data Packet`. - -3. **{term}`Data signature packets`**: These contain the {term}`cryptographic signature` corresponding to the original data. - -```{figure} plain_svg/ops-signed-message.svg -:name: fig-ops-signed-message -:alt: Depicts the structure of a one-pass signed message. Two one-pass signatures lead a literal data packet, followed by two signature packets. Arrows show, how the hash-algorithm field of the one-pass signatures is inspected in order to initiate the hashing procedure. - -The structure of a one-pass signed message. -``` - -```{note} -Despite its name, a {term}`one-pass signature packet` is not a type of {term}`signature packet`. - -Instead, it's a type of auxiliary packet that can be used in conjunction with {term}`signature packets`. Its use allows storing the {term}`signature packets` after the message body. -``` - -#### The function of the one-pass signature packet - -To understand the purpose of this packet, consider that without it, the position of signature packets within an inline signed OpenPGP message constitutes a trade-off for efficient data processing. In particular when signed data is large and exceeds available memory in size. - -The producer of a signed OpenPGP message wants to streamline the signature calculation process in such a way that allows to emit a copy of the signed data while calculating the cryptographic signature. On the signer's side, the signature packet is therefore easy to store after the signed data. - -The verifier, on the other hand, needs some information from the signature packet in order to perform the signature verification process. In particular, the verifier needs to know which hash algorithm was used to calculate the signature, in order to perform the same hashing operation on the message data. - -As a consequence, without a {term}`one-pass signature packet`, either: -- the producer would need to process the signed data twice: - - once to calculate the signature, and - - a second time to emit the signed data (the result is a prefixed signed message), or -- the verifier would need to process the OpenPGP message twice: - - once to read the signature packets at the end in order to determine the hash algorithm, and - - a second time to process the body of the message, and calculate the hash verifying the signature. - -The one-pass signature packet solves this issue, by allowing both the creation and verification of a signed message in a single pass. It effectively contains a copy of the data in a signature packet, but without the cryptographic signature data. - -The signer can easily emit this metadata before processing the full message, and for the verifier, this metadata enables processing of the message body. Both signer and verifier can efficiently generate or check a one-pass signed message. - -#### Creation - -To produce a {term}`one-pass inline signature`, the {term}`signer` decides on a hash algorithm and emits a {term}`one-pass signature packet` into the destination {term}`OpenPGP message`. This contains essential information such as the {term}`fingerprint` of the {term}`signing key` and the {term}`hash` algorithm used for computing the {term}`signature`'s {term}`hash digest`. The signer then processes the entirety of the signed message, emitting it as a series of one or more {term}`packets` into the message as well. Once the data is processed, the {term}`signer` calculates a {term}`cryptographic signature` using the calculated hash value. Lastly, the result is emitted as a {term}`data signature packet` to the output message, and the whole packet sequence can be efficiently stored or transmitted. - -For efficient {term}`verification`, an application must understand how to handle the {term}`OpenPGP message` prior to reading from it. This requirement is addressed by the {term}`one-pass signature packets` located at the beginning of {term}`inline-signed` messages. This setup enables the verifier to process the data correctly and efficiently in a single pass. - -Strictly speaking, knowing just the hash algorithm would be sufficient to begin the verification process. However, having efficient access to the signer's fingerprint or key ID upfront allows OpenPGP software to fetch the signer's certificate(s) before processing the entirety of the - potentially large - signed data. This may, for example, involve downloading the certificate from a keyserver. In case fetching the signer's certificate(s) fails, or requires additional input from the user, it is better to signal the user about this before processing the data. - -#### Verification - -{term}`Inline-signed` messages enable efficient {term}`verification` in *one pass*, structured as follows: - -1. **Initiation with {term}`one-pass signature packets`**: These {term}`packets` begin the {term}`verification` process. They include the {term}`signer`'s {term}`key ID`/{term}`fingerprint`, essential for identifying the appropriate {term}`public key` for signature {term}`validation`. - -2. **Processing the {term}`OpenPGP message`**: This step involves {term}`hashing` its data, preparing it for {term}`signature` {term}`verification`. - -3. **{term}`Verifying` {term}`signature packets`**: Located at the end of the message, these {term}`packets` are checked against the previously calculated {term}`hash digest`. - -Important to note, the {term}`signer`'s {term}`public key`, critical for the final {term}`verification` step, is not embedded in the message. Verifiers must acquire this {term}`key` externally (e.g., from a {term}`key server`) to authenticate the {term}`signature` successfully. - -(prefixed-signature)= -### Prefixed signed message - -A {term}`prefixed signed message` consists of {term}`signature packet(s)` followed by the message. For the verifier, processing one-pass signed and prefixed signed messages are equally convenient. However, on the signer's side, it takes more resources to generate a {term}`prefixed signed message`. - -#### Structure - -In this format, the signature packets are stored ahead of the message itself: - -1. **{term}`Data signature packets`**: These one or more packets contain the {term}`cryptographic signature` corresponding to the original data. - -2. [**{term}`OpenPGP message`**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#lit): This contains the original data (e.g., the body of a message), without additional interpretation or conversion. - -```{figure} plain_svg/prefixed-signed-message.svg -:name: fig-prefixed-signed-message -:alt: Depicts the structure of a prefixed signed message. As an example, two signature packets lead a literal data packet. Arrows show, how the signatures hash algorithm field is inspected to start the hashing procedure. - -Structure of a prefixed signed message. -``` - -Compared to a {term}`one-pass signed message`, there are no {term}`one-pass signature packets` in this format, and the (otherwise equivalent) {term}`signature packet(s)` are stored ahead of the signed data. - -For verification, this is equally convenient as the one-pass signed message form. - -However, when a signer creates a {term}`prefixed signed message`, the signed data must be processed twice: - -- once reading it to calculate the cryptographic signature, and -- once more to store the data in the generated OpenPGP message, after the signature packet(s). +For more details and internals, see [](adv-inline-signature). (cleartext-signature)= ## Cleartext signatures From 2444e6cc931247b56a3f666447ab88be80a25f75 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 23 Dec 2023 04:01:07 +0100 Subject: [PATCH 23/33] Adjust styling of "one-pass" in the nesting section --- book/source/adv/signing_data.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/book/source/adv/signing_data.md b/book/source/adv/signing_data.md index d89250e..2f65f87 100644 --- a/book/source/adv/signing_data.md +++ b/book/source/adv/signing_data.md @@ -116,16 +116,16 @@ However, when a signer creates a {term}`prefixed signed message`, the signed dat ## Nesting of one-pass signatures -Signing a message using the one-pass mechanism involves prepending a *One-Pass-Signature* (OPS) packet to the message and appending the corresponding signature, sandwiching the signed content. +Signing a message using the one-pass mechanism involves prepending a *one-pass signature* (OPS) packet to the message and appending the corresponding signature, sandwiching the signed content. An OpenPGP message can contain multiple signatures added that way. ```{note} -One-Pass-Signatures are nested, meaning the outermost One-Pass-Signature packet corresponds to the outermost signature packet. +One-pass signatures are nested, meaning the outermost one-pass signature packet corresponds to the outermost signature packet. ``` When a message is signed, the signature is always calculated over the contents of the literal data packet, not the literal data packet itself. -This means that if a message, which is compressed using a compressed data packet is wrapped using a one-pass-signature, the signature is still being calculated over the plaintext inside the literal data packet. +This means that if a message, which is compressed using a compressed data packet is wrapped using a one-pass signature, the signature is still being calculated over the plaintext inside the literal data packet. There is one exception, though. ```{note} @@ -137,20 +137,20 @@ If this flag is set to `0`, it indicates that further OPSs will follow this pack [^nested-flag]: See [description of the nested flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-5.4-3.8.1). -This mechanism enables attested signatures, where the signer signs an already one-pass-signed message including the already contained signature. +This mechanism enables attested signatures, where the signer signs an already one-pass signed message including the already contained signature. As a practical example, consider the following notation: * `LIT("Hello World")` represents a literal data packet with the content `Hello World`. * `COMP(XYZ)` represents a compressed data packet over some other packet `XYZ`. -* `OPS₁` represents a one-pass-signature packet with the nested flag set to `1`. Analogous, `OPS₀` has the nested flag set to `0`. +* `OPS₁` represents a one-pass signature packet with the nested flag set to `1`. Analogous, `OPS₀` has the nested flag set to `0`. * `SIG` represents a signature packet. -A normal, one-pass-signed message looks like this: +A normal, one-pass signed message looks like this: `OPS₁ LIT("Hello World") SIG` Here, the signature is calculated over the plaintext `Hello World`, as is it in a message that has the following form: `OPS₁ COMP(LIT("Hello World")) SIG`. -A message, where multiple one-pass-signatures are calculated over the same plaintext looks the following: +A message, where multiple one-pass signatures are calculated over the same plaintext looks the following: `OPS₀ OPS₀ OPS₁ LIT("Hello World") SIG SIG SIG` All three signatures are calculated over the same plaintext `Hello World`. From 7b4031dc0a5b6d12038f710c2e7fda215b959023 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 23 Dec 2023 19:09:17 +0100 Subject: [PATCH 24/33] Move "nesting" section up into the OPS section --- book/source/adv/signing_data.md | 60 ++++++++++++++++----------------- 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/book/source/adv/signing_data.md b/book/source/adv/signing_data.md index 2f65f87..b8e9ad6 100644 --- a/book/source/adv/signing_data.md +++ b/book/source/adv/signing_data.md @@ -85,36 +85,7 @@ Strictly speaking, knowing just the hash algorithm would be sufficient to begin Important to note, the {term}`signer`'s {term}`public key`, critical for the final {term}`verification` step, is not embedded in the message. Verifiers must acquire this {term}`key` externally (e.g., from a {term}`key server`) to authenticate the {term}`signature` successfully. -(prefixed-signature)= -### Prefixed signed message - -A {term}`prefixed signed message` consists of {term}`signature packet(s)` followed by the message. For the verifier, processing one-pass signed and prefixed signed messages are equally convenient. However, on the signer's side, it takes more resources to generate a {term}`prefixed signed message`. - -#### Structure - -In this format, the signature packets are stored ahead of the message itself: - -1. **{term}`Data signature packets`**: These one or more packets contain the {term}`cryptographic signature` corresponding to the original data. - -2. [**{term}`OpenPGP message`**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#lit): This contains the original data (e.g., the body of a message), without additional interpretation or conversion. - -```{figure} ../plain_svg/prefixed-signed-message.svg -:name: fig-prefixed-signed-message -:alt: Depicts the structure of a prefixed signed message. As an example, two signature packets lead a literal data packet. Arrows show, how the signatures hash algorithm field is inspected to start the hashing procedure. - -Structure of a prefixed signed message. -``` - -Compared to a {term}`one-pass signed message`, there are no {term}`one-pass signature packets` in this format, and the (otherwise equivalent) {term}`signature packet(s)` are stored ahead of the signed data. - -For verification, this is equally convenient as the one-pass signed message form. - -However, when a signer creates a {term}`prefixed signed message`, the signed data must be processed twice: - -- once reading it to calculate the cryptographic signature, and -- once more to store the data in the generated OpenPGP message, after the signature packet(s). - -## Nesting of one-pass signatures +#### Nesting of one-pass signatures Signing a message using the one-pass mechanism involves prepending a *one-pass signature* (OPS) packet to the message and appending the corresponding signature, sandwiching the signed content. @@ -159,3 +130,32 @@ Now, a message, where the signer attests an already signed message has the follo `OPS₁ OPS₁ LIT("Hello World") SIG SIG` While the inner signature is calculated over the usual plaintext `Hello World`, the outer signature is instead calculated over `OPS₁ Hello World SIG`. + +(prefixed-signature)= +### Prefixed signed message + +A {term}`prefixed signed message` consists of {term}`signature packet(s)` followed by the message. For the verifier, processing one-pass signed and prefixed signed messages are equally convenient. However, on the signer's side, it takes more resources to generate a {term}`prefixed signed message`. + +#### Structure + +In this format, the signature packets are stored ahead of the message itself: + +1. **{term}`Data signature packets`**: These one or more packets contain the {term}`cryptographic signature` corresponding to the original data. + +2. [**{term}`OpenPGP message`**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#lit): This contains the original data (e.g., the body of a message), without additional interpretation or conversion. + +```{figure} ../plain_svg/prefixed-signed-message.svg +:name: fig-prefixed-signed-message +:alt: Depicts the structure of a prefixed signed message. As an example, two signature packets lead a literal data packet. Arrows show, how the signatures hash algorithm field is inspected to start the hashing procedure. + +Structure of a prefixed signed message. +``` + +Compared to a {term}`one-pass signed message`, there are no {term}`one-pass signature packets` in this format, and the (otherwise equivalent) {term}`signature packet(s)` are stored ahead of the signed data. + +For verification, this is equally convenient as the one-pass signed message form. + +However, when a signer creates a {term}`prefixed signed message`, the signed data must be processed twice: + +- once reading it to calculate the cryptographic signature, and +- once more to store the data in the generated OpenPGP message, after the signature packet(s). From 59832e220bb10a3d658890b7822489b60cb7e27d Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 26 Dec 2023 17:15:31 +0100 Subject: [PATCH 25/33] Edits for clarity; normalize "inline signed". Inline signed: without dash, to correspond with "one-pass signed". C-R seems inconsistent about this styling. --- book/source/adv/signing_data.md | 54 ++++++++++++++++++--------------- 1 file changed, 30 insertions(+), 24 deletions(-) diff --git a/book/source/adv/signing_data.md b/book/source/adv/signing_data.md index b8e9ad6..5411dfb 100644 --- a/book/source/adv/signing_data.md +++ b/book/source/adv/signing_data.md @@ -8,11 +8,11 @@ SPDX-License-Identifier: CC-BY-SA-4.0 (adv-inline-signature)= ## Internals of inline signed messages -Inline-signed messages are one of the forms of [OpenPGP data signatures](forms-of-data-signatures). An {term}`inline-signed message ` joins the signed data and its corresponding {term}`data signature` into a single {term}`OpenPGP message`. +Inline signed messages are one of the forms of [OpenPGP data signatures](forms-of-data-signatures). An {term}`inline signed message ` joins the signed data and its corresponding {term}`data signature` into a single {term}`OpenPGP message`. -OpenPGP defines two variant forms of inline-signed messages: +OpenPGP defines two variant forms of inline signed messages: -1. **{term}`One-pass signed messages`** This is the commonly used format for inline-signed messages. A signer can produce and a verifier can verify this format in one pass. +1. **{term}`One-pass signed messages`** This is the commonly used format for inline signed messages. A signer can produce and a verifier can verify this format in one pass. 2. **{term}`Prefixed signed messages`** This format predates[^inline-signature-formats] {term}`one-pass signed messages` and is conceptually slightly simpler. However, it has no strong benefits and is now rarely used. [^inline-signature-formats]: One-pass signing was first specified in RFC 2440. The format was not supported in PGP 2.6.x. @@ -28,7 +28,7 @@ A {term}`one-pass signed` {term}`OpenPGP message` consi 1. [**One-pass signature packets**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#one-pass-sig): These one or more {term}`packets` precede the signed data and enable {term}`signature` computation (both creation and verification) in a single pass. -2. [**{term}`OpenPGP message`**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#lit): This contains the original data (e.g., the body of a message), which is signed without additional interpretation or conversion. Internally, a signed [message](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-openpgp-messages) consists of one or more OpenPGP packets. The message that gets signed could, for example, consist of a {term}`Literal Data Packet`, or a {term}`Compressed Data Packet`. +2. [**{term}`OpenPGP message`**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#lit): This contains the original data (e.g., the body of a message), which is signed without additional interpretation or conversion. Internally, a signed [message](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-openpgp-messages) consists of one or more OpenPGP packets. The message that gets signed will typically consist of either a {term}`Literal Data Packet`, or a {term}`Compressed Data Packet`. 3. **{term}`Data signature packets`**: These contain the {term}`cryptographic signature` corresponding to the original data. @@ -42,40 +42,46 @@ The structure of a one-pass signed message. ```{note} Despite its name, a {term}`one-pass signature packet` is not a type of {term}`signature packet`. -Instead, it's a type of auxiliary packet that can be used in conjunction with {term}`signature packets`. Its use allows storing the {term}`signature packets` after the message body. +Instead, it's a type of auxiliary packet that can be used in conjunction with {term}`signature packets`, to enable efficient generation and checking of inline signed messages. + +The structure of a {term}`one-pass signature packet` closely mirrors an {term}`OpenPGP signature packet`. However, it does not contain a cryptographic signature. ``` #### The function of the one-pass signature packet -To understand the purpose of this packet, consider that without it, the position of signature packets within an inline signed OpenPGP message constitutes a trade-off for efficient data processing. In particular when signed data is large and exceeds available memory in size. +The purpose of this packet is efficient handling of inline signed messages in *stream processing* mode. This is particularly important when the signed message is large and exceeds available memory in size. -The producer of a signed OpenPGP message wants to streamline the signature calculation process in such a way that allows to emit a copy of the signed data while calculating the cryptographic signature. On the signer's side, the signature packet is therefore easy to store after the signed data. +Without this packet, the position of signature packets within an inline signed OpenPGP message constitutes a trade-off: -The verifier, on the other hand, needs some information from the signature packet in order to perform the signature verification process. In particular, the verifier needs to know which hash algorithm was used to calculate the signature, in order to perform the same hashing operation on the message data. +- The producer of a signed OpenPGP message wants to streamline the signature calculation process in such a way that allows to emit a copy of the signed data while calculating the cryptographic signature. On the signer's side, the signature packet is therefore easy to store after the signed data. +- The verifier, on the other hand, needs some information from the signature packet to perform the signature verification process. In particular, the verifier needs to know which hash algorithm was used to calculate the signature, to perform the same hashing operation on the message data. As a consequence, without a {term}`one-pass signature packet`, either: -- the producer would need to process the signed data twice: - - once to calculate the signature, and - - a second time to emit the signed data (the result is a prefixed signed message), or -- the verifier would need to process the OpenPGP message twice: - - once to read the signature packets at the end in order to determine the hash algorithm, and + +- The producer would need to process the input data twice: + - once to calculate the cryptographic signature, and + - a second time to emit the signed data (this format result is a [](prefixed-signature)), or +- The verifier would need to process the OpenPGP message twice: + - once to read the signature packets at the end to determine the hash algorithm, and - a second time to process the body of the message, and calculate the hash verifying the signature. -The one-pass signature packet solves this issue, by allowing both the creation and verification of a signed message in a single pass. It effectively contains a copy of the data in a signature packet, but without the cryptographic signature data. +The one-pass signature packet solves this issue by allowing both the *creation* and *verification* of a signed message in a single pass. The one-pass signature packet effectively contains an advance copy of the data in the signature packet, but without the cryptographic signature data. -The signer can easily emit this metadata before processing the full message, and for the verifier, this metadata enables processing of the message body. Both signer and verifier can efficiently generate or check a one-pass signed message. +The signer can easily emit the metadata in the one-pass signature packet before processing the full message. For the verifier, availability of this metadata at the start of the signed message enables processing of the message body. + +Even in stream processing mode, signers can efficiently generate one-pass signed messages, and verifiers can efficiently check them. #### Creation To produce a {term}`one-pass inline signature`, the {term}`signer` decides on a hash algorithm and emits a {term}`one-pass signature packet` into the destination {term}`OpenPGP message`. This contains essential information such as the {term}`fingerprint` of the {term}`signing key` and the {term}`hash` algorithm used for computing the {term}`signature`'s {term}`hash digest`. The signer then processes the entirety of the signed message, emitting it as a series of one or more {term}`packets` into the message as well. Once the data is processed, the {term}`signer` calculates a {term}`cryptographic signature` using the calculated hash value. Lastly, the result is emitted as a {term}`data signature packet` to the output message, and the whole packet sequence can be efficiently stored or transmitted. -For efficient {term}`verification`, an application must understand how to handle the {term}`OpenPGP message` prior to reading from it. This requirement is addressed by the {term}`one-pass signature packets` located at the beginning of {term}`inline-signed` messages. This setup enables the verifier to process the data correctly and efficiently in a single pass. +For efficient {term}`verification`, an application must understand how to handle the {term}`OpenPGP message` prior to reading from it. This requirement is addressed by the {term}`one-pass signature packets` located at the beginning of {term}`inline signed` messages. This setup enables the verifier to process the data correctly and efficiently in a single pass. Strictly speaking, knowing just the hash algorithm would be sufficient to begin the verification process. However, having efficient access to the signer's fingerprint or key ID upfront allows OpenPGP software to fetch the signer's certificate(s) before processing the entirety of the - potentially large - signed data. This may, for example, involve downloading the certificate from a keyserver. In case fetching the signer's certificate(s) fails, or requires additional input from the user, it is better to signal the user about this before processing the data. #### Verification -{term}`Inline-signed` messages enable efficient {term}`verification` in *one pass*, structured as follows: +{term}`Inline signed` messages enable efficient {term}`verification` in *one pass*, structured as follows: 1. **Initiation with {term}`one-pass signature packets`**: These {term}`packets` begin the {term}`verification` process. They include the {term}`signer`'s {term}`key ID`/{term}`fingerprint`, essential for identifying the appropriate {term}`public key` for signature {term}`validation`. @@ -87,24 +93,24 @@ Important to note, the {term}`signer`'s {term}`public key`, #### Nesting of one-pass signatures -Signing a message using the one-pass mechanism involves prepending a *one-pass signature* (OPS) packet to the message and appending the corresponding signature, sandwiching the signed content. +A {term}`one-pass signed message` can contain multiple signatures. -An OpenPGP message can contain multiple signatures added that way. +There are two subtly different use cases for this: + +- Multiple signers can issue cryptographic signatures that can be stored in one shared (and thus space-efficient) inline signed message. In this case, each signer makes a cryptographic statement about just the signed message. The individual signatures are independent of each other. +- Alternatively, a later signer can sign not just the input message, but also include a previous signature in their signature. In this case, the second signer notarizes the previous signer's signature combined with the signed message. ```{note} -One-pass signatures are nested, meaning the outermost one-pass signature packet corresponds to the outermost signature packet. +One-pass signatures are nested. The outermost one-pass signature packet corresponds to the outermost signature packet. ``` -When a message is signed, the signature is always calculated over the contents of the literal data packet, not the literal data packet itself. -This means that if a message, which is compressed using a compressed data packet is wrapped using a one-pass signature, the signature is still being calculated over the plaintext inside the literal data packet. - There is one exception, though. ```{note} Of course there is. ``` The OPS packet has a "nested" flag[^nested-flag], which can either be `1` or `0`. -If this flag is set to `0`, it indicates that further OPSs will follow this packet, which are calculated over the same plaintext data as this OPS is. A value of `1` indicates, that either no further OPS packets will follow (this OPS is the last), or that this OPS is calculated over the the usual plaintext data, but wrapped inside any OPS+Signature combinations that follow this OPS. +If this flag is set to `0`, it indicates that further OPSs will follow this packet, which are calculated over the same plaintext data as this OPS is. A value of `1` indicates, that either no further OPS packets will follow (this OPS is the last), or that this OPS is calculated over the usual plaintext data, but wrapped inside any OPS+Signature combinations that follow this OPS. [^nested-flag]: See [description of the nested flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-5.4-3.8.1). From 99ea7856cd6fd3945e370264e8989a6742ecb03f Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 26 Dec 2023 22:18:52 +0100 Subject: [PATCH 26/33] Link to one-pass signature packet section from glossary --- book/source/adv/signing_data.md | 1 + book/source/glossary.md | 5 ++++- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/book/source/adv/signing_data.md b/book/source/adv/signing_data.md index 5411dfb..85fcbea 100644 --- a/book/source/adv/signing_data.md +++ b/book/source/adv/signing_data.md @@ -47,6 +47,7 @@ Instead, it's a type of auxiliary packet that can be used in conjunction with {t The structure of a {term}`one-pass signature packet` closely mirrors an {term}`OpenPGP signature packet`. However, it does not contain a cryptographic signature. ``` +(one-pass-signature-packet)= #### The function of the one-pass signature packet The purpose of this packet is efficient handling of inline signed messages in *stream processing* mode. This is particularly important when the signed message is large and exceeds available memory in size. diff --git a/book/source/glossary.md b/book/source/glossary.md index e93d2bc..6b6be3e 100644 --- a/book/source/glossary.md +++ b/book/source/glossary.md @@ -347,7 +347,10 @@ Notation Tag Part of a {term}`Notation` name. One-pass Signature Packet - One or more {term}`packets` before the actual data in a {term}`Data Signature` which contain information to allow a receiving {term}`implementation` to create {term}`hashes` required for signature verification. See [RFC 5.4](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#one-pass-sig) for more details. + One or more {term}`packets` before the actual data in a {term}`Data Signature` which contain information to allow a receiving {term}`implementation` to create {term}`hashes` required for signature verification. + + See [](one-pass-signature-packet). + Also see [RFC 5.4](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#one-pass-sig). One-pass signed Message The commonly used form of an OpenPGP {term}`Inline Signature`. It combines an {term}`OpenPGP Message` with {term}`signature packets` and accompanying auxiliary {term}`One-pass signatures`. From 468f38da6db1e4800e356f600482995abc87f8d9 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 27 Dec 2023 03:30:55 +0100 Subject: [PATCH 27/33] Move verification-related text to the right section --- book/source/adv/signing_data.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/book/source/adv/signing_data.md b/book/source/adv/signing_data.md index 85fcbea..e899a77 100644 --- a/book/source/adv/signing_data.md +++ b/book/source/adv/signing_data.md @@ -76,13 +76,13 @@ Even in stream processing mode, signers can efficiently generate one-pass signed To produce a {term}`one-pass inline signature`, the {term}`signer` decides on a hash algorithm and emits a {term}`one-pass signature packet` into the destination {term}`OpenPGP message`. This contains essential information such as the {term}`fingerprint` of the {term}`signing key` and the {term}`hash` algorithm used for computing the {term}`signature`'s {term}`hash digest`. The signer then processes the entirety of the signed message, emitting it as a series of one or more {term}`packets` into the message as well. Once the data is processed, the {term}`signer` calculates a {term}`cryptographic signature` using the calculated hash value. Lastly, the result is emitted as a {term}`data signature packet` to the output message, and the whole packet sequence can be efficiently stored or transmitted. -For efficient {term}`verification`, an application must understand how to handle the {term}`OpenPGP message` prior to reading from it. This requirement is addressed by the {term}`one-pass signature packets` located at the beginning of {term}`inline signed` messages. This setup enables the verifier to process the data correctly and efficiently in a single pass. - -Strictly speaking, knowing just the hash algorithm would be sufficient to begin the verification process. However, having efficient access to the signer's fingerprint or key ID upfront allows OpenPGP software to fetch the signer's certificate(s) before processing the entirety of the - potentially large - signed data. This may, for example, involve downloading the certificate from a keyserver. In case fetching the signer's certificate(s) fails, or requires additional input from the user, it is better to signal the user about this before processing the data. - #### Verification -{term}`Inline signed` messages enable efficient {term}`verification` in *one pass*, structured as follows: +For efficient {term}`verification`, an application must understand how to handle the {term}`OpenPGP message` prior to reading from it. This requirement is addressed by the {term}`one-pass signature packets` located at the beginning of {term}`inline signed` messages. This setup enables the verifier to process the data correctly and efficiently in a single pass. + +Strictly speaking, knowing just the hash algorithm would be sufficient to begin the verification process. However, having efficient access to the signer's fingerprint or key ID upfront allows OpenPGP software to fetch the signer's certificate(s) before processing the entirety of the - potentially large - signed data. This may involve downloading the certificate from a keyserver. In case fetching the signer's certificate(s) fails, or requires additional input from the user, it is better to signal the user about this before processing the data. + +{term}`one-pass inline signed messages` enable efficient {term}`verification` in *one pass*, structured as follows: 1. **Initiation with {term}`one-pass signature packets`**: These {term}`packets` begin the {term}`verification` process. They include the {term}`signer`'s {term}`key ID`/{term}`fingerprint`, essential for identifying the appropriate {term}`public key` for signature {term}`validation`. From d9443963917e37c2764bf4e1751a22d6df282875 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 27 Dec 2023 03:36:58 +0100 Subject: [PATCH 28/33] Add a separate section about hashing of inline signature payload --- book/source/adv/signing_data.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/book/source/adv/signing_data.md b/book/source/adv/signing_data.md index e899a77..4082a64 100644 --- a/book/source/adv/signing_data.md +++ b/book/source/adv/signing_data.md @@ -166,3 +166,17 @@ However, when a signer creates a {term}`prefixed signed message`, the signed dat - once reading it to calculate the cryptographic signature, and - once more to store the data in the generated OpenPGP message, after the signature packet(s). + +(hashing-inline-data)= +### Hashing the signed payload of an inline signature + +When inline signing a message, the hash for the signed content is calculated over just the raw payload contained in a literal data packet. No metadata of the literal data packet is included in the signed hash. Even if a compressed data packet wraps the literal data packet, the inline signature is still calculated over the uncompressed content of the literal data packet. + +The calculation of inline data signatures is unusual in two regards: + +- Most OpenPGP signature calculations include packet metadata, but for literal data packets, only the payload is hashed. +- Packets are usually hashed without transforming the packet content for hashing. Decompressing the content of a compressed data packet for hashing is an exception to this pattern. + +However, this approach means that detached signatures and inline signatures are calculated on exactly the same data. + +One format can be transformed into the other, after the fact, without requiring the private key material of the signer. A compression layer can be inserted or removed without disturbing the validity of an existing signature. From eec47a64013100d1547e041ab1030a3115f008a1 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 27 Dec 2023 03:40:21 +0100 Subject: [PATCH 29/33] Simplify "nesting" section --- book/source/adv/signing_data.md | 18 ++++++------------ 1 file changed, 6 insertions(+), 12 deletions(-) diff --git a/book/source/adv/signing_data.md b/book/source/adv/signing_data.md index 4082a64..6a75d40 100644 --- a/book/source/adv/signing_data.md +++ b/book/source/adv/signing_data.md @@ -96,25 +96,19 @@ Important to note, the {term}`signer`'s {term}`public key`, A {term}`one-pass signed message` can contain multiple signatures. -There are two subtly different use cases for this: - -- Multiple signers can issue cryptographic signatures that can be stored in one shared (and thus space-efficient) inline signed message. In this case, each signer makes a cryptographic statement about just the signed message. The individual signatures are independent of each other. -- Alternatively, a later signer can sign not just the input message, but also include a previous signature in their signature. In this case, the second signer notarizes the previous signer's signature combined with the signed message. - ```{note} One-pass signatures are nested. The outermost one-pass signature packet corresponds to the outermost signature packet. ``` -There is one exception, though. -```{note} -Of course there is. -``` +There are two subtly different use cases for inline signatures that contain multiple signatures: + +- Multiple signers can issue cryptographic signatures that can be stored in one shared (and thus space-efficient) inline signed message. In this case, each signer makes a cryptographic statement about just the signed message. The individual signatures are independent of each other. +- Alternatively, a later signer can sign not just the input message, but also include a previous signature in their signature. In this case, the second signer attests the previous signer's signature combined with the signed message. + +To specify which of these two functions a signature performs, the {term}`one-pass signature packet` has a ["nested" flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-5.4-3.8.1), with a value of either `1` or `0`. -The OPS packet has a "nested" flag[^nested-flag], which can either be `1` or `0`. If this flag is set to `0`, it indicates that further OPSs will follow this packet, which are calculated over the same plaintext data as this OPS is. A value of `1` indicates, that either no further OPS packets will follow (this OPS is the last), or that this OPS is calculated over the usual plaintext data, but wrapped inside any OPS+Signature combinations that follow this OPS. -[^nested-flag]: See [description of the nested flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-5.4-3.8.1). - This mechanism enables attested signatures, where the signer signs an already one-pass signed message including the already contained signature. As a practical example, consider the following notation: From fda7264f10b12026fb2c3be41ae2d1e881bd56b1 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 27 Dec 2023 03:50:43 +0100 Subject: [PATCH 30/33] Move away from using "plaintext" to refer to signed data --- book/source/adv/signing_data.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/book/source/adv/signing_data.md b/book/source/adv/signing_data.md index 6a75d40..6eff25c 100644 --- a/book/source/adv/signing_data.md +++ b/book/source/adv/signing_data.md @@ -107,7 +107,7 @@ There are two subtly different use cases for inline signatures that contain mult To specify which of these two functions a signature performs, the {term}`one-pass signature packet` has a ["nested" flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-5.4-3.8.1), with a value of either `1` or `0`. -If this flag is set to `0`, it indicates that further OPSs will follow this packet, which are calculated over the same plaintext data as this OPS is. A value of `1` indicates, that either no further OPS packets will follow (this OPS is the last), or that this OPS is calculated over the usual plaintext data, but wrapped inside any OPS+Signature combinations that follow this OPS. +If the "nested" flag is set to `0`, it indicates that further OPSs will follow this packet, which are calculated over the same message payload data as this OPS is. A value of `1` indicates, that either no further OPS packets will follow (this OPS is the last), or that this OPS is calculated over the usual message payload data, but wrapped inside any OPS+Signature combinations that follow this OPS. This mechanism enables attested signatures, where the signer signs an already one-pass signed message including the already contained signature. @@ -120,17 +120,17 @@ As a practical example, consider the following notation: A normal, one-pass signed message looks like this: `OPS₁ LIT("Hello World") SIG` -Here, the signature is calculated over the plaintext `Hello World`, as is it in a message that has the following form: `OPS₁ COMP(LIT("Hello World")) SIG`. +Here, the signature is calculated over the payload `Hello World`. The signature doesn't change if the signed message is instead stored as: `OPS₁ COMP(LIT("Hello World")) SIG` (also see [](hashing-inline-data)). -A message, where multiple one-pass signatures are calculated over the same plaintext looks the following: +A message, where multiple one-pass signatures are calculated over the same payload looks the following: `OPS₀ OPS₀ OPS₁ LIT("Hello World") SIG SIG SIG` -All three signatures are calculated over the same plaintext `Hello World`. +All three signatures are calculated over the same payload `Hello World`. Now, a message, where the signer attests an already signed message has the following format: `OPS₁ OPS₁ LIT("Hello World") SIG SIG` -While the inner signature is calculated over the usual plaintext `Hello World`, the outer signature is instead calculated over `OPS₁ Hello World SIG`. +While the inner signature is calculated over the usual payload `Hello World`, the outer signature is instead calculated over `OPS₁ Hello World SIG`. (prefixed-signature)= ### Prefixed signed message From 6f3956c3a661983f4cbdb75e6af6f59ebca507f1 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Thu, 28 Dec 2023 02:32:34 +0100 Subject: [PATCH 31/33] Attempt to clarify and structure "nesting" section, some more --- book/source/adv/signing_data.md | 45 ++++++++++++++++++++------------- 1 file changed, 27 insertions(+), 18 deletions(-) diff --git a/book/source/adv/signing_data.md b/book/source/adv/signing_data.md index 6eff25c..9cc7f8d 100644 --- a/book/source/adv/signing_data.md +++ b/book/source/adv/signing_data.md @@ -94,22 +94,35 @@ Important to note, the {term}`signer`'s {term}`public key`, #### Nesting of one-pass signatures -A {term}`one-pass signed message` can contain multiple signatures. +A {term}`one-pass signed message` can actually contain multiple, nested, signatures. -```{note} -One-pass signatures are nested. The outermost one-pass signature packet corresponds to the outermost signature packet. -``` +Formally, this is the case because in the [OpenPGP message grammar](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-openpgp-messages) when an input OpenPGP message is one-pass signed, the resulting sequence of packets is in turn also considered an OpenPGP message. -There are two subtly different use cases for inline signatures that contain multiple signatures: +Thus, this signed message can be one-pass signed yet again. This construction means that all signature packet pairs bracket the innermost message, and the outermost one-pass signature packet corresponds to the outermost signature packet. -- Multiple signers can issue cryptographic signatures that can be stored in one shared (and thus space-efficient) inline signed message. In this case, each signer makes a cryptographic statement about just the signed message. The individual signatures are independent of each other. -- Alternatively, a later signer can sign not just the input message, but also include a previous signature in their signature. In this case, the second signer attests the previous signer's signature combined with the signed message. +##### Two semantics of nested signatures -To specify which of these two functions a signature performs, the {term}`one-pass signature packet` has a ["nested" flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-5.4-3.8.1), with a value of either `1` or `0`. +There are two different use cases and semantics for nested one-pass signatures: -If the "nested" flag is set to `0`, it indicates that further OPSs will follow this packet, which are calculated over the same message payload data as this OPS is. A value of `1` indicates, that either no further OPS packets will follow (this OPS is the last), or that this OPS is calculated over the usual message payload data, but wrapped inside any OPS+Signature combinations that follow this OPS. +- Multiple signers issue independent cryptographic signatures that are stored in one shared (and thus space-efficient) inline signed message. In this case, each signer makes a cryptographic statement about just the signed message. The signatures are independent of each other. +- Alternatively, a signer can sign not just the input message, but also include previous signatures in their signature. In this case, the signer makes a cryptographic statement about the pre-existing signature(s) combined with the signed message. This means that the new signer attests the previous signature(s)[^but-why]. -This mechanism enables attested signatures, where the signer signs an already one-pass signed message including the already contained signature. +[^but-why]: It's unclear to the authors of this text if any real-world use case for signatures that notarize inner signatures exists. + +##### How to pick one + +When nesting one-pass signatures, the default expectation would be that each enclosing signature makes a statement about the complete message it contains, including any one-pass signatures within the inner message. + +Issuers of signatures can choose the semantics of their signature, using the ["nested" flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-5.4-3.8.1) in the {term}`one-pass signature packet`. The "nested" flag has a value of either `1` or `0`. + +Meaning of the "nested" flag: + +- `0` means that the one-pass signature that this signature encloses is *not* signed/attested. The new signature doesn't make a cryptographic statement about the directly enclosed signature. If the directly enclosed one-pass signature also has its "nested" flag set to `0`, the enclosing signature also doesn't include the subsequent inner signature in its hashing, and so on. +- `1` means that this one-pass signature makes a cryptographic statement about the full message that it encloses, including all enclosed signatures, if any. + +A typical pattern of use is to set the "nested" flag to `1` on the innermost signature and to `0` on all enclosing signatures. With this pattern, all signatures are independent of each other. Each signature makes a statement about just the innermost message payload (which is stored in a literal data packet). + +##### Examples As a practical example, consider the following notation: * `LIT("Hello World")` represents a literal data packet with the content `Hello World`. @@ -122,15 +135,11 @@ A normal, one-pass signed message looks like this: Here, the signature is calculated over the payload `Hello World`. The signature doesn't change if the signed message is instead stored as: `OPS₁ COMP(LIT("Hello World")) SIG` (also see [](hashing-inline-data)). -A message, where multiple one-pass signatures are calculated over the same payload looks the following: -`OPS₀ OPS₀ OPS₁ LIT("Hello World") SIG SIG SIG` +A message, where multiple independent one-pass signatures are calculated over the same payload looks the following: +`OPS₀ OPS₀ OPS₁ LIT("Hello World") SIG SIG SIG` - all three signatures are calculated over the same payload `Hello World`. -All three signatures are calculated over the same payload `Hello World`. - -Now, a message, where the signer attests an already signed message has the following format: -`OPS₁ OPS₁ LIT("Hello World") SIG SIG` - -While the inner signature is calculated over the usual payload `Hello World`, the outer signature is instead calculated over `OPS₁ Hello World SIG`. +By contrast, a message, where the signer attests an already signed message has the following format: +`OPS₁ OPS₁ LIT("Hello World") SIG SIG`. While the inner signature is calculated over the usual payload `Hello World`, the outer signature is instead calculated over `OPS₁ Hello World SIG`. (prefixed-signature)= ### Prefixed signed message From fcab56b6667eee12a34ac9cd1260093c0c960377 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Thu, 28 Dec 2023 02:51:56 +0100 Subject: [PATCH 32/33] Fix some link markup, minor edits. --- book/source/adv/signing_data.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/book/source/adv/signing_data.md b/book/source/adv/signing_data.md index 9cc7f8d..2c88dbf 100644 --- a/book/source/adv/signing_data.md +++ b/book/source/adv/signing_data.md @@ -13,9 +13,9 @@ Inline signed messages are one of the forms of [OpenPGP data signatures](forms-o OpenPGP defines two variant forms of inline signed messages: 1. **{term}`One-pass signed messages`** This is the commonly used format for inline signed messages. A signer can produce and a verifier can verify this format in one pass. -2. **{term}`Prefixed signed messages`** This format predates[^inline-signature-formats] {term}`one-pass signed messages` and is conceptually slightly simpler. However, it has no strong benefits and is now rarely used. +2. **{term}`Prefixed signed messages`** This format predates[^inline-signature-formats] {term}`one-pass signed messages` and is conceptually slightly simpler. However, it is now rarely used and can be considered a legacy format. -[^inline-signature-formats]: One-pass signing was first specified in RFC 2440. The format was not supported in PGP 2.6.x. +[^inline-signature-formats]: One-pass signing was [first specified in RFC 2440](https://www.rfc-editor.org/rfc/rfc2440.html#section-5.4). The format was not supported in PGP 2.6.x. For one discussion of the feature in the lead-up to the standardization of RFC 2440, see [here](https://mailarchive.ietf.org/arch/msg/openpgp/U4Qg3Z9bj-RDgpwW5nmRNetOZKY/). (one-pass-signature)= ### One-pass signed message @@ -26,11 +26,11 @@ This is the commonly used format for inline signed messages. A {term}`one-pass signed` {term}`OpenPGP message` consists of three segments: -1. [**One-pass signature packets**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#one-pass-sig): These one or more {term}`packets` precede the signed data and enable {term}`signature` computation (both creation and verification) in a single pass. +1. **{term}`One-pass signature packets`**: These one or more {term}`packets` precede the signed data and enable {term}`signature` computation (both creation and verification) in a single pass. -2. [**{term}`OpenPGP message`**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#lit): This contains the original data (e.g., the body of a message), which is signed without additional interpretation or conversion. Internally, a signed [message](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-openpgp-messages) consists of one or more OpenPGP packets. The message that gets signed will typically consist of either a {term}`Literal Data Packet`, or a {term}`Compressed Data Packet`. +2. **{term}`OpenPGP message`**: This contains the original payload data (e.g., the body of a message), which is signed without additional interpretation or conversion. Internally, a signed [message](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-openpgp-messages) consists of one or more OpenPGP packets. This payload is typically stored as either a {term}`Literal Data Packet`, or a {term}`Compressed Data Packet`. -3. **{term}`Data signature packets`**: These contain the {term}`cryptographic signature` corresponding to the original data. +3. **{term}`Data signature packets`**: These contain the {term}`cryptographic signature` corresponding to the signed data. ```{figure} ../plain_svg/ops-signed-message.svg :name: fig-ops-signed-message From 096efc363577c35f71b9514dafd336afaf1c129f Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Thu, 28 Dec 2023 04:13:27 +0100 Subject: [PATCH 33/33] Add some more context to prefixed signed format --- book/source/adv/signing_data.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/book/source/adv/signing_data.md b/book/source/adv/signing_data.md index 2c88dbf..57408a0 100644 --- a/book/source/adv/signing_data.md +++ b/book/source/adv/signing_data.md @@ -146,6 +146,8 @@ By contrast, a message, where the signer attests an already signed message has t A {term}`prefixed signed message` consists of {term}`signature packet(s)` followed by the message. For the verifier, processing one-pass signed and prefixed signed messages are equally convenient. However, on the signer's side, it takes more resources to generate a {term}`prefixed signed message`. +This is a legacy format. Not all modern implementations support. However, for example, GnuPG 2.4.x can validate messages with this signature format. + #### Structure In this format, the signature packets are stored ahead of the message itself: @@ -163,7 +165,13 @@ Structure of a prefixed signed message. Compared to a {term}`one-pass signed message`, there are no {term}`one-pass signature packets` in this format, and the (otherwise equivalent) {term}`signature packet(s)` are stored ahead of the signed data. -For verification, this is equally convenient as the one-pass signed message form. +```{note} +Even when a prefixed signed message contains multiple signature packets, each signature packet contains an independent signature of just the message payload. Signatures do not include subsequent signatures in their hashes, every signature is only over the raw payload data of the message. +``` + +#### Format is inefficient for the signer + +For verification, this format is equally convenient as the one-pass signed message form. However, when a signer creates a {term}`prefixed signed message`, the signed data must be processed twice: