Lanzaboote

Tooling for UEFI Secure Boot on NixOS.

Setup

To be able to setup Secure Boot on your device, NixOS needs to be installed in UEFI mode and systemd-boot must be used as a boot loader. This means if you wish to install lanzaboote on a new machine, you need to follow the install instruction for systemd-boot and then switch to lanzaboote after the first boot.

These prerequisites can be checked via bootctl status:

$ bootctl status
System:
     Firmware: UEFI 2.70 (Lenovo 0.4720)
  Secure Boot: disabled (disabled)
 TPM2 Support: yes
 Boot into FW: supported

Current Boot Loader:
      Product: systemd-boot 251.7
...

In the bootctl output, the firmware needs to be UEFI and the current boot loader needs to be systemd-boot. If this is the case, you are all set to continue.

The UEFI boot process revolves around a special partition on the disk. This partition is called ESP, the (U)EFI System Partition. This partition is by convention mounted at /boot on NixOS and the rest of this document assumes this.

You can verify that /boot is the ESP by looking for ESP: in bootctl status output.

To create Secure Boot keys, we use sbctl, a popular Secure Boot Key Manager. sbctl is available in Nixpkgs as pkgs.sbctl.

Once you have installed sbctl (or entered a Nix shell), creating your Secure Boot keys requires this command:

$ sudo sbctl create-keys
[sudo] password for julian:
Created Owner UUID 8ec4b2c3-dc7f-4362-b9a3-0cc17e5a34cd
Creating secure boot keys...✓
Secure boot keys created!

This takes a couple of seconds. When it is done, your Secure Boot keys are located in /var/lib/sbctl. sbctl sets the permissions of the secret key so that only root can read it.

Configuration

Below is a fragment of a NixOS configuration that enables the Secure Boot stack.

{
  description = "A SecureBoot-enabled NixOS configurations";
 
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
 
    lanzaboote = {
      url = "github:nix-community/lanzaboote/v0.4.2";
 
      # Optional but recommended to limit the size of your system closure.
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };
 
  outputs = { self, nixpkgs, lanzaboote, ...}: {
    nixosConfigurations = {
      yourHost = nixpkgs.lib.nixosSystem {
        system = "x86_64-linux";
 
        modules = [
          # This is not a complete NixOS configuration and you need to reference
          # your normal configuration here.
 
          lanzaboote.nixosModules.lanzaboote
 
          ({ pkgs, lib, ... }: {
 
            environment.systemPackages = [
              # For debugging and troubleshooting Secure Boot.
              pkgs.sbctl
            ];
 
            # Lanzaboote currently replaces the systemd-boot module.
            # This setting is usually set to true in configuration.nix
            # generated at installation time. So we force it to false
            # for now.
            boot.loader.systemd-boot.enable = lib.mkForce false;
 
            boot.lanzaboote = {
              enable = true;
              pkiBundle = "/var/lib/sbctl";
            };
          })
        ];
      };
    };
  };
}

After you rebuild your system, check sbctl verify output:

$ sudo sbctl verify
Verifying file database and EFI images in /boot...
✓ /boot/EFI/BOOT/BOOTX64.EFI is signed
✓ /boot/EFI/Linux/nixos-generation-355.efi is signed
✓ /boot/EFI/Linux/nixos-generation-356.efi is signed
✗ /boot/EFI/nixos/0n01vj3mq06pc31i2yhxndvhv4kwl2vp-linux-6.1.3-bzImage.efi is not signed
✓ /boot/EFI/systemd/systemd-bootx64.efi is signed

It is expected that the files ending with bzImage.efi are not signed.

The UEFI firmware allows enrolling Secure Boot keys when it is in Setup Mode.

Once you’ve booted your system into NixOS again, you have to enroll your keys to activate Secure Boot. We include Microsoft keys here to avoid boot issues.

$ sudo sbctl enroll-keys --microsoft
Enrolling keys to EFI variables...
With vendor keys from microsoft...✓
Enrolled keys to the EFI variables!

⚠️ During boot, some hardware might include OptionROMs signed with Microsoft keys. By using the --microsoft, we enroll the Microsoft OEM certificates. Another more experimental option would be to enroll OptionROMs checksum seen at last boot using --tpm-eventlog, but these checksums might change later.

You can now reboot your system. After you’ve booted, Secure Boot is activated and in user mode:

$ bootctl status
System:
      Firmware: UEFI 2.70 (Lenovo 0.4720)
 Firmware Arch: x64
   Secure Boot: enabled (user)
  TPM2 Support: yes
  Boot into FW: supported