ch4: work on structure

Move introduction of asymmetric key pairs and diagrams to ch3.

book/source/03-cryptography.md

@@ -1,7 +1,45 @@
 # Cryptographic concepts/terms
 
 ```
-Lars suggests that we should have a place where we introduce cryptographic terms that we use, and give short definitions (without getting into how specific algorithms work)
+Lars suggests that we should have a chapter where we introduce cryptographic terms that we use, and give short definitions (without getting into how specific algorithms work)
 
 This would be a good place to introduce visualizations for cryptographic primitives
 ```
+
+## Public-key cryptography
+
+https://en.wikipedia.org/wiki/Public-key_cryptography
+
+### Asymmetric cryptographic key pairs
+
+In many places, we'll deal with asymmetric cryptographic key pairs:
+
+![Image](diag/cryptographic_keys.png "A cryptographic keypair")
+
+A cryptographic key pair consists of a public and a private part. In this document, we'll show the public part of a cryptographic key in green, and the private part in red.
+
+We'll usually visualize cryptographic keypairs in this more compact form:
+
+![Image](diag/keypair.png "A cryptographic keypair")
+
+Note that in many contexts, only the public part is present (more on that later):
+
+![Image](diag/keypair_pub.png "Only the public part of a cryptographic keypair")
+
+### Public-key cryptography in OpenPGP
+
+OpenPGP makes heavy use of public-key cryptography. However, for historical reasons, OpenPGP uses the terms "public/secret" instead of "public/private."
+
+So when reading the RFC, or other documentation, you will encounter the term "secret key," instead of the more common "private key."
+
+### Symmetric encryption
+
+https://en.wikipedia.org/wiki/Symmetric-key_algorithm
+
+[TODO: visualization?]
+
+#### Symmetric cryptography in OpenPGP
+
+Symmetric encryption is a core concept in OpenPGP. It usually comes up involving the term "session key."
+
+"Session keys" in OpenPGP are symmetric cryptographic keys.

book/source/04-certificates.md

@@ -1,7 +1,7 @@
 (certificates_chapter)=
 # Certificates
 
-One central (and non-trivial) element of OpenPGP are certificates (also often called "keys"). OpenPGP certificates are relatively complex data structures, so it's good to have a clear mental model of them.
+One central (and non-trivial) element of OpenPGP are certificates (also often called "OpenPGP keys"). OpenPGP certificates are relatively complex data structures, so it's good to have a clear mental model of them.
 
 ## Terminology: The various meanings of "key"
 
