vanitasvitae/openpgp-notes
1
0
Fork 0
mirror of https://codeberg.org/openpgp/notes.git synced 2024-11-30 03:22:06 +01:00
Code Issues Projects Releases Packages Wiki Activity

Merge branch 'tammi-ch7' into heiko-ch7

Browse source 
# Conflicts:
#	book/source/07-signing_data.md
This commit is contained in:
Heiko Schaefer 2023-11-13 23:54:32 +01:00
commit 6db0a1f841
No known key found for this signature in database
GPG key ID: DAE9A9050FCCF1EB
1 changed files with 32 additions and 35 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

67
book/source/07-signing_data.md
View file

@ -15,7 +15,7 @@ it does not automatically signal if the expected party indeed controls the signe
Data signatures can only be issued by component keys with the *signing* [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags).
Note that signatures over data are distinct from {ref}`component_signatures_chapter`, which are used to attach metadata or subkeys to a certificate.
Note that data signatures are distinct from {ref}`component_signatures_chapter`, which are used to attach metadata or subkeys to a certificate.
(data_signature_types)=
## Signature types
@ -31,39 +31,42 @@ Data signature packets manifest in three distinct forms, which will be detailed
## Forms of OpenPGP data signatures
OpenPGP signatures over data can be used in three different forms[^sign-modes-gpg]:
OpenPGP data signatures can be applied in three distinct forms[^sign-modes-gpg]:
- *Detached*: The signature is a standalone artifact, separate from the signed data.
- *Inline*: The original data and the signature over data are enclosed within an OpenPGP container.
- *Cleartext signature*: A plaintext message and a signature over this message are stored in a combined text-format, maintaining the original message's readability.
- **Detached**: The OpenPGP signature exists as a separate entity, independent from the signed data.
- **Inline**: Both the original data and its corresponding OpenPGP signature are encapsulated within an OpenPGP container.
- **Cleartext signature**: A plaintext message and its OpenPGP signature coexist in a combined text format, preserving the readability of the original message.
[^sign-modes-gpg]: These three signature forms correspond with GnuPG's `--detach-sign`, `--sign` and `--clear-sign` modes.
[^sign-modes-gpg]: These three forms of signature application align with GnuPG's `--detach-sign`, `--sign`, and `--clearsign` command options.
### Detached signatures
A detached signature is produced by calculating an OpenPGP signature over the signed data. The original data is left as is, while the OpenPGP signature is stored as a standalone file. A detached signature can be distributed alongside or independent of the original data. The authenticity and integrity of the original data file can be verified using the detached signature file.
A detached signature is produced by calculating an OpenPGP signature over the data intended for signing. The original data remains unchanged, and the OpenPGP signature is stored as a standalone file. A detached signature file can be distributed alongside or independent of the original data. The authenticity and integrity of the original data file can be verified by using the detached signature file.
This signature format is especially useful for signing software releases and other files that must not be modified by the signing process.
This 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 signatures
An inline signature joins the signed data and a signature over this data into one combined OpenPGP message.
An inline signature joins the signed data and its corresponding data signature into a single OpenPGP message.
This method is usually used with signed and/or encrypted emails. Most software that supports OpenPGP for encrypted and/or signed messages uses inline-signatures.
This method is commonly used for signing or encrypting emails. Most email software capable of handling OpenPGP communications typically uses inline signatures.
#### Structure
An inline-signed OpenPGP message consists of three segments:
- One or more [One-Pass Signature packets](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#one-pass-sig),
- the original data, wrapped in a [Literal Data packet](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#lit),
- the corresponding Data Signature packets.
1. **One-pass signature packets**: These one or more packets precede the signed data and enable signature computation in one pass. See[One-Pass Signature Packet (Type ID 4)](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#one-pass-sig) of the RFC.
2. **Literal data**: This is the original data (e.g., the body of a message) that the user wishes to encrypt or sign, without additional interpretation or conversion. [Literal Data Packet (Type ID 11)](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#lit).
3. **Data signature packets**: These contain the cryptographic signature corresponding to the original data.
#### Creation
To produce an inline signature, the signer processes the entirety of the data by reading from an input file and writing into am output OpenPGP message file. The signer calculates a cryptographic signature over the course of this process. Therefore, an efficient signer can only emit the resulting data signature packet at the end of this process, and thus store it at the end of the data stream.
To produce an inline signature, the signer processes the entirety of the data by reading from an input file and writing into am output OpenPGP message file. As the data is processed, the signer simultaneously calculates a cryptographic signature. This procedure results in a data signature packet being appended to the output OpenPGP message file, an essential step for efficient signing.
On the other hand, an efficient verifying application needs to know how to process the literal data before reading it. This is the purpose of the so-called One-Pass Signature packets in the first segment of inline-signed messages. One-Pass Signature packets contain the fingerprint of the signing key, as well as the hash algorithm used to calculate the hash digest for the signature.
For efficient verification, an application must understand how to handle the literal data prior to its reading. This requirement is addressed by the One-Pass Signature packets located at the beginning of inline-signed messages. These packets include essential information such as the fingerprint of the signing key and the hash algorithm used for computing the signature's hash digest. This setup enables the verifier to process the data correctly and efficiently.
```{admonition} TODO
:class: warning
@ -73,24 +76,26 @@ Is the signer keyid/fingerprint in the OPS important for the verifier to be able
#### Verification
This structure allows verifying applications to verify inline-signed messages in *one pass*:
Inline-signed messages enable efficient verification in *one pass*, structured as follows:
- The One-Pass Signature packets initiate the verification process,
- the literal data can then be processed (which means: it gets hashed),
- the signature packets at the end of the message can be verified against the hash digest that the previous step calculated.
1. **Initiation with One-Pass Signature packets**: These packets begin the verification process. They include the signer's key ID/fingerprint, essential for identifying the appropriate public key for signature validation.
Note that the final step of verifying the cryptographic signature requires access to the signer's public key material. This public key material is not included in the signed message. The verifier must obtain the signer's public key data out-of-band (e.g. by obtaining the signer's certificate from a key server).
2. **Processing the literal data**: This step involves hashing the literal data, preparing it for signature verification.
3. **Verifying signature packets**: Located at the end of the message, these packets are checked against the previously calculated hash digest.
Important to note, the signer's public key, critical for the final verification step, is not embedded in the message. Verifiers must acquire this key externally (e.g., from a key server) to authenticate the signature successfully.
### Cleartext signatures
The *Cleartext Signature Framework* (CSF) is an OpenPGP mechanism that combines two goals:
The *Cleartext Signature Framework* (CSF) in OpenPGP accomplishes two primary objectives:
- It leaves the message in clear text format, so that it can be viewed directly by a human in a program that knows nothing about OpenPGP.
- At the same time, it adds an OpenPGP signature that allows verification of that message by users whose software supports OpenPGP.
- maintaining the message in a human-readable cleartext format, accessible without OpenPGP-specific software
- incorporating an OpenPGP signature for authentication by users with OpenPGP-compatible software
#### Example
In {numref}`cleartext` we inspect an example of a cleartext signature in detail. Let's have a brief look at this example, here, to get a sense of what a cleartext signature looks like:
Below is a detailed example of a {numref}`cleartext` signature:
```text
-----BEGIN PGP SIGNED MESSAGE-----
@ -107,13 +112,9 @@ r13/eqMN8kfCDw==
-----END PGP SIGNATURE-----
```
A cleartext signature consists of two blocks. These blocks contain the message and a signature, respectively. In this case, the message consists of the text `hello world`.
This signature is split into two parts: a message ("hello world") and an ASCII-armored OpenPGP signature. The message is immediately comprehensible to a human reader, while the signature block allows for the message's authenticity verification via OpenPGP software.
Notice that the message in the first block is readable by a human reader, without requiring additional software tools, as long as the reader knows where to look, and which elements to ignore.
The second block contains an ASCII-armored OpenPGP signature for the message. Using this signature, OpenPGP software can verify the authenticity of the message.
#### Use-cases
#### Use case
Clear text signatures combine two of the benefits of detached and inline-signatures:
@ -132,14 +133,10 @@ Additionally, as usual for [text signatures](data_signature_types), the signatur
#### Pitfalls
Cleartext signatures are popular and have useful applications.
At the same time, they are considered a "legacy method"[^csf-gnupg] by some.
While widely used, cleartext signatures are sometimes considered a "legacy method"[^csf-gnupg]. The RFC outlines [pitfalls of cleartext signatures](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-issues-with-the-cleartext-s) and advises that inline and detached signature forms are often preferable.
[^csf-gnupg]: https://lists.gnupg.org/pipermail/gnupg-devel/2023-November/035428.html
The RFC points out a number of specific [pitfalls of cleartext signatures](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-issues-with-the-cleartext-s), and how to avoid them. It advises that in many cases, the inline and detached signature forms are preferable.
## Advanced topics
### Nesting of one-pass signatures