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:

• 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 IMX CST TOOL and unarchive it:

tar xf IMX_CST_TOOL_NEW.tgz

imx-mkimage

• Checkout the imx-mkimage:

git clone -b lf-6.6.36-2.1.0 https://github.com/nxp-imx/imx-mkimage.git

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:

BIOS> ahab_status
Lifecycle: 0x00000008, OEM Open
...

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:

$ 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

Generating SRK Table and SRK Hash

• Generate the SRK Table and SRK Hash with srktool:

$ 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

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

$ openssl dgst -binary -sha256 SRK_1_2_3_4_table.bin > SRK_1_2_3_4_fuse.bin

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

$ 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

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:

$ 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

Signing ATF + U-Boot proper Image container

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

$ cd <path to imx-mkimage>
$ make SOC=iMX9 u-boot-atf-container.img

• Note the offset the imx-mkimage tool outputs:

CST: CONTAINER 0 offset: 0x0
CST: CONTAINER 0: Signature Block: offset is at 0x110
        Offsets =       0x0     0x110

• A CSF description file is needed to sign the u-boot-atf-container.img file. You can download it here. In this file, update the offset you previously noted and the eventually the name and path of the keys:

...
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

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

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

• 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:

$ cp signed-u-boot-atf-container.img <path to imx-mkimage>/iMX93/u-boot-atf-container.img

Signing the boot image

• Generate the flash.bin file:

$ cd <path to imx-mkimage>
$ make SOC=iMX9 flash_singleboot

• Note the offset the imx-mkimage tool outputs:

CST: CONTAINER 0 offset: 0x400
CST: CONTAINER 0: Signature Block: offset is at 0x490
        Offsets =       0x400   0x490

• Another CSF description file is needed to sign the flash.bin file. You can download it here. In this file, update the offset you previously noted and the eventually the name of the keys:

...
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

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

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

Flashing U-Boot

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

cp flash-signed.bin /tftproot/opos93-u-boot.bin

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

BIOS> run update_uboot

Burning SRK hash into the fuses

• On your host computer, dump the SRK hash:

$ od -t x4 SRK_1_2_3_4_fuse.bin
0000000 db2959f2 90dfc39c 53394566 e0b75829
0000020 85e6f3b1 af00983d e5e804fe 7a451024

• 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 !

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

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:

BIOS> ahab_status
Lifecycle: 0x00000008, OEM Open

        No Events Found!

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:

BIOS> ahab_close

• Reboot and check with the ahab_status command:

BIOS> ahab_status
Lifecycle: 0x00000020, OEM Closed

        No Events Found!