Skip to content

Secure Boot

Complete technical reference for the meta-tolomeo secure boot integration: distro features, include files, classes, recipe variables, and recipes.

DISTRO_FEATURES

Feature What it activates
secure-boot HAB/AHAB U-Boot config fragments, FIT image signing (UBOOT_SIGN_ENABLE=1), and the imx-boot-signature recipe on NXP targets

Classes

Class Layer Scope Purpose
xhab.bbclass meta-tolomeo-nxp NXP signing recipes Maps machine family to signing protocol (hab4 or ahab) and SPSDK family name
sigtool.bbclass meta-tolomeo-nxp NXP signing recipes Validates that the correct signing tool (CST for HAB4, SPSDK for AHAB) is installed at SIG_TOOL_PATH
kernel_fitimage_mcore.bbclass meta-tolomeo-nxp Kernel recipes Builds and RSA-signs FIT images containing the kernel, DTBs, and optional M-core firmware

Include Files

File Layer Used in Purpose
conf/machine/include/u-boot-secure-boot.inc meta-tolomeo-bsp Machine .conf Sets UBOOT_SIGN_ENABLE, UBOOT_SIGN_KEYDIR, UBOOT_SIGN_KEYNAME, UBOOT_FIT_GENERATE_KEYS
recipes-bsp/u-boot/u-boot-fit-signature.inc meta-tolomeo-bsp U-Boot bbappend (generic BSP) Conditionally adds fit-signature.cfg fragment enabling CONFIG_FIT_SIGNATURE=y
recipes-bsp/u-boot/u-boot-secure-boot.inc meta-tolomeo-nxp u-boot-imx_%.bbappend Wrapper that requires both u-boot-fit-signature.inc and u-boot-hab.inc
recipes-bsp/u-boot/u-boot-hab.inc meta-tolomeo-nxp Via u-boot-secure-boot.inc Adds CONFIG_IMX_HAB=y (mx8-generic-bsp) or CONFIG_AHAB_BOOT=y (mx9-generic-bsp)

NXP Boot Signing Variables

Variable Default Set in Description
SIG_TOOL_PATH — kas / local.conf Path to the CST (HAB4) or SPSDK (AHAB) installation directory
SIG_DATA_PATH ${SIG_TOOL_PATH} kas / local.conf Directory containing the signing configuration file; falls back to SIG_TOOL_PATH
AHAB_CFGFILE spsdk_ahab.yaml bbappend / local.conf Filename of the SPSDK AHAB signing configuration
HAB4_CFGFILE csf_hab4.cfg bbappend / local.conf Filename of the CST HAB4 signing configuration
BOOT_VARIANT — kas / local.conf Optional suffix appended to the boot image name
BOOT_SIGN_TYPE derived (xhab) read-only Signing protocol for the target machine: hab4 or ahab
SPSDK_FAMILY derived (xhab) read-only SPSDK family identifier for the target device (e.g. mimx9352)

Signing Data Layout

imx_signer hardcodes two subdirectory names under SIG_DATA_PATH. A flat directory does not work.

<SIG_DATA_PATH>/
├── <AHAB_CFGFILE or HAB4_CFGFILE>
├── crts/
└── keys/
Reference in the signing config Path resolved
srktable_file, csfk_file, img_file, nocak_file (HAB4) ${SIG_DATA_PATH}/crts/<value>
srk_array entries (AHAB) ${SIG_DATA_PATH}/crts/<value>
signer (AHAB) ${SIG_DATA_PATH}/keys/<value>
Private key passphrase ${SIG_DATA_PATH}/keys/key_pass.txt

Three rules follow:

  • Configuration files name bare filenames, never paths. imx_signer prepends the directory.
  • keys/key_pass.txt must exist. For AHAB it is always referenced. For HAB4, CST looks for it beside the private key and treats a missing file as "the keys are not encrypted".
  • CST derives each private key from its certificate by rewriting _crt.pem to _key.pem and the crts path component to keys, which is why the two directories must be siblings.

When a HAB4 configuration field is left empty, imx_signer falls back to crts/SRK_1_2_3_4_table.bin, crts/CSF1_1_sha256_2048_65537_v3_usr_crt.pem, and crts/IMG1_1_sha256_2048_65537_v3_usr_crt.pem — the names produced by a four-SRK, RSA-2048, SHA-256 PKI tree.

FIT Signing Variables

Variable Default Set in Description
UBOOT_SIGN_ENABLE derived read-only "1" when secure-boot is in DISTRO_FEATURES, otherwise "0"
UBOOT_SIGN_KEYDIR "keys" machine conf / kas Directory containing the FIT signing key pair, relative to ${BSPDIR}
UBOOT_SIGN_KEYNAME "dev" machine conf / kas Base name of the key pair; build reads <name>.key and <name>.crt
UBOOT_SIGN_IMG_KEYNAME — machine conf / kas Base name for a separate key used to sign individual FIT image nodes
UBOOT_FIT_GENERATE_KEYS "0" machine conf Set to "1" to auto-generate keys at build time (development only)

Recipes

Recipe Layer Requires Output
imx-boot-signature meta-tolomeo-nxp secure-boot distro feature signed-imx-boot-<machine>.bin in the deploy directory
nxp-imx-signer meta-tolomeo-nxp — imx_signer tool binary in deploy/imx-boot-tools/

See also