Skip to content

Enable NXP Authenticated Boot

This guide covers enabling HAB4 (i.MX8M) or AHAB (i.MX9) authenticated boot in a custom BSP layer built on top of meta-tolomeo-nxp.

Prerequisites

Enable the Distro Feature

Add to your distro configuration file:

DISTRO_FEATURES += "tlm-secure-boot"

Declare it in the distro configuration only: tolomeo.inc assigns DISTRO_FEATURES with =, so a += in a machine configuration is discarded.

Include the U-Boot Fragment

Add to your u-boot-imx_%.bbappend file inside your BSP layer:

require recipes-bsp/u-boot/u-boot-secure-boot.inc

This include is provided by meta-tolomeo-nxp. It pulls in:

  • FIT image signature support (CONFIG_FIT_SIGNATURE=y, CONFIG_RSA=y)
  • The HAB/AHAB U-Boot config fragment:
  • CONFIG_IMX_HAB=y for i.MX8M (mx8-generic-bsp)
  • CONFIG_AHAB_BOOT=y for i.MX9 (mx9-generic-bsp)

Configure the Signing Tool

The meta-tolomeo-nxp kas fragment sets SIG_TOOL_PATH to ${BSPDIR}/venv/bin and SIG_DATA_PATH to ${BSPDIR}/keys/secure-boot. Set the variables in your kas configuration file or local.conf to override them:

# Path to the SPSDK or CST installation
SIG_TOOL_PATH = "/path/to/spsdk-or-cst"

# Directory holding the signing configuration file, plus crts/ and keys/
# Falls back to SIG_TOOL_PATH when empty
SIG_DATA_PATH = "${BSPDIR}/keys/secure-boot"

Place your signing configuration file in SIG_DATA_PATH:

Target family Config file Variable
i.MX9 (AHAB) spsdk_ahab.yaml AHAB_CFGFILE
i.MX8M (HAB4) csf_hab4.cfg HAB4_CFGFILE

The default config filenames can be overridden — see Secure Boot.

SIG_DATA_PATH must also contain crts/ and keys/ subdirectories. imx_signer resolves every certificate named in the configuration under ${SIG_DATA_PATH}/crts/, every private key under ${SIG_DATA_PATH}/keys/, and the key passphrase from ${SIG_DATA_PATH}/keys/key_pass.txt. See Secure Boot for the full layout.

Build

Run the build as usual. The imx-boot-signature recipe runs automatically when tlm-secure-boot is active:

kas build kas/<your-machine>_<your-distro>_<your-image>.yml

The signed boot image is written to the deploy directory:

build/tmp-glibc/deploy/images/<machine>/signed-imx-boot-<machine>.bin

Use the Development Keys (Optional)

DAVE provides pre-generated key material in devel-keys/ for build validation without requiring a production PKI:

File Purpose
devel-keys/secure-boot/ahab/spsdk_ahab.yaml AHAB signing configuration for mimx9352
devel-keys/secure-boot/ahab/crts/ SRK certificate set SRK0 to SRK3 (secp384r1)
devel-keys/secure-boot/ahab/keys/ SRK private keys and key_pass.txt
devel-keys/secure-boot/hab4/csf_hab4.cfg CST HAB4 signing configuration
devel-keys/secure-boot/hab4/crts/ SRK, CSF, IMG certificates and SRK table
devel-keys/secure-boot/hab4/keys/ Matching private keys and key_pass.txt

To use the development keys, point SIG_DATA_PATH at the subdirectory for your signing protocol:

# i.MX9 (AHAB)
SIG_DATA_PATH = "${BSPDIR}/devel-keys/secure-boot/ahab"

# i.MX8M (HAB4)
SIG_DATA_PATH = "${BSPDIR}/devel-keys/secure-boot/hab4"

Warning

The keys in devel-keys/ are publicly known and exist only for build validation. Never use them on a production device.

See also