From 8fb7ec2a254c276d7de60c4765d89179806ae56d Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Fri, 1 Dec 2023 19:47:16 +0100 Subject: [PATCH] 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