From ce992297ab52f773350ef115431d8c92718055f4 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sun, 10 Dec 2023 22:14:21 +0100 Subject: [PATCH] move "advanced" sections to their own chapters --- book/source/05-private.md | 78 ------------- book/source/06-signatures.md | 51 --------- book/source/07-signing_data.md | 48 -------- book/source/08-signing_components.md | 153 -------------------------- book/source/17b-adv-private.md | 82 ++++++++++++++ book/source/17c-adv-signatures.md | 55 ++++++++++ book/source/17d-adv-sign-data.md | 52 +++++++++ book/source/17e-adv-sig-component.md | 157 +++++++++++++++++++++++++++ 8 files changed, 346 insertions(+), 330 deletions(-) create mode 100644 book/source/17b-adv-private.md create mode 100644 book/source/17c-adv-signatures.md create mode 100644 book/source/17d-adv-sign-data.md create mode 100644 book/source/17e-adv-sig-component.md diff --git a/book/source/05-private.md b/book/source/05-private.md index f83ce65..ce52cce 100644 --- a/book/source/05-private.md +++ b/book/source/05-private.md @@ -132,81 +132,3 @@ Specifically, an OpenPGP private keystore implements two primitives: 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. - -## Advanced topics - -(key-store-design)= -### Private keystores - -This section examines the diverse architectures and operational mechanics of private keystores in OpenPGP. It focuses on the various design choices, their functional implications, and how they contribute to the secure management of private key material. - -#### Design variations - -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. -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. - -```{note} -The third design option, involving the storage of full TSKs in the private key subsystem, can cause "split brain" problems. - -For example, a private keystore might contain a TSK with outdated certificate metadata, marking the certificate as expired, while the updated version in the local public keystore could indicate an extended expiration date. - -This problem was notably present in GnuPG 1.x, which held separate TSK copies in its private store component. Similarly, the current design of Thunderbird's OpenPGP subsystem can lead to users experiencing such issues. -``` - -#### Two-tier architecture - -At its core, an OpenPGP private key subsystem performs operations requiring only the private cryptographic key material, akin to the "separate backend operations" model described above. - -However, the subsystem also supports operations that require additional access to the metadata of the component key. These operations, supplementary to the core keystore operations, do not involve the private key material. - -When implementing a keystore based on hardware cryptographic devices like [OpenPGP card](card-priv), its design will consist of two layers: - -- **core layer**: directly handles private key material, and -- **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. - - 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). -``` - -#### Addressing individual keys - -A critical aspect of private keystore design involves determining how users address individual keys. - -One common method is using the fingerprint of each component key. The availability of these fingerprints, however, depends on the underlying technology of the keystore. For instance, in software-based private keystores or OpenPGP cards, fingerprints of component keys are usually readily available. Keystores relying on generic cryptographic hardware, like TPMs, need to implement their own mechanisms for tracking and managing the fingerprints of each key. - -#### Additional keystore duties - -In addition to key management, a keystore often involves various supplementary functions: - -- **Tracking devices**: Keystores may track which devices contain particular component keys. - -- **Handling secrets**: This involves the management of sensitive information such as passphrases for software keys or PINs for OpenPGP cards. - -- **User interaction alerts**: Keystores might also need to prompt users for necessary interactions during certain operations. For example, OpenPGP cards may require user touch confirmation to authorize each cryptographic action. - -### Understanding key overwriting (KO) attacks - -#### What they are - -OpenPGP is subject to specific vulnerabilities known as key overwriting (KO) attacks. These attacks exploit weaknesses in how encrypted private keys or their metadata are handled, potentially leading to the leakage of secret data when the key is used. The core issue lies in OpenPGP's handling of Secret-Key packets, where corruption of the non-encrypted fields can cause the unaltered private key material to be used with altered parameters. This mismatch can result in private key leakage. - -Importantly, KO attacks are particularly relevant when an attacker is responsible for storing a user's encrypted private key. By altering the algorithm field in the Secret-Key packet, the attacker may cause the user to perform a cryptographic operation with a different algorithm. E.g., performing a DSA operation with ECC private key material. By observing the output of that attacker-corrupted operation, the attacker can recover the user's unencrypted private key material, even though the attacker had no direct access to it. - -#### Mitigation - -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 consider if this attack class is a concern in their applications. - -Private keys that are protected with [S2K usage mode 253 (AEAD)](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-secret-key-encryption), are not vulnerable to 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 packet, then decryption of the private key material will fail, and the user is prevented from e.g. accidentally using the key material with an altered attacker-controlled algorithm. - -Note that while S2K usage mode 253 (AEAD) has been introduced in the OpenPGP version 6 specification, it can also be applied to OpenPGP version 4 key material (also see {ref}`migration_s2k`). - -#### Resources - -For comprehensive information on KO attacks, including background, attack vectors, countermeasures, and technical analyses, visit [KOpenPGP.com](https://www.kopenpgp.com/). It is based on the paper "Victory by KO: Attacking OpenPGP Using Key Overwriting" written by Lara Bruseghini, Daniel Huigens, and Kenneth G. Paterson for the Proceedings of ACM Conference on Computer and Communications Security, Los Angeles, November 2022. diff --git a/book/source/06-signatures.md b/book/source/06-signatures.md index c84eb2b..e45d403 100644 --- a/book/source/06-signatures.md +++ b/book/source/06-signatures.md @@ -148,54 +148,3 @@ This mechanism accounts for different {term}`OpenPGP implementations` does not recognize a {term}`subpacket` indicating {term}`signature` {term}`expiration`. Without understanding this concept, the {term}`implementation` might erroneously accept an already {term}`expired` {term}`signature`. By marking the {term}`signature expiration time subpacket` as {term}`critical`, the creator of the {term}`signature` ensures that any recipient who cannot process this {term}`subpacket` will reject the {term}`signature` as {term}`invalid`. For specific guidelines on which {term}`subpackets` should be marked as {term}`critical`, 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). - -## Advanced topics - -(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` in OpenPGP with user-defined {term}`notations`. {term}`Issuers` can use these {term}`notations` to add name-value pairs to an {term}`OpenPGP signature`. - -{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. - -{term}`Notations`, as described earlier, allow for user-defined extensions to the {term}`OpenPGP signature subpacket types`. A practical and popular application of this functionality is seen in Keyoxide, a decentralized {term}`identity verification` service. Keyoxide uses {term}`notations` in the `ariadne.id` namespace. For the details of this {term}`implementation`, refer to the [Keyoxide documentation](https://docs.keyoxide.org/wiki/ariadne-identity/). - -### Choosing the hash algorithm for a signature - -A central element of signature packets is the hash digest of the input data. Most OpenPGP software supports a set of different hash mechanisms, of which one is chosen for each signature packet (this is one aspect of OpenPGP's *cryptographic agility*), and used to calculate the hash digest. - -Different hash mechanisms offer different trade-offs: - -- *Hash digest size*: Larger hash size tends to correspond with greater strength against cryptanalysis, and hash digests are relatively small: at the time of this writing, typical sizes are 32 to 64 bytes. However, for some use cases - especially where small messages are sent over a bandwidth-limited transport - larger hash sizes may unacceptably increase message size. -- *Computational cost*: Different hash algorithms may have different computational costs. Some OpenPGP users may prefer to limit this cost, for example on constrained computing environments. - -The following sections discuss how the hash algorithm is chosen, based on preferences that are associated with the involved OpenPGP certificates. - -#### Typically: Local determination - -Often, signature creation isn't targeted at a specific receiver. Many signatures are issued for an indeterminate set of "anyone who receives the signature." - -For example, self-signatures that form a certificate are aimed at everyone who interacts with that certificate. Similarly, when creating a data signature for a software package, this signature is aimed at "anyone who will check the signature," often over a long period of time, easily spanning years. - -In such cases, the issuer of that signature chooses the hash algorithm locally, without following preferences of a third party. - -#### With a specific recipient: "Negotiation" based on recipient's preferences - -In contrast, when a message is created for a specific recipient, the sender can - and should - choose the hash algorithm for the signature packet [based on the recipient's hash algorithm preference](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-hash-algorithm-preferences). - -The recipient's hash algorithm preference is defined in metadata of their certificate, see {ref}`algo-pref` for more details. - -In this workflow, the signed hash digest is created with a hash algorithm that follows the recipient's preferences, and its intersection with the sender's capabilities and preferences. - -### 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. - -That is: - -- OpenPGP version 6 keys must generate version 6 signature packets -- OpenPGP version 4 keys must generate version 4 signature packets - -Note that some historical version 3 signature packets may still be relevant for applications that handle old OpenPGP data[^sig-v3]. These version 3 signature packets will have been generated by version 4 keys. - -[sig-v3]Version 4 signature packets were introduced in [RFC 2440](https://datatracker.ietf.org/doc/html/rfc2440#section-5.2) in 1998, which specifies that applications SHOULD generate v4 signature, however generation of v3 signature packets has remained allowed through [RFC 4880](https://www.rfc-editor.org/rfc/rfc4880.html#section-5.2). \ No newline at end of file diff --git a/book/source/07-signing_data.md b/book/source/07-signing_data.md index d166794..009b824 100644 --- a/book/source/07-signing_data.md +++ b/book/source/07-signing_data.md @@ -137,51 +137,3 @@ The {term}`cleartext signature framework` includes specific text normalization p Despite their widespread adoption, {term}`cleartext signatures` 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` and {term}`detached signature` forms are advised. [^csf-gnupg]: https://lists.gnupg.org/pipermail/gnupg-devel/2023-November/035428.html - -## Advanced topics - -### Nesting of one-pass signatures - -Signing a message using the one-pass mechanism involves prepending a *One-Pass-Signature* (OPS) packet to the message and appending the corresponding signature, sandwiching the signed content. - -An OpenPGP message can contain multiple signatures added that way. - -```{note} -One-Pass-Signatures are nested, meaning the outermost One-Pass-Signature packet corresponds to the outermost signature packet. -``` - -When a message is signed, the signature is always calculated over the contents of the literal data packet, not the literal data packet itself. -This means, that if a message, which is compressed using a compressed data packet is wrapped using a one-pass-signature, the signature is still being calculated over the plaintext inside the literal data packet. - -There is one exception though. -```{note} -Of course there is. -``` - -The OPS packet has a "nested" flag[^nested-flag], which can either be `1` or `0`. -If this flag is set to `0`, it indicates that further OPSs will follow this packet, which are calculated over the same plaintext data as this OPS is. A value of `1` indicates, that either no further OPS packets will follow (this OPS is the last), or that this OPS is calculated over the the usual plaintext data, but wrapped inside any OPS+Signature combinations that follow this OPS. - -[^nested-flag]: See [description of the nested flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-5.4-3.8.1). - -This mechanism enables attested signatures, where the signer signs an already one-pass-signed message including the already contained signature. - -As a practical example, consider the following notation: -* `LIT("Hello World")` represents a literal data packet with the content `Hello World`. -* `COMP(XYZ)` represents a compressed data packet over some other packet `XYZ`. -* `OPS₁` represents a one-pass-signature packet with the nested flag set to `1`. Analogous, `OPS₀` has the nested flag set to `0`. -* `SIG` represents a signature packet. - -A normal, one-pass-signed message looks like this: -`OPS₁ LIT("Hello World") SIG` - -Here, the signature is calculated over the plaintext `Hello World`, as is it in a message that has the following form: `OPS₁ COMP(LIT("Hello World")) SIG`. - -A message, where multiple one-pass-signatures are calculated over the same plaintext looks the following: -`OPS₀ OPS₀ OPS₁ LIT("Hello World") SIG SIG SIG` - -All three signatures are calculated over the same plaintext `Hello World`. - -Now, a message, where the signer attests an already signed message has the following format: -`OPS₁ OPS₁ LIT("Hello World") SIG SIG` - -While the inner signature is calculated over the usual plaintext `Hello World`, the outer signature is instead calculated over `OPS₁ Hello World SIG`. diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index 17abd1d..292c465 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -282,156 +282,3 @@ The {term}`OpenPGP 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` `0x30`). The {term}`revocation` must be issued by the same {term}`key` that created the original {term}`signature` 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). - -## Advanced topics - -### Certification recipes - -Different {term}`signatures` in OpenPGP serve various specific purposes. This section provides practical guidance on creating these {term}`signatures`, illustrating each with concrete examples. - -(change_algorithm_preferences)= -#### Change algorithm preferences - -To modify the preferred {term}`symmetric`, compression, {term}`hash`, or {term}`AEAD algorithms` for a {term}`key`, the {term}`key owner` needs to issue a {term}`direct key signature` ({term}`type ID` `0x1F`) on the {term}`primary key`. - -This {term}`signature` should have the following structure: - -| {term}`Subpacket` | Area | {term}`Critical` | Mandatory | Notes | -|---------------------------------------------------------------------------------------------|-----------------------------|------------------------------------------|----------------------|----------------------------------------------------------------------------------------| -| {term}`Signature Creation Time` | {term}`Hashed` | True | True | Current time | -| {term}`Issuer Fingerprint` | {term}`Hashed` | True or False | Strongly Recommended | The {term}`primary key` is the {term}`issuer` | -| {term}`Key Flags` | {term}`Hashed` | True | False | Retain {term}`key flags` from the previous {term}`self-signature` | -| {term}`Features` | {term}`Hashed` | True | False | Retain {term}`features` from the previous {term}`self-signature` | -| {term}`Key Expiration Time` | {term}`Hashed` | True | False | Retain {term}`expiration time` from the previous {term}`self-signature`, if applicable | -| {term}`Hash Algorithm Preferences` | {term}`Hashed` | False | False | New {term}`preferences` | -| {term}`Compression Algorithm Preferences` | {term}`Hashed` | False | False | New {term}`preferences` | -| {term}`Symmetric Algorithm Preferences` | {term}`Hashed` | False | False | New {term}`preferences` | -| {term}`AEAD Algorithm Preferences` | {term}`Hashed` | False | False | New {term}`preferences` | - -#### Change expiration time - -To adjust the {term}`expiration time` of an {term}`OpenPGP certificate`, a new *{term}`DirectKey`* {term}`signature` ({term}`type ID` `0x1F`) with a modified {term}`Key Expiration Time subpacket` must be issued. The structure of this {term}`signature` is identical to the one outlined in the previous section on changing {term}`algorithm preferences`. - -Additionally, the {term}`expiration time` can be altered for individual {term}`User IDs` (detailed below) or separate {term}`subkeys` (see {numref}`bind_subkey`). - -#### Add User ID - -To {term}`bind` a {term}`User ID` to an {term}`OpenPGP certificate` a {term}`certification signature` ({term}`type ID` `0x10`-`0x13`) is used which should have the following structure: - -| {term}`Subpacket` | Area | {term}`Critical` | Mandatory | Notes | -|------------------------------------------------------------------------|-----------------------------|------------------------------------------|----------------------|-------------------------------------------------------------------------------------| -| {term}`Signature Creation Time` | {term}`Hashed` | True | True | Current time | -| {term}`Issuer Fingerprint` | {term}`Hashed` | True or False | Strongly Recommended | The {term}`primary key` is the {term}`issuer` | -| {term}`Primary User ID` | {term}`Hashed` | True | False | Optional | -| {term}`Signature Expiration Time` | {term}`Hashed` | True | False | Optional | - -In addition to these {term}`subpackets`, {term}`self-certifications` for {term}`User IDs` can include others – such as {term}`key flags`, {term}`features`, and {term}`algorithm preferences` – as shown in the previous table. This enables the specification of unique capabilities and {term}`preferences` for each {term}`identity` associated with the {term}`certificate`. - -#### Remove or revoke a User ID - -Since {term}`OpenPGP certificates` are often distributed by the means of {term}`key servers`, new {term}`signatures` on a {term}`certificate` are often "merged" into existing copies of the {term}`certificate` locally by the recipient. - -```{admonition} TODO -:class: warning - -Link to the "Merging" section in chapter 4, once merged. -``` - -This integration process means it is practically impossible to directly remove {term}`signatures` or {term}`User IDs` from a {term}`certificate`, as there is no way to communicate the intention of {term}`packet` deletion to the recipient. - -To effectively mark a {term}`User ID` as invalid, the user can publish a copy of their {term}`certificate` with a {term}`Certification Revocation signature` ({term}`type ID` `0x30`) attached to the invalidated {term}`User ID`. This {term}`signature` signals that the specified {term}`User ID` is no longer valid or associated with the {term}`certificate holder`. - -The structure of a {term}`Certification Revocation signature` is as follows: - -| {term}`Subpacket` | Area | {term}`Critical` | Mandatory | Notes | -|--------------------------------------------------------------------|-----------------------------|------------------------------------------|----------------------|-------------------------------------------------------------------------------------| -| {term}`Signature Creation Time` | {term}`Hashed` | True | True | Current time | -| {term}`Issuer Fingerprint` | {term}`Hashed` | True or False | Strongly Recommended | The {term}`primary key` is the {term}`issuer` | -| {term}`Reason for Revocation` | {term}`Hashed` | True | False | Determines {term}`soft` or {term}`hard revocation` | - -For {term}`User ID` {term}`revocations`, the *{term}`Reason for Revocation`* {term}`subpacket` is crucial. A value of `0` means no specific reason, leading to a {term}`hard revocation`, while `32` indicates the {term}`User ID` is no longer valid, resulting in a {term}`soft revocation`. Omitting the {term}`reason subpacket` is also equivalent to a {term}`hard revocation`. - -It is generally advisable to use reason code `32` for revoking {term}`User IDs`. - -(binding_subkeys)= -#### Add a subkey - -As part of {term}`life-cycle management`, users may need to add a new {term}`subkey` to their {term}`OpenPGP certificate`, often for reasons such as upgrading to a {term}`subkey` with more advanced cryptographic algorithms. The process involves creating a specific {term}`signature` structure: - -| {term}`Subpacket` | Area | {term}`Critical` | Mandatory | Notes | -|---------------------------------------------------------------------------------------------|-----------------------------|------------------------------------------|-------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| {term}`Signature Creation Time` | {term}`Hashed` | True | True | Current time | -| {term}`Issuer Fingerprint` | {term}`Hashed` | True or False | Strongly Recommended | The {term}`primary key` is the {term}`issuer` | -| {term}`Key Flags` | {term}`Hashed` | True | Strongly Recommended | Determine the usage of the {term}`key` | -| {term}`Key Expiration Time` | {term}`Hashed` | True | False | Specifies the {term}`expiration time` of the {term}`subkey` | -| {term}`Embedded Signature` | {term}`Hashed` | True | If {term}`Key Flags` contains **{term}`S`** | {term}`Signing subkeys` require embedded *{term}`Primary Key Binding`* {term}`signature` | -| {term}`Hash Algorithm Preferences` | {term}`Hashed` | False | False | Per {term}`key` {term}`preferences` | -| {term}`Compression Algorithm Preferences` | {term}`Hashed` | False | False | Per {term}`key` {term}`preferences` | -| {term}`Symmetric Algorithm Preferences` | {term}`Hashed` | False | False | Per {term}`key` {term}`preferences` | -| {term}`AEAD Algorithm Preferences` | {term}`Hashed` | False | False | Per {term}`key` {term}`preferences` | - -In addition to these {term}`subpackets`, users can specify {term}`algorithm preferences` for each {term}`subkey`, distinct from those set in the {term}`certificate`'s *{term}`Direct Key`* {term}`signature`. - -#### Revoke a subkey - -{term}`Subkeys`, like {term}`User IDs`, can be individually revoked in OpenPGP. -This is done by issuing a {term}`Subkey Revocation signature` ({term}`type ID` `0x28`) using the {term}`primary key`. - -The structure of such a {term}`signature` is straightforward: - -| {term}`Subpacket` | Area | {term}`Critical` | Mandatory | Notes | -|--------------------------------------------------------------------|-----------------------------|------------------------------------------|----------------------|-------------------------------------------------------------------------------------| -| {term}`Signature Creation Time` | {term}`Hashed` | True | True | Current time | -| {term}`Issuer Fingerprint` | {term}`Hashed` | True or False | Strongly Recommended | The {term}`primary key` is the {term}`issuer` | -| {term}`Reason for Revocation` | {term}`Hashed` | True | False | Determines {term}`soft` or {term}`hard revocation` | - - -In {term}`Subkey Revocation signatures`, the [reason for revocation](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-reason-for-revocation) {term}`subpacket` can only have values in the range of `0-3`. The values `1` ({term}`key` superseded) and `3` ({term}`key` retired and no longer used) indicate {term}`soft revocations`, whereas values `0` (no reason) and `2` ({term}`key` compromised) indicate {term}`hard revocations`. - -Note that a value of `32` is not applicable in these {term}`signatures`. - -```{admonition} TODO -:class: warning - -Research and explain hardness in the context of subkey revocations. What does a hard subkey revocation express concretely? -``` - -#### Revoke a certificate - -Users may find themselves needing to revoke their entire {term}`OpenPGP certificate`, rendering it unusable. This could be for various reasons, such as migrating to a new {term}`certificate` or in response to a compromise of the {term}`certificate`'s {term}`secret key material`. - -While a {term}`soft-revoked` {term}`certificate` can be re-validated at a later time with a new {term}`certification`, a {term}`hard revocation` is permanent. - -The recommended way to {term}`revoke` a {term}`certificate` is by issuing a {term}`Key Revocation signature` ({term}`type ID` `0x20`). Its structure is similar to that of a {term}`Certification Revocation signature`. - -| {term}`Subpacket` | Area | {term}`Critical` | Mandatory | Notes | -|--------------------------------------------------------------------|-----------------------------|------------------------------------------|----------------------|-------------------------------------------------------------------------------------| -| {term}`Signature Creation Time` | {term}`Hashed` | True | True | Current time | -| {term}`Issuer Fingerprint` | {term}`Hashed` | True or False | Strongly Recommended | The {term}`primary key` is the {term}`issuer` | -| {term}`Reason for Revocation` | {term}`Hashed` | True | False | Determines {term}`soft` or {term}`hard revocation` | - -For {term}`Key Revocation signatures`, 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`. - -#### Common subpackets in OpenPGP signatures - -In OpenPGP, certain {term}`subpackets` are universally expected across all types of {term}`signatures`, serving fundamental roles in the {term}`signature`'s structure, {term}`verification` and {term}`validation`: - -* **{term}`Signature Creation Time`**: This is a mandatory {term}`subpacket` in every {term}`OpenPGP signature`. It contains the timestamp of when the {term}`signature` was created. For security and integrity, this {term}`subpacket` must be located in the {term}`hashed area` of the {term}`signature` and is recommended to be marked as {term}`critical`. - -* **{term}`Issuer Fingerprint`**: Essential for {term}`signature` {term}`validation`, this {term}`subpacket` identifies the {term}`key` (or {term}`subkey`) that was used to create the {term}`signature`. OpenPGP v6 {term}`signatures` should include the {term}`Issuer Fingerprint subpacket`, containing the 32-byte {term}`fingerprint` of the {term}`key`. - -```{note} -The {term}`key` used as the {term}`issuer` in the {term}`signature` might be a {term}`subkey` of the {term}`certificate`. -``` - -These {term}`subpackets` can be placed in either the {term}`hashed` or {term}`unhashed area` due to its self-{term}`authenticating` nature. However, we recommend including them in the {term}`signature`'s {term}`hashed area`. - -### Managing subpacket conflicts and duplication - -In {term}`OpenPGP signatures`, both the {term}`hashed` and {term}`unhashed areas` are composed of lists of {term}`subpackets`. Inherently, this structure permits the duplication of the same {term}`subpacket`, which could lead to conflicts. To manage these potential conflicts, the following strategies are used: - -- **Precedence of {term}`hashed area`**: {term}`Subpackets` within the {term}`hashed area` of a {term}`signature` take precedence over those in the {term}`unhashed area`. This hierarchy helps resolve conflicts when the same {term}`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` have different {term}`expiration times`. 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` should favor the last occurrence of a conflicting {term}`subpacket` in the {term}`hashed area`. - -In certain scenarios, having duplicate {term}`subpackets` with conflicting content is logical and even necessary. For example, consider a {term}`signature` created by a version 4 {term}`issuer` {term}`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` would differ between these versions. Therefore, a v4 signature might contain two {term}`issuer key ID subpackets`, each with different, yet correct values for v3 and v4 {term}`keys`, respectively. This allows for backward compatibility and ensures the {term}`signature` can be {term}`validated` under both {term}`key ID` calculation schemes. diff --git a/book/source/17b-adv-private.md b/book/source/17b-adv-private.md new file mode 100644 index 0000000..9180f31 --- /dev/null +++ b/book/source/17b-adv-private.md @@ -0,0 +1,82 @@ + + +# Advanced material: Private key material in OpenPGP + +(key-store-design)= +## Private keystores + +This section examines the diverse architectures and operational mechanics of private keystores in OpenPGP. It focuses on the various design choices, their functional implications, and how they contribute to the secure management of private key material. + +### Design variations + +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. +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. + +```{note} +The third design option, involving the storage of full TSKs in the private key subsystem, can cause "split brain" problems. + +For example, a private keystore might contain a TSK with outdated certificate metadata, marking the certificate as expired, while the updated version in the local public keystore could indicate an extended expiration date. + +This problem was notably present in GnuPG 1.x, which held separate TSK copies in its private store component. Similarly, the current design of Thunderbird's OpenPGP subsystem can lead to users experiencing such issues. +``` + +### Two-tier architecture + +At its core, an OpenPGP private key subsystem performs operations requiring only the private cryptographic key material, akin to the "separate backend operations" model described above. + +However, the subsystem also supports operations that require additional access to the metadata of the component key. These operations, supplementary to the core keystore operations, do not involve the private key material. + +When implementing a keystore based on hardware cryptographic devices like [OpenPGP card](card-priv), its design will consist of two layers: + +- **core layer**: directly handles private key material, and +- **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. + + 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). +``` + +### Addressing individual keys + +A critical aspect of private keystore design involves determining how users address individual keys. + +One common method is using the fingerprint of each component key. The availability of these fingerprints, however, depends on the underlying technology of the keystore. For instance, in software-based private keystores or OpenPGP cards, fingerprints of component keys are usually readily available. Keystores relying on generic cryptographic hardware, like TPMs, need to implement their own mechanisms for tracking and managing the fingerprints of each key. + +### Additional keystore duties + +In addition to key management, a keystore often involves various supplementary functions: + +- **Tracking devices**: Keystores may track which devices contain particular component keys. + +- **Handling secrets**: This involves the management of sensitive information such as passphrases for software keys or PINs for OpenPGP cards. + +- **User interaction alerts**: Keystores might also need to prompt users for necessary interactions during certain operations. For example, OpenPGP cards may require user touch confirmation to authorize each cryptographic action. + +## Understanding key overwriting (KO) attacks + +### What they are + +OpenPGP is subject to specific vulnerabilities known as key overwriting (KO) attacks. These attacks exploit weaknesses in how encrypted private keys or their metadata are handled, potentially leading to the leakage of secret data when the key is used. The core issue lies in OpenPGP's handling of Secret-Key packets, where corruption of the non-encrypted fields can cause the unaltered private key material to be used with altered parameters. This mismatch can result in private key leakage. + +Importantly, KO attacks are particularly relevant when an attacker is responsible for storing a user's encrypted private key. By altering the algorithm field in the Secret-Key packet, the attacker may cause the user to perform a cryptographic operation with a different algorithm. E.g., performing a DSA operation with ECC private key material. By observing the output of that attacker-corrupted operation, the attacker can recover the user's unencrypted private key material, even though the attacker had no direct access to it. + +### Mitigation + +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 consider if this attack class is a concern in their applications. + +Private keys that are protected with [S2K usage mode 253 (AEAD)](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-secret-key-encryption), are not vulnerable to 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 packet, then decryption of the private key material will fail, and the user is prevented from e.g. accidentally using the key material with an altered attacker-controlled algorithm. + +Note that while S2K usage mode 253 (AEAD) has been introduced in the OpenPGP version 6 specification, it can also be applied to OpenPGP version 4 key material (also see {ref}`migration_s2k`). + +#### Resources + +For comprehensive information on KO attacks, including background, attack vectors, countermeasures, and technical analyses, visit [KOpenPGP.com](https://www.kopenpgp.com/). It is based on the paper "Victory by KO: Attacking OpenPGP Using Key Overwriting" written by Lara Bruseghini, Daniel Huigens, and Kenneth G. Paterson for the Proceedings of ACM Conference on Computer and Communications Security, Los Angeles, November 2022. diff --git a/book/source/17c-adv-signatures.md b/book/source/17c-adv-signatures.md new file mode 100644 index 0000000..539d602 --- /dev/null +++ b/book/source/17c-adv-signatures.md @@ -0,0 +1,55 @@ + + +# Advanced material: OpenPGP Signatures + +(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` in OpenPGP with user-defined {term}`notations`. {term}`Issuers` can use these {term}`notations` to add name-value pairs to an {term}`OpenPGP signature`. + +{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. + +{term}`Notations`, as described earlier, allow for user-defined extensions to the {term}`OpenPGP signature subpacket types`. A practical and popular application of this functionality is seen in Keyoxide, a decentralized {term}`identity verification` service. Keyoxide uses {term}`notations` in the `ariadne.id` namespace. For the details of this {term}`implementation`, refer to the [Keyoxide documentation](https://docs.keyoxide.org/wiki/ariadne-identity/). + +## Choosing the hash algorithm for a signature + +A central element of signature packets is the hash digest of the input data. Most OpenPGP software supports a set of different hash mechanisms, of which one is chosen for each signature packet (this is one aspect of OpenPGP's *cryptographic agility*), and used to calculate the hash digest. + +Different hash mechanisms offer different trade-offs: + +- *Hash digest size*: Larger hash size tends to correspond with greater strength against cryptanalysis, and hash digests are relatively small: at the time of this writing, typical sizes are 32 to 64 bytes. However, for some use cases - especially where small messages are sent over a bandwidth-limited transport - larger hash sizes may unacceptably increase message size. +- *Computational cost*: Different hash algorithms may have different computational costs. Some OpenPGP users may prefer to limit this cost, for example on constrained computing environments. + +The following sections discuss how the hash algorithm is chosen, based on preferences that are associated with the involved OpenPGP certificates. + +### Typically: Local determination + +Often, signature creation isn't targeted at a specific receiver. Many signatures are issued for an indeterminate set of "anyone who receives the signature." + +For example, self-signatures that form a certificate are aimed at everyone who interacts with that certificate. Similarly, when creating a data signature for a software package, this signature is aimed at "anyone who will check the signature," often over a long period of time, easily spanning years. + +In such cases, the issuer of that signature chooses the hash algorithm locally, without following preferences of a third party. + +### With a specific recipient: "Negotiation" based on recipient's preferences + +In contrast, when a message is created for a specific recipient, the sender can - and should - choose the hash algorithm for the signature packet [based on the recipient's hash algorithm preference](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-hash-algorithm-preferences). + +The recipient's hash algorithm preference is defined in metadata of their certificate, see {ref}`algo-pref` for more details. + +In this workflow, the signed hash digest is created with a hash algorithm that follows the recipient's preferences, and its intersection with the sender's capabilities and preferences. + +## 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. + +That is: + +- OpenPGP version 6 keys must generate version 6 signature packets +- OpenPGP version 4 keys must generate version 4 signature packets + +Note that some historical version 3 signature packets may still be relevant for applications that handle old OpenPGP data[^sig-v3]. These version 3 signature packets will have been generated by version 4 keys. + +[sig-v3]Version 4 signature packets were introduced in [RFC 2440](https://datatracker.ietf.org/doc/html/rfc2440#section-5.2) in 1998, which specifies that applications SHOULD generate v4 signature, however generation of v3 signature packets has remained allowed through [RFC 4880](https://www.rfc-editor.org/rfc/rfc4880.html#section-5.2). \ No newline at end of file diff --git a/book/source/17d-adv-sign-data.md b/book/source/17d-adv-sign-data.md new file mode 100644 index 0000000..f031233 --- /dev/null +++ b/book/source/17d-adv-sign-data.md @@ -0,0 +1,52 @@ + + +# Advanced material: Signatures over data + +## Nesting of one-pass signatures + +Signing a message using the one-pass mechanism involves prepending a *One-Pass-Signature* (OPS) packet to the message and appending the corresponding signature, sandwiching the signed content. + +An OpenPGP message can contain multiple signatures added that way. + +```{note} +One-Pass-Signatures are nested, meaning the outermost One-Pass-Signature packet corresponds to the outermost signature packet. +``` + +When a message is signed, the signature is always calculated over the contents of the literal data packet, not the literal data packet itself. +This means, that if a message, which is compressed using a compressed data packet is wrapped using a one-pass-signature, the signature is still being calculated over the plaintext inside the literal data packet. + +There is one exception though. +```{note} +Of course there is. +``` + +The OPS packet has a "nested" flag[^nested-flag], which can either be `1` or `0`. +If this flag is set to `0`, it indicates that further OPSs will follow this packet, which are calculated over the same plaintext data as this OPS is. A value of `1` indicates, that either no further OPS packets will follow (this OPS is the last), or that this OPS is calculated over the the usual plaintext data, but wrapped inside any OPS+Signature combinations that follow this OPS. + +[^nested-flag]: See [description of the nested flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-5.4-3.8.1). + +This mechanism enables attested signatures, where the signer signs an already one-pass-signed message including the already contained signature. + +As a practical example, consider the following notation: +* `LIT("Hello World")` represents a literal data packet with the content `Hello World`. +* `COMP(XYZ)` represents a compressed data packet over some other packet `XYZ`. +* `OPS₁` represents a one-pass-signature packet with the nested flag set to `1`. Analogous, `OPS₀` has the nested flag set to `0`. +* `SIG` represents a signature packet. + +A normal, one-pass-signed message looks like this: +`OPS₁ LIT("Hello World") SIG` + +Here, the signature is calculated over the plaintext `Hello World`, as is it in a message that has the following form: `OPS₁ COMP(LIT("Hello World")) SIG`. + +A message, where multiple one-pass-signatures are calculated over the same plaintext looks the following: +`OPS₀ OPS₀ OPS₁ LIT("Hello World") SIG SIG SIG` + +All three signatures are calculated over the same plaintext `Hello World`. + +Now, a message, where the signer attests an already signed message has the following format: +`OPS₁ OPS₁ LIT("Hello World") SIG SIG` + +While the inner signature is calculated over the usual plaintext `Hello World`, the outer signature is instead calculated over `OPS₁ Hello World SIG`. diff --git a/book/source/17e-adv-sig-component.md b/book/source/17e-adv-sig-component.md new file mode 100644 index 0000000..19b4110 --- /dev/null +++ b/book/source/17e-adv-sig-component.md @@ -0,0 +1,157 @@ + + +# Advanced material: Signatures on components + +## Certification recipes + +Different {term}`signatures` in OpenPGP serve various specific purposes. This section provides practical guidance on creating these {term}`signatures`, illustrating each with concrete examples. + +(change_algorithm_preferences)= +### Change algorithm preferences + +To modify the preferred {term}`symmetric`, compression, {term}`hash`, or {term}`AEAD algorithms` for a {term}`key`, the {term}`key owner` needs to issue a {term}`direct key signature` ({term}`type ID` `0x1F`) on the {term}`primary key`. + +This {term}`signature` should have the following structure: + +| {term}`Subpacket` | Area | {term}`Critical` | Mandatory | Notes | +|---------------------------------------------------------------------------------------------|-----------------------------|------------------------------------------|----------------------|----------------------------------------------------------------------------------------| +| {term}`Signature Creation Time` | {term}`Hashed` | True | True | Current time | +| {term}`Issuer Fingerprint` | {term}`Hashed` | True or False | Strongly Recommended | The {term}`primary key` is the {term}`issuer` | +| {term}`Key Flags` | {term}`Hashed` | True | False | Retain {term}`key flags` from the previous {term}`self-signature` | +| {term}`Features` | {term}`Hashed` | True | False | Retain {term}`features` from the previous {term}`self-signature` | +| {term}`Key Expiration Time` | {term}`Hashed` | True | False | Retain {term}`expiration time` from the previous {term}`self-signature`, if applicable | +| {term}`Hash Algorithm Preferences` | {term}`Hashed` | False | False | New {term}`preferences` | +| {term}`Compression Algorithm Preferences` | {term}`Hashed` | False | False | New {term}`preferences` | +| {term}`Symmetric Algorithm Preferences` | {term}`Hashed` | False | False | New {term}`preferences` | +| {term}`AEAD Algorithm Preferences` | {term}`Hashed` | False | False | New {term}`preferences` | + +### Change expiration time + +To adjust the {term}`expiration time` of an {term}`OpenPGP certificate`, a new *{term}`DirectKey`* {term}`signature` ({term}`type ID` `0x1F`) with a modified {term}`Key Expiration Time subpacket` must be issued. The structure of this {term}`signature` is identical to the one outlined in the previous section on changing {term}`algorithm preferences`. + +Additionally, the {term}`expiration time` can be altered for individual {term}`User IDs` (detailed below) or separate {term}`subkeys` (see {numref}`bind_subkey`). + +### Add User ID + +To {term}`bind` a {term}`User ID` to an {term}`OpenPGP certificate` a {term}`certification signature` ({term}`type ID` `0x10`-`0x13`) is used which should have the following structure: + +| {term}`Subpacket` | Area | {term}`Critical` | Mandatory | Notes | +|------------------------------------------------------------------------|-----------------------------|------------------------------------------|----------------------|-------------------------------------------------------------------------------------| +| {term}`Signature Creation Time` | {term}`Hashed` | True | True | Current time | +| {term}`Issuer Fingerprint` | {term}`Hashed` | True or False | Strongly Recommended | The {term}`primary key` is the {term}`issuer` | +| {term}`Primary User ID` | {term}`Hashed` | True | False | Optional | +| {term}`Signature Expiration Time` | {term}`Hashed` | True | False | Optional | + +In addition to these {term}`subpackets`, {term}`self-certifications` for {term}`User IDs` can include others – such as {term}`key flags`, {term}`features`, and {term}`algorithm preferences` – as shown in the previous table. This enables the specification of unique capabilities and {term}`preferences` for each {term}`identity` associated with the {term}`certificate`. + +### Remove or revoke a User ID + +Since {term}`OpenPGP certificates` are often distributed by the means of {term}`key servers`, new {term}`signatures` on a {term}`certificate` are often "merged" into existing copies of the {term}`certificate` locally by the recipient. + +```{admonition} TODO +:class: warning + +Link to the "Merging" section in chapter 4, once merged. +``` + +This integration process means it is practically impossible to directly remove {term}`signatures` or {term}`User IDs` from a {term}`certificate`, as there is no way to communicate the intention of {term}`packet` deletion to the recipient. + +To effectively mark a {term}`User ID` as invalid, the user can publish a copy of their {term}`certificate` with a {term}`Certification Revocation signature` ({term}`type ID` `0x30`) attached to the invalidated {term}`User ID`. This {term}`signature` signals that the specified {term}`User ID` is no longer valid or associated with the {term}`certificate holder`. + +The structure of a {term}`Certification Revocation signature` is as follows: + +| {term}`Subpacket` | Area | {term}`Critical` | Mandatory | Notes | +|--------------------------------------------------------------------|-----------------------------|------------------------------------------|----------------------|-------------------------------------------------------------------------------------| +| {term}`Signature Creation Time` | {term}`Hashed` | True | True | Current time | +| {term}`Issuer Fingerprint` | {term}`Hashed` | True or False | Strongly Recommended | The {term}`primary key` is the {term}`issuer` | +| {term}`Reason for Revocation` | {term}`Hashed` | True | False | Determines {term}`soft` or {term}`hard revocation` | + +For {term}`User ID` {term}`revocations`, the *{term}`Reason for Revocation`* {term}`subpacket` is crucial. A value of `0` means no specific reason, leading to a {term}`hard revocation`, while `32` indicates the {term}`User ID` is no longer valid, resulting in a {term}`soft revocation`. Omitting the {term}`reason subpacket` is also equivalent to a {term}`hard revocation`. + +It is generally advisable to use reason code `32` for revoking {term}`User IDs`. + +(binding_subkeys)= +### Add a subkey + +As part of {term}`life-cycle management`, users may need to add a new {term}`subkey` to their {term}`OpenPGP certificate`, often for reasons such as upgrading to a {term}`subkey` with more advanced cryptographic algorithms. The process involves creating a specific {term}`signature` structure: + +| {term}`Subpacket` | Area | {term}`Critical` | Mandatory | Notes | +|---------------------------------------------------------------------------------------------|-----------------------------|------------------------------------------|-------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| {term}`Signature Creation Time` | {term}`Hashed` | True | True | Current time | +| {term}`Issuer Fingerprint` | {term}`Hashed` | True or False | Strongly Recommended | The {term}`primary key` is the {term}`issuer` | +| {term}`Key Flags` | {term}`Hashed` | True | Strongly Recommended | Determine the usage of the {term}`key` | +| {term}`Key Expiration Time` | {term}`Hashed` | True | False | Specifies the {term}`expiration time` of the {term}`subkey` | +| {term}`Embedded Signature` | {term}`Hashed` | True | If {term}`Key Flags` contains **{term}`S`** | {term}`Signing subkeys` require embedded *{term}`Primary Key Binding`* {term}`signature` | +| {term}`Hash Algorithm Preferences` | {term}`Hashed` | False | False | Per {term}`key` {term}`preferences` | +| {term}`Compression Algorithm Preferences` | {term}`Hashed` | False | False | Per {term}`key` {term}`preferences` | +| {term}`Symmetric Algorithm Preferences` | {term}`Hashed` | False | False | Per {term}`key` {term}`preferences` | +| {term}`AEAD Algorithm Preferences` | {term}`Hashed` | False | False | Per {term}`key` {term}`preferences` | + +In addition to these {term}`subpackets`, users can specify {term}`algorithm preferences` for each {term}`subkey`, distinct from those set in the {term}`certificate`'s *{term}`Direct Key`* {term}`signature`. + +### Revoke a subkey + +{term}`Subkeys`, like {term}`User IDs`, can be individually revoked in OpenPGP. +This is done by issuing a {term}`Subkey Revocation signature` ({term}`type ID` `0x28`) using the {term}`primary key`. + +The structure of such a {term}`signature` is straightforward: + +| {term}`Subpacket` | Area | {term}`Critical` | Mandatory | Notes | +|--------------------------------------------------------------------|-----------------------------|------------------------------------------|----------------------|-------------------------------------------------------------------------------------| +| {term}`Signature Creation Time` | {term}`Hashed` | True | True | Current time | +| {term}`Issuer Fingerprint` | {term}`Hashed` | True or False | Strongly Recommended | The {term}`primary key` is the {term}`issuer` | +| {term}`Reason for Revocation` | {term}`Hashed` | True | False | Determines {term}`soft` or {term}`hard revocation` | + + +In {term}`Subkey Revocation signatures`, the [reason for revocation](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-reason-for-revocation) {term}`subpacket` can only have values in the range of `0-3`. The values `1` ({term}`key` superseded) and `3` ({term}`key` retired and no longer used) indicate {term}`soft revocations`, whereas values `0` (no reason) and `2` ({term}`key` compromised) indicate {term}`hard revocations`. + +Note that a value of `32` is not applicable in these {term}`signatures`. + +```{admonition} TODO +:class: warning + +Research and explain hardness in the context of subkey revocations. What does a hard subkey revocation express concretely? +``` + +### Revoke a certificate + +Users may find themselves needing to revoke their entire {term}`OpenPGP certificate`, rendering it unusable. This could be for various reasons, such as migrating to a new {term}`certificate` or in response to a compromise of the {term}`certificate`'s {term}`secret key material`. + +While a {term}`soft-revoked` {term}`certificate` can be re-validated at a later time with a new {term}`certification`, a {term}`hard revocation` is permanent. + +The recommended way to {term}`revoke` a {term}`certificate` is by issuing a {term}`Key Revocation signature` ({term}`type ID` `0x20`). Its structure is similar to that of a {term}`Certification Revocation signature`. + +| {term}`Subpacket` | Area | {term}`Critical` | Mandatory | Notes | +|--------------------------------------------------------------------|-----------------------------|------------------------------------------|----------------------|-------------------------------------------------------------------------------------| +| {term}`Signature Creation Time` | {term}`Hashed` | True | True | Current time | +| {term}`Issuer Fingerprint` | {term}`Hashed` | True or False | Strongly Recommended | The {term}`primary key` is the {term}`issuer` | +| {term}`Reason for Revocation` | {term}`Hashed` | True | False | Determines {term}`soft` or {term}`hard revocation` | + +For {term}`Key Revocation signatures`, 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`. + +### Common subpackets in OpenPGP signatures + +In OpenPGP, certain {term}`subpackets` are universally expected across all types of {term}`signatures`, serving fundamental roles in the {term}`signature`'s structure, {term}`verification` and {term}`validation`: + +* **{term}`Signature Creation Time`**: This is a mandatory {term}`subpacket` in every {term}`OpenPGP signature`. It contains the timestamp of when the {term}`signature` was created. For security and integrity, this {term}`subpacket` must be located in the {term}`hashed area` of the {term}`signature` and is recommended to be marked as {term}`critical`. + +* **{term}`Issuer Fingerprint`**: Essential for {term}`signature` {term}`validation`, this {term}`subpacket` identifies the {term}`key` (or {term}`subkey`) that was used to create the {term}`signature`. OpenPGP v6 {term}`signatures` should include the {term}`Issuer Fingerprint subpacket`, containing the 32-byte {term}`fingerprint` of the {term}`key`. + +```{note} +The {term}`key` used as the {term}`issuer` in the {term}`signature` might be a {term}`subkey` of the {term}`certificate`. +``` + +These {term}`subpackets` can be placed in either the {term}`hashed` or {term}`unhashed area` due to its self-{term}`authenticating` nature. However, we recommend including them in the {term}`signature`'s {term}`hashed area`. + +## Managing subpacket conflicts and duplication + +In {term}`OpenPGP signatures`, both the {term}`hashed` and {term}`unhashed areas` are composed of lists of {term}`subpackets`. Inherently, this structure permits the duplication of the same {term}`subpacket`, which could lead to conflicts. To manage these potential conflicts, the following strategies are used: + +- **Precedence of {term}`hashed area`**: {term}`Subpackets` within the {term}`hashed area` of a {term}`signature` take precedence over those in the {term}`unhashed area`. This hierarchy helps resolve conflicts when the same {term}`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` have different {term}`expiration times`. 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` should favor the last occurrence of a conflicting {term}`subpacket` in the {term}`hashed area`. + +In certain scenarios, having duplicate {term}`subpackets` with conflicting content is logical and even necessary. For example, consider a {term}`signature` created by a version 4 {term}`issuer` {term}`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` would differ between these versions. Therefore, a v4 signature might contain two {term}`issuer key ID subpackets`, each with different, yet correct values for v3 and v4 {term}`keys`, respectively. This allows for backward compatibility and ensures the {term}`signature` can be {term}`validated` under both {term}`key ID` calculation schemes.