restructure text blocks

book/source/08-signing_components.md

@@ -11,11 +11,13 @@ In this chapter, we'll look into OpenPGP signatures that apply to components of
 - Component keys (primary keys or subkeys) and
 - Identity components (User IDs or User attributes).
 
-This chapter adds detail to material we discussed in the {ref}`certificates_chapter` chapter. Signatures on components are a crucial mechanism for forming OpenPGP certificates, as well as for life-cycle management of certificates.
+This chapter adds detail to material we discussed in the {ref}`certificates_chapter` chapter.
 
-Separately, signatures on components serve as a central building block for OpenPGP's decentralized authentication functionality.
+## Two flavors of signatures on components: first party vs third party
 
-## Who signs?
+Signatures on components are a crucial mechanism for forming OpenPGP certificates, as well as for life-cycle management of certificates, when issued by the certificate holder.
+
+Separately, signatures on components can serve as a building block for OpenPGP's decentralized authentication functionality. Signatures for this functionality are issued by third parties.
 
 ### Self-signatures: Forming certificates and life-cycle management
 
@@ -47,38 +49,6 @@ Or:
 - Certifying self-signatures (type IDs `0x10` - `0x13`) are used to bind a User ID to a certificate, while
 - the same signature type IDs issued by a third party are statements by the signer that they endorse the authenticity of the signed User ID to some degree.
 
