Signing Keys Generation

OrchestraOS BSP signing for NXP targets uses the NXP Code Signing Tool (CST) key layout described in CST_UG.pdf. The generated keys and certificates are used by meta-orchestraos-bsp during the image build. UUU fuse scripts are used later to program the matching SRK hash. Closing the device is a separate, platform-specific provisioning operation.

Machine signing data is selected through SIG_DATA_PATH. By default it points to layers/meta-orchestraos-bsp/common/imx-cst/<machine>, but it can also point to an external key directory.

Signing Tools Supplied by the Build

The image build fetches and builds its signing tools through Yocto recipes. imx-cst-native supplies CST and srktool; the native signer integration also brings in python3-spsdk-native for the AHAB path. The BSP selects SIG_TOOL_PATH in the native recipe sysroot. A manual download of the NXP CST package is not a prerequisite for the reference image build.

Production key generation is a separate provisioning activity. The examples below assume a private CST workspace containing NXP’s hab4_pki_tree.sh or ahab_pki_tree.sh scripts and their associated inputs. Those offline PKI scripts are not installed by the image build’s CST recipe. Prepare that workspace separately when generating new keys; image builds consume the resulting signing data through SIG_DATA_PATH.

Warning

Secure-boot fuse provisioning is irreversible on production devices. Keep private keys protected, and test the complete signing and flashing flow on sacrificial hardware before fusing production devices.

Key Layout Used By OrchestraOS

meta-orchestraos-bsp expects the directory referenced by SIG_DATA_PATH to use this layout:

