Sign EFI binaries at flash time for UEFI Secure Boot

The secureboot PR (#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'.

Author: Mic92

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

@@ -42,37 +42,131 @@ efi-readvar -v KEK
 efi-readvar -v db
 ```
 
-## Jetson Orin signed flashing workflow
+## Jetson Orin Secure Boot
 
-Jetson Orin targets produce two independent build artifacts in CI:
+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.
 
-1. The flash script (`nix build .#nvidia-jetson-orin-agx-debug-from-x86_64-flash-script`) which orchestrates NVIDIA's flashing tools.
-2. The filesystem image (`nix build .#nvidia-jetson-orin-agx-debug-from-x86_64`) that contains the ESP and root partitions.
+This keeps private signing keys out of the Nix store while still producing a
+fully signed boot chain.
 
-After the filesystem image is signed, pass its Nix store path directly to the flash helper:
+### 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
-SIGNED_SD_IMAGE=$(nix path-info .#nvidia-jetson-orin-agx-debug-from-x86_64)
-./result/bin/initrd-flash-ghaf-host -s "$SIGNED_SD_IMAGE"
+# 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 `-s/--signed-sd-image` flag extracts `BOOTAA64.EFI` and the kernel from the signed image, wires them into the flashing workdir, and launches NVIDIA's flashing script without requiring any additional staging directories or host key material.
+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
 
-For ad-hoc debugging you can also point `-s` to a copy of the signed build outside the Nix store (for example, `cp -a $(nix path-info …) /tmp/orin-signed` and then pass `/tmp/orin-signed`), which is useful when the original store path is unavailable on the flashing host.
+### 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)
+};
+```
 
-For CI jobs that still need a deterministic artifact directory (for example when reusing the same signed files across multiple runs), the helper `modules/secureboot/extract-signed-orin-artifacts.sh` can be used:
+### Verification
+
+After flashing and booting, verify Secure Boot is active:
 
 ```sh
-./modules/secureboot/extract-signed-orin-artifacts.sh \
-  --sd-image-dir "$SIGNED_SD_IMAGE" \
-  --output /build/orin-flash-artifacts \
-  --force
-
-# Optional: reuse the staged directory via configuration or the environment
-export SIGNED_ARTIFACTS_DIR=/build/orin-flash-artifacts
-./result/bin/initrd-flash-ghaf-host
+# 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)
 ```
 
-The helper resolves the supplied directory—whether it's a `/nix/store/...` path or a copy under `/tmp`—before extracting the ESP and root partitions.
+### 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
+```
 
-The existing module option `ghaf.hardware.nvidia.orin.flashScriptOverrides.signedArtifactsPath` still forces the flash script to pick up a specific directory when the environment variable is not convenient.
+After regenerating, you must reflash the device for the new keys to take effect.

modules/profiles/orin.nix

@@ -216,6 +216,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/partition-template-verity.nix

@@ -126,8 +126,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

@@ -1,6 +1,11 @@
 # 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. Private keys never enter the Nix store.
 {
   config,
   lib,
@@ -31,6 +36,19 @@ in
       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. 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 {

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

@@ -32,43 +32,26 @@ let
   #   ghaf_<ver>_<hash>.manifest       — JSON manifest
   inherit (config.system.build) ghafImage;
 
-  espImage =
-    pkgs.runCommand "esp-image"
-      {
-        nativeBuildInputs = with pkgs.buildPackages; [
-          dosfstools
-          mtools
-          zstd
-        ];
-      }
-      ''
-        mkdir -p $out
-
-        # Find the UKI from ghafImage (built without .dtb, roothash patched)
-        uki=$(find ${ghafImage} -name '*.efi' | head -1)
-        if [ -z "$uki" ]; then
-          echo "ERROR: No UKI (.efi) found in ghafImage output"
-          ls -la ${ghafImage}/
-          exit 1
-        fi
-        echo "Using UKI: $uki"
-
-        # Create 512M FAT32 image
-        truncate -s 512M esp.img
-        mkfs.vfat -F 32 -n ESP esp.img
-
-        # Install systemd-boot as BOOTAA64.efi
-        boot_efi="${config.systemd.package}/lib/systemd/boot/efi/systemd-bootaa64.efi"
-        mmd -i esp.img ::EFI
-        mmd -i esp.img ::EFI/BOOT
-        mmd -i esp.img ::EFI/Linux
-        mcopy -i esp.img "$boot_efi" ::EFI/BOOT/BOOTAA64.efi
-
-        # Install UKI — auto-discovered by systemd-boot from EFI/Linux/
-        mcopy -i esp.img "$uki" "::EFI/Linux/$(basename "$uki")"
-
-        zstd --compress esp.img -o $out/esp.img.zst
-      '';
+  # The ESP FAT image is built at flash time (not here) so that
+  # EFI binaries can be signed with a private key that never enters
+  # the Nix store.  We only export the individual files needed.
+  espFiles = pkgs.runCommand "esp-files" { } ''
+    mkdir -p $out
+
+    # UKI (roothash-patched)
+    uki=$(find ${ghafImage} -name '*.efi' | head -1)
+    if [ -z "$uki" ]; then
+      echo "ERROR: No UKI (.efi) found in ghafImage output"
+      ls -la ${ghafImage}/
+      exit 1
+    fi
+    ln -s "$uki" "$out/uki.efi"
+    basename "$uki" > "$out/uki-filename"
+
+    # systemd-boot
+    ln -s "${config.systemd.package}/lib/systemd/boot/efi/systemd-bootaa64.efi" \
+      "$out/systemd-bootaa64.efi"
+  '';
 
   # LVM image: must be built in a VM because LVM needs block devices.
   # Reads the manifest from ghafImage to determine LV names, then writes
@@ -228,7 +211,7 @@ in
   config = lib.mkIf cfg.enable {
     system.build.verityImages = pkgs.runCommand "verity-images" { } ''
       mkdir -p $out
-      ln -s ${espImage}/esp.img.zst $out/esp.img.zst
+      ln -s ${espFiles} $out/esp-files
       ln -s ${lvmImage}/system.img.zst $out/system.img.zst
       ln -s ${lvmImage}/system.raw_size $out/system.raw_size
     '';

modules/secureboot/dev-keys/KEK.crt

@@ -0,0 +1,19 @@
+-----BEGIN CERTIFICATE-----
+MIIDJzCCAg+gAwIBAgIUKgZOKjCeExGRuKBKJUB3Xx3f8fgwDQYJKoZIhvcNAQEL
+BQAwIzEhMB8GA1UEAwwYR2hhZiBEZXYgU2VjdXJlIEJvb3QgS0VLMB4XDTI2MDIy
+NDE3NTUyMloXDTM2MDIyMjE3NTUyMlowIzEhMB8GA1UEAwwYR2hhZiBEZXYgU2Vj
+dXJlIEJvb3QgS0VLMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAoYiA
+bnOFBfPs03ajvbPRLP1KIEi6J8K8SGkA5Q6wIrezrYWRQTfGBcLhMOGjlTbfUyrf
+FFzdadMH2iPl3cuu1IfHk1O0S/+UPZrQ1xhiNvXYoxTJsq0rKWvcSPm2KjULUtcH
+/ZhWlZlZQKi80E8h/mDOr5BnOfLJ8D8BzxTan50V3iEjUpryxGG0iZzl8vElm4Kw
+DLfx8OFTr/VgTB/KvuUjZ98qeUJm0GIoTJN51KAXw8GsE9DIRTQo0oxqK1uVEse4
+MvV/IMCVqzVzP9ogfGFGEY3OWZ6XkmdM0EYFUjQQiz1+a0AthaxIPr0tqIcw7BzG
+0EVK7qMsSOfQl/xmSwIDAQABo1MwUTAdBgNVHQ4EFgQUDjNPiTHM6bFAfxOLr0hm
+8FlDFdswHwYDVR0jBBgwFoAUDjNPiTHM6bFAfxOLr0hm8FlDFdswDwYDVR0TAQH/
+BAUwAwEB/zANBgkqhkiG9w0BAQsFAAOCAQEAIhmQkI8Cl+kdEoCBOAHuEqP3/0wA
+YtDutO4tUw3tpS9RaFwzmTg7Ckf6IVTJTnxDkbqvbHtMIzLnWGEMT0j0JWQETuT0
+FLoE1AULwVxxCvE98EIOXzECtB0x5KLj+b5NTriCVfjUB+qRyp+BmcJKhwSiX690
+OzGrPDdAnIFacpUgcadqui/Wrh8MRhrQ80905Gpu2H5prPxP9eHbVQmFgT+B7QcE
+s6FsOJyby1jRsaKyp+3sgVaIKHAPp8Cj0ExNXRhSj/Wfv3tViY6ZDtCgk9knxHTI
+vfOw5iSoQ+FwLHf0XaW3M83unzVSoa+ybJJ5lBsD29RBmiF7zGK6E+U+vA==
+-----END CERTIFICATE-----

modules/secureboot/dev-keys/KEK.crt.license

@@ -0,0 +1,2 @@
+SPDX-FileCopyrightText: 2022-2026 TII (SSRC) and the Ghaf contributors
+SPDX-License-Identifier: Apache-2.0

modules/secureboot/dev-keys/KEK.key

@@ -0,0 +1,28 @@
+-----BEGIN PRIVATE KEY-----
+MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQChiIBuc4UF8+zT
+dqO9s9Es/UogSLonwrxIaQDlDrAit7OthZFBN8YFwuEw4aOVNt9TKt8UXN1p0wfa
+I+Xdy67Uh8eTU7RL/5Q9mtDXGGI29dijFMmyrSspa9xI+bYqNQtS1wf9mFaVmVlA
+qLzQTyH+YM6vkGc58snwPwHPFNqfnRXeISNSmvLEYbSJnOXy8SWbgrAMt/Hw4VOv
+9WBMH8q+5SNn3yp5QmbQYihMk3nUoBfDwawT0MhFNCjSjGorW5USx7gy9X8gwJWr
+NXM/2iB8YUYRjc5ZnpeSZ0zQRgVSNBCLPX5rQC2FrEg+vS2ohzDsHMbQRUruoyxI
+59CX/GZLAgMBAAECggEABQh1x/s9d9QD2wrlSzHhIJ+7wYnCkx6UM0ViS8DLaCmF
+JbD1t6x/NQq/bYB6UlnlV3gMf1vtYjC7G+bmcKS6C9E3PLXs9jk+azT5sNoHpWK/
+n0U0i6ato5rCwFtXe7UvZyNgEly+xeaDS2p2h58Plhd6GSpMrReNhzjPW55wuWxk
+53L6+sOLY5YJvsmC+3rQkf8NYfU7NR7qmmcpxU5xecnXrEXH5onE0lb6UtRTNVnn
+j/JY0wEr7a/Px9kmVnrQ7kOrK4iysVzYzpxfUpyEiCbdDo3exfq+g9nNxqaxmZRW
+4OYbkW+6gonfthGw9PKrJxJgZYnURTBA0nbaV/9WkQKBgQDO1c0qPrUn0VGaPcSx
+0g6m9huz+YkVtzZRqK/rpwLffZSriWGlseXfPpzFc8iG/QrzNQOMqtgU5bCT5Zlf
+JeXsnDwDxMKoa9gmyE6F8F9KCl6hukRlZPhRhTWiE16Yeo/E6CuTMVKdNclr1CHM
+gk+Jk7B+rZo3rYmumYJi2lrmJwKBgQDH7gPvVMWt+ScA3l3fweG8edJgfit0YIQt
+vdXbYySX+3HiKogHHujFPIvifrKfY1pbPINaqim6STsvq+R6JKghLoJ/oBx+sPQy
+RswbUoI3ZUx1Bm8avs1ThEDB/8qPKKL7/7fYuqSbT5ZbC2cZG7vHOKOCkTbCI7Kw
+PlsMGTBZPQKBgDX69qCf3QeXSYTHuh3uhIRulqxR48UXG8YUEFWgMM/DJpneMO3d
+j/DDloaxwRP51nHC1DpSHDLX/02aDn0Wlvs5izAwmdz6yF7WyCeMpFHegvQSeOc9
+gtFDwsuZ4oZI9lyde0HfDYCaGQdbRbbqC3gMY3OsOyNs1xIKXk0OT8rhAoGAfivg
+Qda+1hcJnUu39HD306kRsiGNrOkIIZHO95/uxRdC/JcYt12zSl32bZ7FfT8HE9Lx
+lnMS2GREvMX+73JYxHAEnSRfNzjXMy9oucltMiZ0hNnlnfxRueYZtBSIMaZUjTIJ
+RPYs0XL9kUF18+uDqqs8zTZ1VzmOGBmR/eWblIUCgYAHOewawwwxFxCxRDjjMdOM
+APweu1nzcFBs3VyvYTYSK0J9T/qN9uA/h72IyRFxDEW1yBbMyhbS3gE9d6LAoaO6
+LNgsVj2mRUduTp0vHGtLimqLzOGy96IgFErYQFtbY1DrbgfEhDgu8JmGBJ8g3SAz
+6JK2cy6SzW+pxV092xeJ4g==
+-----END PRIVATE KEY-----

modules/secureboot/dev-keys/KEK.key.license

@@ -0,0 +1,2 @@
+SPDX-FileCopyrightText: 2022-2026 TII (SSRC) and the Ghaf contributors
+SPDX-License-Identifier: Apache-2.0