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

Progress

Browse source
This commit is contained in:
Paul Schaub 2023-10-03 11:26:28 +02:00 committed by Heiko Schaefer
parent c80678e8f1
commit be5fff67ab
No known key found for this signature in database
GPG key ID: 4A849A1904CCBD7D
1 changed files with 57 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

60
book/source/06-certifications.md
View file

@ -12,7 +12,7 @@ They act as the syntax that allows forming and interpreting complex statements a
Without signatures there would only be loose keys, impossible to associate with their owner. Without signatures there would only be loose keys, impossible to associate with their owner.
Signatures are the glue that allows for keys, subkeys and identities to be assembled into hierarchical certificates and for messages to gain authenticity. Signatures are the glue that allows for keys, subkeys and identities to be assembled into hierarchical certificates and for messages to gain authenticity.
```{admonition} TODO ```{admonition}
:class: warning :class: warning
- Purpose of a signature - Purpose of a signature
@ -30,15 +30,21 @@ For the purpose of this document, the term signature will refer to an OpenPGP si
OpenPGP signatures can be separated into *data signatures* and *certifications*. OpenPGP signatures can be separated into *data signatures* and *certifications*.
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. 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, while certifications require keys carrying the **C**ertify Others key flag (with the exception of so called Primary Key Binding Signatures). 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. 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. 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. 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. 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. Data signatures are always calculated using a **S**igning key.
Certifications are separated into *self-certifications* and *third-party certifications*.
A certification made by a key over components of the same certificate is referred to as a *self-certification*. A certification made by a key over components of the same certificate is referred to as a *self-certification*.
:::{note}
The **C**certify Others key flag is not required in order to issue self-certifications.
It is only necessary to issue valid third-party certifications.
:::
A typical use-case for a self-certification is to attach a user ID, such as a name and email address to a certificate. A typical use-case for a self-certification is to attach a user ID, such as a name and email address to a certificate.
This is done by calculating the signature over the user ID and the public primary key. This is done by calculating the signature over the user ID and the public primary key.
The resulting user ID certification (typically type 0x13, potentially type 0x10-0x12) can then be inserted into the certificate, right after the user ID packet. The resulting user ID certification (typically type 0x13, potentially type 0x10-0x12) can then be inserted into the certificate, right after the user ID packet.
@ -84,6 +90,54 @@ By marking the expiration date subpacket as critical, the user can indicate, tha
Sections 5.2.3.11 - 5.2.3.36 give guidance on which subpackets are usually marked as critical. Sections 5.2.3.11 - 5.2.3.36 give guidance on which subpackets are usually marked as critical.
### Certification Recipes
As mentioned above, different signatures are used for different purposes.
In this section, we will try to give guidance on how to create certain signatures by example.
#### Change Algorithm Preferences
In order to change what symmetric, compression, hash or AEAD algorithms are preferred by the key owner, they can issue a direct-key signature (type 0x1F) on the primary key.
This signature should have the following structure:
| Subpacket | Area | Critical | Mandatory | Notes |
|-----------|------|----------|-----------|-------|
| Signature Creation Time | Hashed | True | True | Current time |
| Issuer Fingerprint | Hashed | True or false | Strongly recommended | The primary key is the issuer |
| Key Flags | Hashed | True | False | Carry over key flags from previous self-signature |
| Features | Hashed | True | False | Carry over features from previous self-signature |
| Key Expiration Time | Hashed | True | False | Carry over expiration time from previous self-signature, if present |
| Hash Alg. Pref. | Hashed | False | False | New preferences |
| Comp. Alg. Pref. | Hashed | False | False | New preferences |
| Symm. Alg. Pref. | Hashed | False | False | New preferences |
| AEAD Alg. Pref. | Hashed | False | False | New preferences |
#### Add User ID
To add (or re-bind) a User ID to a certificate, a signature of type `PositiveCertification` (0x13) is calculated over the primary key and User ID.
The signature should have the following structure:
| Subpacket | Area | Critical | Mandatory | Notes |
|-----------|------|----------|-----------|-------|
| Signature Creation Time | Hashed | True | True | Current time |
| Issuer Fingerprint | Hashed | True or false | Strongly Recommended | The primary key is the issuer |
| Primary User ID | Hashed | True | False | Optional |
| Signature Expiration Time | Hashed | True | False | Optional |
Self-certifications over User IDs can optionally carry the same subpackets as listed in the previous table (key flags, features, algorithm preferences).
This way, separate capabilities can be assigned to different identities.
#### Common Subpackets
There are some subpackets that are expected to be included in any type of signature.
* **Signature Creation Time**: Every OpenPGP signature MUST contain a Signature Creation Time subpacket (2) containing the timestamp at which the signature was made. This packet MUST be present in the hashed area of the signature and SHOULD be marked as critical.
* **Issuer Fingerprint**: In order to be able to verify a signature, the verifier needs to know, which (sub-)key was used to issue the signature in the first place. Therefore, every OpenPGP v6 signature SHOULD contain an Issuer Fingerprint subpacket (33) containing the 32 byte fingerprint of the particular component key that was used to create the signature.
:::{note}
The issuer key might be a subkey.
:::
Since the issuer fingerprint subpacket is self-authenticating, it can either be included as a hashed or unhashed subpacket, but the authors of this book recommend to place it in the hashed area of the signature.
### Potential conflicts and duplication ### Potential conflicts and duplication
Since the hashed and unhashed areas of a signature are just lists of subpackets, in principle they allow duplicates of the same subpacket, which might lead to conflicts. Since the hashed and unhashed areas of a signature are just lists of subpackets, in principle they allow duplicates of the same subpacket, which might lead to conflicts.
@ -95,7 +149,7 @@ In some cases, duplicate packets with conflicting content even make sense, e.g.
In this case, either the v3 or v4 key could be used to validate the v4 signature, but since the key ID calculation scheme was changed between v3 and v4, these identifiers would differ. In this case, either the v3 or v4 key could be used to validate the v4 signature, but since the key ID calculation scheme was changed between v3 and v4, these identifiers would differ.
Therefore, the signature could contain two isuer key ID subpackets with conflicting, but correct values. Therefore, the signature could contain two isuer key ID subpackets with conflicting, but correct values.
```{admonition} TODO ```{admonition}
:class: warning :class: warning
- Key Flags - Key Flags