more restructuring

book/source/06-certifications.md

@@ -9,29 +9,29 @@ SPDX-License-Identifier: CC-BY-SA-4.0
 
 Signatures make up the magic of OpenPGP. They act as the syntax that allows forming and interpreting rich statements about certificates and their components, as well as data.
 
-Without signatures, there would only be loose keys, impossible to associate with their owner. Signatures are the glue that allows for components (keys, subkeys and identities) to be assembled into hierarchical certificates, and for messages to gain authenticity.
+Without signatures, there would only be loose keys, impossible to associate with a certificate, or their owner. Signatures are the glue that allows for components (component keys and identity components) to be assembled into hierarchical certificates, and for messages to gain authenticity.
 
-In this chapter, we'll discuss signatures that apply to component keys and identity components. See our chapter {ref}`signing_data`, for a discussion of the other type of signatures in OpenPGP.
+## Terminology
 
-```{figure} mermaid/06-terminology.png
-
-Types of signatures in OpenPGP
-```
-
-## Signatures in OpenPGP
-
-The term *signature* can have multiple meanings in the context of the OpenPGP specification:
+The term *signature* can have multiple meanings in the context of OpenPGP:
 
 - Cryptographic keys create raw signatures which are byte sequences calculated according to some signature scheme.
 - OpenPGP packs these raw signatures up into OpenPGP signature packets, which carry additional information in the form of signature subpackets.
 
 For the purpose of this document, the term signature will refer to an OpenPGP [signature packet](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-signature-packet-type-id-2).
 
-### Types of signatures
+## Types of signatures in OpenPGP
 
 OpenPGP signatures can be separated into *signatures on components* and *data signatures*.
 
-#### Signatures on components
+In this chapter, we'll discuss signatures that apply to components: That is, to component keys and identity components. See our chapter {ref}`signing_data`, for a discussion of the other type of signatures in OpenPGP.
+
+```{figure} mermaid/06-terminology.png
+
+Types of signatures in OpenPGP
+```
+
+## Signatures on components
 
 Signatures on components are separated into *self-signatures* and *third-party certifications*.
 A signature made by a key over components of the same certificate is referred to as a *self-signature*.
@@ -56,7 +56,7 @@ If Alice is certain that `Bob Baker <bob@example.com>` controls the key `0xB0B`,
 Bob can then add this signature to his certificate.
 TODO: More WoT.
 
-##### Types of signatures on components
+### Types of signatures on components
 
 There are two classes of components that signatures can apply to:
 
@@ -72,7 +72,7 @@ The same OpenPGP signature mechanism is used for all of these cases. So at first
 
 However, there are differences in some of the details of the signatures for these different cases, which we will then look into - as well as the semantics, which differ between these types of signatures. We'll discuss all of this in this chapter.
 
-##### Revocations
+### Revocations
 
 One important class of self-signatures are revocations.
 
@@ -82,19 +82,7 @@ Typical use-cases for revocations are marking certificates or individual subkeys
 
 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, meaning signatures that were issued before the revocation remain intact, while a hard revocation 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.
 
-#### Data signatures
-
-A data signature serves the purpose to cryptographically guarantee the authenticity (and implicitly also the integrity) of a message, e.g. an email or a file, while a certification is used to attach metadata or subkeys to a certificate.
-Data signatures are always calculated by keys carrying the **S**igning key flag.
-Different types of signatures are distinguished by a signature type code and are calculated in different ways.
-Signatures can either be distributed standalone as *detached* signatures, or can be inlined with OpenPGP data, such as an OpenPGP message or a key or certificate.
-
-Data signatures (type 0x00 and 0x01) are created by hashing the message content and calculating a cryptographic signature over the hash.
-You can read more about data signatures in the [next chapter](signing_data).
-The result is packed up into an OpenPGP signature packet, which can either be included in the OpenPGP message (TODO: See section about forming messages, cleartext signature framework), or distributed separately as a so-called *detached* signature.
-Data signatures are always calculated using a **S**igning key.
-
-### Signature types
+## Signature types
 
 The OpenPGP standard defines a set of [Signature Types](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-signature-types), each identified by a numerical signature type ID.
 
@@ -107,7 +95,7 @@ Self-certifications of types `0x10` - `0x13` can be used to bind a User ID to a
 
 There are further signature types for signatures on data, as well as designated types to bind and revoke subkeys.
 
-### Signature subpackets
+## Signature subpackets
 
 A cryptographic signature alone is often not expressive enough to serve certain use-cases.
 For this reason, the OpenPGP protocol introduced signature subpackets with rfc4880.
@@ -123,7 +111,7 @@ The unhashed area can be used to retroactively add, change or remove subpackets
 Due to the fact that the unhashed area doesn't provide any cryptographic guarantees, it is only intended for advisory packets, or packets that self-authenticate (e.g. the issuer fingerprint subpacket, whose "correctness" can be proven by successfully verifying the signature using the referenced issuer key).
 In most cases, signature subpackets are simply added into the hashed area.
 
-#### Criticality of subpackets
+### Criticality of subpackets
 
 Each signature subpacket has a flag that indicates whether or not the subpacket is *critical*.
 Since different OpenPGP implementations might support subsets of the standard, it would be fatal, if for example an implementation did not understand the concept of signature expiration.

book/source/07-signing_data.md

@@ -16,3 +16,15 @@ Add content, including:
 - Signature of a canonical text document
   - "The signature is calculated over the text data with its line endings converted to `<CR><LF>`"
 ```
+
+## Data signatures
+
+A data signature serves the purpose to cryptographically guarantee the authenticity (and implicitly also the integrity) of a message, e.g. an email or a file, while a certification is used to attach metadata or subkeys to a certificate.
+Data signatures are always calculated by keys carrying the **S**igning key flag.
+Different types of signatures are distinguished by a signature type code and are calculated in different ways.
+Signatures can either be distributed standalone as *detached* signatures, or can be inlined with OpenPGP data, such as an OpenPGP message or a key or certificate.
+
+Data signatures (type 0x00 and 0x01) are created by hashing the message content and calculating a cryptographic signature over the hash.
+You can read more about data signatures in the [next chapter](signing_data).
+The result is packed up into an OpenPGP signature packet, which can either be included in the OpenPGP message (TODO: See section about forming messages, cleartext signature framework), or distributed separately as a so-called *detached* signature.
+Data signatures are always calculated using a **S**igning key.