.. _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, 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/``, 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: .. 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``. 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. 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``: .. code-block:: text uuu-fuse-.auto For example, if ``UBOOT_CONFIG`` is ``sd``, the fuse script is: .. code-block:: bash sudo uuu build/tmp/deploy/images//.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: .. image:: /chapters/orchestra-os/images/NXP_iMX_Software.png :alt: NXP i.MX software page showing Code Signing Tool download :width: 720px :align: center