diff --git a/book/source/07-signing_data.md b/book/source/07-signing_data.md index 618e80f..0c342a5 100644 --- a/book/source/07-signing_data.md +++ b/book/source/07-signing_data.md @@ -87,14 +87,14 @@ Important to note, the signer's public key, critical for the final verification ### Cleartext signatures -The *Cleartext Signature Framework* (CSF) is an OpenPGP mechanism that combines two goals: +The *Cleartext Signature Framework* (CSF) in OpenPGP accomplishes two primary objectives: -- 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. -- At the same time, it adds an OpenPGP signature that allows verification of that message by users whose software supports OpenPGP. +- maintaining the message in a human-readable cleartext format, accessible without OpenPGP-specific software +- incorporating an OpenPGP signature for authentication by users with OpenPGP-compatible software #### 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: +Below is a detailed example of a {numref}`cleartext` signature: ```text -----BEGIN PGP SIGNED MESSAGE----- @@ -111,15 +111,11 @@ r13/eqMN8kfCDw== -----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". +This signature is split into two parts: a message ("hello world") and an ASCII-armored OpenPGP signature. The message is immediately comprehensible to a human reader, while the signature block allows for the message's authenticity verification via OpenPGP software. -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. +#### Use case -The message is followed by a block that contains an ASCII-armored OpenPGP signature for the message. Using this signature, OpenPGP software can verify the authenticity of the message in the first block. - -#### 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. +A common use case is requesting someone to sign data. The signer can easily inspect the data using simple command line tools (e.g., `cat`) to verify that they agree with the content of the data before deciding to sign it. ```{admonition} TODO :class: warning @@ -139,14 +135,10 @@ explain text transformations for cleartext signatures (LF->CRLF and additional e #### Pitfalls -Cleartext signatures are popular and have useful applications. - -At the same time, they are considered a "legacy method"[^csf-gnupg] by some. +While widely used, cleartext signatures are sometimes considered a "legacy method"[^csf-gnupg]. The RFC outlines [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 inline and detached signature forms are often preferable. [^csf-gnupg]: https://lists.gnupg.org/pipermail/gnupg-devel/2023-November/035428.html -The RFC points out a number of specific [pitfalls of cleartext signatures](https://www.ietf.org/archive/id/draft-ietf-openpgp-crypto-refresh-12.html#name-issues-with-the-cleartext-s), and how to avoid them. It advises that in many cases, the inline and detached signature forms are preferable. - ## Advanced topics ### Nesting of one-pass signatures