diff --git a/book/source/05-private.md b/book/source/05-private.md index bf52b20..85cf6e9 100644 --- a/book/source/05-private.md +++ b/book/source/05-private.md @@ -4,7 +4,9 @@ SPDX-License-Identifier: CC-BY-SA-4.0 --> (private_key_chapter)= -# OpenPGP private keys +# Private key material in OpenPGP + +This chapter discusses the handling of private key material, in 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` Historically, terminology around OpenPGP certificates and keys has often been used inconsistently. The pair of terms "OpenPGP public key" and "OpenPGP private/secret keys" were commonly used (while the shorthand "OpenPGP key" can refer to both, depending on context). @@ -14,7 +16,7 @@ In this document, we use the term *OpenPGP certificate* to refer "OpenPGP public This chapter is about the counterpart to the public material in certificates: Here, we discuss the handling of *private key material* in OpenPGP. -In this text, we treat the private key material as logically separate from the OpenPGP certificate. Operations that use the private key material are typically handled by a separate subsystem. We think it is useful to think about OpenPGP certificates on one hand, and the associated private key material, on the other, as two related elements, which are usually handled separately[^pkcs11]: +In this text, we treat the private key material as logically separate from the OpenPGP certificate. Operations that use the private key material are typically handled by a separate subsystem. It is useful to think about OpenPGP certificates on one hand, and the associated private key material, on the other, as two related elements, which are usually handled separately[^pkcs11]: ```{admonition} VISUAL :class: warning @@ -24,11 +26,17 @@ In this text, we treat the private key material as logically separate from the O [^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. -However, there is one exception. "OpenPGP private keys" are sometimes handled in a format that combines the certificate and the private key data: [*Transferable secret keys (TSK)*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-11.html#name-transferable-secret-keys). +However, there is one exception. Raw cryptographic private key material is sometimes embedded in an OpenPGP framing format that additionally contains the certificate: [*Transferable secret keys (TSK)*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-11.html#name-transferable-secret-keys). + +```{admonition} Terminology +:class: note + +Transferable secret keys are sometimes colloquially referred to as "OpenPGP private keys". +``` ## Transferable secret keys -Sometimes users handle "OpenPGP private keys" in the form of *transferable secret keys* (TSK). That is: a serialized format that combines the OpenPGP certificate data with the connected private key material, stored in a single file. +Sometimes users handle OpenPGP certificates combined with private key material in the form of *transferable secret keys* (TSK). Transferable secret keys are a serialized format that combines the OpenPGP certificate data with the connected private key material, stored in a single file. ```{admonition} VISUAL :class: warning @@ -40,6 +48,8 @@ The TSK format can be useful for backups of OpenPGP key material, or to move a k [^gpg-tsk]: For example, with GnuPG, an OpenPGP key can be exported in (armored) TSK format like this: `gpg --export-secret-key --armor ` +See the chapter {ref}`zoom_private` for insights into the packet structure of a TSK. + (encrypted_secrets)= ## Protecting secret key material with a passphrase (using S2K) @@ -57,7 +67,11 @@ OpenPGP defines a mechanism called [string-to-key (S2K)](https://www.ietf.org/ar - passphrase --(S2k mechanism)--> symmetric encryption key ``` -Encryption of private key material can be configured independently for each component key. Component keys that are associated with the same certificate can use different mechanisms for passphrase protection, and/or different passphrases. +The private key material for individual component keys of one certificate can be encrypted with different mechanisms, and/or using different passphrases. + +However, this is not customarily done. Usually, when creating a certificate, the user's software will use the same encryption mechanism and passphrase for all component keys (to limit complexity). + +However, 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. ### S2K mechanisms for symmetric key generation @@ -73,14 +87,39 @@ Different mechanisms are specified [for the encryption of the secret key data](h ## Private key operations -The core of private key operations doesn't require access to the whole certificate. A private key subsystem only needs to handle the cryptographic key material. +The core of private key operations doesn't require access to the whole certificate. + +Designs of private key subsystems in the OpenPGP space differ: + +- 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). +- In other designs, the OpenPGP private key subsystem requires the additional metadata that is stored in the component key (the key creation time, for all keys, and in the case of keys that use ECDH algorithms: the KDF parameters). + +Either way: at most, a private key subsystem should need access to individual component keys and the associated private key material. + +```{admonition} TODO +:class: warning + +Keeping a copy of the full certificate information in the private key subsystem can cause "split brain" problems. E.g.: expiration times could then differ between different subsystems, when they keep different copies of the certificate information. + +(Thunderbird users currently suffer from such issues, I think) +``` ### OpenPGP card for private keys -[OpenPGP card](https://en.wikipedia.org/wiki/OpenPGP_card) devices are a type of hardware security device. They are one popular way to handle OpenPGP private key material. These devices do not store the full OpenPGP certificate. +[OpenPGP card](https://en.wikipedia.org/wiki/OpenPGP_card) devices are a type of hardware security device. They are one popular way to handle OpenPGP private key material. + +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 an OpenPGP private key subsystem: + +OpenPGP card devices do not store the full OpenPGP certificate. Instead, they have three "key slots": one each for signing, decryption and authentication. Each key slots stores the component key data and the associated cryptographic private key material[^missing-ecdh]. In addition, for each key slot, the OpenPGP fingerprint for the contained component key is explicitly stored on the card (note that storing the fingerprint on the card is different from how OpenPGP key data is usually handled: normally, fingerprints are not explicitly stored, but calculated on the fly from the component key data). + +[^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. ## Advanced topics ### TSKs: Best practices S2K + S2K migration? ### The KOpenPGP attack + +See [https://www.kopenpgp.com/](https://www.kopenpgp.com/) diff --git a/book/source/18-zoom_private_keys.md b/book/source/18-zoom_private_keys.md index 095850d..2c5bbcb 100644 --- a/book/source/18-zoom_private_keys.md +++ b/book/source/18-zoom_private_keys.md @@ -3,6 +3,7 @@ SPDX-FileCopyrightText: 2023 The "Notes on OpenPGP" project SPDX-License-Identifier: CC-BY-SA-4.0 --> +(zoom_private)= # Zooming in: Packet structure of private key material ## A look at Alice's (unencrypted) private key packets