layers/meta-orchestraos-bsp/common/imx-cst/<machine>/
|-- crts/
|   |-- SRK_1_2_3_4_table.bin
|   |-- SRK_1_2_3_4_fuse.bin
|   `-- *_crt.pem / *_crt.der
|-- keys/
|   `-- *_key.pem / *_key.der
|-- csf_hab4.cfg
`-- spsdk_ahab.yaml

Not every machine uses every file:

• HAB4 targets use CST keys/certificates, SRK_1_2_3_4_table.bin, SRK_1_2_3_4_fuse.bin, and csf_hab4.cfg.

• AHAB targets use SRK keys/certificates and spsdk_ahab.yaml.

• EIGXS also uses an OS-container template describing kernel, device-tree, and initramfs placement. AHAB_OS_CONTAINER_CONFIG selects the board’s template independently of SIG_DATA_PATH and permits an explicit override.

If SIG_DATA_PATH points outside the repository and the build runs through kas-container, make sure that directory is mounted into the container and that the path used by BitBake matches the path visible inside the container. This may require extending the container runtime arguments or wrapper configuration used by your build environment.

Generate HAB4 Keys

Use HAB4 keys for i.MX devices that boot through HAB4, such as EIG-M and EIG-MA.

1. Prepare a private CST workspace outside the repository:

   export CST_WORKDIR=/secure/path/to/cst
   cd ${CST_WORKDIR}/keys
   openssl rand -hex 16 > serial
   printf "replace-with-a-strong-passphrase\nreplace-with-a-strong-passphrase\n" > key_pass.txt
   chmod 600 key_pass.txt
   

2. Generate the HAB4 PKI tree. A typical non-interactive RSA tree with four SRKs is:

   ./hab4_pki_tree.sh \
     -existing-ca n \
     -kt rsa \
     -kl 2048 \
     -duration 10 \
     -num-srk 4 \
     -srk-ca y
   

   This creates CA, SRK, CSF, and IMG private keys under keys/ and matching X.509 certificates under crts/. Private keys are encrypted with the passphrase from key_pass.txt.

3. Generate the HAB4 SRK table and fuse hash from the SRK certificates:

   cd ${CST_WORKDIR}/crts
   srktool --hab_ver 4 \
     --table SRK_1_2_3_4_table.bin \
     --efuses SRK_1_2_3_4_fuse.bin \
     --digest sha256 \
     --certs SRK1_sha256_2048_65537_v3_ca_crt.pem,SRK2_sha256_2048_65537_v3_ca_crt.pem,SRK3_sha256_2048_65537_v3_ca_crt.pem,SRK4_sha256_2048_65537_v3_ca_crt.pem
   

   Do not insert spaces in the certificate list. The generated fuse file is the SRK hash that must match the value fused into the device.

4. Arrange the generated files into a signing-data directory that follows the SIG_DATA_PATH layout:

   export SIGNING_DATA_PATH=/secure/path/to/orchestraos-signing/<machine>
   install -d ${SIGNING_DATA_PATH}/keys
   install -d ${SIGNING_DATA_PATH}/crts
   cp ${CST_WORKDIR}/keys/* ${SIGNING_DATA_PATH}/keys/
   cp ${CST_WORKDIR}/crts/* ${SIGNING_DATA_PATH}/crts/
   

5. Place or update csf_hab4.cfg in the same SIG_DATA_PATH directory if you change the selected SRK, CSF key, or IMG key:

   srktable_file=SRK_1_2_3_4_table.bin
   srk_source_index=0
   csfk_file=CSF1_1_sha256_2048_65537_v3_usr_crt.pem
   img_file=IMG1_1_sha256_2048_65537_v3_usr_crt.pem
   

Generate AHAB Keys

Use AHAB keys for targets that boot through AHAB, such as i.MX93/EIG-XS.

1. Prepare a private CST workspace outside the repository:

   export CST_WORKDIR=/secure/path/to/cst
   cd ${CST_WORKDIR}/keys
   openssl rand -hex 16 > serial
   printf "replace-with-a-strong-passphrase\nreplace-with-a-strong-passphrase\n" > key_pass.txt
   chmod 600 key_pass.txt
   

2. Generate the AHAB PKI tree. The EIG-XS reference configuration uses ECDSA P-256 SRKs with SHA-256:

   ./ahab_pki_tree.sh \
     -existing-ca n \
     -kt ecc \
     -kl p256 \
     -da sha256 \
     -duration 10 \
     -srk-ca n
   

3. Arrange the generated files into a signing-data directory that follows the SIG_DATA_PATH layout:

   export SIGNING_DATA_PATH=/secure/path/to/orchestraos-signing/eigxs
   install -d ${SIGNING_DATA_PATH}/keys
   install -d ${SIGNING_DATA_PATH}/crts
   cp ${CST_WORKDIR}/keys/* ${SIGNING_DATA_PATH}/keys/
   cp ${CST_WORKDIR}/crts/* ${SIGNING_DATA_PATH}/crts/
   

4. Place or update spsdk_ahab.yaml in the same SIG_DATA_PATH directory so it references the selected key and SRK certificates:

   used_srk_id: 0
   signer: SRK1_sha256_secp256r1_v3_usr_key.pem
   srk_table:
     flag_ca: false
     hash_algorithm: sha256
     srk_array:
       - SRK1_sha256_secp256r1_v3_usr_crt.pem
       - SRK2_sha256_secp256r1_v3_usr_crt.pem
       - SRK3_sha256_secp256r1_v3_usr_crt.pem
       - SRK4_sha256_secp256r1_v3_usr_crt.pem
   

Build With The Generated Keys

Set SIG_DATA_PATH to the signing-data directory in the selected KAS configuration or another local configuration layer:

local_conf_header:
  signing-data-path: |
    SIG_DATA_PATH = "/secure/path/to/orchestraos-signing/eigm"

If the path is outside the checkout and the build runs through kas-container, make the key directory available inside the container before running BitBake:

kas-container ${REPO_ACCESS} \
  --runtime-args "-v /secure/path/to/orchestraos-signing:/secure/path/to/orchestraos-signing:ro" \
  build ci/orcos/orcos-cmdline-rauc-eigm-release.yml

The exact container argument depends on the local build wrapper. The important requirement is that BitBake can read the path assigned to SIG_DATA_PATH from inside the build container.

For machines with imx-boot-signature or linux-imx-signature enabled, the build produces signed bootloader and/or kernel artifacts. The signed kernel is installed into the boot filesystem in place of the unsigned image, and RAUC bootloader slots use the signed bootloader artifact when secure boot signing is enabled.

External Signing Keys

The optional NetHSM Signing extension integrates Nitrokey NetHSM with boot-artifact and RAUC bundle signing. Its layer repository maintains the provider setup, authentication, and key-selection instructions in README.md.

RAUC Bundle Signing

RAUC uses its own RAUC_SIGNING_KEY, RAUC_SIGNING_CERT, and RAUC_KEYRING_FILE_SRC settings. The first two sign the update bundle; the keyring defines which bundle certificates the installed image trusts. Configure these together in the project layer and plan certificate renewal or rotation for installed devices. Replacing the HAB4/AHAB keys does not replace the RAUC trust chain, and vice versa.

Program the SRK Hash and Close the Device

The generated UUU archive provides separate scripts named by UBOOT_CONFIG:

Provisioning operations

Script	Effect
uuu-<UBOOT_CONFIG>.auto	Flashes the image using the normal bundle procedure.
uuu-no-bmap-<UBOOT_CONFIG>.auto	Flashes without the block map.
uuu-fuse-<UBOOT_CONFIG>.auto	Programs the configured SRK hash into the platform’s fuse locations.
uuu-close-<UBOOT_CONFIG>.auto	Runs the HAB4 device-closing procedure on supported i.MX8M targets.

For EIG-M, choose the actual memory variant, such as sd-d2 or sd-d4. Check the scripts generated in the archive for the selected machine rather than assuming every machine uses the generic sd configuration.

First validate the signed boot image and review its SRK hash against the target SoC’s fuse map. Program the matching hash, verify the boot authentication state, and only then apply the platform’s closing procedure. The HAB4 close script compares the expected SRK hash, checks the HAB event log with hab_event_check, and attempts the closing fuse operation when those checks allow it. Review the command results and the device state explicitly.

Fuse programming and closing are irreversible. The key hash, signed software, and production provisioning procedure must agree before these operations are performed. Once a device enforces authenticated boot, recovery depends on retaining the appropriate trusted signing material and supported recovery path.