iMX91 Industrial Secure Boot - Revision history

Voipac at 15:43, 16 January 2026

2026-01-16T15:43:39Z

Voipac-sw at 10:37, 15 January 2026

2026-01-15T10:37:56Z

Voipac at 08:56, 12 January 2026

2026-01-12T08:56:03Z

Voipac at 08:46, 12 January 2026

2026-01-12T08:46:09Z

Voipac: Created page with "Category:iMX91 Industrial Category:iMX91 Industrial Software
TOC
This Wiki page provides a step-by-step guide to building..."

2025-12-26T13:57:29Z

Created page with "Category:iMX91 Industrial Category:iMX91 Industrial Software  <div style="float:right">__TOC__</div> This Wiki page provides a step-by-step guide to building..."

New page

[[Category:iMX91 Industrial]]
[[Category:iMX91 Industrial Software]]

<div style="float:right">__TOC__</div>

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 and iMX91 Industrial Modules.

'''''Note:''''' Please inspect all the recent changes at [https://github.com/voipac/yocto-imx-voipac/blob/imx9-secure-boot/ Voipac GitHub repository] and start the custom build with the newest updates.

'''''Note:''''' Additional information about the process could be found at [https://github.com/nxp-imx/uboot-imx/blob/lf_v2023.04/doc/imx/ahab/guides/mx8ulp_9x_secure_boot.txt NXP Github page].

This build was verified on Ubuntu 18.04 and Ubuntu 20.04.

== Prerequisites ==
* Install docker package on the operating system
* Download the CST tool from [https://www.nxp.com/webapp/sps/download/license.jsp?colCode=IMX_CST_TOOL NXP website]
* Unpack it into a machine where Yocto will be compiled:
<syntaxhighlight lang="bash">/home/user/cst</syntaxhighlight>
* Navigate to the subdirectory:
<syntaxhighlight lang="bash">/home/user/cst/keys</syntaxhighlight>
* Create a text file called '''''"serial"''''', which contains 8 digits. It will be used for the certificate serial numbers:
<syntaxhighlight lang="bash">echo 12345678 > serial</syntaxhighlight>
* 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:
<syntaxhighlight lang="bash">
echo my_secret_password > key_pass.txt
echo my_secret_password >> key_pass.txt
</syntaxhighlight>

== Generating keys ==
To generate the PKI tree, run the following command:
<syntaxhighlight lang="bash">
./ahab_pki_tree.sh
</syntaxhighlight>

Complete the interactive questions. For example:
<syntaxhighlight lang="bash">
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
</syntaxhighlight>

Generate Super Root Key (SRK) table:
<syntaxhighlight lang="bash">
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
</syntaxhighlight>

'''''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:
<syntaxhighlight lang="bash">
#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=
</syntaxhighlight>

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:
<syntaxhighlight lang="bash">
build_image_container.sh pro imx93
</syntaxhighlight>

When image is ready, locate machine files in the build directory and copy them into an output directory:
<syntaxhighlight lang="bash">
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
</syntaxhighlight>

Use following script to flash the image into the development kit:
<syntaxhighlight lang="bash">
#!/bin/sh

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

Where '''''"uuu-hab.lst"''''' has following content:
<syntaxhighlight lang="bash">
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
</syntaxhighlight>

'''''Note:''''' The complete flashing procedure is described in detail in the [[iMX93 Industrial Flashing Procedure|flashing procedure wiki page]].

== Programming fuses and closing the device ==
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: <syntaxhighlight lang="bash">cst/crts</syntaxhighlight>
* Run following command: <syntaxhighlight lang="bash">od -t x4 SRK1234fuse.bin</syntaxhighlight>
* Its output should be looking like this:
<syntaxhighlight lang="bash">
0000000 f43dab72 1b8eda1a 1ddd596d a1cb9682
0000020 0bf178ea 32308483 d596393c ca21a9b
</syntaxhighlight>

'''''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.
<syntaxhighlight lang="bash">
=> 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
</syntaxhighlight>

Restart the board, press any key to stay in u-boot and run '''''"ahab_status"'''''. Output should look like this:
<syntaxhighlight lang="bash">
=> ahab_status
Lifecycle: 0x00000008, OEM Open

No Events Found!
</syntaxhighlight>

If there are any events present, please go back and double check if the keys were generated correctly and fuses flashed properly.
<br /><br />
Please also verify if the board can boot to the userspace.

Restart the board, stop the execution in uboot, and close the device:
<syntaxhighlight lang="bash">
ahab_close
</syntaxhighlight>

Restart the board and run '''''"ahab_status"''''' command again:
<syntaxhighlight lang="bash">
=> ahab_status
Lifecycle: 0x00000020, OEM Closed

No Events Found!
</syntaxhighlight>

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

@@ Line 1: / Line 1: @@
-[[Category:imx91 Industrial]]
+[[Category:iMX91 Industrial]]
-[[Category:imx91 Industrial Software]]
+[[Category:iMX91 Industrial Software]]
 <!-- -->
 <div style="float:right">__TOC__</div>
-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 imx91 Industrial Module.
+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 iMX91 Industrial Module.
 '''''Note:''''' Please inspect all the recent changes at [https://github.com/voipac/yocto-imx-voipac/blob/imx9-secure-boot/ Voipac GitHub repository] and start the custom build with the newest updates.
@@ Line 51: / Line 51: @@
 </syntaxhighlight>
-'''''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.
+'''''Note:''''' For the i.MX 91 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:
@@ Line 71: / Line 71: @@
 == Building an image ==
-Build an image for imx91 Industrial Development Kit in the docker container:
+Build an image for iMX91 Industrial Development Kit in the docker container:
 <syntaxhighlight lang="bash">
 build_image_container.sh pro imx91
@@ Line 107: / Line 107: @@
 </syntaxhighlight>
-'''''Note:''''' The complete flashing procedure is described in detail in the [[imx91 Industrial Flashing Procedure|flashing procedure wiki page]].
+'''''Note:''''' The complete flashing procedure is described in detail in the [[iMX91 Industrial Flashing Procedure|flashing procedure wiki page]].
 == Programming fuses ==

← Older revision		Revision as of 08:56, 12 January 2026
Line 162:		Line 162:
	</syntaxhighlight>		</syntaxhighlight>

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

@@ Line 1: / Line 1: @@
-[[Category:iMX91 Industrial]]
+[[Category:imx91 Industrial]]
-[[Category:iMX91 Industrial Software]]
+[[Category:imx91 Industrial Software]]
 <!-- -->
 <div style="float:right">__TOC__</div>
-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 iMX91 Industrial Module.
+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 imx91 Industrial Module.
 '''''Note:''''' Please inspect all the recent changes at [https://github.com/voipac/yocto-imx-voipac/blob/imx9-secure-boot/ Voipac GitHub repository] and start the custom build with the newest updates.
@@ Line 71: / Line 71: @@
 == Building an image ==
-Build an image for iMX93 Industrial Development Kit in the docker container:
+Build an image for imx91 Industrial Development Kit in the docker container:
 <syntaxhighlight lang="bash">
-build_image_container.sh pro imx93
+build_image_container.sh pro imx91
 </syntaxhighlight>
 When image is ready, locate machine files in the build directory and copy them into an output directory:
 <syntaxhighlight lang="bash">
-cp -p signed-imx-boot-imx93-voipac-sd.bin-flash_singleboot /home/user/output
+cp -p signed-imx-boot-imx91-voipac-sd.bin-flash_singleboot /home/user/output
-cp -p voipac-image-imx93-voipac.rootfs.wic.zst /home/user/output
+cp -p voipac-image-imx91-voipac.rootfs.wic.zst /home/user/output
 </syntaxhighlight>
@@ Line 86: / Line 86: @@
 #!/bin/sh
-sudo ./uuu -b emmc_all voipac-image-imx93-voipac.rootfs.wic.zst
+sudo ./uuu -b emmc_all voipac-image-imx91-voipac.rootfs.wic.zst
 # flash secure imx-boot
 sudo ./uuu uuu-hab.lst
@@ Line 95: / Line 95: @@
 uuu_version 1.2.39
-SDPS: boot -f signed-imx-boot-imx93-voipac-sd.bin-flash_singleboot
+SDPS: boot -f signed-imx-boot-imx91-voipac-sd.bin-flash_singleboot
@@ Line 101: / Line 101: @@
 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: flash bootloader signed-imx-boot-imx91-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
@@ Line 107: / Line 107: @@
 </syntaxhighlight>
-'''''Note:''''' The complete flashing procedure is described in detail in the [[iMX93 Industrial Flashing Procedure|flashing procedure wiki page]].
+'''''Note:''''' The complete flashing procedure is described in detail in the [[imx91 Industrial Flashing Procedure|flashing procedure wiki page]].
-== Programming fuses and closing the device ==
+== Programming fuses ==
 Boot the newly built image and hit any key after startup to halt the booting.
@@ Line 148: / Line 148: @@
 <br /><br />
 Please also verify if the board can boot to the userspace.
 Restart the board, stop the execution in uboot, and close the device: