From 5fbc684fd4dcb8ee6c7356cdbfd0eec29bdc99f7 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Tue, 28 Nov 2023 21:33:55 +0100 Subject: [PATCH 01/26] correct minor issues ch5 intro --- book/source/05-private.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/source/05-private.md b/book/source/05-private.md index 6251790..ddc3a05 100644 --- a/book/source/05-private.md +++ b/book/source/05-private.md @@ -6,9 +6,9 @@ SPDX-License-Identifier: CC-BY-SA-4.0 (private_key_chapter)= # Private key material in OpenPGP -This chapter discusses the handling of private key material in OpenPGP. +This chapter discusses the handling of private key material within OpenPGP. -Private key material is associated with component keys that are parts of [OpenPGP certificates](certificates_chapter). For a discussion of packet structure internals, see the chapter {ref}`zoom_private` +Private key material is associated with component keys, which are integral parts of [OpenPGP certificates](certificates_chapter). For a discussion of packet structure internals, see the chapter {ref}`zoom_private`. ## Terminology: "Certificates" and "private keys" From 710c7b830b06d5a33adf8051459accc64d59dc71 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Tue, 28 Nov 2023 21:45:36 +0100 Subject: [PATCH 02/26] edit Terminology: "certificates" and "private keys --- book/source/05-private.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/book/source/05-private.md b/book/source/05-private.md index ddc3a05..630cc3e 100644 --- a/book/source/05-private.md +++ b/book/source/05-private.md @@ -10,24 +10,25 @@ This chapter discusses the handling of private key material within OpenPGP. Private key material is associated with component keys, which are integral parts of [OpenPGP certificates](certificates_chapter). For a discussion of packet structure internals, see the chapter {ref}`zoom_private`. -## Terminology: "Certificates" and "private keys" +## Terminology: "certificates" and "private keys" -Recall that in this document, we use the term *OpenPGP certificate* to refer to what are often called "OpenPGP public keys": OpenPGP certificates are the combination of component public keys, identity components, binding self-signatures and third-party certifications (as discussed in the previous chapter, {ref}`certificates_chapter`). +Recall that in this document, the term *OpenPGP certificate* refers to what are commonly known as "OpenPGP public keys." OpenPGP certificates are the combination of component public keys, identity components, binding self-signatures, and third-party certifications, +as discussed in the previous chapter ({ref}`certificates_chapter`). -This chapter is about the remaining counterpart to the elements of certificates: The corresponding *private key material* of component keys. +This chapter focuses on the corresponding counterpart to the elements of certificates: the *private key material* of component keys. -In this book, we treat the private key material as logically separate from the OpenPGP certificate. A separate subsystem typically handles operations that use private key material. It is useful to think about OpenPGP certificates on one hand, and the associated private key material, on the other, as related but separate elements[^pkcs11]: +In this documentation, we treat the private key material as logically separate from the OpenPGP certificate. Operations that use private key material are typically managed by a separate subsystem. It is useful to view OpenPGP certificates and the associated private key material as related but distinct elements[^pkcs11]: ```{figure} diag/OpenPGPCert_with_privatekeystore.png :name: fig-openpgp-certificate-with-private-key-store -:alt: Depicts a diagram on white background with an OpenPGP Certificate and a private key store. Gray dotted lines connect the green public key symbols of the OpenPGP Certificate with red dotted private key symbols in the private key store. +:alt: A diagram on white background showing an OpenPGP certificate and a private key store. Gray dotted lines connect the green public key symbols of the OpenPGP certificate to red dotted private key symbols in the private key store. An OpenPGP certificate, with the associated private key material handled in a separate subsystem. ``` -[^pkcs11]: This kind of distinction between certificates (which combine public key material and identity information) on the one hand, and private key material on the other, is also applied in the data model of [PKCS #11](https://en.wikipedia.org/wiki/PKCS_11) cryptographic systems. +[^pkcs11]: The distinction between certificates (which combine public key material and identity information) and private key material is similarly made in the data model of [PKCS #11](https://en.wikipedia.org/wiki/PKCS_11) cryptographic systems. -However, there is one exception. The cryptographic private key material is sometimes embedded in an OpenPGP framing format that also contains the certificate: Transferable secret keys (TSK). +However, there is one exception. Cryptographic private key material is sometimes embedded within an OpenPGP framing format that also contains the certificate: transferable secret keys (TSK). ## Transferable secret key format From f6e456dd552c18fbea3fc854ff6f945b0a51b2ea Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Tue, 28 Nov 2023 21:56:12 +0100 Subject: [PATCH 03/26] edit ch5 tsk format --- book/source/05-private.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/book/source/05-private.md b/book/source/05-private.md index 630cc3e..0bcd6d5 100644 --- a/book/source/05-private.md +++ b/book/source/05-private.md @@ -21,7 +21,7 @@ In this documentation, we treat the private key material as logically separate f ```{figure} diag/OpenPGPCert_with_privatekeystore.png :name: fig-openpgp-certificate-with-private-key-store -:alt: A diagram on white background showing an OpenPGP certificate and a private key store. Gray dotted lines connect the green public key symbols of the OpenPGP certificate to red dotted private key symbols in the private key store. +:alt: A diagram on a white background showing an OpenPGP certificate and a private key store. Gray dotted lines connect the green public key symbols of the OpenPGP certificate to red dotted private key symbols in the private key store. An OpenPGP certificate, with the associated private key material handled in a separate subsystem. ``` @@ -32,26 +32,26 @@ However, there is one exception. Cryptographic private key material is sometimes ## Transferable secret key format -Sometimes it is useful to handle OpenPGP certificates combined with private key material in the form of [*transferable secret keys (TSK)*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-11.html#name-transferable-secret-keys). Transferable secret keys are a serialized format that combines OpenPGP certificate data with the 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.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-11.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} diag/TSK.png :name: fig-transferable-secret-key -:alt: Depicts a box on white background with the title "Transferable secret key". It is identical to the figure depicting an OpenPGP certificate, with the exception, that in each component key box, below the green public key symbol, also the red dotted private key symbol is shown. +:alt: A box on a white background titled "transferable secret key." It resembles the figure depicting an OpenPGP certificate, except that in each component key box, below the green public key symbol, the red-dotted private key symbol is also shown. OpenPGP certificate with integrated private key material, as a TSK ``` -The TSK format can be useful for backups of OpenPGP key material, or to move a key to a different computer[^gpg-tsk]. See the chapter {ref}`zoom_private` for insights into the packet structure of a TSK. +The TSK format is particularly useful for backups of OpenPGP key material or transferring a key to a different computer[^gpg-tsk]. For insights into the packet structure of a TSK, see the chapter {ref}`zoom_private`. -[^gpg-tsk]: For example, with GnuPG, an OpenPGP key can be exported in (armored) TSK format like this: `gpg --export-secret-key --armor ` +[^gpg-tsk]: For example, in GnuPG, an OpenPGP key can be exported in (armored) TSK format using the following command: `gpg --export-secret-key --armor `. ```{admonition} Terminology :class: note -Transferable secret keys are sometimes colloquially referred to as "OpenPGP private keys". +Transferable secret keys are sometimes colloquially referred to as "OpenPGP private keys." ``` -Historically, the concept of TSKs, which combine all aspects of an OpenPGP certificate and the associated private key material, has sometimes been conflated with OpenPGP private key operations. We consider it more helpful to think of TSKs as a specialized format for storage/transport, and not as a data structure for use in a key store. Also see {ref}`key-store-design`. +Historically, the concept of TSKs, which combine all components of an OpenPGP certificate with the associated private key material, has sometimes been conflated with OpenPGP private key operations. However, it is more accurate to view TSKs as a specialized format for storage and transport, rather than as a data structure for use in a key store. For further details, see {ref}`key-store-design`. (encrypted_secrets)= ## Protection of private key material in OpenPGP From 2d1c71fd7d72c84ba9cdc581f0110b5262770f1f Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Tue, 28 Nov 2023 23:26:31 +0100 Subject: [PATCH 04/26] edit passkey section (restored) --- book/source/05-private.md | 35 +++++++++++++++++------------------ 1 file changed, 17 insertions(+), 18 deletions(-) diff --git a/book/source/05-private.md b/book/source/05-private.md index 0bcd6d5..7851171 100644 --- a/book/source/05-private.md +++ b/book/source/05-private.md @@ -56,41 +56,41 @@ Historically, the concept of TSKs, which combine all components of an OpenPGP ce (encrypted_secrets)= ## Protection of private key material in OpenPGP -In OpenPGP format, private key material can optionally be protected with a [passphrase](https://en.wikipedia.org/wiki/Passphrase). +In the OpenPGP format, private key material can be optionally protected with a [passphrase](https://en.wikipedia.org/wiki/Passphrase). -Protecting private key material with a passphrase can be useful when a third party obtains a copy of the OpenPGP key data, but doesn't know the passphrase. In this scenario, the attacker may have obtained a copy of an OpenPGP key, but is unable to use it, because it is protected with a passphrase that is not known to the attacker. +This method proves effective in scenarios where an unauthorized party obtains the OpenPGP key data but does not know the passphrase. Such a safeguard renders the key unusable to the attacker, effectively protecting it against unauthorized access or use. ### Transforming a passphrase into a symmetric key -When protecting private key material in OpenPGP, a symmetric key is derived from the user's passphrase. This key is then used to protect the OpenPGP private key data. +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. -For this purpose, the OpenPGP standard defines a family of mechanisms called [string-to-key (S2K)](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-11.html#name-string-to-key-s2k-specifier). These are used to derive (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.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-11.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} diag/passphrase_using_S2K.png :name: fig-passphrase-using-s2k -:alt: Depicts a diagram on white background with the title "Converting a passphrase into a symmetric key". On the left hand side a box with dotted yellow frame and light yellow background and the text "correct horse battery staple" is shown. It is connected by a dotted yellow line with the word "Passphrase". Right of the passphrase an arrow with green dotted frame, light green background and the text "S2K mechanism (string-to-key)", pointing to the right is shown. On the right hand side the yellow symmetric key symbol is shown. +:alt: A diagram on a white background titled "Converting a passphrase into a symmetric key." On the left is a light-yellow box with dotted-yellow borders framing the phrase "correct horse battery staple." A dotted yellow line falls below the box to the term "passphrase." To the right of the box is a light-green arrow with green-dotted borders and the text "S2K mechanism (string-to-key). The arrow points to its right, where a yellow symmetric key symbol is shown. Deriving a symmetric key from a passphrase ``` -This symmetric key is used to protect the private key material "at rest." E.g., while it is stored on disk. To use a passphrase-protected OpenPGP private key, it is decrypted using the symmetric key, and used for private key operations, while it is temporarily unlocked, in memory. +This symmetric key is used to protect the private key material it is in a passive state, for example, when stored on disk. To use a passphrase-protected OpenPGP private key, it is first decrypted using the symmetric key and then used for private key operations, remaining temporarily unlocked in memory. #### Mechanisms for symmetric key generation -Over time, OpenPGP has specified different S2K [mechanisms to generate symmetric keys](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-11.html#name-string-to-key-s2k-types-reg), following the state of the art. Of these, two are recommended unconditionally, today: +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-11.html#name-string-to-key-s2k-types-reg), 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-11.html#name-argon2), which was newly added in OpenPGP version 6. It is a memory-hard mechanism, which reduces the efficiency of brute-force attacks with specialised hardware. -- [Iterated and Salted S2K](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-11.html#name-iterated-and-salted-s2k), which OpenPGP version 4 implementations can handle. +- [**Argon2**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-11.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-11.html#name-iterated-and-salted-s2k): This mechanism is a staple with OpenPGP version 4 implementations. -A third mechanism is allowed conditionally for generation. Decryption of private keys that use obsolete mechanisms is allowed. +A third mechanism is conditionally allowed for key generation. Decryption of private keys that use obsolete mechanisms is also allowed. -The RFC refers to the mechanism that is used to *generate* a symmetric key from a passphrase with the term "String-to-Key (S2K) specifier" or "String-to-Key (S2K) specifier type." +The RFC uses the terms "String-to-Key (S2K) specifier" or "String-to-Key (S2K) specifier type" for mechanisms used to *generate* a symmetric key from a passphrase. ### Using the symmetric key for encryption -So far, we've looked at generating a symmetric key from a passphrase. Following that, the symmetric key is used to encrypt or decrypt the OpenPGP private key material. +The generation of a symmetric key from a passphrase leads to its subsequent use in encrypting or decrypting OpenPGP private key material. -The RFC refers to the mechanism that is used to *apply* the symmetric key with the term "String-to-Key Usage (S2K usage)". +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). @@ -98,13 +98,12 @@ Different mechanisms are specified [for encryption of OpenPGP private key materi The OpenPGP mechanism for protecting private key material applies individually to each component key: -- Private key material for individual component keys of one certificate can be protected with different mechanisms, and/or -- using different passphrases. -- Individual component keys may be stored in unprotected form, while others are protected. +- Private key material for individual component keys within a single certificate can be protected with different mechanisms or passphrases. +- Individual component keys may be stored in unprotected form, while others are secured. -However, usually, when creating a certificate, the user's software will use the same encryption mechanism and passphrase for all component keys. This might give the erroneous impression that all component private key material is internally encrypted in one monolithic operation, necessarily using only one passphrase. +Commonly, when creating a certificate, the user's software will use the same encryption mechanism and passphrase for all component keys. This might give the erroneous impression that all component private key material is encrypted in one, monolithic operation using a single passphrase. -But for example when adding new subkeys to a certificate at a later date, the user might choose to use a different passphrase. Or the user's software may choose a different encryption mechanism, e.g., based on updated best practices. +However, variations are possible, such as when adding new subkeys to an existing certificate. In such cases, a user might choose a different passphrase, or the software might select a different encryption mechanism, for instance, for updated best practices. (card-priv)= ## OpenPGP card for private keys From f508aaa3621d9670ae7fea53fc14ca51efb2fcff Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Thu, 30 Nov 2023 14:47:51 +0100 Subject: [PATCH 05/26] edit ch5 section on OpenPGP cards for private keys --- book/source/05-private.md | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/book/source/05-private.md b/book/source/05-private.md index 7851171..d45ce3a 100644 --- a/book/source/05-private.md +++ b/book/source/05-private.md @@ -106,23 +106,19 @@ Commonly, when creating a certificate, the user's software will use the same enc However, variations are possible, such as when adding new subkeys to an existing certificate. In such cases, a user might choose a different passphrase, or the software might select a different encryption mechanism, for instance, for updated best practices. (card-priv)= -## OpenPGP card for private keys +## OpenPGP cards for private keys -[OpenPGP card](https://en.wikipedia.org/wiki/OpenPGP_card) devices are a type of hardware security device. +[OpenPGP cards](https://en.wikipedia.org/wiki/OpenPGP_card) represent a category of hardware security devices specifically designed to handle OpenPGP private key material. These cards offer an alternative to directly managing private key material on the user's computer. -They are one popular way to handle OpenPGP private key material. Using an OpenPGP card is an alternative to directly handling private key material on the user's computer. +Hardware security devices, such as OpenPGP cards, are designed to prevent the user's computer from direct access to the private key material. The goal is to make it impossible to exfiltrate the key material, even when a remote attacker has fully compromised the user's system. -Hardware security devices, such as OpenPGP cards, are designed so that the user's computer never has direct access to the private key material. The goal is to make it impossible to exfiltrate the key material, even when a remote attacker has fully compromised the user's system. +OpenPGP cards adhere to an open specification detailed in the [Functional Specification of the OpenPGP application on ISO Smart Card Operating Systems, Version 3.4.1](https://gnupg.org/ftp/specs/OpenPGP-smart-card-application-3.4.1.pdf). This specification has been implemented by multiple vendors across various devices, with several Free Software versions available, some of which are compatible with open hardware designs. -OpenPGP card devices implement an open specification: [Functional Specification of the OpenPGP application on ISO Smart Card Operating Systems, Version 3.4.1](https://gnupg.org/ftp/specs/OpenPGP-smart-card-application-3.4.1.pdf). Multiple vendors produce devices that implement this specification, and there are a number of Free Software implementations (some of which can even be run on open hardware designs). +Effectively, the OpenPGP card specification outlines one model for a private key store subsystem. OpenPGP cards do not store a full OpenPGP certificate. Instead, they have three distinct "key slots" designated for *signing*, *decryption*, and *authentication*. Each key slot stores the data of one component key[^missing-ecdh], including its cryptographic private key material. Additionally, OpenPGP cards explicitly store the fingerprint of each component key within the corresponding key slot. -Effectively, the OpenPGP card specification outlines one model for an OpenPGP private key store subsystem: +[^missing-ecdh]: In the case of ECDH keys, the KDF parameters (hash function ID and a symmetric encryption algorithm ID) are not stored on the OpenPGP card. This is considered a flaw in the OpenPGP card specification. These missing parameters can be handled in two ways by OpenPGP software on the host computer: either by consulting a copy of the component key (e.g., by inspecting a copy of the certificate) or by deducing the missing KDF parameters from the stored OpenPGP fingerprint on the card. -OpenPGP card devices do not store a full OpenPGP certificate. Instead, they have three "key slots", one each for *signing*, *decryption* and *authentication*. Each key slot stores the data of one component key[^missing-ecdh], complete with cryptographic private key material. Additionally, the fingerprint for the component key in each key slot is explicitly stored on the card. - -[^missing-ecdh]: In the case of ECDH keys, the KDF parameters (hash function ID and a symmetric encryption algorithm ID) are not stored on the OpenPGP card. This is considered a flaw in the OpenPGP card specification. These missing parameters can be handled in two ways, by OpenPGP software running on the host computer: Either by consulting a copy of the component key (e.g. by inspecting a copy of the certificate), or by deducing the missing KDF parameters from the OpenPGP fingerprint that is stored on the card. - -Note that explicitly stored fingerprints on OpenPGP cards are in contrast to how OpenPGP's format stores component keys: fingerprints are not explicitly stored, but calculated on the fly from the component key data. +Notably, the practice of explicitly storing fingerprints on OpenPGP cards contrasts with the general OpenPGP format, where fingerprints of component keys are not stored but are instead dynamically calculated from the key data. ## Private key operations From 4ddf0388ed96172af7a87491ff1dfd3f59e828f2 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Thu, 30 Nov 2023 14:54:44 +0100 Subject: [PATCH 06/26] edit Private key operations --- book/source/05-private.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/source/05-private.md b/book/source/05-private.md index d45ce3a..d7448de 100644 --- a/book/source/05-private.md +++ b/book/source/05-private.md @@ -122,14 +122,14 @@ Notably, the practice of explicitly storing fingerprints on OpenPGP cards contra ## Private key operations -While OpenPGP as a whole employs a broad range of cryptographic mechanisms, the set of operations that are performed in the core of a private key store are simple and very limited. +Although OpenPGP encompasses a broad range of cryptographic mechanisms, the set of operations performed within the core of a private key store are simple and very limited. Specifically, an OpenPGP private key store 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. -All required operations can be performed with access to the component keys, including their private key material. That is, [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 for the operations in a private key store. +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. (key-store-design)= ## Private key stores From 249948096ca312b581724d2360691ac5987019fd Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Thu, 30 Nov 2023 15:07:39 +0100 Subject: [PATCH 07/26] briefly introduce the content of the Private key stores section --- book/source/05-private.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/book/source/05-private.md b/book/source/05-private.md index d7448de..682f4cb 100644 --- a/book/source/05-private.md +++ b/book/source/05-private.md @@ -134,6 +134,8 @@ These essential operations require access only to the component keys and their a (key-store-design)= ## Private key stores +This section examines the diverse architectures and operational mechanics of private key stores 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 options Designs of private key subsystems in the OpenPGP space differ: From 8bfb2c8bf1b7f2f415faadae1a7c717206d76c4a Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Thu, 30 Nov 2023 15:38:23 +0100 Subject: [PATCH 08/26] edit design options/variations of privarte key store systems --- book/source/05-private.md | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/book/source/05-private.md b/book/source/05-private.md index 682f4cb..6f8043f 100644 --- a/book/source/05-private.md +++ b/book/source/05-private.md @@ -136,26 +136,24 @@ These essential operations require access only to the component keys and their a This section examines the diverse architectures and operational mechanics of private key stores 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 options +### Design variations -Designs of private key subsystems in the OpenPGP space differ: +The design of private key subsystems within the OpenPGP framework varies, offering different approaches to cryptographic operations: -1. Some designs perform the primitive cryptographic operations in a separate backend, only using the cryptographic key material itself. This type of design matches well with general purpose hardware cryptographic devices (such as TPMs). -2. An OpenPGP private key subsystem may be built around component keys - that is, 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 include metadata, which is required for some operations. ECDH operations, in particular, require metadata as KDF parameters. -3. Keeping a copy of full TSKs in the private key subsystem, and using those for private key 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. -Private key store operations require component keys, but do not require access to the rest of the certificate. +While private key store operations require component keys, they do not require access to the entire OpenPGP certificate. ```{note} -Design 3, which involves keeping a copy of full TSKs in the private key subsystem can cause "split brain" problems. +The third design option, involving the storage of full TSKs in the private key subsystem, can cause "split brain" problems. -For example, the private key store may contain a TSK, with outdated certificate metadata. The certificate may be considered expired, based on data in the TSK, while the copy of the same certificate in the local public key store might show an updated version where the expiration date has been extended[^tb-split]. +For example, a private key store might contain a TSK with outdated certificate metadata, marking the certificate as expired, while the updated version in the local public key store could indicate an extended expiration date. -This class of problem existed in GnuPG 1.x, which held separate copies of full TSKs in its private store component. +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. ``` -[^tb-split]: The current design of Thunderbird's OpenPGP subsystem can lead to users experiencing such issues. - ### Two tiers At its core, an OpenPGP private key subsystem performs operations that only require the private cryptographic key material, as in design 1. From cd6b049ae5bea1d67432604ac6da7eb9553e8050 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Thu, 30 Nov 2023 17:19:42 +0100 Subject: [PATCH 09/26] edit ### Two-tier architecture --- book/source/05-private.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/book/source/05-private.md b/book/source/05-private.md index 6f8043f..42bd71e 100644 --- a/book/source/05-private.md +++ b/book/source/05-private.md @@ -154,21 +154,21 @@ For example, a private key store might contain a TSK with outdated certificate m 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 tiers +### Two-tier architecture -At its core, an OpenPGP private key subsystem performs operations that only require the private cryptographic key material, as in design 1. +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, some operations require additional access to the metadata of the component key. Those operations can be considered supplementary to the core keystore operations, and don't involve the private key material, themselves. When implementing a key store based on hardware cryptographic devices, like [OpenPGP card](card-priv), its design will consist of two layers: +However, the subsystem also supports operations that require additional access to the metadata of the component key. These operations, supplementary to the core key store operations, do not involve the private key material. -- One that deals immediately with private key material, and -- One that performs additional cryptographic operations, which don't directly use the private key material (in particular: [AES key wrap](https://www.rfc-editor.org/rfc/rfc3394.html) for ECDH). +When implementing a key store 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} -Decryption with ECC algorithms using ECDH in particular is a multi-step procedure. + The decryption process using ECC algorithms, especially ECDH, has multiple steps. The initial step, typically 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. -Only one of these steps deals directly with private key material, and is performed by e.g. an OpenPGP card device. This step produces the "shared secret". - - An additional ["AES key unwrap"](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-ec-dh-algorithm-ecdh) step happens in software, outside the card. Also see "Advanced Encryption Standard (AES) Key Wrap Algorithm" [RFC 3394](https://www.rfc-editor.org/rfc/rfc3394.html). + 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 From 84ba8afc5c485e5b07b78b15c93ed0ed652fb63f Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Thu, 30 Nov 2023 17:34:28 +0100 Subject: [PATCH 10/26] change key store to keystore, edit two-tier section --- book/source/05-private.md | 36 +++++++++++++++++------------------- 1 file changed, 17 insertions(+), 19 deletions(-) diff --git a/book/source/05-private.md b/book/source/05-private.md index 42bd71e..d2301a3 100644 --- a/book/source/05-private.md +++ b/book/source/05-private.md @@ -21,7 +21,7 @@ In this documentation, we treat the private key material as logically separate f ```{figure} diag/OpenPGPCert_with_privatekeystore.png :name: fig-openpgp-certificate-with-private-key-store -:alt: A diagram on a white background showing an OpenPGP certificate and a private key store. Gray dotted lines connect the green public key symbols of the OpenPGP certificate to red dotted private key symbols in the private key store. +:alt: A diagram on a white background showing an OpenPGP certificate and a private keystore. Gray dotted lines connect the green public key symbols of the OpenPGP certificate to red dotted private key symbols in the private keystore. An OpenPGP certificate, with the associated private key material handled in a separate subsystem. ``` @@ -51,7 +51,7 @@ The TSK format is particularly useful for backups of OpenPGP key material or tra Transferable secret keys are sometimes colloquially referred to as "OpenPGP private keys." ``` -Historically, the concept of TSKs, which combine all components of an OpenPGP certificate with the associated private key material, has sometimes been conflated with OpenPGP private key operations. However, it is more accurate to view TSKs as a specialized format for storage and transport, rather than as a data structure for use in a key store. For further details, see {ref}`key-store-design`. +Historically, the concept of TSKs, which combine all components of an OpenPGP certificate with the associated private key material, has sometimes been conflated with OpenPGP private key operations. However, it is more accurate to view TSKs as a specialized format for storage and transport, rather than as a data structure for use in a keystore. For further details, see {ref}`key-store-design`. (encrypted_secrets)= ## Protection of private key material in OpenPGP @@ -114,7 +114,7 @@ Hardware security devices, such as OpenPGP cards, are designed to prevent the us OpenPGP cards adhere to an open specification detailed in the [Functional Specification of the OpenPGP application on ISO Smart Card Operating Systems, Version 3.4.1](https://gnupg.org/ftp/specs/OpenPGP-smart-card-application-3.4.1.pdf). This specification has been implemented by multiple vendors across various devices, with several Free Software versions available, some of which are compatible with open hardware designs. -Effectively, the OpenPGP card specification outlines one model for a private key store subsystem. OpenPGP cards do not store a full OpenPGP certificate. Instead, they have three distinct "key slots" designated for *signing*, *decryption*, and *authentication*. Each key slot stores the data of one component key[^missing-ecdh], including its cryptographic private key material. Additionally, OpenPGP cards explicitly store the fingerprint of each component key within the corresponding key slot. +Effectively, the OpenPGP card specification outlines one model for a private keystore subsystem. OpenPGP cards do not store a full OpenPGP certificate. Instead, they have three distinct "key slots" designated for *signing*, *decryption*, and *authentication*. Each key slot stores the data of one component key[^missing-ecdh], including its cryptographic private key material. Additionally, OpenPGP cards explicitly store the fingerprint of each component key within the corresponding key slot. [^missing-ecdh]: In the case of ECDH keys, the KDF parameters (hash function ID and a symmetric encryption algorithm ID) are not stored on the OpenPGP card. This is considered a flaw in the OpenPGP card specification. These missing parameters can be handled in two ways by OpenPGP software on the host computer: either by consulting a copy of the component key (e.g., by inspecting a copy of the certificate) or by deducing the missing KDF parameters from the stored OpenPGP fingerprint on the card. @@ -122,9 +122,9 @@ Notably, the practice of explicitly storing fingerprints on OpenPGP cards contra ## Private key operations -Although OpenPGP encompasses a broad range of cryptographic mechanisms, the set of operations performed within the core of a private key store are simple and very limited. +Although OpenPGP encompasses a broad range of cryptographic mechanisms, the set of operations performed within the core of a private keystore are simple and very limited. -Specifically, an OpenPGP private key store implements two primitives: +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. @@ -132,9 +132,9 @@ Specifically, an OpenPGP private key store implements two primitives: 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. (key-store-design)= -## Private key stores +## Private keystores -This section examines the diverse architectures and operational mechanics of private key stores in OpenPGP. It focuses on the various design choices, their functional implications, and how they contribute to the secure management of private key material. +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 @@ -144,12 +144,12 @@ The design of private key subsystems within the OpenPGP framework varies, offeri 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 key store operations require component keys, they do not require access to the entire OpenPGP certificate. +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 key store might contain a TSK with outdated certificate metadata, marking the certificate as expired, while the updated version in the local public key store could indicate an extended expiration date. +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. ``` @@ -158,9 +158,9 @@ This problem was notably present in GnuPG 1.x, which held separate TSK copies in 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 key store operations, do not involve the private key material. +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 key store based on hardware cryptographic devices like [OpenPGP card](card-priv), its design will consist of two layers: +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. @@ -173,17 +173,15 @@ When implementing a key store based on hardware cryptographic devices like [Open ### Addressing individual keys -An independent design question is how key material is addressed, by users of the keystore. +A critical aspect of keystore design involves determining how users address individual key materials. -The fingerprint of the individual component keys is one obvious option. - -Depending on what backs the keystore, fingerprints are readily available, such as with software private keys, or OpenPGP card devices. In other cases, the key store needs to keep track of fingerprints by itself, e.g., when based on generic cryptographic hardware such as TPM. +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 directly accessible. Key stores relying on generic cryptographic hardware, like TPMs, need to implement their own mechanisms for tracking and managing the fingerprints of each key. ### Assorted other duties -Additionally, a key store may want to keep track of devices that contain particular component keys. It may need to deal with secrets, such as passphrases of software keys, or PINs of OpenPGP card devices. It may need to notify the user that some interaction is required. For example, some OpenPGP card devices can require touch confirmation to authorize each cryptographic operation. +Additionally, a keystore may want to keep track of devices that contain particular component keys. It may need to deal with secrets, such as passphrases of software keys, or PINs of OpenPGP card devices. It may need to notify the user that some interaction is required. For example, some OpenPGP card devices can require touch confirmation to authorize each cryptographic operation. -### Visualizing key store operations +### Visualizing keystore operations #### Signing @@ -196,7 +194,7 @@ write ```{admonition} VISUAL :class: warning -show examples for the operations in a private key store. +show examples for the operations in a private keystore. - reuse the visual elements of the lowest level in the ch6 "how signatures are made" diagram (ch 6): "making a cryptographic signature from a hash digest" ``` @@ -212,7 +210,7 @@ write ```{admonition} VISUAL :class: warning -show examples for the operations in a private key store. +show examples for the operations in a private keystore. - once we have a visual for the low level asymmetric decryption operation (in ch11), mirror it here ``` From 78b1de81ec4f59357ff2bb28c0a3695b0a6ab336 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Thu, 30 Nov 2023 17:53:53 +0100 Subject: [PATCH 11/26] edit "Additional keystore duties" section --- book/source/05-private.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/book/source/05-private.md b/book/source/05-private.md index d2301a3..ed30d76 100644 --- a/book/source/05-private.md +++ b/book/source/05-private.md @@ -175,11 +175,17 @@ When implementing a keystore based on hardware cryptographic devices like [OpenP A critical aspect of keystore design involves determining how users address individual key materials. -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 directly accessible. Key stores relying on generic cryptographic hardware, like TPMs, need to implement their own mechanisms for tracking and managing the fingerprints of each key. +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. -### Assorted other duties +### Additional keystore duties -Additionally, a keystore may want to keep track of devices that contain particular component keys. It may need to deal with secrets, such as passphrases of software keys, or PINs of OpenPGP card devices. It may need to notify the user that some interaction is required. For example, some OpenPGP card devices can require touch confirmation to authorize each cryptographic operation. +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. ### Visualizing keystore operations From 6b574e736cac2f5a7a22c1817ffbbe3d94bd358c Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Thu, 30 Nov 2023 18:19:33 +0100 Subject: [PATCH 12/26] create summary of KO attacks, KOpenPGP site --- book/source/05-private.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/book/source/05-private.md b/book/source/05-private.md index ed30d76..c10df3b 100644 --- a/book/source/05-private.md +++ b/book/source/05-private.md @@ -231,6 +231,10 @@ show examples for the operations in a private keystore. write ``` -### The KOpenPGP attack +### Understanding key overwriting (KO) attacks -See [https://www.kopenpgp.com/](https://www.kopenpgp.com/) +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 a key is used. The core issue lies in OpenPGP's handling of Secret-Key packets, where corruption of the public, non-encrypted fields of these packets can cause the correct private key material to be used with corrupted public key parameters. This mismatch can result in private key leakage. + +Understanding KO attacks is crucial due to their potential to compromise the integrity and confidentiality of encrypted communications. KO attacks highlight the necessity for robust key validation procedures and the dangers of storing keys in insecure environments. As OpenPGP application developers, you should be aware of these risks to ensure the secure management of keys and to implement appropriate countermeasures. + +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. \ No newline at end of file From fc8d0e16927477788f356426d5462156548c6a46 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Thu, 30 Nov 2023 18:54:58 +0100 Subject: [PATCH 13/26] change headers --- book/source/05-private.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/book/source/05-private.md b/book/source/05-private.md index c10df3b..d345425 100644 --- a/book/source/05-private.md +++ b/book/source/05-private.md @@ -4,13 +4,15 @@ SPDX-License-Identifier: CC-BY-SA-4.0 --> (private_key_chapter)= -# Private key material in OpenPGP +# Managing private key material in OpenPGP + +## Overview of private keys This chapter discusses the handling of private key material within OpenPGP. Private key material is associated with component keys, which are integral parts of [OpenPGP certificates](certificates_chapter). For a discussion of packet structure internals, see the chapter {ref}`zoom_private`. -## Terminology: "certificates" and "private keys" +## "Certificates" and "private keys" explained Recall that in this document, the term *OpenPGP certificate* refers to what are commonly known as "OpenPGP public keys." OpenPGP certificates are the combination of component public keys, identity components, binding self-signatures, and third-party certifications, as discussed in the previous chapter ({ref}`certificates_chapter`). From 58f14b495da8876f8b8f0525a686b4af8e571abc Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Thu, 30 Nov 2023 18:55:39 +0100 Subject: [PATCH 14/26] rewrite exception statement re: TSKs --- book/source/05-private.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/05-private.md b/book/source/05-private.md index d345425..b928177 100644 --- a/book/source/05-private.md +++ b/book/source/05-private.md @@ -30,7 +30,7 @@ An OpenPGP certificate, with the associated private key material handled in a se [^pkcs11]: The distinction between certificates (which combine public key material and identity information) and private key material is similarly made in the data model of [PKCS #11](https://en.wikipedia.org/wiki/PKCS_11) cryptographic systems. -However, there is one exception. Cryptographic private key material is sometimes embedded within an OpenPGP framing format that also contains the certificate: transferable secret keys (TSK). +In certain cases, an exception arises where the cryptographic private key material is integrated into the same OpenPGP framing format as the certificate. This is specifically done in the context of transferable secret keys (TSKs). ## Transferable secret key format From 1dc1a8147407bb29b915fdae9a8e0fa679eff902 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Thu, 30 Nov 2023 19:06:46 +0100 Subject: [PATCH 15/26] improve headers --- book/source/05-private.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/book/source/05-private.md b/book/source/05-private.md index b928177..305255b 100644 --- a/book/source/05-private.md +++ b/book/source/05-private.md @@ -56,13 +56,13 @@ Transferable secret keys are sometimes colloquially referred to as "OpenPGP priv Historically, the concept of TSKs, which combine all components of an OpenPGP certificate with the associated private key material, has sometimes been conflated with OpenPGP private key operations. However, it is more accurate to view TSKs as a specialized format for storage and transport, rather than as a data structure for use in a keystore. For further details, see {ref}`key-store-design`. (encrypted_secrets)= -## Protection of private key material in OpenPGP +## Protecting keys with passphrases In the OpenPGP format, private key material can be optionally protected with a [passphrase](https://en.wikipedia.org/wiki/Passphrase). This method proves effective in scenarios where an unauthorized party obtains the OpenPGP key data but does not know the passphrase. Such a safeguard renders the key unusable to the attacker, effectively protecting it against unauthorized access or use. -### Transforming a passphrase into a symmetric key +### Transforming passphrases into symmetric keys 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. @@ -88,7 +88,7 @@ A third mechanism is conditionally allowed for key generation. Decryption of pri The RFC uses the terms "String-to-Key (S2K) specifier" or "String-to-Key (S2K) specifier type" for mechanisms used to *generate* a symmetric key from a passphrase. -### Using the symmetric key for encryption +### Using symmetric keys for encryption The generation of a symmetric key from a passphrase leads to its subsequent use in encrypting or decrypting OpenPGP private key material. @@ -96,7 +96,7 @@ The RFC uses the term "String-to-Key Usage (S2K usage)" for the mechanism used t 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). -### Passphrase-protection acts per-component key +### Component-based passphrase protection The OpenPGP mechanism for protecting private key material applies individually to each component key: From e4733eeb6c532c373d3cbcb6ecb4207ebde0033e Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Thu, 30 Nov 2023 22:44:37 +0100 Subject: [PATCH 16/26] "elements" is the term we've introduced to clearly encompass the combination of "components + assorted signatures" --- book/source/05-private.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/05-private.md b/book/source/05-private.md index 305255b..f4a97b7 100644 --- a/book/source/05-private.md +++ b/book/source/05-private.md @@ -53,7 +53,7 @@ The TSK format is particularly useful for backups of OpenPGP key material or tra Transferable secret keys are sometimes colloquially referred to as "OpenPGP private keys." ``` -Historically, the concept of TSKs, which combine all components of an OpenPGP certificate with the associated private key material, has sometimes been conflated with OpenPGP private key operations. However, it is more accurate to view TSKs as a specialized format for storage and transport, rather than as a data structure for use in a keystore. For further details, see {ref}`key-store-design`. +Historically, the concept of TSKs, which combine all elements of an OpenPGP certificate with the associated private key material, has sometimes been conflated with OpenPGP private key operations. However, it is more accurate to view TSKs as a specialized format for storage and transport, rather than as a data structure for use in a keystore. For further details, see {ref}`key-store-design`. (encrypted_secrets)= ## Protecting keys with passphrases From 552e32f9f0c2abb8bc0c91da39960e75147a3945 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Thu, 30 Nov 2023 23:27:00 +0100 Subject: [PATCH 17/26] Software keys are very commonly used, so claiming "typically" a hardware device is used is saying too much. However, if a hardware device is used, the delineation of what the hardware device does and doesn't do heavily impacts the architecture. --- book/source/05-private.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/05-private.md b/book/source/05-private.md index f4a97b7..5efe62e 100644 --- a/book/source/05-private.md +++ b/book/source/05-private.md @@ -168,7 +168,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, typically 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.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). ``` From 8b5727ff9c0330cbb8ba9a57c14a78b2110e018b Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Thu, 30 Nov 2023 23:29:39 +0100 Subject: [PATCH 18/26] The plural "key materials" feels extremely off to me. Maybe that's just me? Either way, I think this edit has no downsides. --- book/source/05-private.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/05-private.md b/book/source/05-private.md index 5efe62e..fb2950d 100644 --- a/book/source/05-private.md +++ b/book/source/05-private.md @@ -175,7 +175,7 @@ When implementing a keystore based on hardware cryptographic devices like [OpenP ### Addressing individual keys -A critical aspect of keystore design involves determining how users address individual key materials. +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. From 8fb7ec2a254c276d7de60c4765d89179806ae56d Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Fri, 1 Dec 2023 19:47:16 +0100 Subject: [PATCH 19/26] ch5: move keystore text to advanced section --- book/source/05-private.md | 118 +++++++++++++++++++------------------- 1 file changed, 58 insertions(+), 60 deletions(-) diff --git a/book/source/05-private.md b/book/source/05-private.md index fb2950d..8f4cca2 100644 --- a/book/source/05-private.md +++ b/book/source/05-private.md @@ -133,65 +133,7 @@ Specifically, an OpenPGP private keystore implements two primitives: 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. -(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. - -### Visualizing keystore operations - -#### Signing +### Visualizing a signing operation ```{admonition} TODO :class: warning @@ -207,7 +149,7 @@ show examples for the operations in a private keystore. - reuse the visual elements of the lowest level in the ch6 "how signatures are made" diagram (ch 6): "making a cryptographic signature from a hash digest" ``` -#### Decryption +### Visualizing a decryption operation ```{admonition} TODO :class: warning @@ -225,6 +167,62 @@ show examples for the operations in a private keystore. ## 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. + ### TSKs: Best practices S2K + S2K migration? ```{admonition} TODO From 5be84794020bc2409821e92a029a11da7be57cb2 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Sat, 2 Dec 2023 18:03:09 +0000 Subject: [PATCH 20/26] restore "terminology" per discussion with Heiko --- book/source/05-private.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/05-private.md b/book/source/05-private.md index 8f4cca2..dc532cc 100644 --- a/book/source/05-private.md +++ b/book/source/05-private.md @@ -12,7 +12,7 @@ This chapter discusses the handling of private key material within OpenPGP. Private key material is associated with component keys, which are integral parts of [OpenPGP certificates](certificates_chapter). For a discussion of packet structure internals, see the chapter {ref}`zoom_private`. -## "Certificates" and "private keys" explained +## Terminology: "certificates" and "private keys" Recall that in this document, the term *OpenPGP certificate* refers to what are commonly known as "OpenPGP public keys." OpenPGP certificates are the combination of component public keys, identity components, binding self-signatures, and third-party certifications, as discussed in the previous chapter ({ref}`certificates_chapter`). From edbea315ab250b75aee75305701c672d79dde779 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Sat, 2 Dec 2023 18:09:23 +0000 Subject: [PATCH 21/26] clarify appropriate use for TSKs per Heiko discussion --- book/source/05-private.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/05-private.md b/book/source/05-private.md index dc532cc..5019d57 100644 --- a/book/source/05-private.md +++ b/book/source/05-private.md @@ -53,7 +53,7 @@ The TSK format is particularly useful for backups of OpenPGP key material or tra Transferable secret keys are sometimes colloquially referred to as "OpenPGP private keys." ``` -Historically, the concept of TSKs, which combine all elements of an OpenPGP certificate with the associated private key material, has sometimes been conflated with OpenPGP private key operations. However, it is more accurate to view TSKs as a specialized format for storage and transport, rather than as a data structure for use in a keystore. For further details, see {ref}`key-store-design`. +Historically, the concept of TSKs, which combine all elements of an OpenPGP certificate with the associated private key material, has sometimes been conflated with OpenPGP private key operations. However, TSKs are primarily a format for storage and transport; it is generally considered inappropriate as a data structure for use in a private keystore. For further details, see {ref}`key-store-design`. (encrypted_secrets)= ## Protecting keys with passphrases From 332078392068e5ddc42c815500c3930661cb68a0 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Sat, 2 Dec 2023 18:20:53 +0000 Subject: [PATCH 22/26] integrate @vanitasvitae comments --- book/source/05-private.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/book/source/05-private.md b/book/source/05-private.md index 5019d57..433d4fa 100644 --- a/book/source/05-private.md +++ b/book/source/05-private.md @@ -235,6 +235,10 @@ write 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 a key is used. The core issue lies in OpenPGP's handling of Secret-Key packets, where corruption of the public, non-encrypted fields of these packets can cause the correct private key material to be used with corrupted public key 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 material. The attack involves providing the user with a corrupted version of their own encrypted (passphrase-protected) key material, thereby compromising the key's integrity. + Understanding KO attacks is crucial due to their potential to compromise the integrity and confidentiality of encrypted communications. KO attacks highlight the necessity for robust key validation procedures and the dangers of storing keys in insecure environments. As OpenPGP application developers, you should be aware of these risks to ensure the secure management of keys and to implement appropriate countermeasures. +It's noteworthy that OpenPGP version 6 keys are not vulnerable to KO attacks when using S2K usage mode 253 (Argon2 + AEAD). This mode ensures the integrity of the public key by incorporating it into the encryption routine as additional data for verification. + 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. \ No newline at end of file From af44cc65caf87193abb5bea49aa0f61924e69fcb Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 2 Dec 2023 19:22:38 +0100 Subject: [PATCH 23/26] clarify KO attack details and mitigation --- book/source/05-private.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/book/source/05-private.md b/book/source/05-private.md index 433d4fa..210eb37 100644 --- a/book/source/05-private.md +++ b/book/source/05-private.md @@ -233,12 +233,20 @@ write ### Understanding key overwriting (KO) attacks -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 a key is used. The core issue lies in OpenPGP's handling of Secret-Key packets, where corruption of the public, non-encrypted fields of these packets can cause the correct private key material to be used with corrupted public key parameters. This mismatch can result in private key leakage. +#### What they are -Importantly, KO attacks are particularly relevant when an attacker is responsible for storing a user's encrypted private key material. The attack involves providing the user with a corrupted version of their own encrypted (passphrase-protected) key material, thereby compromising the key's integrity. +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. -Understanding KO attacks is crucial due to their potential to compromise the integrity and confidentiality of encrypted communications. KO attacks highlight the necessity for robust key validation procedures and the dangers of storing keys in insecure environments. As OpenPGP application developers, you should be aware of these risks to ensure the secure management of keys and to implement appropriate countermeasures. +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. -It's noteworthy that OpenPGP version 6 keys are not vulnerable to KO attacks when using S2K usage mode 253 (Argon2 + AEAD). This mode ensures the integrity of the public key by incorporating it into the encryption routine as additional data for verification. +#### 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}`s2k_best_practice`). + +#### 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. \ No newline at end of file From 32566e4bb0ec590477031897c39b25caca1034e1 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 2 Dec 2023 21:13:25 +0100 Subject: [PATCH 24/26] Move "best practices" section down, write a minimal text --- book/source/05-private.md | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/book/source/05-private.md b/book/source/05-private.md index 210eb37..b862157 100644 --- a/book/source/05-private.md +++ b/book/source/05-private.md @@ -223,14 +223,6 @@ In addition to key management, a keystore often involves various supplementary f - **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. -### TSKs: Best practices S2K + S2K migration? - -```{admonition} TODO -:class: warning - -write -``` - ### Understanding key overwriting (KO) attacks #### What they are @@ -249,4 +241,19 @@ Note that while S2K usage mode 253 (AEAD) has been introduced in the OpenPGP ver #### 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. \ No newline at end of file +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. + +(s2k_best_practice)= +### TSKs: Best practices S2K + S2K migration? + +The RFC [recommends](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-avoiding-ciphertext-malleab) that: "Users should migrate to AEAD with all due speed." + +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 (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 all private keys. + +```{admonition} TODO +:class: warning + +Can we make more specific recommendations, e.g. on how to do that? +``` From 11ba97a3f3ab303c106675529d2e043c33d5be9f Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Fri, 8 Dec 2023 18:42:29 +0100 Subject: [PATCH 25/26] move visualization sections out into #183 for now --- book/source/05-private.md | 32 -------------------------------- 1 file changed, 32 deletions(-) diff --git a/book/source/05-private.md b/book/source/05-private.md index b862157..217d28e 100644 --- a/book/source/05-private.md +++ b/book/source/05-private.md @@ -133,38 +133,6 @@ Specifically, an OpenPGP private keystore implements two primitives: 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. -### Visualizing a signing operation - -```{admonition} TODO -:class: warning - -write -``` - -```{admonition} VISUAL -:class: warning - -show examples for the operations in a private keystore. - -- reuse the visual elements of the lowest level in the ch6 "how signatures are made" diagram (ch 6): "making a cryptographic signature from a hash digest" -``` - -### Visualizing a decryption operation - -```{admonition} TODO -:class: warning - -write -``` - -```{admonition} VISUAL -:class: warning - -show examples for the operations in a private keystore. - -- once we have a visual for the low level asymmetric decryption operation (in ch11), mirror it here -``` - ## Advanced topics (key-store-design)= From bc35e695e9706a945a7ea9ad745c1ca8c5112e60 Mon Sep 17 00:00:00 2001 From: Paul Schaub Date: Fri, 8 Dec 2023 21:09:06 +0100 Subject: [PATCH 26/26] Remove S2K migration section, as it has moved to ch15 in paul-ch15 --- book/source/05-private.md | 17 +---------------- 1 file changed, 1 insertion(+), 16 deletions(-) diff --git a/book/source/05-private.md b/book/source/05-private.md index 217d28e..daa1278 100644 --- a/book/source/05-private.md +++ b/book/source/05-private.md @@ -205,23 +205,8 @@ Understanding KO attacks is crucial due to their potential to compromise the int 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}`s2k_best_practice`). +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. - -(s2k_best_practice)= -### TSKs: Best practices S2K + S2K migration? - -The RFC [recommends](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-avoiding-ciphertext-malleab) that: "Users should migrate to AEAD with all due speed." - -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 (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 all private keys. - -```{admonition} TODO -:class: warning - -Can we make more specific recommendations, e.g. on how to do that? -```