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

ch7: merge in old text, edits

Browse source
This commit is contained in:
Heiko Schaefer 2023-10-29 18:16:20 +01:00
parent 3ec73a8549
commit 3f536dfaaa
No known key found for this signature in database
GPG key ID: 4A849A1904CCBD7D
1 changed files with 43 additions and 46 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -6,40 +6,56 @@ SPDX-License-Identifier: CC-BY-SA-4.0
(signing_data)=
# Signatures over data
One major use of OpenPGP is to create signatures over various pieces of data, for example software packages or emails.
Contrary to alternative solutions like [signify](https://flak.tedunangst.com/post/signify), OpenPGP offers the advantage of allowing for strong authetication due to the binding between certificates and entities.
A data signature guarantees the authenticity (and implicitly also the integrity) of a message, e.g., an email or a file.
Note that signatures over data are different from {ref}`component_signatures_chapter`, which are used to attach metadata or subkeys to a certificate.
One major use case for OpenPGP is to create signatures for software packages or emails. These are examples for signatures over data, with OpenPGP.
When signing data, OpenPGP offers the advantage that it comes with mechanisms for strong authentication, based on bindings between certificates and identities, and the option to certify those bindings.
Other signing solutions, like [signify](https://flak.tedunangst.com/post/signify), typically only offer a solution for pure signing, without offering
a mechanism for authentication.
## Signature types
There are two signature types which are relevant for data signatures:
* 0x00: *Binary Signature* is a universal signature type for binary data. This signature type is typically used for files or data streams.
Two OpenPGP [signature types](signature_types) apply to data signatures:
- Signature of a binary document (*Binary Signature*, type ID `0x00`): a universal signature type for binary data. This signature type is typically used for files or data streams.
Binary signatures are calculated over the data "as is", without performing any transformations.
* 0x01: *Text Signature* is used for textual data, such as email bodies.
To calculate a text signature, the data is first transformed by converting line endings into a canonical form (<CR><LF>).
This is done to mitigate issues caused by platform-specific default text encodings.
- Signature of a canonical text document (*Text Signature*, type ID `0x01`): used for textual data, such as email bodies. When calculating a text signature, the data is first normalized by converting line endings into a canonical form (`<CR><LF>`). This normalization mitigates issues caused by platform-specific default text encodings.
(This can be useful for detached signatures, when the message file may get re-encoded between signature generation and validation)
## Signature schemes
Data signatures are always calculated by a component key that carries the *signing* key flag.
Historically, OpenPGP offers different schemes for signing data:
Data signatures are created by hashing the message content and calculating a cryptographic signature over the hash.
The resulting cryptographic signature is stored in an OpenPGP signature packet, which can be used in different ways:
* *Detached signatures* can be distributed alongside the unaltered data that is being signed.
This method is especially useful for signing software releases and other files that must not be modified by the signing process.
* Inline-signatures using so called One-Pass-Signature packets embed the signed data in an OpenPGP artifact.
This method is usually used with signed and/or encrypted emails.
* The *Cleartext Signature Framework* (CSF) is a deprecated method of signing text, which leaves the original message in a human-readable format.
This method is often used in scenarios where recipient clients might not offer OpenPGP support.
## Forms of OpenPGP data signatures
OpenPGP signatures over data can be generated and distributed in three forms[^sign-modes-gpg]:
- *Detached*: The signature is a standalone artifact, separate from the signed data.
- *Inline*: The original data and the signature over the data are stored in an OpenPGP container.
- *Cleartext signature*: A method to sign text while leaving the original message in a human-readable format.
[^sign-modes-gpg]: These signature forms correspond with GnuPG's `--detach-sign`, `--sign` and `--clear-sign` modes.
### Detached signatures
A detached signature is produced by calculating an OpenPGP signature over a piece of data.
The resulting OpenPGP signature packet can then be distributed alongside the original data.
The resulting OpenPGP signature packet can then be distributed alongside or independent of the original data.
### Inline-signatures
This method is especially useful for signing software releases and other files that must not be modified by the signing process.
### Inline signatures
This method is usually used with signed and/or encrypted emails.
Most clients that support OpenPGP for encrypted and/or signed messages make use of inline-signatures.
To produce a signature, the entirety of the data needs to be processed by the producer. This has the consequence, that an application that efficiently emits signed data, can only append the signature at the end of the data stream.
On the other hand, an application that needs to efficiently verify signed data needs to know the signers public key and used hash algorithm before processing the data.
To solve this issue, One-Pass-Signature packets are prefixed to the signed data. Those are small packets containing the fingerprint of the signing key, as well as the used hash algorithm. This is all the information a receiving application needs to know in order to initiate the verification process.
To produce a signature, the entirety of the data needs to be processed by the producer. This has the consequence that an application that efficiently emits signed data can only append the signature at the end of the data stream.
On the other hand, an application that needs to efficiently verify signed data needs to know the signer's public key and used hash algorithm before processing the data.
To solve this issue, so-called One-Pass-Signature packets are prefixed to the signed data. Those are small packets containing the fingerprint of the signing key, as well as the used hash algorithm. This is all the information a receiving application needs to know to initiate the verification process.
To produce an inline-signed message, the original data is first wrapped in a Literal Data packet, which is prefixed with one or more One-Pass-Signature packets, and affixed with the corresponding signature packets.
The verifying application can read the One-Pass-Signature packets and initiate the verification process.
@ -47,34 +63,15 @@ The literal data can then be processed, such that the signatures at the end of t
TODO: explain nesting of OPSs.
```{admonition} TODO
:class: warning
### Cleartext signatures
Add content, including:
The *Cleartext Signature Framework* (CSF) is a mechanism that combines two goals:
- Signature of a binary document
- 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.
- But also adds an OpenPGP signature that allows verification of that message by users whose software supports OpenPGP.
- Signature of a canonical text document
- "The signature is calculated over the text data with its line endings converted to `<CR><LF>`"
TODO: explain text transforms for cleartext signatures (LF->CRLF etc)
data signatures have three forms:
- detached,
- inline (that is signature contains the data which is signed inside of a signature container) and
- cleartext which I guess will be special-cased in v6 (to require small text etc).
#### Pitfalls
(This corresponds to gnupg's --detach-sign --sign and --clear-sign)
cleartext: explain text transforms for cleartext signatures (LF->CRLF etc)
```
## Data signatures
A data signature serves the purpose to cryptographically guarantee the authenticity (and implicitly also the integrity) of a message, e.g. an email or a file, while a certification is used to attach metadata or subkeys to a certificate.
Data signatures are always calculated by keys carrying the **S**igning key flag.
Different types of signatures are distinguished by a signature type code and are calculated in different ways.
Signatures can either be distributed standalone as *detached* signatures, or can be inlined with OpenPGP data, such as an OpenPGP message or a key or certificate.
Data signatures (type 0x00 and 0x01) are created by hashing the message content and calculating a cryptographic signature over the hash.
You can read more about data signatures in the [next chapter](signing_data).
The result is packed up into an OpenPGP signature packet, which can either be included in the OpenPGP message (TODO: See section about forming messages, cleartext signature framework), or distributed separately as a so-called *detached* signature.
Data signatures are always calculated using a **S**igning key.
The RFC points out a number of [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 in many cases, the inline and detached signature forms are preferable.