Secure Boot on Giovanni Bassi

NixOS: Installation Guide with RAID 1, encryption, and TPM Unlock (part 5 - unlocking the disk with TPM)

giggio@giggio.net (Giovanni Bassi) — Mon, 18 May 2026 11:00:00 -0300

At last, we are going to automatically decrypt the NixOS disk using the TPM!

This is the fifth post in the series:

Preparing the virtual machine and partitioning the disks
Disko, LUKS, and btrfs
Installing the OS
Enabling Secure Boot
Unlocking the disk with TPM (this post)

Up to now, every boot has required the LUKS password to decrypt the disk. But if the machine’s integrity has not been compromised, there is no problem in doing this automatically. But how?

Now it is time to orchestrate everything we have put together so far, connecting LUKS, Secure Boot, and the TPM.

Why this is safe

Assuming the machine has not been compromised, when the operating system comes up, the only safe way to access it is with valid credentials — assuming the system has no exploitable vulnerability. That means logging in through the console, SSH, the graphical interface, or a serial connection. In practice, that means that without a login password there is no access to the computer, and no privilege is gained.

Everything works based on this principle: an uncompromised and intact system protects itself, and if it is compromised (firmware modification, disk removal, etc), encryption protects the data.

Understanding the TPM

The TPM (Trusted Platform Module) is a dedicated processor that stores, in an inviolable way, measurements taken of the hardware and software running on the computer. These measurements are stored in PCRs (Platform Configuration Registers), whose values can be extended, but never set directly. Every value sent to the TPM extends the previous value and produces a new one. If we were to model this as a formula, it would be something like this:

PCR = HASH(PCR || new_measurement)

In other words, the PCR hash is used together with the new measured value to create the new hash.

You can see the hashes of each PCR on your running TPM (fictitious values):

$ systemd-analyze pcrs
NR NAME SHA256
 0 platform-code 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
 1 platform-config 123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0
 2 external-code 23456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef01
 3 external-config 3456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef012
 4 boot-loader-code 456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123
 5 boot-loader-config 56789abcdef0123456789abcdef0123456789abcdef0123456789abcdef01234
 6 host-platform 6789abcdef0123456789abcdef0123456789abcdef0123456789abcdef012345
 7 secure-boot-policy 789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456
 8 - 89abcdef0123456789abcdef0123456789abcdef0123456789abcdef01234567
 9 kernel-initrd 9abcdef0123456789abcdef0123456789abcdef0123456789abcdef012345678
10 ima abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789
11 kernel-boot 0000000000000000000000000000000000000000000000000000000000000000
12 kernel-config 0000000000000000000000000000000000000000000000000000000000000000
13 sysexts 0000000000000000000000000000000000000000000000000000000000000000
14 shim-policy bcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789a
15 system-identity 0000000000000000000000000000000000000000000000000000000000000000
16 debug 0000000000000000000000000000000000000000000000000000000000000000
17 - ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
18 - ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
19 - ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
20 - ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
21 - ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
22 - ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
23 application-support 0000000000000000000000000000000000000000000000000000000000000000

Each PCR is independent and is extended freely, without depending on the others. On compatible TPMs there are 24 PCRs; the UAPI (Linux Userspace API Group) in its specifications considers 0–7 to be firmware and 8–15 to be the range available to the operating system, although the systemd ecosystem also uses specific PCRs for additional measurements, and PCRs 16–23 are also usable.

When the computer powers on, all PCRs start out with no value. The firmware then begins extending the PCRs. For example, PCR 0 depends on the software running in the firmware — what we normally call the BIOS. When you “update the BIOS”, PCR 0 changes. PCR 1 may change if you replace a hardware component. PCR 4 is tied to the operating system; it measures the boot loader and additional drivers. And so on.

PCR 7 depends on the Secure Boot state. Its values are commonly extended using the keys enrolled in Secure Boot, as well as the Secure Boot Authority. It is this PCR that we will use to unlock the disk, at this moment.

I will come back to PCRs in the next posts, but it is important to understand what they are for. If you decide to use what I am proposing in these posts, this knowledge may be useful if you run into trouble.

You can see all the events that led to PCR extensions by running sudo systemd-pcrlock log. Using jq, you can show only the events that led to PCR 7:

