From 1b5edc1774ae3ca1891cd35148fc0d0c9281eeff Mon Sep 17 00:00:00 2001 From: Heiko Schaefer Date: Sat, 11 Nov 2023 18:37:14 +0100 Subject: [PATCH] ch7: clarify CSF and its use --- book/source/07-signing_data.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/book/source/07-signing_data.md b/book/source/07-signing_data.md index 6d9b541..cc0385c 100644 --- a/book/source/07-signing_data.md +++ b/book/source/07-signing_data.md @@ -106,23 +106,22 @@ 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". +A cleartext signature consists of two blocks. These blocks 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. +Notice that the message in the first block is readable by a human reader, without requiring additional software tools, as long as the reader knows where to look, and which elements to ignore. -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. +The second block contains an ASCII-armored OpenPGP signature for the message. Using this signature, OpenPGP software can verify the authenticity of the message. -#### Use-case +#### Use-cases -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. +Clear text signatures combine two of the benefits of detached and inline-signatures: -```{admonition} TODO -:class: warning +- They are self-contained, the message and signature can be stored as a single file +- The message remains human-readable, without requiring additional software tooling -(Ask David for details:) +This combination can be attractive for processes where signed messages are handled in a partially manual manner, and stored in a system that doesn't have strong support for OpenPGP in that particular workflow[^arch-certifications]. -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). -``` +[^arch-certifications]: For example, Arch Linux uses a workflow to certify User IDs of new packagers that relies on [cleartext signed statements by established 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 in an issue tracker system, as attachments, for later inspection. In this use case, it is convenient that the message and the signature are stored as one combined file (not as separate ones which would be more tedious to handle manually), and that the message is easy to read. Based on the vouches in these cleartext signed messages, and an [email confirmation by the new packager](https://gitlab.archlinux.org/archlinux/archlinux-keyring/-/wikis/workflows/verify-a-packager-key), main signing key operators issue OpenPGP third-party certifications. #### Text transformations for cleartext signatures