From 6abd5336cf4377d9d7336c8ddced0e62a54a536a Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Thu, 19 Oct 2023 17:30:13 +0200 Subject: [PATCH 1/5] edit ch4 --- .DS_Store | Bin 0 -> 6148 bytes book/source/04-certificates.md | 38 ++++++++++++++++++--------------- 2 files changed, 21 insertions(+), 17 deletions(-) create mode 100644 .DS_Store diff --git a/.DS_Store b/.DS_Store new file mode 100644 index 0000000000000000000000000000000000000000..eb788aa81b782b77aea7cc134c0e09cd6991f010 GIT binary patch literal 6148 zcmeHK%}T>S5T308EA`N$2PyjiBJ>SniBC|xOB!jV4GI3>(R~bk5f9#d3!g>&W_JkP zq|u9r$V{32lKI)4eEHc95t-S2F(n!k(GbcwIKZ$&*w5OLfmjZKhUeHUr}ITs)}2T- z{8a|{-X(NOOS-1J=>AO}Kel~km1X&+%3;I9;GSPsZ)dT;_|jjmww{fX6sa`Ax(`(0 zS5Qq?w4gP{o2Uv(F8U)|HND&}eN8>{mQ_^YH_=hO{`~+?xvzE|Rd~GrjtU!JtEQ)h zC&_J9(eX#?PAsNYQ3jL&W#Gpdz@E)A90k--8Bhk4frbJ8K3FJYD(C|GPX`9y0ss@3 zz2KO83C^*Csh|r855$C2U`RF6VwjK)yOp?9&;<S eZ^cJYFR)ua0H%U2AS@95Bj9P!K^gc}20j57l4oTA literal 0 HcmV?d00001 diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 644d1a5..0fe1785 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -1,7 +1,7 @@ (certificates_chapter)= # Certificates -OpenPGP fundamentally hinges on the concept of "OpenPGP certificates," often referred to as "OpenPGP keys." These certificates are complex data structures essential for identity verification, data encryption, and digital signatures. Understanding their structure and functionality is pivotal for effective application of the OpenPGP standard. +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. ## Terminology: Understanding "keys" @@ -27,54 +27,58 @@ For detailed insights on structure and handling, refer to our chapters on OpenPG An OpenPGP certificate (or "OpenPGP key") is a collection of an arbitrary number of elements[^packets]: -[^packets]: In technical terms, the elements of an OpenPGP certificate are a collection "packets". Each component key and identity component is internally represented as one packet. The other common type of element is "signature" packets, which link the components of a certificate together. +[^packets]: In technical terms, the elements of an OpenPGP certificate are a collection of "packets." Each component key and identity component is internally represented as a packet. Another common type of packet is the "signature" packet, which connect the components of a certificate. -- Component OpenPGP keys, -- Identity components, -- Other metadata (this includes connections between the certificate's components). +- Component keys +- Identity components +- Additional metadata, including connections between the certificate's components We sometimes collectively refer to component keys and identity information as "the components of a certificate." +```{admonition} Warning +Please clarify who "we" is in this statement. +``` + ```{figure} diag/OpenPGP_Certificate.png Typical components in an OpenPGP certificate ``` -All elements in an OpenPGP certificate are structured around one central component: the *OpenPGP primary key*. The primary key acts as a personal {term}`CA` for the certificate's owner: It can make cryptographic statements about subkeys, identities, expiration, revocation, ... +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. ```{note} -OpenPGP certificates are typically long-lived and may be changed (typically by their owner), over time. Components can be added and invalidated, over the lifetime of a certificate +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. ``` ## Component keys -An OpenPGP certificate usually contains multiple OpenPGP component keys. Component keys are used in one of two roles: either as "OpenPGP primary key," or as an "OpenPGP subkey." +An OpenPGP certificate usually contains multiple component keys. Component keys serve in one of two roles: either as an "OpenPGP primary key" or as an "OpenPGP subkey." -OpenPGP component keys logically consist of an [asymmetric cryptographic keypair](asymmetric_key_pair) and a creation timestamp. These attributes of a component key cannot be changed after creation (in the case of ECDH keys, two additional parameters are part of a component key's constituting data[^ecdh-paramters]). +OpenPGP component keys logically consist of an [asymmetric cryptographic keypair](asymmetric_key_pair) and a creation timestamp. Once created, these attributes of a component key remain fixed (for ECDH keys, two additional parameters are part of a component key's constitutive data[^ecdh-parameters]). -[^ecdh-paramters]: 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 part of the component key's constituting and immutable properties. Those parameters define a hash function and a symmetric encryption algorithm. +[^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 An OpenPGP component key ``` -Component key representations that include private key material also contain metadata that specifies the password protection scheme for the private key material. However, in this chapter, we're looking at *OpenPGP certificates*, which *don't* contain private key information. Each component key of such a certificate contains only the public part of its cryptographic key data. To read more about private keys in OpenPGP, see {numref}`private_key_chapter`. +Component keys containing private key material also contain metadata that specifies the password protection scheme for the private key material. However, in this chapter, we're looking at *OpenPGP certificates*, which *don't* contain private key information. Each component key of such a certificate contains only the public part of its cryptographic key data. To read more about private keys in OpenPGP, see {numref}`private_key_chapter`. ### Fingerprint -For each OpenPGP component key, an *OpenPGP fingerprint* can be derived from the combination of the public key material and creation timestamp (and ECDH parameters, if applicable). +For each OpenPGP component key, an *OpenPGP fingerprint* can be generated. This fingerprint is derived from the combination of the public key material and creation timestamp (and ECDH parameters, if applicable). ```{figure} diag/Fingerprint.png -Every OpenPGP component key can be named by a fingerprint +Every OpenPGP component key is identifiable by a unique fingerprint. ``` -The fingerprint of our example component OpenPGP key is `C0A5 8384 A438 E5A1 4F73 7124 26A4 D45D BAEE F4A3 9E6B 30B0 9D55 13F9 78AC CA94`[^keyid]. +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]. -[^keyid]: In OpenPGP version 4, the rightmost 64 bit were sometimes used as a shorter identifier, called "Key ID". -E.g., an OpenPGP version 4 certificate with the fingerprint `B3D2 7B09 FBA4 1235 2B41 8972 C8B8 6AC4 2455 4239` might be referred to by the 64 bit Key ID `C8B8 6AC4 2455 4239` or styled as `0xC8B86AC424554239`. -Historically, even shorter 32 bit identifiers have sometimes been used, like this: `2455 4239`, or `0x24554239`. You may still see such identifiers in very old documents about PGP. However, 32 bit identifiers have [been unfit for purpose for a long time](https://evil32.com/). At some point, 32 bit identifiers were called "short Key ID", while 64 bit identifiers were called "long Key ID". +[^keyid]: In OpenPGP version 4, the rightmost 64 bits were sometimes used as a shorter identifier, called "Key ID." +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." ### Primary key From f98122526100e365faf9c1a744b43e9abc5a5e10 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Thu, 19 Oct 2023 17:35:17 +0200 Subject: [PATCH 2/5] edit ch4 primary key --- 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 0fe1785..31bdede 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -82,17 +82,17 @@ Historically, even shorter 32-bit identifiers were used, like this: `2455 4239`, ### Primary key -The "OpenPGP primary key" is a component key that serves a central role in an OpenPGP certificate: +The OpenPGP primary key is a distinct component key that serves a central role in an OpenPGP certificate: -- Its fingerprint is used as the unique identifier for the full OpenPGP certificate. -- It is used for lifecycle operations, such as adding or invalidating subkeys or identities in a certificate. +- Its fingerprint acts as the unique identifier for the entire OpenPGP certificate. +- It facilitates lifecycle operations, such as adding or invalidating subkeys or identities within a certificate. The validity of the primary key limits its capacity to confer validity to other components. E.g.: The primary key cannot confer an expiration time beyond its own expiration to a subkey. It can also not confer validity to components after it has been revoked. ```{admonition} Terminology :class: note -In the RFC, the OpenPGP primary key is also sometimes referred to as "top-level key." It has also sometimes informally been called "master key." +In the RFC, the OpenPGP primary key is occasionally referred to as "top-level key." Informally, it has also been termed the "master key." ``` ### Subkeys From 9a5ff9f2abc2b23504dd75d73f7945ce00788399 Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Thu, 19 Oct 2023 17:40:57 +0200 Subject: [PATCH 3/5] edit ch4 subkeys --- book/source/04-certificates.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 31bdede..34c745e 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -97,15 +97,15 @@ In the RFC, the OpenPGP primary key is occasionally referred to as "top-level ke ### Subkeys -In addition to the primary key, modern OpenPGP certificates usually contain a number of "subkeys" (however, it's not technically necessary for a certificate to contain subkeys). +In addition to the primary key, modern OpenPGP certificates usually contain several subkeys, although they are not technically required. -Subkeys have the same structure as the primary key, but they are used in a different role. Subkeys are cryptographically linked with the primary key (more on this in {numref}`binding_subkeys`). +Subkeys have the same structural attributes as the primary key but fulfill a different role. Subkeys are cryptographically linked with the primary key (more on this in {numref}`binding_subkeys`). ```{figure} diag/Subkeys.png -:name: Certificate with Subkeys -:alt: Three component keys. The primary key is shown at the top. It can be used for certification. Below it, linked with arrows, are two more component keys, used as subkeys. They are marked as "for encryption" and "for signing", respectively. +:name: Certificate with subkeys +:alt: Three component keys depicted. The primary key is positioned at the top, designated for certification. Below it, linked by arrows, are two more component keys, used as subkeys. They are labeled as "for encryption" and "for signing," respectively. -OpenPGP certificates can contain a number of subkeys +OpenPGP certificates can contain multiple subkeys. ``` ### Key flags: defining which operations a component key can perform From 17e0efb421943a989a67795aaa8e7481ec809b5d Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Thu, 19 Oct 2023 17:44:47 +0200 Subject: [PATCH 4/5] add warning/task regarding capitalization --- book/source/04-certificates.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 34c745e..795a741 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -110,6 +110,10 @@ OpenPGP certificates can contain multiple subkeys. ### Key flags: defining which operations a component key can perform +```{admonition} Warning +Let's decide whether the capitalization of F is necessary. +``` + 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 specify which operations that key can perform. The commonly used key flags are: From b484018f41ac78d02ba3bb50f28c57e35ab19e4d Mon Sep 17 00:00:00 2001 From: "Tammi L. Coles" Date: Thu, 19 Oct 2023 19:16:11 +0200 Subject: [PATCH 5/5] edit key flags in part --- book/source/04-certificates.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 795a741..9b8eff3 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -108,21 +108,25 @@ Subkeys have the same structural attributes as the primary key but fulfill a dif OpenPGP certificates can contain multiple subkeys. ``` -### Key flags: defining which operations a component key can perform +#### Defining operational capabilities with Key Flags ```{admonition} Warning Let's decide whether the capitalization of F is necessary. ``` -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 specify which operations that key can perform. +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. -The commonly used key flags are: +Commonly used key flags are: - **C**ertification (issuing third-party certifications) - **S**igning (signing data) - **E**ncryption (encrypting data) - **A**uthentication (commonly used for OpenPGP authentication) +```{admonition} Warning +Accessibility. Is the bolding of C, S, E, A compatible with screenreaders? Is it worth the effort? +``` + By convention, only the primary key is allowed to perform "certification" operations. All other operations can be configured on either the primary key or a subkey. ```{note}