From 9b925ffd9c3b5566efa9d32a49e5b5589144648b Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Fri, 17 Nov 2023 00:14:09 +0100 Subject: [PATCH 01/81] fix list dash --- book/source/07-signing_data.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/07-signing_data.md b/book/source/07-signing_data.md index 5163be4..0b9952c 100644 --- a/book/source/07-signing_data.md +++ b/book/source/07-signing_data.md @@ -131,7 +131,7 @@ These features are particularly beneficial in scenarios where signed messages ar The cleartext signature framework includes specific text normalization procedures to ensure the integrity and clarity of the message: -_ **Escaping dashes**: The framework implements a method of [dash-escaped text](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-dash-escaped-text) within the message. Dash-escaping ensures that the parser correctly distinguishes between the armor headers, which are part of the signature's structure, and any lines in the message that happen to start with a dash. +- **Escaping dashes**: The framework implements a method of [dash-escaped text](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-dash-escaped-text) within the message. Dash-escaping ensures that the parser correctly distinguishes between the armor headers, which are part of the signature's structure, and any lines in the message that happen to start with a dash. - **Normalization of line endings**: Consistent with the approach for any other [text signature](data_signature_types), a cleartext signature is calculated on the text with normalized line endings (``). This ensures that the signature remains valid regardless of the text format of the receiving implementation. From c43b4449806de4459f3855ee5f793ae87e6fcc91 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Fri, 17 Nov 2023 13:34:18 +0100 Subject: [PATCH 02/81] RNP is independent of Thunderbird --- book/source/02-highlevel.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/02-highlevel.md b/book/source/02-highlevel.md index 3dbbb26..19bb393 100644 --- a/book/source/02-highlevel.md +++ b/book/source/02-highlevel.md @@ -65,7 +65,7 @@ Some implementations explored other non-standardized extensions. Notably, algori Today, multiple implementations of OpenPGP play important roles: - Proton Mail, which provides email encryption services for a large number of users, uses and maintains [OpenPGP.js](https://openpgpjs.org/) as well as [GopenPGP](https://gopenpgp.org/), an OpenPGP wrapper library written in golang. -- The Mozilla Thunderbird email software uses [RNP](https://www.rnpgp.org/), its C++ implementation of OpenPGP. +- The Mozilla Thunderbird email software uses [RNP](https://www.rnpgp.org/), a C++ implementation of OpenPGP. - The RPM Package Manager software includes an OpenPGP backend based on [Sequoia PGP](https://sequoia-pgp.org/), a modern OpenPGP implementation written in Rust. The Fedora operating system, Fedora Linux 38, [uses Sequoia PGP in rpm](https://sequoia-pgp.org/blog/2023/04/27/rpm-sequoia/). (interop_section)= From 3d02f4ae8842e99f4b24eefeb1b934c06ed9e220 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Fri, 17 Nov 2023 13:34:18 +0100 Subject: [PATCH 03/81] Fix swapped description (From #112) --- book/source/03-cryptography.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/03-cryptography.md b/book/source/03-cryptography.md index ebfd687..bb7ad6c 100644 --- a/book/source/03-cryptography.md +++ b/book/source/03-cryptography.md @@ -82,7 +82,7 @@ By addressing the malleability problem, AEAD also counters a variation of the EF [Public-key cryptography](https://en.wikipedia.org/wiki/Public-key_cryptography) uses asymmetric pairs of related keys. Each pair consists of a public key and a private key. These systems support encryption, decryption, and digital signature operations. -Unlike symmetric cryptography, participants are not required to pre-arrange a shared secret. In public-key cryptography, the public key material is shared openly for certain cryptographic operations, such as encryption and signature creation, while the private key, kept confidential, is used for operations like decryption and signature verification. +Unlike symmetric cryptography, participants are not required to pre-arrange a shared secret. In public-key cryptography, the public key material is shared openly for certain cryptographic operations, such as encryption and signature verification, while the private key, kept confidential, is used for operations like decryption and signature creation. (asymmetric_key_pair)= ### Asymmetric cryptographic key pairs From 36399d330b249dcbeaba5db869dc1b6c5c3578c8 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Fri, 17 Nov 2023 14:29:07 +0100 Subject: [PATCH 04/81] ch3 feedback from liw, fixes #112 --- book/source/03-cryptography.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/book/source/03-cryptography.md b/book/source/03-cryptography.md index bb7ad6c..06ec95a 100644 --- a/book/source/03-cryptography.md +++ b/book/source/03-cryptography.md @@ -8,11 +8,11 @@ SPDX-License-Identifier: CC-BY-SA-4.0 ## Cryptographic hash functions -[Cryptographic hash functions](https://en.wikipedia.org/wiki/Cryptographic_hash_function) take data strings of any length (like a text message or file) and output a fixed-size code, a "hash digest," which is often abbreviated as either "digest" or "hash." A hash digest acts like a unique identifier for the original data. +[Cryptographic hash functions](https://en.wikipedia.org/wiki/Cryptographic_hash_function) take data strings of any length (like a text message or file) and output a fixed-size code, a "hash digest," which is often abbreviated as either "digest" or "hash." Hash digests are also sometimes called a "(cryptographic) checksum." A hash digest acts like a unique identifier for the original data. Here are two important properties of cryptographic hash functions: -- ["Pre-image resistance"](https://en.wikipedia.org/wiki/Preimage_attack): Given a hash digest, it should be very difficult to determine the original data it represents. +- ["Pre-image resistance"](https://en.wikipedia.org/wiki/Preimage_attack): Given a hash digest, it should be very difficult to determine any data that matches this hash digest (including, but not limited to, the original data the hash represents). This property is related to acting as a [one-way function](https://en.wikipedia.org/wiki/One-way_function): a calculation that is easy to perform, but very hard to reverse. - ["Collision resistance"](https://en.wikipedia.org/wiki/Collision_resistance): It should be very difficult to find two distinct pieces of data that map to the same hash digest. ## Message authentication codes @@ -95,7 +95,7 @@ Throughout this document, we will frequently reference asymmetric cryptographic An asymmetric cryptographic key pair ``` -Each key pair comprises two parts: the public key and the private key. For ease of identification, we will depict the public key in green and the private key in red throughout this document. +Each key pair comprises two parts: the public key and the private key. For ease of identification, we will depict the public key in green and the private key in red throughout this document. Additionally, public keys are shown with a solid edge and pointing to the right, while private keys are shown with dotted edge and pointing to the left. It's important to note that in many scenarios, only the public key is exposed or used (we will expand on these situations in subsequent sections): From 8236e97002117256033e2b6ec5bb1a28f8becce9 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Fri, 17 Nov 2023 14:43:35 +0100 Subject: [PATCH 05/81] typo fix --- book/source/03-cryptography.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/03-cryptography.md b/book/source/03-cryptography.md index 06ec95a..c070e88 100644 --- a/book/source/03-cryptography.md +++ b/book/source/03-cryptography.md @@ -102,7 +102,7 @@ It's important to note that in many scenarios, only the public key is exposed or ```{figure} diag/public_key.png --- --- -The public parts of an asymmetric key pair +The public part of an asymmetric key pair ``` ### Usage and terminology in OpenPGP From d7bcc75249b7d74e5519a0bf196b20dda072f91b Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Fri, 17 Nov 2023 14:44:42 +0100 Subject: [PATCH 06/81] align link names and ordering with current chapter naming --- book/source/03-cryptography.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/03-cryptography.md b/book/source/03-cryptography.md index c070e88..a213c89 100644 --- a/book/source/03-cryptography.md +++ b/book/source/03-cryptography.md @@ -125,8 +125,8 @@ In OpenPGP, digital signatures have diverse applications, extending beyond mere Digital signatures in OpenPGP are used in two primary contexts: -- [Certification statements](component_signatures_chapter) - [Data signatures](signing_data) +- [Signatures on components](component_signatures_chapter) (hybrid_cryptosystems)= ## Hybrid cryptosystems From 4ddbeb9e5a7e56e7af4803490da1ee819a63b5e9 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Fri, 17 Nov 2023 14:47:55 +0100 Subject: [PATCH 07/81] use "signature packet" for disambiguation --- book/source/06-signatures.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/06-signatures.md b/book/source/06-signatures.md index bf7efb7..cbb0e92 100644 --- a/book/source/06-signatures.md +++ b/book/source/06-signatures.md @@ -26,7 +26,7 @@ In this document, "signature" will refer to OpenPGP signature packets. (signature_types)= ## Signature types in OpenPGP -The OpenPGP standard defines a set of [Signature types](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-signature-types), each identified by a numerical *signature type ID*. Signature types define the purpose of a signature and how it should be interpreted. +The OpenPGP standard defines a set of [Signature types](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-signature-types), each identified by a numerical *signature type ID*. Signature types define the purpose of a signature packet and how it should be interpreted. Signature types can be predominantly classified in two ways: From 0389d75da05929070dd1575489d70a64986819cb Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 14 Nov 2023 20:57:43 +0100 Subject: [PATCH 08/81] ch4: drop minor redundancy --- book/source/04-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 771f39b..8b03e4e 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -64,7 +64,7 @@ OpenPGP component keys logically consist of an [asymmetric cryptographic keypair An OpenPGP component key ``` -In OpenPGP, component keys containing private key material also include metadata specifying the password protection scheme. This is another facet of metadata, akin to the aforementioned creation timestamp and additional parameters for certain algorithms. However, this discussion focuses on OpenPGP certificates, in which the component keys contain only the public part of its cryptographic key data. For information on private keys in OpenPGP, see {numref}`private_key_chapter`. +Component keys containing private key material also include metadata specifying the password protection scheme. This is another facet of metadata, akin to the aforementioned creation timestamp and additional parameters for certain algorithms. However, this discussion focuses on OpenPGP certificates, in which the component keys contain only the public part of its cryptographic key data. For information on private keys in OpenPGP, see {numref}`private_key_chapter`. ### Fingerprint From 5cb7b94950821eecca56068fbb807b83f407514e Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 18 Nov 2023 17:14:53 +0100 Subject: [PATCH 09/81] moved to #119 --- book/source/04-certificates.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 8b03e4e..4f45591 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -155,10 +155,6 @@ OpenPGP certificates can contain multiple [User IDs](https://www.ietf.org/archiv OpenPGP certificates can contain any number of User IDs ``` -```{admonition} Warning -This image could be visually improved! The new image should have an alt tag -``` - A typical User ID identity is a UTF-8-encoded string composed of a name and an email address. By convention, User IDs align with the format described in [RFC2822](https://www.rfc-editor.org/rfc/rfc2822) as a *name-addr*. For further conventions on User IDs, refer to the document [draft-dkg-openpgp-userid-conventions-00](https://datatracker.ietf.org/doc/draft-dkg-openpgp-userid-conventions/), dated 25 August 2023. From 514bb02d3d23d6b366d9519ae87ba0219ba09dc3 Mon Sep 17 00:00:00 2001 From: David Runge Date: Mon, 20 Nov 2023 16:21:57 +0100 Subject: [PATCH 10/81] Configure sphinx to render numbering for figures in flat hierarchy Signed-off-by: David Runge --- book/source/conf.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/book/source/conf.py b/book/source/conf.py index db227e5..96f5eb4 100644 --- a/book/source/conf.py +++ b/book/source/conf.py @@ -46,3 +46,8 @@ html_theme_options = { # we want to circumvent obscure warnings about footnotes following a heading: # https://github.com/executablebooks/MyST-Parser/issues/352 myst_footnote_transition = False + +# number code-blocks, figures and tables, if they have a caption +numfig = True +# number figures in flat hierarchy +numfig_secnum_depth = 0 From 83a07f0001ac12fcab8b9923390ff64aafd312b5 Mon Sep 17 00:00:00 2001 From: David Runge Date: Mon, 20 Nov 2023 16:23:25 +0100 Subject: [PATCH 11/81] Add name and alt attributes for all figures Signed-off-by: David Runge --- book/source/03-cryptography.md | 19 +++++++++++-------- book/source/04-certificates.md | 10 +++++++++- book/source/05-private.md | 6 ++++++ book/source/06-signatures.md | 10 ++++++++++ book/source/08-signing_components.md | 6 ++++++ book/source/17-zoom_certificates.md | 8 ++++++++ book/source/18-zoom_private_keys.md | 4 +++- 7 files changed, 53 insertions(+), 10 deletions(-) diff --git a/book/source/03-cryptography.md b/book/source/03-cryptography.md index bb7ad6c..560d24e 100644 --- a/book/source/03-cryptography.md +++ b/book/source/03-cryptography.md @@ -39,9 +39,10 @@ For detailed information on KDFs and their role in the OpenPGP protocol, see the Participants in symmetric-key operations need to exchange the shared secret over a secure channel. ```{figure} diag/symmetric_key.png ---- ---- -A symmetric cryptographic key (which acts as a shared secret) +:name: fig-symmetric-key +:alt: Depicts a box with a white background and the title "Symmetric key". In the box a single key symbol, rendered with full yellow line, is shown pointing to the right hand side. + +A symmetric cryptographic key (which acts as a shared secret) ``` ### Benefits and downsides @@ -90,8 +91,9 @@ Unlike symmetric cryptography, participants are not required to pre-arrange a sh Throughout this document, we will frequently reference asymmetric cryptographic key pairs: ```{figure} diag/asymmetric_keypair.png ---- ---- +:name: fig-asymmetric-keypair +:alt: Depicts a box with white background and the title "Asymmetric keypair". In the box two key symbols with text next to them are shown. The top key symbol is rendered using full green lines, points to the right hand side and has the accompanying text "Public key". The lower key symbol is rendered using dotted red lines, points to the left hand side and has the accompanying text "Private key". + An asymmetric cryptographic key pair ``` @@ -100,8 +102,9 @@ Each key pair comprises two parts: the public key and the private key. For ease It's important to note that in many scenarios, only the public key is exposed or used (we will expand on these situations in subsequent sections): ```{figure} diag/public_key.png ---- ---- +:name: fig-public-key +:alt: Depicts a box with white background and the title "Public part of an asymmetric keypair". In the box one key symbol with text next to it is shown. The key symbol is rendered using full green lines, points to the right hand side and has the accompanying text "Public key". + The public parts of an asymmetric key pair ``` @@ -141,4 +144,4 @@ Move this to the chapter that details it: Within OpenPGP's hybrid system, so-called "session keys" are central. They are generated uniquely for each session and are instrumental in both encrypting and decrypting the actual message content, using the efficiency of symmetric-key cryptography. Using asymmetric (public-key) cryptography, the session keys are also encrypted. This ensures that only the intended recipient, the holder of the corresponding private key, can decrypt and gain access to the session key. With the decrypted session key, they can then use the session key to decrypt the actual message. -``` \ No newline at end of file +``` diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 4f45591..254afc9 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -41,6 +41,8 @@ An OpenPGP certificate (or "OpenPGP key") is a collection of an arbitrary number This documentation collectively refers to component keys and identity components as "the components of a certificate." ```{figure} diag/OpenPGP_Certificate.png +:name: fig-openpgp-certificate +:alt: Depicts a box with white background and the title "OpenPGP certificate". In the box several other boxes and accompanying texts, representing component keys and User IDs, are shown. There are three component keys boxes with a green frame, each with a dotted lower-left section, that shows the text "key creation time" and the green public key symbol in the lower right area. All three have a title, a unique fingerprint below the box and a unique capability keyword, perpendicular to the box on the right side. The top-most component key box has a light-green background, with the title "Component Key (primary)" and capability keyword "certification". The second-to-top component key box has a white background, with the title "Component Key" and capability keyword "encryption". The lowest component key box has a white background, with the title "Component Key" and capability keyword "signing". There are two User ID boxes, each with a black frame, open to top left and lower right corner. Both boxes have a user icon on the top left side, the title "User ID" on the top right side and a User ID string at the bottom. The top box has "Alice Adams " and the lower box has "Alice" as User ID string. Typical components in an OpenPGP certificate ``` @@ -60,6 +62,8 @@ OpenPGP component keys logically consist of an [asymmetric cryptographic keypair [^ecdh-parameters]: For [ECDH](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-algorithm-specific-part-for-ecd) component keys, two additional algorithm parameters are integral to the component key's constitutive and immutable properties. Those parameters specify a hash function and a symmetric encryption algorithm. ```{figure} diag/Component_Key.svg +:name: fig-component-key +:alt: Depicts a box with white background and no title. In the box one other box is shown. The inner box has a green frame, with a dotted lower-left section, that shows the text "key creation time" and the green public key symbol, as well as the red-dotted private key symbol in the lower right area. In the top left of the inner box the text reads "Component Key". An OpenPGP component key ``` @@ -71,6 +75,8 @@ Component keys containing private key material also include metadata specifying Each OpenPGP component key possesses an *OpenPGP fingerprint*. This fingerprint is derived from the public key material, the creation timestamp, and, when relevant, the ECDH parameters. ```{figure} diag/Fingerprint.png +:name: fig-fingerprint +:alt: Depicts a box with white background and the title "Fingerprint of an OpenPGP component key". Inside, another box with a green frame, the title "Component Key", the text "key creation time" on the lower left and a the green public key symbol on the lower right is shown. Below the component key box a fingerprint in a box with a light-yellow background and a yellow dotted line is depicted. The word "Fingerprint" is shown left of the box with the fingerprint and both are connected with a yellow dotted line. Every OpenPGP component key is identifiable by a fingerprint. Although it's technically possible for different keys to share a fingerprint, cryptographic mechanisms make it exceedingly difficult, if not practically impossible with current technology, to find keys that share a fingerprint. ``` @@ -101,7 +107,7 @@ Modern OpenPGP certificates typically include several subkeys in addition to the While subkeys have the same structural attributes as the primary key, they fulfill different roles. Subkeys are cryptographically linked with the primary key, a relationship further discussed in {numref}`binding_subkeys`. ```{figure} diag/Subkeys.png -:name: Certificate with subkeys +:name: fig-subkeys :alt: Diagram depicting three component keys. The primary key is positioned at the top, designated for certification. Below it, connected by arrows, are two subkeys labeled as "for encryption" and "for signing," respectively. OpenPGP certificates can contain multiple subkeys. @@ -151,6 +157,8 @@ Identity components in an OpenPGP certificate are used by the certificate holder OpenPGP certificates can contain multiple [User IDs](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-user-id-packet-tag-13). Each User ID associates the certificate with an identity. ```{figure} diag/user_ids.png +:name: fig-user-ids +:alt: Depicts a diagram with white background and the title "User IDs". Inside, a public primary component key for certification and a User ID is shown. A green arrow points from component key to User ID and is annotated with a signature. OpenPGP certificates can contain any number of User IDs ``` diff --git a/book/source/05-private.md b/book/source/05-private.md index 49ac43c..87c7c11 100644 --- a/book/source/05-private.md +++ b/book/source/05-private.md @@ -20,6 +20,8 @@ In this text, we treat the private key material as logically separate from the O ```{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. An OpenPGP certificate, with the associated private key material handled by a key store subsystem. ``` @@ -39,6 +41,8 @@ Transferable secret keys are sometimes colloquially referred to as "OpenPGP priv 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. ```{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. OpenPGP certificate with integrated private key material, as a TSK ``` @@ -61,6 +65,8 @@ Using a passphrase can be useful when a third party can obtain a copy of the Ope OpenPGP defines a mechanism called [string-to-key (S2K)](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-11.html#name-string-to-key-s2k-specifier) that is 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). ```{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. Transforming a passphrase into a symmetric key ``` diff --git a/book/source/06-signatures.md b/book/source/06-signatures.md index cbb0e92..961547e 100644 --- a/book/source/06-signatures.md +++ b/book/source/06-signatures.md @@ -17,6 +17,8 @@ Within OpenPGP, the term *signature* can have two different meanings: - **OpenPGP signature packets**: Defined in the [OpenPGP standard](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-signature-packet-type-id-2), these packets combine a raw cryptographic signature along with a *type* designation and additional metadata. ```{figure} diag/meaning_of_signatures.png +:name: fig-meaning-of-signatures +:alt: Depicts a box on white background with the title "Meanings of signature in OpenPGP", "signature" in italics. The top half of the box shows a green seal symbol with the word "sig" in it on the left side. The symbol is connected to the text "Cryptographic signature" by a black dotted line. The bottom half of the box shows a diagram. On the left hand side a box with green dotted frame and white background provides the title "Signature type", while inside the box the text reads "Signature over Signature data, Signature metadata". The words "Signature metadata" serve as title for a yellow box at the lower half of the signature type box. The yellow box also contains a cryptographic signature symbol. Right of the signature type box, the text "OpenPGP signature packet" is shown, which is connected to the box by a green dotted line. Below the text a list is shown, which reads "signature type, signature over input data, additional metadata and cryptographic signature". The last item is connected to the cryptographic signature symbol in the yellow box by a black dotted line. Two meanings of the term "signature" in OpenPGP ``` @@ -39,6 +41,8 @@ Signatures on components are a complex topic, and we discuss them in depth in {r - the nature of the statement made by the signature, such as certifying an identity or binding component keys into a certificate ```{figure} mermaid/sig-types.png +:name: fig-signature-types +:alt: Depicts a diagram, describing different types of OpenPGP signatures. On the right hand side a long yellow box with the title "Signature Types and Targets" is shown, which contains signature type IDs and their names (in gray boxes) and further yellow boxes, grouping other types of signature type IDs. At the top the signature type ID "0x02 Standalone" is shown. Below, another yellow box groups the "Signature Packet"s "0x50 Third-Party Confirmation" and "0x40 Timestamp". Another box groups types of signatures, that apply to "Data" packets "0x00 Binary Data" and "0x01 Canonical Text". Below, a box groups types of signatures, that apply to "Primary Key + User ID/ Attr. Packet"s. The type IDs "0x10 Generic Certification", "0x11 Persona Certification", "0x12 Casual Certification" and "0x13 Positive Certification" are shown together in one gray box and "0x30 Certification Revocation" in another. Another yellow box groups types of signatures, that apply to "Primary Key" packets "0x1F Direct-Key Signature" and "0x20 Key Revocation". The last box groups types of signatures, that apply to "Primary + Subkey" packets. "0x18 Subkey Binding" and "0x19 Primary Key Binding" are shown together in one gray box, "0x28 Subkey Revocation" in another. On the left hand side of the diagram shows gray boxes identifying different types of signatures, with the most basic being "OpenPGP Signature" on the far left. With arrows it points to further signature types ("Signature on Data", "Signature on Component") and several signature type IDs ("0x02", "0x50" and "0x40"). The signature type "Signature on Data" points to "0x00" and "0x01". The signature type "Signature on Component" points to two more specific signature types, namely "Third-Party" and "Self-Signature". "Third-Party" points at the group of "0x10", "0x11", "0x12" and "0x13", as well as "0x30" and "0x1F". "Self-Signature" points at the group of "0x10", "0x11", "0x12" and "0x13", as well as "0x30", "0x1F", the group of "0x18" and "0x19" and finally "0x28". An overview of signature types in OpenPGP ``` @@ -56,6 +60,8 @@ As outlined above, an OpenPGP signature is a composite data structure, which com - **Raw cryptographic signature** ```{figure} diag/signature_packet.png +:name: fig-signature-packet +:alt: Depicts a diagram with the title "A signature packet". On the left hand side a box with green dotted frame and white background provides the title "Signature type", while inside the box the text reads "Signature over Signature data, Signature metadata". The words "Signature metadata" serve as title for a yellow box at the lower half of the signature type box. The yellow box also contains a cryptographic signature symbol. Right of the signature type box, the text "OpenPGP signature packet" is shown, which is connected to the box by a green dotted line. Below the text a list is shown, which reads "signature type, signature over input data, additional metadata and raw cryptographic signature". The last item is connected to the cryptographic signature symbol in the yellow box by a black dotted line. Structure of an OpenPGP signature packet ``` @@ -79,6 +85,8 @@ The signature packet consists of two parts: - The signature is then calculated for this hash digest. ```{figure} diag/Signature_Creation.png +:name: fig-signature-creation +:alt: Depicts a complex diagram with white background and the title "Signature creation". On the top left side a box with black frame and white background reads "Input Data packets, One or more packets". Below it the symbol of a signature packet is shown (however, instead of the green signature symbol, only a circle with white background and dotted frame is shown). Both are connected (via green dotted arrows) to a green, right pointing arrow symbol with green dotted frame and the title "Hash mechanism". Text above the green arrow symbol reads "A hash digest is calculated from the input data packets and the signature metadata". The "Hash mechanism" arrow points at a box with white background and green frame, which reads "hash digest". At the top right corner of the diagram the symbol for a component key with both public and private key and the title "Signer private key" is shown. Both hash digest and component key symbol point to a large green arrow symbol, with green dotted frame, at the lower right corner of the diagram, using green dotted arrow lines. The large arrow symbol has the title "Signing mechanism" and text overlaid across it reads "A cryptographic signature is calculated over the hash digest, using the private key material of the signer.". It points at a cryptographic signature symbol at the bottom of the diagram. The cryptographic signature symbol is connected (via a green dotted arrow line) to the circle with white background and dotted green frame in the signature packet symbol. Creating a signature in OpenPGP ``` @@ -95,6 +103,8 @@ The main differences: After calculating the hash digest from the input data, a signature verification mechanism is employed. This mechanism uses the hash digest, the cryptographic signature from the signature packet, and the public key of the signer. Its purpose is to ascertain the cryptographic validity of the signature. ```{figure} diag/Signature_Verification.png +:name: fig-signature-verification +:alt: Depicts a complex diagram with white background and the title "Signature verification". On the top left side a box with black frame and white background reads "Input Data packets, One or more packets". Below it the symbol of a signature packet is shown. Both are connected (via green dotted arrows) to a green, right pointing arrow symbol with green dotted frame and the title "Hash mechanism". Text above the green arrow symbol reads "A hash digest is calculated from the input data packates and the signature metadata". The "Hash mechanism" arrow points at a box with white background and green frame, which reads "hash digest". At the top right corner of the diagram the symbol for a component key with only public key and the title "Signer public key" is shown. Hash digest, component key symbol and the cryptographic signature symbol in the signature packet point to a large green arrow symbol, with green dotted frame, at the lower right corner of the diagram, using green dotted arrow lines. The large arrow symbol has the title "Signature verification mechanism" and text overlaid across it reads "A cryptographic signature is verified against the hash digest, using the public key of the signer.". It points at a success and fail symbol at the bottom of the diagram. Verifying a signature in OpenPGP ``` diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index e3d0ace..796aaed 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -101,6 +101,8 @@ A subkey binding signature binds a subkey to a primary key, and adds metadata in (Note that subkeys that have the *signing* [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags) are a special case, and are handled slightly differently. See {numref}`bind_subkey_sign`.) ```{figure} diag/subkey_binding_signature.png +:name: fig-subkey-binding-signature +:alt: Depicts a diagram on white background with the title "Subkey binding signature". At the top left the symbol of a primary component key with certification capability is shown. At the bottom left the symbol of a component key with encryption capability is shown. The primary component key points at the lower component key with a full green arrow line. In the middle of the connection the small symbol of a signature packet is shown. On the right side of the diagram a detailed version of the signature packet can be found in a box with the title "Subkey binding signature". The text reads "Signature over Primary key, Subkey" and the box with "Signature metadata" contains the list "signature creation time", "key expiration time", "key flags" and "issuer fingerprint". The primary component key points at the detailed signature packet with a dotted green arrow line and the text "Primary key creates a subkey binding signature to bind the subkey to the primary key". Linking an OpenPGP subkey to the primary key with a binding signature ``` @@ -127,6 +129,8 @@ This is to prevent an attack where the attacker "adopts" the victims signing sub In contrast to the [subkey binding signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-subkey-binding) (type ID `0x18`), which is issued by the certificate's primary key, the [primary key binding signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#sigtype-primary-binding) (type ID `0x19`) is instead created by the subkey (informally also called an embedded "back signature"). ```{figure} diag/subkey_binding_signatur_for_signing_sk.png +:name: fig-subkey-binding-signature-for-signing-subkeys +:alt: Depicts a diagram on white background with the title "Subkey binding signature for signing subkeys". At the top left the symbol of a primary component key with certification capability is shown. At the bottom left the symbol of a component key with signing capability is shown. The primary component key points at the lower component key with a full green arrow line. In the middle of the connection the small symbol of a signature packet is shown. On the right side of the diagram a detailed version of the signature packet can be found in a box with the title "Subkey binding signature". The text reads "Signature over Primary key, Subkey" and the box with "Signature metadata" in it contains the list "signature creation time", "key expiration time", "key flags" and "issuer fingerprint". Within the signature metadata a box with a green dotted frame extends the list with an inlined signature packet with the title "Embedded Signature; Primary key binding". Its inner text reads "Signature over Primary Key, Signing Subkey". The signature metadata area of this embedded signature holds the list "signature creation time" and "issuer fingerprint". The cryptographic signature symbol overlaps both metadata and general section of the embedded signature. From the signing component key a green dotted arrow line points to the embedded signature in the subkey binding signature with the text "Signing key creates a primary binding signature to associate itself with the primary key" ("primary binding signature" in bold). At the top of the diagram, the primary component key points at the detailed signature packet with a dotted green arrow line and the text "Primary key creates a subkey binding signature to bind the subkey to the primary key". Linking an OpenPGP signing subkey to the primary key with a binding signature, and an embedded primary key binding signature ``` @@ -149,6 +153,8 @@ Alice can link a User ID to her OpenPGP certificate with a cryptographic signatu The resulting certifying self-signature packet is stored as part of the certificate, directly following the User ID packet. ```{figure} diag/user_id_certification.png +:name: fig-user-id-certification +:alt: Depicts a diagram on white background with the title "User ID binding signature". At the top left the symbol of a primary component key with certification capability is shown. At the bottom left the symbol of a User ID reads "Alice Adams ". The primary component key points at the User ID with a full green arrow line. In the middle of the connection the small symbol of a signature packet is shown. On the right side of the diagram a detailed version of the signature packet can be found in a box with the title "User ID binding signature". The text reads "Signature over Primary key, User ID" and the box with "Signature metadata" in it contains the list "signature creation time", "key expiration time", "primary User ID flag", "algorithm preferences", "key expiration time (primary key)" and "key flags (primary key)". At the top of the diagram, the primary component key points at the detailed signature packet with a dotted green arrow line and the text "Primary key creates a User ID binding signature to associate the User ID with the primary key". Linking a User ID to an OpenPGP certificate ``` diff --git a/book/source/17-zoom_certificates.md b/book/source/17-zoom_certificates.md index ca204ea..ec928a0 100644 --- a/book/source/17-zoom_certificates.md +++ b/book/source/17-zoom_certificates.md @@ -48,6 +48,8 @@ alice.pub-9--Signature ```{figure} diag/certificate_packet_list.png +:name: fig-certificate-packet-list +:alt: Depicts a box with white background and the title "Certificate packet list". Inside, a list of several boxes on white background and varying frame colors represent a list of OpenPGP packets from top to bottom. The first box, with green frame, represents the "Public-Key packet", and includes the green public key symbol. The second box, with yellow frame, represents a "Signature packet" ("Direct Key Signature") and includes the green cryptographic signature symbol. The third box, with black frame, represents a "User ID packet", and includes the black User ID symbol. The fourth box, with yellow frame, represents a "Signature packet" ("Certifying self-signature for User ID"), and includes the green cryptographic signature symbol. The fifth box, with green frame, represents a "Public-Subkey packet" and includes the green public key symbol. The sixth box, with yellow frame, represents a "Signature packet" ("Subkey binding signature") and includes the green cryptographic signature symbol. The seventh box, with green frame, represents a "Public-Subkey packet" and includes the green public key symbol. The eighth box, with yellow frame, represents a "Signature packet" ("Subkey binding signature") and includes the green cryptographic signature symbol. The ninth box, with green frame, represents a "Public-Subkey packet" and includes the green public key symbol. The tenth box, with yellow frame, represents a "Signature packet" ("Subkey binding signature") and includes the green cryptographic signature symbol. Overview of the packets in Alice's OpenPGP certificate ``` @@ -76,6 +78,8 @@ This version of Alice's certificate contains just two packets: This is the shape of the packets we'll explore in the subsequent sections: ```{figure} diag/pubcert-minimal.png +:name: fig-public-certificate-minimal +:alt: TODO :width: 40% A minimal OpenPGP certificate, visualized @@ -171,6 +175,8 @@ The packet type ID ("6") defines the semantics of the following data within the Note that the *Public-Key packet* contains only the public part of the key. ```{figure} diag/public-key_packet.png +:name: fig-public-key-packet +:alt: Depicts a box with white background and title "Public-Key packet". In the center a box with white background and green frame is shown. Inside it several items are listed, separated by green dotted horizontal lines. The first three are "Version", "Creation Time", "Public-Key Algorithm" written in black. The last one is written in green and reads "Public Key Material" and has the green public key symbol at its right side. Structure of a Public-Key packet. ``` @@ -361,6 +367,8 @@ The hash digest is calculated from the following data (see [Computing Signatures The signature is calculated from this hash digest. ```{figure} diag/direct_key_signature_packet.png +:name: fig-direct-key-signature-packet +:alt: Depicts a box with white background, title "Signature packet" and subtitle "Direct Key Signature (type ID 0x1F)". In the center a box with white background and green frame is shown. Inside it several items are listed, separated by green dotted horizontal lines. The first three are "Version", "Public-Key Algorithm" and "Hash Algorithm". The fourth item is called "Hashed area" and confines further sub-items by a light-green frame on the top and left side. The sub-items are "Signature Creation Time", "Key Expiration Time", "Preferred Symmetric Ciphers for v1 SEIPD", "Preferred Hash Algorithms", "Key Flags", "Features" and "Issuer Fingerprint". The fifth item is named "Unhashed area" and again introduces an area for sub-items, this time using a light-gray border on the top and left side. The unhashed area has no sub-items though. The last item is called "Cryptographic Signature", with the subtitle "by the primary key over primary key, subkey and signature metadata" and includes the green cryptographic signature symbol on the right side. Structure of a direct key signature packet. ``` diff --git a/book/source/18-zoom_private_keys.md b/book/source/18-zoom_private_keys.md index 2c5bbcb..7396b7a 100644 --- a/book/source/18-zoom_private_keys.md +++ b/book/source/18-zoom_private_keys.md @@ -23,6 +23,8 @@ The output starts with the (primary) [Secret-Key packet](https://www.ietf.org/ar This is the structure of the Secret-Key packet we will now look at. ```{figure} diag/secret-key_packet.png +:name: fig-secret-key-packet +:alt: Depicts a box with white background and title "Secret-Key packet". In the center a box with white background and red frame is shown. Inside it several items are listed, separated by red dotted horizontal lines. The first three are "Version", "Creation Time", "Public-Key Algorithm" written in black. The fourth one is written in green and reads "Public Key Material" and has the green public key symbol at its right side. The fifth one is again written in black and reads "S2K Usage (Secret Key Encryption)". The sixth item reads "Secret Key Material", written in red and has the red private key symbol at its right side. Structure of a Secret-Key packet. ``` @@ -199,4 +201,4 @@ Is the example key wrong?! ``` -"Plain or encrypted multiprecision integers comprising the secret key data. This is algorithm-specific and described in Section 5.5.5. If the string-to-key usage octet is 253 (AEAD), then an AEAD authentication tag is at the end of that data." \ No newline at end of file +"Plain or encrypted multiprecision integers comprising the secret key data. This is algorithm-specific and described in Section 5.5.5. If the string-to-key usage octet is 253 (AEAD), then an AEAD authentication tag is at the end of that data." From bf3c72d8552bbd87e74cc6198bc85aea97c21b70 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Mon, 20 Nov 2023 19:41:42 +0100 Subject: [PATCH 12/81] Adjust color description --- book/source/17-zoom_certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/17-zoom_certificates.md b/book/source/17-zoom_certificates.md index ec928a0..1d1fd60 100644 --- a/book/source/17-zoom_certificates.md +++ b/book/source/17-zoom_certificates.md @@ -368,7 +368,7 @@ The signature is calculated from this hash digest. ```{figure} diag/direct_key_signature_packet.png :name: fig-direct-key-signature-packet -:alt: Depicts a box with white background, title "Signature packet" and subtitle "Direct Key Signature (type ID 0x1F)". In the center a box with white background and green frame is shown. Inside it several items are listed, separated by green dotted horizontal lines. The first three are "Version", "Public-Key Algorithm" and "Hash Algorithm". The fourth item is called "Hashed area" and confines further sub-items by a light-green frame on the top and left side. The sub-items are "Signature Creation Time", "Key Expiration Time", "Preferred Symmetric Ciphers for v1 SEIPD", "Preferred Hash Algorithms", "Key Flags", "Features" and "Issuer Fingerprint". The fifth item is named "Unhashed area" and again introduces an area for sub-items, this time using a light-gray border on the top and left side. The unhashed area has no sub-items though. The last item is called "Cryptographic Signature", with the subtitle "by the primary key over primary key, subkey and signature metadata" and includes the green cryptographic signature symbol on the right side. +:alt: Depicts a box with white background, title "Signature packet" and subtitle "Direct Key Signature (type ID 0x1F)". In the center a box with white background and yellow frame is shown. Inside it several items are listed, separated by yellow dotted horizontal lines. The first three are "Version", "Public-Key Algorithm" and "Hash Algorithm". The fourth item is called "Hashed area" and confines further sub-items by a light-yellow frame on the top and left side. The sub-items are "Signature Creation Time", "Key Expiration Time", "Preferred Symmetric Ciphers for v1 SEIPD", "Preferred Hash Algorithms", "Key Flags", "Features" and "Issuer Fingerprint". The fifth item is named "Unhashed area" and again introduces an area for sub-items, this time using a light-gray border on the top and left side. The unhashed area has no sub-items though. The last item is called "Cryptographic Signature", with the subtitle "by the primary key over primary key, subkey and signature metadata" and includes the green cryptographic signature symbol on the right side. Structure of a direct key signature packet. ``` From f4ed0b2de1ac57ff588176ce2b00518ac9dcbc6d Mon Sep 17 00:00:00 2001 From: David Runge Date: Mon, 20 Nov 2023 19:21:10 +0100 Subject: [PATCH 13/81] Add contributing guidelines Signed-off-by: David Runge --- CONTRIBUTING.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..fa8a4ce --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,91 @@ + + +# Contributing + +These are the contribution guidelines for "Notes on OpenPGP". + +Development takes place at https://codeberg.org/openpgp/notes. + +Discussion around this project takes place in [`#notes-on-openpgp:matrix.org`] on [Matrix]. + +## Providing changes + +This project uses [sphinx] and [MyST-parser] to allow building various output formats, such as [HTML] and [EPUB], for the included book projects. + +Contributors can provide changes by pull request towards the project. + +### Building and testing + +The included book projects can be built and tested using a `Makefile`. + +The below examples show how to use it with a book named `book`. + +To cleanly build the [HTML] output: + +```shell +$ make -C book clean build +``` + +To cleanly build the [EPUB] output: + +```shell +$ make -C book clean epub +``` + +To spell check all files using [codespell]: + +```shell +$ make -C book codespell +``` + +To check the external links in all [HTML] files using [lychee]: + +```shell +$ make -C book html-linkcheck +``` + +### Writing text + +The syntax follows what is available in [MyST-parser]. + +--- +**NOTE**: It is advisable to always relate to the [MyST-parser] documentation, as [MyST] itself offers more/ different features! + +--- + +#### Cross-referencing + +There are a few guidelines when it comes to cross-referencing, which work around oddities with [sphinx] and [MyST-parser]: + +* When referencing chapters by file, use `[](/my-chapter)`, instead of relying on [explicit targets] for a top-level heading. +* To reference a figure by its title, use `[](#my-figure)` for a figure with the `:name:` attribute `my-figure` (and e.g. the title `My Figure`). +* To reference a figure by number (e.g. `Fig. 1`), use ```{numref}`my-figure` ``` for a figure with the `:name:` attribute `my-figure`. + +#### Figures + +[Figure] environments must have a `:name:` attribute, prefixed with `fig-`, so that they can be referenced elsewhere. +The `:alt:` attribute should explain what is displayed in the picture, as this is an [accessibility] feature. To keep matters brief, components and symbols that are described in other figures already, can be referenced by name instead of explaining them in detail. + +## License + +All text contributions fall under the terms of the [CC-BY-SA-4.0]. + +Configuration file contributions fall under the terms of the [CC0-1.0]. + +[`#notes-on-openpgp:matrix.org`]: https://matrix.to/#/%23notes-on-openpgp%3Amatrix.org +[Matrix]: https://matrix.org +[sphinx]: https://www.sphinx-doc.org/en/master/ +[MyST-parser]: https://myst-parser.readthedocs.io/en/latest/ +[HTML]: https://en.wikipedia.org/wiki/HTML +[EPUB]: https://en.wikipedia.org/wiki/EPUB +[MyST]: https://mystmd.org/guide/quickstart-myst-markdown +[codespell]: https://github.com/codespell-project/codespell +[lychee]: https://lychee.cli.rs +[explicit targets]: https://myst-parser.readthedocs.io/en/latest/syntax/cross-referencing.html#creating-explicit-targets +[Figure]: https://myst-parser.readthedocs.io/en/latest/syntax/images_and_figures.html#figures-images-with-captions +[accessibility]: https://en.wikipedia.org/wiki/Computer_accessibility +[CC-BY-SA-4.0]: ./LICENSES/CC-BY-SA-4.0.txt +[CC0-1.0]: ./LICENSES/CC0-1.0.txt From 886e8f5ff214098dd8f6b981c97c202ea398dab5 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 22 Nov 2023 15:05:17 +0100 Subject: [PATCH 14/81] Add anchor, and clarify intended meaning of section --- book/source/08-signing_components.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index 796aaed..cfafa7f 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -161,12 +161,12 @@ Linking a User ID to an OpenPGP certificate This signature is calculated over the primary key, User ID and the metadata of the signature packet. - -### Adding metadata to the primary key +(primary-metadata)= +### Adding metadata to the primary key/certificate The signatures that bind subkeys and identity components to a certificate serve two different purposes: Linking components to the certificate and adding metadata to a component. -The primary key in a certificate doesn't need to be linked to the certificate. It acts as the anchor for linking, itself and thus doesn't require being linked. However, there is nevertheless a need to associate metadata with the primary key. +The primary key in a certificate doesn't need to be linked to the certificate. It acts as the anchor for linking, itself and thus doesn't require being linked. However, there is nevertheless a need to associate metadata with the primary key, which typically applies to the certificate as a whole. There are two mechanisms for adding metadata to the primary key: From fd32381839c5929649de63bde8abfcbb27c4f30c Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 15 Nov 2023 00:02:18 +0100 Subject: [PATCH 15/81] ch8: add link anchor --- book/source/08-signing_components.md | 1 + 1 file changed, 1 insertion(+) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index cfafa7f..e94f00b 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -190,6 +190,7 @@ In OpenPGP v6, a direct key signature is the [preferred mechanism](https://www.i In a certificate, one User ID serves as the [*primary* User ID](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-primary-user-id). The metadata in the binding self-signature on this User ID applies to the primary key of the certificate. +(self-revocations)= ### Revocation self-signatures: Invalidating components of a certificate One important class of self-signatures are revocations. From 999549dcc391704e39d4682fc335c2118072343e Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 14 Nov 2023 21:51:14 +0100 Subject: [PATCH 16/81] ch4: elaborate on split User IDs --- book/source/04-certificates.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 254afc9..d8255e1 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -167,11 +167,13 @@ A typical User ID identity is a UTF-8-encoded string composed of a name and an e For further conventions on User IDs, refer to the document [draft-dkg-openpgp-userid-conventions-00](https://datatracker.ietf.org/doc/draft-dkg-openpgp-userid-conventions/), dated 25 August 2023. -One proposed variant for encoding identities in User ID is to use ["split User IDs"](https://dkg.fifthhorseman.net/blog/2021-dkg-openpgp-transition.html#split-user-ids). +**Split User IDs** -```{admonition} Warning -Heiko, please clarify what the value is of this proposal or remove it. -``` +One proposed variant for encoding identities in User ID is to use ["split User IDs"](https://dkg.fifthhorseman.net/blog/2021-dkg-openpgp-transition.html#split-user-ids). This style of User IDs is currently uncommon, but there is no technical impediment to using this format right now. + +An argument for split User IDs is that a name and an email address are two distinct identities, which are easier to reason about separately. This is particularly relevant when third parties consider certifying that an identity is legitimately connected to a certificate. + +For example, some third party may be sure about the email identity of a contact, and happy to issue a certification for an email-based identity (such as ``). But they may not have any insight into a name based identity (such as `Alice Adams`), and thus not willing to certify such a name-based identity. (primary_user_id)= ### Implications of the Primary User ID From c6888559f5598a64eb2095f56c84169a9e731d6f Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 14 Nov 2023 23:03:48 +0100 Subject: [PATCH 17/81] ch4: restructure text about metadata Move "metadata" content into its own section. This section started out as a remark about key flags, and was part of the "component key" section. Generalizing it seems better, so it's now after the "linking" section, which introduces binding self-signatures. --- book/source/04-certificates.md | 73 ++++++++++++++++++---------------- 1 file changed, 39 insertions(+), 34 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index d8255e1..4d5fc61 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -113,40 +113,6 @@ While subkeys have the same structural attributes as the primary key, they fulfi OpenPGP certificates can contain multiple subkeys. ``` -#### Defining operational capabilities with key flags - -Each component key has a set of ["key flags"](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#key-flags) that delineate the operations a key can perform. - -Commonly used key flags include: - -- **Certification**: enables issuing third-party certifications -- **Signing**: allows the key to sign data -- **Encryption**: allows the key to encrypt data -- **Authentication**: primarily used for OpenPGP authentication - -```{note} -Distinct component keys handle specific operations. Only the primary key can be used for certification, although it can have additional capabilities. Subkeys can be used for signing, encryption, and authentication but cannot have the certification capability. It is considered good practice, however, to [use separate keys for each capability](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-10.1.5-7). - -Notably, in many algorithms, encryption and signing-related functionalities (i.e., certification, signing, authentication) are mutually exclusive, because the algorithms only support one of those two families of operations[^key-flag-sharing]). -``` - -[^key-flag-sharing]: With ECC algorithms, it's impossible to combine encryption functions with those intended for signing. For example, ed25519 is specifically used for signing; cv25519 is designated for encryption. - -### Component key metadata, including key flags - -The key flags for a component key are not stored within the component key directly. - -Instead, key flags, along with other metadata about that component key, such as the key expiration time, are stored using mechanisms that bind components into an OpenPGP certificate: - -- For the primary key, its key flags and other metadata can be defined in two ways: they can be linked with the [Primary User ID](primary_user_id) or through a [direct key signature](direct_key_signature). -- For subkeys, the key flags and other metadata are set using the mechanism that binds the subkey to the certificate, specifically through the primary key. Further details on [binding subkeys](binding_subkeys) are below. - -```{admonition} TODO -:class: warning - -Write a section about algorithm preference/feature signaling -``` - (identity_components)= ## Identity components @@ -208,6 +174,45 @@ In very abstract terms, the primary key of a certificate acts as a root of trust By binding components using digital signatures, recipients of an OpenPGP certificate need only validate the authenticity of the primary key to use for their communication partner. Traditionally, this is done by manually verifying the *fingerprint* of the primary key. Once the validity of the primary key is confirmed, the validity of the remaining components can be automatically assessed by the user's OpenPGP software. Generally, components are valid parts of a certificate if there is a statement signed by the certificate's primary key endorsing this validity. +## Metadata: capabilities, preferences, etc + +Much of the metadata in OpenPGP certificates is actually not stored inside the components that the metadata applies to. Instead, much of the metadata for certificates, component keys and identities is defined as a part of the signatures that join components into a certificate. + +For example, the capabilities of a component key (such as *signing* or *encryption*), or the expiration time of a component key, are not encoded as a part of the *packet* that encodes the data of that component key. + +Instead, are stored using mechanisms that bind components into an OpenPGP certificate: + +- For the primary key, its key flags and other metadata can be defined in two ways: they can be linked with the [Primary User ID](primary_user_id) or through a [direct key signature](direct_key_signature). +- For subkeys, the key flags and other metadata are set using the mechanism that binds the subkey to the certificate, specifically through the primary key. Further details on [binding subkeys](binding_subkeys) are below. +- For identity components, like User IDs, metadata is associated via the [certifying self-signature](bind_ident) that links the identity to the certificate. + +### Defining operational capabilities of component keys with key flags + +Each component key has a set of ["key flags"](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#key-flags) that delineate the operations a key can perform. + +Commonly used key flags include: + +- **Certification**: enables issuing third-party certifications +- **Signing**: allows the key to sign data +- **Encryption**: allows the key to encrypt data +- **Authentication**: primarily used for OpenPGP authentication + +```{note} +Distinct component keys handle specific operations. Only the primary key can be used for certification, although it can have additional capabilities. Subkeys can be used for signing, encryption, and authentication but cannot have the certification capability. It is considered good practice, however, to [use separate keys for each capability](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-10.1.5-7). + +Notably, in many algorithms, encryption and signing-related functionalities (i.e., certification, signing, authentication) are mutually exclusive, because the algorithms only support one of those two families of operations[^key-flag-sharing]). +``` + +[^key-flag-sharing]: With ECC algorithms, it's impossible to combine encryption functions with those intended for signing. For example, ed25519 is specifically used for signing; cv25519 is designated for encryption. + +### Algorithm preferences and feature signaling + +```{admonition} TODO +:class: warning + +Write a section about algorithm preference/feature signaling +``` + ## Revocations ```{admonition} TODO From 6f609c7f88cf0d523112fcf6fbc496db4e5cf871 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 14 Nov 2023 23:39:23 +0100 Subject: [PATCH 18/81] ch4: new text about preferences/features --- book/source/04-certificates.md | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 4d5fc61..ec3e9e1 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -207,11 +207,25 @@ Notably, in many algorithms, encryption and signing-related functionalities (i.e ### Algorithm preferences and feature signaling -```{admonition} TODO -:class: warning +OpenPGP has a lot of ["cryptographic agility"](https://en.wikipedia.org/wiki/Cryptographic_agility). That is, OpenPGP doesn't just use one fixed set of algorithms, but defines a suite of cryptographic primitives that users (or their applications) can pick from. -Write a section about algorithm preference/feature signaling -``` +This agility has the advantage that adoption of new cryptographic primitives into the standard is relatively easy, and can be done without disruption. Users can gradually migrate to using new cryptographic mechanisms. + +However, it also means that OpenPGP software needs to figure out which mechanisms a set of communication partners can handle and prefers. To do this, there are a number of mechanisms in OpenPGP that can be negotiated between sender and recipient. The sender interprets the preferences of the recipient: + +- [Preferred Hash Algorithms](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-hashes-subpacket) +- [Preferred Symmetric Ciphers for v1 SEIPD](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-v1-seipd) +- [Preferred AEAD Ciphersuites](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-v2-seipd) +- [Features](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#features-subpacket) +- [Preferred Compression Algorithms](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-compression-subpacket) + +In addition to these explicitly expressed preferences, implementations also deduce capabilities of communication partners based on the OpenPGP version of the certificate that they write to. + +#### User ID-specific preferences + +As a starting point, a certificate has a set of preferences that apply generally. These are defined either in a direct key signature, or via the primary User ID of the certificate. + +Additionally, OpenPGP allows modeling User ID-specific preferences. The idea is that a user may prefer a different suite of algorithms on their private email account compared to their work email account. Such identity-specific preferences can be expressed on the certifying signatures that bind User IDs to a certificate. ## Revocations From 441936eb98d62207f63017dc73e196635fed235b Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 15 Nov 2023 00:02:54 +0100 Subject: [PATCH 19/81] ch4: new text about revocations --- book/source/04-certificates.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index ec3e9e1..cd4bdb7 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -229,11 +229,11 @@ Additionally, OpenPGP allows modeling User ID-specific preferences. The idea is ## Revocations -```{admonition} TODO -:class: warning +When the owner of a certificate wants to invalidate some components of that certificate, or the entire certificate, they can do so by "revoking" the component in question. Revoking the primary key renders the entire certificate invalid. -This section needs to be written -``` +More on revoking components of a certificate in {ref}`self-revocations`. + +Note that there are other ways besides revocations in which components can become invalid. For example, the component's expiration time may have passed. ## Third-party (identity) certifications From 451b881c03b17e7d59cf274a4aa04a29eecaa75a Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 15 Nov 2023 00:03:13 +0100 Subject: [PATCH 20/81] ch4: new text about third-party certifications --- book/source/04-certificates.md | 21 +++++++-------------- 1 file changed, 7 insertions(+), 14 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index cd4bdb7..f3d3bbd 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -237,13 +237,15 @@ Note that there are other ways besides revocations in which components can becom ## Third-party (identity) certifications -```{admonition} TODO -:class: warning +Third-party identity certifications have been a pivotal mechanism in the OpenPGP ecosystem since the beginning. The designers of PGP, beginning with Phil Zimmermann, have favored decentralized trust models, which don't hinge on centralized authorities. -This section needs to be written -``` +Third-party certifications are statements by OpenPGP users who attest that they have confirmed that a particular OpenPGP certificate belongs to a user with a particular identity. -Third-party identity certifications have historically played a pivotal role in the OpenPGP ecosystem. +For example, Bob's OpenPGP software may issue a certification that Bob has checked that the User ID `Alice Adams ` and the certificate with the fingerprint `AAA1 8CBB 2546 85C5 8358 3205 63FD 37B6 7F33 00F9 FB0E C457 378C D29F 1026 98B3` are legitimately linked. + +This presupposes that Bob knows this person who goes by "Alice Adams", and is satisfied that Alice uses the email address `alice@example.org`. Further, that Bob has verified that the certificate his OpenPGP software uses for Alice matches the certificate that Alice is using. Effectively this verification must ensure that both users have a certificate for Alice with the same fingerprint. In OpenPGP version 6, manual comparison of the fingerprint by end users is discouraged. A replacement mechanism is still pending. The verification must use a sufficiently secure channel, for example an end-to-end encrypted video call, or an in-person meeting. + +For more on third-party certifications, see {ref}`third_party_cert`. ### Security considerations @@ -255,15 +257,6 @@ It also opens the door to potential denial-of-service attacks, rendering the cer The popular [SKS keyserver network experienced certificate flooding firsthand](https://dkg.fifthhorseman.net/blog/openpgp-certificate-flooding.html), causing it to shut down operations in 2019. -### Improved mechanisms in OpenPGP v6 - -```{admonition} TODO -:class: warning - -This section needs to be written -``` - - ## Advanced topics ```{admonition} TODO From f35044bd683f2a3a4eac9fd4350066c35d7b291d Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 15 Nov 2023 00:51:00 +0100 Subject: [PATCH 21/81] ch4: move certification flooding section to "advanced" part --- book/source/04-certificates.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index f3d3bbd..637b048 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -247,16 +247,6 @@ This presupposes that Bob knows this person who goes by "Alice Adams", and is sa For more on third-party certifications, see {ref}`third_party_cert`. -### Security considerations - -While a convenience for consumers, indiscriminately accepting and integrating third-party identity certifications comes with significant risks. - -Without any restrictions in place, malicious entities can flood a certificate with excessive certifications. Called "certificate flooding," this form of digital vandalism grossly expands the certificate size, making the certificate cumbersome and impractical for users. - -It also opens the door to potential denial-of-service attacks, rendering the certificate non-functional or significantly impeding its operation. - -The popular [SKS keyserver network experienced certificate flooding firsthand](https://dkg.fifthhorseman.net/blog/openpgp-certificate-flooding.html), causing it to shut down operations in 2019. - ## Advanced topics ```{admonition} TODO @@ -323,3 +313,13 @@ references/links missing ``` Some OpenPGP subsystems may add User IDs to a certificate, which are not bound to the primary key by the certificate's owner. This can be useful to store local identity information (e.g., Sequoia's public store attaches "pet-names" to certificates, in this way). + +### Third-party certification flooding + +While a convenience for consumers, indiscriminately accepting and integrating third-party identity certifications comes with significant risks. + +Without any restrictions in place, malicious entities can flood a certificate with excessive certifications. Called "certificate flooding," this form of digital vandalism grossly expands the certificate size, making the certificate cumbersome and impractical for users. + +It also opens the door to potential denial-of-service attacks, rendering the certificate non-functional or significantly impeding its operation. + +The popular [SKS keyserver network experienced certificate flooding firsthand](https://dkg.fifthhorseman.net/blog/openpgp-certificate-flooding.html), causing it to shut down operations in 2019. From d157a4d1fc64e5f991b30280ef2425aa22e67a15 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 18 Nov 2023 17:44:01 +0100 Subject: [PATCH 22/81] move todo into advanced section branch, add link --- book/source/04-certificates.md | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 637b048..3064ea9 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -148,14 +148,7 @@ Within a certificate, a specific User ID is designated as the [Primary User ID]( Each User ID carries associated preference settings, such as preferred encryption algorithms, which is detailed in {numref}`zooming_in_user_id`). The preferences associated with the Primary User ID take precedence by default. -```{admonition} TODO -:class: warning - -i think crypto-refresh suggests that the direct key signature should hold the default preferences? -we might need to write a more nuanced text here, about how DKS and primary user id interact in v6, and mention the differences to v4? - -the primary User ID can also specify metadata about the primary key -``` +The primary User ID was historically sometimes used to store preferences that apply to the certificate as a whole. For more details on this, see {ref}`dks-puid`. ### User attributes in OpenPGP While From 26df966a2c8d4b1d9faf49d74eb825a6c3d28a9c Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 18 Nov 2023 18:54:03 +0100 Subject: [PATCH 23/81] clarify metadata section --- book/source/04-certificates.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 3064ea9..df5db9b 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -169,15 +169,17 @@ By binding components using digital signatures, recipients of an OpenPGP certifi ## Metadata: capabilities, preferences, etc -Much of the metadata in OpenPGP certificates is actually not stored inside the components that the metadata applies to. Instead, much of the metadata for certificates, component keys and identities is defined as a part of the signatures that join components into a certificate. +Much of the metadata for OpenPGP certificates, component keys, and identities, is not actually stored as part of the components that the metadata applies to. -For example, the capabilities of a component key (such as *signing* or *encryption*), or the expiration time of a component key, are not encoded as a part of the *packet* that encodes the data of that component key. +For example, the capabilities of a component key, such as *signing* or *encryption*, as well as its expiration time, are not stored as a part of the data of that component key. -Instead, are stored using mechanisms that bind components into an OpenPGP certificate: +Instead, this kind of metadata is stored as part of the signature packets that join components into an OpenPGP certificate: -- For the primary key, its key flags and other metadata can be defined in two ways: they can be linked with the [Primary User ID](primary_user_id) or through a [direct key signature](direct_key_signature). -- For subkeys, the key flags and other metadata are set using the mechanism that binds the subkey to the certificate, specifically through the primary key. Further details on [binding subkeys](binding_subkeys) are below. -- For identity components, like User IDs, metadata is associated via the [certifying self-signature](bind_ident) that links the identity to the certificate. +- For the primary key, its key flags and other metadata can be defined in two ways: + - With a [direct key signature](direct_key_signature) on the primary key, + - or by associating the metadata with the [Primary User ID](primary_user_id). +- For subkeys, metadata is defined with the [subkey binding signature](binding_subkeys) that links the subkey to the certificate. +- For identity components like User IDs, metadata is associated via the [certifying self-signature](bind_ident) that links the identity to the certificate. ### Defining operational capabilities of component keys with key flags From 15af2240acb1faabb442d3581ff0ea046bdf45a8 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Mon, 20 Nov 2023 15:27:19 +0100 Subject: [PATCH 24/81] ch4: minor edits from wiktor feedback --- book/source/04-certificates.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index df5db9b..abd5035 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -47,7 +47,7 @@ This documentation collectively refers to component keys and identity components Typical components in an OpenPGP certificate ``` -Every element in an OpenPGP certificate revolves around a central component: the *OpenPGP primary key*. The primary key acts as a personal CA (Certification Authority) for the certificate's owner, enabling cryptographic statements regarding subkeys, identities, expiration, revocation, and more. +Every element in an OpenPGP certificate revolves around a central component: the *OpenPGP primary key*. The primary key acts as a personal *certification authority* (CA) for the certificate's owner, enabling cryptographic statements regarding subkeys, identities, expiration, revocation, and more. ```{note} OpenPGP certificates tend to have a long lifespan, with the potential for modifications (typically by their owner) over time. Components may be added or invalidated throughout a certificate's lifetime. @@ -158,7 +158,7 @@ Currently, the OpenPGP standard prescribes only one format to be stored in user ## Linking the components -To form an OpenPGP certificate, individual components are interconnected by the certificate holder using their OpenPGP software. Within OpenPGP, this process is termed "binding," as in "a subkey is bound to the primary key." These bindings are realized using cryptographic signatures. An in-depth discussion of this topic can be found in {ref}`component_signatures_chapter`). +To form an OpenPGP certificate, individual components are interconnected by the certificate holder using their OpenPGP software. Within OpenPGP, this process is termed "binding," as in "a subkey is bound to the primary key." These bindings are realized using cryptographic signatures. An in-depth discussion of this topic can be found in {ref}`component_signatures_chapter`. In very abstract terms, the primary key of a certificate acts as a root of trust or "certification authority." It is responsible for: @@ -195,7 +195,7 @@ Commonly used key flags include: ```{note} Distinct component keys handle specific operations. Only the primary key can be used for certification, although it can have additional capabilities. Subkeys can be used for signing, encryption, and authentication but cannot have the certification capability. It is considered good practice, however, to [use separate keys for each capability](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-10.1.5-7). -Notably, in many algorithms, encryption and signing-related functionalities (i.e., certification, signing, authentication) are mutually exclusive, because the algorithms only support one of those two families of operations[^key-flag-sharing]). +Notably, in many algorithms, encryption and signing-related functionalities (i.e., certification, signing, authentication) are mutually exclusive, because the algorithms only support one of those two families of operations[^key-flag-sharing]. ``` [^key-flag-sharing]: With ECC algorithms, it's impossible to combine encryption functions with those intended for signing. For example, ed25519 is specifically used for signing; cv25519 is designated for encryption. From 1156d4987e1f7402c0adf06911888d39aa8faf02 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Mon, 20 Nov 2023 20:03:08 +0100 Subject: [PATCH 25/81] adjust User ID diagram description --- book/source/04-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index abd5035..d647e12 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -126,7 +126,7 @@ OpenPGP certificates can contain multiple [User IDs](https://www.ietf.org/archiv :name: fig-user-ids :alt: Depicts a diagram with white background and the title "User IDs". Inside, a public primary component key for certification and a User ID is shown. A green arrow points from component key to User ID and is annotated with a signature. -OpenPGP certificates can contain any number of User IDs +Relationship of User ID to primary component key in an OpenPGP certificate ``` A typical User ID identity is a UTF-8-encoded string composed of a name and an email address. By convention, User IDs align with the format described in [RFC2822](https://www.rfc-editor.org/rfc/rfc2822) as a *name-addr*. From 992c878fea254cef727275798cc2b4d1c2be87af Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 21 Nov 2023 10:02:39 +0100 Subject: [PATCH 26/81] This phrasing feels less confusing to me. I think this paragraph needs some more sharpening, but am still unsure about exactly how. --- book/source/04-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index d647e12..55c3d4b 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -26,7 +26,7 @@ In OpenPGP, the term "key" may refer to three distinct layers, each serving a un The following section will delve into the OpenPGP-specific layers (2 and 3) to provide a clearer understanding of their roles within OpenPGP certificates. -For a discussion of private key material in OpenPGP, see the chapter {ref}`private_key_chapter`. Bindings that connect the components of a certificate are discussed in our chapter {ref}`component_signatures_chapter`. For much more detail on the internal (packet) structure of certificates and keys refer to our chapter {ref}`zoom_certificates`. Additionally, managing certificates, and understanding their authentication and trust models are vital topics. While this document briefly touches upon these aspects, they are integral to working proficiently with OpenPGP. +For a discussion of private key material in OpenPGP, see the chapter {ref}`private_key_chapter`. Bindings that connect the components of a certificate are discussed in our chapter {ref}`component_signatures_chapter`. For much more detail on the internal (packet) structure of certificates and keys refer to our chapter {ref}`zoom_certificates`. Additionally, managing certificates, and understanding their authentication and trust models are vital topics. While this document only touches upon these aspects briefly, they are integral to working proficiently with OpenPGP. ## Structure of OpenPGP certificates From ff198a3413b2f6ea6a6b46b5ddec16c641d73ef0 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 21 Nov 2023 10:08:12 +0100 Subject: [PATCH 27/81] Clarify authentication key flag --- book/source/04-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 55c3d4b..2ceb0cc 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -190,7 +190,7 @@ Commonly used key flags include: - **Certification**: enables issuing third-party certifications - **Signing**: allows the key to sign data - **Encryption**: allows the key to encrypt data -- **Authentication**: primarily used for OpenPGP authentication +- **Authentication**: primarily used for SSH authentication ```{note} Distinct component keys handle specific operations. Only the primary key can be used for certification, although it can have additional capabilities. Subkeys can be used for signing, encryption, and authentication but cannot have the certification capability. It is considered good practice, however, to [use separate keys for each capability](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-10.1.5-7). From 42b9e98e211638b83935c3ab482fa556478abd5d Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 21 Nov 2023 10:13:32 +0100 Subject: [PATCH 28/81] clarify that "authentication" key flag is not about validating user ids --- book/source/04-certificates.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 2ceb0cc..f0220bb 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -190,7 +190,9 @@ Commonly used key flags include: - **Certification**: enables issuing third-party certifications - **Signing**: allows the key to sign data - **Encryption**: allows the key to encrypt data -- **Authentication**: primarily used for SSH authentication +- **Authentication**: primarily used for SSH authentication[^auth-flag] + +[^auth-flag]: Note that the capability offered by the [authentication](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-authentication-via-digital-) key flag is unrelated to "authentication" in the context of certifying and verifying OpenPGP identities and their connection to certificates. This key flag is about a mechanism that proves control of private key material to a remote system, using cryptographic signatures. ```{note} Distinct component keys handle specific operations. Only the primary key can be used for certification, although it can have additional capabilities. Subkeys can be used for signing, encryption, and authentication but cannot have the certification capability. It is considered good practice, however, to [use separate keys for each capability](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-10.1.5-7). From ade8edd697b628c040917830a21a1df3e3512e9e Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 21 Nov 2023 10:31:41 +0100 Subject: [PATCH 29/81] link to cryptographic hashes --- book/source/03-cryptography.md | 1 + book/source/04-certificates.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/book/source/03-cryptography.md b/book/source/03-cryptography.md index 560d24e..166e869 100644 --- a/book/source/03-cryptography.md +++ b/book/source/03-cryptography.md @@ -6,6 +6,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 (cryptography_chapter)= # Cryptographic concepts and terms +(crypto-hash)= ## Cryptographic hash functions [Cryptographic hash functions](https://en.wikipedia.org/wiki/Cryptographic_hash_function) take data strings of any length (like a text message or file) and output a fixed-size code, a "hash digest," which is often abbreviated as either "digest" or "hash." A hash digest acts like a unique identifier for the original data. diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index f0220bb..b0119ad 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -78,7 +78,7 @@ Each OpenPGP component key possesses an *OpenPGP fingerprint*. This fingerprint :name: fig-fingerprint :alt: Depicts a box with white background and the title "Fingerprint of an OpenPGP component key". Inside, another box with a green frame, the title "Component Key", the text "key creation time" on the lower left and a the green public key symbol on the lower right is shown. Below the component key box a fingerprint in a box with a light-yellow background and a yellow dotted line is depicted. The word "Fingerprint" is shown left of the box with the fingerprint and both are connected with a yellow dotted line. -Every OpenPGP component key is identifiable by a fingerprint. Although it's technically possible for different keys to share a fingerprint, cryptographic mechanisms make it exceedingly difficult, if not practically impossible with current technology, to find keys that share a fingerprint. +Every OpenPGP component key is identifiable by a fingerprint. Although it's technically possible for different keys to share a fingerprint, [cryptographic mechanisms](crypto-hash) make it exceedingly difficult, if not practically impossible with current technology, to find keys that share a fingerprint. ``` The fingerprint of our example OpenPGP component key is `C0A5 8384 A438 E5A1 4F73 7124 26A4 D45D BAEE F4A3 9E6B 30B0 9D55 13F9 78AC CA94`[^keyid]. From ae2c732730acb2691538aa950098560caaaa2cdf Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Tue, 21 Nov 2023 12:30:18 +0100 Subject: [PATCH 30/81] Note that DKS is preferred in v6 --- book/source/04-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index b0119ad..b99fe94 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -176,7 +176,7 @@ For example, the capabilities of a component key, such as *signing* or *encrypti Instead, this kind of metadata is stored as part of the signature packets that join components into an OpenPGP certificate: - For the primary key, its key flags and other metadata can be defined in two ways: - - With a [direct key signature](direct_key_signature) on the primary key, + - With a [direct key signature](direct_key_signature) on the primary key (preferred method in OpenPGP version 6), - or by associating the metadata with the [Primary User ID](primary_user_id). - For subkeys, metadata is defined with the [subkey binding signature](binding_subkeys) that links the subkey to the certificate. - For identity components like User IDs, metadata is associated via the [certifying self-signature](bind_ident) that links the identity to the certificate. From 4a39b205869276088a154cd098ece1809677eb43 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 22 Nov 2023 15:16:07 +0100 Subject: [PATCH 31/81] ch4: clarify primary user id section --- book/source/04-certificates.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index b99fe94..bdce127 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -146,9 +146,9 @@ For example, some third party may be sure about the email identity of a contact, Within a certificate, a specific User ID is designated as the [Primary User ID](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-primary-user-id). -Each User ID carries associated preference settings, such as preferred encryption algorithms, which is detailed in {numref}`zooming_in_user_id`). The preferences associated with the Primary User ID take precedence by default. +Each User ID carries associated preference settings, such as preferred encryption algorithms, which is detailed in {numref}`zooming_in_user_id`). When a certificate is used in the context of a specific identity, then the preferences associated with that identity component are used. When a certificate is used without reference to a specific identity, the preferences associated with the direct key signature, or the primary User ID take precedence by default. -The primary User ID was historically sometimes used to store preferences that apply to the certificate as a whole. For more details on this, see {ref}`dks-puid`. +The primary User ID was historically the main store for preferences that apply to the certificate as a whole. For more on this, see {ref}`primary-metadata`. ### User attributes in OpenPGP While From 2f4a794d1c29fed0b70b6634a372ab81c51b7c67 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 22 Nov 2023 16:26:17 +0100 Subject: [PATCH 32/81] ch8: add link anchor --- book/source/08-signing_components.md | 1 + 1 file changed, 1 insertion(+) diff --git a/book/source/08-signing_components.md b/book/source/08-signing_components.md index e94f00b..8eda52e 100644 --- a/book/source/08-signing_components.md +++ b/book/source/08-signing_components.md @@ -302,6 +302,7 @@ For example, Alice could delegate trust decisions only for email addresses in th add diagrams? ``` +(wot)= ### Decentralized automated trust decisions; or, the "Web of Trust" The OpenPGP, the "Web of Trust" is a trust model that performs authentication decisions on a set of certifications and delegations. From 166ab7bc55b6ab890e3b3d59dc12f97897d453f6 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 22 Nov 2023 16:54:59 +0100 Subject: [PATCH 33/81] mention "wot" and link to ch8 section --- book/source/04-certificates.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index bdce127..9b328c9 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -234,13 +234,13 @@ Note that there are other ways besides revocations in which components can becom ## Third-party (identity) certifications -Third-party identity certifications have been a pivotal mechanism in the OpenPGP ecosystem since the beginning. The designers of PGP, beginning with Phil Zimmermann, have favored decentralized trust models, which don't hinge on centralized authorities. +Third-party identity certifications have been a pivotal mechanism in the OpenPGP ecosystem since the beginning. The designers of PGP, beginning with Phil Zimmermann, have favored decentralized trust models, which don't hinge on centralized authorities. OpenPGP's decentralized trust model is called the ["Web of Trust."](wot) Third-party certifications are statements by OpenPGP users who attest that they have confirmed that a particular OpenPGP certificate belongs to a user with a particular identity. For example, Bob's OpenPGP software may issue a certification that Bob has checked that the User ID `Alice Adams ` and the certificate with the fingerprint `AAA1 8CBB 2546 85C5 8358 3205 63FD 37B6 7F33 00F9 FB0E C457 378C D29F 1026 98B3` are legitimately linked. -This presupposes that Bob knows this person who goes by "Alice Adams", and is satisfied that Alice uses the email address `alice@example.org`. Further, that Bob has verified that the certificate his OpenPGP software uses for Alice matches the certificate that Alice is using. Effectively this verification must ensure that both users have a certificate for Alice with the same fingerprint. In OpenPGP version 6, manual comparison of the fingerprint by end users is discouraged. A replacement mechanism is still pending. The verification must use a sufficiently secure channel, for example an end-to-end encrypted video call, or an in-person meeting. +This presupposes that Bob knows this person who goes by "Alice Adams", and is satisfied that Alice uses the email address `alice@example.org`. Further, that Bob has verified that the certificate his OpenPGP software uses for Alice matches the certificate that Alice is using. Effectively, this verification must ensure that both users have a certificate for Alice with the same fingerprint. In OpenPGP version 6, manual comparison of the fingerprint by end users is discouraged. A replacement mechanism is still pending. The verification must use a sufficiently secure channel, for example an end-to-end encrypted video call, or an in-person meeting. For more on third-party certifications, see {ref}`third_party_cert`. From 6757b47f81e14ce48004d1f60e0d55a502f86a65 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 22 Nov 2023 17:03:55 +0100 Subject: [PATCH 34/81] ch4: minor edits --- book/source/04-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 9b328c9..8611056 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -240,7 +240,7 @@ Third-party certifications are statements by OpenPGP users who attest that they For example, Bob's OpenPGP software may issue a certification that Bob has checked that the User ID `Alice Adams ` and the certificate with the fingerprint `AAA1 8CBB 2546 85C5 8358 3205 63FD 37B6 7F33 00F9 FB0E C457 378C D29F 1026 98B3` are legitimately linked. -This presupposes that Bob knows this person who goes by "Alice Adams", and is satisfied that Alice uses the email address `alice@example.org`. Further, that Bob has verified that the certificate his OpenPGP software uses for Alice matches the certificate that Alice is using. Effectively, this verification must ensure that both users have a certificate for Alice with the same fingerprint. In OpenPGP version 6, manual comparison of the fingerprint by end users is discouraged. A replacement mechanism is still pending. The verification must use a sufficiently secure channel, for example an end-to-end encrypted video call, or an in-person meeting. +This presupposes that Bob knows this person who goes by "Alice Adams," and is satisfied that Alice uses the email address `alice@example.org`. Further, that Bob has verified that the certificate his OpenPGP software uses for Alice matches the certificate that Alice is using. Effectively, this verification must ensure that both users have a certificate for Alice with the same fingerprint. In OpenPGP version 6, manual comparison of the fingerprint by end users is discouraged. A replacement mechanism is still pending. The verification must use a sufficiently secure channel, for example, an end-to-end encrypted video call, or an in-person meeting. For more on third-party certifications, see {ref}`third_party_cert`. From c575165cd34997018907ae646635f9a3b4689a15 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 22 Nov 2023 17:09:14 +0100 Subject: [PATCH 35/81] ch4: clarify/link "certificates are effectively append-only" --- book/source/04-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 8611056..13f32b2 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -50,7 +50,7 @@ Typical components in an OpenPGP certificate Every element in an OpenPGP certificate revolves around a central component: the *OpenPGP primary key*. The primary key acts as a personal *certification authority* (CA) for the certificate's owner, enabling cryptographic statements regarding subkeys, identities, expiration, revocation, and more. ```{note} -OpenPGP certificates tend to have a long lifespan, with the potential for modifications (typically by their owner) over time. Components may be added or invalidated throughout a certificate's lifetime. +OpenPGP certificates tend to have a long lifespan, with the potential for modifications (typically by their owner) over time. Components may be added or invalidated throughout a certificate's lifetime. However, once published, components [cannot be removed](append-only) from certificates. ``` ## Component keys From 142250277fad219940864b0ab242171e766157be Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 22 Nov 2023 17:18:51 +0100 Subject: [PATCH 36/81] ch4: qualify split user id section with a footnote linking to dkg's 2019 blog outlining problems --- book/source/04-certificates.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 13f32b2..ce5996f 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -135,11 +135,13 @@ For further conventions on User IDs, refer to the document [draft-dkg-openpgp-us **Split User IDs** -One proposed variant for encoding identities in User ID is to use ["split User IDs"](https://dkg.fifthhorseman.net/blog/2021-dkg-openpgp-transition.html#split-user-ids). This style of User IDs is currently uncommon, but there is no technical impediment to using this format right now. +One proposed variant for encoding identities in User ID is to use ["split User IDs"](https://dkg.fifthhorseman.net/blog/2021-dkg-openpgp-transition.html#split-user-ids). This style of User IDs is currently uncommon, but there is no strong technical impediment to using this format right now[^dkg-split]. + +[^dkg-split]: Note that in the past, there were stumbling blocks in the OpenPGP ecosystem, see ["What were Separated User IDs"](https://dkg.fifthhorseman.net/blog/2019-dkg-openpgp-transition.html#what-were-separated-user-ids) from January 2019, by Daniel Kahn Gillmor. An argument for split User IDs is that a name and an email address are two distinct identities, which are easier to reason about separately. This is particularly relevant when third parties consider certifying that an identity is legitimately connected to a certificate. -For example, some third party may be sure about the email identity of a contact, and happy to issue a certification for an email-based identity (such as ``). But they may not have any insight into a name based identity (such as `Alice Adams`), and thus not willing to certify such a name-based identity. +For example, some third party may be sure about the email identity of a contact, and happy to issue a certification for an email-based identity (such as ``). But they may not have any insight into a name-based identity (such as `Alice Adams`), and thus not willing to certify such a name-based identity. (primary_user_id)= ### Implications of the Primary User ID From e0457bac6407c8cbdd6c601c9dfcfcf6bd1961a6 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 22 Nov 2023 17:24:29 +0100 Subject: [PATCH 37/81] ch4: clarify that user attribute images are JPEG --- book/source/04-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index ce5996f..f0b3e12 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -156,7 +156,7 @@ The primary User ID was historically the main store for preferences that apply t While [user attributes](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-user-attribute-packet-tag-1) are similar to User IDs, they are less commonly used. -Currently, the OpenPGP standard prescribes only one format to be stored in user attributes: an [image](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-the-image-attribute-subpack). Typically, this image represents the key owner, although it is not required. +Currently, the OpenPGP standard prescribes only one format to be stored in user attributes: an [image](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-the-image-attribute-subpack), in JPEG format. Typically, this image represents the key owner, although it is not required. ## Linking the components From fc665cb19738a4f0c03e95b0985d28f79e199e77 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 22 Nov 2023 17:34:53 +0100 Subject: [PATCH 38/81] ch4: clarification as suggested by wiktor --- book/source/04-certificates.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index f0b3e12..ef106aa 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -183,6 +183,8 @@ Instead, this kind of metadata is stored as part of the signature packets that j - For subkeys, metadata is defined with the [subkey binding signature](binding_subkeys) that links the subkey to the certificate. - For identity components like User IDs, metadata is associated via the [certifying self-signature](bind_ident) that links the identity to the certificate. +Note that the components of an OpenPGP certificate are themselves never changed, after their initial creation. By storing associated metadata in signatures, it can be modified at a later point in time by issuing a new signature that replaces the previous one. For example, the certificate holder can change the expiration time of a component of their certificate by issuing a new signature. + ### Defining operational capabilities of component keys with key flags Each component key has a set of ["key flags"](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#key-flags) that delineate the operations a key can perform. From 28ec86b4b68dde49bef9e8e9d5297c8a86806901 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 22 Nov 2023 17:36:31 +0100 Subject: [PATCH 39/81] ch4: fix flow/logic --- book/source/04-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index ef106aa..a89d21d 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -199,7 +199,7 @@ Commonly used key flags include: [^auth-flag]: Note that the capability offered by the [authentication](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-authentication-via-digital-) key flag is unrelated to "authentication" in the context of certifying and verifying OpenPGP identities and their connection to certificates. This key flag is about a mechanism that proves control of private key material to a remote system, using cryptographic signatures. ```{note} -Distinct component keys handle specific operations. Only the primary key can be used for certification, although it can have additional capabilities. Subkeys can be used for signing, encryption, and authentication but cannot have the certification capability. It is considered good practice, however, to [use separate keys for each capability](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-10.1.5-7). +Distinct component keys handle specific operations. Only the primary key can be used for certification, although it can have additional capabilities. Subkeys can be used for signing, encryption, and authentication but cannot have the certification capability. A component key can technically have multiple capabilities. It is considered good practice, however, to [use separate keys for each capability](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-10.1.5-7). Notably, in many algorithms, encryption and signing-related functionalities (i.e., certification, signing, authentication) are mutually exclusive, because the algorithms only support one of those two families of operations[^key-flag-sharing]. ``` From 7f90c71be472b65548e63e9934eff07724f1d23a Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 22 Nov 2023 17:49:08 +0100 Subject: [PATCH 40/81] ch4: clarification --- book/source/04-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index a89d21d..e0ddfaf 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -212,7 +212,7 @@ OpenPGP has a lot of ["cryptographic agility"](https://en.wikipedia.org/wiki/Cry This agility has the advantage that adoption of new cryptographic primitives into the standard is relatively easy, and can be done without disruption. Users can gradually migrate to using new cryptographic mechanisms. -However, it also means that OpenPGP software needs to figure out which mechanisms a set of communication partners can handle and prefers. To do this, there are a number of mechanisms in OpenPGP that can be negotiated between sender and recipient. The sender interprets the preferences of the recipient: +However, it also means that OpenPGP software needs to figure out which mechanisms a set of communication partners can handle and prefer. To do this, there are a number of mechanisms in OpenPGP that can be negotiated between sender and recipient. Note that OpenPGP is not an online scheme, so this negotiation is effectively one-way: The active party interprets the preferences that are expressed in the certificate of the passive party. - [Preferred Hash Algorithms](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-hashes-subpacket) - [Preferred Symmetric Ciphers for v1 SEIPD](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-v1-seipd) From b337068d612c31b5ef5f645652d98f0c0f397627 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 22 Nov 2023 21:08:22 +0100 Subject: [PATCH 41/81] ch4: process input from liw, in #113 --- book/source/04-certificates.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index e0ddfaf..c3b3ff1 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -6,7 +6,9 @@ SPDX-License-Identifier: CC-BY-SA-4.0 (certificates_chapter)= # Certificates -OpenPGP fundamentally hinges on the concept of "OpenPGP certificates," also known as "OpenPGP keys." These certificates are complex data structures essential for identity verification, data encryption, and digital signatures. Understanding their structure and function is pivotal to effectively applying the OpenPGP standard. +OpenPGP fundamentally hinges on the concept of "OpenPGP certificates," also known as "OpenPGP public keys." These certificates are complex data structures essential for identity verification, data encryption, and digital signatures. Understanding their structure and function is pivotal to effectively applying the OpenPGP standard. + +An OpenPGP certificate, by definition, does not contain private key material. ## Terminology: Understanding "keys" From 02b0785584a3e2b8fcc52bcbdc2bde3e2d5afa2c Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Wed, 22 Nov 2023 21:38:33 +0100 Subject: [PATCH 42/81] ch4: attempt at clarifying the kind-of-unique-but-technically-not property of fingerprints, to deal with #113 --- book/source/04-certificates.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index c3b3ff1..4f0e559 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -80,7 +80,7 @@ Each OpenPGP component key possesses an *OpenPGP fingerprint*. This fingerprint :name: fig-fingerprint :alt: Depicts a box with white background and the title "Fingerprint of an OpenPGP component key". Inside, another box with a green frame, the title "Component Key", the text "key creation time" on the lower left and a the green public key symbol on the lower right is shown. Below the component key box a fingerprint in a box with a light-yellow background and a yellow dotted line is depicted. The word "Fingerprint" is shown left of the box with the fingerprint and both are connected with a yellow dotted line. -Every OpenPGP component key is identifiable by a fingerprint. Although it's technically possible for different keys to share a fingerprint, [cryptographic mechanisms](crypto-hash) make it exceedingly difficult, if not practically impossible with current technology, to find keys that share a fingerprint. +Every OpenPGP component key is identifiable by a fingerprint. ``` The fingerprint of our example OpenPGP component key is `C0A5 8384 A438 E5A1 4F73 7124 26A4 D45D BAEE F4A3 9E6B 30B0 9D55 13F9 78AC CA94`[^keyid]. @@ -89,6 +89,12 @@ The fingerprint of our example OpenPGP component key is `C0A5 8384 A438 E5A1 4F7 For example, an OpenPGP version 4 certificate with the fingerprint `B3D2 7B09 FBA4 1235 2B41 8972 C8B8 6AC4 2455 4239` might be referenced by the 64-bit Key ID `C8B8 6AC4 2455 4239` or formatted as `0xC8B86AC424554239`. Historically, even shorter 32-bit identifiers were used, like this: `2455 4239`, or `0x24554239`. Such identifiers still appear in very old documents about PGP. However, [32-bit identifiers have been long deemed unfit for purpose](https://evil32.com/). At one point, 32-bit identifiers were called "short Key ID," while 64-bit identifiers were referred to as "long Key ID." +```{note} +In practice, the fingerprint of a component key is used like a unique identifier. + +However, formally, a fingerprint is not unique. For every component key, other component keys with the same fingerprint exist, in theory. But because fingerprints are calculated using a [cryptographic hash algorithm](crypto-hash), it is practically impossible to find two different component keys that have the same fingerprint. + ``` + ### Primary key The OpenPGP primary key is a component key that serves a distinct, central role in an OpenPGP certificate: From a3cff899be046ea1b85d56c2b26e18e950d8de82 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Thu, 23 Nov 2023 12:48:18 +0100 Subject: [PATCH 43/81] move chapters 17+ one back, insert a new "differences between versions" chapter 17 --- book/source/17-versions.md | 7 +++++++ .../{17-zoom_certificates.md => 18-zoom_certificates.md} | 0 .../{18-zoom_private_keys.md => 19-zoom_private_keys.md} | 0 .../{19-zoom_signatures.md => 20-zoom_signatures.md} | 0 book/source/{20-zoom_encyption.md => 21-zoom_encyption.md} | 0 book/source/{21-resources.md => 22-resources.md} | 0 book/source/{22-glossary.md => 23-glossary.md} | 0 .../{23-acknowledgements.md => 24-acknowledgements.md} | 0 8 files changed, 7 insertions(+) create mode 100644 book/source/17-versions.md rename book/source/{17-zoom_certificates.md => 18-zoom_certificates.md} (100%) rename book/source/{18-zoom_private_keys.md => 19-zoom_private_keys.md} (100%) rename book/source/{19-zoom_signatures.md => 20-zoom_signatures.md} (100%) rename book/source/{20-zoom_encyption.md => 21-zoom_encyption.md} (100%) rename book/source/{21-resources.md => 22-resources.md} (100%) rename book/source/{22-glossary.md => 23-glossary.md} (100%) rename book/source/{23-acknowledgements.md => 24-acknowledgements.md} (100%) diff --git a/book/source/17-versions.md b/book/source/17-versions.md new file mode 100644 index 0000000..b5ac53e --- /dev/null +++ b/book/source/17-versions.md @@ -0,0 +1,7 @@ + + +(versions)= +# Differences between OpenPGP versions diff --git a/book/source/17-zoom_certificates.md b/book/source/18-zoom_certificates.md similarity index 100% rename from book/source/17-zoom_certificates.md rename to book/source/18-zoom_certificates.md diff --git a/book/source/18-zoom_private_keys.md b/book/source/19-zoom_private_keys.md similarity index 100% rename from book/source/18-zoom_private_keys.md rename to book/source/19-zoom_private_keys.md diff --git a/book/source/19-zoom_signatures.md b/book/source/20-zoom_signatures.md similarity index 100% rename from book/source/19-zoom_signatures.md rename to book/source/20-zoom_signatures.md diff --git a/book/source/20-zoom_encyption.md b/book/source/21-zoom_encyption.md similarity index 100% rename from book/source/20-zoom_encyption.md rename to book/source/21-zoom_encyption.md diff --git a/book/source/21-resources.md b/book/source/22-resources.md similarity index 100% rename from book/source/21-resources.md rename to book/source/22-resources.md diff --git a/book/source/22-glossary.md b/book/source/23-glossary.md similarity index 100% rename from book/source/22-glossary.md rename to book/source/23-glossary.md diff --git a/book/source/23-acknowledgements.md b/book/source/24-acknowledgements.md similarity index 100% rename from book/source/23-acknowledgements.md rename to book/source/24-acknowledgements.md From 4e9f1c0ffde6808b7ee60fd5bbc4b2a622b987a3 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Thu, 23 Nov 2023 13:19:28 +0100 Subject: [PATCH 44/81] add note to "differences between versions" chapter --- book/source/17-versions.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/book/source/17-versions.md b/book/source/17-versions.md index b5ac53e..1043db1 100644 --- a/book/source/17-versions.md +++ b/book/source/17-versions.md @@ -5,3 +5,10 @@ SPDX-License-Identifier: CC-BY-SA-4.0 (versions)= # Differences between OpenPGP versions + +```{admonition} TODO +:class: warning + +write about the delta between v4 and v6, most of all +- a starting point? https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-upgrade-guidance-adapting-i +``` From 7f68db756cded2d2f1eee3473b900c735a36cb65 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Thu, 23 Nov 2023 13:31:16 +0100 Subject: [PATCH 45/81] ch3: streamline the text that connects the "hybrid cryptosystems" concept to its use in openpgp --- book/source/03-cryptography.md | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/book/source/03-cryptography.md b/book/source/03-cryptography.md index a213c89..c016b1a 100644 --- a/book/source/03-cryptography.md +++ b/book/source/03-cryptography.md @@ -131,14 +131,8 @@ Digital signatures in OpenPGP are used in two primary contexts: (hybrid_cryptosystems)= ## Hybrid cryptosystems -OpenPGP uses a hybrid cryptosystem. [Hybrid cryptosystems](https://en.wikipedia.org/wiki/Hybrid_cryptosystem) combine the use of symmetric and asymmetric (public-key) cryptography to capitalize on the strengths of each, namely symmetric cryptography's speed and efficiency and public-key cryptography's mechanism for secure key exchange. +[Hybrid cryptosystems](https://en.wikipedia.org/wiki/Hybrid_cryptosystem) combine the use of symmetric and asymmetric (public-key) cryptography to capitalize on the strengths of each, namely symmetric cryptography's speed and efficiency and public-key cryptography's mechanism for secure key exchange. -```{admonition} TODO -:class: warning +### Usage and terminology in OpenPGP -Move this to the chapter that details it: - -Within OpenPGP's hybrid system, so-called "session keys" are central. They are generated uniquely for each session and are instrumental in both encrypting and decrypting the actual message content, using the efficiency of symmetric-key cryptography. - -Using asymmetric (public-key) cryptography, the session keys are also encrypted. This ensures that only the intended recipient, the holder of the corresponding private key, can decrypt and gain access to the session key. With the decrypted session key, they can then use the session key to decrypt the actual message. -``` \ No newline at end of file +OpenPGP uses a hybrid cryptosystem for encryption. Shared secrets are generated uniquely for each session, and are called "session keys." For more on this, see the chapters {ref}`encryption_chapter` and {ref}`decryption_chapter`. From ec761273df6d6288458ab19320c1a2d645a12cbe Mon Sep 17 00:00:00 2001 From: David Runge Date: Wed, 22 Nov 2023 22:32:53 +0100 Subject: [PATCH 46/81] Modify CSS for admonition environments when building EPUB Add a lightgray `background-color` for all admonition environments. Add a palevioletred `background-color` for all admonition-warning and warning environments. Signed-off-by: David Runge --- book/source/_static/epub/css/custom.css | 13 +++++++++++++ book/source/conf.py | 5 +++++ 2 files changed, 18 insertions(+) create mode 100644 book/source/_static/epub/css/custom.css diff --git a/book/source/_static/epub/css/custom.css b/book/source/_static/epub/css/custom.css new file mode 100644 index 0000000..40ca147 --- /dev/null +++ b/book/source/_static/epub/css/custom.css @@ -0,0 +1,13 @@ +/* +SPDX-FileCopyrightText: 2023 The "Notes on OpenPGP" project +SPDX-License-Identifier: CC0-1.0 +*/ + +div.admonition { + background-color: lightgray; +} + +div.warning, +div.admonition-warning { + background-color: palevioletred; +} \ No newline at end of file diff --git a/book/source/conf.py b/book/source/conf.py index 96f5eb4..abacb6f 100644 --- a/book/source/conf.py +++ b/book/source/conf.py @@ -24,7 +24,12 @@ source_suffix = ['.md', '.rst'] templates_path = ['_templates'] exclude_patterns = [] +# -- Options for EPUB output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-epub-output +epub_css_files = [ + 'epub/css/custom.css' +] # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output From 34f94f780291a90490440f458922b3b2d2a317d9 Mon Sep 17 00:00:00 2001 From: David Runge Date: Fri, 24 Nov 2023 10:50:44 +0100 Subject: [PATCH 47/81] Move numfig configuration to general configuration Signed-off-by: David Runge --- book/source/conf.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/book/source/conf.py b/book/source/conf.py index abacb6f..26f49db 100644 --- a/book/source/conf.py +++ b/book/source/conf.py @@ -24,6 +24,11 @@ source_suffix = ['.md', '.rst'] templates_path = ['_templates'] exclude_patterns = [] +# number code-blocks, figures and tables, if they have a caption +numfig = True +# number figures in flat hierarchy +numfig_secnum_depth = 0 + # -- Options for EPUB output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-epub-output @@ -51,8 +56,3 @@ html_theme_options = { # we want to circumvent obscure warnings about footnotes following a heading: # https://github.com/executablebooks/MyST-Parser/issues/352 myst_footnote_transition = False - -# number code-blocks, figures and tables, if they have a caption -numfig = True -# number figures in flat hierarchy -numfig_secnum_depth = 0 From d7d34d49406b31246617a24c0a71cb1202b0028c Mon Sep 17 00:00:00 2001 From: David Runge Date: Fri, 24 Nov 2023 10:52:18 +0100 Subject: [PATCH 48/81] Move MyST-parser configuration to its own section Signed-off-by: David Runge --- book/source/conf.py | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/book/source/conf.py b/book/source/conf.py index 26f49db..63b6dcd 100644 --- a/book/source/conf.py +++ b/book/source/conf.py @@ -29,6 +29,13 @@ numfig = True # number figures in flat hierarchy numfig_secnum_depth = 0 +# -- Options for MyST-parser ------------------------------------------------- +# https://myst-parser.readthedocs.io/en/latest/configuration.html + +# we want to circumvent obscure warnings about footnotes following a heading: +# https://github.com/executablebooks/MyST-Parser/issues/352 +myst_footnote_transition = False + # -- Options for EPUB output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-epub-output @@ -52,7 +59,3 @@ html_theme_options = { 'show_relbars': 'yes', 'show_powered_by': False, } - -# we want to circumvent obscure warnings about footnotes following a heading: -# https://github.com/executablebooks/MyST-Parser/issues/352 -myst_footnote_transition = False From 8f1d939ddbccae92fec333a1efcd5564ad7003ec Mon Sep 17 00:00:00 2001 From: David Runge Date: Fri, 24 Nov 2023 12:00:05 +0100 Subject: [PATCH 49/81] Add make target to check a cleanly built EPUB using epubcheck Signed-off-by: David Runge --- book/Makefile | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/book/Makefile b/book/Makefile index a4c41c9..8e84021 100644 --- a/book/Makefile +++ b/book/Makefile @@ -7,6 +7,7 @@ # You can set these variables from the command line, and also # from the environment for the first two. CODESPELL ?= codespell +EPUBCHECK ?= epubcheck SPHINXOPTS ?= -W SPHINXBUILD ?= sphinx-build LYCHEE ?= lychee @@ -14,6 +15,9 @@ PRINTF ?= printf SOURCEDIR = source BUILDDIR = build +epub-check: clean epub + @$(EPUBCHECK) "$(BUILDDIR)/epub/"*.epub + # Put it first so that "make" without argument is like "make help". help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) From 57f62222d20bfabfab9f987de03df17379400983 Mon Sep 17 00:00:00 2001 From: David Runge Date: Fri, 24 Nov 2023 13:16:46 +0100 Subject: [PATCH 50/81] Add reuse config for patches Signed-off-by: David Runge --- .reuse/dep5 | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.reuse/dep5 b/.reuse/dep5 index bee0e46..6ff7050 100644 --- a/.reuse/dep5 +++ b/.reuse/dep5 @@ -10,3 +10,7 @@ License: CC-BY-SA-4.0 Files: book/source/mermaid/*.png Copyright: 2023 The "Notes on OpenPGP" project License: CC-BY-SA-4.0 + +Files: book/patches/*.patch +Copyright: 2023 The "Notes on OpenPGP" project +License: CC0-1.0 From ccddbe42041f123707a58b719a0fc45abd341576 Mon Sep 17 00:00:00 2001 From: David Runge Date: Fri, 24 Nov 2023 12:01:01 +0100 Subject: [PATCH 51/81] Add local copy of upstreamed sphinx patch for CSS issues with EPUBs The patch fixes https://github.com/sphinx-doc/sphinx/issues/11598 for sphinx >= 7.2.0 Signed-off-by: David Runge --- book/patches/sphinx-11766.patch | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 book/patches/sphinx-11766.patch diff --git a/book/patches/sphinx-11766.patch b/book/patches/sphinx-11766.patch new file mode 100644 index 0000000..c507523 --- /dev/null +++ b/book/patches/sphinx-11766.patch @@ -0,0 +1,26 @@ +diff --git a/sphinx/builders/html/__init__.py b/sphinx/builders/html/__init__.py +index 85067be0178..91d3647597c 100644 +--- a/sphinx/builders/html/__init__.py ++++ b/sphinx/builders/html/__init__.py +@@ -1061,7 +1061,9 @@ def css_tag(css: _CascadingStyleSheet) -> str: + attrs.append(f'{key}="{html.escape(value, quote=True)}"') + uri = pathto(os.fspath(css.filename), resource=True) + if checksum := _file_checksum(outdir, css.filename): +- uri += f'?v={checksum}' ++ # the EPUB format does not allow the use of query components ++ if self.name != 'epub': ++ uri += f'?v={checksum}' + return f'' + + ctx['css_tag'] = css_tag +@@ -1092,7 +1094,9 @@ def js_tag(js: _JavaScript | str) -> str: + # https://github.com/sphinx-doc/sphinx/issues/11658 + pass + elif checksum := _file_checksum(outdir, js.filename): +- uri += f'?v={checksum}' ++ # the EPUB format does not allow the use of query components ++ if self.name != 'epub': ++ uri += f'?v={checksum}' + if attrs: + return f'' + return f'' From eeb1de8ab706af426aeda4ce464f87e5a107aeb1 Mon Sep 17 00:00:00 2001 From: David Runge Date: Fri, 24 Nov 2023 12:02:34 +0100 Subject: [PATCH 52/81] Add woodpecker integration for building and testing the EPUB Signed-off-by: David Runge --- .woodpecker/epub.yml | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 .woodpecker/epub.yml diff --git a/.woodpecker/epub.yml b/.woodpecker/epub.yml new file mode 100644 index 0000000..798fbea --- /dev/null +++ b/.woodpecker/epub.yml @@ -0,0 +1,24 @@ +# SPDX-FileCopyrightText: 2023 The "Notes on OpenPGP" project +# SPDX-License-Identifier: CC0-1.0 + +clone: + git: + image: woodpeckerci/plugin-git + settings: + lfs: false + +when: + branch: draft + event: + - push + - pull_request + +steps: + epub-check: + image: archlinux:latest + commands: + - pacman -Sy --needed --noconfirm archlinux-keyring + - pacman -Syu --needed --noconfirm epubcheck make patch python-myst-parser python-sphinx + # fix sphinx: https://github.com/sphinx-doc/sphinx/issues/11598 + - patch -Np1 -d /usr/lib/python3.11/site-packages/ -i "$(pwd)/book/patches/sphinx-11766.patch" + - make -C book epub-check From 02c7b04cfd2fb58a96777a521f039f42c4ba3ef9 Mon Sep 17 00:00:00 2001 From: David Runge Date: Fri, 24 Nov 2023 12:49:20 +0100 Subject: [PATCH 53/81] Adapt Containerfile to build with a patched version of sphinx Sphinx >= 7.1.0 has issues rendering EPUBs correctly. Install latest sphinx and apply a patch to fix EPUB rendering. Signed-off-by: David Runge --- Dockerfile | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/Dockerfile b/Dockerfile index 3941373..24aadea 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,13 +1,16 @@ # SPDX-FileCopyrightText: 2023 The "Notes on OpenPGP" project # SPDX-License-Identifier: CC0-1.0 -FROM sphinxdoc/sphinx AS build -RUN pip install myst-parser +FROM archlinux:latest AS build COPY book/ /book WORKDIR /book -RUN make html -RUN make epub +# fix EPUB rendering: https://github.com/sphinx-doc/sphinx/issues/11598 +RUN \ + pacman -Sy --needed --noconfirm archlinux-keyring \ + && pacman -Syu --needed --noconfirm epubcheck make patch python-myst-parser python-sphinx \ + && patch -Np1 -d /usr/lib/python3.11/site-packages/ -i /book/patches/sphinx-11766.patch \ + && make epub html FROM scratch COPY --from=build /book/build/html / -COPY --from=build /book/build/epub/OpenPGPforapplicationdevelopers.epub / \ No newline at end of file +COPY --from=build /book/build/epub/OpenPGPforapplicationdevelopers.epub / From 5ce162b7f11465798bfcb7c17e2470c99ec50b11 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sun, 19 Nov 2023 23:15:29 +0100 Subject: [PATCH 54/81] ch5: diagram notes --- book/source/05-private.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/book/source/05-private.md b/book/source/05-private.md index 87c7c11..3917324 100644 --- a/book/source/05-private.md +++ b/book/source/05-private.md @@ -119,6 +119,23 @@ OpenPGP card devices do not store the full OpenPGP certificate. Instead, they ha [^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. +## What a private key store does + +```{admonition} TODO +:class: warning + +write +``` + +```{admonition} VISUAL +:class: warning + +show examples for the operations in a private key store. + +- re-use 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" +- analogous: once we have a visual for the low level asymmetric decryption operation (in ch11), mirror it here +``` + ## Advanced topics ### TSKs: Best practices S2K + S2K migration? From d9ebc637213554cca8f1150ab8fd0b89871510db Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Thu, 23 Nov 2023 23:06:18 +0100 Subject: [PATCH 55/81] ch5: edits --- book/source/05-private.md | 144 ++++++++++++++++++++++++++------------ 1 file changed, 101 insertions(+), 43 deletions(-) diff --git a/book/source/05-private.md b/book/source/05-private.md index 3917324..d8efb31 100644 --- a/book/source/05-private.md +++ b/book/source/05-private.md @@ -6,18 +6,17 @@ 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. 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` +This chapter discusses the handling of private key material in OpenPGP. -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). +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` -## Terms +## Terminology: "Certificates" and "private keys" -In this document, we use the term *OpenPGP certificate* to refer "OpenPGP public keys": The combination of component public keys, identity components and bindings. +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. -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. 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]: +This chapter is about the counterpart to the material in certificates: The corresponding *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]: ```{figure} diag/OpenPGPCert_with_privatekeystore.png :name: fig-openpgp-certificate-with-private-key-store @@ -28,17 +27,13 @@ An OpenPGP certificate, with the associated private key material handled by a ke [^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. 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). +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). -```{admonition} Terminology -:class: note +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). -Transferable secret keys are sometimes colloquially referred to as "OpenPGP private keys". -``` +## Transferable secret key format -## Transferable secret keys - -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. +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. ```{figure} diag/TSK.png :name: fig-transferable-secret-key @@ -47,86 +42,118 @@ Sometimes users handle OpenPGP certificates combined with private key material i 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]. +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. [^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. +```{admonition} Terminology +:class: note + +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. (encrypted_secrets)= -## Protecting private key material with a passphrase (using S2K) +## 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 OpenPGP format, private key material can be optionally protected with a [passphrase](https://en.wikipedia.org/wiki/Passphrase). This mechanism applies symmetric encryption to the private key data in component keys. +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. -The symmetric encryption key is derived from a secret that the user knows (the passphrase). +### Passphrases to symmetric keys (S2K) -Using a passphrase can be useful when a third party can obtain a copy of the OpenPGP key data, but doesn't know the passphrase. In this scenario, an attacker may have obtained a copy of an OpenPGP key, but is unable to use it, because the private key material is encrypted, and the attacker cannot decrypt it. +When protecting private key material in OpenPGP, a symmetric key is derived from the user's passphrase. -OpenPGP defines a mechanism called [string-to-key (S2K)](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-11.html#name-string-to-key-s2k-specifier) that is 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). +For this purpose, OpenPGP defines a mechanism called [string-to-key (S2K)](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-11.html#name-string-to-key-s2k-specifier) that is 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). ```{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. -Transforming a passphrase into a symmetric key +Deriving a symmetric key from a passphrase ``` -The private key material for individual component keys of one certificate can be encrypted with different mechanisms, and/or using different passphrases. +This symmetric key is used to protect the private key material "at rest." That is, while it is stored on-disk. To use a passphrase-protected OpenPGP private key, it is decrypted using the symmetric key, and then used for a set of private key operations. -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 +#### S2K mechanisms for symmetric key generation Over time, OpenPGP has specified a series of [S2K mechanisms](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-11.html#name-string-to-key-s2k-types-reg), following the current state of the art. Of the specified S2K mechanisms, two remain relevant today: - [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), which was newly added in OpenPGP version 6, and additionally protects the passphrase against brute-force attacks because it is memory-hard (which reduces the efficiency of attacks with specialised hardware) -### Mechanisms for secret key encryption with S2K +### Encryption of private key material with a symmetric key -Different mechanisms are specified [for the encryption of the secret key data](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-secret-key-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. +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 + +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. + +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 are internally encrypted in one monolithic operation, necessarily using only one 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. ## Private key operations The core of private key operations doesn't require access to the whole certificate. +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. + +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. + +### Key store design options + 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). +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 also require 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). +3. Keeping a copy of full TSKs in the private key subsystem, and using those for private key operations. -Either way: at most, a private key subsystem should need access to individual component keys and the associated private key material. +Either way: An OpenPGP private key subsystem performs operations that only require the private cryptographic key material. + +An independent concern is how key material is selected, when using the keystore. The fingerprint of the component key is an obvious option. This requirement can be solved by design 2, which allows calculation of component key fingerprints. ```{note} +Design 3, which involves keeping a copy of full TSKs in the private key subsystem can cause "split brain" problems. -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. +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]. -(Thunderbird users currently suffer from such issues, I think) +This class of problem existed in GnuPG 1.x, which held separate copies of full TSKs in its private store component. ``` +[^tb-split]: The current design of Thunderbird's OpenPGP subsystem can lead to users experiencing such issues. + ### 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. 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: +Effectively, the OpenPGP card specification outlines one model for an OpenPGP private key store 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). +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. -## What a private key store does +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. -```{admonition} TODO -:class: warning - -write +```{note} +The ECDH mechanism for decryption on an OpenPGP card produces the "shared secret". The unwrapping step happens in software, outside the card. ``` +## Details about the operation of an OpenPGP key store + ```{admonition} VISUAL :class: warning @@ -136,6 +163,37 @@ show examples for the operations in a private key store. - analogous: once we have a visual for the low level asymmetric decryption operation (in ch11), mirror it here ``` +### Signing + +```{admonition} TODO +:class: warning + +write +``` + +### Decryption + +```{admonition} TODO +:class: warning + +write +``` + +```{note} +Decryption with ECC algorithms, using ECDH, is a multi-step procedure. Only one of these steps is handled by the card. + +The ECDH mechanism on the card produces a "shared secret" in compliance with the Elliptic Curve Key Agreement Scheme from Diffie-Hellman. Further processing (such as the key derivation function) happens in software. + + + +ECDH: Key Wrap Algorithm (RFC 3394) + + + +- [Decrypt unwrap in Sequoias ecdh.rs](https://gitlab.com/sequoia-pgp/sequoia/-/blob/main/openpgp/src/crypto/ecdh.rs?ref_type=heads#L120) should be a good place to start +``` + + ## Advanced topics ### TSKs: Best practices S2K + S2K migration? From 9e233cc011387a8756e3912867145ee7dfb839ed Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Fri, 24 Nov 2023 20:12:14 +0100 Subject: [PATCH 56/81] ch5: edits --- book/source/05-private.md | 177 ++++++++++++++++++++++---------------- 1 file changed, 105 insertions(+), 72 deletions(-) diff --git a/book/source/05-private.md b/book/source/05-private.md index d8efb31..5c63c2f 100644 --- a/book/source/05-private.md +++ b/book/source/05-private.md @@ -12,9 +12,9 @@ Private key material is associated with component keys that are parts of [OpenPG ## Terminology: "Certificates" and "private keys" -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. +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`). -This chapter is about the counterpart to the material in certificates: The corresponding *private key material* of component keys. +This chapter is about the remaining counterpart to the elements of certificates: The corresponding *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]: @@ -22,15 +22,13 @@ In this book, we treat the private key material as logically separate from the O :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. -An OpenPGP certificate, with the associated private key material handled by a key store subsystem. +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. 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). -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). - ## 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. @@ -52,7 +50,7 @@ The TSK format can be useful for backups of OpenPGP key material, or to move a k 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. +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`. (encrypted_secrets)= ## Protection of private key material in OpenPGP @@ -61,11 +59,11 @@ In OpenPGP format, private key material can optionally be protected with a [pass 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. -### Passphrases to symmetric keys (S2K) +### Transforming a passphrase into a symmetric key -When protecting private key material in OpenPGP, a symmetric key is derived from the user's passphrase. +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. -For this purpose, OpenPGP defines a mechanism called [string-to-key (S2K)](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-11.html#name-string-to-key-s2k-specifier) that is 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). +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). ```{figure} diag/passphrase_using_S2K.png :name: fig-passphrase-using-s2k @@ -74,19 +72,25 @@ For this purpose, OpenPGP defines a mechanism called [string-to-key (S2K)](https Deriving a symmetric key from a passphrase ``` -This symmetric key is used to protect the private key material "at rest." That is, while it is stored on-disk. To use a passphrase-protected OpenPGP private key, it is decrypted using the symmetric key, and then used for a set of private key operations. +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. -#### S2K mechanisms for symmetric key generation +#### Mechanisms for symmetric key generation -Over time, OpenPGP has specified a series of [S2K mechanisms](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-11.html#name-string-to-key-s2k-types-reg), following the current state of the art. Of the specified S2K mechanisms, two remain relevant today: +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: -- [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), which was newly added in OpenPGP version 6, and additionally protects the passphrase against brute-force attacks because it is memory-hard (which reduces the efficiency of attacks with specialised hardware) +- [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. -### Encryption of private key material with a symmetric key +A third mechanism is allowed conditionally for generation. Decryption of private keys that use obsolete mechanisms is 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." + +### 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 RFC refers to the mechanism that is used to *apply* the symmetric key with the term "String-to-Key Usage (S2K usage)". + 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 @@ -97,46 +101,18 @@ The OpenPGP mechanism for protecting private key material applies individually t - using different passphrases. - Individual component keys may be stored in unprotected form, while others are protected. -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 are internally encrypted in one monolithic operation, necessarily using only one passphrase. +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. 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. -## Private key operations +(card-priv)= +## OpenPGP card for private keys -The core of private key operations doesn't require access to the whole certificate. +[OpenPGP card](https://en.wikipedia.org/wiki/OpenPGP_card) devices are a type of hardware security device. -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. +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. -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. - -### Key store design options - -Designs of private key subsystems in the OpenPGP space differ: - -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 also require 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). -3. Keeping a copy of full TSKs in the private key subsystem, and using those for private key operations. - -Either way: An OpenPGP private key subsystem performs operations that only require the private cryptographic key material. - -An independent concern is how key material is selected, when using the keystore. The fingerprint of the component key is an obvious option. This requirement can be solved by design 2, which allows calculation of component key fingerprints. - -```{note} -Design 3, which involves keeping a copy 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]. - -This class of problem existed in GnuPG 1.x, which held separate copies of full TSKs in its private store component. -``` - -[^tb-split]: The current design of Thunderbird's OpenPGP subsystem can lead to users experiencing such issues. - -### 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. +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 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). @@ -148,11 +124,78 @@ OpenPGP card devices do not store a full OpenPGP certificate. Instead, they have 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. +## 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. + +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. + +(key-store-design)= +## Private key stores + +### Design options + +Designs of private key subsystems in the OpenPGP space differ: + +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. + +Private key store operations require component keys, but do not require access to the rest of the certificate. + ```{note} -The ECDH mechanism for decryption on an OpenPGP card produces the "shared secret". The unwrapping step happens in software, outside the card. +Design 3, which involves keeping a copy 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]. + +This class of problem existed in GnuPG 1.x, which held separate copies of full TSKs in its private store component. ``` -## Details about the operation of an OpenPGP key store +[^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. + +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: + +- 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). + +```{note} +Decryption with ECC algorithms using ECDH in particular is a multi-step procedure. + +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). +``` + +### Addressing individual keys + +An independent design question is how key material is adressed, by users of the keystore. + +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. + +### 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. + +### Visualizing key store operations + +#### Signing + +```{admonition} TODO +:class: warning + +write +``` ```{admonition} VISUAL :class: warning @@ -160,10 +203,9 @@ The ECDH mechanism for decryption on an OpenPGP card produces the "shared secret show examples for the operations in a private key store. - re-use 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" -- analogous: once we have a visual for the low level asymmetric decryption operation (in ch11), mirror it here ``` -### Signing +#### Decryption ```{admonition} TODO :class: warning @@ -171,33 +213,24 @@ show examples for the operations in a private key store. write ``` -### Decryption - -```{admonition} TODO +```{admonition} VISUAL :class: warning -write +show examples for the operations in a private key store. + +- once we have a visual for the low level asymmetric decryption operation (in ch11), mirror it here ``` -```{note} -Decryption with ECC algorithms, using ECDH, is a multi-step procedure. Only one of these steps is handled by the card. - -The ECDH mechanism on the card produces a "shared secret" in compliance with the Elliptic Curve Key Agreement Scheme from Diffie-Hellman. Further processing (such as the key derivation function) happens in software. - - - -ECDH: Key Wrap Algorithm (RFC 3394) - - - -- [Decrypt unwrap in Sequoias ecdh.rs](https://gitlab.com/sequoia-pgp/sequoia/-/blob/main/openpgp/src/crypto/ecdh.rs?ref_type=heads#L120) should be a good place to start -``` - - ## Advanced topics ### TSKs: Best practices S2K + S2K migration? +```{admonition} TODO +:class: warning + +write +``` + ### The KOpenPGP attack See [https://www.kopenpgp.com/](https://www.kopenpgp.com/) From 10ce55fa77151e58b41d6c3c3eb5d1c558419425 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Sat, 25 Nov 2023 11:51:59 +0100 Subject: [PATCH 57/81] edits to #999549dcc3 --- book/source/04-certificates.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 4f0e559..f9e7ba6 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -143,13 +143,13 @@ For further conventions on User IDs, refer to the document [draft-dkg-openpgp-us **Split User IDs** -One proposed variant for encoding identities in User ID is to use ["split User IDs"](https://dkg.fifthhorseman.net/blog/2021-dkg-openpgp-transition.html#split-user-ids). This style of User IDs is currently uncommon, but there is no strong technical impediment to using this format right now[^dkg-split]. +One proposed variant for encoding identities in User IDs is to use ["split User IDs"](https://dkg.fifthhorseman.net/blog/2021-dkg-openpgp-transition.html#split-user-ids). Although currently uncommon, there are currently no significant technical barriers to implementing this format[^dkg-split]. -[^dkg-split]: Note that in the past, there were stumbling blocks in the OpenPGP ecosystem, see ["What were Separated User IDs"](https://dkg.fifthhorseman.net/blog/2019-dkg-openpgp-transition.html#what-were-separated-user-ids) from January 2019, by Daniel Kahn Gillmor. +[^dkg-split]: Historically, the OpenPGP ecosystem faced challenges in this context. For further details, refer to Daniel Kahn Gillmor's January 2019 article, ["What were Separated User IDs"](https://dkg.fifthhorseman.net/blog/2019-dkg-openpgp-transition.html#what-were-separated-user-ids). -An argument for split User IDs is that a name and an email address are two distinct identities, which are easier to reason about separately. This is particularly relevant when third parties consider certifying that an identity is legitimately connected to a certificate. +The rationale for split User IDs lies in the distinction between a name and an email address, which represent two separate facets of an individual's identity. Separating these elements simplifies the process for third parties tasked with certifying that an identity is legitimately connected to a certificate. -For example, some third party may be sure about the email identity of a contact, and happy to issue a certification for an email-based identity (such as ``). But they may not have any insight into a name-based identity (such as `Alice Adams`), and thus not willing to certify such a name-based identity. +Consider this scenario: A third party is confident about the email-based identity of an individual (e.g.,``) and is willing to certify it. However, they might not have sufficient knowledge about the person's name-based identity (e.g., `Alice Adams`), so are unwilling to extend the same level of certification. Split User IDs address this dichotomy by allowing distinct certification processes for each type of identity. (primary_user_id)= ### Implications of the Primary User ID From 50bdb0b72e6d4a6297475437179b8cb41792a1a8 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Sat, 25 Nov 2023 11:51:59 +0100 Subject: [PATCH 58/81] edits to commit 999549dcc391704e39d4682fc335c2118072343e --- book/source/04-certificates.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 4f0e559..f9e7ba6 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -143,13 +143,13 @@ For further conventions on User IDs, refer to the document [draft-dkg-openpgp-us **Split User IDs** -One proposed variant for encoding identities in User ID is to use ["split User IDs"](https://dkg.fifthhorseman.net/blog/2021-dkg-openpgp-transition.html#split-user-ids). This style of User IDs is currently uncommon, but there is no strong technical impediment to using this format right now[^dkg-split]. +One proposed variant for encoding identities in User IDs is to use ["split User IDs"](https://dkg.fifthhorseman.net/blog/2021-dkg-openpgp-transition.html#split-user-ids). Although currently uncommon, there are currently no significant technical barriers to implementing this format[^dkg-split]. -[^dkg-split]: Note that in the past, there were stumbling blocks in the OpenPGP ecosystem, see ["What were Separated User IDs"](https://dkg.fifthhorseman.net/blog/2019-dkg-openpgp-transition.html#what-were-separated-user-ids) from January 2019, by Daniel Kahn Gillmor. +[^dkg-split]: Historically, the OpenPGP ecosystem faced challenges in this context. For further details, refer to Daniel Kahn Gillmor's January 2019 article, ["What were Separated User IDs"](https://dkg.fifthhorseman.net/blog/2019-dkg-openpgp-transition.html#what-were-separated-user-ids). -An argument for split User IDs is that a name and an email address are two distinct identities, which are easier to reason about separately. This is particularly relevant when third parties consider certifying that an identity is legitimately connected to a certificate. +The rationale for split User IDs lies in the distinction between a name and an email address, which represent two separate facets of an individual's identity. Separating these elements simplifies the process for third parties tasked with certifying that an identity is legitimately connected to a certificate. -For example, some third party may be sure about the email identity of a contact, and happy to issue a certification for an email-based identity (such as ``). But they may not have any insight into a name-based identity (such as `Alice Adams`), and thus not willing to certify such a name-based identity. +Consider this scenario: A third party is confident about the email-based identity of an individual (e.g.,``) and is willing to certify it. However, they might not have sufficient knowledge about the person's name-based identity (e.g., `Alice Adams`), so are unwilling to extend the same level of certification. Split User IDs address this dichotomy by allowing distinct certification processes for each type of identity. (primary_user_id)= ### Implications of the Primary User ID From 6ada412e740ee2492b34a60a8e23d871148770ff Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Sat, 25 Nov 2023 13:42:41 +0100 Subject: [PATCH 59/81] clarify auth-flag of commit c6888559f5598a64eb2095f56c84169a9e731d6f --- book/source/04-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index f9e7ba6..d7de02b 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -204,7 +204,7 @@ Commonly used key flags include: - **Encryption**: allows the key to encrypt data - **Authentication**: primarily used for SSH authentication[^auth-flag] -[^auth-flag]: Note that the capability offered by the [authentication](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-authentication-via-digital-) key flag is unrelated to "authentication" in the context of certifying and verifying OpenPGP identities and their connection to certificates. This key flag is about a mechanism that proves control of private key material to a remote system, using cryptographic signatures. +[^auth-flag]: It's important to note that the function of the [authentication](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-authentication-via-digital-) key flag is unrelated to the authentication process used in certifying OpenPGP identities and linking them to certificates. Rather, this flag indicates a mechanism that uses cryptographic signatures to confirm control of private key material with a remote system. ```{note} Distinct component keys handle specific operations. Only the primary key can be used for certification, although it can have additional capabilities. Subkeys can be used for signing, encryption, and authentication but cannot have the certification capability. A component key can technically have multiple capabilities. It is considered good practice, however, to [use separate keys for each capability](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#section-10.1.5-7). From a914e60fa3f33e7d1564c118b1f0256f2132b5fe Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Sat, 25 Nov 2023 13:59:35 +0100 Subject: [PATCH 60/81] edit metadata capabilities of commit c6888559f5598a64eb2095f56c84169a9e731d6f --- book/source/04-certificates.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index d7de02b..119b790 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -177,21 +177,19 @@ In very abstract terms, the primary key of a certificate acts as a root of trust By binding components using digital signatures, recipients of an OpenPGP certificate need only validate the authenticity of the primary key to use for their communication partner. Traditionally, this is done by manually verifying the *fingerprint* of the primary key. Once the validity of the primary key is confirmed, the validity of the remaining components can be automatically assessed by the user's OpenPGP software. Generally, components are valid parts of a certificate if there is a statement signed by the certificate's primary key endorsing this validity. -## Metadata: capabilities, preferences, etc +## Metadata capabilities, preferences, and storage -Much of the metadata for OpenPGP certificates, component keys, and identities, is not actually stored as part of the components that the metadata applies to. +OpenPGP certificates, their component keys, and identities possess metadata that is not stored within the components it pertains to. Instead, this metadata is stored within signature packets, which are integral to the structure of an OpenPGP certificate. -For example, the capabilities of a component key, such as *signing* or *encryption*, as well as its expiration time, are not stored as a part of the data of that component key. +Key attributes, such as capabilities (like *signing* or *encryption*) and expiration times, are examples of metadata not stored in the component key data. How this metadata is stored depends on the component: -Instead, this kind of metadata is stored as part of the signature packets that join components into an OpenPGP certificate: +- **Primary key metadata** is defined either through a direct key signature on the primary key (preferred in OpenPGP version 6), or by associating the metadata with the [Primary User ID](primary_user_id). -- For the primary key, its key flags and other metadata can be defined in two ways: - - With a [direct key signature](direct_key_signature) on the primary key (preferred method in OpenPGP version 6), - - or by associating the metadata with the [Primary User ID](primary_user_id). -- For subkeys, metadata is defined with the [subkey binding signature](binding_subkeys) that links the subkey to the certificate. -- For identity components like User IDs, metadata is associated via the [certifying self-signature](bind_ident) that links the identity to the certificate. +- **Subkey metadata** is defined within the [subkey binding signature](binding_subkeys) that links the subkey to the certificate. -Note that the components of an OpenPGP certificate are themselves never changed, after their initial creation. By storing associated metadata in signatures, it can be modified at a later point in time by issuing a new signature that replaces the previous one. For example, the certificate holder can change the expiration time of a component of their certificate by issuing a new signature. +- **User ID metadata** is is associated via the [certifying self-signature](bind_ident) that links the identity to the certificate. + +It is crucial to note that the components of an OpenPGP certificate remain static after their creation. The use of signatures to store metadata allows for subsequent modifications without altering the original components. For instance, a certificate holder can update the expiration time of a component by issuing a new, superseding signature. ### Defining operational capabilities of component keys with key flags From d49cf0b7130664890693f7f1edb1320fad8fbca0 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Sat, 25 Nov 2023 14:12:09 +0100 Subject: [PATCH 61/81] Edit commit 6f609c7f88cf0d523112fcf6fbc496db4e5cf871 --- book/source/04-certificates.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 119b790..ce1a88f 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -214,19 +214,21 @@ Notably, in many algorithms, encryption and signing-related functionalities (i.e ### Algorithm preferences and feature signaling -OpenPGP has a lot of ["cryptographic agility"](https://en.wikipedia.org/wiki/Cryptographic_agility). That is, OpenPGP doesn't just use one fixed set of algorithms, but defines a suite of cryptographic primitives that users (or their applications) can pick from. +OpenPGP demonstrates significant ["cryptographic agility"](https://en.wikipedia.org/wiki/Cryptographic_agility). It doesn't rely on a single fixed set of algorithms. Instead, it defines a suite of cryptographic primitives from which users (or their applications) can choose. -This agility has the advantage that adoption of new cryptographic primitives into the standard is relatively easy, and can be done without disruption. Users can gradually migrate to using new cryptographic mechanisms. +This agility facilitates the easy adoption of new cryptographic primitives into the standard, allowing for a seamless transition. Users can gradually migrate to new cryptographic mechanisms without disruption. -However, it also means that OpenPGP software needs to figure out which mechanisms a set of communication partners can handle and prefer. To do this, there are a number of mechanisms in OpenPGP that can be negotiated between sender and recipient. Note that OpenPGP is not an online scheme, so this negotiation is effectively one-way: The active party interprets the preferences that are expressed in the certificate of the passive party. +However, this approach requires that OpenPGP software determine the cryptographic mechanisms that a set of communication partners can handle and prefer. OpenPGP employs several mechanisms for this purpose, which allow negotiation between sender and recipient. It's important to note that OpenPGP is not an online scheme; thus, this negotiation is effectively one-way. The active party interprets the preferences expressed in the certificate of the passive party. -- [Preferred Hash Algorithms](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-hashes-subpacket) -- [Preferred Symmetric Ciphers for v1 SEIPD](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-v1-seipd) -- [Preferred AEAD Ciphersuites](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-v2-seipd) -- [Features](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#features-subpacket) -- [Preferred Compression Algorithms](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-compression-subpacket) +Key negotiation mechanisms in OpenPGP include: -In addition to these explicitly expressed preferences, implementations also deduce capabilities of communication partners based on the OpenPGP version of the certificate that they write to. +- [Preferred hash algorithms](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-hashes-subpacket) +- [Preferred symmetric ciphers for v1 SEIPD](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-v1-seipd) +- [Preferred AEAD ciphersuites](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-v2-seipd) +- [Features subpacket](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#features-subpacket) +- [Preferred compression algorithms](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-compression-subpacket) + +Beyond these explicitly expressed preferences, implementations also deduce capabilities of communication partners based on the version of the OpenPGP certificate they possess. #### User ID-specific preferences From a9c8e138feb13097ea39906ac32051a1b0e7c6d0 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 25 Nov 2023 14:19:37 +0100 Subject: [PATCH 62/81] add "cert-flooding" link anchor --- book/source/04-certificates.md | 1 + 1 file changed, 1 insertion(+) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 254afc9..ae03ec1 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -224,6 +224,7 @@ This section needs to be written Third-party identity certifications have historically played a pivotal role in the OpenPGP ecosystem. +(cert-flooding)= ### Security considerations While a convenience for consumers, indiscriminately accepting and integrating third-party identity certifications comes with significant risks. From 018a6107c1e3d76a9a969640d65ab42710fc3bfa Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Sat, 25 Nov 2023 15:33:34 +0100 Subject: [PATCH 63/81] edit to commit 441936eb98 --- book/source/04-certificates.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index ce1a88f..ff98e44 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -238,11 +238,11 @@ Additionally, OpenPGP allows modeling User ID-specific preferences. The idea is ## Revocations -When the owner of a certificate wants to invalidate some components of that certificate, or the entire certificate, they can do so by "revoking" the component in question. Revoking the primary key renders the entire certificate invalid. +When a certificate owner needs to invalidate certain components of their certificate, or even the entire certificate, they accomplish this through "revocation." Revoking the primary key renders the entire certificate invalid. -More on revoking components of a certificate in {ref}`self-revocations`. +Notably, revocations are not the only means by which components can become invalid. Other factors, such as the passing of a component's expiration time, can also render components invalid. -Note that there are other ways besides revocations in which components can become invalid. For example, the component's expiration time may have passed. +For more detailed information on revoking specific components of a certificate, see the section on {ref}`self-revocations`. ## Third-party (identity) certifications From 7cb536008bf50d5998162c2181327af0d624a7ba Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Sat, 25 Nov 2023 16:03:52 +0100 Subject: [PATCH 64/81] edit commit 451b881c03 --- book/source/04-certificates.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index ff98e44..c4b0d55 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -246,13 +246,15 @@ For more detailed information on revoking specific components of a certificate, ## Third-party (identity) certifications -Third-party identity certifications have been a pivotal mechanism in the OpenPGP ecosystem since the beginning. The designers of PGP, beginning with Phil Zimmermann, have favored decentralized trust models, which don't hinge on centralized authorities. OpenPGP's decentralized trust model is called the ["Web of Trust."](wot) +Since its inception, third-party identity certifications have been a cornerstone of the OpenPGP ecosystem. The original PGP designers, starting with Phil Zimmermann, advocated for decentralized trust models over reliance on centralized authorities. This decentralized approach in OpenPGP is known as the ["Web of Trust."](wot) -Third-party certifications are statements by OpenPGP users who attest that they have confirmed that a particular OpenPGP certificate belongs to a user with a particular identity. +Third-party certifications are statements by OpenPGP users confirming that a user with a specific identity is the owner of a particular OpenPGP certificate. For example, Bob's OpenPGP software may issue a certification that Bob has checked that the User ID `Alice Adams ` and the certificate with the fingerprint `AAA1 8CBB 2546 85C5 8358 3205 63FD 37B6 7F33 00F9 FB0E C457 378C D29F 1026 98B3` are legitimately linked. -This presupposes that Bob knows this person who goes by "Alice Adams," and is satisfied that Alice uses the email address `alice@example.org`. Further, that Bob has verified that the certificate his OpenPGP software uses for Alice matches the certificate that Alice is using. Effectively, this verification must ensure that both users have a certificate for Alice with the same fingerprint. In OpenPGP version 6, manual comparison of the fingerprint by end users is discouraged. A replacement mechanism is still pending. The verification must use a sufficiently secure channel, for example, an end-to-end encrypted video call, or an in-person meeting. +Take, for instance, a scenario where Bob's OpenPGP software issues a certification confirming as legitimate the link between the User ID `Alice Adams ` and the certificate bearing the fingerprint `AAA1 8CBB 2546 85C5 8358 3205 63FD 37B6 7F33 00F9 FB0E C457 378C D29F 1026 98B3`. + +This process assumes that Bob knows the person known as `Alice Adams` and is confident that `alice@example.org` is indeed Alice's email address. Bob also verifies that the certificate his OpenPGP software associates with Alice matches the one Alice uses. In essence, both users must have a certificate for Alice with an identical fingerprint. In OpenPGP version 6, manual fingerprint comparison by end-users is discouraged, with a replacement verification mechanism still under development. The verification process must occur over a sufficiently secure channel, such as an end-to-end encrypted video call or a face-to-face meeting. For more on third-party certifications, see {ref}`third_party_cert`. From f0e5c00803997df829ed4a26dd31fca7ce67c3de Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Sat, 25 Nov 2023 16:17:31 +0100 Subject: [PATCH 65/81] reorganize and structure content to answer commit 992c878fea --- book/source/04-certificates.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index c4b0d55..a6219b5 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -28,7 +28,13 @@ In OpenPGP, the term "key" may refer to three distinct layers, each serving a un The following section will delve into the OpenPGP-specific layers (2 and 3) to provide a clearer understanding of their roles within OpenPGP certificates. -For a discussion of private key material in OpenPGP, see the chapter {ref}`private_key_chapter`. Bindings that connect the components of a certificate are discussed in our chapter {ref}`component_signatures_chapter`. For much more detail on the internal (packet) structure of certificates and keys refer to our chapter {ref}`zoom_certificates`. Additionally, managing certificates, and understanding their authentication and trust models are vital topics. While this document only touches upon these aspects briefly, they are integral to working proficiently with OpenPGP. +Fundamentally, the effective management of certificates and a thorough grasp of their authentication and trust models are crucial for proficient OpenPGP usage. Although this document offers just a brief overview of these aspects, they form a fundamental part of the broader OpenPGP framework and warrant further study. + +– For an in-depth exploration of OpenPGP's private key material, refer to {ref}`private_key_chapter`. This chapter provides essential insights into key management and security practices. + +– The bindings that unify the components of a certificate are comprehensively discussed in {ref}`component_signatures_chapter`, offering a deeper understanding of certificate structure and integrity. + +– For a detailed analysis of the internal (packet) structure of certificates and keys, our chapter {ref}`zoom_certificates` can serve as an invaluable resource. ## Structure of OpenPGP certificates From 4a2595c5f71ee1c72ef58bfd779b8efe2158ab70 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Sat, 25 Nov 2023 16:24:09 +0100 Subject: [PATCH 66/81] remove comma in commit e0457bac64 --- book/source/04-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index a6219b5..9550e3e 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -170,7 +170,7 @@ The primary User ID was historically the main store for preferences that apply t While [user attributes](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-user-attribute-packet-tag-1) are similar to User IDs, they are less commonly used. -Currently, the OpenPGP standard prescribes only one format to be stored in user attributes: an [image](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-the-image-attribute-subpack), in JPEG format. Typically, this image represents the key owner, although it is not required. +Currently, the OpenPGP standard prescribes only one format to be stored in user attributes: an [image](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-the-image-attribute-subpack) in JPEG format. Typically, this image represents the key owner, although it is not required. ## Linking the components From 8c8cf2ed50f6d546462e5a8c61d9c99c4ac8a843 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Sat, 25 Nov 2023 16:30:54 +0100 Subject: [PATCH 67/81] edit commit 02b0785584 on the not-exactly-unique fingerprint --- book/source/04-certificates.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 9550e3e..0e0fcc0 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -96,9 +96,7 @@ For example, an OpenPGP version 4 certificate with the fingerprint `B3D2 7B09 FB Historically, even shorter 32-bit identifiers were used, like this: `2455 4239`, or `0x24554239`. Such identifiers still appear in very old documents about PGP. However, [32-bit identifiers have been long deemed unfit for purpose](https://evil32.com/). At one point, 32-bit identifiers were called "short Key ID," while 64-bit identifiers were referred to as "long Key ID." ```{note} -In practice, the fingerprint of a component key is used like a unique identifier. - -However, formally, a fingerprint is not unique. For every component key, other component keys with the same fingerprint exist, in theory. But because fingerprints are calculated using a [cryptographic hash algorithm](crypto-hash), it is practically impossible to find two different component keys that have the same fingerprint. +In practice, the fingerprint of a component key, while not theoretically unique, functions effectively as a unique identifier. The use of a [cryptographic hash algorithm](crypto-hash) in generating fingerprints makes the occurrence of two different component keys with the same fingerprint extremely unlikely. ``` ### Primary key From 3b0dfd5cd76b5c4cd5b4c2ebeb693aa511cff909 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 25 Nov 2023 18:14:45 +0100 Subject: [PATCH 68/81] move contextualization paragraphs up to the first block --- book/source/04-certificates.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 0e0fcc0..17451ee 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -10,6 +10,14 @@ OpenPGP fundamentally hinges on the concept of "OpenPGP certificates," also know An OpenPGP certificate, by definition, does not contain private key material. +Fundamentally, the effective management of certificates and a thorough grasp of their authentication and trust models are crucial for proficient OpenPGP usage. Although this document offers just a brief overview of these aspects, they form a fundamental part of the broader OpenPGP framework and warrant further study. + +- For an in-depth exploration of OpenPGP's private key material, refer to {ref}`private_key_chapter`. This chapter provides essential insights into private key management and security practices. + +- The bindings that link the components of a certificate are comprehensively discussed in {ref}`component_signatures_chapter`, offering a deeper understanding of certificate structure and integrity. + +- For a detailed analysis of the internal (packet) structure of certificates and keys, our chapter {ref}`zoom_certificates` can serve as an invaluable resource. + ## Terminology: Understanding "keys" The term "(cryptographic) keys" is central to grasping the concept of OpenPGP certificates. However, it can refer to different entities, making it a potentially confusing term. Let's clarify those differences. @@ -28,14 +36,6 @@ In OpenPGP, the term "key" may refer to three distinct layers, each serving a un The following section will delve into the OpenPGP-specific layers (2 and 3) to provide a clearer understanding of their roles within OpenPGP certificates. -Fundamentally, the effective management of certificates and a thorough grasp of their authentication and trust models are crucial for proficient OpenPGP usage. Although this document offers just a brief overview of these aspects, they form a fundamental part of the broader OpenPGP framework and warrant further study. - -– For an in-depth exploration of OpenPGP's private key material, refer to {ref}`private_key_chapter`. This chapter provides essential insights into key management and security practices. - -– The bindings that unify the components of a certificate are comprehensively discussed in {ref}`component_signatures_chapter`, offering a deeper understanding of certificate structure and integrity. - -– For a detailed analysis of the internal (packet) structure of certificates and keys, our chapter {ref}`zoom_certificates` can serve as an invaluable resource. - ## Structure of OpenPGP certificates An OpenPGP certificate (or "OpenPGP key") is a collection of an arbitrary number of elements[^packets]: From a4318538326607078aee0d296e00cbaebedcb097 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 25 Nov 2023 18:24:36 +0100 Subject: [PATCH 69/81] zoom_certificates doesn't talk about private keys (anymore). de-emphasize the packet-level chapter (it's still very unclear to me how many readers should look at those chapters). --- book/source/04-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 17451ee..7359147 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -16,7 +16,7 @@ Fundamentally, the effective management of certificates and a thorough grasp of - The bindings that link the components of a certificate are comprehensively discussed in {ref}`component_signatures_chapter`, offering a deeper understanding of certificate structure and integrity. -- For a detailed analysis of the internal (packet) structure of certificates and keys, our chapter {ref}`zoom_certificates` can serve as an invaluable resource. +- Finally, our chapter {ref}`zoom_certificates` discusses the internal structure of certificates in detail. ## Terminology: Understanding "keys" From 111f6cca41dbd39520576986d14ad3b59e274c90 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 25 Nov 2023 18:38:30 +0100 Subject: [PATCH 70/81] attempt at footnote with more detail on fingerprint uniqueness. the exact content might need more tweaking. --- book/source/04-certificates.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 7359147..05901dc 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -96,9 +96,11 @@ For example, an OpenPGP version 4 certificate with the fingerprint `B3D2 7B09 FB Historically, even shorter 32-bit identifiers were used, like this: `2455 4239`, or `0x24554239`. Such identifiers still appear in very old documents about PGP. However, [32-bit identifiers have been long deemed unfit for purpose](https://evil32.com/). At one point, 32-bit identifiers were called "short Key ID," while 64-bit identifiers were referred to as "long Key ID." ```{note} -In practice, the fingerprint of a component key, while not theoretically unique, functions effectively as a unique identifier. The use of a [cryptographic hash algorithm](crypto-hash) in generating fingerprints makes the occurrence of two different component keys with the same fingerprint extremely unlikely. +In practice, the fingerprint of a component key, while not theoretically unique, functions effectively as a unique identifier. The use of a [cryptographic hash algorithm](crypto-hash) in generating fingerprints makes the occurrence of two different component keys with the same fingerprint extremely unlikely[^finger-unique]. ``` +[^finger-unique]: For both OpenPGP version 6 and version 4, the likelihood of accidental occurrence of duplicate fingerprints is negligible when key material is generated based on an acceptable source of entropy. A separate question is if an attacker can purposely craft a second key with the same fingerprint as a given pre-existing component key. With the current state of the art, this is not possible for OpenPGP version 6 and version 4 keys. However, at the time of this writing, the SHA-1-based fingerprints of OpenPGP version 4 are considered insufficiently strong at protecting against the generation of pairs of key material with the same fingerprint. + ### Primary key The OpenPGP primary key is a component key that serves a distinct, central role in an OpenPGP certificate: From 4635d15ecec394571ffb984e2273028dea242184 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 25 Nov 2023 18:41:35 +0100 Subject: [PATCH 71/81] drop duplication --- book/source/04-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 05901dc..45e5d77 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -149,7 +149,7 @@ For further conventions on User IDs, refer to the document [draft-dkg-openpgp-us **Split User IDs** -One proposed variant for encoding identities in User IDs is to use ["split User IDs"](https://dkg.fifthhorseman.net/blog/2021-dkg-openpgp-transition.html#split-user-ids). Although currently uncommon, there are currently no significant technical barriers to implementing this format[^dkg-split]. +One proposed variant for encoding identities in User IDs is to use ["split User IDs"](https://dkg.fifthhorseman.net/blog/2021-dkg-openpgp-transition.html#split-user-ids). Although uncommon, there are currently no significant technical barriers to implementing this format[^dkg-split]. [^dkg-split]: Historically, the OpenPGP ecosystem faced challenges in this context. For further details, refer to Daniel Kahn Gillmor's January 2019 article, ["What were Separated User IDs"](https://dkg.fifthhorseman.net/blog/2019-dkg-openpgp-transition.html#what-were-separated-user-ids). From ee1e9d539618cfda0a26ff206fc6e269d5f76002 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 25 Nov 2023 19:20:00 +0100 Subject: [PATCH 72/81] simplify/clarify section title --- book/source/04-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 45e5d77..30f81b9 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -183,7 +183,7 @@ In very abstract terms, the primary key of a certificate acts as a root of trust By binding components using digital signatures, recipients of an OpenPGP certificate need only validate the authenticity of the primary key to use for their communication partner. Traditionally, this is done by manually verifying the *fingerprint* of the primary key. Once the validity of the primary key is confirmed, the validity of the remaining components can be automatically assessed by the user's OpenPGP software. Generally, components are valid parts of a certificate if there is a statement signed by the certificate's primary key endorsing this validity. -## Metadata capabilities, preferences, and storage +## Metadata in certificates OpenPGP certificates, their component keys, and identities possess metadata that is not stored within the components it pertains to. Instead, this metadata is stored within signature packets, which are integral to the structure of an OpenPGP certificate. From 0a2bccb380cd82c88a3e0d0a0a87fa6e75ae181a Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 25 Nov 2023 19:20:42 +0100 Subject: [PATCH 73/81] generalize: User Attributes are uncommon, but we should include them --- book/source/04-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 30f81b9..db334e6 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -193,7 +193,7 @@ Key attributes, such as capabilities (like *signing* or *encryption*) and expira - **Subkey metadata** is defined within the [subkey binding signature](binding_subkeys) that links the subkey to the certificate. -- **User ID metadata** is is associated via the [certifying self-signature](bind_ident) that links the identity to the certificate. +- **Identity component metadata** is associated via the [certifying self-signature](bind_ident) that links the identity (usually in the form of a User ID) to the certificate. It is crucial to note that the components of an OpenPGP certificate remain static after their creation. The use of signatures to store metadata allows for subsequent modifications without altering the original components. For instance, a certificate holder can update the expiration time of a component by issuing a new, superseding signature. From b121676a0de3ddb195251060a5eef3d50b04d7c5 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 25 Nov 2023 19:26:55 +0100 Subject: [PATCH 74/81] i think "demonstrate" gestures partly in the wrong direction. much agility is already built in. the point here is not that more agility can be built in on short notice (even though that is also true). but rather that OpenPGP already allows users to make a lot of decisions about which mechanisms to use, right now. --- book/source/04-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index db334e6..1a1660a 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -220,7 +220,7 @@ Notably, in many algorithms, encryption and signing-related functionalities (i.e ### Algorithm preferences and feature signaling -OpenPGP demonstrates significant ["cryptographic agility"](https://en.wikipedia.org/wiki/Cryptographic_agility). It doesn't rely on a single fixed set of algorithms. Instead, it defines a suite of cryptographic primitives from which users (or their applications) can choose. +OpenPGP incorporates significant ["cryptographic agility"](https://en.wikipedia.org/wiki/Cryptographic_agility). It doesn't rely on a single fixed set of algorithms. Instead, it defines a suite of cryptographic primitives from which users (or their applications) can choose. This agility facilitates the easy adoption of new cryptographic primitives into the standard, allowing for a seamless transition. Users can gradually migrate to new cryptographic mechanisms without disruption. From 5621dfa79cbf08606bf0542ffa8fc8780ef145d4 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 25 Nov 2023 19:29:18 +0100 Subject: [PATCH 75/81] avoid using the technical term "key" as a generic word --- book/source/04-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 1a1660a..47cc2f2 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -226,7 +226,7 @@ This agility facilitates the easy adoption of new cryptographic primitives into However, this approach requires that OpenPGP software determine the cryptographic mechanisms that a set of communication partners can handle and prefer. OpenPGP employs several mechanisms for this purpose, which allow negotiation between sender and recipient. It's important to note that OpenPGP is not an online scheme; thus, this negotiation is effectively one-way. The active party interprets the preferences expressed in the certificate of the passive party. -Key negotiation mechanisms in OpenPGP include: +Negotiation mechanisms in OpenPGP include: - [Preferred hash algorithms](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-hashes-subpacket) - [Preferred symmetric ciphers for v1 SEIPD](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#preferred-v1-seipd) From dc9e9510d068c1b021b281e0fb295f9f904041fc Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 25 Nov 2023 20:01:26 +0100 Subject: [PATCH 76/81] ci: codespell fixes --- 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 5c63c2f..6251790 100644 --- a/book/source/05-private.md +++ b/book/source/05-private.md @@ -177,7 +177,7 @@ Only one of these steps deals directly with private key material, and is perform ### Addressing individual keys -An independent design question is how key material is adressed, by users of the keystore. +An independent design question is how key material is addressed, by users of the keystore. The fingerprint of the individual component keys is one obvious option. @@ -202,7 +202,7 @@ write show examples for the operations in a private key store. -- re-use 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" +- 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 From 11542af6458616472eaae15a351a75dbaa1f60e8 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 25 Nov 2023 20:03:58 +0100 Subject: [PATCH 77/81] add placeholder "append-only" link target --- book/source/04-certificates.md | 1 + 1 file changed, 1 insertion(+) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index fe9ab64..f8c6c5e 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -283,6 +283,7 @@ The popular [SKS keyserver network experienced certificate flooding firsthand](h This section only contains notes and still needs to be written ``` +(append-only)= ### Certificate management / Evolution of a certificate over time Minimized versions, merging, effective "append only" semantics, ... From 8ab3d359e6fe76614dcfd9b2dd27ad1bd3546b09 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Sat, 25 Nov 2023 22:07:07 +0100 Subject: [PATCH 78/81] edit to commit 36399d330b --- book/source/03-cryptography.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/book/source/03-cryptography.md b/book/source/03-cryptography.md index c016b1a..98bfa7b 100644 --- a/book/source/03-cryptography.md +++ b/book/source/03-cryptography.md @@ -8,12 +8,12 @@ SPDX-License-Identifier: CC-BY-SA-4.0 ## Cryptographic hash functions -[Cryptographic hash functions](https://en.wikipedia.org/wiki/Cryptographic_hash_function) take data strings of any length (like a text message or file) and output a fixed-size code, a "hash digest," which is often abbreviated as either "digest" or "hash." Hash digests are also sometimes called a "(cryptographic) checksum." A hash digest acts like a unique identifier for the original data. +[Cryptographic hash functions](https://en.wikipedia.org/wiki/Cryptographic_hash_function) take data strings of any length (like a text message or file) and output a fixed-size code, a "hash digest," which is often abbreviated as either "digest" or "hash." A hash digest is also sometimes called a "(cryptographic) checksum." A hash digest acts like a unique identifier for the original data. -Here are two important properties of cryptographic hash functions: +Cryptographic hash functions have two important properties: -- ["Pre-image resistance"](https://en.wikipedia.org/wiki/Preimage_attack): Given a hash digest, it should be very difficult to determine any data that matches this hash digest (including, but not limited to, the original data the hash represents). This property is related to acting as a [one-way function](https://en.wikipedia.org/wiki/One-way_function): a calculation that is easy to perform, but very hard to reverse. -- ["Collision resistance"](https://en.wikipedia.org/wiki/Collision_resistance): It should be very difficult to find two distinct pieces of data that map to the same hash digest. +- [**Pre-image resistance**](https://en.wikipedia.org/wiki/Preimage_attack): Given a hash digest, it should be very difficult to determine any data that matches this hash digest (including, but not limited to, the original data the hash represents). This property embodies the concept of a [one-way function](https://en.wikipedia.org/wiki/One-way_function) – a calculation that is easy to perform, but very hard to reverse. +- [**Collision resistance**](https://en.wikipedia.org/wiki/Collision_resistance): It should be very difficult to find two distinct pieces of data that map to the same hash digest. ## Message authentication codes @@ -95,9 +95,9 @@ Throughout this document, we will frequently reference asymmetric cryptographic An asymmetric cryptographic key pair ``` -Each key pair comprises two parts: the public key and the private key. For ease of identification, we will depict the public key in green and the private key in red throughout this document. Additionally, public keys are shown with a solid edge and pointing to the right, while private keys are shown with dotted edge and pointing to the left. +Each key pair comprises two parts: the public key and the private key. For ease of identification in this documentation, the public key will be shown in green and the private key in red. Additionally, public keys are depicted with a solid border and pointing to the right, while private keys are shown with a dotted border and pointing to the left. -It's important to note that in many scenarios, only the public key is exposed or used (we will expand on these situations in subsequent sections): +It's important to note that in many scenarios, only the public key is exposed or used. These situations will be elaborated upon in subsequent sections of this document. ```{figure} diag/public_key.png --- From 90f2ad9c4fa68fe9f3de2f337c720a8f4fab55df Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Sat, 25 Nov 2023 22:15:37 +0100 Subject: [PATCH 79/81] further streamline commit 7f68db756c --- book/source/03-cryptography.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/book/source/03-cryptography.md b/book/source/03-cryptography.md index 98bfa7b..92fb7cf 100644 --- a/book/source/03-cryptography.md +++ b/book/source/03-cryptography.md @@ -129,10 +129,8 @@ Digital signatures in OpenPGP are used in two primary contexts: - [Signatures on components](component_signatures_chapter) (hybrid_cryptosystems)= -## Hybrid cryptosystems +## Hybrid cryptosystems in OpenPGP [Hybrid cryptosystems](https://en.wikipedia.org/wiki/Hybrid_cryptosystem) combine the use of symmetric and asymmetric (public-key) cryptography to capitalize on the strengths of each, namely symmetric cryptography's speed and efficiency and public-key cryptography's mechanism for secure key exchange. -### Usage and terminology in OpenPGP - -OpenPGP uses a hybrid cryptosystem for encryption. Shared secrets are generated uniquely for each session, and are called "session keys." For more on this, see the chapters {ref}`encryption_chapter` and {ref}`decryption_chapter`. +OpenPGP uses a hybrid cryptosystem for encryption. This approach involves generating unique shared secrets, known as "session keys," for each session. For detailed information on this topic, please refer to the chapters {ref}`encryption_chapter` and {ref}`decryption_chapter`. \ No newline at end of file From f1e6da7e74bdeb6bf236cc976c356680064c33a0 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Sat, 25 Nov 2023 22:53:02 +0100 Subject: [PATCH 80/81] try again --- book/source/03-cryptography.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/source/03-cryptography.md b/book/source/03-cryptography.md index 92fb7cf..4ebea83 100644 --- a/book/source/03-cryptography.md +++ b/book/source/03-cryptography.md @@ -133,4 +133,4 @@ Digital signatures in OpenPGP are used in two primary contexts: [Hybrid cryptosystems](https://en.wikipedia.org/wiki/Hybrid_cryptosystem) combine the use of symmetric and asymmetric (public-key) cryptography to capitalize on the strengths of each, namely symmetric cryptography's speed and efficiency and public-key cryptography's mechanism for secure key exchange. -OpenPGP uses a hybrid cryptosystem for encryption. This approach involves generating unique shared secrets, known as "session keys," for each session. For detailed information on this topic, please refer to the chapters {ref}`encryption_chapter` and {ref}`decryption_chapter`. \ No newline at end of file +OpenPGP uses a hybrid cryptosystem for encryption. This approach involves generating unique shared secrets, known as "session keys," for each session. For detailed information on this topic, please refer to the chapters {ref}`encryption_chapter` and {ref}`decryption_chapter`. From 8431dd8e1daae0135cc42a2377d26eaca3f8fb79 Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 25 Nov 2023 23:05:13 +0100 Subject: [PATCH 81/81] re-instate section structure --- book/source/03-cryptography.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/book/source/03-cryptography.md b/book/source/03-cryptography.md index 6dcd73e..839fd19 100644 --- a/book/source/03-cryptography.md +++ b/book/source/03-cryptography.md @@ -133,8 +133,10 @@ Digital signatures in OpenPGP are used in two primary contexts: - [Signatures on components](component_signatures_chapter) (hybrid_cryptosystems)= -## Hybrid cryptosystems in OpenPGP +## Hybrid cryptosystems [Hybrid cryptosystems](https://en.wikipedia.org/wiki/Hybrid_cryptosystem) combine the use of symmetric and asymmetric (public-key) cryptography to capitalize on the strengths of each, namely symmetric cryptography's speed and efficiency and public-key cryptography's mechanism for secure key exchange. +### Usage and terminology in OpenPGP + OpenPGP uses a hybrid cryptosystem for encryption. This approach involves generating unique shared secrets, known as "session keys," for each session. For detailed information on this topic, please refer to the chapters {ref}`encryption_chapter` and {ref}`decryption_chapter`.