Secure Boot and Trusted Boot
Secure Boot
UEFI Secure Boot validates the cryptographic signatures of the bootloader and kernel before execution, preventing unauthorized code from running during the early boot process.
Garden Linux supports Secure Boot via the _secureboot feature. The required signing certificates are generated by running ./cert/build before building the image. See Building Images for the build prerequisites.
Since Garden Linux does not ship certificates that are pre-enrolled in standard UEFI firmware, the certificates must be enrolled either internally (using UEFI setup mode) or externally (providing UEFI variables at instance creation time). See Deploying Secure Boot Images for cloud-provider-specific enrollment steps.
The handling of Secure Boot keys in the release pipeline is described in ADR 0005.
Secure Boot requires the USI boot mode. It is incompatible with Legacy boot.
Trusted Boot
Trusted Boot extends Secure Boot by validating not just the bootloader and kernel, but the integrity of the entire root filesystem. In Garden Linux, this additional guarantee comes at almost no extra cost because of the USI boot mode: the rootfs is embedded directly in the signed Unified Kernel Image (UKI), so signing the UKI implicitly signs the rootfs.
INFO
Trusted Boot is implemented on top of the USI boot mode. Enabling _trustedboot automatically enables _usi and sets the default storage mode to _ephemeral. It is incompatible with _nocrypt. Use _tpm2 if persistent /var storage is required.
Security Guarantees
A Trusted Boot image enforces the following at runtime:
- Bootloader integrity — UEFI Secure Boot verifies the systemd-boot EFI binary before execution.
- Kernel integrity — The UKI signature covers the kernel, command line, and initrd.
- Root filesystem integrity — The EROFS rootfs is embedded in the signed UKI; any modification invalidates the signature.
- Initrd integrity — The initrd is embedded in the UKI and covered by the same signature.
- Boot state verification — The
check-securebootservice halts the system if Secure Boot is not active when the image boots. - No emergency shell — The emergency service is overridden to immediately halt the system, preventing shell access on boot failure.
Feature Dependencies
The _trustedboot feature automatically includes:
| Feature | Automatically included | Purpose |
|---|---|---|
_usi | Yes | UKI-based immutable boot |
_ephemeral | Yes (default) | Per-boot encrypted /var, no persistence |
_tpm2 | No (optional) | Persistent /var sealed to TPM 2.0 PCR 7 |
_secureboot | Implicitly required | UEFI Secure Boot key enrollment |
The _nocrypt and _unsigned features are incompatible with _trustedboot.
Mutable Data with Trusted Boot
Because Trusted Boot uses the USI boot mode, /var is always a separate partition managed by systemd-repart. Two options are available:
_ephemeral(default): A fresh encrypted partition is created on every boot with a random key. No data persists across reboots. This is the strongest protection against offline attacks._tpm2(optional): The/varpartition is created once on first boot and encrypted with a key sealed to the machine's TPM 2.0 device. The key is bound to PCR 7 (the Secure Boot certificate chain), so decryption only succeeds if the Secure Boot state is unchanged. This provides both persistence and offline attack protection.
For a full comparison of mutable data modes, see Boot Modes: Mutable Data Modes.
Building Trusted Boot Images
Before building any image with _trustedboot or _tpm2, Secure Boot signing certificates must be generated first. See Building Images: Secureboot / Trustedboot / TPM2 for full build instructions, including local file-based and AWS KMS-based key storage.
For step-by-step deployment instructions — including auto-key-enrollment, cloud-provider-specific certificate upload, and how to verify Secure Boot is active — see Deploying Secure Boot Images.
Deploying Trusted Boot Images
Cloud providers that support UEFI Secure Boot (AWS, GCP) require the Garden Linux signing certificates to be enrolled alongside the image. See Deploying Secure Boot Images for platform-specific enrollment steps.
The handling of Secure Boot signing keys in the release pipeline is described in ADR 0005.