-## Signatures on components
-
-A typical use-case for a self-signature is to link a User ID, such as a name and email address to a certificate.
-This is done by calculating a signature over the User ID and the public primary key.
-The resulting certification (typically signature type 0x13, potentially type 0x10-0x12) is then stored as part of the certificate, right after the User ID packet.
-
-Other examples for self-signatures are binding signatures for subkeys. To add an OpenPGP subkey to a certificate, a subkey binding signature is calculated over the public primary key, followed by the public subkey.
-The resulting subkey binding signature (type 0x18) can then be inserted into the certificate right after the subkey.
-If the subkey itself is intended to be used as a **S**igning key, an extra step is required.
-To prevent an attacker from being able to "adopt" a victims signing subkey and then being able to claim to be the origin of signatures in fact made by victim, subkey binding signatures for signing subkeys need to include an embedded "back signature" (formally known as [primary key binding signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#sigtype-primary-binding)) made by the signing key itself.
-
-Certifications over User IDs can also be used to certify certificates of third-parties.
-If Alice is certain that `Bob Baker <bob@example.com>` controls the key `0xB0B`, she can create a User ID certification signature for that identity and send it to Bob.
-Bob can then add this signature to his certificate.
-TODO: More WoT.
-
-### Revocations
-
-One important class of self-signatures are revocations.
-
-A revocation signature is used to retract the statement formed by a prior signature.
-A subkey revocation signature revokes a prior subkey binding signature, while a certification revocation revokes a certification signature.
-Typical use-cases for revocations are marking certificates or individual subkeys as unusable (for example, when the private key has been compromised or superseded), or marking User IDs as no longer used.
-
-A revocation signature can either be hard or soft. A soft revocation of a certificate invalidates it from the revocation signature's creation time onwards. This means signatures issued before the revocation remain intact. A hard revocation, by contrast, invalidates the certificate retroactively, rendering all issued signatures invalid, regardless of creation time. Soft revocations are typically used whenever a key or User ID is retired or superseded gracefully, while hard revocations can, for example, signal compromise of secret key material.
-
-```{note}
-OpenPGP certificates act as append-only data structures, in practice. Elements of a certiciate can not be removed from the copies on key servers and the OpenPGP systems of third parties, once published. Implementations usually merge all available components and signatures.
-
-Revocations are used as a mechanism to mark components or signatures as invalid.
-```
-
 ## Self-signatures: Linking the components of a certificate
 
 So far we've looked at the components in an OpenPGP certificate, but certificates actually contain another set of elements, which bind the components together, and add metadata to them.
@@ -107,19 +77,18 @@ Note, though, that there are some cases where third parties legitimately add "un
 (bind_subkey)=
 ### Binding subkeys to a certificate
 
-Linking a subkey to an OpenPGP certificate is done with a ["Subkey Binding Signature"](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-subkey-binding). Such a signature signals that the "primary key wants to be associated with the subkey".
+A subkey is linked to an OpenPGP certificate using a [subkey binding signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-subkey-binding) (type ID 0x18). This signature type effectively signals that the "primary key wants to be associated with the subkey".
 
-The subkey binding signature also adds metadata.
+A subkey binding signature binds the public primary key and the public subkey, and additionally metadata in the signature packet. Once generated, the subkey binding signature packet is stored in the certificate right after the subkey.
+
+(Note that subkeys that have the *signing* [key flag](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-key-flags) are a special case, see {numref}`bind_subkey_sign`.)
 
 ```{figure} diag/subkey_binding_signature.png
 
 Linking an OpenPGP subkey to the primary key with a binding signature
 ```
 
-The [Signature packet](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-signature-packet-tag-2) that binds the subkey to the primary key has the signature type [SubkeyBinding](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-subkey-binding-signature-si).
+In order to specify an expiration time for the subkey, a key expiration time subpacket can be included in the subkey binding signature packet.
-
-
-In order to specify an expiration time for the subkey, a key expiration time subpacket can be included.
 
 ```{note}
 The validity of a subkey is bounded by that of the primary key, meaning an expired primary key causes the subkey to be invalidated, no matter the subkey expiration time.
@@ -129,15 +98,16 @@ It's legal for a subkey to not have an explicit expiry time. In that case, its e
 A subkey cannot be "older" than the primary key. The value of the subkeys creation date MUST be greater than that of the primary key.
 ```
 
+(bind_subkey_sign)=
 ### Special case: Binding signing subkeys to a certificate
 
-Binding subkeys with the "signing" key flag is a special case. For the most part, it works the same as binding other types of subkeys, but there is an additional requirement:
+To bind subkeys with the "signing" key flag to a certificate is a special case. For the most part, it works the same as binding other types of subkeys, but there is an additional requirement:
 
 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."
 
 Otherwise, Alice could "adopt" Bob's signing subkey and convincingly claim that she made signatures that were in fact issued by Bob.
 This is to prevent an attack where the attacker "adopts" the victims signing subkey as their own in order to claim ownership over documents which were in fact signed by the victim.
-Contrary to the `SubkeyBinding` signature, which is issued by the certificate's primary key, the `PrimaryKeyBinding` signature is instead created by the subkey.
+In contrast to the [subkey binding signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-subkey-binding) (type ID 0x18), which is issued by the certificate's primary key, the [primary key binding signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#sigtype-primary-binding) (type ID 0x19) is instead created by the subkey (informally also called an embedded "back signature").
 
 ```{figure} diag/subkey_binding_signatur_for_signing_sk.png
 
@@ -150,11 +120,15 @@ The *primary key binding signature* is "embedded" as subpacket data in the *subk
 
 ### Binding identities to a certificate
 
-"User ID" identity components are bound to an OpenPGP certificate by issuing a self-signature ("User Attributes" work analogously).
+Another use-case for a self-signature is to link an identity component (such as a User ID that specifies a name and email address) to a certificate.
+
+User ID components are bound to an OpenPGP certificate by issuing a self-signature ("User Attributes" work analogously).
 
 For example, the User ID `Alice Adams <alice@example.org>` may be associated with Alice's certificate `AAA1 8CBB 2546 85C5 8358 3205 63FD 37B6  7F33 00F9 FB0E C457 378C D29F 1026 98B3`.
 
-Alice can link a User ID to her OpenPGP certificate with a cryptographic signature. To link a User ID, a self-signature is created (usually with the signature type [PositiveCertification](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-positive-cert)). This signature is issued by the primary key.
+Alice can link a User ID to her OpenPGP certificate with a cryptographic signature. To link a User ID, a "certifying self-signature" is created (usually with the signature type [positive certification](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#sigtype-positive-cert) (type ID 0x13, or sometimes with type ID 0x10, 0x11 or 0x12)). This signature is issued by the primary key.
+
+The resulting certification is stored as part of the certificate, right after the User ID packet.
 
 ```{figure} diag/user_id_certification.png
 ---
@@ -176,10 +150,18 @@ explain metadata associated with this signature, and that c-r prefers this over
 
 ### Revocations: Invalidating components of a certificate
 
-```{admonition} TODO
+One important class of self-signatures are revocations.
-:class: warning
 
-This section only contains notes and still needs to be written
+A revocation signature is used to retract the statement formed by a prior signature.
+A subkey revocation signature revokes a prior subkey binding signature, while a certification revocation revokes a certification signature.
+Typical use-cases for revocations are marking certificates or individual subkeys as unusable (for example, when the private key has been compromised or superseded), or marking User IDs as no longer used.
+
+A revocation signature can either be hard or soft. A soft revocation of a certificate invalidates it from the revocation signature's creation time onwards. This means signatures issued before the revocation remain intact. A hard revocation, by contrast, invalidates the certificate retroactively, rendering all issued signatures invalid, regardless of creation time. Soft revocations are typically used whenever a key or User ID is retired or superseded gracefully, while hard revocations can, for example, signal compromise of secret key material.
+
+```{note}
+OpenPGP certificates act as append-only data structures, in practice. Elements of a certiciate can not be removed from the copies on key servers and the OpenPGP systems of third parties, once published. Implementations usually merge all available components and signatures.
+
+Revocations are used as a mechanism to mark components or signatures as invalid.
 ```
 
 Note: certification signatures [can be made irrevocable](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-10.html#name-revocable).
@@ -206,6 +188,19 @@ A missing revocation reason subpacket is equivalent with a hard revocation reaso
 write
 ```
 
+### Certifying identities
+
+Certifications over User IDs can also be used to certify certificates of third-parties.
+If Alice is certain that `Bob Baker <bob@example.com>` controls the key `0xB0B`, she can create a User ID certification signature for that identity and send it to Bob.
+Bob can then add this signature to his certificate.
+
+TODO: More WoT.
+
+### Delegating authentication: trust signatures
+
+### Revocations: Undoing previous statements
+
+
 ## Advanced topics
 
 ### Certification Recipes