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

Merge branch 'verifying-sigs-secpack'

Browse Source
This commit is contained in:
Andrew David Wong 2021-07-20 04:13:31 -07:00
commit e84a92fde3
No known key found for this signature in database
GPG Key ID: 8CE137352A019A17
6 changed files with 57 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
developer/building/qubes-iso-building.md
View File

@ -52,7 +52,7 @@ gpg --import qubes-developers-keys.asc
~~~ ~~~
**Note** In the above process, we do *not* rely on the security of our server (keys.qubes-os.org) nor the connection (ssl, cert) -- we only rely on you getting the Qubes Master Signing Key fingerprint *somehow* and ensuring they match! **Note** In the above process, we do *not* rely on the security of our server (keys.qubes-os.org) nor the connection (ssl, cert) -- we only rely on you getting the Qubes Master Signing Key fingerprint *somehow* and ensuring they match!
See [Verifying Signatures](/security/verifying-signatures/#1-get-the-qubes-master-signing-key-and-verify-its-authenticity) for verification sources. See [verifying signatures](/security/verifying-signatures/#how-to-import-and-authenticate-the-qubes-master-signing-key) for verification sources.
Now let's bootstrap the builder. Unfortunately, the builder cannot verify itself (the classic Chicken and Egg problem), so we need to verify the signature manually: Now let's bootstrap the builder. Unfortunately, the builder cannot verify itself (the classic Chicken and Egg problem), so we need to verify the signature manually:

2
introduction/faq.md
View File

@ -281,7 +281,7 @@ This website is hosted on [GitHub Pages](https://pages.github.com/) ([why?](#why
Therefore, it is largely outside of our control. Therefore, it is largely outside of our control.
We don't consider this a problem, however, since we explicitly [distrust the infrastructure](#what-does-it-mean-to-distrust-the-infrastructure). We don't consider this a problem, however, since we explicitly [distrust the infrastructure](#what-does-it-mean-to-distrust-the-infrastructure).
For this reason, we don't think that anyone should place undue trust in the live version of this site on the Web. For this reason, we don't think that anyone should place undue trust in the live version of this site on the Web.
Instead, if you want to obtain your own trustworthy copy of this website in a secure way, you should clone our [website repo](https://github.com/QubesOS/qubesos.github.io), [verify the PGP signatures on the commits and/or tags](/security/verifying-signatures/#how-to-verify-qubes-repos) signed by the [doc-signing keys](https://github.com/QubesOS/qubes-secpack/tree/master/keys/doc-signing) (which indicates that the content has undergone [review](/doc/how-to-edit-the-documentation/#security)), then either [render the site on your local machine](https://github.com/QubesOS/qubesos.github.io/blob/master/README.md#instructions) or simply read the source, the vast majority of which was [intentionally written in Markdown so as to be readable as plain text for this very reason](/doc/documentation-style-guide/#markdown-conventions). Instead, if you want to obtain your own trustworthy copy of this website in a secure way, you should clone our [website repo](https://github.com/QubesOS/qubesos.github.io), [verify the PGP signatures on the commits and/or tags](/security/verifying-signatures/#how-to-verify-signatures-on-git-repository-tags-and-commits) signed by the [doc-signing keys](https://github.com/QubesOS/qubes-secpack/tree/master/keys/doc-signing) (which indicates that the content has undergone [review](/doc/how-to-edit-the-documentation/#security)), then either [render the site on your local machine](https://github.com/QubesOS/qubesos.github.io/blob/master/README.md#instructions) or simply read the source, the vast majority of which was [intentionally written in Markdown so as to be readable as plain text for this very reason](/doc/documentation-style-guide/#markdown-conventions).
We've gone to special effort to set all of this up so that no one has to trust the infrastructure and so that the contents of this website are maximally available and accessible. We've gone to special effort to set all of this up so that no one has to trust the infrastructure and so that the contents of this website are maximally available and accessible.
### What does it mean to "distrust the infrastructure"? ### What does it mean to "distrust the infrastructure"?

7
project-security/security-pack.md
View File

@ -32,10 +32,11 @@ official location is:
<https://github.com/QubesOS/qubes-secpack> <https://github.com/QubesOS/qubes-secpack>
## How to obtain, verify, and read ## How to obtain and authenticate
The following example demonstrates one method of obtaining the qubes-secpack, The following example demonstrates one method of obtaining the qubes-secpack and
verifying its authenticity, and reading the contents. verifying its authenticity. This requires Git and [OpenPGP
software](/security/verifying-signatures/#openpgp-software).
1. Use Git to clone the qubes-secpack repo. 1. Use Git to clone the qubes-secpack repo.

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

@ -64,7 +64,7 @@ generate are the genuine ones. The next rest of this page explains how to
verify the authenticity of the various keys used in the project and how to use verify the authenticity of the various keys used in the project and how to use
those keys to verify certain important assets. those keys to verify certain important assets.
## How to obtain and authenticate PGP keys ## OpenPGP software
We use [PGP](https://en.wikipedia.org/wiki/Pretty_Good_Privacy) (specifically, We use [PGP](https://en.wikipedia.org/wiki/Pretty_Good_Privacy) (specifically,
the [OpenPGP](https://en.wikipedia.org/wiki/Pretty_Good_Privacy#OpenPGP) the [OpenPGP](https://en.wikipedia.org/wiki/Pretty_Good_Privacy#OpenPGP)
@ -90,22 +90,25 @@ work for you, try `gpg` instead. If that still doesn't work, please consult the
documentation for your specific program (see links above) and the documentation for your specific program (see links above) and the
[troubleshooting FAQ](#troubleshooting-faq) below. [troubleshooting FAQ](#troubleshooting-faq) below.
### How to import and authenticate the Qubes Master Signing Key ## How to import and authenticate the Qubes Master Signing Key
Many important Qubes OS Project assets (e.g., ISOs, RPMs, TGZs, and Git Many important Qubes OS Project assets (e.g., ISOs, RPMs, TGZs, and Git
objects) are digitally signed by an official team member's key or by a release objects) are digitally signed by an official team member's key or by a release
signing key (RSK). Each such key is, in turn, signed by the [Qubes Master signing key (RSK). Each such key is, in turn, signed by the [**Qubes Master
Signing Key Signing Key
(QMSK)](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc) (QMSK)**](https://keys.qubes-os.org/keys/qubes-master-signing-key.asc)
(`0x427F11FD0FAA4B080123F01CDDFA1A3E36879494`). In this way, the QMSK is the (`0x427F11FD0FAA4B080123F01CDDFA1A3E36879494`). In this way, the QMSK is the
ultimate root of trust for the Qubes OS Project. ultimate root of trust for the Qubes OS Project.
The developer signing keys are set to expire after one year, while the QMSK and The developer signing keys are set to expire after one year, while the QMSK and
RSKs have no expiration date. Th QMSK was generated on and is kept only on a RSKs have no expiration date. The QMSK was generated on and is kept only on a
dedicated, air-gapped "vault" machine, and the private portion will (hopefully) dedicated, air-gapped "vault" machine, and the private portion will (hopefully)
never leave this isolated machine. never leave this isolated machine.
There are several ways to get the QMSK. Before we proceed, you must first complete the prerequisite step of [installing
OpenPGP software](#openpgp-software).
Now, there are several ways to get the QMSK.
- If you're on Qubes OS, it's available in every - If you're on Qubes OS, it's available in every
qube ([except dom0](https://github.com/QubesOS/qubes-issues/issues/2544)): qube ([except dom0](https://github.com/QubesOS/qubes-issues/issues/2544)):
@ -263,8 +266,8 @@ gpg> q
Now, when you import any of the release signing keys and many Qubes team member Now, when you import any of the release signing keys and many Qubes team member
keys, they will already be trusted in virtue of being signed by the QMSK. keys, they will already be trusted in virtue of being signed by the QMSK.
Before proceeding to the next step, let's do a final sanity check to make sure As a final sanity check, make sure the QMSK is in your keyring with the correct
the QMSK is in your keyring with the correct trust level. trust level.
``` ```
$ gpg2 -k "Qubes Master Signing Key" $ gpg2 -k "Qubes Master Signing Key"
@ -277,12 +280,15 @@ If you don't see the QMSK here with a trust level of "ultimate," go back and
follow the instructions in this section carefully and consult the follow the instructions in this section carefully and consult the
[troubleshooting FAQ](#troubleshooting-faq) below. [troubleshooting FAQ](#troubleshooting-faq) below.
### 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). Before we proceed, you in turn signed by the Qubes Master Signing Key (QMSK).
must first [import and authenticate the Qubes Master Signing
Key](#how-to-import-and-authenticate-the-qubes-master-signing-key). Before we proceed, you must first complete the following prerequisite steps:
1. [Install OpenPGP software.](#openpgp-software)
2. [Import and authenticate the Qubes Master Signing Key.](#how-to-import-and-authenticate-the-qubes-master-signing-key)
The first step is to obtain the correct RSK. The filename of the RSK for your The first step is to obtain the correct RSK. The filename of the RSK for your
Qubes OS release is usually `qubes-release-X-signing-key.asc`, where `X` is the Qubes OS release is usually `qubes-release-X-signing-key.asc`, where `X` is the
@ -355,13 +361,13 @@ If you don't see the correct RSK here with a trust level of "full" or higher,
go back and follow the instructions in this section carefully, and consult the go back and follow the instructions in this section carefully, and consult the
[troubleshooting FAQ](#troubleshooting-faq) below. [troubleshooting FAQ](#troubleshooting-faq) below.
### How to obtain and authenticate other signing keys ## How to obtain and authenticate other signing keys
Please see the [Qubes security pack](/security/pack/) documentation. Please see the [Qubes security pack](/security/pack/) documentation.
## How to verify the cryptographic hash values of Qubes ISOs ## How to verify the cryptographic hash values of Qubes ISOs
There are two ways to verify Qubes ISO: cryptographic hash values and detached There are two ways to verify Qubes ISOs: cryptographic hash values and detached
PGP signatures. Both methods are equally secure. Using just one method is PGP signatures. Both methods are equally secure. Using just one method is
sufficient to verify your Qubes ISO. Using both methods is not necessary, but sufficient to verify your Qubes ISO. Using both methods is not necessary, but
you can do so if you like. One method might be more convenient than another in you can do so if you like. One method might be more convenient than another in
@ -371,10 +377,11 @@ on Qubes ISOs](#how-to-verify-detached-pgp-signatures-on-qubes-isos).
Before we proceed, you must first complete the following prerequisite steps: Before we proceed, you must first complete the following prerequisite steps:
1. [Import and authenticate the Qubes Master Signing Key.](#how-to-import-and-authenticate-the-qubes-master-signing-key) 1. [Install OpenPGP software.](#openpgp-software)
2. [Import and authenticate your release signing key.](#how-to-import-and-authenticate-release-signing-keys) 2. [Import and authenticate the Qubes Master Signing Key.](#how-to-import-and-authenticate-the-qubes-master-signing-key)
3. [Import and authenticate your release signing key.](#how-to-import-and-authenticate-release-signing-keys)
Each Qubes ISO is accompanied by a set of **cyrptographic hash values** 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
@ -500,7 +507,7 @@ FAQ](#troubleshooting-faq) below.
## How to verify detached PGP signatures on Qubes ISOs ## How to verify detached PGP signatures on Qubes ISOs
There are two ways to verify Qubes ISO: cryptographic hash values and detached There are two ways to verify Qubes ISOs: cryptographic hash values and detached
PGP signatures. Both methods are equally secure. Using just one method is PGP signatures. Both methods are equally secure. Using just one method is
sufficient to verify your Qubes ISO. Using both methods is not necessary, but sufficient to verify your Qubes ISO. Using both methods is not necessary, but
you can do so if you like. One method might be more convenient than another in you can do so if you like. One method might be more convenient than another in
@ -511,8 +518,9 @@ ISOs](#how-to-verify-the-cryptographic-hash-values-of-qubes-isos).
Before we proceed, you must first complete the following prerequisite steps: Before we proceed, you must first complete the following prerequisite steps:
1. [Import and authenticate the Qubes Master Signing Key.](#how-to-import-and-authenticate-the-qubes-master-signing-key) 1. [Install OpenPGP software.](#openpgp-software)
2. [Import and authenticate your release signing key.](#how-to-import-and-authenticate-release-signing-keys) 2. [Import and authenticate the Qubes Master Signing Key.](#how-to-import-and-authenticate-the-qubes-master-signing-key)
3. [Import and authenticate your release signing key.](#how-to-import-and-authenticate-release-signing-keys)
Every Qubes ISO is released with a **detached PGP signature** file, which you Every Qubes ISO is released with a **detached PGP signature** file, which you
can find on the [downloads](/downloads/) page alongside the ISO. If the can find on the [downloads](/downloads/) page alongside the ISO. If the
@ -544,6 +552,19 @@ FAQ](#troubleshooting-faq) below.
## How to verify signatures on Git repository tags and commits ## How to verify signatures on Git repository tags and commits
Before we proceed, you must first complete the following prerequisite steps:
1. [Install OpenPGP software.](#openpgp-software)
2. [Import and authenticate the Qubes Master Signing Key.](#how-to-import-and-authenticate-the-qubes-master-signing-key)
3. [Import and authenticate keys from the Qubes security pack (qubes-secpack).](/security/pack/)
**Note:** Only some keys in the qubes-secpack are signed by the QMSK. Keys
that are not signed directly by the QMSK are still signed indirectly by
virtue of being included in the qubes-secpack, which is itself signed (via
Git tags and/or commits) by keys that are in turn signed by the QMSK. If a
key is not signed directly by the QMSK, you may need to set its trust level
directly.
Whenever you use one of the [Qubes repositories](https://github.com/QubesOS), Whenever you use one of the [Qubes repositories](https://github.com/QubesOS),
you should use Git to verify the PGP signature in a tag on the latest commit or you should use Git to verify the PGP signature in a tag on the latest commit or
on the latest commit itself. (One or both may be present, but only one is on the latest commit itself. (One or both may be present, but only one is
@ -565,18 +586,7 @@ all such conditions hold, you're much better off verifying signatures yourself.
(Also see: [distrusting the (Also see: [distrusting the
infrastructure](/faq/#what-does-it-mean-to-distrust-the-infrastructure).) infrastructure](/faq/#what-does-it-mean-to-distrust-the-infrastructure).)
Before we proceed, you must first complete the following prerequisite steps: **To verify a signature on a Git tag:**
1. [Import and authenticate the Qubes Master Signing Key.](#how-to-import-and-authenticate-the-qubes-master-signing-key)
2. [Import and authenticate keys from the Qubes security pack (qubes-secpack)](/security/pack/)
**Note:** Only some keys in the qubes-secpack are signed by the QMSK. Keys that
are not signed directly by the QMSK are still signed indirectly by virtue of
being included in the qubes-secpack, which is itself signed (via Git tags
and/or commits) by keys that are in turn signed by the QMSK. If a key is not
signed directly by the QMSK, you may need to set its trust level directly.
To verify a signature on a Git tag:
```shell_session ```shell_session
$ git tag -v <tag name> $ git tag -v <tag name>
@ -588,7 +598,7 @@ or
$ git verify-tag <tag name> $ git verify-tag <tag name>
``` ```
To verify a signature on a Git commit: **To verify a signature on a Git commit:**
```shell_session ```shell_session
$ git log --show-signature <commit ID> $ git log --show-signature <commit ID>

14
user/how-to-guides/backup-emergency-restore-v4.md
View File

@ -37,12 +37,12 @@ Here are instructions for obtaining a compiled `scrypt` binary. This example
uses an RPM-based system (Fedora), but the same general procedure should work uses an RPM-based system (Fedora), but the same general procedure should work
on any GNU/Linux system. on any GNU/Linux system.
1. If you're not on Qubes 4.X, [get and verify the Release 4 Signing Key](/security/verifying-signatures/#2-get-the-release-signing-key). 1. If you're not on Qubes 4.X, [import and authenticate the Release 4 Signing
2. If you're not on Qubes 4.X, import the Release 4 Signing Key. Key](/security/verifying-signatures/#how-to-import-and-authenticate-release-signing-keys).
[user@restore ~]$ sudo rpm --import qubes-release-4-signing-key.asc [user@restore ~]$ sudo rpm --import qubes-release-4-signing-key.asc
3. Download the `scrypt` RPM. 2. Download the `scrypt` RPM.
[user@restore ~]$ dnf download scrypt [user@restore ~]$ dnf download scrypt
@ -50,7 +50,7 @@ on any GNU/Linux system.
[user@restore ~]$ curl -O https://yum.qubes-os.org/r4.0/current/vm/fc28/rpm/scrypt-1.2.1-1.fc28.x86_64.rpm [user@restore ~]$ curl -O https://yum.qubes-os.org/r4.0/current/vm/fc28/rpm/scrypt-1.2.1-1.fc28.x86_64.rpm
4. Verify the signature on the `scrypt` RPM. 3. Verify the signature on the `scrypt` RPM.
[user@restore ~]$ rpm -K scrypt-*.rpm [user@restore ~]$ rpm -K scrypt-*.rpm
scrypt-*.rpm: digests signatures OK scrypt-*.rpm: digests signatures OK
@ -58,15 +58,15 @@ on any GNU/Linux system.
The message `digests signatures OK` means that both the digest (i.e., the The message `digests signatures OK` means that both the digest (i.e., the
output of a hash function) and PGP signature verification were successful. output of a hash function) and PGP signature verification were successful.
5. Install `rpmdevtools`. 4. Install `rpmdevtools`.
[user@restore ~]$ sudo dnf install rpmdevtools [user@restore ~]$ sudo dnf install rpmdevtools
6. Extract the `scrypt` binary from the RPM. 5. Extract the `scrypt` binary from the RPM.
[user@restore ~]$ rpmdev-extract scrypt-*.rpm [user@restore ~]$ rpmdev-extract scrypt-*.rpm
7. (Optional) Create an alias for the new binary. 6. (Optional) Create an alias for the new binary.
[user@restore ~]$ alias scrypt="scrypt-*/usr/bin/scrypt" [user@restore ~]$ alias scrypt="scrypt-*/usr/bin/scrypt"

2
user/troubleshooting/installation-troubleshooting.md
View File

@ -26,7 +26,7 @@ Note that the Qubes installation image is over 4GB, so it may not fit on a small
If a machine can not boot from a bigger USB, it may be too old to run Qubes. If a machine can not boot from a bigger USB, it may be too old to run Qubes.
* **Verify your Qubes ISO:** * **Verify your Qubes ISO:**
Errors will occur if the Qubes installer is corrupted. Errors will occur if the Qubes installer is corrupted.
Ensure that the installer is correct and complete before writing it to a flash drive by [verifying the ISO](/security/verifying-signatures/#how-to-verify-qubes-iso-signatures). Ensure that the installer is correct and complete before writing it to a flash drive by [verifying the ISO](/security/verifying-signatures/).
* **Change the method you used to [write your ISO to a USB key](/doc/installation-guide/#copying-the-iso-onto-the-installation-medium):** * **Change the method you used to [write your ISO to a USB key](/doc/installation-guide/#copying-the-iso-onto-the-installation-medium):**
Some people use the ``dd`` command (recommended), others use tools like Rufus, balenaEtcher or the GNOME Disk Utility. Some people use the ``dd`` command (recommended), others use tools like Rufus, balenaEtcher or the GNOME Disk Utility.
If installation fails after using one tool, try a different one. If installation fails after using one tool, try a different one.