Garden Linux

Appearance

Feature: _trustedboot ​

Description ​

A feature that establishes a fully trusted boot chain: UEFI Secure Boot verifies the bootloader and Unified Kernel Image (UKI) and the root filesystem (embedded as EROFS in the UKI) is covered by the same signature. At runtime, the system halts if Secure Boot is not active, closing all emergency escape paths. For the full trust model and security guarantees, see Secure Boot and Trusted Boot.

What it does ​

_trustedboot composes several layers of boot-chain integrity:

  • Includes _usi — switches the image to UKI boot mode, embedding the EROFS root filesystem in a single signed EFI binary.
  • Includes _ephemeral — sets the default /var storage to a per-boot randomly-keyed encrypted partition (no state persists across reboots). Replace with _tpm2 if persistent /var is needed.
  • Signs the UKI — usi.config runs at build time to sign the systemd-boot EFI binary and the UKI with sbsign, using either a local key or an AWS KMS PKCS#11 key. Secure Boot auth files (PK, KEK, db) are copied to the ESP and loader.conf is configured for automatic key enrollment.
  • Verifies Secure Boot at runtime — check-secureboot.service reads the SecureBoot EFI variable in the initrd and halts the system if Secure Boot is not active, before any local filesystem is mounted.
  • Removes all emergency escape paths — emergency.service is overridden to call halt -f immediately, and 99-no-rd-shell.cfg strips rd.shell and rd.emergency from the kernel command line, appending rd.shell=0 rd.emergency=poweroff.
  • Enforces Secure Boot capability — requirements.mod declares requirements["secureboot"]=true, so the build system rejects targets that do not support Secure Boot.

For a detailed breakdown of security guarantees, the feature dependency table, and mutable data mode comparison, see Secure Boot and Trusted Boot.

How it works ​

Boot-time verification (initrd) ​

All verification steps run inside the initrd, before any local filesystem is mounted:

  1. Secure Boot check (check-secureboot.service, ordered before local-fs.target via local-fs.target.requires/):

    • check-secureboot reads /sys/firmware/efi/efivars/SecureBoot-8be4df61-93ca-11d2-aa0d-00e098032b8c and checks whether the last byte is 1.
    • If Secure Boot is not active, it logs an error to the kernel log and exits non-zero, triggering emergency.target.

  2. Emergency halt override (emergency.service):

    • The standard emergency.service (which drops to a root shell) is replaced with a one-shot unit that calls halt -f immediately. Combined with the kernel command line changes, there is no way to reach a shell on boot failure.

  3. Kernel command line hardening (99-no-rd-shell.cfg):

    • Strips any existing rd.shell and rd.emergency parameters using sed, then appends rd.shell=0 rd.emergency=poweroff systemd.gpt_auto=0. This prevents the kernel or dracut from offering an emergency shell regardless of how the system was invoked.

Image signing (usi.config, build-time) ​

usi.config is called by the _usi image builder with the UKI path, ESP directory, and rootfs path as arguments:

  1. Signs the systemd-boot EFI binary (EFI/BOOT/BOOT{X64,AA64}.EFI) with sbsign using either a local PEM key (cert/secureboot.db.key) or an AWS KMS PKCS#11 engine key identified by ARN (cert/secureboot.db.arn).
  2. Writes loader/loader.conf with secure-boot-enroll force so that systemd-boot auto-enrolls the Garden Linux Secure Boot certificates on first boot.
  3. Copies the Garden Linux Secure Boot auth files (PK, KEK, db) from /etc/gardenlinux/ in the rootfs to EFI/loader/keys/auto/ in the ESP.
  4. Signs the UKI with sbsign and places the signed binary at EFI/Linux/$BUILDER_CNAME.efi in the ESP.

For certificate generation and build instructions, see Building Images: Secureboot / Trustedboot / TPM2.

Testing on macOS ​

  1. Generate the Secure Boot certificate chain:
    bash
    ./cert/build
  2. Build an image with the _trustedboot flag, optionally combined with _tpm2:
    bash
    ./build kvm_dev_trustedboot_tpm2
  3. Obtain an edk2 build with Secure Boot support:
    bash
    mkdir edk2
