Secure Boot¶
Secure boot is the tlm-secure-boot distro feature plus the classes, includes, variables and recipes that sign the boot
chain.
DISTRO_FEATURES¶
| Feature | What it activates |
|---|---|
tlm-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 |
meta-tolomeo-nxp |
NXP signing recipes | Maps machine family to signing protocol (hab4 or ahab) and SPSDK family name |
sigtool |
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 |
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) |
† The meta-tolomeo-nxp kas fragment sets SIG_TOOL_PATH to ${BSPDIR}/venv/bin and SIG_DATA_PATH to
${BSPDIR}/keys/secure-boot.
Signing Data Layout¶
imx_signer hardcodes two subdirectory names under SIG_DATA_PATH. A flat directory does not work.
| 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_signerprepends the directory. keys/key_pass.txtmust 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.pemto_key.pemand thecrtspath component tokeys, 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 tlm-secure-boot is in DISTRO_FEATURES, otherwise "0" |
UBOOT_SIGN_KEYDIR |
"keys"† |
machine conf / kas | Directory containing the FIT signing key pair |
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) |
† The meta-tolomeo-bsp kas fragment sets UBOOT_SIGN_KEYDIR to ${BSPDIR}/keys and UBOOT_SIGN_KEYNAME to
fitImage-sign.
Recipes¶
| Recipe | Layer | Requires | Output |
|---|---|---|---|
imx-boot-signature |
meta-tolomeo-nxp |
tlm-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
- Enable NXP Authenticated Boot — HAB4/AHAB task guide
- Enable FIT Image Signing — FIT signing task guide
- Secure Boot Chain — design rationale
- Generate a HAB4 PKI Tree — CST key generation
- Generate an AHAB PKI Tree — SPSDK key generation