sudo /run/current-system/systemd/lib/systemd/systemd-pcrlock log --json=short 2>/dev/null | jq '[.log[] | select(.pcr == 7)]'

The result, simplified so it does not get too long, is this:

[
 {
 "pcr": 7,
 "pcrname": "secure-boot-policy",
 "event": "efi-variable-driver-config",
 "match": true,
 "sha256": "9f75b6823bff6af1024a4e2036719cdd548d3cbc2bf1de8e7ef4d0ed01f94bf9",
 "phase": "F",
 "component": null,
 "description": "Variable: dbx-d719b2cb-3d3a-4596-a3bc-dad00e67656f"
 },
 {
 "pcr": 7,
 "pcrname": "secure-boot-policy",
 "event": "efi-variable-authority",
 "match": true,
 "sha256": "f35567246a92b2fcdd2901e4ad2febdfd80173f25527c5a73033bf100a8eb980",
 "phase": "F",
 "component": null,
 "description": "Authority: db-d719b2cb-3d3a-4596-a3bc-dad00e67656f"
 }
]

Note that the hash value, stored in the sha256 field, changes with each event. When the TPM receives a request to decrypt a value, its state must match exactly what was used when the value was encrypted (this is done through TPM policies). That means a value encrypted early in the boot process may no longer be decryptable at the end of the boot process, if the PCR has been extended again. This is especially useful for this very reason: allowing a value to be accessible only at a specific point in the boot sequence, such as during initrd startup (PCR 11 has measurements that make this possible).

Systemd documents how it uses PCRs, and since nowadays there is practically no Linux without systemd, it is worth understanding. This document will be useful later, when we look more closely at PCR 15 (system identity).

Unlocking the disk during boot

Only one command is needed to make everything happen. In our case, since we have two disks and two partitions, we run the command once for each of them (you will need to enter your LUKS password for the process to complete):

sudo systemd-cryptenroll --tpm2-device=auto --tpm2-pcrs=7 /dev/disk/by-label/NIXLUKS1
sudo systemd-cryptenroll --tpm2-device=auto --tpm2-pcrs=7 /dev/disk/by-label/NIXLUKS2

When this command runs, the volume master key is obtained using your password. It is then encrypted (sealed) using the TPM, and this sealed value is stored in the LUKS volume header. In this case, only PCR 7 is being used to seal the value, meaning only the Secure Boot state. That means if the Secure Boot state changes (if it is reset, or if a new key is removed or added), the TPM’s PCR 7 state will also change, and the disk will no longer be decrypted during boot. In this post, the goal is to tie automatic disk decryption to the Secure Boot state, and that is what we have done.

You can see the details stored in the LUKS volume header by running the following command after systemd-cryptenroll has been executed:

sudo cryptsetup luksDump /dev/disk/by-label/NIXLUKS1

Notice the Tokens field, with the first one being systemd-tpm2, with a Keyslot:

Tokens:
 0: systemd-tpm2
 Keyslot: 1

To see more details about the sealed value, run:

sudo cryptsetup luksDump --dump-json-metadata /dev/disk/by-label/NIXLUKS1 | jq -r '.tokens."0"'

The result will look something like this:

{
 "type": "systemd-tpm2",
 "keyslots": ["1"],
 "tpm2-blob": "<a base64 value>",
 "tpm2-pcrs": [7],
 "tpm2-pcr-bank": "sha256",
 "tpm2-policy-hash": "<a hash>",
 "tpm2_srk": "<another base64 value>",
}

The tpm2-blob contains the value encrypted by the TPM (plus metadata). Using the tools from the tpm2-tools package and root access, you could recover the master password from this value. That is not a security problem: the system is already running and the disk is already decrypted. The purpose of TPM protection is not to protect a healthy running system from its administrator, but to protect against integrity violations that happen before, during, and after boot.

With just these two commands, the TPM will start unlocking both LUKS volumes. Reboot to confirm that it no longer asks for the password. If it does, inspect the boot logs with sudo journalctl --boot.

Is it secure?

Not yet.

There are two vulnerabilities, and I will address them in the next posts. Neither is trivial, but someone who understands how all of this works could gain access to the data in a short amount of time. None of the work done so far will be lost; we will build on the current solution. The good news is that both issues are easy to fix.