podman run --rm -v "$PWD/edk2:/mnt" debian:testing bash -c \
  'apt update && apt install -y qemu-efi-aarch64 && \
   cp /usr/share/AAVMF/AAVMF_CODE.secboot.fd /usr/share/AAVMF/AAVMF_VARS.fd /mnt/'
  4. Boot the image with start-vm (the ,qcow=4G suffix is required to make the disk large enough for systemd-repart to create the /var partition):
    bash
    ./bin/start-vm \
  --ueficode edk2/AAVMF_CODE.secboot.fd \
  --uefivars edk2/AAVMF_VARS.fd \
  --tpm2 disk.qcow2,qcow=4G

Files ​

Files present in this feature and their purpose. See the feature file reference for the semantics of each file type.

FilePurpose
file.include.markers.yaml (ref)Maps file.include files to test-coverage marker IDs.
info.yaml (ref)Declares type: flag; includes _usi and _ephemeral; excludes _nocrypt and _unsigned.
initrd.include.markers.yaml (ref)Maps initrd files to test-coverage marker IDs.
requirements.modDeclares requirements["secureboot"]=true, enforcing that the build target supports Secure Boot.
usi.configBuild-time signing script called by the _usi image builder: signs the systemd-boot EFI binary and the UKI with sbsign (local PEM key or AWS KMS PKCS#11); configures auto-enrollment; copies Garden Linux Secure Boot auth files to the ESP.
file.include/etc/kernel/cmdline.d/99-no-rd-shell.cfg (file.include)Strips rd.shell and rd.emergency kernel parameters and appends rd.shell=0 rd.emergency=poweroff systemd.gpt_auto=0, closing all emergency escape hatches in the initrd.
initrd.include/etc/systemd/system/check-secureboot.service (initrd.include)Initrd service ordered before local-fs.target (via local-fs.target.requires/) that runs check-secureboot and triggers emergency.target (immediate halt) if Secure Boot is not active.
initrd.include/etc/systemd/system/emergency.service (initrd.include)Overrides the standard emergency shell: replaces ExecStart with halt -f, preventing any interactive access if the system enters emergency mode.
initrd.include/etc/systemd/system/local-fs.target.requires/check-secureboot.service (initrd.include)Symlink ordering check-secureboot.service as a requirement of local-fs.target, ensuring the Secure Boot check runs before any local filesystem is mounted.
initrd.include/usr/bin/check-secureboot (initrd.include)Script invoked by check-secureboot.service: reads the SecureBoot EFI variable from /sys/firmware/efi/efivars/; logs an error and exits non-zero if Secure Boot is not active (1).

Includes:

  • _usi — provides the UKI boot mode (embedded EROFS root in a signed EFI binary) that Trusted Boot depends on. Signing the UKI implicitly signs the root filesystem.
  • _ephemeral — the default /var storage mode for Trusted Boot: a fresh randomly-keyed encrypted partition on every boot. No data persists across reboots, providing the strongest protection against offline attacks.

Excludes (incompatible with):

  • _nocrypt — a plaintext /var partition is incompatible with the integrity guarantees of Trusted Boot.
  • _unsigned — unsigned EFI binaries bypass Secure Boot entirely; incompatible with a signed and verified boot chain.

Closely pairs with:

  • _tpm2 — optional replacement for _ephemeral when persistent /var state is needed. Seals the /var encryption key to TPM 2.0 PCR 7, so the key is only released when the Secure Boot state is unchanged. Use _tpm2 instead of (not in addition to) _ephemeral.

Further reading ​

EU and German government funding logos

Funded by the European Union – NextGenerationEU.

The views and opinions expressed are solely those of the author(s) and do not necessarily reflect the views of the European Union or the European Commission. Neither the European Union nor the European Commission can be held responsible for them.

Copyright © Linux Foundation Europe.

Feature: _trustedboot | Garden Linux is a project of the NeoNephos Foundation. For applicable policies including privacy policy, terms of use and trademark usage guidelines, please see https://linuxfoundation.eu/policies. Linux is a registered trademark of Linus Torvalds.

Building this site is powered by