Verifying Qubes OS ISO with GPG

Hello Alex,

Welcome to your seventh lesson. In our previous session, we created a bootable Qubes OS USB drive. We ended with a crucial cliffhanger: the drive was created, but it was not yet trusted. Today, we address that by performing one of the most important steps in the entire process of building a secure system.

This lesson's learning outcome is to use GPG to verify the cryptographic signature of the downloaded Qubes OS ISO image. We will use the files you downloaded last time to build a cryptographic "chain of trust" from a single, verifiable source all the way to the installer file on your USB drive. This practice embodies the security philosophy of "distrusting the infrastructure."

Given your background in statistics and formal systems, you can think of this process as being analogous to a mathematical proof. We will establish a single axiom—the Qubes Master Signing Key—and then use cryptographic logic to prove that our ISO file is a direct, untampered consequence of that axiom.

Estimated time to complete: 60 minutes.

Recap from the Previous Lesson

• You downloaded three key files: the Qubes OS .iso, the detached signature .asc file, and the .DIGESTS file.
• You used the dd command to perform a block-level copy of the .iso file to a USB drive, creating bootable installation media.
• We concluded that while the media is bootable, its authenticity and integrity are unverified.

---

1. The Chain of Trust: From Axiom to ISO

Before we type any commands, let's solidify the theory. We cannot trust the website we downloaded from, the server hosting the files, or any network infrastructure in between. An attacker could have compromised any of these to serve a malicious file.

Instead, we rely on public-key cryptography. The Qubes OS project establishes a chain of trust that looks like this:

1. Qubes Master Signing Key (QMSK): This is the ultimate root of trust, our "axiom." It's a long-lived key, stored offline, that is used for one primary purpose: signing other, more transient keys.
2. Release Signing Key (RSK): For each major version of Qubes (e.g., R4.2), there is a specific RSK. This key is signed by the QMSK. This proves the RSK is authentic.
3. ISO Image & Digest File: The actual installation files are signed by the appropriate RSK. This proves the ISO is authentic and has its integrity intact.

Our task is to verify each link in this chain, starting from the QMSK.

For a deeper dive into the principles of authenticity and integrity that digital signatures provide, the following reading is excellent.

Reading time: ~5 minutes.
Verifying signatures (What digital signatures can and cannot prove)

---

2. Step 1: Establishing the Root of Trust (The QMSK)

Our entire security model for this installation will hinge on the authenticity of one item: the Qubes Master Signing Key. Therefore, verifying it correctly is the single most important step.

2.1. Installing GPG

We will use GnuPG (GPG), the open-source implementation of the OpenPGP standard, to perform our verification. If you are on a standard Linux distribution or macOS with developer tools, it is almost certainly already installed. You can check by opening a terminal and typing gpg --version.

If it's not installed, please refer to the official documentation for your OS.

Verifying signatures (OpenPGP software)

2.2. Importing and Authenticating the QMSK

First, we'll fetch the key from the Qubes OS project's keyserver.

gpg --fetch-keys https://keys.qubes-os.org/keys/qubes-master-signing-key.asc

Now, you have the key, but you don't know if it's the real key. Anyone can generate a key and call it "Qubes Master Signing Key." The unique identifier we must verify is its fingerprint.

Run the following command to display the fingerprint of the key you just imported:

gpg --fingerprint 'Qubes Master Signing Key'

The output should show this exact 40-character string:
427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494

This is the critical verification step. You should not trust that the fingerprint I've written here is correct, nor should you trust only the one on the Qubes website. As the documentation eloquently explains, you must now engage in a bit of investigative work.

Please read the following section carefully. It details the philosophy and methods for convincing yourself that you have the genuine fingerprint. This is a practical application of your reasoning skills to a security problem.

Reading time: ~10 minutes.
Verifying signatures (How to import and authenticate the Qubes Master Signing Key)

After you have cross-referenced the fingerprint from several independent sources (mailing list archives, developer social media, conference talk recordings, etc.) and are confident in its authenticity, you can proceed.

2.3. Assigning Ultimate Trust

Now you must tell GPG that you have personally verified this key and that it should be considered an ultimate root of trust. This will allow GPG to automatically trust other keys that are signed by the QMSK.

The blog post below provides a very clear, practical walkthrough of this interactive process.

Action: Follow the steps in the blog post to edit the key and assign it "ultimate" trust.
Qubes OS images - 'distrust the infrastructure' with PGP (Qubes Master Signing Key)

In summary, the commands are:

1. gpg --edit-key 0x427F11FD0FAA4B080123F01CDDFA1A3E36879494
2. At the gpg> prompt, type trust.
3. Choose 5 = I trust ultimately.
4. Confirm with y.
5. Exit with q.

You can confirm success with gpg -k "Qubes Master Signing Key", which should now show [ultimate] next to the user ID.

---

3. Step 2: Verifying the Release Signing Key (RSK)

