Expand glossary entries for inline signatures forms.

(This mirrors section 10.3 in c-r)

book/source/glossary.md

@@ -224,7 +224,14 @@ Initial Introducer
     An {term}`OpenPGP Certificate` explicitly {term}`delegated<Delegation>` to from a {term}`Trust Anchor`.
 
 Inline Signature
-    A {term}`Data Signature` which exists encapsulated alongside the data it was created for in an OpenPGP container. See [](forms-of-data-signatures).
+    An [inline signature](inline-signature) is a type of {term}`OpenPGP message` which stores a {term}`Data Signature` alongside the message it signs. Both the message and the signature are stored in a shared OpenPGP container.
+     
+    The standard defines two variant formats for inline signatures:
+     
+    - {term}`One-pass signed Message`: This format is now commonly used.
+    - {term}`Prefixed signed Message`: This is a historical format. It is still supported, but rarely used.
+      
+    For more context, see [](forms-of-data-signatures).
 
 Issuer
     An entity, that created an {term}`OpenPGP Signature Packet` using an {term}`Transferable Secret Key`.
@@ -315,8 +322,10 @@ Notation Tag
 One-pass Signature Packet
     One or more {term}`packets<Packet>` before the actual data in a {term}`Data Signature` which contain information to allow a receiving {term}`implementation<OpenPGP Implementation>` to create {term}`hashes<Hash Digest>` required for signature verification. See [RFC 5.4](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#one-pass-sig) for more details.
 
-One-pass-signed Message
-    A {term}`OpenPGP Message` signed using one or more {term}`One-pass signatures<One-pass Signature Packet>`.
+One-pass signed Message
+    The commonly used form of an OpenPGP {term}`Inline Signature`. It combines an {term}`OpenPGP Message` with {term}`signature packets<OpenPGP Signature Packet>` and accompanying auxiliary {term}`One-pass signatures<One-pass Signature Packet>`.
+    
+    For details see [](one-pass-signature).
 
 OpenPGP Certificate
     An OpenPGP certificate contains public key material, identity claims and third party certifications (but no private key material)
@@ -408,8 +417,10 @@ Preferred AEAD Ciphersuites Subpacket
 
     See [RFC 5.2.3.15](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-preferred-aead-ciphersuites)
 
-Prefixed-Signed Message
-    An {term}`OpenPGP Message` with one or more prefixed {term}`signature packets<OpenPGP Signature Packet>`.
+Prefixed signed Message
+    A type of {term}`Inline Signature`. This form of {term}`Inline Signature` is historical and now rarely used. Superseded by {term}`One-pass signed Message`.
+     
+     For details see [](prefixed-signature).
 
 Primary Component Key
     See {term}`OpenPGP Primary Key`.

book/source/signing_data.md

@@ -26,7 +26,7 @@ Note that {term}`data signatures<Data Signature>` are distinct from [](/signing_
 
 {term}`Data signatures<Data Signature>` are generated by {term}`hashing<Hash Digest>` the message content along with the {term}`metadata` in the {term}`OpenPGP signature packet`, and calculating a {term}`cryptographic signature` over that {term}`hash<Hash Digest>`. The resulting {term}`cryptographic signature` is stored in the {term}`signature packet<OpenPGP Signature Packet>`.
 
-{term}`Data signature packets<Data Signature Packet>` manifest in three distinct forms, which will be detailed in the subsequent section.
+{term}`Data signatures<Data Signature>` manifest in three distinct forms, which will be detailed in the subsequent section.
 
 (forms-of-data-signatures)=
 ## Forms of OpenPGP data signatures
@@ -39,27 +39,34 @@ Note that {term}`data signatures<Data Signature>` are distinct from [](/signing_
 
 [^sign-modes-gpg]: These three forms of {term}`signature<OpenPGP Signature Packet>` application align with GnuPG's `--detach-sign`, `--sign`, and `--clearsign` command options.
 
-### Detached signatures
+## Detached signatures
 
 A {term}`detached signature` is produced by calculating an {term}`OpenPGP signature<OpenPGP Signature Packet>` over the data intended for signing. The original data remains unchanged, and the {term}`OpenPGP signature<OpenPGP Signature Packet>` is stored as a standalone file. A {term}`detached signature` file can be distributed alongside or independent of the original data. The {term}`authenticity<Authentication>` and integrity of the original data file can be {term}`verified<Verification>` by using the {term}`detached signature` file.
 
 This {term}`signature<OpenPGP Signature Packet>` format is especially useful for signing software releases and other files where it is imperative that the content remains unaltered during the signing process.
 
 (inline-signature)=
-### Inline signatures
+## Inline signatures
 
 An {term}`inline signature` joins the signed data and its corresponding {term}`data signature` into a single {term}`OpenPGP message`.
 
 This method is commonly used for signing or encrypting emails. Most email software capable of handling OpenPGP communications typically uses {term}`inline signatures<Inline Signature>`.
 
+OpenPGP defines two variant forms of inline-signed messages:
+
+1. **{term}`One-pass signed messages<One-pass signed Message>`** This is the commonly used format for inline-signed messages. A signer can produce this format in one pass.
+2. **{term}`Prefixed signed messages<Prefixed signed Message>`** This format predates[^inline-signature-formats] {term}`one-pass signed messages<One-pass signed Message>` and is conceptually slightly simpler. However, it has no strong benefits and is now rarely used.
+
+[^inline-signature-formats]: One-pass signing was first specified in RFC 2440. The format was not supported in PGP 2.6.x.
+
+(one-pass-signature)=
+### One-pass signed message
+
+This is the commonly used format for inline signed messages.
+
 #### Structure
 
-There are two different constructions available to generate inline-signed messages:
-
-* {term}`One-pass-signed messages<One-pass-signed Message>` are signed using one or more {term}`one-pass signatures<One-pass Signature Packet>` 
-* {term}`Prefixed-signed messages<Prefixed-signed Message>` have the actual signature(s) prefixed to the {term}`OpenPGP message<OpenPGP Message>`.
-
-A {term}`one-pass-signed<One-pass-signed Message>` {term}`OpenPGP message` consists of three segments:
+A {term}`one-pass signed<One-pass signed Message>` {term}`OpenPGP message` consists of three segments:
 
 1. [**One-pass signature packets**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#one-pass-sig): These one or more {term}`packets<Packet>` precede the signed data and enable {term}`signature<OpenPGP Signature Packet>` computation in one pass.
 
@@ -67,7 +74,11 @@ A {term}`one-pass-signed<One-pass-signed Message>` {term}`OpenPGP message` consi
 
 3. **{term}`Data signature packets<OpenPGP Signature Packet>`**: These contain the {term}`cryptographic signature` corresponding to the original data.
 
-Less commonly used are {term}`prefixed-signed messages<Prefixed-signed Message>`, where the {term}`signature packet(s)<signature packet>` are simply prepended to the message.
+```{note}
+Despite its name, a {term}`one-pass signature packet` is not a type of {term}`signature packet<OpenPGP Signature Packet>`.
+
+Instead, it's a type of auxiliary packet that can be used in conjunction with {term}`signature packets<OpenPGP Signature Packet>`. Its use allows storing the {term}`signature packets<OpenPGP Signature Packet>` after the message body. 
+```
 
 #### Creation
 
@@ -75,29 +86,51 @@ To produce an {term}`inline signature`, the {term}`signer` processes the entiret
 
 For efficient {term}`verification`, an application must understand how to handle the {term}`literal data<Literal Data Packet>` prior to its reading. This requirement is addressed by the {term}`one-pass signature packets<One-pass Signature Packet>` located at the beginning of {term}`inline-signed<Inline Signature>` messages. These {term}`packets<Packet>` include essential information such as the {term}`fingerprint<OpenPGP Fingerprint>` of the {term}`signing key<OpenPGP Component Key>` and the {term}`hash<Hash Digest>` algorithm used for computing the {term}`signature<OpenPGP Signature Packet>`'s {term}`hash digest`. This setup enables the verifier to process the data correctly and efficiently.
 
-Strictly speaking, knowing just the hash algorithm would be sufficient to begin the verification process. However, having efficient access to the signer's fingerprint or key ID upfront allows OpenPGP software to fetch the signer's certificates before processing the entirety of the - potentially large - signed data, and .
+Strictly speaking, knowing just the hash algorithm would be sufficient to begin the verification process. However, having efficient access to the signer's fingerprint or key ID upfront allows OpenPGP software to fetch the signer's certificate(s) before processing the entirety of the - potentially large - signed data. This may, for example, involve downloading the certificate from a keyserver. In case fetching the signer's certificate(s) fails, or requires additional input from the user, it is better to signal the user about this before processing the data.
 
 #### Verification
 
 {term}`Inline-signed<Inline Signature>` messages enable efficient {term}`verification` in *one pass*, structured as follows:
 
 1. **Initiation with {term}`one-pass signature packets<One-pass Signature Packet>`**: These {term}`packets<Packet>` begin the {term}`verification` process. They include the {term}`signer`'s {term}`key ID`/{term}`fingerprint<OpenPGP Fingerprint>`, essential for identifying the appropriate {term}`public key<OpenPGP Certificate>` for signature {term}`validation`.
-   
+
 2. **Processing the {term}`literal data packet`**: This step involves {term}`hashing<Hash Digest>` the literal data, preparing it for {term}`signature<OpenPGP Signature Packet>` {term}`verification`.
 
 3. **{term}`Verifying<Verification>` {term}`signature packets<OpenPGP Signature Packet>`**: Located at the end of the message, these {term}`packets<Packet>` are checked against the previously calculated {term}`hash digest`.
 
 Important to note, the {term}`signer`'s {term}`public key<OpenPGP Certificate>`, critical for the final {term}`verification` step, is not embedded in the message. Verifiers must acquire this {term}`key` externally (e.g., from a {term}`key server`) to authenticate the {term}`signature<OpenPGP Signature Packet>` successfully. 
 
+(prefixed-signature)=
+### Prefixed signed message
+
+A {term}`prefixed signed message` consists of {term}`signature packet(s)<signature packet>` followed by the message. This inline signature format serves the same function as a {term}`one-pass signed message`. For the verifier, the two formats are equally convenient. However, on the signer's side, it takes more computational work to generate a {term}`prefixed signed message`.
+
+#### Structure
+
+In this format, the signature packets are stored ahead of the message itself:
+
+1. **{term}`Data signature packets<OpenPGP Signature Packet>`**: These one or more packets contain the {term}`cryptographic signature` corresponding to the original data.
+
+2. [**Literal data packet**](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#lit): This contains the original data (e.g., the body of a message), without additional interpretation or conversion.
+
+Compared to a {term}`one-pass signed message`, there are no {term}`one-pass signature packets<One-pass Signature Packet>` in this format, and the (otherwise equivalent) {term}`signature packet(s)<signature packet>` are stored ahead of the signed data.
+
+For verification, this is equally convenient as the one-pass signed message form.
+
+However, when a signer creates a {term}`prefixed signed message`, the signed data must be processed twice:
+
+- once reading it to calculate the cryptographic signature, and
+- once more to store the data in the generated OpenPGP message, after the signature packet(s).
+
 (cleartext-signature)=
-### Cleartext signatures
+## Cleartext signatures
 
 The *{term}`Cleartext Signature Framework`* (CSF) in OpenPGP accomplishes two primary objectives:
 
 - maintaining the message in a human-readable cleartext format, accessible without OpenPGP-specific software
 - incorporating an {term}`OpenPGP signature<OpenPGP Signature Packet>` for {term}`authentication` by users with OpenPGP-compatible software
 
-#### Example
+### Example
 
 The following is a detailed example of a {numref}`cleartext` signature:
 
@@ -118,7 +151,7 @@ r13/eqMN8kfCDw==
 
 This {term}`signature<Cleartext Signature>` consists of two parts: a message ("hello world") and an ASCII-armored {term}`OpenPGP signature<OpenPGP Signature Packet>`. The message is immediately comprehensible to a human reader, while the {term}`signature<OpenPGP Signature Packet>` block allows for the message's {term}`authenticity<Authentication>` {term}`verification` via OpenPGP software.
 
-#### Use case
+### Use case
 
 {term}`Cleartext signatures<Cleartext Signature>` combine the advantages of both {term}`detached<Detached Signature>` and {term}`inline signatures<Inline Signature>`:
 
@@ -130,7 +163,7 @@ These features are particularly beneficial in scenarios where signed messages ar
 
 [^arch-certifications]: An illustrative example is the workflow adopted by Arch Linux to {term}`certify<Certification>` {term}`User IDs<User ID>` of new packagers. This process relies on [cleartext signed statements from existing packagers](https://gitlab.archlinux.org/archlinux/archlinux-keyring/-/blob/master/.gitlab/issue_templates/New%20Packager%20Key.md?ref_type=heads&plain=1#L33-46). These signed statements are stored as attachments in an issue tracking system for later inspection. The advantage of this approach lies in the convenience of having the message and signature in a single file, which simplifies manual handling. Based on the vouches in these {term}`cleartext signed<Cleartext Signature>` messages and an [email confirmation from the new packager](https://gitlab.archlinux.org/archlinux/archlinux-keyring/-/wikis/workflows/verify-a-packager-key), the main key operators can issue {term}`OpenPGP third-party certifications<Third-party Identity Certification>`.
 
-#### Text transformations for cleartext signatures
+### Text transformations for cleartext signatures
 
 The {term}`cleartext signature framework` includes specific text normalization procedures to ensure the integrity and clarity of the message:
 
@@ -138,7 +171,7 @@ The {term}`cleartext signature framework` includes specific text normalization p
 
 - **Normalization of line endings**: Consistent with the approach for any other [text signature](data-signature-types), a {term}`cleartext signature` is calculated on the text with normalized line endings (`<CR><LF>`). This ensures that the {term}`signature<OpenPGP Signature Packet>` remains valid regardless of the text format of the receiving {term}`implementation<OpenPGP Implementation>`.
 
-#### Pitfalls
+### Pitfalls
 
 Despite their widespread adoption, {term}`cleartext signatures<Cleartext Signature>` have their limitations and are sometimes viewed as a "legacy method"[^csf-gnupg]. The {term}`RFC` details the [pitfalls of cleartext signatures](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-issues-with-the-cleartext-s), such as incompatibility with semantically meaningful whitespace, challenges with large messages, and security vulnerabilities related to misleading Hash header manipulations. Given these issues, safer alternatives like {term}`inline<Inline Signature>` and {term}`detached signature` forms are advised.