edits

book/source/06-certifications.md

@@ -7,50 +7,57 @@ SPDX-License-Identifier: CC-BY-SA-4.0
 
 # Signatures on components
 
-Signatures make up the magic of OpenPGP.
-They act as the syntax that allows forming and interpreting complex statements about data and identities.
-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.
+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.
 
-In this chapter, we'll discuss signatures that apply to component keys and identity components. In {ref}`signing_data`, we discuss the other class of signatures, which makes statements about 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.
 
-In this chapter, one important distinction is between:
-
-- Self-signatures, where the owner of a certificate uses signatures internal to their certificate and
-- Third-party signatures, where a third party issues statements about components of a certificate.
+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.
 
 ```{figure} mermaid/06-terminology.png
 
 Types of signatures in OpenPGP
 ```
 
-## Terminology
+## Types of signatures on components
 
-The term *signature* can have multiple meanings in the context of the OpenPGP specification.
-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 (tag 2).
+There are two classes of components that signatures can apply to:
 
-OpenPGP signatures can be separated into *data signatures* and *certifications*.
-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.
+- Component keys (primary keys or subkeys).
+- Identity components (User IDs or User attributes).
 
-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.
+And there are two important scenarios that we will distinguish. Signatures on components can be issued by:
 
-Certifications are separated into *self-certifications* and *third-party certifications*.
-A certification made by a key over components of the same certificate is referred to as a *self-certification*.
+- The certificate's owner (in which case we call them *self-signatures*), or
+- A third party (in which case we call them *third-party signatures*).
+
+The same OpenPGP signature mechanism is used for all of these cases. So at first, we will discuss the general shape of OpenPGP signatures.
+
+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.
+
+## Signatures in OpenPGP
+
+The term *signature* can have multiple meanings in the context of the OpenPGP specification:
+
+- 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
+
+OpenPGP signatures can be separated into *signatures on components* and *data signatures*.
+
+#### 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*.
 
 ```{note}
 The **C**ertify Others key flag is not required in order to issue self-certifications.
 It is only necessary to issue valid third-party certifications.
 ```
 
-A typical use-case for a self-certification is to attach a User ID, such as a name and email address to a certificate.
+A typical use-case for a self-signature is to attach a User ID, such as a name and email address to a certificate.
 This is done by calculating the signature over the User ID and the public primary key.
 The resulting User ID certification (typically type 0x13, potentially type 0x10-0x12) can then be inserted into the certificate, right after the User ID packet.
 
@@ -65,26 +72,42 @@ 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.
 
-Another important category of signatures are revocations.
+##### Revocations
+
+One important class of self-signatures are revocations.
+
 A revocation 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, 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, 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.
 
-## Signature Types
-There is a number of different Signature Types in the form of numerical IDs.
-These give guidance on what the intent of a signature is and how it needs to be interpreted, however, the meaning of a signature also depends on who issued it.
-A self-signature has a different meaning from a signature issued by a third party.
+#### Data signatures
 
-A `DirectKeySignature` issued as a self-signature can be used to set preferences and advertise features that apply to the whole certificate.
-A third-party `DirectKeySignature` carrying a `TrustSignature` subpacket on the other hand can be interpreted as a statement by the issuer that it delegates trust to the signed certificate (WoT).
+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.
 
-Self-certifications of types `0x10` - `0x13` can be used to bind a User ID to a certificate, while the same types issued by a third-party are statements by the issuer that they have checked the authenticity of the signed User ID to some degree.
+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
+
+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.
+
+Signature types define the intent of a signature, and how it needs to be interpreted. However, the meaning of a signature also depends on who issued it: A self-signature has a different meaning from a signature issued by a third party.
+
+A [direct key signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-direct-key-signature-type-i) issued as a self-signature can be used to set preferences and advertise features that apply to the whole certificate.
+A third-party [direct key signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-direct-key-signature-type-i) carrying a [trust signature](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-trust-signature) subpacket on the other hand can be interpreted as a statement by the issuer that they delegate trust to the signed certificate (WoT).
+
+Self-certifications of types `0x10` - `0x13` can be used to bind a User ID to a certificate, while the same types issued by a third party are statements by the signer that they have checked the authenticity of the signed User ID to some degree.
 
 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.
@@ -100,7 +123,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
+#### 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.
@@ -110,14 +133,7 @@ By marking the expiration date subpacket as critical, the user can indicate, tha
 Sections 5.2.3.11 - 5.2.3.36 give guidance on which subpackets are usually marked as critical.
 
 
-(direct_key_signature)=
-#### Direct key signature
-
-```{admonition} TODO
-explain metadata associated with this signature, and that c-r prefers this over primary user id.
-```
-
-## Self-signatures
+## 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.
 
@@ -176,9 +192,7 @@ Linking an OpenPGP signing subkey to the primary key with a binding signature, a
 This additional "Primary Key Binding" Signature is informally called a "back signature" (because the subkey uses the signature to point "back" to the primary key) is an embedded `PrimaryKeyBinding` "back signature" (type 0x19).
 
 
-
-
-### Certifying identities
+### Binding identities to a certificate
 
 "User ID" identity components are bound to an OpenPGP certificate by issuing a self-signature ("User Attributes" work analogously).
 
@@ -194,7 +208,15 @@ Linking a User ID to an OpenPGP certificate
 
 This signature is calculated over the primary key and User ID.
 
-### Revocations
+
+(direct_key_signature)=
+### Direct key signature: Adding metadata to the primary key
+
+```{admonition} TODO
+explain metadata associated with this signature, and that c-r prefers this over primary user id.
+```
+
+### Revocations: Invalidating components of a certificate
 
 ```{admonition} TODO
 :class: warning
@@ -215,13 +237,15 @@ Contrary, a hard revocation cannot be re-validated. Furthermore, a hard-revoked
 
 A missing revocation reason subpacket is equivalent with a hard revocation reason.
 
+## Third-party signatures: Making statements about other people's certificates and identities 
 
+```{admonition} TODO
+:class: warning
 
-## Third-party signatures
+write
+```
 
-------
-
-## Advanced 
+## Advanced topics
 
 ### Certification Recipes