U-Boot Secure Boot: FIT Signatures and Chain of Trust

Understand U-Boot FIT signatures, trusted control device trees and boot-chain limits with a versioned example and explicit rejection and recovery tests.

U-Boot Secure Boot: FIT Signatures and Chain of Trust

An enforced boot chain authenticates the objects it covers. Mutable execution paths and recovery mechanisms need their own controls. In embedded Linux systems using U-Boot, the Flattened Image Tree (FIT) format provides a structured way to bundle kernel, device tree, and initramfs images with cryptographic signatures. This guide explains the signing objects, trust boundaries and failure tests using the U-Boot v2025.01 documentation. The example is illustrative and has not been executed as a complete boot sequence.

What the chain of trust looks like

A complete chain of trust for an embedded Linux device typically has three or four stages:

  1. ROM bootloader (in silicon) → verifies the secondary bootloader
  2. Secondary bootloader (SPL/TPL) → verifies U-Boot proper
  3. U-Boot → verifies the FIT image (kernel + DTB + optional initramfs)
  4. Kernel → verifies the root filesystem (via dm-verity or IMA)

This guide focuses on stage 3: U-Boot verifying a signed FIT image. For root filesystem verification, see dm-verity for root filesystem integrity.

Understand the boot process end-to-end

Secure boot spans hardware, bootloader, kernel, and filesystem layers. A solid grounding in how operating systems initialise hardware, load code, and transition between privilege levels makes this chain of trust easier to reason about. The Fundamentals of Operating Systems course is a good place to build that understanding.

FIT image structure

A FIT image is a single binary containing multiple components described by an embedded device tree structure. A typical signed FIT image includes:

/images/
    kernel-1   → compressed kernel binary
    fdt-1      → device tree blob
    ramdisk-1  → initramfs (optional)
/configurations/
    conf-1     → ties kernel + fdt + ramdisk together
               → carries the RSA signature

The configuration node is what gets signed. This means the signature covers the specific combination of kernel, device tree, and initramfs. Swapping any component invalidates the signature.

Key generation

Generate an RSA key pair. U-Boot supports RSA-2048, RSA-3072, and RSA-4096. Use RSA-4096 for new designs unless performance constraints dictate otherwise.

# Illustrative U-Boot v2025.01 key-directory layout, disposable keys only
mkdir -p keys
openssl genpkey -algorithm RSA -out keys/sign-key.key -pkeyopt rsa_keygen_bits:4096
openssl req -new -x509 -key keys/sign-key.key -out keys/sign-key.crt -subj /CN=Disposable-FIT-Test/

The private key signs images during the build. The public key is embedded in U-Boot itself (or in the SPL that verifies U-Boot). Protect the private key; if it leaks, an attacker can sign arbitrary images.

Embedding the public key in U-Boot

U-Boot stores the public key in its control device tree (the DTB compiled into U-Boot or loaded alongside it). The mkimage tool handles this during the signing step.

Use the control DTB generated by the pinned U-Boot build. Keep a disposable copy for the signing test. mkimage creates the public-key properties from the matching certificate; a handwritten node containing only an algorithm and name is not a complete verification key.

During the FIT signing step, mkimage -K writes public-key parameters into the specified control DTB. That updated DTB must be the trusted one actually used by U-Boot.

Creating and signing a FIT image

Write a FIT image description (.its file):

/dts-v1/;

/ {
    description = "Signed kernel image";
    #address-cells = <1>;

    images {
        kernel-1 {
            description = "Linux kernel";
            data = /incbin/("Image.gz");
            type = "kernel";
            arch = "arm64";
            os = "linux";
            compression = "gzip";
            load = <0x40480000>;
            entry = <0x40480000>;
            hash-1 {
                algo = "sha256";
            };
        };
        fdt-1 {
            description = "Device tree";
            data = /incbin/("target.dtb");
            type = "flat_dt";
            arch = "arm64";
            compression = "none";
            hash-1 {
                algo = "sha256";
            };
        };
    };

    configurations {
        default = "conf-1";
        conf-1 {
            description = "Boot configuration";
            kernel = "kernel-1";
            fdt = "fdt-1";
            signature-1 {
                algo = "sha256,rsa4096";
                key-name-hint = "sign-key";
                sign-images = "kernel", "fdt";
            };
        };
    };
};

