Generate a HAB4 PKI Tree¶

This guide covers generating the key set, SRK table, and eFuse hash required to sign i.MX8M boot images with HAB4, using the NXP Code Signing Tool (CST). The resulting key set is consumed by Enable NXP Authenticated Boot.

Prerequisites¶

NXP CST 4.0.1 or later, extracted on the build host
openssl available on the host
An i.MX8M target. i.MX9 targets use AHAB — see Generate an AHAB PKI Tree

Generate the PKI Tree¶

Write the intended passphrase into keys/key_pass.txt, the same value twice, one per line. If the file is absent the script creates it with the password test.

cd <cst>/keys
./hab4_pki_tree.sh \
    -existing-ca n \
    -kt rsa \
    -kl 2048 \
    -duration 10 \
    -num-srk 4 \
    -srk-ca y

Option	Value	Description
`-existing-ca`	`n`	Create a new root CA instead of reusing one
`-kt`	`rsa`	Key type; `rsa-pss` and `ecc` are also accepted
`-kl`	`2048`	RSA key length in bits: 1024, 2048, 3072, or 4096
`-duration`	`10`	Certificate validity in years
`-num-srk`	`4`	Number of SRKs; four leaves one that can never be revoked
`-srk-ca`	`y`	SRK certificates carry the CA flag (standard PKI tree)

The script writes certificates and private keys into two sibling directories of the CST tree, each file in both PEM and DER form:

<cst>/
├── crts/                                             # X.509 certificates
│   ├── CA1_sha256_2048_65537_v3_ca_crt.pem
│   ├── SRK{1..4}_sha256_2048_65537_v3_ca_crt.pem
│   ├── CSF{1..4}_1_sha256_2048_65537_v3_usr_crt.pem
│   └── IMG{1..4}_1_sha256_2048_65537_v3_usr_crt.pem
└── keys/                                             # PKCS#8 private keys
    ├── CA1_sha256_2048_65537_v3_ca_key.pem
    ├── SRK{1..4}_sha256_2048_65537_v3_ca_key.pem
    ├── CSF{1..4}_1_sha256_2048_65537_v3_usr_key.pem
    ├── IMG{1..4}_1_sha256_2048_65537_v3_usr_key.pem
    └── key_pass.txt                                  # passphrase, one line per entry

Note

The key type, length, and digest appear in every filename. Changing -kt or -kl changes every name referenced later in this guide and in csf_hab4.cfg. OpenSSL also leaves serial-numbered certificate copies (keys/1234567*.pem), serial.old, and index.txt.attr behind; they are harmless and can be deleted.

Warning

Restrict permissions on keys/ and never commit it. In production, hold the PKI tree on a host separate from the build machine, or use the CST PKCS#11 back end with an HSM.

Generate the SRK Table and eFuse Hash¶

cd ../crts
SRKS=$(ls -1 SRK[1-4]_sha256_2048_65537_v3_ca_crt.pem | paste -sd,)
../linux64/bin/srktool \
    -h 4 \
    -t SRK_1_2_3_4_table.bin \
    -e SRK_1_2_3_4_fuse.bin \
    -d sha256 \
    -c "$SRKS" \
    -f 1

Option	Description
`-h 4`	HAB version 4
`-t`	Output SRK table, referenced by `srktable_file` in the CSF
`-e`	Output eFuse hash binary
`-d sha256`	Digest algorithm
`-c`	Comma-separated SRK certificates, with no whitespace
`-f 1`	32 bits of eFuse data per word; use `-f 0` for SoCs needing 8 bits per word

Warning

srktool silently drops every certificate listed after a whitespace character in -c, producing a table and hash that omit them. Building the list into $SRKS avoids this.

The tool prints the eight hash words to burn:

SRK HASH[0] = 0x5B31CBE9
SRK HASH[1] = 0x6DE304C8
SRK HASH[2] = 0x99F821DE
SRK HASH[3] = 0x2803B237
SRK HASH[4] = 0xC8EF0FF8
SRK HASH[5] = 0x12F30689
SRK HASH[6] = 0xF38CE4A3
SRK HASH[7] = 0x39669C00

