diff --git a/README.md b/README.md index 0aa58db..1dc44f7 100644 --- a/README.md +++ b/README.md @@ -5,94 +5,92 @@ [![made-with-rust](https://img.shields.io/badge/Made%20with-Rust-1f425f.svg)](https://www.rust-lang.org/) ![GitHub](https://img.shields.io/github/license/blitz/lanzaboote) -🚧🚧🚧 **This is not ready for non-developer usage.** 🚧🚧🚧 +This repository contains tooling for [UEFI Secure +Boot](https://en.wikipedia.org/wiki/UEFI#Secure_Boot) on +[NixOS](https://nixos.org/). The goal is to make Secure Boot available +from [nixpkgs](https://github.com/NixOS/nixpkgs) for any platform that +supports UEFI. -This repository contains experimental tooling for Secure Boot on -[NixOS](https://nixos.org/). +## ⚡ Quickstart ⚡ -## 🪛 To Do 🪛 +If you want to try this out, head over [here](./docs/QUICK_START) for +instructions. -There is a bunch of work to do. Please coordinate in the [Matrix -room](https://matrix.to/#/#nixos-secure-boot:ukvly.org), if you want -to take something up: +## 🪛 Get Involved 🪛 -- Overview documentation about the approach -- Document a experimental setup for developers on how to use this repository -- Coordinate with bootspec RFC stakeholders to communicate a experience report on the bootspec usage -- Cleaning up flakes.nix for AArch64 -- Upstream nixpkgs work - - Lanzatool - - Lanzaboote (needs unstable Rust!) - - NixOS boot loader installation etc. -- Unit testing for Lanzatool -- Investigating how this can fit into systemd-boot theory about sysexts for initrds while keeping NixOS semantics -- Threat modelling explanations: "bring your own PKI", "share your PKI with MSFT CA", "bring rhboot shim with MOK", etc. -- Ensuring 99 % of the paths are "happy paths" : protecting user against bricking their machines, identifying sources of risk, communicating intent and detecting risks -- Experimenting with `fwupd` / Green Checkmark in GNOME Device Security - - https://github.com/fwupd/fwupd/issues/5284 -- Experimenting with TPM2 measurements -- Support bootspec with no initrd -- Studying the initrd secrets feature in NixOS wrt SecureBoot & TPM2 -- ... +There is still a bunch of work to do before this work can be +upstreamed into [nixpkgs](https://github.com/NixOS/nixpkgs). Please +coordinate in the [Matrix +room](https://matrix.to/#/#nixos-secure-boot:ukvly.org) or check the +[issues](https://github.com/nix-community/lanzaboote/issues), if you +want to take something up. -## High-Level Boot Flow +## Overview -```mermaid -flowchart LR - systemd[systemd-boot] - lanzaboote[lanzaboote] - kernel[Linux Kernel] +### Secure Boot - systemd --> lanzaboote - lanzaboote --> kernel -``` +The goal of UEFI Secure Boot is to allow only trusted operating +systems to boot on a system. This can be used to defend against +certain classes of attacks that compromise the boot flow of a +system. For example, an attacker will have difficulty replacing the +Linux kernel that boots a system when Secure Boot is active. -## lanzatool +UEFI Secure Boot works by digitally signing all drivers, bootloaders, +the Linux kernel and its initrd. This establishes a chain of trust +where one trusted component only hands off control to the next part of +the boot flow when the integrity of the chain is cryptographically +validated. -`lanzatool` is a Linux command line application that takes a -[bootspec](https://github.com/NixOS/rfcs/pull/125) document and -installs the boot files into the UEFI -[ESP](https://en.wikipedia.org/wiki/EFI_system_partition). +### Caveats +There are some additional steps that are required to make UEFI Secure +Boot effective: -To make systemd-boot recognize a new boot target, `lanzatool` builds a -[UKI](https://wiki.archlinux.org/title/Unified_kernel_image) image. To -avoid having to embed kernel and initrd, we use a custom stub -`lanzaboote` (see below) that loads kernel and initrd from the ESP. +- There must be a BIOS password or a similar restriction that prevents + unauthorized changes to the Secure Boot policy. +- The booted system must have some form of integrity protection. +- The firmware must be kept up-to-date. -Remaining items to implement are: +These steps will not be covered here. -- Migrations from non-SecureBoot machine (old generation files) ; -- Alternative Nix stores paths ; -- Key rotation support ; -- Bootspec (abuse) cleanups ; -- Automatic synchronization policies for changing PKI (rotating keys, re-enrolling them, etc.) ; -- NixOS specialisations support ; -- Automatic removal of unused files relative to the `configurationLimit` option ; -- `os-release` patch so `systemd-boot` shows pretty names with generation number +### Lanzatool -## lanzaboote +At the moment, boot loaders, kernels and initrds on NixOS are signed +on the current system. These then need to be prepared as [Unified +Kernel Images +(UKI)](https://uapi-group.org/specifications/specs/boot_loader_specification/#type-2-efi-unified-kernel-images) and placed on the [EFI System Partition (ESP)](https://en.wikipedia.org/wiki/EFI_system_partition). -`lanzaboote` is the stub that `lanzatool` uses to form an UKI. It -loads a Linux kernel and initrd without breaking the Secure Boot chain -of trust. Instead of rolling our own crypto, `lanzaboote` re-uses the -signature verification that is built-in to UEFI. +`lanzatool` is a Linux command line application that takes care of +this flow. It takes a [NixOS +bootspec](https://github.com/NixOS/rfcs/pull/125) document, signs the +relevant files, creates a UKI using lanzaboote (see below) and +installs the UKI along with other required files to the +ESP. `lanzatool` is also aware of multiple NixOS genertions and will +sign all configurations that should be bootable. +### Lanzaboote -Remaining items to implement are: +When the Linux kernel and initrd are packed into a UKI, they need an +UEFI application stub. This role is typically filled by +[`systemd-stub`](https://www.freedesktop.org/software/systemd/man/systemd-stub.html). -- TPM measurements like `systemd-stub` does -- Better error management +The downside of `systemd-stub` is that it requires the kernel and +initrd to be packed into the UKI, which makes it pretty large. As we +need one UKI per NixOS configuration, systems with many configurations +quickly run out of the limited disk space in the ESP. -## Relevant Nixpkgs Work +`lanzaboote` is a UEFI stub that solves the same problem as +`systemd-stub`, but allows kernel and initrd to be stored separately +on the ESP. The chain of trust is maintained by validating the +signature on the Linux kernel and embedding a cryptographic hash of +the initrd into the signed UKI. -This project depends on upstream nixpkgs work: +`lanzaboote` lives in `rust/lanzaboote`. -- https://github.com/NixOS/nixpkgs/pull/191665 -- https://github.com/DeterminateSystems/bootspec-secureboot/ -- https://github.com/DeterminateSystems/bootspec +## State of Upstreaming to Nixpkgs -You can find everything integrated as PoC -[here](https://github.com/NixOS/nixpkgs/pull/202497). +Secure Boot is available as an Nixpkgs out-of-tree feature using the +[bootspec feature preview](https://github.com/NixOS/rfcs/pull/125). It +works with current nixpkgs-unstable. ## Funding