ch5: writing

book/source/05-private.md

@@ -1,26 +1,70 @@
 (private_key_chapter)=
-# Private keys
+# OpenPGP private keys
 
-```{admonition} TODO
+Historically, terminology around OpenPGP certificates and keys has often been used inconsistently. The pair of terms "OpenPGP public key" and "OpenPGP private/secret keys" were commonly used (while the shorthand "OpenPGP key" can refer to both, depending on context).
+
+## Terms
+
+In this document, we use the term *OpenPGP certificate* to refer "OpenPGP public keys": The combination of component public keys, identity components and bindings.
+
+This chapter is about the counterpart to the public material in certificates: Here, we discuss the handling of *private key material* in OpenPGP.
+
+In this text, we treat the private key material as logically separate from the OpenPGP certificate. Operations that use the private key material are typically handled by a separate subsystem. 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 elements, which are usually handled separately[^pkcs11]:
+
+```{admonition} VISUAL
 :class: warning
 
-- Consistently consider private key material as a separate thing from Certificates? (like in pkcs#11?)
+- OpenPGP certificate side-by-side with the 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. "OpenPGP private keys" are sometimes handled in a format that combines the certificate and the private key data: [*Transferable secret keys (TSK)*](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-11.html#name-transferable-secret-keys).
+
 ## Transferable secret keys
 
-https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-transferable-secret-keys
+Sometimes users handle "OpenPGP private keys" in the form of *transferable secret keys* (TSK). That is: a serialized format that combines the OpenPGP certificate data with the connected private key material, stored in a single file.
 
-
+```{admonition} VISUAL
-(encrypted_secrets)=
-## Password protecting secret key material
-
-```{admonition} TODO
 :class: warning
 
-S2K, symmetric encryption
+- OpenPGP certificate with integrated private key material, as TSK
 ```
 
+The TSK format can be useful for backups of OpenPGP key material, or 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 applies symmetric encryption to the private key data in component keys.
+
+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).
+
+```{admonition} VISUAL
+:class: warning
+
+- passphrase --(S2k mechanism)--> symmetric encryption key
+```
+
+Encryption of private key material can be configured independently for each component key. Component keys that are associated with the same certificate can use different mechanisms for passphrase protection, and/or different passphrases.
+
+### S2K mechanisms for symmetric key generation
+
+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)
+
+### Mechanisms for secret key encryption with S2K
+
+Different mechanisms are specified [for the encryption of the secret key data](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-secret-key-encryption).
+
 
 ## Private key operations