.. _os-signing-keys: ####################### 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/``, 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: .. code-block:: text layers/meta-orchestraos-bsp/common/imx-cst// |-- 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: .. code-block:: bash 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: .. code-block:: bash ./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: .. code-block:: bash 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: .. code-block:: bash export SIGNING_DATA_PATH=/secure/path/to/orchestraos-signing/ 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: .. code-block:: text 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: .. code-block:: bash 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: .. code-block:: bash ./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: .. code-block:: bash 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: .. code-block:: yaml 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: .. code-block:: yaml 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: .. code-block:: bash 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 :ref:`os-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``: .. list-table:: Provisioning operations :header-rows: 1 * - Script - Effect * - ``uuu-.auto`` - Flashes the image using the normal bundle procedure. * - ``uuu-no-bmap-.auto`` - Flashes without the block map. * - ``uuu-fuse-.auto`` - Programs the configured SRK hash into the platform's fuse locations. * - ``uuu-close-.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.