With our root of trust established, we can now verify the next link in the chain: the key for the specific Qubes OS release you are installing.

3.1. Import the RSK

In the last lesson, you downloaded the .asc file for your release. Now, import it into GPG. For Qubes 4.2, the command would be:

# Adjust the filename to match the one you downloaded
gpg --import qubes-release-4.2-signing-key.asc

3.2. Check the RSK's Signature

This is the moment of cryptographic truth. We will ask GPG to check the signatures on the RSK. Because you have marked the QMSK as "ultimately trusted," GPG will be able to give you a definitive answer.

Action: Read the relevant section from the official docs and the practical example from the blog post. Then, run the command yourself.

Verifying signatures (How to import and authenticate release signing keys)
Qubes OS images - 'distrust the infrastructure' with PGP (Download and Verify the image with Qubes release key)

The command will look like this (adjust the name for your release):

gpg --check-signatures "Qubes OS Release 4.2 Signing Key"

The crucial line in the output is the one that says sig! DDFA1A3E36879494 ... Qubes Master Signing Key. The ! indicates a valid, good signature from the QMSK (whose key ID ends in 36879494). You have now cryptographically proven that the Release Key is authentic.

---

4. Step 3: Verifying the ISO Image

We are at the final step: verifying the multi-gigabyte ISO file you downloaded. There are two equally secure methods to do this. We'll focus on the detached signature method, as it's the most direct.

Method 1: Verifying with the Detached Signature (Recommended)

This method uses the .iso.asc file you downloaded. This is a "detached signature"—it's separate from the data it signs. This is efficient, as you don't need to bundle the signature with the huge ISO file.

Action: Ensure the .iso file and the .iso.asc file are in the same directory. Then, run the verification command as shown in the official documentation and the blog post.

Verifying signatures (How to verify detached PGP signatures on Qubes ISOs)
Qubes OS images - 'distrust the infrastructure' with PGP (Download and Verify the image with Qubes release key)

The command is:

# Adjust filenames to match your downloaded versions
gpg --verify Qubes-R4.2.0-x86_64.iso.asc Qubes-R4.2.0-x86_64.iso

You are looking for the output: Good signature from "Qubes OS Release X Signing Key". This message confirms that the ISO file is authentic (signed by the key we just verified) and has its integrity intact (the contents have not changed since it was signed).

Method 2: Verifying with the Digest File (Alternative)

The .DIGESTS file offers another path. This file contains several cryptographic hashes (MD5, SHA1, SHA256, SHA512) of the ISO. The entire text file is then signed by the RSK.

This is a two-step verification:

1. Verify the digest file itself:

   # Adjust filename
   gpg --verify Qubes-R4.2.0-x86_64.iso.DIGESTS
   

   You should see a Good signature... message.

2. Use the trusted digest file to check the ISO:

   # Adjust filename. The -c flag tells the tool to check hashes from the file.
   sha256sum -c Qubes-R4.2.0-x86_64.iso.DIGESTS
   

   You should see an OK message for your ISO file. You can safely ignore the warnings about "improperly formatted lines," as the tool is simply skipping the hashes for other algorithms and the PGP signature block.

For more detail on this method, see:
Verifying signatures (How to verify the cryptographic hash values of Qubes ISOs)
Qubes OS images - 'distrust the infrastructure' with PGP (Alternative way to confirm integrity and authenticity)

---

5. Troubleshooting Common Issues

GPG's error messages can be cryptic. If you encounter any issues, your first stop should be the excellent FAQ at the end of the Qubes verification document.

Verifying signatures (Troubleshooting FAQ)

The most common error is:
WARNING: This key is not certified with a trusted signature! There is no indication that the signature belongs to the owner.

This almost always means that you did not correctly set the trust level of the QMSK to "ultimate" in step 2.3. Go back and run the gpg --edit-key command again to fix it.

---

Conclusion

You have now successfully navigated the chain of trust and have cryptographically proven that your Qubes OS installer is authentic and untampered. This is a non-trivial skill and is fundamental to the security of any system you build from downloaded software. Your bootable USB drive is no longer just a collection of bits; it is a trusted artifact, ready for the next stage.

Key Takeaways:

• Security relies on a chain of trust, which for Qubes OS is: QMSK → RSK → ISO.
• The QMSK fingerprint is the single root of trust (our axiom) and must be verified from multiple independent sources.
• The gpg command allows us to import keys (--fetch-keys, --import), check them (--fingerprint, --check-signatures), and verify files (--verify).
• Setting the QMSK to ultimate trust is a critical step that tells GPG to trust keys signed by it.

Preview of the Next Lesson

With a verified and trusted installation medium in hand, we are ready to begin the "hardware surgery" on the x230. In the next lesson, "Install Qubes OS on the x230, configuring LUKS-based Full Disk Encryption with a strong passphrase," we will boot from the USB drive you've prepared and walk through the installation process, paying special attention to setting up the crucial layer of data protection for when the machine is powered off: Full Disk Encryption.