Sign EFI binaries at flash time for UEFI Secure Boot

The secureboot PR (tiiuae#1713) enrolls PK/KEK/db keys into the Jetson Orin
firmware, but nothing was signing the UKI or systemd-boot. Once keys
are enrolled and the UEFI leaves Setup Mode, it rejects unsigned
binaries with 'Access denied', bricking the device.

Move ESP image construction from a Nix derivation into the flash
script so we can sign EFI binaries with sbsign just before writing
them to the FAT partition. The private key is read at flash time
from SECURE_BOOT_SIGNING_KEY_DIR (or the signingKeyDir option),
keeping it out of the Nix store.

Add self-signed development keys under modules/secureboot/dev-keys/
for testing. These are explicitly not secret and must not be used in
production.

Tested on Jetson AGX Orin: device boots with Secure Boot enabled
(user mode), unsigned UKI is rejected with 'Access denied'.

Signed-off-by: Jörg Thalheim <joerg@thalheim.io>

Author: Mic92

docs/src/content/docs/ghaf/overview/arch/secureboot.mdx

@@ -43,3 +43,149 @@ efi-readvar -v PK
 efi-readvar -v KEK
 efi-readvar -v db
 ```
+
+## Jetson Orin Secure Boot
+
+On Jetson Orin targets with verity boot, Secure Boot is handled differently from
+the x86 laptop flow. The NVIDIA UEFI firmware supports standard UEFI Secure Boot
+key enrollment via a device tree overlay, and EFI binaries (systemd-boot and UKIs)
+are signed at flash time rather than build time.
+
+This keeps private signing keys out of the Nix store while still producing a
+fully signed boot chain.
+
+### How it works
+
+1. **Key enrollment**: During flash, a DTB overlay (`UefiDefaultSecurityKeys.dtbo`)
+   embeds PK, KEK, and db certificates into the firmware. On first boot, the UEFI
+   enrolls these keys and transitions from Setup Mode to User Mode.
+
+2. **EFI signing**: The flash script builds the ESP image at flash time. Before
+   copying EFI binaries into the FAT partition, it signs each `.efi` file with
+   `sbsign` using the db private key. This signs both systemd-boot (`BOOTAA64.efi`)
+   and the UKI.
+
+3. **Enforcement**: Once in User Mode (SetupMode=0, SecureBoot=1), the UEFI
+   firmware rejects any unsigned or incorrectly signed EFI binary with
+   "Access denied".
+
+### Key material
+
+The repository contains two sets of keys:
+
+- **`modules/secureboot/keys/`** — Production certificates generated from a
+  NetHSM. Contains only `.crt` and `.auth` files (public material).
+
+- **`modules/secureboot/dev-keys/`** — Self-signed development keys for testing.
+  Contains both `.crt` (public) and `.key` (private) files. These keys are
+  checked into the repository for convenience — they are explicitly **not secret**
+  and must not be used in production.
+
+### Configuration
+
+Secure Boot is enabled by default for Orin targets via `jetson-orin.nix`:
+
+```nix
+ghaf.hardware.nvidia.orin.secureboot.enable = lib.mkDefault true;
+```
+
+The Orin profile overrides the enrollment certificates to use dev keys:
+
+```nix
+ghaf.hardware.nvidia.orin.secureboot.keysSource = lib.mkDefault ../secureboot/dev-keys;
+```
+
+Available options:
+
+| Option | Description |
+|--------|-------------|
+| `ghaf.hardware.nvidia.orin.secureboot.enable` | Enable/disable UEFI Secure Boot key enrollment |
+| `ghaf.hardware.nvidia.orin.secureboot.keysSource` | Directory with `PK.crt`, `KEK.crt`, `db.crt` for enrollment |
+| `ghaf.hardware.nvidia.orin.secureboot.signingKeyDir` | Directory with `db.key` and `db.crt` for flash-time signing |
+
+### Flashing with Secure Boot
+
+The flash script reads the signing key from `SECURE_BOOT_SIGNING_KEY_DIR` (or
+falls back to the `signingKeyDir` option). Since private keys are not copied into
+the Nix store, you must point the environment variable to the working tree:
+
+```sh
+# Build the flash script
+nix build .#nvidia-jetson-orin-agx-verity-debug-from-x86_64-flash-script
+
+# Flash with dev keys (device must be in recovery mode)
+sudo SECURE_BOOT_SIGNING_KEY_DIR=$PWD/modules/secureboot/dev-keys \
+  ./result/bin/flash-ghaf-host
+```
+
+The flash script will:
+1. Sign `BOOTAA64.efi` and the UKI with the db key
+2. Build the ESP FAT image with the signed binaries
+3. Flash QSPI firmware (with key enrollment DTB overlay) and eMMC partitions
+
+### OTA update image signing
+
+UKIs in OTA update images must also be signed for Secure Boot to accept them.
+
+In **debug builds**, the `uki-signing-key-dir` option signs UKIs at Nix build
+time using the dev keys. This is gated by an assertion — it cannot be used in
+release builds because it places private keys in the Nix store:
+
+```nix
+ghaf.partitioning.verity-volume.uki-signing-key-dir = ./path/to/dev-keys;
+```
+
+In **production**, the OTA update server is responsible for signing UKIs before
+distributing them to devices. The device never holds private signing keys.
+The exact signing integration depends on the update server implementation
+and is not yet implemented.
+
+### Production key workflow
+
+For production builds, replace the key material:
+
+1. Generate production PK/KEK/db certificates (e.g., from a Hardware Security
+   Module).
+2. Set `keysSource` to the directory containing the production `.crt` files.
+3. At flash time, set `SECURE_BOOT_SIGNING_KEY_DIR` to a directory containing
+   the production `db.key` and `db.crt` (e.g., from an HSM-backed PKCS#11
+   token or a secure build machine).
+
+```nix
+ghaf.hardware.nvidia.orin.secureboot = {
+  keysSource = /path/to/production/certs;  # PK.crt, KEK.crt, db.crt
+  signingKeyDir = "/secure/signing/keys";  # db.key, db.crt (runtime path)
+};
+```
+
+### Verification
+
+After flashing and booting, verify Secure Boot is active:
+
+```sh
+# Check UEFI variables
+efi-readvar
+
+# Check boot status
+bootctl status | head -10
+# Should show: Secure Boot: enabled (user)
+
+# Check SetupMode is off (enforcing)
+hexdump -C /sys/firmware/efi/efivars/SetupMode-8be4df61-93ca-11d2-aa0d-00e098032b8c
+# Last byte should be 00 (not in setup mode)
+```
+
+### Generating new dev keys
+
+To regenerate the development keys:
+
+```sh
+cd modules/secureboot/dev-keys
+for name in PK KEK db; do
+  openssl req -new -x509 -newkey rsa:2048 -nodes \
+    -keyout "$name.key" -out "$name.crt" \
+    -subj "/CN=Ghaf Dev Secure Boot $name/" -days 3650
+done
+```
+
+After regenerating, you must reflash the device for the new keys to take effect.

modules/partitioning/verity-volume.nix

@@ -14,9 +14,26 @@ in
 {
   options.ghaf.partitioning.verity-volume = {
     enable = lib.mkEnableOption "the verity (image-based) partitioning scheme";
+
+    uki-signing-key-dir = lib.mkOption {
+      type = lib.types.nullOr lib.types.path;
+      default = null;
+      description = ''
+        Directory containing db.key and db.crt for signing the UKI in
+        the OTA update image. When set, the UKI is signed at build time
+        so devices with Secure Boot enabled can boot from OTA-installed
+        slots. In production, the OTA server signs images instead.
+      '';
+    };
   };
 
   config = lib.mkIf cfg.enable {
+    assertions = [
+      {
+        assertion = cfg.uki-signing-key-dir == null || debugEnable;
+        message = "uki-signing-key-dir puts private keys in the Nix store and must only be used in debug builds. In production, the OTA server signs images before distribution.";
+      }
+    ];
     system.build.ghafImage =
       let
         inherit (config.ghaf) version;
@@ -92,6 +109,13 @@ in
             --output="kernel.efi"
           # ${kernelImage} don't work for some reasons, so move kernel in place
           mv kernel.efi ${kernelImage}
+          ${lib.optionalString (cfg.uki-signing-key-dir != null) ''
+            echo "Signing UKI with Secure Boot key..."
+            ${pkgs.buildPackages.sbsigntool}/bin/sbsign \
+              --key ${cfg.uki-signing-key-dir}/db.key \
+              --cert ${cfg.uki-signing-key-dir}/db.crt \
+              --output ${kernelImage} ${kernelImage}
+          ''}
 
           # FIXME: move compression into mk-manifest.py and compute unpacked sizes there.
           rootUnpackedSize=$(stat -c%s ${fsImage})

modules/profiles/orin.nix

@@ -213,6 +213,12 @@ in
       givc.enable = true;
       global-config.givc.enable = true;
 
+      # Use development keys for both enrollment and signing.
+      # Production builds should override keysSource with the real
+      # certs and set SECURE_BOOT_SIGNING_KEY_DIR to the HSM-backed
+      # key directory at flash time.
+      hardware.nvidia.orin.secureboot.keysSource = lib.mkDefault ../secureboot/dev-keys;
+
       host.networking = {
         enable = true;
       };

modules/reference/hardware/jetpack/nvidia-jetson-orin/default.nix

@@ -6,6 +6,7 @@
   imports = [
     ./partition-template.nix
     ./jetson-orin.nix
+    ./secureboot.nix
     ./pci-passthrough-common.nix
     ./virtualization
     ./optee/optee.nix

modules/reference/hardware/jetpack/nvidia-jetson-orin/partition-template-verity.nix

@@ -140,8 +140,58 @@ let
     # prevents flash.sh from rebuilding esp.img via create_espimage.
     export NO_ESP_IMG=0
 
-    echo "Decompressing pre-built ESP image..."
-    "${pkgs.pkgsBuildBuild.zstd}/bin/zstd" -f -d "${verityImages}/esp.img.zst" -o "$WORKDIR/bootloader/esp.img"
+    echo "Building ESP image..."
+    _esp="$WORKDIR/bootloader/esp.img"
+    _uki_name=$(cat "${verityImages}/esp-files/uki-filename")
+    _uki_src="${verityImages}/esp-files/uki.efi"
+    _boot_src="${verityImages}/esp-files/systemd-bootaa64.efi"
+
+    # Copy to writable tmp so we can sign in-place
+    _sign_dir=$(mktemp -d)
+    cp "$_boot_src" "$_sign_dir/BOOTAA64.efi"
+    cp "$_uki_src" "$_sign_dir/$_uki_name"
+
+    # Sign EFI binaries if secure boot keys are available
+    _sb_key_dir="''${SECURE_BOOT_SIGNING_KEY_DIR:-${
+      if config.ghaf.hardware.nvidia.orin.secureboot.enable then
+        config.ghaf.hardware.nvidia.orin.secureboot.signingKeyDir
+      else
+        ""
+    }}"
+    if [ -n "$_sb_key_dir" ] && [ -f "$_sb_key_dir/db.key" ] && [ -f "$_sb_key_dir/db.crt" ]; then
+      echo "Signing EFI binaries with $_sb_key_dir/db.crt ..."
+      for _efi in "$_sign_dir"/*.efi; do
+        echo "  Signing: $(basename "$_efi")"
+        "${pkgs.pkgsBuildBuild.sbsigntool}/bin/sbsign" \
+          --key "$_sb_key_dir/db.key" --cert "$_sb_key_dir/db.crt" \
+          --output "$_efi" "$_efi"
+      done
+    ${
+      if config.ghaf.hardware.nvidia.orin.secureboot.enable then
+        ''
+          else
+            echo "ERROR: Secure Boot is enabled but no signing keys found." >&2
+            echo "  Set SECURE_BOOT_SIGNING_KEY_DIR or place db.key + db.crt in:" >&2
+            echo "  $_sb_key_dir" >&2
+            exit 1
+        ''
+      else
+        ''
+          else
+            echo "Secure Boot signing skipped (no keys found)."
+        ''
+    }
+    fi
+
+    # Create 512M FAT32 ESP image
+    "${pkgs.pkgsBuildBuild.dosfstools}/bin/mkfs.vfat" -F 32 -n ESP -C "$_esp" $((512 * 1024))
+    "${pkgs.pkgsBuildBuild.mtools}/bin/mmd" -i "$_esp" ::EFI
+    "${pkgs.pkgsBuildBuild.mtools}/bin/mmd" -i "$_esp" ::EFI/BOOT
+    "${pkgs.pkgsBuildBuild.mtools}/bin/mmd" -i "$_esp" ::EFI/Linux
+    "${pkgs.pkgsBuildBuild.mtools}/bin/mcopy" -i "$_esp" "$_sign_dir/BOOTAA64.efi" ::EFI/BOOT/BOOTAA64.efi
+    "${pkgs.pkgsBuildBuild.mtools}/bin/mcopy" -i "$_esp" "$_sign_dir/$_uki_name" "::EFI/Linux/$_uki_name"
+    rm -rf "$_sign_dir"
+    echo "ESP image built: $_esp"
 
     echo "Decompressing pre-built system (LVM) sparse image..."
     "${pkgs.pkgsBuildBuild.zstd}/bin/zstd" -f -d "${verityImages}/system.img.zst" -o "$WORKDIR/bootloader/system.img"

modules/reference/hardware/jetpack/nvidia-jetson-orin/secureboot.nix

@@ -0,0 +1,64 @@
+# SPDX-FileCopyrightText: 2022-2026 TII (SSRC) and the Ghaf contributors
+# SPDX-License-Identifier: Apache-2.0
+#
+# UEFI Secure Boot for Jetson Orin
+#
+# Enrolls PK/KEK/db keys into the firmware via a DTB overlay.
+# EFI binaries are signed at flash time by partition-template-verity.nix
+# using the db private key. OTA update images should be pre-signed by
+# the update server before distribution.
+{
+  config,
+  lib,
+  pkgs,
+  ...
+}:
+let
+  cfg = config.ghaf.hardware.nvidia.orin.secureboot;
+
+  eslFromCert =
+    name: cert:
+    pkgs.runCommand name { nativeBuildInputs = [ pkgs.buildPackages.efitools ]; } ''
+      ${pkgs.buildPackages.efitools}/bin/cert-to-efi-sig-list ${cert} $out
+    '';
+
+  keysDir = cfg.keysSource;
+
+  pkEsl = eslFromCert "PK.esl" "${keysDir}/PK.crt";
+  kekEsl = eslFromCert "KEK.esl" "${keysDir}/KEK.crt";
+  dbEsl = eslFromCert "db.esl" "${keysDir}/db.crt";
+in
+{
+  options.ghaf.hardware.nvidia.orin.secureboot = {
+    enable = lib.mkEnableOption "UEFI Secure Boot key enrollment for Jetson Orin";
+
+    keysSource = lib.mkOption {
+      type = lib.types.path;
+      default = ../../../../secureboot/keys;
+      description = "Directory containing PK.crt, KEK.crt and db.crt used to generate ESLs.";
+    };
+
+    signingKeyDir = lib.mkOption {
+      type = lib.types.str;
+      default = toString ../../../../secureboot/dev-keys;
+      description = ''
+        Path to directory containing db.key and db.crt for signing EFI
+        binaries at flash time (on the build host). This is intentionally
+        a string (not a path) to avoid copying private keys into the Nix
+        store.
+
+        Can be overridden at flash time via the SECURE_BOOT_SIGNING_KEY_DIR
+        environment variable.
+      '';
+    };
+  };
+
+  config = lib.mkIf cfg.enable {
+    hardware.nvidia-jetpack.firmware.uefi.secureBoot = {
+      enrollDefaultKeys = true;
+      defaultPkEslFile = pkEsl;
+      defaultKekEslFile = kekEsl;
+      defaultDbEslFile = dbEsl;
+    };
+  };
+}