@@ -9,38 +9,36 @@ One central (and non-trivial) element of OpenPGP are certificates (also often ca
 
 First, without additional context, the word "key" can refer either to public, or to private key material.
 
-### Layers of keys
+### Layers of "keys," in OpenPGP
 
-Independent of the distinction between private and public keys, in the OpenPGP space, the term "key" has historically been used to refer to three different layers, all related but distinct:
+Independent of the distinction between private and public keys, in OpenPGP, the term "key" is used to refer to three different layers, all related but distinct:
 
 - A (bare) "cryptographic key" (without additional metadata). Those might be the private and/or public parameters that form a key, e.g., in case of an RSA private key, the exponent `d` along with the prime numbers `p` and `q`.
 - An OpenPGP *component key*: Either an "OpenPGP primary key", or an "OpenPGP subkey". A component key is one building block of an OpenPGP certificate. It consist of a (bare) cryptographic keypair combined some invariant metadata (e.g. key creation time).
 - An "OpenPGP key", or "OpenPGP certificate": Consists of a number of component keys plus additional elements, such as identity information. (OpenPGP "key servers" serve this type of object).
 
-In the following section, we'll look more closely at each of these three layers.
+In the following section, we'll look at these different layers.
 
 
-## "OpenPGP keys/certificates": collections of cryptographic keys, identity information and other metadata
+## Structure of OpenPGP certificates
 
-A full "OpenPGP certificate" (or "OpenPGP key") is composed of an arbitrary number of elements.
+An OpenPGP certificate (or "OpenPGP key") is a collection of an arbitrary number of elements. These elements are:
 
-All elements of an OpenPGP certificate are structured around one central component key: the *OpenPGP primary key*. This primary key acts like a personal CA for the key's owner: It can make cryptographic statements about subkeys, identities, expiration times, revocation, ...
+- component keys,
+- identity information, and
+- other metadata.
 
-Note that OpenPGP keys are often long-lived and may be changed (typically by their owner), over time.
+All elements of an OpenPGP certificate are structured around one central element: the *OpenPGP primary key*. The primary key acts as a personal CA for the key's owner: It can make cryptographic statements about subkeys, identities, expiration times, revocation, ...
+
+Note that OpenPGP certificates are typically long-lived and may be changed (typically by their owner), over time. Components can be added and invalidatedm, over the lifetime of a certificate
 
 ### OpenPGP component keys
 
 An OpenPGP component key (either the "OpenPGP primary key," or an "OpenPGP subkey") consists mainly of an asymmetric cryptographic keypair:
 
-![Image](diag/cryptographic_keys.png "A cryptographic keypair")
-
-A cryptographic keypair, in turn, consists of a private and a public part. In this document, we'll show the public part of a cryptographic key in green, and the private part in red.
-
-We'll usually visualize cryptographic keypairs in this more compact form:
-
 ![Image](diag/keypair.png "A cryptographic keypair")
 
-Note that in many contexts, only the public part is present (more on that later):
+Note that in many contexts, only the public key material is present:
 
 ![Image](diag/keypair_pub.png "Only the public part of a cryptographic keypair")
 
@@ -54,28 +52,29 @@ For each OpenPGP component key, an *OpenPGP fingerprint* can be derived from the
 
 The fingerprint of our example component OpenPGP key is `B3D2 7B09 FBA4 1235 2B41  8972 C8B8 6AC4 2455 4239` [^keyid].
 
-### Special role of the OpenPGP primary key
+[^keyid]: Sometimes, a shortened (64 bit) version of the fingerprint is used instead of the full fingerprint, like this: `C8B8 6AC4 2455 4239` (the rightmost 64 bit of the fingerprint). This type of identifier is called a "Key ID". Historically, 32 bit shorthand identifiers have been used with PGP, like this: `2455 4239`. You may still see such identifiers in very old documents about PGP, but 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".
 
-The primary OpenPGP key has a central role:
+#### Primary key
+
+The "OpenPGP primary key" has the same structure as all other component keys. But it serves a central role:
 
 - Its fingerprint is used as the unique identifier for the full OpenPGP certificate.
 - In addition, it is used for lifecycle operations (e.g. adding or invalidating subkeys or identities in a certificate)
 
-## What is in a certificate (Structure) / Components of an OpenPGP key/certificate
 
-In addition to the primary key, OpenPGP keys/certificates can contain a number of other components:
+#### Subkeys
 
-### Subkeys
+In addition to the primary key, modern OpenPGP certificates can contain "subkeys" in addition to the primary key.
 
-Modern OpenPGP keys/certificates contain "subkeys" in addition to the primary key.
+Subkeys have the same structure as the primary key, but play a subtly different role in the certificate.
 
 ![Image](diag/with_subkeys.png "OpenPGP certificates can contain any number of subkeys")
 
-A component key consists of a cryptographic keypair, plus some additional metadata.
+As before, a component key consists of a cryptographic keypair combined with additional metadata.
 
 Each component key (this includes the primary key, and all subkeys) has a marker that specifies which operations the component key can perform.
 
-#### Excursion, "Key Flags": defining what operations a component key can perform
+#### Key Flags: defining what operations a component key can perform
 
 Each component key has ["Key Flags"](https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.3.21) that specify which types of operation the key can perform.
 
@@ -86,7 +85,7 @@ The commonly used flags are:
 - **E**ncryption
 - **A**uthentication
 
-Only the primary key can perform "certification" operations. All other operations can technically be performed by either the primary key or subkeys.
+Only the primary key can perform "certification" operations. All other operations can be performed by either the primary key or subkeys.
 
 It is considered good practice to have separate component keys for each type of operation (specifically: to allow only *Certification* operations for the primary key, and to have separate *Signing*, *Encryption* and *Authentication* subkeys).
 
@@ -105,17 +104,19 @@ Typically, these identities are composed of a name and an email address.
 User attributes are similar to User IDs, but less commonly used.
 
 
-## Linking the components of an OpenPGP certificate together / Bindings
+### Linking the components of an OpenPGP certificate together ("bindings")
 
-Technically, an OpenPGP certificate consists of a sequence of OpenPGP packets. These packets are just stringed together, one after the other. When you have a file that contains a copy of someone's certificate, it's easy to remove some of these packets, or add new ones.
+Internally, an OpenPGP certificate consists of a sequence of OpenPGP packets. These packets are just stringed together, one after the other. When a certificate is stored in a file[^tpk], it's easy to remove some of these packets, or add new ones.
 
-However, as the owner of a certificate, I don't want a third party to add additional subkeys (or identity claims) to my certificate. I don't want third parties to pretend that those components were put there by me.
+[^tpk]: When an OpenPGP certificate is stored as a file, it's in a format that is called [transferable public key](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-transferable-public-keys) in the RFC
+
+However, as the owner of my certificate, I don't want a third party to add subkeys (or add identity claims) to my certificate, pretending that I put those components there.
 
 To prevent such malicious addition of components, OpenPGP uses cryptographic signatures. These signatures show the cryptographic identity that has linked a component to an OpenPGP certificate (in many cases, the linking is done by the primary key of the certificate in question).
 
 So while anyone can still unilaterally put subkeys and identity claims into a file with my OpenPGP certificate, OpenPGP implementations that read the file are expected to discard components that aren't cryptographically linked to my certificate.
 
-### "Binding" subkeys to an OpenPGP certificate
+#### "Binding" subkeys to an OpenPGP certificate
 
 Linking a subkey to an OpenPGP certificate is done with a ["Subkey Binding Signature"](https://datatracker.ietf.org/doc/html/rfc4880#section-5.2.1). Such a signature signals that the "primary key wants to be associated with the subkey".
 
@@ -123,12 +124,12 @@ The subkey binding signature also adds metadata.
 
 ![Image](diag/subkey_binding.png "Linking an OpenPGP subkey to the primary key with a binding signature")
 
-#### Signature Subpackets
+##### Signature Subpackets
 
 - (key-) expiration
 - flags
 
-#### Binding signing subkeys
+##### Binding signing subkeys
 
 When binding a signing subkey to a primary key, it is not sufficient that the "primary key wants to be associated with the subkey." In addition, the subkey must signal that it wants to be associated with that primary key.
 
@@ -137,7 +138,7 @@ Otherwise, Alice could "adopt" Bob's signing subkey and convincingly claim that
 This additional "Primary Key Binding Signature" is informally called a "back signature" (because the subkey uses the signature to point "back" to the primary key).
 
 
-### Certifying identity claims / Third party signatures
+#### Self-certification of identity claims
 
 OpenPGP certificates often contain identity markers. Typically, in the form of "User ID"s (however, User Attributes are analogous for the purpose of this section).
 
@@ -147,30 +148,12 @@ Alice can link a User ID to her OpenPGP certificate with a cryptographic signatu
 
 ![Image](diag/user_id_certification.png "Linking a User ID to an OpenPGP certificate")
 
-#### Metadata Leak of Social Graph
-
-#### How to generate "minimized" certificate?
-
-
-## Certificate Management / Evolution of a certificate over time
-
-Minimized versions, merging, effective "append only" semantics, ...
-
-### Merging
-
-- How to merge two copies of the same certificate?
-- Canonicalization
-
-### Best Practices regarding Key Freshness
- 
-- Expiry
-- Subkey rotation
 
 ## Third party (identity) certifications
 
 ## Revocations
 
-[^keyid]: Sometimes, a shortened (64 bit) version of the fingerprint is used instead  of the full fingerprint, like this: `C8B8 6AC4 2455 4239` (the rightmost 64 bit of the fingerprint). This type of identifier is called a "Key ID". Historically, 32 bit shorthand identifiers have been used with PGP, like this: `2455 4239`. You may still see such identifiers in very old documents about PGP, but 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".
+### Hard vs. soft revocations
 
 ## Zooming in: Looking at the package structure and internals
 
@@ -630,8 +613,27 @@ Instead of two sections, as before, we see four sections in this certificate:
 
 From here on, we'll look at the dumps in shorter format (you can see more detail by copying the certificates into the web-dumper at https://dump.sequoia-pgp.org/ and checking the "HexDump" checkbox).
 
-### Certifications (Signatures)
+### Certifications (Third Party Signatures)
-
 
 ### Revocations
 
+
+## Advanced topics
+
+### Certificate Management / Evolution of a certificate over time
+
+Minimized versions, merging, effective "append only" semantics, ...
+
+### Merging
+
+- How to merge two copies of the same certificate?
+- Canonicalization
+
+### How to generate "minimized" certificate?
+
+### Best Practices regarding Key Freshness
+
+- Expiry
+- Subkey rotation
+
+### Metadata Leak of Social Graph