diff --git a/book/source/03-cryptography.md b/book/source/03-cryptography.md index 5a2c02f..0cbe953 100644 --- a/book/source/03-cryptography.md +++ b/book/source/03-cryptography.md @@ -14,17 +14,30 @@ https://en.wikipedia.org/wiki/Public-key_cryptography In many places, we'll deal with asymmetric cryptographic key pairs: -![Image](diag/cryptographic_keys.png "A cryptographic keypair") +```{figure} 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") +```{figure} diag/keypair.png +--- +--- +A cryptographic keypair, more compact representation +``` 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") + +```{figure} diag/keypair_pub.png +--- +--- +Only the public part of a cryptographic keypair +``` ### Public-key cryptography in OpenPGP diff --git a/book/source/04-certificates.md b/book/source/04-certificates.md index 7b2f3a1..b1c7e4c 100644 --- a/book/source/04-certificates.md +++ b/book/source/04-certificates.md @@ -36,19 +36,35 @@ Note that OpenPGP certificates are typically long-lived and may be changed (typi An OpenPGP component key (either the "OpenPGP primary key," or an "OpenPGP subkey") consists mainly of an asymmetric cryptographic keypair: -![Image](diag/keypair.png "A cryptographic keypair") +```{figure} diag/keypair.png +--- +--- +A cryptographic keypair +``` -Note that in many contexts, only the public key material is present: +Recall that in many contexts, only the public key material is present: -![Image](diag/keypair_pub.png "Only the public part of a cryptographic keypair") +```{figure} diag/keypair_pub.png +--- +--- +Only the public part of a cryptographic keypair +``` Besides a cryptographic keypair, an OpenPGP component key contains additional metadata (including a creation timestamp): -![Image](diag/primary_key.png "An OpenPGP component key") +```{figure} diag/primary_key.png +--- +--- +An OpenPGP component key +``` For each OpenPGP component key, an *OpenPGP fingerprint* can be derived from the combination of the public key material and metadata: -![Image](diag/fingerprint.png "Each OpenPGP component key has a fingerprint") +```{figure} diag/fingerprint.png +--- +--- +Each OpenPGP component key has a fingerprint +``` The fingerprint of our example component OpenPGP key is `B3D2 7B09 FBA4 1235 2B41 8972 C8B8 6AC4 2455 4239` [^keyid]. @@ -68,7 +84,11 @@ In addition to the primary key, modern OpenPGP certificates can contain "subkeys 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") +```{figure} diag/with_subkeys.png +--- +--- +OpenPGP certificates can contain any number of subkeys +``` As before, a component key consists of a cryptographic keypair combined with additional metadata. @@ -95,7 +115,11 @@ An OpenPGP certificate can contain any number of User IDs. Each user ID associat Typically, these identities are composed of a name and an email address. -![Image](diag/user_id.png "OpenPGP certificates can contain any number of User IDs") +```{figure} diag/user_id.png +--- +--- +OpenPGP certificates can contain any number of User IDs +``` #### Primary UserID and its implications @@ -122,7 +146,11 @@ Linking a subkey to an OpenPGP certificate is done with a ["Subkey Binding Signa The subkey binding signature also adds metadata. -![Image](diag/subkey_binding.png "Linking an OpenPGP subkey to the primary key with a binding signature") +```{figure} diag/subkey_binding.png +--- +--- +Linking an OpenPGP subkey to the primary key with a binding signature +``` ##### Signature Subpackets @@ -146,7 +174,11 @@ For example, above, we saw the User ID "Alice Adams " associa Alice can link a User ID to her OpenPGP certificate with a cryptographic signature. To link a User ID, a signature of the type `PositiveCertification` is created. The signature is issued using the primary (secret) key. -![Image](diag/user_id_certification.png "Linking a User ID to an OpenPGP certificate") +```{figure} diag/user_id_certification.png +--- +--- +Linking a User ID to an OpenPGP certificate +``` ## Third party (identity) certifications @@ -320,8 +352,11 @@ We see that the key consists of two packets: * First, a [*"Secret-Key Packet"*](https://tools.ietf.org/html/rfc4880#section-5.5.1.3), which contains the actual cryptographic key data. Note: the "Secret-Key" Packet contains both the private and the public part of the key. We also see in the output that this packet is "Unencrypted" (i.e. not password-protected). * Second, a [*"Signature Packet"*](https://tools.ietf.org/html/rfc4880#section-5.2) of type 0x1F, *"Signature directly on a key"*. This packet *"binds the information in the Signature subpackets to the key"*. Each entry under "Signature Packet -> Hashed area" is one Signature subpacket, including for example information about algorithm preferences (*"Symmetric algo preferences"* and *"Hash preferences"*). -![Image](diag/key-minimal.png "A minimal OpenPGP key, visualized") - +```{figure} diag/key-minimal.png +--- +--- +A minimal OpenPGP key, visualized +``` #### Seen as a public certificate @@ -429,7 +464,11 @@ The public certificate uses the packet type "Public-Key Packet" instead of "Secr * s2k configuration data, if any (this example doesn't have any). s2k is used when the secret key material is password-protected. -![Image](diag/pubcert-minimal.png "A minimal OpenPGP public certificate, visualized") +```{figure} diag/pubcert-minimal.png +--- +--- +A minimal OpenPGP public certificate, visualized +``` In the following examples, we will look at OpenPGP private keys only. The corresponding public certificates are easy to imagine (just leave out the private key material).