Both output files belong in crts/, alongside the certificates.

Wire the Key Set into the Build¶

imx_signer resolves every file named in csf_hab4.cfg under ${SIG_DATA_PATH}/crts/, and every private key under ${SIG_DATA_PATH}/keys/. Copy the generated crts/ and keys/ contents out of the CST tree and into SIG_DATA_PATH, then assemble the directory accordingly:

<SIG_DATA_PATH>/
├── csf_hab4.cfg
├── crts/
│   ├── SRK_1_2_3_4_table.bin
│   ├── CSF1_1_sha256_2048_65537_v3_usr_crt.pem
│   └── IMG1_1_sha256_2048_65537_v3_usr_crt.pem
└── keys/
    ├── CSF1_1_sha256_2048_65537_v3_usr_key.pem
    ├── IMG1_1_sha256_2048_65537_v3_usr_key.pem
    └── key_pass.txt

Start from devel-keys/secure-boot/hab4/csf_hab4.cfg and set these fields to the matching bare filenames:

CSF field	Value
`srktable_file`	`SRK_1_2_3_4_table.bin`
`srk_source_index`	Index of the SRK used to sign — `0` for SRK1
`csfk_file`	`CSF1_1_sha256_2048_65537_v3_usr_crt.pem`
`img_file`	`IMG1_1_sha256_2048_65537_v3_usr_crt.pem`
`img_verification_index`	`0`
`img_target_index`	`2`
`auth_verification_index`	`2`

Warning

Use bare filenames, never paths. imx_signer prepends ${SIG_DATA_PATH}/crts/, so a path here produces a CSF that CST cannot resolve.

Point the build at the tool and the data directory, then continue with Enable NXP Authenticated Boot:

SIG_TOOL_PATH = "/path/to/cst"
SIG_DATA_PATH = "${BSPDIR}/keys/hab4"

Program the SRK Hash into eFuses¶

Danger

eFuse writes are irreversible. A wrong SRK hash permanently prevents the SoC from booting once the device is closed. Program the hash, read it back, boot a signed image with no HAB events, and only then close the device.

The commands below are for i.MX8M Plus, where SRK_HASH spans fuse banks 6 and 7, words 0–3 each. Other i.MX8M variants follow the same procedure; the fuse map in the SoC reference manual is authoritative.

u-boot=> fuse prog -y 6 0 <SRK_HASH[0]>
u-boot=> fuse prog -y 6 1 <SRK_HASH[1]>
u-boot=> fuse prog -y 6 2 <SRK_HASH[2]>
u-boot=> fuse prog -y 6 3 <SRK_HASH[3]>
u-boot=> fuse prog -y 7 0 <SRK_HASH[4]>
u-boot=> fuse prog -y 7 1 <SRK_HASH[5]>
u-boot=> fuse prog -y 7 2 <SRK_HASH[6]>
u-boot=> fuse prog -y 7 3 <SRK_HASH[7]>

Read the values back:

u-boot=> fuse read 6 0 4
u-boot=> fuse read 7 0 4

Boot the signed image and confirm HAB reports no events:

u-boot=> hab_status

Close the device by blowing SEC_CONFIG[1]. This is the final, irreversible step:

u-boot=> fuse prog -y 1 3 0x2000000

Automation

SRK extraction and fuse programming are manual today. The secure boot recipes under meta-tolomeo-nxp may automate SRK hash extraction and fuse-script generation in a future release.

Development Keys¶

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

File	Purpose
`devel-keys/secure-boot/hab4/csf_hab4.cfg`	CST HAB4 signing configuration
`devel-keys/secure-boot/hab4/crts/`	SRK, CSF, and IMG certificates, SRK table, eFuse hash
`devel-keys/secure-boot/hab4/keys/`	Matching private keys and `key_pass.txt`

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, and never fuse their SRK hash into a shipping SoC.