That said, it is fair assume that most people, including technicians who are not systems penetration experts, would no longer be able to read the disk of a computer encrypted this way. In other words, sending a laptop for repair with this configuration would probably not present a risk. But that is still not good enough.

In the next post we will start closing the gaps.

NixOS: Installation Guide with RAID 1, encryption, and TPM Unlock (part 4 - Secure Boot)

giggio@giggio.net (Giovanni Bassi) — Thu, 14 May 2026 11:00:00 -0300

In the fourth post of our series, we are going to configure Secure Boot to ensure that only trusted operating systems can be executed.

This is the fourth post of the series:

Preparing the virtual machine and partitioning the disks
Disko, LUKS, and btrfs
Installing the OS
Enabling Secure Boot (this post)

Secure Boot is a fundamental component for tightening the security, especially when using the TPM to automatically decrypt the disk. I will explain what it is, what it’s for, and how to implement it in NixOS using Lanzaboote.

Understanding Secure Boot

Secure Boot is a protocol that is part of the UEFI (Unified Extensible Firmware Interface). When enabled, it verifies if the operating system’s bootloader has a valid digital signature recognized by the keys registered in the motherboard’s firmware.

This prevents boot-level malware (rootkits) or unauthorized operating systems from loading. Additionally, the TPM uses the Secure Boot state as one of the metrics to decide whether or not to release the disk encryption keys.

There are three main ways to manage Secure Boot keys:

Factory default keys: Usually the Microsoft keys that come with almost every computer;
Custom keys (User Mode): You remove the Microsoft keys and install only your own;
Hybrid Mode: You keep the Microsoft keys (for dual-booting with Windows) and add your own.

If you don’t intend to run Windows, the second option is the most restrictive and secure. If you need dual boot, the third is mandatory. It’s worth noting that NixOS does not have a bootloader signed by Microsoft (unlike Ubuntu or Fedora), so we always need to generate our own keys.

And why Microsoft keys, specifically? Because they were the first company to push Secure Boot as mandatory, and they hold the largest share of the PC market. There is quite a bit of controversy regarding this.

The important thing for our setup is knowing that once you define how Secure Boot will be used, it cannot be changed without breaking the automatic decryption process (which will be done with the help of the TPM). In our case, we will use the third option (mixing Microsoft keys with our own). If Secure Boot is turned off on the machine or a new platform key is loaded, the TPM will refuse to decrypt the disk. I’ll explain this in future posts, so for now, what matters is enabling Secure Boot.

Putting the Firmware into Setup Mode

In the first post, we cleared the keys in the VM’s boot menu to enter Setup Mode. This is essential: for us to write our keys via software, the firmware must be “open” to new signatures.

Confirm the status by running:

$ sudo bootctl status
...
Secure Boot: disabled (setup)
...

If disabled (setup) appears, we are ready to proceed.

Generating Keys with sbctl

We will use sbctl to create and register our keys. Since it isn’t installed by default, let’s use nix-shell:

nix-shell -p sbctl

Note: In NixOS, you can bring any application into your terminal’s context using nix-shell. With this, the sbctl command becomes available in a subshell — to exit, just run exit.

To generate the keys, we will run the create-keys subcommand:

sudo sbctl create-keys

The keys will be generated in /var/lib/sbctl/. You can see the structure with the tree command:

$ tree /var/lib/sbctl/
/var/lib/sbctl/
├── GUID
└── keys
 ├── db
 │   ├── db.key
 │   └── db.pem
 ├── KEK
 │   ├── KEK.key
 │   └── KEK.pem
 └── PK
 ├── PK.key
 └── PK.pem

Install the keys into the machine’s firmware with enroll-keys. This will use the keys we created earlier with sbctl. With the --microsoft argument, Microsoft’s platform keys will also be installed:

sudo sbctl enroll-keys --microsoft

Verify that Secure Boot has been re-enabled with:

sudo bootctl status

It should show Secure Boot: enabled (user). It might not show as enabled yet until the next boot, showing up as Secure Boot: disabled, but without setup. But don’t reboot just yet!

Signing the Boot with Lanzaboote

