View source for Secure boot on OPOS93

= Introduction =

This document is a quick how-to boot a signed boot firmware on the OPOS93 SoM. It summarizes the documents provided by NXP: 

* [https://www.nxp.com/doc/an12312 AN12312]
* https://github.com/nxp-imx/uboot-imx/blob/lf-6.1.22-2.0.0/doc/imx/ahab/introduction_ahab.txt
* https://github.com/nxp-imx/uboot-imx/blob/lf-6.6.36-2.1.0/doc/imx/ahab/guides/mx8ulp_9x_secure_boot.txt

= Requirements =

== IMX CST TOOL ==

* Download the [https://www.nxp.com/webapp/Download?colCode=IMX_CST_TOOL_NEW IMX CST TOOL] and unarchive it:

<pre class="host">
tar xf IMX_CST_TOOL_NEW.tgz
</pre>

== imx-mkimage ==

* Checkout the imx-mkimage:

<pre class="host">
git clone -b lf-6.6.36-2.1.0 https://github.com/nxp-imx/imx-mkimage.git
</pre>

== Latest Armadeus U-Boot ==

* Make sure you have the latest Armadeus U-Boot installed on you OPOS93 SoM. It must have the '''ahab_status''' commands:

<pre class="code">
BIOS> ahab_status
Lifecycle: 0x00000008, OEM Open
...
</pre>

If the command is not available on your OPOS93 SoM, update to the latest Armadeus U-Boot.

= Generating a PKI tree =

* To generate your PKI tree, go to the CST TOOL directory and use the script '''ahab_pki_tree.sh''':

<pre class="host">
$ cd cst-3.4.1/
$ ./keys/ahab_pki_tree.sh
...
Do you want to use an existing CA key (y/n)?: n
Do you want to use Elliptic Curve Cryptography (y/n)?: y
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): 5
Do you want the SRK certificates to have the CA flag set? (y/n)?: y
</pre>

= Generating SRK Table and SRK Hash =

* Generate the SRK Table and SRK Hash with '''srktool''':

<pre class="host">
$ cd crts/
$ ../linux64/bin/srktool -a -d sha256 -s sha384 -t SRK_1_2_3_4_table.bin \
  -e SRK_1_2_3_4_fuse.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
</pre>

* Regenerate the SRK HASH (SRK_1_2_3_4_fuse.bin) by using SHA256 with SRK_1_2_3_4_table.bin:

<pre class="host">
$ openssl dgst -binary -sha256 SRK_1_2_3_4_table.bin > SRK_1_2_3_4_fuse.bin
</pre>

* Check if the hash in the SRK_1_2_3_4_fuse.bin is correct:

<pre class="host">
$ hexdump -C SRK_1_2_3_4_fuse.bin
0000000 db2959f2 90dfc39c 53394566 e0b75829
0000020 85e6f3b1 af00983d e5e804fe 7a451024

$ sha256sum SRK_1_2_3_4_table.bin
db2959f290dfc39c53394566e0b7582985e6f3b1af00983de5e804fe7a451024  SRK_1_2_3_4_table.bin
</pre>

= Signing the boot image =

* From the images directory of the Armadeus BSP, copy the files needed to generate a boot image (SPL, U-Boot proper, ATF) into the i.MX93 directory of the imx-mkimage tool:

<pre class="host">
$ cp <path to BSP Armadeus>/images/u-boot.bin <path to imx-mkimage>/iMX93/
$ cp <path to BSP Armadeus>/images/u-boot-spl.bin <path to imx-mkimage>/iMX93/
$ cp <path to BSP Armadeus>/images/bl31.bin <path to imx-mkimage>/iMX93/
$ cp <path to BSP Armadeus>/images/lpddr4* <path to imx-mkimage>/iMX93/
$ cp <path to BSP Armadeus>/images/ahab-container.img <path to imx-mkimage>/iMX93/mx93a1-ahab-container.img
</pre>

== Signing ATF + U-Boot proper Image container ==

* Generate the u-boot-atf-container.img file:

<pre class="host">
$ cd <path to imx-mkimage>
$ make SOC=iMX9 u-boot-atf-container.img
</pre>

* Note the offset the imx-mkimage tool outputs:

<pre class="host">
CST: CONTAINER 0 offset: 0x0
CST: CONTAINER 0: Signature Block: offset is at 0x110
        Offsets =       0x0     0x110
</pre>

* A CSF description file is needed to sign the u-boot-atf-container.img file. You can download one [https://github.com/nxp-imx/uboot-imx/raw/refs/tags/lf-6.6.36-2.1.0/doc/imx/ahab/csf_examples/csf_uboot_atf.txt here]. In this file, update the offset you previously noted and the eventually the name and path of the keys:

<pre class="host">
...
Source = "../crts/SRK1_sha384_secp384r1_v3_ca_crt.pem"
...
[Authenticate Data]
# Binary to be signed generated by mkimage
File = "u-boot-atf-container.img"
# Offsets = Container header  Signature block
Offsets   = 0x0               0x110
</pre>

* Sign the u-boot-atf-container.img with the CST TOOL:

<pre class="host">
$ cd <path to CST TOOL>
$ ./linux64/bin/cst -i ~/Downloads/csf_uboot_atf.txt -o signed-u-boot-atf-container.img
</pre>

* Replace the u-boot-atf-container.img file with the signed-u-boot-atf-container.img file in the iMX93 directory of the imx-mkimage tool:

<pre class="host">
$ cp signed-u-boot-atf-container.img <path to imx-mkimage>/iMX93/u-boot-atf-container.img
</pre>

== Signing the boot image ==

* Generate the flash.bin file:

<pre class="host">
$ cd <path to imx-mkimage>
$ make SOC=iMX9 flash_singleboot
</pre>

* Note the offset the imx-mkimage tool outputs:

<pre class="host">
CST: CONTAINER 0 offset: 0x400
CST: CONTAINER 0: Signature Block: offset is at 0x490
        Offsets =       0x400   0x490
</pre>

* Another CSF description file is needed to sign the flash.bin file. You can download it [https://github.com/nxp-imx/uboot-imx/raw/refs/tags/lf-6.6.36-2.1.0/doc/imx/ahab/csf_examples/csf_boot_image.txt here]. In this file, update the offset you previously noted and the eventually the name of the keys:

<pre class="host">
...
Source = "../crts/SRK1_sha384_secp384r1_v3_ca_crt.pem"
...
[Authenticate Data]
# Binary to be signed generated by mkimage
File = "/home/sszy/development/imx-mkimage/iMX93/flash.bin"
# Offsets = Container header  Signature block (printed out by mkimage)
Offsets   = 0x400             0x490
</pre>

* Sign the flash.bin file with the CST TOOL:

<pre class="host">
$ cd <path to CST TOOL>
$ ./linux64/bin/cst -i ~/Downloads/csf_boot_image.txt -o signed-flash.bin
</pre>

= Flashing U-Boot =

* On your computer, copy the signed boot image into the root directory of your tftp server:

<pre class="host">
cp flash-signed.bin /tftproot/opos93-u-boot.bin
</pre>

* On your OPOS93, update U-Boot as usual:

<pre class="code">
BIOS> run update_uboot
</pre>

= Burning SRK hash into the fuses =

* On your host computer, dump the SRK hash:

<pre class="host">
$ od -t x4 SRK_1_2_3_4_fuse.bin
0000000 db2959f2 90dfc39c 53394566 e0b75829
0000020 85e6f3b1 af00983d e5e804fe 7a451024
</pre>

* On the OPOS93, on U-Boot, burn the SRK hash into the fuses.
'''Obviously, don't burn these values but the ones the previous command outputs with your keys !'''

<pre class="host">
BIOS> fuse prog 16 0 0xdb2959f2
BIOS> fuse prog 16 1 0x90dfc39c
BIOS> fuse prog 16 2 0x53394566
BIOS> fuse prog 16 3 0xe0b75829
BIOS> fuse prog 16 4 0x85e6f3b1
BIOS> fuse prog 16 5 0xaf00983d
BIOS> fuse prog 16 6 0xe5e804fe
BIOS> fuse prog 16 7 0x7a451024
</pre>

= Checking = 

* Power off / on the board, and stop the boot into U-Boot. Run the ahab_status command. If everything is ok, there should be no AHAB events:

<pre class="code">
BIOS> ahab_status
Lifecycle: 0x00000008, OEM Open

        No Events Found!
</pre>

= Closing the OPOS93 =

{{Warning|Before closing your OPOS93, make sure everything is ok (double or triple check...), there is no AHAB events and you are able to boot a signed image. A missigned boot image on a closed OPOS93 will make your OPOS93 unrecoverable !}}

* To close your OPOS93, run the '''ahab_close''' command:

<pre class="host">
BIOS> ahab_close
</pre>

* Reboot and check with the '''ahab_status''' command:

<pre class="host">
BIOS> ahab_status
Lifecycle: 0x00000020, OEM Closed

        No Events Found!
</pre>