Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2024-10-01 01:25:40 -04:00
Code Issues Packages Projects Releases Wiki Activity

(docs): update project-security/verifying-signatures.md

Browse Source 
- use active voice where applicable
- add articles
- add `shell_session` to code fences to match document style
- reword phrases to increase readability & reduce verbiage
This commit is contained in:
vladislav doster 2021-11-28 13:00:47 -06:00 committed by GitHub
parent f457e274ee
commit 29ed6e6e9b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 25 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

52
project-security/verifying-signatures.md
View File

@ -25,8 +25,8 @@ even if it looks trivial at first sight.
Digital signatures can prove both **authenticity** and **integrity** to a Digital signatures can prove both **authenticity** and **integrity** to a
reasonable degree of certainty. **Authenticity** ensures that a given file was 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 indeed created by the person who signed it (i.e., that a
third party). **Integrity** ensures that the contents of the file have not been 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 tampered with (i.e., that a third party has not undetectably altered its
contents *en route*). 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). 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, 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 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
a trusted party, then it should not be malicious or negligently buggy. The
decision of whether to trust any given party is beyond the scope of digital decision of whether to trust any given party is beyond the scope of digital
signatures. It's more of a social and political decision. 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 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 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 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 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 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 (and subsequently choose to refrain from executing, installing, or opening
them). them).
However, for digital signatures to make any sense, we must ensure that the However, for digital signatures to make sense, we must ensure that the
public keys we use for signature verification are indeed the original ones. public keys we use for signature verification are the original ones.
Anybody can generate a cryptographic key that purports to belong to "The Qubes 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) 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 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 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 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 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 several other Qubes keys. On Debian, your keyring may already contain the
necessary keys. necessary keys.
@ -176,7 +175,7 @@ copy of it is authentic, simply by comparing the fingerprints.
For example, here is the QMSK fingerprint: For example, here is the QMSK fingerprint:
``` ```shell_session
pub 4096R/36879494 2010-04-01 pub 4096R/36879494 2010-04-01
Key fingerprint = 427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494 Key fingerprint = 427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494
uid Qubes Master Signing Key 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 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 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 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: 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 so that it can be used to automatically verify all the keys signed by the QMSK
(in particular, RSKs). (in particular, RSKs).
``` ```shell_session
$ gpg2 --edit-key 0x427F11FD0FAA4B080123F01CDDFA1A3E36879494 $ gpg2 --edit-key 0x427F11FD0FAA4B080123F01CDDFA1A3E36879494
gpg (GnuPG) 1.4.18; Copyright (C) 2014 Free Software Foundation, Inc. gpg (GnuPG) 1.4.18; Copyright (C) 2014 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it. 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 ## 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). in turn, signed by the Qubes Master Signing Key (QMSK).
Before we proceed, you must first complete the following prerequisite steps: 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, `/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.: make sure to import it into your keyring, e.g.:
``` ```shell_session
$ gpg2 --import /etc/pki/rpm-gpg/RPM-GPG-KEY-qubes-* $ 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 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 with a `sig!` prefix. This verifies the authenticity of the
RSK. Note that the `!` flag after the `sig` tag is important because it means 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 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
and `sig%` would mean that gpg encountered an error while verifying the
signature. It is not necessary to independently verify the authenticity of the signature. It is not necessary to independently verify the authenticity of the
RSK, since you already verified the authenticity of the QMSK. 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 As a final sanity check, make sure the RSK is in your keyring with the correct
trust level: trust level:
``` ```shell_session
$ gpg2 -k "Qubes OS Release" $ gpg2 -k "Qubes OS Release"
pub rsa4096 2017-03-06 [SC] pub rsa4096 2017-03-06 [SC]
5817A43B283DE5A9181A522E1848792F9E2795E9 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 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 [downloads](/downloads/) page alongside the ISO. This file contains the output
of running several different cryptographic hash functions on the ISO (a process 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." values" or "digests."
One convenient property of hash values is that they can be generated on any 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. 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. or have saved on a different computer.
In addition to the `.DIGESTS` files on the [downloads](/downloads/) page 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 you can open it with any text editor. Inside, you should find text that looks
similar to this: similar to this:
``` ```shell_session
-----BEGIN PGP SIGNED MESSAGE----- -----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256 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 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 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` 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 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 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 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 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 If you don't see a good signature here, go back and follow the instructions in
this section carefully, and consult the [troubleshooting 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 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 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, 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 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. all such conditions hold, you're much better off verifying signatures yourself.
(Also see: [distrusting the (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: 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, - You're using the wrong GPG command. Follow the provided examples carefully,
or try using `gpg` instead of `gpg2` (or vice versa). or try using `gpg` instead of `gpg2` (or vice versa).
- The ISO or [detached PGP signature - 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? ### 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 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 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 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. ### 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 particular, make sure you have the [Qubes Master Signing
Key](#how-to-import-and-authenticate-the-qubes-master-signing-key), the Key](#how-to-import-and-authenticate-the-qubes-master-signing-key), the
[release signing key](#how-to-import-and-authenticate-release-signing-keys) for [release signing key](#how-to-import-and-authenticate-release-signing-keys) for