From 29ed6e6e9b442e598ecf8475fd5863051dfaf4fd Mon Sep 17 00:00:00 2001 From: vladislav doster Date: Sun, 28 Nov 2021 13:00:47 -0600 Subject: [PATCH 1/2] (docs): update `project-security/verifying-signatures.md` - use active voice where applicable - add articles - add `shell_session` to code fences to match document style - reword phrases to increase readability & reduce verbiage --- project-security/verifying-signatures.md | 52 ++++++++++++------------ 1 file changed, 25 insertions(+), 27 deletions(-) diff --git a/project-security/verifying-signatures.md b/project-security/verifying-signatures.md index 5cdfc45c..9bc07311 100644 --- a/project-security/verifying-signatures.md +++ b/project-security/verifying-signatures.md @@ -25,8 +25,8 @@ even if it looks trivial at first sight. Digital signatures can prove both **authenticity** and **integrity** to a reasonable degree of certainty. **Authenticity** ensures that a given file was -indeed created by the person who signed it (i.e., that it was not forged by a -third party). **Integrity** ensures that the contents of the file have not been +indeed created by the person who signed it (i.e., that a +third party did not forge it). **Integrity** ensures that the contents of the file have not been tampered with (i.e., that a third party has not undetectably altered its contents *en route*). @@ -35,15 +35,14 @@ malicious. In fact, there is nothing that could stop someone from signing a malicious program (and it happens from time to time in reality). The point is that we must decide who we will trust (e.g., Linus Torvalds, -Microsoft, or the Qubes Project) and assume that if a given file was signed by -a trusted party, then it should not be malicious or negligently buggy. The +Microsoft, or the Qubes Project) and assume that if a trusted party signed a given file, then it should not be malicious or negligently buggy. The decision of whether to trust any given party is beyond the scope of digital signatures. It's more of a social and political decision. -Once we make the decision to trust certain parties, digital signatures are +Once we decide to trust certain parties, digital signatures are useful, because they make it possible for us to limit our trust only to those few parties we choose and not to worry about all the bad things that can happen -between us and them, e.g., server compromises (qubes-os.org will surely be +between them and us, e.g., server compromises (qubes-os.org will surely be compromised one day, so [don't blindly trust the live version of this site](/faq/#should-i-trust-this-website)), dishonest IT staff at the hosting company, dishonest staff at the ISPs, Wi-Fi attacks, etc. We call this @@ -56,8 +55,8 @@ above, since we can easily detect whether any files have been tampered with (and subsequently choose to refrain from executing, installing, or opening them). -However, for digital signatures to make any sense, we must ensure that the -public keys we use for signature verification are indeed the original ones. +However, for digital signatures to make sense, we must ensure that the +public keys we use for signature verification are the original ones. Anybody can generate a cryptographic key that purports to belong to "The Qubes OS Project," but of course only the keys that we (the real Qubes developers) generate are the genuine ones. The rest of this page explains how to @@ -163,7 +162,7 @@ should not rely on any single website, not even over HTTPS. So, what *should* you do? One option is to use the PGP [Web of Trust](https://en.wikipedia.org/wiki/Web_of_trust). In addition, some operating -systems include the means to acquire the QMSK in a secure way. For example, on +systems include the means to acquire the QMSK securely. For example, on Fedora, `dnf install distribution-gpg-keys` will get you the QMSK along with several other Qubes keys. On Debian, your keyring may already contain the necessary keys. @@ -176,7 +175,7 @@ copy of it is authentic, simply by comparing the fingerprints. For example, here is the QMSK fingerprint: -``` +```shell_session pub 4096R/36879494 2010-04-01 Key fingerprint = 427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494 uid Qubes Master Signing Key @@ -185,7 +184,7 @@ uid Qubes Master Signing Key But how do you know that this is the real fingerprint? After all, [this website could be compromised](/faq/#should-i-trust-this-website), so the fingerprint you see here may not be genuine. That's why we strongly suggest obtaining the -fingerprint from *multiple, independent sources in several different ways*. +fingerprint from *multiple independent sources in several different ways*. Here are some ideas for how to do that: @@ -222,7 +221,7 @@ Now that you've imported the authentic QMSK, set its trust level to "ultimate" so that it can be used to automatically verify all the keys signed by the QMSK (in particular, RSKs). -``` +```shell_session $ gpg2 --edit-key 0x427F11FD0FAA4B080123F01CDDFA1A3E36879494 gpg (GnuPG) 1.4.18; Copyright (C) 2014 Free Software Foundation, Inc. This is free software: you are free to change and redistribute it. @@ -283,7 +282,7 @@ follow the instructions in this section carefully and consult the ## How to import and authenticate release signing keys Every Qubes OS release is signed by a **release signing key (RSK)**, which is -in turn signed by the Qubes Master Signing Key (QMSK). +in turn, signed by the Qubes Master Signing Key (QMSK). Before we proceed, you must first complete the following prerequisite steps: @@ -305,7 +304,7 @@ the RSK for your Qubes release. `/etc/pki/rpm-gpg/RPM-GPG-KEY-qubes-*`. If you wish to use one of these keys, make sure to import it into your keyring, e.g.: - ``` + ```shell_session $ gpg2 --import /etc/pki/rpm-gpg/RPM-GPG-KEY-qubes-* ``` @@ -341,18 +340,17 @@ gpg: 2 good signatures ``` This is just an example, so the output you receive will not look exactly the -same. What matters is the line that shows that this key is signed by the QMSK +same. What matters is the line that shows that the QMSK signs this key with a `sig!` prefix. This verifies the authenticity of the RSK. Note that the `!` flag after the `sig` tag is important because it means -that the key signature is valid. A `sig-` prefix would indicate a bad signature -and `sig%` would mean that gpg encountered an error while verifying the +that the key signature is valid. A `sig-` prefix would indicate a bad signature, and `sig%` would mean that gpg encountered an error while verifying the signature. It is not necessary to independently verify the authenticity of the RSK, since you already verified the authenticity of the QMSK. As a final sanity check, make sure the RSK is in your keyring with the correct trust level: -``` +```shell_session $ gpg2 -k "Qubes OS Release" pub rsa4096 2017-03-06 [SC] 5817A43B283DE5A9181A522E1848792F9E2795E9 @@ -387,12 +385,12 @@ Each Qubes ISO is accompanied by a set of **cryptographic hash values** contained in a plain text file ending in `.DIGESTS`, which can find on the [downloads](/downloads/) page alongside the ISO. This file contains the output of running several different cryptographic hash functions on the ISO (a process -known as "hashing") in order to obtain alphanumeric outputs known as "hash +known as "hashing") to obtain alphanumeric outputs known as "hash values" or "digests." One convenient property of hash values is that they can be generated on any computer. This means, for example, that you can download a Qubes ISO on one -computer, hash it, then visually compare that hash value to one you generated +computer, hash it, then visually compare that hash value to the one you generated or have saved on a different computer. In addition to the `.DIGESTS` files on the [downloads](/downloads/) page @@ -406,7 +404,7 @@ filename followed by `.DIGESTS`. Since the digest file is a plain text file, you can open it with any text editor. Inside, you should find text that looks similar to this: -``` +```shell_session -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA256 @@ -455,7 +453,7 @@ sha512sum: WARNING: 23 lines are improperly formatted The `OK` response tells us that the hash value for that particular hash function matches. The program also warns us that there are 23 improperly -formatted lines, but this is to be expected. This is because each file contains +formatted lines, but this is expected. This is because each file contains lines for several different hash values (as mentioned above), but each `*sum` program verifies only the line for its own hash function. In addition, there are lines for the PGP signature that the `*sum` programs do not know how to @@ -497,7 +495,7 @@ gpg: textmode signature, digest algorithm SHA256 This is just an example, so the output you receive will not look exactly the same. What matters is the line that says `Good signature from "Qubes OS Release -X Signing Key"`. This confirms that the signature on digest file is good. +X Signing Key"`. This confirms that the signature on the digest file is good. If you don't see a good signature here, go back and follow the instructions in this section carefully, and consult the [troubleshooting @@ -575,7 +573,7 @@ properly authenticated keys rather than relying on a third party, such as GitHub. While the GitHub interface may claim that a commit has a verified signature from a member of the Qubes team, this is only trustworthy if GitHub has performed the signature check correctly, the account identity is authentic, -the user's key has not been replaced by an admin, GitHub's servers have not +an admin has not replaced the user's key, GitHub's servers have not been compromised, and so on. Since there's no way for you to be certain that all such conditions hold, you're much better off verifying signatures yourself. (Also see: [distrusting the @@ -616,7 +614,7 @@ key](#how-to-import-and-authenticate-release-signing-keys). The problem could be one or more of the following: -- You're trying to verify the wrong file(s). Read this page again carefully. +- You're trying to verify the wrong file(s). Reread this page carefully. - You're using the wrong GPG command. Follow the provided examples carefully, or try using `gpg` instead of `gpg2` (or vice versa). - The ISO or [detached PGP signature @@ -676,7 +674,7 @@ your Qubes release. ### Why am I seeing additional signatures on a key with "[User ID not found]" or from a revoked key? -This is just a basic part of how OpenPGP works. Anyone can sign anyone else's +This is just a fundamental part of how OpenPGP works. Anyone can sign anyone else's public key and upload the signed public key to keyservers. Everyone is also free to revoke their own keys at any time (assuming they possess or can create a revocation certificate). This has no impact on verifying Qubes ISOs, code, or @@ -718,7 +716,7 @@ The correct ISO is not in your working directory. ### I have another problem that isn't mentioned here. -Carefully read this page again to be certain that you didn't skip any steps. In +Carefully reread this page to be certain that you didn't skip any steps. In particular, make sure you have the [Qubes Master Signing Key](#how-to-import-and-authenticate-the-qubes-master-signing-key), the [release signing key](#how-to-import-and-authenticate-release-signing-keys) for From 3bee60ec01daa4828c210e91b80131046d2af512 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Tue, 30 Nov 2021 03:12:56 -0800 Subject: [PATCH 2/2] Copyedit; wrap text --- project-security/verifying-signatures.md | 40 +++++++++++++----------- 1 file changed, 22 insertions(+), 18 deletions(-) diff --git a/project-security/verifying-signatures.md b/project-security/verifying-signatures.md index 9bc07311..a4d0e998 100644 --- a/project-security/verifying-signatures.md +++ b/project-security/verifying-signatures.md @@ -25,8 +25,8 @@ even if it looks trivial at first sight. Digital signatures can prove both **authenticity** and **integrity** to a reasonable degree of certainty. **Authenticity** ensures that a given file was -indeed created by the person who signed it (i.e., that a -third party did not forge it). **Integrity** ensures that the contents of the file have not been +indeed created by the person who signed it (i.e., that a third party did not +forge it). **Integrity** ensures that the contents of the file have not been tampered with (i.e., that a third party has not undetectably altered its contents *en route*). @@ -35,9 +35,10 @@ malicious. In fact, there is nothing that could stop someone from signing a malicious program (and it happens from time to time in reality). The point is that we must decide who we will trust (e.g., Linus Torvalds, -Microsoft, or the Qubes Project) and assume that if a trusted party signed a given file, then it should not be malicious or negligently buggy. The -decision of whether to trust any given party is beyond the scope of digital -signatures. It's more of a social and political decision. +Microsoft, or the Qubes Project) and assume that if a trusted party signed a +given file, then it should not be malicious or negligently buggy. The decision +of whether to trust any given party is beyond the scope of digital signatures. +It's more of a social and political decision. Once we decide to trust certain parties, digital signatures are useful, because they make it possible for us to limit our trust only to those @@ -116,7 +117,9 @@ Now, there are several ways to get the QMSK. $ gpg2 --import /usr/share/qubes/qubes-master-key.asc ``` -- If you're on Fedora, you can get it in the [distribution-gpg-keys](https://github.com/xsuchy/distribution-gpg-keys) package: +- If you're on Fedora, you can get it in the + [distribution-gpg-keys](https://github.com/xsuchy/distribution-gpg-keys) + package: ```shell_session $ dnf install distribution-gpg-keys @@ -281,7 +284,7 @@ follow the instructions in this section carefully and consult the ## How to import and authenticate release signing keys -Every Qubes OS release is signed by a **release signing key (RSK)**, which is +Every Qubes OS release is signed by a **release signing key (RSK)**, which is, in turn, signed by the Qubes Master Signing Key (QMSK). Before we proceed, you must first complete the following prerequisite steps: @@ -339,13 +342,14 @@ sig! DDFA1A3E36879494 2017-03-08 Qubes Master Signing Key gpg: 2 good signatures ``` -This is just an example, so the output you receive will not look exactly the -same. What matters is the line that shows that the QMSK signs this key -with a `sig!` prefix. This verifies the authenticity of the -RSK. Note that the `!` flag after the `sig` tag is important because it means -that the key signature is valid. A `sig-` prefix would indicate a bad signature, and `sig%` would mean that gpg encountered an error while verifying the -signature. It is not necessary to independently verify the authenticity of the -RSK, since you already verified the authenticity of the QMSK. +This is just an example, so the output you receive may not look exactly the +same. What matters is the line with a `sig!` prefix showing that the QMSK has +signed this key. This verifies the authenticity of the RSK. Note that the `!` +flag after the `sig` tag is important because it means that the key signature +is valid. A `sig-` prefix would indicate a bad signature, and `sig%` would mean +that gpg encountered an error while verifying the signature. It is not +necessary to independently verify the authenticity of the RSK, since you +already verified the authenticity of the QMSK. As a final sanity check, make sure the RSK is in your keyring with the correct trust level: @@ -385,13 +389,13 @@ Each Qubes ISO is accompanied by a set of **cryptographic hash values** contained in a plain text file ending in `.DIGESTS`, which can find on the [downloads](/downloads/) page alongside the ISO. This file contains the output of running several different cryptographic hash functions on the ISO (a process -known as "hashing") to obtain alphanumeric outputs known as "hash -values" or "digests." +known as "hashing") to obtain alphanumeric outputs known as "hash values" or +"digests." One convenient property of hash values is that they can be generated on any computer. This means, for example, that you can download a Qubes ISO on one -computer, hash it, then visually compare that hash value to the one you generated -or have saved on a different computer. +computer, hash it, then visually compare that hash value to the one you +generated or have saved on a different computer. In addition to the `.DIGESTS` files on the [downloads](/downloads/) page alongside each ISO, and you can always find all the digest files for every