Sign the image:

mkimage -f image.its -k keys -K u-boot.dtb -r fitImage

The -k flag selects the directory containing matching sign-key.key and sign-key.crt files. The -K flag selects the control DTB to receive public-key parameters. The -r flag marks the key as "required" in the U-Boot DTB, meaning U-Boot will refuse to boot unsigned or incorrectly signed configurations.

Configuring U-Boot for verified boot

Enable these options in your U-Boot defconfig:

CONFIG_FIT=y
CONFIG_FIT_SIGNATURE=y
CONFIG_RSA=y
CONFIG_FIT_VERBOSE=y
# CONFIG_LEGACY_IMAGE_FORMAT is not set

Disabling LEGACY_IMAGE_FORMAT is important. If legacy image format is enabled, an attacker can bypass FIT signature verification by providing a legacy (unsigned) image instead.

Boot flow with verification

When U-Boot boots a signed FIT image:

  1. U-Boot parses the FIT structure
  2. For each configuration, U-Boot checks if a signature node exists
  3. U-Boot computes the hash of the referenced images (kernel, DTB, etc.)
  4. U-Boot verifies the signature against the embedded public key
  5. If verification succeeds, boot proceeds. If it fails, U-Boot halts or falls back (depending on configuration)

Failure modes and handling

What happens when verification fails matters as much as the verification itself.

A failed required-signature check must stop that boot attempt. The surrounding boot script decides whether to stop or try an independently authenticated recovery image. Inspect all subsequent commands: a failed bootm command must not fall through to an unsigned boot path.

The required key policy applies to the verified FIT operation. It does not authenticate a mutable U-Boot environment or remove alternative execution commands. Constrain those paths and test the actual deployed configuration, including recovery and provisioning modes.

Recovery mechanisms

A device that refuses to boot due to a failed signature check needs a recovery path:

  • Dual-bank (A/B) boot: Maintain two image slots. If the primary fails verification, boot the secondary. Plan A/B updates and rollback with bounded retries and an authenticated recovery image.
  • Recovery partition: A minimal, separately-signed recovery image that can download and flash a new primary image.
  • Serial/USB recovery: U-Boot's USB DFU or serial boot modes can load a new image. These should be disabled or authenticated in production.

Key rotation

Plan for key rotation from the start. Embed a "next key" slot in your U-Boot DTB. When you need to rotate keys:

  1. Sign a transition image with the old key
  2. The transition image contains U-Boot with the new public key embedded
  3. Subsequent images are signed with the new key

Without a key rotation mechanism, a compromised key means replacing U-Boot itself, which may require physical access.

Testing the chain

Test both the happy path and the failure path:

Use the U-Boot v2025.01 sandbox verified-boot tests as the disposable integration reference. Record the source revision, build configuration and complete test log. The fragments above describe the signing layout and require board-specific addresses and input images. They have not been executed as a complete boot sequence here. U-Boot v2025.01 FIT signature documentation.

Test a valid signed configuration, a changed signed component, a missing required signature and an untrusted signing key. Use a copy of the FIT and identify the component through the image tree. A fixed byte offset can modify the wrong region. Verify that each rejected image enters the intended bounded recovery flow.

Download the implementation-review worksheet. Record how the control DTB is authenticated, how mutable boot arguments are constrained, and which recovery commands can load code. Hardware-anchored secure boot also requires the ROM-to-bootloader chain and provisioning policy to be verified on the actual platform.

Integrating these cases into your CI pipeline alongside automated code review checks helps catch regressions in signing configuration before they reach hardware.

For teams working within the ProteanOS ecosystem, U-Boot verification patterns and failure modes covers additional U-Boot verification scenarios including key storage locations and common failure modes across different SoC families.

The board bring-up checklist includes secure boot as a bring-up milestone for new hardware platforms.

Summary

FIT image signing with U-Boot provides a practical, well-tested mechanism for embedded secure boot. The key steps are: generate keys, embed the public key in U-Boot, sign FIT images during the build, and configure U-Boot to require valid signatures. Test failure modes thoroughly and plan key rotation before your first production shipment.