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. It covers the BitBake integration steps only.

Prerequisites

Enable the Distro Feature

Add to your distro configuration file or machine configuration file:

DISTRO_FEATURES += "secure-boot"

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

Set the following variables in your kas configuration file or local.conf:

# 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/
# Defaults to SIG_TOOL_PATH when not set
SIG_DATA_PATH = "${BSPDIR}/keys/ahab"

Place your signing configuration file in SIG_DATA_PATH:

Target family Config file Default 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 Reference.

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 Reference for the full layout.

Build

Run the build as usual. The imx-boot-signature recipe runs automatically when 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

Development Keys

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–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