vanitasvitae/openpgp-notes
1
0
Fork 0
mirror of https://codeberg.org/openpgp/notes.git synced 2025-12-05 05:01:07 +01:00
Code Issues Projects Releases Packages Wiki Activity

Update all "deep" RFC links to point into RFC 9580

Browse source 
Also checked and fixed all changed anchor names
This commit is contained in:
Heiko Schaefer 2025-10-19 14:59:03 +02:00
parent f37374bc44
commit 9e1ba07748
No known key found for this signature in database
GPG key ID: DAE9A9050FCCF1EB
22 changed files with 196 additions and 196 deletions
Download patch file Download diff file Expand all files Collapse all files

10
book/source/adv/certificates.md
View file

@ -31,7 +31,7 @@ Using the expiration mechanism is useful for two reasons:
- Expiration of a certificate means that it cannot be used anymore. This forces users of that certificate (or their OpenPGP software) to poll for updates for it. For example, from a keyserver.
- It is a passive way for certificates to "time out," e.g., if their owner loses control over them, or isn't able to broadcast a revocation, for any reason.
Component keys use *Key Expiration Time* subpackets for expressing the expiration time. Identity components rely on the [*signature expiration time*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#signature-expiration-subpacket) subpacket of their binding signature. If a binding signature expires, the binding becomes invalid, and the component is considered expired.
Component keys use *Key Expiration Time* subpackets for expressing the expiration time. Identity components rely on the [*signature expiration time*](https://www.rfc-editor.org/rfc/rfc9580.html#signature-expiration-subpacket) subpacket of their binding signature. If a binding signature expires, the binding becomes invalid, and the component is considered expired.
### Revocation
@ -41,7 +41,7 @@ Each component, such as User ID and a subkey, can be revoked without affecting t
The *primary User ID* is an exception: when it is revoked, the entire certificate is considered invalid.
Revoking the primary key with a [*Key revocation signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-revocation-signature-ty) (type ID `0x20`) also marks the entire certificate, including all of its components, as invalid and unusable.
Revoking the primary key with a [*Key revocation signature*](https://www.rfc-editor.org/rfc/rfc9580.html#name-key-revocation-signature-ty) (type ID `0x20`) also marks the entire certificate, including all of its components, as invalid and unusable.
### Semantics of Revocations
@ -49,7 +49,7 @@ In contrast to expiration, revocation is typically final and not withdrawn[^undo
[^undo-revocations]: While some revocations can be reverted, undoing revocations is an uncommon workflow. Unlike expirations, which are commonly undone by extending the expiration time.
A revocation indicates that the component should not be used. Revocation signatures over components use a [*Reason for Revocation*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#reason-for-revocation) subpacket to specify further details about the reason why the component or certification was revoked. The OpenPGP format specifies a set of distinct [values for *Reasons for Revocation*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#table-10), and additionally provides space for a human-readable free text field for comments about the revocation.
A revocation indicates that the component should not be used. Revocation signatures over components use a [*Reason for Revocation*](https://www.rfc-editor.org/rfc/rfc9580.html#reason-for-revocation) subpacket to specify further details about the reason why the component or certification was revoked. The OpenPGP format specifies a set of distinct [values for *Reasons for Revocation*](https://www.rfc-editor.org/rfc/rfc9580.html#table-10), and additionally provides space for a human-readable free text field for comments about the revocation.
Some libraries, such as Sequoia PGP, expose these distinct reasons for users, enabling nuanced machine-readable statements by the revoker. Other implementations focus mainly on the distinction between "hard" and "soft" revocations.
@ -253,7 +253,7 @@ required users to manually compare the 40 character long hexadecimal representat
### Fingerprints in Version 6
The OpenPGP version 6 standard uses 32 byte (256 bit) fingerprints, but explicitly defines no format for displaying those fingerprints in a human-readable form. The standard [recommends strongly against](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-fingerprint-usability) using version 6 fingerprints as identifiers in user-facing workflows.
The OpenPGP version 6 standard uses 32 byte (256 bit) fingerprints, but explicitly defines no format for displaying those fingerprints in a human-readable form. The standard [recommends strongly against](https://www.rfc-editor.org/rfc/rfc9580.html#name-fingerprint-usability) using version 6 fingerprints as identifiers in user-facing workflows.
Instead, "mechanical fingerprint transfer and comparison" should be preferred, wherever possible. The reasoning is that humans tend to be bad at comparing high-entropy data[^schuermann] (in addition, many users are probably put off by being asked to compare long hexadecimal strings).
@ -317,7 +317,7 @@ Some OpenPGP software may add User IDs to a certificate, which are not bound to
[PET]: https://sequoia-pgp.org/blog/2023/04/08/sequoia-sq/#an-address-book-style-trust-model
Sequoia additionally certifies these "local, third party, User IDs" with a local trust anchor to facilitate local authentication decisions.
To prevent accidental publication of these local User IDs (e.g. to public keyservers), Sequoia marks these binding signatures as "local" artifacts using [Exportable Certification](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-exportable-certification) subpackets to mark them as non-exportable.
To prevent accidental publication of these local User IDs (e.g. to public keyservers), Sequoia marks these binding signatures as "local" artifacts using [Exportable Certification](https://www.rfc-editor.org/rfc/rfc9580.html#name-exportable-certification) subpackets to mark them as non-exportable.
(certificate-distribution)=
## Certificate distribution mechanisms

2
book/source/adv/decryption.md
View file

@ -14,7 +14,7 @@ During decrypting, these 2 bytes can be compared to the 15th and 16th random byt
Since the chance to accidentally end up with matching quick check bytes albeit the use of the wrong session key is 1:65536, some implementations validate further contents of the plaintext, such as the packet headers.
The standard [warns against](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-risks-of-a-quick-check-orac) using the quick check mechanism, as it introduces the risk of a decryption oracle. Instead, the use of SEIPDv2 is recommended, as the AEAD mechanism automatically detects use of the wrong session key early on after the first chunk has been decrypted.
The standard [warns against](https://www.rfc-editor.org/rfc/rfc9580.html#name-risks-of-a-quick-check-orac) using the quick check mechanism, as it introduces the risk of a decryption oracle. Instead, the use of SEIPDv2 is recommended, as the AEAD mechanism automatically detects use of the wrong session key early on after the first chunk has been decrypted.
(decryption-anonymous-recipient)=
## Anonymous recipients

6
book/source/adv/private_keys.md
View file

@ -15,7 +15,7 @@ This section examines the diverse architectures and operational mechanics of pri
The design of private key subsystems within the OpenPGP framework varies, offering different approaches to cryptographic operations:
1. **Separate backend operations**: Some designs execute the primitive cryptographic operations in a separate backend, using only the cryptographic key material. This approach is particularly compatible with general purpose hardware cryptographic devices, such as [trusted platform modules (TPMs)](https://en.wikipedia.org/wiki/Trusted_Platform_Module).
2. **Component key-based systems**: An OpenPGP private key subsystem may be built around component keys, specifically the content of [Secret-Key packets](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-secret-key-packet-formats). These packets contain metadata that is required for some operations. ECDH operations, in particular, require metadata as KDF parameters.
2. **Component key-based systems**: An OpenPGP private key subsystem may be built around component keys, specifically the content of [Secret-Key packets](https://www.rfc-editor.org/rfc/rfc9580.html#name-secret-key-packet-formats). These packets contain metadata that is required for some operations. ECDH operations, in particular, require metadata as KDF parameters.
3. **Full transferable secret keys**: Some designs maintain copies of full TSKs in the private key subsystem, leveraging these for private key operations.
While private keystore operations require component keys, they do not require access to the entire OpenPGP certificate.
@ -40,7 +40,7 @@ When implementing a keystore based on hardware cryptographic devices like [OpenP
- **supplementary layer**: performs additional cryptographic operations that don't directly use the private key material, such as [AES key wrap](https://www.rfc-editor.org/rfc/rfc3394.html) for ECDH.
```{note}
The decryption process using ECC algorithms, especially ECDH, has multiple steps. The initial step, potentially performed by devices such as OpenPGP cards, directly uses private key material to produce a "shared secret." Following this, operations like ["AES key unwrap"](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-ec-dh-algorithm-ecdh) are conducted in software outside the hardware device.
The decryption process using ECC algorithms, especially ECDH, has multiple steps. The initial step, potentially performed by devices such as OpenPGP cards, directly uses private key material to produce a "shared secret." Following this, operations like ["AES key unwrap"](https://www.rfc-editor.org/rfc/rfc9580.html#name-ecdh-algorithm) are conducted in software outside the hardware device.
Further details on this process can be found in the "Advanced Encryption Standard (AES) Key Wrap Algorithm" [RFC 3394](https://www.rfc-editor.org/rfc/rfc3394.html).
```
@ -73,7 +73,7 @@ Importantly, KO attacks are particularly relevant in scenarios where an attacker
Understanding KO attacks is crucial due to their potential to compromise the integrity and confidentiality of encrypted communications, and the risk of complete private key material compromise. KO attacks highlight the necessity for robust key validation procedures and the dangers of storing keys in insecure environments. OpenPGP application developers should conduct a risk assessment to determine the relevance of KO attacks to their applications.
Private keys secured with [S2K usage mode 253 (AEAD)](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-secret-key-encryption) are safeguarded against KO attacks. This mode ensures the integrity of the private key by using its unencrypted fields, including the algorithm field, as the *authentication tag* for integrity verification in the decryption process.
Private keys secured with [S2K usage mode 253 (AEAD)](https://www.rfc-editor.org/rfc/rfc9580.html#name-secret-key-encryption) are safeguarded against KO attacks. This mode ensures the integrity of the private key by using its unencrypted fields, including the algorithm field, as the *authentication tag* for integrity verification in the decryption process.
When an attacker alters the unencrypted part of the Secret-Key packet, then decryption of the private key material will fail. This effectively prevents the user from unknowingly using the key material with an altered attacker-controlled algorithm.

6
book/source/adv/signatures.md
View file

@ -8,7 +8,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0
(notation-signature-subpackets)=
## Notation signature subpackets
[Notation signature subpackets](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#notation-data) can be used to effectively extend the otherwise limited set of {term}`signature subpacket types<OpenPGP Signature Subpacket Type>` in OpenPGP with user-defined {term}`notations<Notation>`. {term}`Issuers<Issuer>` can use these {term}`notations<Notation>` to add name-value pairs to an {term}`OpenPGP signature<OpenPGP Signature Packet>`.
[Notation signature subpackets](https://www.rfc-editor.org/rfc/rfc9580.html#notation-data) can be used to effectively extend the otherwise limited set of {term}`signature subpacket types<OpenPGP Signature Subpacket Type>` in OpenPGP with user-defined {term}`notations<Notation>`. {term}`Issuers<Issuer>` can use these {term}`notations<Notation>` to add name-value pairs to an {term}`OpenPGP signature<OpenPGP Signature Packet>`.
{term}`Notation` names - strings encoded in UTF-8 - may reside in the "user namespace." This namespace is characterized by a {term}`notation tag`, followed by a DNS domain name, both in UTF-8 format.
@ -35,7 +35,7 @@ In such cases, where there isn't a specific recipient in mind, the issuer of the
### Specific signature context, recipient-driven choice
When a message is being prepared for a particular recipient, the selection of the hash algorithm for the signature packet should be guided by [the recipient's hash algorithm preference](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-hash-algorithm-preferences).
When a message is being prepared for a particular recipient, the selection of the hash algorithm for the signature packet should be guided by [the recipient's hash algorithm preference](https://www.rfc-editor.org/rfc/rfc9580.html#name-hash-algorithm-preferences).
The recipient's hash algorithm preference is defined in the metadata of their OpenPGP certificate. See {ref}`preferences-features` for more details.
@ -43,7 +43,7 @@ In this workflow, the signed hash digest is created with a hash algorithm repres
## Signature versions
As described in the [RFC](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-signature-packet-type-id-2), the version of a generated signature packet must conform to the version of the key that issues the signature.
As described in the [RFC](https://www.rfc-editor.org/rfc/rfc9580.html#name-signature-packet-type-id-2), the version of a generated signature packet must conform to the version of the key that issues the signature.
That is:

6
book/source/adv/signing_components.md
View file

@ -100,7 +100,7 @@ The structure of such a {term}`signature<OpenPGP Signature Packet>` is straightf
| {term}`Reason for Revocation<Reason For Revocation Subpacket>` | {term}`Hashed<Hashed Area>` | True | False | Determines {term}`soft<Soft Revocation>` or {term}`hard revocation` |
In {term}`Subkey Revocation signatures<Subkey Revocation Signature Packet>`, the [reason for revocation](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-reason-for-revocation) {term}`subpacket<OpenPGP Signature Subpacket>` can only have values in the range of `0-3`. The values `1` ({term}`key<OpenPGP Subkey>` superseded) and `3` ({term}`key<OpenPGP Subkey>` retired and no longer used) indicate {term}`soft revocations<Soft Revocation>`, whereas values `0` (no reason) and `2` ({term}`key<OpenPGP Subkey>` compromised) indicate {term}`hard revocations<Hard Revocation>`.
In {term}`Subkey Revocation signatures<Subkey Revocation Signature Packet>`, the [reason for revocation](https://www.rfc-editor.org/rfc/rfc9580.html#name-reason-for-revocation) {term}`subpacket<OpenPGP Signature Subpacket>` can only have values in the range of `0-3`. The values `1` ({term}`key<OpenPGP Subkey>` superseded) and `3` ({term}`key<OpenPGP Subkey>` retired and no longer used) indicate {term}`soft revocations<Soft Revocation>`, whereas values `0` (no reason) and `2` ({term}`key<OpenPGP Subkey>` compromised) indicate {term}`hard revocations<Hard Revocation>`.
Note that a value of `32` is not applicable in these {term}`signatures<OpenPGP Signature Packet>`.
@ -118,7 +118,7 @@ The recommended way to {term}`revoke<Revocation>` a {term}`certificate<OpenPGP C
| {term}`Issuer Fingerprint<Issuer Fingerprint Subpacket>` | {term}`Hashed<Hashed Area>` | True or False | Strongly Recommended | The {term}`primary key<OpenPGP Primary Key>` is the {term}`issuer` |
| {term}`Reason for Revocation<Reason For Revocation Subpacket>` | {term}`Hashed<Hashed Area>` | True | False | Determines {term}`soft<Soft Revocation>` or {term}`hard revocation` |
For {term}`Key Revocation signatures<Key Revocation Signature Packet>`, the guidelines regarding the [*Reason for Revocation* subpacket](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-reason-for-revocation) are the same as those for {term}`Subkey Revocation signatures<Subkey Revocation Signature Packet>`.
For {term}`Key Revocation signatures<Key Revocation Signature Packet>`, the guidelines regarding the [*Reason for Revocation* subpacket](https://www.rfc-editor.org/rfc/rfc9580.html#name-reason-for-revocation) are the same as those for {term}`Subkey Revocation signatures<Subkey Revocation Signature Packet>`.
### Common subpackets in OpenPGP signatures
@ -140,6 +140,6 @@ In {term}`OpenPGP signatures<OpenPGP Signature Packet>`, both the {term}`hashed<
- **Precedence of {term}`hashed area`**: {term}`Subpackets<OpenPGP Signature Subpacket>` within the {term}`hashed area` of a {term}`signature<OpenPGP Signature Packet>` take precedence over those in the {term}`unhashed area`. This hierarchy helps resolve conflicts when the same {term}`subpacket<OpenPGP Signature Subpacket>` appears in both areas.
- **Handling conflicts within the same area**: Conflicts can still arise within the same area, such as when two {term}`subpackets<OpenPGP Signature Subpacket>` have different {term}`expiration times<Expiration Time>`. In such cases, the [OpenPGP specification](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-notes-on-subpackets) advises that {term}`implementations<OpenPGP Implementation>` should favor the last occurrence of a conflicting {term}`subpacket<OpenPGP Signature Subpacket>` in the {term}`hashed area`.
- **Handling conflicts within the same area**: Conflicts can still arise within the same area, such as when two {term}`subpackets<OpenPGP Signature Subpacket>` have different {term}`expiration times<Expiration Time>`. In such cases, the [OpenPGP specification](https://www.rfc-editor.org/rfc/rfc9580.html#name-notes-on-subpackets) advises that {term}`implementations<OpenPGP Implementation>` should favor the last occurrence of a conflicting {term}`subpacket<OpenPGP Signature Subpacket>` in the {term}`hashed area`.
In certain scenarios, having duplicate {term}`subpackets<OpenPGP Signature Subpacket>` with conflicting content is logical and even necessary. For example, consider a {term}`signature<OpenPGP Signature Packet>` created by a version 4 {term}`issuer` {term}`key<Component Key>`, which was upgraded from an older OpenPGP version (like v3). Since the {term}`key ID` calculation scheme changed from v3 to v4, the identifiers for the same {term}`key<Component Key>` would differ between these versions. Therefore, a v4 signature might contain two {term}`issuer key ID subpackets<Issuer Fingerprint Subpacket>`, each with different, yet correct values for v3 and v4 {term}`keys<Component Key>`, respectively. This allows for backward compatibility and ensures the {term}`signature<OpenPGP Signature Packet>` can be {term}`validated<Validation>` under both {term}`key ID` calculation schemes.

6
book/source/adv/signing_data.md
View file

@ -28,7 +28,7 @@ A {term}`one-pass signed<One-pass signed Message>` {term}`OpenPGP message` consi
1. **{term}`One-pass signature packets<One-pass signature packet>`**: These one or more {term}`packets<Packet>` precede the signed data and enable {term}`signature<OpenPGP Signature Packet>` computation (both creation and verification) in a single pass.
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`.
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.rfc-editor.org/rfc/rfc9580.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<OpenPGP Signature Packet>`**: These contain the {term}`cryptographic signature` corresponding to the signed data.
@ -96,7 +96,7 @@ Important to note, the {term}`signer`'s {term}`public key<OpenPGP Certificate>`,
A {term}`one-pass signed message` can actually contain multiple, nested, signatures.
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.
Formally, this is the case because in the [OpenPGP message grammar](https://www.rfc-editor.org/rfc/rfc9580.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.
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.
@ -113,7 +113,7 @@ There are two different use cases and semantics for nested one-pass signatures:
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`.
Issuers of signatures can choose the semantics of their signature, using the ["nested" flag](https://www.rfc-editor.org/rfc/rfc9580.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:

4
book/source/adv/verification.md
View file

@ -10,7 +10,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0
When determining the preferences of a key, several signatures may have to be inspected.
For example, when using a signing subkey to generate a data signature, an implementation might want to check for hash algorithm preferences on the subkey binding signature.
However, the RFC [states](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-5.2.3.10-2) that signature subpackets in a direct key signature (which may also contain preferences) on the OpenPGP certificate's primary key apply to the entire OpenPGP key, and therefore also to the signing subkey.
However, the RFC [states](https://www.rfc-editor.org/rfc/rfc9580.html#section-5.2.3.10-2) that signature subpackets in a direct key signature (which may also contain preferences) on the OpenPGP certificate's primary key apply to the entire OpenPGP key, and therefore also to the signing subkey.
In this case, the implementation uses the preferences from the subkey binding signature, but if no such subpacket is found on the latest binding signature, it falls back to the preferences from the direct key signature.
This is called attribute shadowing, since direct key signature subpackets apply to all subkeys, but are shadowed by binding signature subpackets.
@ -78,7 +78,7 @@ Alternatively, there can be competing qualifying signatures of different types,
[^conflicting-prefs]: However, the semantics of these cases are not currently fully specified, see [this discussion](https://gitlab.com/openpgp-wg/rfc4880bis/-/issues/103).
Depending on how a certificate is "located," different metadata from possible candidate signatures "shadow" one another. The RFC [states](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-notes-on-self-signatures) that when a certificate is "located" by the OpenPGP software "via an identity", then the metadata associated with that identity takes precedence over more global metadata, such as that associated with the certificate's primary key, with a direct key signature.
Depending on how a certificate is "located," different metadata from possible candidate signatures "shadow" one another. The RFC [states](https://www.rfc-editor.org/rfc/rfc9580.html#name-notes-on-self-signatures) that when a certificate is "located" by the OpenPGP software "via an identity", then the metadata associated with that identity takes precedence over more global metadata, such as that associated with the certificate's primary key, with a direct key signature.
For example, the latest direct key signature could list "SHA512, SHA384" as hash algorithm preferences, while the latest self-certification of the User ID "Bob" could list only "SHA256."
For yet another User ID "Bobby," the self-signature could list no hash algorithm preferences at all.

14
book/source/armor.md
View file

@ -13,11 +13,11 @@ However, in many use cases it is customary to use OpenPGP data in a non-binary e
OpenPGP's ASCII armor mechanism consists of:
- An [armor header line](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-armor-header-line)
- Optional [armor headers](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-armor-headers) that can contain additional metadata
- The [base64 encoded](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-base64-conversions) OpenPGP data
- An [optional checksum](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-optional-checksum) for this data
- An [armor tail line](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-armor-tail-line) (or footer) that matches the header line
- An [armor header line](https://www.rfc-editor.org/rfc/rfc9580.html#name-armor-header-line)
- Optional [armor headers](https://www.rfc-editor.org/rfc/rfc9580.html#name-armor-headers) that can contain additional metadata
- The [base64 encoded](https://www.rfc-editor.org/rfc/rfc9580.html#name-base64-conversions) OpenPGP data
- An [optional checksum](https://www.rfc-editor.org/rfc/rfc9580.html#name-optional-checksum) for this data
- An [armor tail line](https://www.rfc-editor.org/rfc/rfc9580.html#name-armor-tail-line) (or footer) that matches the header line
## Example
@ -80,7 +80,7 @@ Both the binary and the ASCII armored format encode exactly the same information
## The cleartext signature framework
One noteworthy mechanism in OpenPGP that uses a specialized variant of ASCII armoring is the [*cleartext signature framework*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#cleartext-signature), which stores an ASCII-armored signature and a cleartext message as a combined text file.
One noteworthy mechanism in OpenPGP that uses a specialized variant of ASCII armoring is the [*cleartext signature framework*](https://www.rfc-editor.org/rfc/rfc9580.html#cleartext-signature), which stores an ASCII-armored signature and a cleartext message as a combined text file.
See our section on the [cleartext signature framework](cleartext-signature) for an example of that format.
@ -90,6 +90,6 @@ See our section on the [cleartext signature framework](cleartext-signature) for
Historically, the ASCII armor mechanism of OpenPGP has specified an (optional) checksum mechanism for the base64 encoded data.
The specification for OpenPGP version 6 [deprecates this mechanism](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-optional-checksum).
The specification for OpenPGP version 6 [deprecates this mechanism](https://www.rfc-editor.org/rfc/rfc9580.html#name-optional-checksum).
Existing CRC24 footers should be ignored, and generating these footers is strongly discouraged, except in cases where interoperability requires it.

26
book/source/certificates.md
View file

@ -68,7 +68,7 @@ An {term}`OpenPGP certificate` usually contains multiple {term}`component keys<O
{term}`OpenPGP component keys<OpenPGP Component Key>` logically consist of an [asymmetric cryptographic keypair](asymmetric-key-pair) and a creation timestamp. Once created, these attributes of a {term}`component key<OpenPGP Component Key>` remain fixed (for ECDH keys, two additional parameters are part of a {term}`component key`'s constitutive data[^ecdh-parameters]).
[^ecdh-parameters]: For [ECDH](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-algorithm-specific-part-for-ecd) {term}`component keys<OpenPGP Component Key>`, two additional algorithm parameters are integral to the {term}`component key<OpenPGP Component Key>`'s constitutive and immutable properties. Those parameters specify a hash function and a {term}`symmetric<Symmetric Cryptography>` encryption algorithm.
[^ecdh-parameters]: For [ECDH](https://www.rfc-editor.org/rfc/rfc9580.html#name-algorithm-specific-part-for-ecd) {term}`component keys<OpenPGP Component Key>`, two additional algorithm parameters are integral to the {term}`component key<OpenPGP Component Key>`'s constitutive and immutable properties. Those parameters specify a hash function and a {term}`symmetric<Symmetric Cryptography>` encryption algorithm.
```{figure} plain_svg/Component_Key.svg
:name: fig-component-key
@ -139,7 +139,7 @@ While {term}`subkeys<OpenPGP Subkey>` have the same structural attributes as the
(user-ids)=
### User IDs in OpenPGP certificates
{term}`OpenPGP certificates<OpenPGP Certificate>` can contain multiple [User IDs](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#uid). Each {term}`User ID` associates the {term}`certificate<OpenPGP Certificate>` with an {term}`identity`.
{term}`OpenPGP certificates<OpenPGP Certificate>` can contain multiple [User IDs](https://www.rfc-editor.org/rfc/rfc9580.html#uid). Each {term}`User ID` associates the {term}`certificate<OpenPGP Certificate>` with an {term}`identity`.
```{figure} plain_svg/Binding_a_UserID.svg
:name: fig-user-ids
@ -165,7 +165,7 @@ Consider this scenario: A third party is confident about the email-based {term}`
(primary-user-id)=
### Implications of the Primary User ID
Within a {term}`certificate<OpenPGP Certificate>`, a specific {term}`User ID` is designated as the [Primary User ID](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-primary-user-id).
Within a {term}`certificate<OpenPGP Certificate>`, a specific {term}`User ID` is designated as the [Primary User ID](https://www.rfc-editor.org/rfc/rfc9580.html#name-primary-user-id).
Each {term}`User ID` carries associated preference settings, such as preferred encryption algorithms, which is detailed in {numref}`zoom-user-id`). When a {term}`certificate<OpenPGP Certificate>` is used in the context of a specific {term}`identity`, then the preferences associated with that {term}`identity component` are used. When a {term}`certificate<OpenPGP Certificate>` is used without reference to a specific {term}`identity`, the preferences associated with the {term}`direct key signature`, or the {term}`primary User ID` take precedence by default.
@ -174,9 +174,9 @@ The {term}`primary User ID` was historically the main store for preferences that
(user-attributes)=
### User attributes in OpenPGP
While
[user attributes](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#user-attribute-packet) are similar to {term}`User IDs<User ID>`, they are less commonly used.
[user attributes](https://www.rfc-editor.org/rfc/rfc9580.html#user-attribute-packet) are similar to {term}`User IDs<User ID>`, they are less commonly used.
Currently, the OpenPGP standard prescribes only one format to be stored in user attributes: an [image](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-the-image-attribute-subpack) in JPEG format. Typically, this image represents the key owner, although it is not required.
Currently, the OpenPGP standard prescribes only one format to be stored in user attributes: an [image](https://www.rfc-editor.org/rfc/rfc9580.html#name-image-attribute-subpacket) in JPEG format. Typically, this image represents the key owner, although it is not required.
## Linking the components
@ -214,7 +214,7 @@ It is crucial to note that the {term}`components<Component>` of an {term}`OpenPG
(key-flags)=
### Defining operational capabilities of component keys with key flags
Each {term}`component key` has a set of ["key flags"](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#key-flags) that delineate the operations a key can perform.
Each {term}`component key` has a set of ["key flags"](https://www.rfc-editor.org/rfc/rfc9580.html#key-flags) that delineate the operations a key can perform.
Commonly used {term}`key flags<Key Flag>` include:
@ -223,10 +223,10 @@ Commonly used {term}`key flags<Key Flag>` include:
- **{term}`Encryption<Encryption Key Flag>`**: allows the key to encrypt data
- **{term}`Authentication<Authentication Key Flag>`**: primarily used for SSH authentication[^auth-flag]
[^auth-flag]: It's important to note that the function of the [authentication](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-authentication-via-digital-) {term}`key flag` is unrelated to the {term}`authentication` process used in certifying OpenPGP {term}`identities<Identity>` and linking them to {term}`certificate<OpenPGP Certificate>`. Rather, this flag indicates a mechanism that uses {term}`cryptographic signatures<OpenPGP Signature Packet>` to confirm control of {term}`private key material` with a remote system.
[^auth-flag]: It's important to note that the function of the [authentication](https://www.rfc-editor.org/rfc/rfc9580.html#name-authentication-via-digital-) {term}`key flag` is unrelated to the {term}`authentication` process used in certifying OpenPGP {term}`identities<Identity>` and linking them to {term}`certificate<OpenPGP Certificate>`. Rather, this flag indicates a mechanism that uses {term}`cryptographic signatures<OpenPGP Signature Packet>` to confirm control of {term}`private key material` with a remote system.
```{note}
Distinct {term}`component keys<Component Key>` handle specific operations. Only the {term}`primary key<OpenPGP Primary Key>` can be used for {term}`certification`, although it can have additional {term}`capabilities<Capability>`. {term}`Subkeys<OpenPGP Subkey>` can be used for signing, encryption, and authentication but cannot have the {term}`certification` {term}`capability`. A {term}`component key` can technically have multiple {term}`capabilities<Capability>`. It is considered good practice, however, to [use separate keys for each capability](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-10.1.5-7).
Distinct {term}`component keys<Component Key>` handle specific operations. Only the {term}`primary key<OpenPGP Primary Key>` can be used for {term}`certification`, although it can have additional {term}`capabilities<Capability>`. {term}`Subkeys<OpenPGP Subkey>` can be used for signing, encryption, and authentication but cannot have the {term}`certification` {term}`capability`. A {term}`component key` can technically have multiple {term}`capabilities<Capability>`. It is considered good practice, however, to [use separate keys for each capability](https://www.rfc-editor.org/rfc/rfc9580.html#section-10.1.5-7).
Notably, in many algorithms, encryption and signing-related functionalities (i.e., {term}`certification<Certification Key Flag>`, {term}`signing<Signing Key Flag>`, {term}`authentication<Authentication Key Flag>`) are mutually exclusive, because the algorithms only support one of those two families of operations[^key-flag-sharing].
```
@ -244,11 +244,11 @@ However, this approach requires that OpenPGP software determine the cryptographi
Negotiation mechanisms in OpenPGP include:
- [Preferred hash algorithms](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-hashes-subpacket)
- [Preferred symmetric ciphers for v1 SEIPD](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-v1-seipd)
- [Preferred AEAD ciphersuites](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-v2-seipd)
- [Features subpacket](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#features-subpacket)
- [Preferred compression algorithms](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-compression-subpacket)
- [Preferred hash algorithms](https://www.rfc-editor.org/rfc/rfc9580.html#preferred-hashes-subpacket)
- [Preferred symmetric ciphers for v1 SEIPD](https://www.rfc-editor.org/rfc/rfc9580.html#preferred-v1-seipd)
- [Preferred AEAD ciphersuites](https://www.rfc-editor.org/rfc/rfc9580.html#preferred-v2-seipd)
- [Features subpacket](https://www.rfc-editor.org/rfc/rfc9580.html#features-subpacket)
- [Preferred compression algorithms](https://www.rfc-editor.org/rfc/rfc9580.html#preferred-compression-subpacket)
Beyond these explicitly expressed preferences, implementations also deduce {term}`capabilities<Capability>` of communication partners based on the version of the {term}`OpenPGP certificate` they possess.

2
book/source/compression.md
View file

@ -14,7 +14,7 @@ This means that to use whatever potential for compression exists, the message mu
## Decompression yields a 'wrapped' OpenPGP packet stream
Compression in OpenPGP is a simple mechanism: A [Compressed Data packet](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-compressed-data-packet-type) acts as a compressed container for a series of OpenPGP packets.
Compression in OpenPGP is a simple mechanism: A [Compressed Data packet](https://www.rfc-editor.org/rfc/rfc9580.html#name-compressed-data-packet-type) acts as a compressed container for a series of OpenPGP packets.
The compressed data packet consists of the specification of which compression algorithm is used, followed by a compressed representation of the contained data.

6
book/source/cryptography.md
View file

@ -62,12 +62,12 @@ However, exchanging the required shared secret is a problem that needs to be sol
Symmetric-key cryptography is used in OpenPGP in three contexts:
- most prominently, as part of a hybrid cryptosystem to encrypt and decrypt data,
- to encrypt [password-protected private key material](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-secret-key-encryption), and
- for [password-protected data encryption](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-symmetric-key-encrypted-ses), a less commonly used feature of the standard.
- to encrypt [password-protected private key material](https://www.rfc-editor.org/rfc/rfc9580.html#name-secret-key-encryption), and
- for [password-protected data encryption](https://www.rfc-editor.org/rfc/rfc9580.html#name-symmetric-key-encrypted-ses), a less commonly used feature of the standard.
Where symmetric keys are used in OpenPGP for data encryption, they are called either "message keys" or "session keys[^sessionkey]."
[^sessionkey]: In OpenPGP version 6, the ["Version 2 Symmetrically Encrypted Integrity Protected Data Packet Format"](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-version-2-symmetrically-enc) requires that a "message key" is derived from a "session key." In contrast, up to OpenPGP version 4, and in version 6 when using ["Version 1 Symmetrically Encrypted Integrity Protected Data Packet Format"](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-version-1-symmetrically-enc), the "session key" was used directly as a symmetric encryption key.
[^sessionkey]: In OpenPGP version 6, the ["Version 2 Symmetrically Encrypted Integrity Protected Data Packet Format"](https://www.rfc-editor.org/rfc/rfc9580.html#name-version-2-symmetrically-enc) requires that a "message key" is derived from a "session key." In contrast, up to OpenPGP version 4, and in version 6 when using ["Version 1 Symmetrically Encrypted Integrity Protected Data Packet Format"](https://www.rfc-editor.org/rfc/rfc9580.html#name-version-1-symmetrically-enc), the "session key" was used directly as a symmetric encryption key.
### Authenticated encryption with associated data (AEAD)

12
book/source/decryption.md
View file

@ -87,11 +87,11 @@ The Key ID of the subkey to be used is recorded in the PKESKs key-id field. A va
To detect, which symmetric cipher is used to decrypt the SEIPD v1 packet later on, each public key algorithm uses a slightly different encoding to unpack the symmetric algorithm tag from the decrypted session key. See the respective sections[^rsa-spec] [^elgamal-spec] [^ecdh-spec] [^x25519-spec] [^x448-spec] of the standard. Typically, the cipher algorithm ID is prefixed to the actual session key.
[^rsa-spec]: [Algorithm-Specific Fields for RSA encryption](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-algorithm-specific-fields-f)
[^elgamal-spec]: [Algorithm-Specific Fields for Elgamal encryption](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-algorithm-specific-fields-fo)
[^ecdh-spec]: [Algorithm-Specific Fields for ECDH encryption](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-algorithm-specific-fields-for)
[^x25519-spec]: [Algorithm-Specific Fields for X25519 encryption](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-algorithm-specific-fields-for-)
[^x448-spec]: [Algorithm-Specific Fields for X448 encryption](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-algorithm-specific-fields-for-x)
[^rsa-spec]: [Algorithm-Specific Fields for RSA encryption](https://www.rfc-editor.org/rfc/rfc9580.html#name-algorithm-specific-fields-f)
[^elgamal-spec]: [Algorithm-Specific Fields for Elgamal encryption](https://www.rfc-editor.org/rfc/rfc9580.html#name-algorithm-specific-fields-fo)
[^ecdh-spec]: [Algorithm-Specific Fields for ECDH encryption](https://www.rfc-editor.org/rfc/rfc9580.html#name-algorithm-specific-fields-for)
[^x25519-spec]: [Algorithm-Specific Fields for X25519 encryption](https://www.rfc-editor.org/rfc/rfc9580.html#name-algorithm-specific-fields-for-)
[^x448-spec]: [Algorithm-Specific Fields for X448 encryption](https://www.rfc-editor.org/rfc/rfc9580.html#name-algorithm-specific-fields-for-x)
```{figure} plain_svg/PKESKv3-decryption.svg
:name: fig-decryption-pkesk3
@ -183,4 +183,4 @@ Each chunk is decrypted using AEAD using the message key and an IV with appended
The Symmetrically Encrypted Data packet predates the SEIPD packet and is nowadays deprecated.
Due to the lack of integrity protection, this packet is susceptible to a whole class of attacks where the attacker modifies the ciphertext.
Therefore, implementations MUST NOT produce this packet and are encouraged not to accept incoming SED packages from untrusted sources.
Therefore, implementations MUST NOT produce this packet and are encouraged not to accept incoming SED packages from untrusted sources.

28
book/source/encryption.md
View file

@ -5,7 +5,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0
# Encryption
[Encryption](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-confidentiality-via-encrypt) is one of the core facilities of OpenPGP. It provides confidentiality.
[Encryption](https://www.rfc-editor.org/rfc/rfc9580.html#name-confidentiality-via-encrypt) is one of the core facilities of OpenPGP. It provides confidentiality.
For an in-depth, packet-level view of encrypted data in OpenPGP, see [](/zoom/encryption).
@ -23,7 +23,7 @@ For an in-depth, packet-level view of encrypted data in OpenPGP, see [](/zoom/en
Encryption in OpenPGP is performed in two distinct steps:
1. **Symmetric encryption**: The plaintext is encrypted based on a (secret) symmetric key, the [*session key*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-confidentiality-via-encrypt). The (potentially large) ciphertext only needs to be stored once, even if it is sent to multiple recipients. All recipients get access to the same shared *session key* to decrypt the message.
1. **Symmetric encryption**: The plaintext is encrypted based on a (secret) symmetric key, the [*session key*](https://www.rfc-editor.org/rfc/rfc9580.html#name-confidentiality-via-encrypt). The (potentially large) ciphertext only needs to be stored once, even if it is sent to multiple recipients. All recipients get access to the same shared *session key* to decrypt the message.
2. **Session key transmission**: For each recipient of the message, a packet that contains a protected copy of the session key is generated.
- Usually, the *session key* is encrypted to a public encryption component key of the recipient.
- Alternatively - or additionally - the *session key* may also be encrypted using a passphrase. This is a specialized and less commonly used mode of operation that doesn't require OpenPGP certificates.
@ -41,7 +41,7 @@ A *signed message*, in turn, is a packet sequence that either
## Encryption mechanism versions
OpenPGP's encryption mechanisms have evolved over time. The RFC shows an [overview of encryption mechanisms](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-10.3.2.1), and how they may be combined.
OpenPGP's encryption mechanisms have evolved over time. The RFC shows an [overview of encryption mechanisms](https://www.rfc-editor.org/rfc/rfc9580.html#section-10.3.2.1), and how they may be combined.
Two generations of encryption mechanisms are currently relevant in OpenPGP, and will co-exist for the foreseeable future.
@ -51,10 +51,10 @@ Older, legacy encryption mechanisms exist in OpenPGP. However, those must not be
SEIPD packets are used in combination with two mechanisms that store *session keys*:
- [Public-Key Encrypted Session Key](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-public-key-encrypted-sessio) (PKESK) packets and
- [Symmetric-Key Encrypted Session Key](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#skesk) (SKESK) packets.
- [Public-Key Encrypted Session Key](https://www.rfc-editor.org/rfc/rfc9580.html#name-public-key-encrypted-sessio) (PKESK) packets and
- [Symmetric-Key Encrypted Session Key](https://www.rfc-editor.org/rfc/rfc9580.html#skesk) (SKESK) packets.
The typical combination of mechanisms for encryption in OpenPGP is a [hybrid cryptosystem](hybrid-cryptosystems), consisting of one or more [Public-Key Encrypted Session Key](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-public-key-encrypted-sessio) packets (PKESK), followed by a [Symmetrically Encrypted Integrity Protected Data](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-symmetrically-encrypted-int) (SEIPD) packet.
The typical combination of mechanisms for encryption in OpenPGP is a [hybrid cryptosystem](hybrid-cryptosystems), consisting of one or more [Public-Key Encrypted Session Key](https://www.rfc-editor.org/rfc/rfc9580.html#name-public-key-encrypted-sessio) packets (PKESK), followed by a [Symmetrically Encrypted Integrity Protected Data](https://www.rfc-editor.org/rfc/rfc9580.html#name-symmetrically-encrypted-and) (SEIPD) packet.
In this combination, an asymmetric cryptographic mechanism is used to protect a *session key* inside PKESK packets. The *session key*, in turn, is used to protect the plaintext using symmetric-key encryption in a SEIPD packet.
@ -62,8 +62,8 @@ In this combination, an asymmetric cryptographic mechanism is used to protect a
Encrypted session key (ESK) packets are a family of two mechanisms for securing symmetric key material:
- [PKESK](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-public-key-encrypted-sessio): Uses asymmetric OpenPGP key material to protect a session key, and
- [SKESK](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-symmetric-key-encrypted-ses): Uses passphrases to protect the symmetric key material, instead of OpenPGP asymmetric key material (this is less commonly used).
- [PKESK](https://www.rfc-editor.org/rfc/rfc9580.html#name-public-key-encrypted-sessio): Uses asymmetric OpenPGP key material to protect a session key, and
- [SKESK](https://www.rfc-editor.org/rfc/rfc9580.html#name-symmetric-key-encrypted-ses): Uses passphrases to protect the symmetric key material, instead of OpenPGP asymmetric key material (this is less commonly used).
An arbitrary number of PKESKs and SKESKs can be used in the same message. It is also possible to mix the two, resulting in a message which can be decrypted using either one of the designated OpenPGP keys or any of the passphrases used to encrypt the message. This is useful to make a message available to a number of known recipients, with the option to provide the passphrase to future recipients.
@ -91,20 +91,20 @@ The specification currently recommends to use either *Iterated and Salted S2K* o
A SEIPD packet contains the actual payload: the ciphertext of the encrypted message. For a large encrypted message, the SEIPD packet will also be large.
```{note}
SEIPD packets are the successor to the [Symmetrically Encrypted Data](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-symmetrically-encrypted-dat) packet, which is obsolete.
SEIPD packets are the successor to the [Symmetrically Encrypted Data](https://www.rfc-editor.org/rfc/rfc9580.html#name-symmetrically-encrypted-dat) packet, which is obsolete.
```
Two versions of the SEIPD packet (differentiated by the version number) have been specified. Version 1, introduced in RFC4880, is used in OpenPGP v4 while SEIPD version 2 was introduced with OpenPGP v6. Both versions can be used with either OpenPGP v4 or v6 keys, although OpenPGP v4 keys need to announce support for SEIPD version 2 via the *Feature* signature subpacket.
When decrypted, the data contained in a SEIPD packet forms an [OpenPGP message](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-openpgp-messages). That is, the decrypted data consists of a series of OpenPGP packets.
When decrypted, the data contained in a SEIPD packet forms an [OpenPGP message](https://www.rfc-editor.org/rfc/rfc9580.html#name-openpgp-messages). That is, the decrypted data consists of a series of OpenPGP packets.
In both versions of SEIPD, the decryptor must have obtained a *session key* in a previous step, before processing the SEIPD packet. Using this session key, the decryptor can decrypt the SEIPD packet and process the plaintext data that it contains.
### v1 SEIPD, based on MDC
The [version 1 SEIPD](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#version-one-seipd) mechanism is supported by all modern OpenPGP version 4 implementations. It was introduced in [RFC 4880](https://www.rfc-editor.org/rfc/rfc4880.html#section-5.13) as a replacement for the *SED* (Symmetrically Encrypted Data) packet. SEIPDv1 provides integrity protection of the ciphertext using a SHA-1 checksum of the plaintext as modification detection code.
The [version 1 SEIPD](https://www.rfc-editor.org/rfc/rfc9580.html#version-one-seipd) mechanism is supported by all modern OpenPGP version 4 implementations. It was introduced in [RFC 4880](https://www.rfc-editor.org/rfc/rfc4880.html#section-5.13) as a replacement for the *SED* (Symmetrically Encrypted Data) packet. SEIPDv1 provides integrity protection of the ciphertext using a SHA-1 checksum of the plaintext as modification detection code.
Version 1 SEIPD can only be combined with [version 3 PKESK](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#v3-pkesk) and/or [version 4 SKESK](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#v4-skesk) packets.
Version 1 SEIPD can only be combined with [version 3 PKESK](https://www.rfc-editor.org/rfc/rfc9580.html#v3-pkesk) and/or [version 4 SKESK](https://www.rfc-editor.org/rfc/rfc9580.html#v4-skesk) packets.
In this version of the SEIPD packet, the session key is used directly as message key, meaning the payload is encrypted symmetrically using the session key.
@ -141,9 +141,9 @@ Lastly, the whole prepared plaintext is encrypted symmetrically.
(seipd-v2)=
### v2 SEIPD, based on AEAD
The [version 2 SEIPD](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#version-two-seipd) mechanism was introduced in OpenPGP version 6. Consequently, it can only be used for encryption when all recipients explicitly announce support for it using a *Feature* signature subpacket.
The [version 2 SEIPD](https://www.rfc-editor.org/rfc/rfc9580.html#version-two-seipd) mechanism was introduced in OpenPGP version 6. Consequently, it can only be used for encryption when all recipients explicitly announce support for it using a *Feature* signature subpacket.
It provides integrity protection of the ciphertext using *AEAD* (authenticated encryption with additional data).
v2 SEIPD can only be combined with either [version 6 PKESK](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#v6-pkesk) and/or [version 6 SKESK](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#v6-skesk) packets.
v2 SEIPD can only be combined with either [version 6 PKESK](https://www.rfc-editor.org/rfc/rfc9580.html#v6-pkesk) and/or [version 6 SKESK](https://www.rfc-editor.org/rfc/rfc9580.html#v6-skesk) packets.
In version 2 SEIPD, the *session key* is transformed into a *message key*, based on a per-message salt value stored separately in the v2 SEIPD packet. The message key is then used in an AEAD scheme to encrypt the message payload.

56
book/source/glossary.md
View file

@ -87,7 +87,7 @@ Certification Key Flag
Certification Revocation Signature Packet
An {term}`OpenPGP Signature Packet` to {term}`revoke<Revocation>` an earlier {term}`self-certification` of a {term}`User ID`.
[RFC 5.2.1.13](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-certification-revocation-si)
[RFC 5.2.1.13](https://www.rfc-editor.org/rfc/rfc9580.html#name-certification-revocation-si)
Certification Signature
See {term}`Certification`.
@ -99,14 +99,14 @@ Certifying Signature
See {term}`Certification`.
Cipher Type Byte
This historical term was defined in [RFC 1991](https://datatracker.ietf.org/doc/html/rfc1991#section-4.1) and was subsequently superseded by {term}`Packet Tag` in [RFC 2440](https://datatracker.ietf.org/doc/html/rfc2440#section-4.2), which is in turn superseded by {term}`Packet Type ID` in the new [RFC](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-packet-headers).
This historical term was defined in [RFC 1991](https://datatracker.ietf.org/doc/html/rfc1991#section-4.1) and was subsequently superseded by {term}`Packet Tag` in [RFC 2440](https://datatracker.ietf.org/doc/html/rfc2440#section-4.2), which is in turn superseded by {term}`Packet Type ID` in the new [RFC](https://www.rfc-editor.org/rfc/rfc9580.html#name-packet-headers).
Cleartext Signature
A {term}`Data Signature` which exists in a combined text format, encapsulating the (readable) text input it was created for. See [](cleartext-signature).
Cleartext Signature Framework
A framework for creating {term}`cleartext signatures<Cleartext Signature>`.
See [RFC 7](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#cleartext-signature).
See [RFC 7](https://www.rfc-editor.org/rfc/rfc9580.html#cleartext-signature).
Component
An element in an {term}`OpenPGP Certificate`, that represents a {term}`component key` or {term}`identity component`.
@ -166,7 +166,7 @@ Direct Key Signature
Embedded Signature Subpacket
An {term}`OpenPGP Signature Subpacket` which contains a complete {term}`OpenPGP Signature Packet`.
See [RFC 5.2.3.34](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-embedded-signature)
See [RFC 5.2.3.34](https://www.rfc-editor.org/rfc/rfc9580.html#name-embedded-signature)
Encrypted Data
Data that is encrypted.
@ -189,7 +189,7 @@ Features Subpacket
For an in-depth view on these {term}`subpackets<OpenPGP Signature Subpacket>` see [](zoom-dks).
See [RFC 5.2.3.32](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-features)
See [RFC 5.2.3.32](https://www.rfc-editor.org/rfc/rfc9580.html#name-features)
Fingerprint
See {term}`OpenPGP Fingerprint`.
@ -199,7 +199,7 @@ Hard Revocation
See [](hard-vs-soft-revocations).
See [RFC 5.2.3.31](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-reason-for-revocation).
See [RFC 5.2.3.31](https://www.rfc-editor.org/rfc/rfc9580.html#name-reason-for-revocation).
Hash Algorithm
See {term}`Hash Function`.
@ -260,7 +260,7 @@ Issuer
Issuer Fingerprint Subpacket
A {term}`Subpacket` specifying the {term}`Fingerprint` of an {term}`Issuer Key`.
See [RFC 5.2.3.35](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-issuer-fingerprint)
See [RFC 5.2.3.35](https://www.rfc-editor.org/rfc/rfc9580.html#name-issuer-fingerprint)
Issuer Key
The {term}`OpenPGP Component Key` of an {term}`Issuer`, used to create an {term}`OpenPGP Signature Packet`.
@ -283,7 +283,7 @@ Key
Key Expiration Time Subpacket
An {term}`OpenPGP Signature Subpacket Type` which defines the {term}`Expiration Time` for a {term}`key<Component Key>`.
See [RFC 5.2.3.13](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-expiration-time)
See [RFC 5.2.3.13](https://www.rfc-editor.org/rfc/rfc9580.html#name-key-expiration-time)
Key Flag
A preference encoded in an {term}`OpenPGP Signature Subpacket`, that defines the {term}`Capability` a {term}`OpenPGP Component Key` has. See [](signature-subpackets).
@ -322,7 +322,7 @@ Literal Data Packet
A literal data packet typically stores the paintext data of an encrypted message, and/or the data of an inline signed message.
See [RFC 5.9](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#lit).
See [RFC 5.9](https://www.rfc-editor.org/rfc/rfc9580.html#lit).
MAC
See {term}`Message Authentication Code`.
@ -354,7 +354,7 @@ One-pass Signature Packet
One or more {term}`packets<Packet>` before the actual data in a {term}`Data Signature` which contain information to allow a receiving {term}`implementation<OpenPGP Implementation>` to create {term}`hashes<Hash Digest>` 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).
Also see [RFC 5.4](https://www.rfc-editor.org/rfc/rfc9580.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<OpenPGP Signature Packet>` and accompanying auxiliary {term}`One-pass signatures<One-pass Signature Packet>`.
@ -389,7 +389,7 @@ OpenPGP Message
- a {term}`compressed message<compressed data packet>`
- a {term}`literal message<literal data packet>`
Also see [RFC 10.3](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-openpgp-messages).
Also see [RFC 10.3](https://www.rfc-editor.org/rfc/rfc9580.html#name-openpgp-messages).
OpenPGP Public Key
See {term}`OpenPGP Certificate`.
@ -428,10 +428,10 @@ Packet
An element in an {term}`OpenPGP Certificate` or {term}`OpenPGP 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.
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.rfc-editor.org/rfc/rfc9580.html#name-packet-headers), which explains this section in more detail.
Packet Tag
This historical term was defined in [RFC 2440](https://datatracker.ietf.org/doc/html/rfc2440#section-4.2) and is superseded by {term}`Packet Type ID` in the new [RFC](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-packet-headers).
This historical term was defined in [RFC 2440](https://datatracker.ietf.org/doc/html/rfc2440#section-4.2) and is superseded by {term}`Packet Type ID` in the new [RFC](https://www.rfc-editor.org/rfc/rfc9580.html#name-packet-headers).
Packet Type ID
A numerical value encoded in the first octet of a {term}`Packet Header`, defining a {term}`Packet`'s type.
@ -444,22 +444,22 @@ Positive Certification
Preferred Compression Algorithms Subpacket
An {term}`OpenPGP Signature Subpacket Type` which defines the preferred {term}`compression algorithms<Data Compression>` for an {term}`OpenPGP Certificate` or {term}`Component Key`. This defines which {term}`algorithms<Data Compression>` the {term}`key holder<Certificate Holder>` prefers to receive.
See [RFC 5.2.3.17](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-preferred-compression-algor).
See [RFC 5.2.3.17](https://www.rfc-editor.org/rfc/rfc9580.html#name-preferred-compression-algor).
Preferred Hash Algorithms Subpacket
An {term}`OpenPGP Signature Subpacket Type` which defines the preferred {term}`hash algorithm<Hash Function>` for an {term}`OpenPGP Certificate` or {term}`Component Key`. This defines which algorithms the {term}`key holder<Certificate Holder>` prefers to receive.
See [RFC 5.2.3.16](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-preferred-hash-algorithms).
See [RFC 5.2.3.16](https://www.rfc-editor.org/rfc/rfc9580.html#name-preferred-hash-algorithms).
Preferred Symmetric Ciphers for v1 SEIPD Subpacket
An {term}`OpenPGP Signature Subpacket Type` which defines the preferred version 1 {term}`SEIPD<Symmetrically Encrypted Integrity Protected Data>` algorithms for an {term}`OpenPGP Certificate` or {term}`Component Key`. This defines which algorithms the {term}`key holder<Certificate Holder>` prefers to receive and implicitly signifies the supported algorithms of the {term}`key holder<Certificate Holder>`'s {term}`implementation<OpenPGP Implementation>`.
See [RFC 5.2.3.14](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-preferred-symmetric-ciphers).
See [RFC 5.2.3.14](https://www.rfc-editor.org/rfc/rfc9580.html#name-preferred-symmetric-ciphers).
Preferred AEAD Ciphersuites Subpacket
An {term}`OpenPGP Signature Subpacket Type` which defines the preferred version 2 {term}`SEIPD<Symmetrically Encrypted Integrity Protected Data>` algorithms for an {term}`OpenPGP Certificate` or {term}`Component Key`. This defines which algorithms the {term}`key holder<Certificate Holder>` prefers to receive and implicitly signifies the supported algorithms of the {term}`key holder<Certificate Holder>`'s {term}`implementation<OpenPGP Implementation>`.
See [RFC 5.2.3.15](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-preferred-aead-ciphersuites)
See [RFC 5.2.3.15](https://www.rfc-editor.org/rfc/rfc9580.html#name-preferred-aead-ciphersuites)
Prefixed signed Message
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`.
@ -488,7 +488,7 @@ Primary User ID
Primary User ID Subpacket
An {term}`OpenPGP Signature Subpacket` used in {term}`User ID self-signatures<User ID Binding Signature>` which allows to signify whether the {term}`User ID` in question is considered a {term}`Primary User ID`.
See [RFC 5.2.3.27](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#primary-user-id-subpacket)
See [RFC 5.2.3.27](https://www.rfc-editor.org/rfc/rfc9580.html#primary-user-id-subpacket)
Primary User ID Binding Signature
A {term}`Binding Signature`, which is created by an {term}`OpenPGP Primary Key` to bind a {term}`User ID` to its {term}`OpenPGP Certificate` and marking it as the {term}`Primary User ID`.
@ -518,7 +518,7 @@ Public Key Material
Reason For Revocation Subpacket
An {term}`OpenPGP Signature Subpacket`, which is used in {term}`Certification Revocation Signature Packet` and {term}`key revocation signature packets<Key Revocation Signature Packet>` to describe a reason for the {term}`revocation`.
See [RFC 5.2.3.31](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-reason-for-revocation)
See [RFC 5.2.3.31](https://www.rfc-editor.org/rfc/rfc9580.html#name-reason-for-revocation)
Reference Time
A point in time at which an {term}`OpenPGP Certificate` or {term}`OpenPGP Signature` is evaluated.
@ -532,9 +532,9 @@ Revocation
Revocation Certificate
A {term}`Revocation Self-signature` for an {term}`OpenPGP Primary Key` distributed alongside the plain {term}`OpenPGP Primary Key`.
See [RFC 10.1.2](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-openpgp-v6-revocation-certi)
See [RFC 10.1.2](https://www.rfc-editor.org/rfc/rfc9580.html#name-openpgp-version-6-revocatio)
Note that in [OpenPGP v4 this term is typically used](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-10.1.3-6) for a bare {term}`Revocation Self-signature` {term}`packet<OpenPGP Signature Packet>`.
Note that in [OpenPGP v4 this term is typically used](https://www.rfc-editor.org/rfc/rfc9580.html#section-10.1.3-6) for a bare {term}`Revocation Self-signature` {term}`packet<OpenPGP Signature Packet>`.
Revocation Code
A number in a {term}`Reason For Revocation Subpacket` which represents the reason for a {term}`Revocation`.
@ -577,7 +577,7 @@ Soft Revocation
See [](hard-vs-soft-revocations).
See [RFC 5.2.3.31](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-reason-for-revocation).
See [RFC 5.2.3.31](https://www.rfc-editor.org/rfc/rfc9580.html#name-reason-for-revocation).
Signature
See {term}`OpenPGP Signature Packet`.
@ -585,12 +585,12 @@ Signature
Signature Creation Time Subpacket
An {term}`OpenPGP Signature Subpacket Type` which defines the {term}`Creation Time` for an {term}`OpenPGP Signature Packet`.
See [RFC 5.2.3.11](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-signature-creation-time)
See [RFC 5.2.3.11](https://www.rfc-editor.org/rfc/rfc9580.html#name-signature-creation-time)
Signature Expiration Time Subpacket
An {term}`OpenPGP Signature Subpacket Type` which defines the {term}`Expiration Time` for an {term}`OpenPGP Signature Packet`.
See [RFC 5.2.3.18](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-signature-expiration-time)
See [RFC 5.2.3.18](https://www.rfc-editor.org/rfc/rfc9580.html#name-signature-expiration-time)
Signature On Component
{term}`Cryptographic signature` associated with {term}`Component Keys<Component Key>` or {term}`Identity Components<Identity Component>`. See [](/signing_components).
@ -646,7 +646,7 @@ Subkey Binding Signature
Subkey Revocation Signature Packet
A {term}`Self-signature` to {term}`revoke<Revocation>` an {term}`OpenPGP Subkey` in an {term}`OpenPGP Certificate`.
See [RFC 5.2.1.12](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-subkey-revocation-signature)
See [RFC 5.2.1.12](https://www.rfc-editor.org/rfc/rfc9580.html#name-subkey-revocation-signature)
Subpacket
See {term}`OpenPGP Signature Subpacket`.
@ -660,7 +660,7 @@ Symmetric Cryptography
Symmetrically Encrypted Integrity Protected Data
Short *SEIPD*, this refers to {term}`Symmetric Cryptography` based encrypted data, which is used in a Symmetrically Encrypted Integrity Protected Data Packet.
See [RFC 5.13](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-symmetrically-encrypted-int).
See [RFC 5.13](https://www.rfc-editor.org/rfc/rfc9580.html#name-symmetrically-encrypted-and).
Symmetric Secret Key
The {term}`Private Key Material` used in {term}`Symmetric Cryptography`.
@ -682,7 +682,7 @@ Trust Amount
Values less than `120` indicate partial trust, values equal to or greater than `120` indicate complete trust.
See [](trust-amount).
See [RFC 5.2.3.21](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-trust-signature)
See [RFC 5.2.3.21](https://www.rfc-editor.org/rfc/rfc9580.html#name-trust-signature)
Trust Anchor
An entity in a {term}`Trust Model` for which trust is assumed and not derived.
@ -704,7 +704,7 @@ Trust Root
Trust Signature
The *trust signature* {term}`subpacket<OpenPGP Signature Subpacket>` on a {term}`certifying signature<Certification>` is used for {term}`delegation` of {term}`authentication` decisions. With this feature, an OpenPGP user can designate a {term}`certificate<OpenPGP Certificate>` as a "{term}`trusted introducer`" and opt to rely on {term}`certifications<Certification>` they issue.
See [RFC 5.2.3.21](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-trust-signature)
See [RFC 5.2.3.21](https://www.rfc-editor.org/rfc/rfc9580.html#name-trust-signature)
Trusted introducer
OpenPGP users can choose to rely on {term}`certifications<Certification>` issued by a third party. The remote party of such a {term}`delegation` is called a "trusted introducer".

10
book/source/migration.md
View file

@ -35,9 +35,9 @@ Another good example is the S2K mechanism for secret-key encryption.
This feature concerns local copies of OpenPGP private keys on each user's machine. There is, by definition, no interoperability concern around this feature: Passphrase-protection of the private key material is a local implementation detail on each user's machine.
The RFC [states](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-avoiding-ciphertext-malleab) that: "Users are RECOMMENDED to migrate to AEAD."
The RFC [states](https://www.rfc-editor.org/rfc/rfc9580.html#name-avoiding-ciphertext-malleab) that: "Users are RECOMMENDED to migrate to AEAD."
In the context of this chapter, this means that encrypted private keys should be upgraded by the user's OpenPGP software to use [S2K usage mode 253](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-secret-key-encryption-s2k-u) (AEAD) to encrypt the user's private key material.
In the context of this chapter, this means that encrypted private keys should be upgraded by the user's OpenPGP software to use [S2K usage mode 253](https://www.rfc-editor.org/rfc/rfc9580.html#name-secret-key-encryption) (AEAD) to encrypt the user's private key material.
Note that S2K usage mode 253 (AEAD) can be applied to both version 6 and version 4 private keys, with sufficiently up-to-date OpenPGP software. This S2K usage mode is strongly recommended for private keys of all versions.
@ -59,19 +59,19 @@ On the receiving/verifying side, v6 signatures can be checked by anyone whose Op
Over time, steadily more OpenPGP libraries and tools will add support for OpenPGP v6 features. This migration might take a while, while implementers catch up.
The OpenPGP v6 standard gives guidance for library authors to extend an OpenPGP implementation to support version 6 in [Appendix B. Upgrade Guidance](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-upgrade-guidance-adapting-i).
The OpenPGP v6 standard gives guidance for library authors to extend an OpenPGP implementation to support version 6 in [Appendix B. Upgrade Guidance](https://www.rfc-editor.org/rfc/rfc9580.html#name-upgrade-guidance-adapting-i).
## Key migration
Some OpenPGP v6 features are only available for use with keys in the v6 format.
For example, only an [OpenPGP v6 key can issue a v6 signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-packet-versions-in-signatur).
For example, only an [OpenPGP v6 key can issue a v6 signature](https://www.rfc-editor.org/rfc/rfc9580.html#name-packet-versions-in-signatur).
On the other hand, an OpenPGP v6 key can *only* issue v6 signatures, so if you require compatibility with v4 verifiers, you shouldn't yet migrate to a v6 key/certificate.
When migrating to a v6 key, generating a fresh v6 key is the recommended approach.
It is not possible to adopt v4 subkeys into a v6 key, since every subkey to a v6 primary key must itself be a v6 subkey, see in [OpenPGP v6 certificate structure](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-10.1.1-5).
It is not possible to adopt v4 subkeys into a v6 key, since every subkey to a v6 primary key must itself be a v6 subkey, see in [OpenPGP v6 certificate structure](https://www.rfc-editor.org/rfc/rfc9580.html#section-10.1.1-5).
### Converting v4 component keys into v6 component keys

14
book/source/private_keys.md
View file

@ -33,7 +33,7 @@ In certain cases, an exception arises where the cryptographic private key materi
## Transferable secret key format
Sometimes it is useful to handle OpenPGP certificates combined with private key material in the form of a [*transferable secret key (TSK)*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-transferable-secret-keys). A TSK is a serialized format that combines OpenPGP certificate data with its connected private key material, stored in a single file.
Sometimes it is useful to handle OpenPGP certificates combined with private key material in the form of a [*transferable secret key (TSK)*](https://www.rfc-editor.org/rfc/rfc9580.html#name-transferable-secret-keys). A TSK is a serialized format that combines OpenPGP certificate data with its connected private key material, stored in a single file.
```{figure} plain_svg/TSK.svg
:name: fig-transferable-secret-key
@ -65,7 +65,7 @@ This method proves effective in scenarios where an unauthorized party obtains th
When protecting private key material in OpenPGP, a symmetric key is derived from the user's passphrase. This derived key is then used to protect the OpenPGP private key data.
To facilitate this, the OpenPGP standard defines a set of mechanisms known as [string-to-key (S2K)](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-string-to-key-s2k-specifier). S2K mechanisms are used to generate high-entropy symmetric encryption keys from lower-entropy passphrases, using a [key derivation function (KDF)](https://en.wikipedia.org/wiki/Key_derivation_function).
To facilitate this, the OpenPGP standard defines a set of mechanisms known as [string-to-key (S2K)](https://www.rfc-editor.org/rfc/rfc9580.html#name-string-to-key-s2k-specifier). S2K mechanisms are used to generate high-entropy symmetric encryption keys from lower-entropy passphrases, using a [key derivation function (KDF)](https://en.wikipedia.org/wiki/Key_derivation_function).
```{figure} plain_svg/passphrase_using_S2K.svg
:name: fig-passphrase-using-s2k
@ -78,10 +78,10 @@ This symmetric key is used to protect the private key material it is in a passiv
#### Mechanisms for symmetric key generation
Over time, OpenPGP has evolved to include various [S2K mechanisms for generating symmetric keys](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-string-to-key-s2k-types-reg), in line with advancements in cryptographic practices. Currently, two mechanisms are universally recommended:
Over time, OpenPGP has evolved to include various [S2K mechanisms for generating symmetric keys](https://www.rfc-editor.org/rfc/rfc9580.html#name-openpgp-string-to-key-s2k-t), in line with advancements in cryptographic practices. Currently, two mechanisms are universally recommended:
- [**Argon2**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-argon2): Introduced in OpenPGP version 6, Argon2 is a memory-hard mechanism designed to reduce the efficiency of brute-force attacks using specialized hardware.
- [**Iterated and Salted S2K**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-iterated-and-salted-s2k): This mechanism is a staple with OpenPGP version 4 implementations.
- [**Argon2**](https://www.rfc-editor.org/rfc/rfc9580.html#name-argon2): Introduced in OpenPGP version 6, Argon2 is a memory-hard mechanism designed to reduce the efficiency of brute-force attacks using specialized hardware.
- [**Iterated and Salted S2K**](https://www.rfc-editor.org/rfc/rfc9580.html#name-iterated-and-salted-s2k): This mechanism is a staple with OpenPGP version 4 implementations.
A third mechanism is conditionally allowed for key generation. Decryption of private keys that use obsolete mechanisms is also allowed.
@ -93,7 +93,7 @@ The generation of a symmetric key from a passphrase leads to its subsequent use
The RFC uses the term "String-to-Key Usage (S2K usage)" for the mechanism used to *apply* the symmetric key.
Different mechanisms are specified [for encryption of OpenPGP private key material](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-secret-key-encryption).
Different mechanisms are specified [for encryption of OpenPGP private key material](https://www.rfc-editor.org/rfc/rfc9580.html#name-secret-key-encryption).
### Component-based passphrase protection
@ -130,4 +130,4 @@ Specifically, an OpenPGP private keystore implements two primitives:
1. Given private key material whose algorithm supports decryption, it can decrypt a *session key*.
2. Given private key material whose algorithm supports signing, it can calculate a *cryptographic signature* for a hash digest.
These essential operations require access only to the component keys and their associated private key material, specifically [Secret-Key packets](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-secret-key-packet-formats). Additional packets, such as binding signatures, are not required.
These essential operations require access only to the component keys and their associated private key material, specifically [Secret-Key packets](https://www.rfc-editor.org/rfc/rfc9580.html#name-secret-key-packet-formats). Additional packets, such as binding signatures, are not required.

14
book/source/signatures.md
View file

@ -22,7 +22,7 @@ Within OpenPGP, the term *{term}`signature<OpenPGP Signature Packet>`* can have
A {term}`cryptographic signature`
```
- **{term}`OpenPGP signature packets<OpenPGP signature packet>`**: Defined in the [OpenPGP standard](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-signature-packet-type-id-2), these {term}`packets<Packet>` combine a raw {term}`cryptographic signature` along with a *{term}`type<OpenPGP Signature Type>`* designation and additional {term}`metadata`.
- **{term}`OpenPGP signature packets<OpenPGP signature packet>`**: Defined in the [OpenPGP standard](https://www.rfc-editor.org/rfc/rfc9580.html#name-signature-packet-type-id-2), these {term}`packets<Packet>` combine a raw {term}`cryptographic signature` along with a *{term}`type<OpenPGP Signature Type>`* designation and additional {term}`metadata`.
```{figure} plain_svg/OpenPGP_Signature_packet.svg
:name: fig-signature-packet-0
@ -36,7 +36,7 @@ In this document, "{term}`signature<OpenPGP Signature Packet>`" will refer to {t
(signature-types)=
## Signature types in OpenPGP
The OpenPGP standard defines a set of [Signature types](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-signature-types), each identified by a numerical *{term}`signature type ID`*. {term}`Signature types<OpenPGP Signature Type>` define the purpose of a {term}`signature packet<OpenPGP Signature Packet>` and how it should be interpreted.
The OpenPGP standard defines a set of [Signature types](https://www.rfc-editor.org/rfc/rfc9580.html#name-signature-types), each identified by a numerical *{term}`signature type ID`*. {term}`Signature types<OpenPGP Signature Type>` define the purpose of a {term}`signature packet<OpenPGP Signature Packet>` and how it should be interpreted.
{term}`Signature types<OpenPGP Signature Type>` can be predominantly classified in two ways:
@ -130,11 +130,11 @@ Verifying a {term}`signature<OpenPGP Signature Packet>` in OpenPGP
In the OpenPGP protocol, {term}`signature subpackets<OpenPGP Signature Subpacket>` enhance the expressiveness of a {term}`signature<OpenPGP Signature Packet>` beyond what is conveyed by just the bare {term}`cryptographic signature` and the {term}`signature type ID`. These {term}`subpackets<OpenPGP Signature Subpacket>`, introduced in [RFC 2440](https://datatracker.ietf.org/doc/html/rfc2440), are essential for embedding additional {term}`metadata` within {term}`signature packets<OpenPGP Signature Packet>`.
{term}`Signature subpackets<OpenPGP Signature subpacket>` serve as sub-elements within {term}`signature packets<OpenPGP Signature Packet>`, providing extra context and meaning to a {term}`signature<OpenPGP Signature Packet>`.
They are formatted as key-value pairs, where the keys are defined as [subpacket type IDs](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-signature-subpacket-types-r) by the {term}`RFC`. The {term}`RFC` also provides the format and interpretation of the values.
They are formatted as key-value pairs, where the keys are defined as [subpacket type IDs](https://www.rfc-editor.org/rfc/rfc9580.html#name-openpgp-signature-subpacket) by the {term}`RFC`. The {term}`RFC` also provides the format and interpretation of the values.
### Examples of signature subpackets
- The [*issuer fingerprint*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#issuer-fingerprint-subpacket) {term}`subpacket<OpenPGP Signature Subpacket>` encodes the {term}`fingerprint<OpenPGP Fingerprint>` of the {term}`component key` that issued the {term}`signature<OpenPGP Signature Packet>`.
- The [*key flags*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags) {term}`subpacket<OpenPGP Signature Subpacket>` defines the {term}`capabilities<capability>` that are assigned to a {term}`component key` within a {term}`certificate<OpenPGP Certificate>`.
- The [*issuer fingerprint*](https://www.rfc-editor.org/rfc/rfc9580.html#issuer-fingerprint-subpacket) {term}`subpacket<OpenPGP Signature Subpacket>` encodes the {term}`fingerprint<OpenPGP Fingerprint>` of the {term}`component key` that issued the {term}`signature<OpenPGP Signature Packet>`.
- The [*key flags*](https://www.rfc-editor.org/rfc/rfc9580.html#name-key-flags) {term}`subpacket<OpenPGP Signature Subpacket>` defines the {term}`capabilities<capability>` that are assigned to a {term}`component key` within a {term}`certificate<OpenPGP Certificate>`.
(subpacket-areas)=
### Hashed and unhashed signature subpackets
@ -146,7 +146,7 @@ They are formatted as key-value pairs, where the keys are defined as [subpacket
The majority of {term}`signature subpackets<OpenPGP Signature Subpacket>` are stored in the {term}`hashed area`.
For detailed information and specifications, refer to [Hashed vs. Unhashed Subpackets](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-hashed-vs-unhashed-subpacke) in the OpenPGP {term}`RFC`.
For detailed information and specifications, refer to [Hashed vs. Unhashed Subpackets](https://www.rfc-editor.org/rfc/rfc9580.html#name-hashed-vs-unhashed-subpacke) in the OpenPGP {term}`RFC`.
(criticality-of-subpackets)=
### Criticality of subpackets
@ -157,4 +157,4 @@ This mechanism accounts for different {term}`OpenPGP implementations<OpenPGP Imp
Consider a scenario where an {term}`implementation<OpenPGP Implementation>` does not recognize a {term}`subpacket<OpenPGP Signature Subpacket>` indicating {term}`signature<OpenPGP Signature Packet>` {term}`expiration`. Without understanding this concept, the {term}`implementation<OpenPGP Implementation>` might erroneously accept an already {term}`expired<Expiration>` {term}`signature<OpenPGP Signature Packet>`. By marking the {term}`signature expiration time subpacket` as {term}`critical<Criticality Flag>`, the creator of the {term}`signature<OpenPGP Signature Packet>` ensures that any recipient who cannot process this {term}`subpacket<OpenPGP Signature Subpacket>` will reject the {term}`signature<OpenPGP Signature Packet>` as {term}`invalid<Validation>`.
For specific guidelines on which {term}`subpackets<OpenPGP Signature Subpacket>` should be marked as {term}`critical<Criticality Flag>`, refer to the {term}`RFC` sections [5.2.3.11](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-signature-creation-time) to [5.2.3.36](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-intended-recipient-fingerpr).
For specific guidelines on which {term}`subpackets<OpenPGP Signature Subpacket>` should be marked as {term}`critical<Criticality Flag>`, refer to the {term}`RFC` sections [5.2.3.11](https://www.rfc-editor.org/rfc/rfc9580.html#name-signature-creation-time) to [5.2.3.36](https://www.rfc-editor.org/rfc/rfc9580.html#name-intended-recipient-fingerpr).

46
book/source/signing_components.md
View file

@ -35,7 +35,7 @@ This chapter expands on topics introduced in the [](certificates) chapter.
{term}`Self-signatures<Self-signature>` are issued by the {term}`certificate's owner<Certificate Holder>` using the {term}`certificate<OpenPGP Certificate>`'s {term}`primary key<OpenPGP Primary Key>`.
```{note}
No [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags) is required to issue {term}`self-signatures<Self-signature>`. An {term}`OpenPGP primary key` can issue {term}`self-signatures<Self-signature>` by default.
No [key flag](https://www.rfc-editor.org/rfc/rfc9580.html#name-key-flags) is required to issue {term}`self-signatures<Self-signature>`. An {term}`OpenPGP primary key` can issue {term}`self-signatures<Self-signature>` by default.
```
### Third-party signatures
@ -49,29 +49,29 @@ Third-party signatures are used to make specific statements:
- {term}`revoking<Revocation>`, and thus {term}`invalidating<Validation>`, prior {term}`third-party signature` statements
```{note}
The **{term}`certify others<Certification Key Flag>`** [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags) (`0x01`) is required to issue {term}`third-party signatures<Third-party Signature>`. By convention[^primary-certification], only the {term}`certificate<OpenPGP Certificate>`'s {term}`primary key<OpenPGP Primary Key>` can hold this {term}`key flag`.
The **{term}`certify others<Certification Key Flag>`** [key flag](https://www.rfc-editor.org/rfc/rfc9580.html#name-key-flags) (`0x01`) is required to issue {term}`third-party signatures<Third-party Signature>`. By convention[^primary-certification], only the {term}`certificate<OpenPGP Certificate>`'s {term}`primary key<OpenPGP Primary Key>` can hold this {term}`key flag`.
```
[^primary-certification]: Most current {term}`implementations<OpenPGP Implementation>` assume that only the {term}`primary key<OpenPGP Primary Key>` may hold the *{term}`certify others<Certification Key Flag>`* {term}`key flag`, although this is not specified in the {term}`RFC`.
### Distinct functions of self-signatures and third-party signatures
The meaning of an {term}`OpenPGP signature<OpenPGP Signature Packet>` depends significantly on its {term}`issuer`. {term}`Self-signatures<Self-signature>` and {term}`third-party signatures<Third-party Signature>`, even when of the same [signature type](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-signature-types), serve distinct functions. For example:
The meaning of an {term}`OpenPGP signature<OpenPGP Signature Packet>` depends significantly on its {term}`issuer`. {term}`Self-signatures<Self-signature>` and {term}`third-party signatures<Third-party Signature>`, even when of the same [signature type](https://www.rfc-editor.org/rfc/rfc9580.html#name-signature-types), serve distinct functions. For example:
- {term}`Certifying self-signatures<Certifying Self-signature>` ({term}`type IDs<Signature Type ID>` `0x10` - `0x13`) bind a {term}`User ID` to a {term}`certificate<OpenPGP Certificate>`.
- {term}`Third-party signatures<Third-party Signature>` of the same {term}`type IDs<Signature Type ID>` endorse the {term}`authenticity<Authentication>` of a {term}`User ID` on another user's {term}`certificate<OpenPGP Certificate>`.
In another instance:
- *When issued as a {term}`self-signature`*, a [direct key signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-direct-key-signature-type-i) sets {term}`preferences<Algorithm Preferences>` and advertises {term}`features<Features Subpacket>` applicable to the entire {term}`certificate<OpenPGP Certificate>`.
- *When issued by a {term}`third party<Third-party Signature>`*, especially when it carries a [trust signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-trust-signature) {term}`subpacket<OpenPGP Signature Subpacket>`, a similar {term}`direct key signature` {term}`delegates<Delegation>` trust to the signed {term}`certificate<OpenPGP Certificate>`. This may designate the signed {term}`certificate<OpenPGP Certificate>` as a {term}`trust anchor` within the {term}`issuer`'s {term}`Web of Trust`.
- *When issued as a {term}`self-signature`*, a [direct key signature](https://www.rfc-editor.org/rfc/rfc9580.html#name-direct-key-signature-type-i) sets {term}`preferences<Algorithm Preferences>` and advertises {term}`features<Features Subpacket>` applicable to the entire {term}`certificate<OpenPGP Certificate>`.
- *When issued by a {term}`third party<Third-party Signature>`*, especially when it carries a [trust signature](https://www.rfc-editor.org/rfc/rfc9580.html#name-trust-signature) {term}`subpacket<OpenPGP Signature Subpacket>`, a similar {term}`direct key signature` {term}`delegates<Delegation>` trust to the signed {term}`certificate<OpenPGP Certificate>`. This may designate the signed {term}`certificate<OpenPGP Certificate>` as a {term}`trust anchor` within the {term}`issuer`'s {term}`Web of Trust`.
(binding-signatures)=
## Self-signatures in certificate formation and management
{term}`Self-signatures<Self-signature>` play a crucial role in forming and managing the structure of {term}`OpenPGP certificates<OpenPGP certificate>`. These act as *{term}`binding signatures<Binding Signature>`*, joining {term}`components<Component>` and embedding {term}`metadata`.
Internally, an {term}`OpenPGP certificate` is essentially a series of {term}`packets<Packet>` strung sequentially. When a {term}`certificate<OpenPGP Certificate>` is stored in a file format known as a [transferable public key](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-transferable-public-keys), {term}`packets<Packet>` can be easily added or removed.
Internally, an {term}`OpenPGP certificate` is essentially a series of {term}`packets<Packet>` strung sequentially. When a {term}`certificate<OpenPGP Certificate>` is stored in a file format known as a [transferable public key](https://www.rfc-editor.org/rfc/rfc9580.html#name-transferable-public-keys), {term}`packets<Packet>` can be easily added or removed.
To safeguard against unauthorized additions or alterations of {term}`components<Component>`, OpenPGP uses {term}`cryptographic signatures<Cryptographic Signature>`. These validate that all {term}`components<Component>`, such as {term}`subkeys<OpenPGP Subkey>` or [identity components](identity-components), were linked to the {term}`OpenPGP certificate` by its {term}`owner<Certificate Holder>`, using the {term}`primary key<OpenPGP Primary Key>`. While anyone can still store unrelated elements to a {term}`certificate<OpenPGP Certificate>` dataset, {term}`OpenPGP implementations<OpenPGP implementation>` will reject them if they lack a {term}`valid<Validation>` cryptographic connection with the {term}`certificate<OpenPGP Certificate>`.
@ -87,11 +87,11 @@ However, there are legitimate instances in which third parties add "unbound" {te
(bind-subkey)=
### Binding subkeys to a certificate
{term}`Subkeys<OpenPGP Subkey>` are linked to {term}`OpenPGP certificates<OpenPGP certificate>` via a [subkey binding signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#sigtype-subkey-binding) ({term}`type ID<Signature Type ID>` `0x18`). This {term}`signature type<OpenPGP Signature Type>` indicates the association of the {term}`primary key<OpenPGP Primary Key>` with the {term}`subkey<OpenPGP Subkey>`.
{term}`Subkeys<OpenPGP Subkey>` are linked to {term}`OpenPGP certificates<OpenPGP certificate>` via a [subkey binding signature](https://www.rfc-editor.org/rfc/rfc9580.html#sigtype-subkey-binding) ({term}`type ID<Signature Type ID>` `0x18`). This {term}`signature type<OpenPGP Signature Type>` indicates the association of the {term}`primary key<OpenPGP Primary Key>` with the {term}`subkey<OpenPGP Subkey>`.
A {term}`subkey binding signature` binds a {term}`subkey<OpenPGP Subkey>` to a {term}`primary key<OpenPGP Primary Key>`, and it embeds {term}`metadata` into the {term}`signature packet<OpenPGP Signature Packet>`. Once generated, the {term}`subkey binding signature` {term}`packet` is stored in the {term}`certificate<OpenPGP Certificate>` directly after the {term}`subkey<OpenPGP Subkey>` it binds.
{term}`Subkeys<OpenPGP Subkey>` designated for signing purposes, identified by the *{term}`signing<Signing Key Flag>`* [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags), represent a unique category and are handled differently. See {numref}`bind-signing-subkey`.
{term}`Subkeys<OpenPGP Subkey>` designated for signing purposes, identified by the *{term}`signing<Signing Key Flag>`* [key flag](https://www.rfc-editor.org/rfc/rfc9580.html#name-key-flags), represent a unique category and are handled differently. See {numref}`bind-signing-subkey`.
```{figure} plain_svg/subkey_binding_signature.svg
:name: fig-subkey-binding-signature
@ -100,7 +100,7 @@ A {term}`subkey binding signature` binds a {term}`subkey<OpenPGP Subkey>` to a {
Linking an {term}`OpenPGP subkey` to the {term}`primary key<OpenPGP Primary Key>` with a {term}`binding signature`
```
{term}`Metadata` for the {term}`subkey`, such as the [*key expiration time*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#key-expiration-subpacket) and {term}`capabilities<Capability>` set by [*key flags*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#key-flags), are included in {term}`subpackets<OpenPGP Signature Subpacket>` within the {term}`subkey binding signature` {term}`packet`.
{term}`Metadata` for the {term}`subkey`, such as the [*key expiration time*](https://www.rfc-editor.org/rfc/rfc9580.html#key-expiration-subpacket) and {term}`capabilities<Capability>` set by [*key flags*](https://www.rfc-editor.org/rfc/rfc9580.html#key-flags), are included in {term}`subpackets<OpenPGP Signature Subpacket>` within the {term}`subkey binding signature` {term}`packet`.
```{note}
The {term}`validity<Validation>` of a {term}`subkey<OpenPGP Subkey>` is intrinsically linked to that of the {term}`primary key<OpenPGP Primary Key>`. An {term}`expired<Expiration>` {term}`primary key<OpenPGP Primary Key>` renders any associated {term}`subkey<OpenPGP Subkey>` {term}`invalid<Validation>`, regardless of the {term}`subkey<OpenPGP Subkey>`'s own {term}`expiration` setting.
@ -119,8 +119,8 @@ This mutual binding is crucial for security. Without it, an individual (e.g., Al
Alice could thus claim to have issued {term}`signatures<OpenPGP Signature Packet>` which were actually issued by Bob.
To prevent such scenarios, where an attacker might wrongfully "adopt" a victim's {term}`signing subkey<OpenPGP Signing Subkey>`, a dual-layer of {term}`signatures<OpenPGP Signature Packet>` is used:
- the [subkey binding signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#sigtype-subkey-binding) ({term}`type ID<Signature Type ID>` `0x18`), which is issued by the {term}`certificate<OpenPGP Certificate>`'s {term}`primary key<OpenPGP Primary Key>`
- the [primary key binding signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#sigtype-primary-binding) ({term}`type ID<Signature Type ID>` `0x19`), created by the {term}`subkey<OpenPGP Subkey>` itself. This is informally known as an embedded "{term}`back signature<Primary Key Binding Signature>`," because the {term}`subkey<OpenPGP Subkey>`'s {term}`signature<OpenPGP Signature Packet>` points back to the {term}`primary key<OpenPGP Primary Key>`.
- the [subkey binding signature](https://www.rfc-editor.org/rfc/rfc9580.html#sigtype-subkey-binding) ({term}`type ID<Signature Type ID>` `0x18`), which is issued by the {term}`certificate<OpenPGP Certificate>`'s {term}`primary key<OpenPGP Primary Key>`
- the [primary key binding signature](https://www.rfc-editor.org/rfc/rfc9580.html#sigtype-primary-binding) ({term}`type ID<Signature Type ID>` `0x19`), created by the {term}`subkey<OpenPGP Subkey>` itself. This is informally known as an embedded "{term}`back signature<Primary Key Binding Signature>`," because the {term}`subkey<OpenPGP Subkey>`'s {term}`signature<OpenPGP Signature Packet>` points back to the {term}`primary key<OpenPGP Primary Key>`.
```{figure} plain_svg/subkey_binding_signatur_for_signing_sk.svg
:name: fig-subkey-binding-signature-for-signing-subkeys
@ -138,7 +138,7 @@ The {term}`back signature<Primary Key Binding Signature>` signifies the mutualit
To bind the {term}`User ID` `Alice Adams <alice@example.org>` to her {term}`OpenPGP certificate` (`AAA1 8CBB 2546 85C5 8358 3205 63FD 37B6 7F33 00F9 FB0E C457 378C D29F 1026 98B3`), Alice would use a {term}`certification signature<Certifying Self-signature>`.
There are four types of *{term}`certifying self-signature`*. The most commonly used {term}`type<Signature Type ID>` for {term}`binding` {term}`User IDs<User ID>` is the [positive certification](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#sigtype-positive-cert) ({term}`type ID<Signature Type ID>` `0x13`). Alternatively, {term}`type<Signature Type ID>` `0x10`, `0x11`, or `0x12` might be used. This {term}`binding signature` must be issued by the {term}`primary key<OpenPGP Primary Key>`.
There are four types of *{term}`certifying self-signature`*. The most commonly used {term}`type<Signature Type ID>` for {term}`binding` {term}`User IDs<User ID>` is the [positive certification](https://www.rfc-editor.org/rfc/rfc9580.html#sigtype-positive-cert) ({term}`type ID<Signature Type ID>` `0x13`). Alternatively, {term}`type<Signature Type ID>` `0x10`, `0x11`, or `0x12` might be used. This {term}`binding signature` must be issued by the {term}`primary key<OpenPGP Primary Key>`.
The {term}`certifying self-signature` {term}`packet` – calculated over the {term}`primary key<OpenPGP Primary Key>`, {term}`User ID`, and {term}`metadata` of the {term}`signature packet<OpenPGP Signature Packet>` – is added to the {term}`certificate<OpenPGP Certificate>`, directly following the {term}`User ID` {term}`packet`.
@ -171,12 +171,12 @@ The types of {term}`metadata` typically associated with the {term}`certificate<O
(direct-key-signature)=
#### Direct key signature
A [*direct key signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-direct-key-signature-type-i) serves as the [preferred mechanism](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-5.2.3.10-9) in OpenPGP v6 for defining {term}`metadata` for the entire {term}`certificate<OpenPGP Certificate>`, by associating it with the {term}`primary key<OpenPGP Primary Key>`.
A [*direct key signature*](https://www.rfc-editor.org/rfc/rfc9580.html#name-direct-key-signature-type-i) serves as the [preferred mechanism](https://www.rfc-editor.org/rfc/rfc9580.html#section-5.2.3.10-9) in OpenPGP v6 for defining {term}`metadata` for the entire {term}`certificate<OpenPGP Certificate>`, by associating it with the {term}`primary key<OpenPGP Primary Key>`.
(primary-user-id-binding)=
#### Self-signature binding to primary User ID
In OpenPGP v4, another mechanism was often used for {term}`metadata` management: integrating global {term}`certificate<OpenPGP Certificate>` {term}`metadata` within a {term}`User ID binding signature`. This is specifically evident in the {term}`binding signature` of the [*primary* User ID](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-primary-user-id) of the {term}`OpenPGP certificate`.
In OpenPGP v4, another mechanism was often used for {term}`metadata` management: integrating global {term}`certificate<OpenPGP Certificate>` {term}`metadata` within a {term}`User ID binding signature`. This is specifically evident in the {term}`binding signature` of the [*primary* User ID](https://www.rfc-editor.org/rfc/rfc9580.html#name-primary-user-id) of the {term}`OpenPGP certificate`.
This method results in the {term}`primary User ID binding signature` containing a mix of {term}`metadata`: some specific to that {term}`User ID` and some applicable to the {term}`certificate` globally.
@ -189,9 +189,9 @@ Given the widespread adoption of this mechanism in existing {term}`OpenPGP certi
There are several types of {term}`revocation signatures<Revocation Self-signature>`, each serving a specific purpose:
- A [**key revocation signature**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-revocation-signature-ty) ({term}`type ID<Signature Type ID>` `0x20`) marks a {term}`primary key<OpenPGP Primary Key>` as {term}`revoked<Revocation>`.
- A [**subkey revocation signature**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-subkey-revocation-signature) ({term}`type ID<Signature Type ID>` `0x28`) {term}`invalidates<Validation>` the {term}`binding of a subkey<Subkey Binding Signature>`.
- A [**certification revocation**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-certification-revocation-si) ({term}`type ID<Signature Type ID>` `0x30`) {term}`invalidates<Validation>` the {term}`binding` of a {term}`User ID` or {term}`User Attribute`.
- A [**key revocation signature**](https://www.rfc-editor.org/rfc/rfc9580.html#name-key-revocation-signature-ty) ({term}`type ID<Signature Type ID>` `0x20`) marks a {term}`primary key<OpenPGP Primary Key>` as {term}`revoked<Revocation>`.
- A [**subkey revocation signature**](https://www.rfc-editor.org/rfc/rfc9580.html#name-subkey-revocation-signature) ({term}`type ID<Signature Type ID>` `0x28`) {term}`invalidates<Validation>` the {term}`binding of a subkey<Subkey Binding Signature>`.
- A [**certification revocation**](https://www.rfc-editor.org/rfc/rfc9580.html#name-certification-revocation-si) ({term}`type ID<Signature Type ID>` `0x30`) {term}`invalidates<Validation>` the {term}`binding` of a {term}`User ID` or {term}`User Attribute`.
Common scenarios for using {term}`revocations<Revocation>` include marking {term}`certificates<OpenPGP Certificate>` or individual {term}`subkeys<OpenPGP Subkey>` as unusable (e.g., when the {term}`private key<Transferable Secret Key>` has been compromised or replaced) or declaring {term}`User IDs<User ID>` as no longer {term}`valid<Validation>`.
@ -201,12 +201,12 @@ Common scenarios for using {term}`revocations<Revocation>` include marking {term
{term}`Revocations<Revocation>` are used to mark {term}`components<Component>` or {term}`signatures<OpenPGP Signature Packet>` as {term}`invalid<Validation>`.
```
Note: {term}`certification signatures<Certification>` [can be made irrevocable](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-revocable).
Note: {term}`certification signatures<Certification>` [can be made irrevocable](https://www.rfc-editor.org/rfc/rfc9580.html#name-revocable).
(hard-vs-soft-revocations)=
#### Hard vs soft revocations
{term}`Revocation signatures<Revocation Self-signature>` often include a [*Reason for Revocation* subpacket](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-reason-for-revocation), with a code specifying *why* the {term}`revocation<Revocation Self-signature>` was issued. This code determines whether the {term}`revocation` is considered *soft* or *hard*.
{term}`Revocation signatures<Revocation Self-signature>` often include a [*Reason for Revocation* subpacket](https://www.rfc-editor.org/rfc/rfc9580.html#name-reason-for-revocation), with a code specifying *why* the {term}`revocation<Revocation Self-signature>` was issued. This code determines whether the {term}`revocation` is considered *soft* or *hard*.
- **{term}`Soft revocation`**: This is typically used for graceful or planned {term}`invalidation<Validation>` of {term}`components<Component>`, such as retiring or updating {term}`components<Component>`. It {term}`invalidates<Validation>` the {term}`component` from the {term}`revocation signature<Revocation Self-signature>`'s {term}`creation time`, but earlier uses remain {term}`valid<Validation>`. Soft revocations can be reversed with a new {term}`self-signature`.
- **{term}`Hard revocation`**: This irrevocably invalidates the {term}`component`, affecting all past and future uses. It is typically used to signal compromise of {term}`secret key material<Private Key Material>`.
@ -231,12 +231,12 @@ Other users may or may not decide to rely on Alice's statement to determine the
(delegation)=
### Trust signatures: delegating authentication
OpenPGP uses [*trust signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#trust-signature-subpacket) {term}`subpackets<OpenPGP Signature Subpacket>` to {term}`delegate<Delegation>` {term}`authentication` decisions, designating the recipient {term}`certificate<OpenPGP Certificate>` as a "{term}`trusted introducer`" (or a {term}`trust anchor`) for the user. This includes specifying {term}`trust depth` (or level) for transitive {term}`delegations<Delegation>` and quantifying trust with numerical values, indicating the extent of reliance on the {term}`introducer<Trusted Introducer>`'s {term}`certifications<Certification>`.
OpenPGP uses [*trust signature*](https://www.rfc-editor.org/rfc/rfc9580.html#trust-signature-subpacket) {term}`subpackets<OpenPGP Signature Subpacket>` to {term}`delegate<Delegation>` {term}`authentication` decisions, designating the recipient {term}`certificate<OpenPGP Certificate>` as a "{term}`trusted introducer`" (or a {term}`trust anchor`) for the user. This includes specifying {term}`trust depth` (or level) for transitive {term}`delegations<Delegation>` and quantifying trust with numerical values, indicating the extent of reliance on the {term}`introducer<Trusted Introducer>`'s {term}`certifications<Certification>`.
{term}`Trust signature` {term}`subpackets<OpenPGP Signature Subpacket>` are applicable in {term}`third-party signatures<Third-party Signature>`, more specifically:
- {term}`identity certification signatures<Identity Certification>` ({term}`type ID<Signature Type ID>` `0x10` - `0x13`)
- [direct key signatures](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-direct-key-signature-type-i) ({term}`type ID<Signature Type ID>` `0x1F`)
- [direct key signatures](https://www.rfc-editor.org/rfc/rfc9580.html#name-direct-key-signature-type-i) ({term}`type ID<Signature Type ID>` `0x1F`)
(trust-level)=
#### Trust depth/level
@ -259,7 +259,7 @@ A higher value indicates greater degree of reliance. This quantification aids {t
(trust-scope)=
#### Limiting delegation scope
When using *{term}`trust signature`* {term}`subpackets<OpenPGP Signature Subpacket>`, a {term}`delegation` can be limited to {term}`identities<Identity>` that match a [*regular expression*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#regex-subpacket).
When using *{term}`trust signature`* {term}`subpackets<OpenPGP Signature Subpacket>`, a {term}`delegation` can be limited to {term}`identities<Identity>` that match a [*regular expression*](https://www.rfc-editor.org/rfc/rfc9580.html#regex-subpacket).
With this mechanism, for example, it is possible to {term}`delegate<Delegation>` {term}`authentication` decisions only for {term}`User IDs<User ID>` that match the email domain of an organization.
@ -274,4 +274,4 @@ The {term}`OpenPGP RFC<RFC>` doesn't specify exactly how {term}`Web of Trust` ca
### Revoking third-party signatures
To reverse a previously issued {term}`third-party signature`, the {term}`issuer` can generate a [*certification revocation signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-certification-revocation-si) ({term}`type ID<Signature Type ID>` `0x30`). The {term}`revocation` must be issued by the same {term}`key<Component Key>` that created the original {term}`signature<OpenPGP Signature Packet>` or, in deprecated practice, by a designated [Revocation Key](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-revocation-key).
To reverse a previously issued {term}`third-party signature`, the {term}`issuer` can generate a [*certification revocation signature*](https://www.rfc-editor.org/rfc/rfc9580.html#name-certification-revocation-si) ({term}`type ID<Signature Type ID>` `0x30`). The {term}`revocation` must be issued by the same {term}`key<Component Key>` that created the original {term}`signature<OpenPGP Signature Packet>` or, in deprecated practice, by a designated [Revocation Key](https://www.rfc-editor.org/rfc/rfc9580.html#name-revocation-key-deprecated).

10
book/source/signing_data.md
View file

@ -12,7 +12,7 @@ it does not automatically signal if the expected party indeed controls the {term
[^sign-auth]: Other signing solutions, like [signify](https://flak.tedunangst.com/post/signify), focus on pure signing without strong {term}`authentication` of the {term}`signer`'s {term}`identity`.
{term}`Data signatures<Data Signature>` can only be issued by {term}`component keys<Component Key>` with the *{term}`signing<Signing Key Flag>`* [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags).
{term}`Data signatures<Data Signature>` can only be issued by {term}`component keys<Component Key>` with the *{term}`signing<Signing Key Flag>`* [key flag](https://www.rfc-editor.org/rfc/rfc9580.html#name-key-flags).
Note that {term}`data signatures<Data Signature>` are distinct from [](/signing_components), which are used to form and maintain {term}`certificates<OpenPGP Certificate>`, as well as to {term}`certify<Certification>` {term}`identities<Identity>` on {term}`certificates<OpenPGP Certificate>`.
@ -21,8 +21,8 @@ Note that {term}`data signatures<Data Signature>` are distinct from [](/signing_
{term}`OpenPGP data signatures<Data Signature>` use one of two [signature types](signature-types):
- [**Binary signature**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#sigtype-binary) ({term}`type ID<Signature Type ID>` `0x00`): This is the standard {term}`signature type` for binary data and is typically used for files or data streams. {term}`Binary signatures<Binary Signature>` are calculated over the data without any modifications or transformations.
- [**Text signature**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-signature-of-a-canonical-te) ({term}`type ID<Signature Type ID>` `0x01`): Used for textual data, such as email bodies. When calculating a {term}`text signature`, the data is first normalized by converting line endings into a canonical form (`<CR><LF>`). This approach mitigates issues caused by platform-specific text encodings. This is especially important for detached and {term}`cleartext signatures<Cleartext Signature>`, where the message file might undergo re-encoding between the creation and {term}`verification` of the {term}`signature<OpenPGP Signature Packet>`.
- [**Binary signature**](https://www.rfc-editor.org/rfc/rfc9580.html#sigtype-binary) ({term}`type ID<Signature Type ID>` `0x00`): This is the standard {term}`signature type` for binary data and is typically used for files or data streams. {term}`Binary signatures<Binary Signature>` are calculated over the data without any modifications or transformations.
- [**Text signature**](https://www.rfc-editor.org/rfc/rfc9580.html#name-text-signature-type-id-0x01) ({term}`type ID<Signature Type ID>` `0x01`): Used for textual data, such as email bodies. When calculating a {term}`text signature`, the data is first normalized by converting line endings into a canonical form (`<CR><LF>`). This approach mitigates issues caused by platform-specific text encodings. This is especially important for detached and {term}`cleartext signatures<Cleartext Signature>`, where the message file might undergo re-encoding between the creation and {term}`verification` of the {term}`signature<OpenPGP Signature Packet>`.
{term}`Data signatures<Data Signature>` are generated by {term}`hashing<Hash Digest>` the message content along with the {term}`metadata` in the {term}`OpenPGP signature packet`, and calculating a {term}`cryptographic signature` over that {term}`hash<Hash Digest>`. The resulting {term}`cryptographic signature` is stored in the {term}`signature packet<OpenPGP Signature Packet>`.
@ -99,12 +99,12 @@ These features are particularly beneficial in scenarios where signed messages ar
The {term}`cleartext signature framework` includes specific text normalization procedures to ensure the integrity and clarity of the message:
- **Escaping dashes**: The framework implements a method of [dash-escaped text](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-dash-escaped-text) within the message. Dash-escaping ensures that the parser correctly distinguishes between the armor headers, which are part of the {term}`signature<OpenPGP Signature Packet>`'s structure, and any lines in the message that happen to start with a dash.
- **Escaping dashes**: The framework implements a method of [dash-escaped text](https://www.rfc-editor.org/rfc/rfc9580.html#name-dash-escaped-text) within the message. Dash-escaping ensures that the parser correctly distinguishes between the armor headers, which are part of the {term}`signature<OpenPGP Signature Packet>`'s structure, and any lines in the message that happen to start with a dash.
- **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 (`<CR><LF>`). This ensures that the {term}`signature<OpenPGP Signature Packet>` remains valid regardless of the text format of the receiving {term}`implementation<OpenPGP Implementation>`.
### Pitfalls
Despite their widespread adoption, {term}`cleartext signatures<Cleartext Signature>` 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<Inline Signature>` and {term}`detached signature` forms are advised.
Despite their widespread adoption, {term}`cleartext signatures<Cleartext Signature>` have their limitations and are sometimes viewed as a "legacy method"[^csf-gnupg]. The {term}`RFC` details the [pitfalls of cleartext signatures](https://www.rfc-editor.org/rfc/rfc9580.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<Inline Signature>` and {term}`detached signature` forms are advised.
[^csf-gnupg]: https://lists.gnupg.org/pipermail/gnupg-devel/2023-November/035428.html

2
book/source/verification.md
View file

@ -98,7 +98,7 @@ Similarly, certification signatures over third-party certificates require the is
Self-qualifying signatures have no such limitations.
For example, a certificate consisting only of a primary key and a single key-revocation self-signature contains everything needed to verify the revocation, as key-revocation self-signatures are self-qualifying.
This construct is referred to as a [revocation certificate](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-openpgp-v6-revocation-certi).
This construct is referred to as a [revocation certificate](https://www.rfc-editor.org/rfc/rfc9580.html#name-openpgp-version-6-revocatio).
On the other hand, to verify a data signature over a text document, an implementation needs to verify not only the data signature itself, but also the binding signature (and back-signature) of the signing subkey which qualifies the signing subkey.

78
book/source/zoom/certificates.md
View file

@ -71,8 +71,8 @@ This command combines the contents of `alice.pub-0--PublicKey` and `alice.pub-1-
This version of Alice's certificate contains just two packets:
- the [*Public-Key packet*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-public-key-packet-formats) for the primary key, and
- a [*Direct Key Signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#sigtype-direct-key), which is a self-signature that binds metadata to the primary key.
- the [*Public-Key packet*](https://www.rfc-editor.org/rfc/rfc9580.html#name-public-key-packet-formats) for the primary key, and
- a [*Direct Key Signature*](https://www.rfc-editor.org/rfc/rfc9580.html#sigtype-direct-key), which is a self-signature that binds metadata to the primary key.
This is the shape of the packets we'll explore in the subsequent sections:
@ -112,7 +112,7 @@ This will allow us to gain a detailed understanding of the packet contents.
(zoom-public-key)=
### Public-Key packet
The output begins with a (primary) [Public-Key packet](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-public-key-packet-formats):
The output begins with a (primary) [Public-Key packet](https://www.rfc-editor.org/rfc/rfc9580.html#name-public-key-packet-formats):
```text
Public-Key Packet, new CTB, 2 header bytes + 42 bytes
@ -138,27 +138,27 @@ The Public-Key packet consists primarily of the cryptographic key data. Let's lo
**OpenPGP packet syntax**
The first fields of a packet are governed by the general [Packet Syntax](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-packet-syntax):
The first fields of a packet are governed by the general [Packet Syntax](https://www.rfc-editor.org/rfc/rfc9580.html#name-packet-syntax):
- `CTB: 0xc6`[^CTB]: This is the [packet type ID](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-packet-headers) for this packet. The binary representation of the value `0xc6` is `11000110`. The first two bits show that the packet is in *OpenPGP packet format* (as opposed to in *Legacy packet format*) and the remaining 6 bits encode the type ID value, which is "6." This type ID value corresponds to a Public-Key packet, as listed in the [packet type IDs](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-packet-types).
- `CTB: 0xc6`[^CTB]: This is the [packet type ID](https://www.rfc-editor.org/rfc/rfc9580.html#name-packet-headers) for this packet. The binary representation of the value `0xc6` is `11000110`. The first two bits show that the packet is in *OpenPGP packet format* (as opposed to in *Legacy packet format*) and the remaining 6 bits encode the type ID value, which is "6." This type ID value corresponds to a Public-Key packet, as listed in the [packet type IDs](https://www.rfc-editor.org/rfc/rfc9580.html#name-packet-types).
- `length: 0x2a`: This indicates the remaining length of this packet.
**Public-Key packet syntax**
The packet type ID ("6") defines the semantics of the following data within the packet. In this case, it is a Public-Key packet, which is a kind of [Key Material Packet](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-material-packets).
The packet type ID ("6") defines the semantics of the following data within the packet. In this case, it is a Public-Key packet, which is a kind of [Key Material Packet](https://www.rfc-editor.org/rfc/rfc9580.html#name-key-material-packets).
- `version: 0x06`: The key material is in version 6 format. This means that the next part of the packet adheres to the structure of [Version 6 Public Keys](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-version-6-public-keys).
- `version: 0x06`: The key material is in version 6 format. This means that the next part of the packet adheres to the structure of [Version 6 Public Keys](https://www.rfc-editor.org/rfc/rfc9580.html#name-version-6-public-keys).
- `creation_time: 0x6516eaa6`: This field represents the key's creation time. (See also [Time Fields](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-time-fields)).
- `creation_time: 0x6516eaa6`: This field represents the key's creation time. (See also [Time Fields](https://www.rfc-editor.org/rfc/rfc9580.html#name-time-fields)).
- `pk_algo: 0x1b`: This corresponds to the key's public-key algorithm ID, which has a decimal value of 27. Refer to the list of [Public-Key Algorithms](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-public-key-algorithms)) for more details.
- `pk_algo: 0x1b`: This corresponds to the key's public-key algorithm ID, which has a decimal value of 27. Refer to the list of [Public-Key Algorithms](https://www.rfc-editor.org/rfc/rfc9580.html#name-public-key-algorithms)) for more details.
- `public_len: 0x00000020`: This field specifies the octet count for the subsequent public key material. In this case, it represents the length of the following `ed25519_public` field.
- `ed25519_public`: This is the [algorithm-specific representation](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-algorithm-specific-part-for-ed2) of the public key material. The format is based on the value of `pk_algo`, which, in this case, is 32 bytes of Ed25519 public key data.
- `ed25519_public`: This is the [algorithm-specific representation](https://www.rfc-editor.org/rfc/rfc9580.html#name-algorithm-specific-part-for-ed2) of the public key material. The format is based on the value of `pk_algo`, which, in this case, is 32 bytes of Ed25519 public key data.
[^CTB]: Sequoia uses the term CTB ({term}`Cipher Type Byte`) to refer to the [packet type ID](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-packet-headers).
[^CTB]: Sequoia uses the term CTB ({term}`Cipher Type Byte`) to refer to the [packet type ID](https://www.rfc-editor.org/rfc/rfc9580.html#name-packet-headers).
Note that the *Public-Key packet* contains only the public part of the key.
@ -172,7 +172,7 @@ Structure of a Public-Key packet.
(zoom-dks)=
### Direct Key Signature
The next packet in the certificate is a [*Direct Key Signature*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#sigtype-direct-key), which plays a crucial role in binding specific information to the primary key. This signature is contained within the file `alice.pub-1--Signature`.
The next packet in the certificate is a [*Direct Key Signature*](https://www.rfc-editor.org/rfc/rfc9580.html#sigtype-direct-key), which plays a crucial role in binding specific information to the primary key. This signature is contained within the file `alice.pub-1--Signature`.
This packet binds the data within the signature subpackets with the primary key. Each entry under "Signature Packet -> Hashed area" is one signature subpacket, providing essential information such as algorithm preferences, including *symmetric algorithm preference* and *hash algorithm preferences*.
@ -248,7 +248,7 @@ Below is a field-by-field examination of the packet:
**OpenPGP packet syntax**
The first fields of a packet are governed by the general [Packet Syntax](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-packet-syntax):
The first fields of a packet are governed by the general [Packet Syntax](https://www.rfc-editor.org/rfc/rfc9580.html#name-packet-syntax):
- `CTB: 0xc2`: This field indicates the Packet type ID for this packet. Bits 7 and 6 show that the packet is in “OpenPGP packet format.” The remaining 6 bits encode the type ID’s value, which is “2” for a Signature packet.
@ -256,15 +256,15 @@ The first fields of a packet are governed by the general [Packet Syntax](https:/
**Signature packet syntax**
The packet type ID (“2”) defines the semantics of the remaining data in the packet. In this case, as it indicates a [Signature packet](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#signature-packet), the following data is specific to this packet type:
The packet type ID (“2”) defines the semantics of the remaining data in the packet. In this case, as it indicates a [Signature packet](https://www.rfc-editor.org/rfc/rfc9580.html#signature-packet), the following data is specific to this packet type:
- `version: 0x06`: This is a version 6 signature.
- `type: 0x1f`: This indicates the [Signature Type](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-signature-types).
- `type: 0x1f`: This indicates the [Signature Type](https://www.rfc-editor.org/rfc/rfc9580.html#name-signature-types).
- `pk_algo: 0x1b`: This specifies the Public-Key algorithm ID, with decimal 27 corresponding to [Ed25519](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-public-key-algorithms)).
- `pk_algo: 0x1b`: This specifies the Public-Key algorithm ID, with decimal 27 corresponding to [Ed25519](https://www.rfc-editor.org/rfc/rfc9580.html#name-public-key-algorithms)).
- `hash_algo: 0x0a`: This specifies the hash algorithm ID, with decimal 10 corresponding to [SHA2-512](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-hash-algorithms)).
- `hash_algo: 0x0a`: This specifies the hash algorithm ID, with decimal 10 corresponding to [SHA2-512](https://www.rfc-editor.org/rfc/rfc9580.html#name-hash-algorithms)).
- `hashed_area_len: 0x0000003d`: This specifies the length of the following hashed subpacket data.
@ -274,7 +274,7 @@ In OpenPGP Signatures, there are two sets of subpacket data: hashed and unhashed
A subpacket data set in an OpenPGP Signature contains a list of zero or more Signature subpackets.
The following subpacket data consists of sets of "subpacket length, subpacket type ID, data." Each subpacket is displayed as one line, starting with the [subpacket type description](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-signature-subpacket-specifi) (based on the subpacket type ID). Note that bit 7 of the subpacket type ID signals if that subpacket is ["critical."](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-5.2.3.7-7)
The following subpacket data consists of sets of "subpacket length, subpacket type ID, data." Each subpacket is displayed as one line, starting with the [subpacket type description](https://www.rfc-editor.org/rfc/rfc9580.html#name-signature-subpacket-specifi) (based on the subpacket type ID). Note that bit 7 of the subpacket type ID signals if that subpacket is ["critical."](https://www.rfc-editor.org/rfc/rfc9580.html#section-5.2.3.7-7)
```{note}
Critical here means that the receiver must interpret the subpacket and is expected to fail, otherwise. Non-critical subpackets may be ignored by the receiver.
@ -282,43 +282,43 @@ Critical here means that the receiver must interpret the subpacket and is expect
The subpacket details are as follows:
- [**Signature Creation Time**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#signature-creation-subpacket)
- [**Signature Creation Time**](https://www.rfc-editor.org/rfc/rfc9580.html#signature-creation-subpacket)
- Type: `2`
- Critical: `Yes`
- Value: `0x6516eaa6`
- Notes: See also [Time Fields](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-time-fields).
- Notes: See also [Time Fields](https://www.rfc-editor.org/rfc/rfc9580.html#name-time-fields).
- [**Key Expiration Time**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#key-expiration-subpacket)
- [**Key Expiration Time**](https://www.rfc-editor.org/rfc/rfc9580.html#key-expiration-subpacket)
- Type: `9`
- Critical: `Yes`
- Value: `0x05a48fbd`
- Notes: Defined as number of seconds after the key creation time
- [**Preferred Symmetric Ciphers for v1 SEIPD**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-v1-seipd)
- [**Preferred Symmetric Ciphers for v1 SEIPD**](https://www.rfc-editor.org/rfc/rfc9580.html#preferred-v1-seipd)
- Type: `11`
- Critical: `No`
- Value: `0x09 0x07`
- Notes: Values correspond to *AES with 256-bit key* and *AES with 128-bit key*
- [**Preferred Hash Algorithms**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-hashes-subpacket)
- [**Preferred Hash Algorithms**](https://www.rfc-editor.org/rfc/rfc9580.html#preferred-hashes-subpacket)
- Type: `21`
- Critical: `No`
- Value: `0x0a 0x08`
- Notes: Values correspond to *SHA2-512* and *SHA2-256*.
- [**Key Flags**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#key-flags)
- [**Key Flags**](https://www.rfc-editor.org/rfc/rfc9580.html#key-flags)
- Type: `27`
- Critical: `Yes`
- Value: `0x01`
- Notes: Value corresponds to the *certifications* key flag.
- [**Features**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#features-subpacket)
- [**Features**](https://www.rfc-editor.org/rfc/rfc9580.html#features-subpacket)
- Type: `30`
- Critical: `No`
- Value: `0x01`
- Notes: Value corresponds to *Symmetrically Encrypted Integrity Protected Data packet version 1*
- [**Issuer Fingerprint**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#issuer-fingerprint-subpacket)
- [**Issuer Fingerprint**](https://www.rfc-editor.org/rfc/rfc9580.html#issuer-fingerprint-subpacket)
- Type: `33`
- Critical: `No`
- Value: `aaa18cbb254685c58358320563fd37b67f3300f9fb0ec457378cd29f102698b3`
@ -330,7 +330,7 @@ The next part of this packet contains unhashed subpacket data:
As above, the following subpacket data consists of sets of subpacket length, subpacket type id, and data. In this case, only one subpacket follows:
- [**Issuer Key ID**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#issuer-keyid-subpacket)
- [**Issuer Key ID**](https://www.rfc-editor.org/rfc/rfc9580.html#issuer-keyid-subpacket)
- Type: `16`
- Critical: `No`
- Value: `aaa18cbb254685c5`
@ -342,11 +342,11 @@ This next section shows the remaining fields of this signature packet, which rel
- `digest_prefix: 0x6747`: the left 16 bits of the signed hash digest
- `salt_len, salt`: a random [salt value](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-advantages-of-salted-signat) with size [matching the hash algorithm](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#hash-algorithms-registry))
- `salt_len, salt`: a random [salt value](https://www.rfc-editor.org/rfc/rfc9580.html#name-advantages-of-salted-signat) with size [matching the hash algorithm](https://www.rfc-editor.org/rfc/rfc9580.html#hash-algorithms-registry))
- `ed25519_sig`: [algorithm-specific](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-algorithm-specific-fields-for-ed2) representation of the signature (here: 64 bytes of Ed25519 signature)
- `ed25519_sig`: [algorithm-specific](https://www.rfc-editor.org/rfc/rfc9580.html#name-algorithm-specific-fields-for-ed2) representation of the signature (here: 64 bytes of Ed25519 signature)
The hash digest is calculated from the following data (see [Computing Signatures](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-computing-signatures) in the RFC):
The hash digest is calculated from the following data (see [Computing Signatures](https://www.rfc-editor.org/rfc/rfc9580.html#name-computing-signatures) in the RFC):
- the signature's salt
- the serialized primary key's public data
@ -410,9 +410,9 @@ Public-Subkey Packet, new CTB, 2 header bytes + 42 bytes
Notice that the structure of this *Public-Subkey packet* mirrors the primary key's [*Public-Key packet*](zoom-public-key) above. However, there are notable differences between the two packets:
- The packet type ID (`CTB`) in this packet shows type 14 ([*Public-Subkey packet*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-public-subkey-packet-type-i)).
- The packet type ID (`CTB`) in this packet shows type 14 ([*Public-Subkey packet*](https://www.rfc-editor.org/rfc/rfc9580.html#name-public-subkey-packet-type-i)).
- The `pk_algo` value is set to `0x19` (decimal 25), which [corresponds to X25519](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-public-key-algorithms). Notably, though both the primary key and this subkey use a cryptographic mechanism based on Curve25519, the encryption key uses Curve 25519 in a different way: namely, X25519 is a Diffie–Hellman function constructed from Curve25519.
- The `pk_algo` value is set to `0x19` (decimal 25), which [corresponds to X25519](https://www.rfc-editor.org/rfc/rfc9580.html#name-public-key-algorithms). Notably, though both the primary key and this subkey use a cryptographic mechanism based on Curve25519, the encryption key uses Curve 25519 in a different way: namely, X25519 is a Diffie–Hellman function constructed from Curve25519.
- Accordingly, the public part of the cryptographic key pair is labeled `x25519_public`, as implied by the value (`0x19`) of `pk_algo`. However, the actual data is just 32 bytes of cryptographic key material, without any type information.
### Subkey binding signature
@ -483,7 +483,7 @@ Signature Packet, new CTB, 2 header bytes + 171 bytes
The analysis of this packet dump will be less extensive, given that its structure mirrors the *Direct Key Signature* explored above.
One notable difference is the `type` field, showing that this signature is of type `0x18` ([Subkey Binding Signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-subkey-binding-signature-ty)).
One notable difference is the `type` field, showing that this signature is of type `0x18` ([Subkey Binding Signature](https://www.rfc-editor.org/rfc/rfc9580.html#name-subkey-binding-signature-ty)).
The `pk_algo` value of this signature derives from the algorithm of the primary key (`0x1b`, corresponding to Ed25519). This signature is issued by the primary key, thus using the signing algorithm of the primary key. (The algorithm used to produce the cryptographic signature in this packet is entirely independent of the `pk_algo` of the key material of this subkey itself, which uses the X25519 mechanism.)
@ -506,7 +506,7 @@ The signature is calculated over a hash digest. In this case, the hash digest is
- the serialized subkey's public data
- the serialized subkey binding signature packet (excluding the unhashed area)
Refer to [Computing Signatures](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-computing-signatures) in the RFC for details.
Refer to [Computing Signatures](https://www.rfc-editor.org/rfc/rfc9580.html#name-computing-signatures) in the RFC for details.
## Signing subkey
@ -626,7 +626,7 @@ In this section, we'll look at an identity associated with Alice's certificate.
User IDs are a mechanism for connecting [identities](identity-components) with an OpenPGP certificate. Typically, a User ID is a string combining a name and an email address.
To understand the internal packet structure of this identity and its connection to the OpenPGP certificate, we'll examine two packets that constitute the identity component. One is the [User ID packet](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#uid), located in the file `alice.pub-2--UserID`, which contains identity information. The other is a certifying self-signature, specifically a [Positive certification of a User ID and Public-Key packet](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-positive-certification-of-a) located in the file `alice.pub-3--Signature`. This certification, issued after substantial verification of the identity claim, validates the association between the User ID and the certificate's public key. These packets are snippets from Alice's full OpenPGP certificate.
To understand the internal packet structure of this identity and its connection to the OpenPGP certificate, we'll examine two packets that constitute the identity component. One is the [User ID packet](https://www.rfc-editor.org/rfc/rfc9580.html#uid), located in the file `alice.pub-2--UserID`, which contains identity information. The other is a certifying self-signature, specifically a [Positive certification of a User ID and Public-Key packet](https://www.rfc-editor.org/rfc/rfc9580.html#sigtype-positive-cert) located in the file `alice.pub-3--Signature`. This certification, issued after substantial verification of the identity claim, validates the association between the User ID and the certificate's public key. These packets are snippets from Alice's full OpenPGP certificate.
### User ID packet
@ -643,7 +643,7 @@ User ID Packet, new CTB, 2 header bytes + 19 bytes
00000010 2e 6f 72 67 3e
```
- `CTB: 0xcd`: This is the packet type ID for this packet. Bits 7 and 6 show that the packet is in “OpenPGP packet format” (not “Legacy packet format”). The remaining 6 bits encode the type ID’s value: “13,” which is the value for a [User ID packet](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#uid).
- `CTB: 0xcd`: This is the packet type ID for this packet. Bits 7 and 6 show that the packet is in “OpenPGP packet format” (not “Legacy packet format”). The remaining 6 bits encode the type ID’s value: “13,” which is the value for a [User ID packet](https://www.rfc-editor.org/rfc/rfc9580.html#uid).
- `length: 0x13`: This field shows the remaining length of the packet (here: 19 bytes).
@ -732,7 +732,7 @@ Signature Packet, new CTB, 2 header bytes + 185 bytes
Because this packet structure closely mirrors the [Direct Key Signature](zoom-dks) discussed above, we will cover this succinctly.
We're again looking at a Signature packet. Its `type` is `0x13` ([corresponding to a *positive certification* signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-signature-types)).
We're again looking at a Signature packet. Its `type` is `0x13` ([corresponding to a *positive certification* signature](https://www.rfc-editor.org/rfc/rfc9580.html#name-signature-types)).
The designated public key algorithm and hash function for this signature are Ed25519 and SHA512, respectively.
@ -754,7 +754,7 @@ Historically, the self-signature that binds the primary User ID to the certifica
Setting key expiration time and key flags on the primary User ID self-signature is one mechanism to configure the primary key.
The interaction between metadata on direct key signatures and User ID binding self-signatures [is subtle](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-notes-on-self-signatures), with changes between version 6 and version 4.
The interaction between metadata on direct key signatures and User ID binding self-signatures [is subtle](https://www.rfc-editor.org/rfc/rfc9580.html#name-notes-on-self-signatures), with changes between version 6 and version 4.
````
This section is followed, again, by the (informational) unhashed subpacket area.
@ -768,7 +768,7 @@ The signature is calculated over a hash. The hash, in this case, is derived from
- the serialized User ID
This section specifies- the serialized self-signature packet (excluding the unhashed area)
Refer to [Computing Signatures](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-computing-signatures) in the RFC for details.
Refer to [Computing Signatures](https://www.rfc-editor.org/rfc/rfc9580.html#name-computing-signatures) in the RFC for details.
## Certifications (Third Party Signatures)

34
book/source/zoom/private_keys.md
View file

@ -17,7 +17,7 @@ $ sq packet dump --hex alice.priv
### Primary Secret-Key packet
The output starts with the (primary) [Secret-Key packet](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-secret-key-packet-formats).
The output starts with the (primary) [Secret-Key packet](https://www.rfc-editor.org/rfc/rfc9580.html#name-secret-key-packet-formats).
This is the structure of the Secret-Key packet we will now look at.
@ -60,30 +60,30 @@ Secret-Key Packet, new CTB, 2 header bytes + 75 bytes
The Secret-Key packet consists in large part of the actual cryptographic key data. Notice that its content is almost entirely the same as the Public-Key packet [seen in the previous chapter](zoom-public-key). Let's look at the packet field by field:
- `CTB: 0xc5`[^CTB]: The [packet type ID](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-packet-headers) for this packet. The binary representation of the value `0xc5` is `11000101`. Bits 7 and 6 show that the packet is in *OpenPGP packet format* (as opposed to in *Legacy packet format*). The remaining 6 bits encode the type ID's value: "5". This is the value for a Secret-Key packet, as shown in the list of [packet type IDs](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-packet-types).
- `CTB: 0xc5`[^CTB]: The [packet type ID](https://www.rfc-editor.org/rfc/rfc9580.html#name-packet-headers) for this packet. The binary representation of the value `0xc5` is `11000101`. Bits 7 and 6 show that the packet is in *OpenPGP packet format* (as opposed to in *Legacy packet format*). The remaining 6 bits encode the type ID's value: "5". This is the value for a Secret-Key packet, as shown in the list of [packet type IDs](https://www.rfc-editor.org/rfc/rfc9580.html#name-packet-types).
- `length: 0x4b`: The remaining length of this packet.
[^CTB]: Sequoia uses the term CTB ({term}`Cipher Type Byte`) to refer to the [packet type ID](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-packet-headers).
[^CTB]: Sequoia uses the term CTB ({term}`Cipher Type Byte`) to refer to the [packet type ID](https://www.rfc-editor.org/rfc/rfc9580.html#name-packet-headers).
The packet type id defines the semantics of the remaining data in the packet. We're looking at a Secret-Key packet, which is a kind of [Key Material Packet](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-material-packets).
The packet type id defines the semantics of the remaining data in the packet. We're looking at a Secret-Key packet, which is a kind of [Key Material Packet](https://www.rfc-editor.org/rfc/rfc9580.html#name-key-material-packets).
- `version: 0x06`: The key material is in version 6 format
This means that the next part of the packet follows the structure of [Version 6 Public Keys](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-version-6-public-keys)
This means that the next part of the packet follows the structure of [Version 6 Public Keys](https://www.rfc-editor.org/rfc/rfc9580.html#name-version-6-public-keys)
- `creation_time: 0x6516eaa6`: "The time that the key was created" (also see [Time Fields](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-time-fields))
- `pk_algo: 0x1b`: "The public-key algorithm ID of this key" (decimal value 27, see the list of [Public-Key Algorithms](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-public-key-algorithms))
- `creation_time: 0x6516eaa6`: "The time that the key was created" (also see [Time Fields](https://www.rfc-editor.org/rfc/rfc9580.html#name-time-fields))
- `pk_algo: 0x1b`: "The public-key algorithm ID of this key" (decimal value 27, see the list of [Public-Key Algorithms](https://www.rfc-editor.org/rfc/rfc9580.html#name-public-key-algorithms))
- `public_len: 0x00000020`: "Octet count for the following public key material" (in this case, the length of the following `ed25519_public` field)
- `ed25519_public`: [Algorithm-specific representation](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-algorithm-specific-part-for-ed2) of the public key material (the format is based on the value of `pk_algo`), in this case 32 bytes of Ed25519 public key
- `ed25519_public`: [Algorithm-specific representation](https://www.rfc-editor.org/rfc/rfc9580.html#name-algorithm-specific-part-for-ed2) of the public key material (the format is based on the value of `pk_algo`), in this case 32 bytes of Ed25519 public key
This concludes the Public Key section of the packet. The remaining data follows the [Secret-Key packet format](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-secret-key-packet-formats):
This concludes the Public Key section of the packet. The remaining data follows the [Secret-Key packet format](https://www.rfc-editor.org/rfc/rfc9580.html#name-secret-key-packet-formats):
- `s2k_usage: 0x00`: The [*S2K usage* value](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-secret-key-encryption-s2k-u) of `0x00` specifies that the secret-key data is not encrypted
- `ed25519_secret`: [Algorithm-specific representation](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-algorithm-specific-part-for-ed2) of the secret key data (the format is based on the value of `pk_algo`). Because the private key material in this packet is not encrypted, this field
- `s2k_usage: 0x00`: The [*S2K usage* value](https://www.rfc-editor.org/rfc/rfc9580.html#name-openpgp-secret-key-encrypti) of `0x00` specifies that the secret-key data is not encrypted
- `ed25519_secret`: [Algorithm-specific representation](https://www.rfc-editor.org/rfc/rfc9580.html#name-algorithm-specific-part-for-ed2) of the secret key data (the format is based on the value of `pk_algo`). Because the private key material in this packet is not encrypted, this field
```{tip}
The overall structure of OpenPGP packets is described in the [Packet Syntax](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-packet-syntax) chapter of the RFC.
The overall structure of OpenPGP packets is described in the [Packet Syntax](https://www.rfc-editor.org/rfc/rfc9580.html#name-packet-syntax) chapter of the RFC.
```
Note that the *Secret-Key packet* contains both the private and the public part of the key.
@ -171,18 +171,18 @@ Secret-Key Packet, new CTB, 2 header bytes + 134 bytes
00000080 4a 3f 33 d9 2c c9 26 46
```
The first portion of Bob's Secret-Key packet has the same structure as Alice's, but beginning at the `s2k_usage`, we see different data. The format of this data is described in [Secret-Key Packet Formats](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-secret-key-packet-formats).
The first portion of Bob's Secret-Key packet has the same structure as Alice's, but beginning at the `s2k_usage`, we see different data. The format of this data is described in [Secret-Key Packet Formats](https://www.rfc-editor.org/rfc/rfc9580.html#name-secret-key-packet-formats).
- `s2k_usage: 0xfe`: [S2K usage](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-secret-key-encryption-s2k-u) is set to `AEAD`, here (decimal value 253).
- `s2k_usage: 0xfe`: [S2K usage](https://www.rfc-editor.org/rfc/rfc9580.html#name-openpgp-secret-key-encrypti) is set to `AEAD`, here (decimal value 253).
- `parameters_len: 0x16` (decimal value: 22): "Cumulative length of all the following conditionally included string-to-key parameter fields."
- `sym_algo: 0x9`: [Symmetric-Key Algorithm](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-symmetric-key-algorithms) specifies that AES 256 is used as the AEAD algorithm
- `sym_algo: 0x9`: [Symmetric-Key Algorithm](https://www.rfc-editor.org/rfc/rfc9580.html#name-symmetric-key-algorithms) specifies that AES 256 is used as the AEAD algorithm
- `s2k_len: 0x14` (decimal value 20): "[..] count of the size of the one field following this octet"
The next set of data is the "string-to-key (S2K) specifier." Its format depends on the type.
- `s2k_type: 0x04` [String-to-Key (S2K) Specifier Type](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-string-to-key-s2k-specifier-), set to *Argon2* here.
- `s2k_type: 0x04` [String-to-Key (S2K) Specifier Type](https://www.rfc-editor.org/rfc/rfc9580.html#name-string-to-key-s2k-specifier), set to *Argon2* here.
The next fields are [specific to Argon2](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-argon2):
The next fields are [specific to Argon2](https://www.rfc-editor.org/rfc/rfc9580.html#name-argon2):
- `argon2_salt`: "16-octet salt value"
- `argon2_t`: "number of passes t"