Skip to content

Secure boot signing

Secure boot signing

Secure boot signing ensures that only trusted, cryptographically verified code runs during the boot process. When you enable UEFI Secure Boot, the firmware validates the bootloader, initrd, kernel, kernel modules, and kernel command line against a set of trusted signing keys before allowing execution.

Automotive Image Builder provides a set of commands that integrate signing into the image build workflow.

How signing relates to image sealing

AutoSD uses composefs to seal the root filesystem, which ensures that the contents of a deployed image match exactly what was built. Signing and sealing form a chain of trust:

  1. The composefs public key is embedded in the initramfs. At boot, the initramfs uses the key to verify that every file in the root filesystem matches what was originally built.
  2. Secure Boot signing validates the initramfs itself (and the bootloader, kernel, and kernel command line). The firmware checks the signature before executing any boot code.

Because the composefs key lives inside the initramfs, and the initramfs is validated by Secure Boot, the entire filesystem is trusted. A fully secured image uses both mechanisms: Secure Boot proves the boot chain is authentic, and composefs proves the filesystem has not been tampered with.

For more information on how composefs protects the filesystem, see Tamperproof OS.

Signing workflow overview

The signing workflow uses several aib commands in sequence.

Note

The prepare-reseal step in this workflow is specific to Secure Boot. If the image does not require Secure Boot signing, use aib reseal to seal the image directly after building.

  1. aib build: Build a bootc container image from a manifest. The resulting image contains unsigned boot artifacts. If the image requires post-build modifications (for example, layering additional packages with a Containerfile), apply those changes before proceeding to the signing steps.
  2. aib prepare-reseal: Inject the composefs public key into the initramfs and write the result to a new image. This step separates the key injection from the final reseal so that the initramfs can be signed in between. The command takes a source image and a destination image name; it does not modify the source in place.
  3. aib extract-for-signing: Extract the boot-critical files (EFI executables and boot partition images) from the prepared image into a local directory for signing.
  4. Sign the extracted files. Use your organization's signing infrastructure (for example, an HSM, a signing service, or pesign/sbsign) to apply Secure Boot signatures to the extracted files.
  5. aib inject-signed: Inject the signed files back into the prepared image, replacing the unsigned originals. Pass --reseal-with-key to reseal the image in the same step.
  6. aib to-disk-image: Convert the sealed container image to a bootable disk image for deployment.

Note

The to-disk-image step applies to initial provisioning only. For over-the-air (OTA) updates to an already installed system, deploy the signed container image directly without converting to a disk image.

Understanding prepare-reseal

A normal reseal operation regenerates the initramfs as part of injecting a new composefs key. If the initramfs has already been signed for Secure Boot, regenerating it destroys the signature and the image will not boot.

The prepare-reseal command solves this problem by separating the key injection into its own step. After prepare-reseal writes the new initramfs, you can extract and sign it before calling inject-signed --reseal-with-key to finalize the image without regenerating the initramfs again.

Outside of Secure Boot workflows, the standard reseal command handles key injection and signing in a single step. The prepare-reseal command exists specifically for the use case where the initramfs must be signed for Secure Boot between key injection and the final reseal.

All image modifications (layering, configuration injection, and similar changes) must happen before prepare-reseal. Any change after prepare-reseal that alters the initramfs invalidates the signature.

build --> [optional: modify image] --> prepare-reseal
      --> extract-for-signing --> sign
      --> inject-signed (--reseal-with-key) --> to-disk-image
Next steps

For step-by-step instructions, see Signing a bootc image for secure boot.