From ecf0bc1c7b49fa8976d2671a80b6a0d21ac3940d Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Fri, 22 Dec 2023 19:39:04 +0100 Subject: [PATCH] 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