iMX93 Industrial Secure Boot

From Voipac Wiki
Revision as of 11:36, 15 January 2026 by Voipac-sw (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

This Wiki page provides a step-by-step guide to building and flashing a Yocto Project image with secure boot integration. These instructions apply to the iMX93 Industrial Module.

Note: Please inspect all the recent changes at Voipac GitHub repository and start the custom build with the newest updates.

Note: Additional information about the process could be found at NXP Github page.

This build was verified on Ubuntu 20.04.

Prerequisites

  • Install docker package on the operating system
  • Download the CST tool from NXP website
  • Unpack it into a machine where Yocto will be compiled:
/home/user/cst
  • Navigate to the subdirectory:
/home/user/cst/keys
  • Create a text file called "serial", which contains 8 digits. It will be used for the certificate serial numbers:
echo 12345678 > serial
  • Create a text file called "key_pass.txt", which contains two lines of a password repeated twice. This password will be used to protect the generated private keys:
echo my_secret_password >  key_pass.txt
echo my_secret_password >> key_pass.txt

Generating keys

To generate the PKI tree, run the following command: 

./ahab_pki_tree.sh

Complete the interactive questions. For example: 

Do you want to use an existing CA key (y/n)?: n
Key type options (confirm targeted device supports desired key type):
Select the key type (possible values: rsa, rsa-pss, ecc)?: ecc
Enter length for elliptic curve to be used for PKI tree:
Possible values p256, p384, p521: p384
Enter the digest algorithm to use: sha384
Enter PKI tree duration (years): 20
Do you want the SRK certificates to have the CA flag set? (y/n)?: n

Generate Super Root Key (SRK) table: 

cd ../crts
../linux64/bin/srktool -a -d sha256 -s sha384 -t SRK1234table.bin -e SRK1234fuse.bin -f 1 -c SRK1_sha384_secp384r1_v3_usr_crt.pem,SRK2_sha384_secp384r1_v3_usr_crt.pem,SRK3_sha384_secp384r1_v3_usr_crt.pem,SRK4_sha384_secp384r1_v3_usr_crt.pem

Note: For the i.MX 93 SoC, the Message Digest algorithm (option —d) is sha256, while the Signature Digest algorithm (option -s) must match the option from the PKI generation.

Create a file in root of cst directory called "cfs_ahag.cfg" with the following content: 

#Header
header_version=1.0
#Install SRK
srktable_file=SRK1234table.bin
srk_source=SRK1_sha384_secp384r1_v3_usr_crt.pem
srk_source_index=0
srk_source_set=OEM
srk_revocations=0x0
#Install Certificate
sgk_file=
sgk_permissions=

This file will be used by Yocto to point to the proper SRK table and keys.

Building an image

Build an image for iMX93 Industrial Development Kit in the docker container: 

build_image_container.sh pro imx93

When image is ready, locate machine files in the build directory and copy them into an output directory: 

cp -p signed-imx-boot-imx93-voipac-sd.bin-flash_singleboot /home/user/output
cp -p voipac-image-imx93-voipac.rootfs.wic.zst /home/user/output

Use following script to flash the image into the development kit: 

#!/bin/sh

sudo ./uuu -b emmc_all voipac-image-imx93-voipac.rootfs.wic.zst
# flash secure imx-boot
sudo ./uuu uuu-hab.lst

Where "uuu-hab.lst" has following content: 

uuu_version 1.2.39

SDPS: boot -f signed-imx-boot-imx93-voipac-sd.bin-flash_singleboot


FB: ucmd setenv fastboot_dev mmc
FB: ucmd setenv mmcdev ${emmc_dev}
FB: ucmd mmc dev ${emmc_dev}
FB: flash bootloader signed-imx-boot-imx93-voipac-sd.bin-flash_singleboot
FB: ucmd if env exists emmc_ack; then ; else setenv emmc_ack 0; fi;
FB: ucmd mmc partconf ${emmc_dev} ${emmc_ack} 1 0
FB: Done

Note: The complete flashing procedure is described in detail in the flashing procedure wiki page.

Programming fuses

Boot the newly built image and hit any key after startup to halt the booting.

Program the SRK (public keys) to the SOC e-fuses:

  • Navigate to the directory: 
    cst/crts
  • Run following command: 
    od -t x4 SRK1234fuse.bin
  • Its output should be looking like this:
0000000 f43dab72 1b8eda1a 1ddd596d a1cb9682
0000020 0bf178ea 32308483 d596393c ca21a9b

Important: This process in non-reversable. Incorrect fuse programming can lead to bricking the device!

Use these values to set up eFuses in u-boot console:

Important: Do not forget to replace this example with the numbers generated by your keys. 

=> fuse prog 16 0 0xf43dab72
=> fuse prog 16 1 0x1b8eda1a
=> fuse prog 16 2 0x1ddd596d
=> fuse prog 16 3 0xa1cb9682
=> fuse prog 16 4 0x0bf178ea
=> fuse prog 16 5 0x32308483
=> fuse prog 16 6 0xd596393c
=> fuse prog 16 7 0xca21a9b

Restart the board, press any key to stay in u-boot and run "ahab_status". Output should look like this: 

=> ahab_status
  Lifecycle: 0x00000008, OEM Open

          No Events Found!

If there are any events present, please go back and double check if the keys were generated correctly and fuses flashed properly.

Please also verify if the board can boot to the userspace.

Perform verification tests while the device is in Open state

Wrong Key Test

Re-sign container using a different SRK set and flash it over the original.
Boot the device and run ahab_status. Expected AHAB event:
0x0087FA00 — Container authentication failed due to SRK hash mismatch (wrong key or SRK fuses not yet programmed).

Tamper Test

Modify one byte inside the signed container binary (e.g., os_cntr_signed.bin) and reflash it. Boot the device and run ahab_status.

Container authentication failed because signature verification failed (tampered content). 

=> ahab_status
u-boot=> ahab_status
Lifecycle: 0x00000008, OEM Open
                                                                                                        
        0x0287f0d6                                                                                      
        IPC = MU APD (0x2)                                                                              
        CMD = ELE_OEM_CNTN_AUTH_REQ (0x87)                                                              
        IND = ELE_BAD_SIGNATURE_FAILURE_IND (0xF0)                                                      
        STA = ELE_SUCCESS_IND (0xD6)

When try to boot image then we get following: 

Running BSP bootcmd ...
switch to partitions #0, OK
mmc0(part 0) is current device
Failed to load 'boot.scr'
35750715 bytes read in 167 ms (204.2 MiB/s)
Booting from mmc ...
Authenticate OS container at 0x98000000
mu receive msg wait 1s
mu receive msg wait 2s
mu receive msg wait 3s
ERROR: Did not find a cmdline Flattened Device Tree
Could not find a valid device tree

and board fails to boot.

OEM board close

Restart the board, stop the execution in uboot, and close the device: 

ahab_close

Restart the board and run "ahab_status" command again: 

=> ahab_status
  Lifecycle: 0x00000020, OEM Closed

          No Events Found!

After this step the device is locked and only images signed with private keys will be able to boot on this device.

Retrieved from "https://wiki.voipac.com/index.php?title=iMX93_Industrial_Secure_Boot&oldid=6041"