Edits (in part based on feedback from David)

book/source/07-signing_data.md

@@ -8,13 +8,15 @@ SPDX-License-Identifier: CC-BY-SA-4.0
 
 A data signature guarantees the authenticity (and implicitly also the integrity) of a message, e.g., an email or a file.
 
+More specifically, when we say "authenticity", we mean that the signature guarantees that whoever controls the signing key material has issued that signature. The question of who controls that key material is a separate concern. We might independently want to verify that our intended communication partner uses the cryptographic identity in question.
+
 Note that signatures over data are different from {ref}`component_signatures_chapter`, which are used to attach metadata or subkeys to a certificate.
 
-One major use case for OpenPGP is to create signatures for software packages or emails. These are examples for signatures over data, with OpenPGP.
+Typical use cases for signatures over data in OpenPGP are signatures for software packages or emails.
 
-When signing data, OpenPGP offers the advantage that it comes with mechanisms for strong authentication, based on bindings between certificates and identities, and the option to certify those bindings.
+When signing data, OpenPGP offers mechanisms for strong authentication, based on bindings between certificates and identities, and the option to verify those bindings.
 
-Other signing solutions, like [signify](https://flak.tedunangst.com/post/signify), typically only offer a solution for pure signing, without offering 
+Other signing solutions, such as [signify](https://flak.tedunangst.com/post/signify), typically only offer a solution for pure signing, without offering 
 a mechanism for authentication.
 
 ## Signature types
@@ -29,7 +31,7 @@ Binary signatures are calculated over the data "as is", without performing any t
 Data signatures are always calculated by a component key that carries the *signing* key flag.
 
 Data signatures are created by hashing the message content and calculating a cryptographic signature over the hash.
-The resulting cryptographic signature is stored in an OpenPGP signature packet, which can be used in different ways:
+The resulting cryptographic signature is stored in an OpenPGP signature packet, which can be used in different ways. We'll discuss these in the following sections.
 
 ## Forms of OpenPGP data signatures
 
@@ -43,11 +45,11 @@ OpenPGP signatures over data can be generated and distributed in three forms[^si
 
 ### Detached signatures
 
+This method is especially useful for signing software releases and other files that must not be modified by the signing process.
+
 A detached signature is produced by calculating an OpenPGP signature over a piece of data.
 The resulting OpenPGP signature packet can then be distributed alongside or independent of the original data.
 
-This method is especially useful for signing software releases and other files that must not be modified by the signing process.
-
 ### Inline signatures
 
 This method is usually used with signed and/or encrypted emails.
@@ -55,10 +57,10 @@ This method is usually used with signed and/or encrypted emails.
 Most clients that support OpenPGP for encrypted and/or signed messages make use of inline-signatures.
 To produce a signature, the entirety of the data needs to be processed by the producer. This has the consequence that an application that efficiently emits signed data can only append the signature at the end of the data stream.
 On the other hand, an application that needs to efficiently verify signed data needs to know the signer's public key and used hash algorithm before processing the data.
-To solve this issue, so-called One-Pass-Signature packets are prefixed to the signed data. Those are small packets containing the fingerprint of the signing key, as well as the used hash algorithm. This is all the information a receiving application needs to know to initiate the verification process.
+To solve this issue, so-called One-Pass Signature packets are prefixed to the signed data. Those are small packets containing the fingerprint of the signing key, as well as the used hash algorithm. This is all the information a receiving application needs to know to initiate the verification process.
 
-To produce an inline-signed message, the original data is first wrapped in a Literal Data packet, which is prefixed with one or more One-Pass-Signature packets, and affixed with the corresponding signature packets.
-The verifying application can read the One-Pass-Signature packets and initiate the verification process.
+To produce an inline-signed message, the original data is first wrapped in a [Literal Data packet](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#lit), which is prefixed with one or more [One-Pass Signature packets](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#one-pass-sig), and affixed with the corresponding signature packets.
+The verifying application can read the One-Pass Signature packets and initiate the verification process.
 The literal data can then be processed, such that the signatures at the end of the message can be verified in *one pass*.
 
 TODO: explain nesting of OPSs.
@@ -68,10 +70,49 @@ TODO: explain nesting of OPSs.
 The *Cleartext Signature Framework* (CSF) is a mechanism that combines two goals:
 
 - It leaves the message in clear text format, so that it can be viewed directly by a human in a program that knows nothing about OpenPGP.
-- But also adds an OpenPGP signature that allows verification of that message by users whose software supports OpenPGP.
+- At the same time it adds an OpenPGP signature that allows verification of that message by users whose software supports OpenPGP.
+
+#### Example
+
+In {numref}`cleartext` we inspect an example of a cleartext signature in detail. Let's have a brief look at this example, here, to get a sense of what a cleartext signature looks like:
+
+```text
+-----BEGIN PGP SIGNED MESSAGE-----
+Hash: SHA512
+
+hello world
+-----BEGIN PGP SIGNATURE-----
+
+wpgGARsKAAAAKQWCZT0vBCIhBtB7JOyRoU3SQKwtU+bIqeBUlJpBIi6nOFdu0Zyu
+o9yZAAAAANqgIHAzoRTzu/7Zuxc8Izf4r3/qSCmBfDqWzTXqmVtsSBSHACka3qbN
+eehqu8H6S0UK8V7yHbpVhExu9Hu72jWEzU/B0h9MR5gDhJPoWurx8YfyXBDsRS4y
+r13/eqMN8kfCDw==
+=Ks9w
+-----END PGP SIGNATURE-----
+```
+
+The cleartext signature consists of two blocks, which contain the message and a signature, respectively. In this case the message consists of the text "hello world".
+
+Notice that this message is readable by a human reader, without requiring additional software tools, as long as the reader understands which elements to ignore.
+
+The message is followed by a block that contains an OpenPGP signature for the message, in ASCII armored form. Using OpenPGP software, this signature can be verified.
+
+#### Use-case
+
+One use-case for cleartext signatures is: Asking someone to sign some piece of data. The person who is asked to sign the data can easily inspect it with simple commandline tools, such as `cat`, and verify that they agree with the data they are asked to sign.
+
+We use this for example to verify User ID and primary key of Arch Linux packagers before signing the User IDs on their keys with the main signing keys and to verify the data claims when introducing new packagers (i.e. already established packagers vouch for the data of a new packager).
+
+#### Text transformations for cleartext signatures
 
 TODO: explain text transforms for cleartext signatures (LF->CRLF etc)
 
 #### Pitfalls
 
+Cleartext signatures are popular and have useful applications.
+
+At the same time, they are considered a "legacy method"[^csf-gnupg] by some.
+
+[^csf-gnupg]: https://lists.gnupg.org/pipermail/gnupg-devel/2023-November/035428.html
+
 The RFC points out a number of [pitfalls of cleartext signatures](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-issues-with-the-cleartext-s), and advises that in many cases, the inline and detached signature forms are preferable.