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, as a separate provisioning step, to program the matching SRK hash into device fuses and secure the device.

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.

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.

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.

Fuse The Device With Matching SRK Data

The generated SRK fuse data must match the keys used for signing. The generated UUU bundle contains fuse scripts named with the selected UBOOT_CONFIG:

uuu-fuse-<UBOOT_CONFIG>.auto

For example, if UBOOT_CONFIG is sd, the fuse script is:

sudo uuu build/tmp/deploy/images/<machine>/<image>.rootfs.uuu.zip/uuu-fuse-sd.auto

Fusing must be done only after the signed image has been verified and the SRK hash has been reviewed against the target SoC fuse map. Once the device is closed, it will only boot images signed by a trusted, non-revoked key from the fused SRK table.

Download Code Signing Tool From NXP

The NXP CST package is available from the NXP i.MX software page. Open the NXP i.MX Software page then scroll down to the Other Resources section: