ch3/4: Include diagrams as figures with caption

Fixes #28

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
 

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 <alice@example.org>" 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).