Difference between revisions of "iMX93 Industrial Secure Boot"

From Voipac Wiki
Jump to navigation Jump to search
Line 9: Line 9:
  
 
'''''Note:''''' Please inspect all the recent changes at [https://github.com/voipac/debian-imx-voipac Voipac GitHub repository] and start the custom build with the newest updates.
 
'''''Note:''''' Please inspect all the recent changes at [https://github.com/voipac/debian-imx-voipac Voipac GitHub repository] and start the custom build with the newest updates.
 +
 +
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.txtc NXP Github page].
  
 
== Preresiquities ==
 
== Preresiquities ==
Line 18: Line 20:
 
* Create a text file called '''''"serial"''''', which contains 8 digits. It will be used for the certificate serial numbers:
 
* 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>
 
<syntaxhighlight lang="bash">echo 12345678 > serial</syntaxhighlight>
−
mkdir ~/voipac-debian
+
* 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:
−
cd ~/voipac-debian
+
<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 file in root of cst directory called cfs_ahag.cfg with 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 image 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>
  
−
Clone the iMX9x Industrial Debian Project into the host machine:
+
Where ''''"uuu-hab.lst"'''' has following content:
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
−
git clone https://github.com/voipac/debian-imx-voipac
+
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>
 
</syntaxhighlight>
  
−
== Prerequisites  ==
+
== Booting the secure image ==
 +
Boot the newly built image and hit any key during startup to halt the booting.
  
−
For Debian image building it is necessary to install docker [https://docs.docker.com/desktop/setup/install/linux/ubuntu/ installation] as whole procedure is done in virtualised environment.
+
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>
  
−
== Building the image ==
+
'''''Important:''''' Do not forget to replace this example with the numbers generated by your keys!
−
Voipac provides quick and simple-to-use option how to build an image by using [https://github.com/voipac/debian-imx-voipac/blob/master/build_debian_voipac.sh build_debian_voipac.sh] prepared script:
+
Use these values to set up eFuses in u-boot console:
 +
<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>
  
−
This script automatically create Debian image for iMX93:
+
Restart the board, press any key to saty in u-boot and run ''''"ahab_status"''''. Output should look like this:
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
−
MACHINE=imx93-voipac ./build_debian_voipac.sh
+
=> ahab_status
 +
  Lifecycle: 0x00000008, OEM Open
 +
 
 +
          No Events Found!
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
During the u-boot build user will be asked for RAM Size. For basic kit configuration select option (1), for lite select 1G (option 2) and for pro and max configurations choose 2G option (option 3) as shown in below image.<br /><br />
+
If there are any events present, please go back and double check if the keys were generated correctly and fuses were flashed properly.
  
−
[[image:Screenshot from 2025-01-29 08-48-33.png|400px]]<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>
  
−
== Locating output files ==
+
Restart the board and run ''''"ahab_status"'''' command again:
−
After the build process was completed, the freshly built output files are located in the root directory:
 
 
<syntaxhighlight lang="bash">
 
<syntaxhighlight lang="bash">
−
ls -la image.sdimg
+
=> ahab_status
 +
  Lifecycle: 0x00000020, OEM Closed
 +
 
 +
          No Events Found!
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
== Prebuild images ==
+
After this step the device is locked and only images signed with private keys will be able to boot on this device.
−
Prebuild images can be downloaded at following [https://downloads.voipac.com/index.php?p=iMX93_Industrial_Development_Kit/module/software/debian/binaries link]
 
  
−
== Flashing the binaries ==
+
<syntaxhighlight lang="bash">
−
At this point everything was prepared to flash the binaries. Follow the [[iMX93 Industrial Flashing Procedure|flashing procedure]] instructions to start the development kit with the compiled images.
 
  
−
== Login ==
+
</syntaxhighlight>
−
When image is flashed and board is booted default credentials can be either '''root/root''' or '''voipac/voipac'''.
+
 
 +
<syntaxhighlight lang="bash">
 +
 
 +
</syntaxhighlight>

Revision as of 15:15, 25 December 2025

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 Voipac GitHub repository and start the custom build with the newest updates.

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

Preresiquities

  • Download the CST tool from NXP website
  • Unpack it into a machine where Yocto will be compiled such as:
/home/user/cst
  • Navigate to the directory:
/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 file in root of cst directory called cfs_ahag.cfg with 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 image 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

Booting the secure image

Boot the newly built image and hit any key during 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: Do not forget to replace this example with the numbers generated by your keys! Use these values to set up eFuses in u-boot console: 

=> 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 saty 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 were flashed properly.

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

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=5981"