WIP: ch5

book/source/05-private.md

@@ -1,26 +1,66 @@
 (private_key_chapter)=
-# Private keys
+# OpenPGP private keys
 
 ```{admonition} TODO
 :class: warning
 
+General plan, reminder:
+
 - Consistently consider private key material as a separate thing from Certificates? (like in pkcs#11?)
 ```
 
-## Transferable secret keys
+Historically, terminology around OpenPGP certificates and keys has often been used inconsistently. Often, commonly, the terms "OpenPGP public key" and "OpenPGP private/secret keys" were used.
 
-https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-transferable-secret-keys
+In this document, we use the term *OpenPGP certificate* to refer "OpenPGP public keys": The combination of public component keys (without private key material), identity components and bindings. When serialized, OpenPGP certificates are typically stored in [transferable public key (TPK)](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-11.html#name-transferable-public-keys) format.
 
+This chapter is about *private key material*, which is not contained in OpenPGP certificates. We will usually treat the private key material as logically separate from the OpenPGP certificate, and that the private key material is usually handled by a separate subsystem.
 
-(encrypted_secrets)=
-## Password protecting secret key material
+We think it is useful to think about OpenPGP certificates on one hand, and the associated private key material, on the other, as two related but usually separate elements[^pkcs11]:
 
-```{admonition} TODO
+```{admonition} VISUAL
 :class: warning
 
-S2K, symmetric encryption
+- OpenPGP certificate side-to-side with associated, loose private key material
 ```
 
+[^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 to this: "OpenPGP private keys" are sometimes handled as  [transferable secret keys (TSK)](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-11.html#name-transferable-secret-keys), in which the OpenPGP certificate is combined with the private key material.
+
+## Transferable secret keys
+
+Sometimes users handle "OpenPGP private keys" as transferable secret keys (TSK). That is: a serialized format that combines the OpenPGP certificate data with the connected private key material.
+
+```{admonition} VISUAL
+:class: warning
+
+- OpenPGP certificate with integrated private key material, as TSK
+```
+
+The TSK format is useful for backups of OpenPGP key material, and e.g., to move a key to a different computer[^gpg-tsk].
+
+[^gpg-tsk]: For example, with GnuPG, an OpenPGP key can be exported in (armored) TSK format like this: `gpg --export-secret-key --armor <fingerprint>`
+
+(encrypted_secrets)=
+### Protecting secret key material with a passphrase (using S2K)
+
+In OpenPGP format, private key material can be optionally protected with a [passphrase](https://en.wikipedia.org/wiki/Passphrase). This mechanism uses symmetric encryption of (only) the private key data. The symmetric encryption key is derived from a secret that the user knows (the passphrase).
+
+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.
+
+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).
+
+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)  
+
+
+```{admonition} VISUAL
+:class: warning
+
+- passphrase --(S2k mechanism)--> symmetric encryption key
+```
 
 ## Private key operations