At this point, if you restart the machine, NixOS will no longer boot, as the NixOS bootloader is not yet signed with the Secure Boot keys we created in the previous step. That’s where Lanzaboote comes in. It automates the signing of NixOS generations. It replaces the default systemd-boot manager with one that handles the keys generated by sbctl. Once enabled, whenever a new bootloader is created in the /boot directory, it will be signed with the keys located in /var/lib/sbctl.

To enable Lanzaboote and then sign the files, first go to the configuration directory that was copied in previous posts to /etc/nixos, and check out the correct commit. Be careful not to forget the git checkout, or it won’t work:

cd /etc/nixos
# ensuring the current user owns the files:
sudo chown -R giggio:users .
# checkout with the message "Enable lanzaboote":
git checkout dab0fd4

The change in your configuration.nix disables the native systemd-boot and activates lanzaboote, pointing to the keys directory:

 boot.loader.systemd-boot.enable = false;
 boot.lanzaboote = {
 enable = true;
 pkiBundle = "/var/lib/sbctl";
 };

The Lanzaboote configuration was already present; it was just disabled. And with it enabled, systemd-boot can be disabled. Note also that the keys directory, defined in the pkiBundle attribute, is already correctly pointed to /var/lib/sbctl.

That’s all; now just install the new configurations, which take effect immediately and will also be effective on the next boot:

sudo nixos-rebuild switch

Validating the Signature

To ensure Lanzaboote did its job and signed the .efi binaries, run:

$ sudo sbctl verify
Verifying file database and EFI images in /boot...
✓ /boot/EFI/BOOT/BOOTX64.EFI is signed
✓ /boot/EFI/Linux/nixos-generation-1-xxx.efi is signed
✓ /boot/EFI/Linux/nixos-generation-2-yyy.efi is signed
✗ /boot/EFI/nixos/kernel-7.0-zzz.efi is not signed
✓ /boot/EFI/systemd/systemd-bootx64.efi is signed

Note about the Kernel: It is normal to see an ✗ on the isolated kernel file. What matters are the files inside /boot/EFI/ and the boot managers. Lanzaboote creates a Unified Kernel Image (UKI), which bundles the kernel and the initrd into a single signed executable that the UEFI can run directly.

Now you can reboot. If everything went well, the system will come up normally and bootctl status will confirm: Secure Boot: enabled (user).

The machine still asks for the password to decrypt the disk. This is expected, as we haven’t yet implemented the structure for automatic decryption with the TPM.

Troubleshooting Secure Boot

If something goes wrong and the VM won’t start, you can reset the NVRAM (the VM’s “BIOS”). On your host, turn off the VM and run:

# on the host:
virsh start <vm_name> --reset-nvram

This will start the virtual machine normally, but with all the firmware boot settings lost, including Secure Boot settings.

The following commands will re-apply the boot settings to the firmware’s non-volatile memory and the disk:

# on the vm:

# registering platform keys in the firmware again:
sudo sbctl enroll-keys --microsoft
# installing the boot menu option:
sudo bootctl install
# re-signing the UKIs:
sudo nixos-rebuild switch

Why run switch again: When running bootctl install, the files /boot/EFI/systemd/systemd-bootx64.efi and /boot/EFI/BOOT/BOOTX64.EFI will not be signed, so it is necessary to run switch so that these two files become signed again.

Declarative Approach

Lanzaboote allows generating platform keys automatically via Nix config:

boot.lanzaboote = {
 autoGenerateKeys.enable = true;
 autoEnrollKeys = {
 enable = true;
 autoReboot = true;
 };
};

This is described in more detail in the docs on automatic provisioning.

While practical for testing, I don’t recommend using this in production systems. The ideal approach is to generate keys manually (as I demonstrated here) and store them securely somewhere. A good option is to use sops-nix, keeping the keys encrypted within the repository itself. The inconvenience would be during application, where you would always need the keys or devices to decrypt the sops secrets at every nixos-rebuild.

Next Up: Using TPM to Decrypt the Disk

Secure Boot is active. The disk is encrypted. But we still have to type the LUKS password at every boot.

If someone tries to start another operating system, it will need to be signed with your platform key or Microsoft’s. You can make the system more secure by removing the --microsoft option from the enroll-keys command and not allowing any other operating system.

In the next post, we will configure the TPM (Trusted Platform Module) so that it “measures” the Secure Boot state and releases the encryption key automatically if the system hasn’t been tampered with. Maximum security with convenience.

See you then!