Add a step-by-step guide describing how to securely boot an i.MX93 image using AHAB.
This guide is largely based on the following documents: - doc/imx/ahab/guides/mx8ulp_9x_secure_boot.txt, from uboot-imx (lf_v2026.04), originally written by Utkarsh Gupta - doc/imx/habv4/guides/mx8m_spl_secure_boot.txt, from this tree, originally written by Marek Vasut Signed-off-by: Jérémie Dautheribes (Schneider Electric) <[email protected]> --- doc/imx/ahab/guides/mx93_secure_boot.txt | 269 +++++++++++++++++++++++++++++++ 1 file changed, 269 insertions(+) diff --git a/doc/imx/ahab/guides/mx93_secure_boot.txt b/doc/imx/ahab/guides/mx93_secure_boot.txt new file mode 100644 index 00000000000..45a70926d51 --- /dev/null +++ b/doc/imx/ahab/guides/mx93_secure_boot.txt @@ -0,0 +1,269 @@ ++=========================================================+ ++ i.MX93 Secure boot guide using AHAB + ++=========================================================+ + +1. AHAB secure boot process +---------------------------- + +This document provides a step-by-step guide on how to securely boot an +i.MX93 boot image. It is assumed that the reader is familiar with basic +AHAB concepts and with the PKI tree generation. Details about AHAB can be +found in the introduction_ahab.txt document and in processors Security +Reference Manual Document (SRM). The i.MX93 signing procedure is +integrated in the U-Boot build thanks to binman. + +1.1 Preparing the environment to build a secure boot image +----------------------------------------------------------- + +Secure boot image preparation requires the U-Boot build system to build +the image and the Code Signing Tool (CST) to sign it. + +Based on boot mode, the following files are needed to prepare the boot +image: + +- All boot modes + - Edgelock secure enclave Firmware (ELE) (Optional). + - DDR PHY initialization firmware. + - U-Boot proper and SPL. + - ARM Trusted Firmware (ATF). + - OPTEE (Optional) + +The ELE FW is distributed by NXP and is already signed using NXP keys. +In the following sections, <work> designates the repository where all +parts have been downloaded and built. + +1.2 Preparing U-Boot to support AHAB secure boot features +---------------------------------------------------------- + +The U-Boot/SPL provides extra AHAB supported functionalities that include +extension of Root of Trust, checking any events(issues) after image +authentication, chip lifecycle status, securing the target etc. + +The support is enabled by adding CONFIG_AHAB_BOOT to the defconfig file +used by your target: + + - Defconfig: + CONFIG_AHAB_BOOT=y + - Kconfig: + ARM architecture -> Support i.MX9 AHAB features + +Enabling this feature allows the SPL and U-Boot images to extend the Root +of Trust by using the AHAB API call via ELE FW. It also enables binman to +automatically sign the SPL and U-Boot containers while building +flash.bin, as described in the next sections. + +1.3 i.MX93 AHAB image layout +----------------------------- + +The i.MX93 flash.bin image is built by binman and is composed of up to +three containers. The ELE FW container is optional and is provided by NXP, +it is appended at the beginning of the image when the file +mx93a1-ahab-container.img is present in the build directory. The SPL and +U-Boot containers are built by the nxp-imx9image etype and signed by the +nxp-imx93cst etype. + + *start ----> +---------------------------+ --------- + | 1st Container header | ^ + | and signature | | Authenticated at + +---------------------------+ | ELE ROM/FW Level + | Padding | | + +---------------------------+ | + | ELE FW | v + *start + 0x400 ---> +---------------------------+ --------- + | 2nd Container header | ^ + | and signature | | Authenticated at + +---------------------------+ | ELE ROM/FW Level + | Padding | | + +---------------------------+ | + | SPL | v + +---------------------------+ --------- + | 3rd Container header | ^ + | and signature | | Authenticated at + +---------------------------+ | SPL Level + | Padding | | + +---------------------------+ | + | ARM Trusted FW (ATF) | | + +---------------------------+ | + | U-Boot proper | | + +---------------------------+ | + | OPTEE (optional) | v + +---------------------------+ --------- + +The first container includes the ELE FW which is signed using NXP keys, +this container is authenticated by ELE ROM. + +The second container includes the SPL which is signed using OEM keys, +this container is authenticated at ELE FW level. + +The third container includes the U-Boot proper and the ATF. The SPL is in +charge to load this container and also to interface with ELE FW to +authenticate the additional container. + +The signing procedure is slightly different when compared with HABv4 +series. On AHAB the signature is directly included in the container, the +CST is responsible to sign and handle the "Signature Block": + + +----------------------------+ --------- + | | ^ + | | | + | Container header | | + | | | + | | | + +---+------------------------+ | + | S | Signature block header | | Signed + | i +------------------------+ | + | g | | | + | n | | | + | a | SRK table | | + | t | | | + | u | | v + | r +------------------------+ --------- + | e | Signature | + | +------------------------+ + | B | | + | l | SGK Key | + | o | Certificate (optional) | + | c | | + | k | | + +---+------------------------+ + +The certificate block is divided into: + + +---------------+ ^ + | Public key | | Signed + | Permission | | + +---------------+ v + | Signature | + +---------------+ + +The first block (public key permission) verifies the Signature block +preceding (between SRK table and Certificate blocks), while the second +block (signature) is verified by the SRK table block. + +In case not using the subordinate key, the container signature is +verified against the SRK keys directly. + +1.4 Signing the images +----------------------- + +Internally, Command Sequence Files (CSF) are used. The CSF files contain +all the commands that the AHAB executes during the secure boot. These +commands instruct the AHAB code on which memory areas of the image to +authenticate, which keys to install, use and etc. The CSF is generated +using the CST Code Signing Tool based on input configuration file. This +tool input configuration file is generated using binman, and the tool +is invoked from binman as well. + +The existing file structure is automatically collected by the nxp-imx93cst +etype and submitted as a single signing operation: the container header +and the signature block offsets are read from the i.MX container header, +so the offsets in the CST configuration file are always correct, whether +the ELE FW is bundled in the image or not. + +Per default the AHAB keys and certificates need to be located in the +build directory, this means creating a symbolic link or copying the +following files from the AHAB PKI tree directory into the u-boot build +directory for the CST Code Signing Tool to locate them: + +- `crts/SRK_1_2_3_4_table.bin` +- `crts/SRK1_sha384_secp384r1_v3_usr_crt.pem` +- `keys/SRK1_sha384_secp384r1_v3_usr_key.pem` +- `keys/key_pass.txt` + +See the introduction_ahab.txt document for the PKI tree generation +procedure (ahab_pki_tree tool) and for the SRK Table generation +(srktool, use the SHA256 variant for i.MX93). + +The paths to the SRK table and the certificate can be modified via +changes to the nxp-imx93cst device tree node(s) or via the environment +variables. + +The nxp-imx93cst etype is configurable using either DT properties or +environment variables. The following DT properties and environment +variables are supported. Note that environment variables override DT +properties. + ++--------------------+-------------+--------------------------------------------------------------+ +| DT property | Variable | Description | ++====================+=============+==============================================================+ +| nxp,srk-table | SRK_TABLE | full path to SRK_1_2_3_4_table.bin | ++--------------------+-------------+--------------------------------------------------------------+ +| nxp,srk-crt | SRK_KEY | full path to the SRK Key SRK1_sha384_secp384r1_v3_usr_crt.pem| ++--------------------+-------------+--------------------------------------------------------------+ + +Environment variables can be set as follows to point the build process +to external key material: + + $ export SRK_TABLE=$CST_DIR/crts/SRK_1_2_3_4_table.bin + $ export SRK_KEY=$CST_DIR/crts/SRK1_sha384_secp384r1_v3_usr_crt.pem + $ make flash.bin + +1.5 Programming SRK Hash +------------------------- + +As explained in introduction_ahab.txt document, the SRK Hash fuse values +are generated by the srktool and should be programmed in the SoC +SRK_HASH[255:0] fuses. + +Be careful when programming these values, as this data is the basis for +the root of trust. An error in SRK Hash results in a part that does not +boot. + +The U-Boot fuse tool can be used for programming eFuses on i.MX SoCs. + +- Dump SRK Hash fuses values in host machine: + + On i.MX93 family, the SRK Hash uses sha256 and dump 8 words fuses + $ od -t x4 SRK_1_2_3_4_fuse.bin + 0000000 db2959f2 90dfc39c 53394566 e0b75829 + 0000020 85e6f3b1 af00983d e5e804fe 7a451024 + +- Program SRK_HASH[255:0] fuses: + +On i.MX93: + + => fuse prog 16 0 0xdb2959f2 + => fuse prog 16 1 0x90dfc39c + => fuse prog 16 2 0x53394566 + => fuse prog 16 3 0xe0b75829 + => fuse prog 16 4 0x85e6f3b1 + => fuse prog 16 5 0xaf00983d + => fuse prog 16 6 0xe5e804fe + => fuse prog 16 7 0x7a451024 + +1.6 Verify AHAB events +----------------------- + +If the fuses have been burned properly, there should be no AHAB events +after boot. To validate this, power on the board, and run ahab_status +command on U-Boot terminal. + +No events should be returned after this command: + + => ahab_status + Lifecycle: 0x00000008, OEM Open + + No Events Found! + +1.7 Close the device +--------------------- + +After the device successfully boots a signed image without generating any +AHAB security events, it is safe to close the device. The chip lifecycle +should be changed from OEM open to OEM closed. Be aware this step can +damage your board if a previous step failed. It is also irreversible. Run +on the U-Boot terminal: + + => ahab_close + +Warning: Please ensure your sample is in OEM Open state, OEM SRK hash +has been fused, and you are able to boot a signed image successfully +without any SECO events reported. If not, your sample will be +unrecoverable. + +Now reboot the target, and run: + + => ahab_status + Lifecycle: 0x00000020, OEM Closed + + No Events Found! -- 2.55.0
