| +=========================================================+ |
| + i.MX 8, i.MX 8X Secure Boot guide using AHAB + |
| +=========================================================+ |
| |
| 1. AHAB secure boot process |
| ---------------------------- |
| |
| This document describes a step-by-step procedure on how to sign and |
| securely boot a flash.bin image. It is assumed that the reader is |
| familiar with basic AHAB concepts and with the PKI tree generation. |
| |
| It is also assumed that the reader is familiar with all pieces of |
| software needed. The procedure to built SCFW, ATF and download the |
| firmwares are out of scope of this document, please refer to the Linux |
| BSP Release Notes and AN12212[1] for further details. |
| |
| Details about AHAB can be found in the introduction_ahab.txt document |
| and in processors Security Reference Manual Document (SRM). |
| |
| 1.1 Preparing the environment to build a secure boot image |
| ----------------------------------------------------------- |
| |
| Before continuing, be sure to have already downloaded and built the |
| following: |
| |
| - imx-mkimage downloaded and built with i.MX 8 container support. |
| - SECO firmware downloaded. |
| - U-Boot downloaded and built. Please check section 1.2. |
| - ARM Trusted Firmware (ATF) downloaded and built for your target. |
| - System Controller Firmware (SCFW). |
| - Kernel image. |
| |
| You should also have downloaded the Code Signing Tool, available on NXP |
| website. |
| |
| In the following sections, <work> designates the repository where all |
| parts have been downloaded and built. |
| |
| 1.2 Preparing U-Boot to support AHAB secure boot features |
| ---------------------------------------------------------- |
| |
| The U-Boot provides extra functions for AHAB, such as the ability to |
| authenticate additional container images by calling the SCU API |
| sc_misc_seco_authenticate() function. |
| |
| The support is enabled by adding CONFIG_AHAB_BOOT to the defconfig file used |
| for your target: |
| |
| - Defconfig: |
| CONFIG_AHAB_BOOT=y |
| - Kconfig: |
| ARM architecture -> Support i.MX 8 AHAB features |
| |
| 1.3 Building an image supporting secure boot |
| --------------------------------------------- |
| |
| The boot image is composed of different layers: |
| |
| +---------------------------+ <-- *start |
| | 1st Container header | |
| | and signature | |
| +---------------------------+ |
| | Padding for 1kB alignment | |
| +---------------------------+ <-- *start + 0x400 |
| | 2nd Container header | |
| | and signature | |
| +---------------------------+ |
| | Padding | |
| +---------------------------+ |
| | SECO FW | |
| +---------------------------+ |
| | Padding | |
| +---------------------------+ |
| | SCU FW with DDR | |
| | initialization Image | |
| | embedded | |
| +---------------------------+ |
| | Cortex-M4 Image | |
| +---------------------------+ |
| | Cortex-A bootloader | |
| +---------------------------+ |
| |
| It contains two containers, one for the SECO firmware (AHAB), and one for |
| the SCFW, the ATF, U-Boot and M4 Image. They are preceded by their headers. |
| The first one, containing the SECO firmware image, is padded to 0x1000 to |
| fix the start address of the second one, which can contain one or multiple |
| images. |
| |
| If you are familiar with secure boot process with HABv4, you will notice |
| there is no need for CSF in this architecture. The CST is responsible to |
| handle the Signature block: |
| |
| +----------------------------+ ^ |
| | | | |
| | | | |
| | Container header | | |
| | | | |
| | | | |
| +---+------------------------+ | |
| | S | Signature block header | | Signed |
| | i +------------------------+ | |
| | g | | | |
| | n | | | |
| | a | SRK table | | |
| | t | | | |
| | u | | | |
| | r +------------------------+ v |
| | e | Signature | |
| | +------------------------+ |
| | b | | |
| | l | SGK Key | |
| | o | Certificate (optional) | |
| | c | | |
| | k | | |
| +---+------------------------+ |
| |
| The certificate block is divided into: |
| |
| +---------------+ ^ |
| | Public key | | Signed |
| | Permission | | |
| +---------------+ v |
| | Signature | |
| +---------------+ |
| |
| The first block (public key permission) verify the Signature block |
| preceding (between SRK table and Certificate blocks), while the second |
| block (signature) is verified by the SRK table block. |
| |
| 1.4 Prepare the boot image layout |
| ---------------------------------- |
| |
| To generate the flash.bin file: |
| |
| - On i.MX 8 QXP: |
| |
| $ cd <work>/imx-mkimage |
| $ make SOC=iMX8QX flash |
| |
| - On i.MX 8 QM: |
| |
| $ cd <work>/imx-mkimage |
| $ make SOC=iMX8QM flash |
| |
| If the command ends successfully, the end of the result should look |
| like: |
| |
| CST: CONTAINER 0 offset: 0x400 |
| CST: CONTAINER 0: Signature Block: offset is at 0x590 |
| DONE. |
| Note: Please copy image to offset: IVT_OFFSET + IMAGE_OFFSET |
| |
| Keep in mind the offsets above to be used with CST/CSF. |
| |
| Please note that on this example we not including an Cortex-M4 Image, on |
| i.MX8/8x MEK boards the SCU console may be replaced by the M4 console not |
| being possible to run the steps documented in section "1.5.5 Verify SECO |
| events". |
| |
| 1.5 Secure boot setup with the CST |
| ----------------------------------- |
| |
| 1.5.1 Creating the CSF description file for the second container |
| ----------------------------------------------------------------- |
| |
| The CSF contains all the commands that the AHAB executes during the secure |
| boot. These commands instruct the AHAB on which memory areas of the image |
| to authenticate, which keys to install, use and etc. |
| |
| CSF examples are available under doc/imx/hab/ahab/csf_examples/ |
| directory. |
| |
| This csf_boot_image.txt file example should be updated with the offset values |
| of the 1.4 section and the path to your flash.bin file. It is the last part |
| of the file: |
| |
| [Authenticate Data] |
| # Binary to be signed generated by mkimage |
| File = "flash.bin" |
| # Offsets = Container header Signature block (printed out by mkimage) |
| Offsets = 0x400 0x590 |
| |
| 1.5.2 Signing the boot image |
| ----------------------------- |
| |
| Now you use the CST to generate the signed boot image from the previously |
| created csf_boot_image.txt Commands Sequence File: |
| |
| $ cd <work> |
| $ ./release/linux64/bin/cst -i csf_boot_image.txt -o flash.signed.bin |
| |
| 1.5.3 Flash the signed image |
| ----------------------------- |
| |
| Write the signed U-Boot image: |
| |
| $ sudo dd if=flash.signed.bin of=/dev/sdX bs=1k seek=32 ; sync |
| |
| Then insert the SD Card into the board and plug your device to your computer |
| with an USB serial cable. |
| |
| 1.5.4 Programming SRK Hash |
| --------------------------- |
| |
| As explained in introduction_ahab.txt document the SRK Hash fuse values are |
| generated by the srktool and should be programmed in the SoC SRK_HASH[511:0] |
| fuses. |
| |
| Be careful when programming these values, as this data is the basis for the |
| root of trust. An error in SRK Hash results in a part that does not boot. |
| |
| The U-Boot fuse tool can be used for programming eFuses on i.MX SoCs. |
| |
| - Dump SRK Hash fuses values in host machine: |
| |
| $ od -t x4 SRK_1_2_3_4_fuse.bin |
| 0000000 d436cc46 8ecccda9 b89e1601 5fada3db |
| 0000020 d454114a b6cd51f4 77384870 c50ee4b2 |
| 0000040 a27e5132 eba887cf 592c1e2b bb501799 |
| 0000060 ee702e07 cf8ce73e fb55e2d5 eba6bbd2 |
| |
| - Program SRK_HASH[511:0] fuses: |
| |
| * On i.MX 8 QXP: |
| |
| => fuse prog 0 730 0xd436cc46 |
| => fuse prog 0 731 0x8ecccda9 |
| => fuse prog 0 732 0xb89e1601 |
| => fuse prog 0 733 0x5fada3db |
| => fuse prog 0 734 0xd454114a |
| => fuse prog 0 735 0xb6cd51f4 |
| => fuse prog 0 736 0x77384870 |
| => fuse prog 0 737 0xc50ee4b2 |
| => fuse prog 0 738 0xa27e5132 |
| => fuse prog 0 739 0xeba887cf |
| => fuse prog 0 740 0x592c1e2b |
| => fuse prog 0 741 0xbb501799 |
| => fuse prog 0 742 0xee702e07 |
| => fuse prog 0 743 0xcf8ce73e |
| => fuse prog 0 744 0xfb55e2d5 |
| => fuse prog 0 745 0xeba6bbd2 |
| |
| * On i.MX 8 QM: |
| |
| => fuse prog 0 722 0xd436cc46 |
| => fuse prog 0 723 0x8ecccda9 |
| => fuse prog 0 724 0xb89e1601 |
| => fuse prog 0 725 0x5fada3db |
| => fuse prog 0 726 0xd454114a |
| => fuse prog 0 727 0xb6cd51f4 |
| => fuse prog 0 728 0x77384870 |
| => fuse prog 0 729 0xc50ee4b2 |
| => fuse prog 0 730 0xa27e5132 |
| => fuse prog 0 731 0xeba887cf |
| => fuse prog 0 732 0x592c1e2b |
| => fuse prog 0 733 0xbb501799 |
| => fuse prog 0 734 0xee702e07 |
| => fuse prog 0 735 0xcf8ce73e |
| => fuse prog 0 736 0xfb55e2d5 |
| => fuse prog 0 737 0xeba6bbd2 |
| |
| 1.5.5 Verify SECO events |
| ------------------------- |
| |
| If the fuses have been written properly, there should be no SECO events after |
| boot. To validate this, power on the board, and run ahab_status command on |
| U-Boot terminal. |
| |
| No events should be returned after this command: |
| |
| => ahab_status |
| Lifecycle: 0x0020, NXP closed |
| |
| No SECO Events Found! |
| |
| U-Boot will decode the SECO events and provide more details on the failure, |
| for example in case container image was signed with wrong keys and are not |
| matching the OTP SRK hashes: |
| |
| => ahab_status |
| Lifecycle: 0x0020, NXP closed |
| |
| SECO Event[0] = 0x0087EE00 |
| CMD = AHAB_AUTH_CONTAINER_REQ (0x87) |
| IND = AHAB_NO_AUTHENTICATION_IND (0xEE) |
| |
| Note: In case your SRK fuses are not programmed yet the event 0x0087FA00 may |
| also be displayed. |
| |
| 1.5.6 Close the device |
| ----------------------- |
| |
| After the device successfully boots a signed image without generating any |
| SECO security events, it is safe to close the device. The SECO lifecycle |
| should be changed from 0x20 NXP closed to 0x80 OEM closed. Be aware this |
| step can damage your board if a previous step failed. It is also |
| irreversible. Run on the U-Boot terminal: |
| |
| => ahab_close |
| |
| Now reboot the target, and run: |
| |
| => ahab_status |
| |
| The lifecycle value should now be 0x80 OEM closed. |
| |
| 2. Authenticating the OS container |
| ----------------------------------- |
| |
| Note that the following section is not mandatory. If you do not plan to |
| authenticate the kernel image, you can disable this behavior by setting |
| sec_boot=no in U-Boot environment variable. |
| |
| Note, you can also authenticate the OS image by running a U-Boot command: |
| |
| => auth_cntr <Container address> |
| |
| 2.1 Prepare the OS container image |
| ----------------------------------- |
| |
| You need to generate the OS container image. First, copy the binary previously |
| generated to the <work> directory to save it for later: |
| |
| - On i.MX 8 QXP |
| |
| $ cd <work>/imx-mkimage |
| $ cp iMX8QX/flash.bin .. |
| $ make SOC=iMX8QX flash_linux |
| $ mv i.MX8QX/flash.bin iMX8QX/flash_os.bin |
| $ cp iMX8QX/flash_os.bin .. |
| |
| - On i.MX 8 QM |
| |
| $ cd <work>/imx-mkimage |
| $ cp iMX8QM/flash.bin .. |
| $ make SOC=iMX8QM flash_linux |
| $ mv i.MX8QM/flash.bin iMX8QM/flash_os.bin |
| $ cp iMX8QM/flash_os.bin .. |
| |
| If the make command ends successfully, the end of the result should look |
| like: |
| |
| CST: CONTAINER 0 offset: 0x0 |
| CST: CONTAINER 0: Signature Block: offset is at 0x110 |
| DONE. |
| Note: Please copy image to offset: IVT_OFFSET + IMAGE_OFFSET |
| |
| Keep in mind the offsets above to be used with CST/CSF |
| |
| 2.2 Creating the CSF description file for OS container image |
| ------------------------------------------------------------- |
| |
| CSF examples are available under doc/imx/hab/ahab/csf_examples/ |
| directory. |
| |
| This csf_linux_img.txt file example should be updated with the offset values |
| of the 2.1 chapter and the path to your flash_os.bin file. It it the last |
| part of the file: |
| |
| [Authenticate Data] |
| # Binary to be signed generated by mkimage |
| File = "flash_os.bin" |
| # Offsets = Container header Signature block (printed out by mkimage) |
| Offsets = 0x0 0x110 |
| |
| 2.3 Authenticating container image |
| ----------------------------------- |
| |
| Now you use the CST to signed the OS image using the previously |
| created csf_linux_img.txt Commands Sequence File: |
| |
| $ cd <work> |
| $ ./release/linux64/bin/cst -i csf_linux_img.txt -o os_cntr_signed.bin |
| |
| 2.4 Copy OS container |
| ---------------------- |
| |
| Mount the SD Card: |
| |
| $ sudo mount /dev/sdX1 partition |
| |
| Copy the OS signed image on the SD Card: |
| |
| - For i.MX 8 QXP |
| |
| $ sudo cp os_cntr_signed.bin /media/UserID/Boot\ imx8qx |
| |
| - For i.MX 8 QM |
| |
| $ sudo cp os_cntr_signed.bin /media/UserID/Boot\ imx8qm |
| |
| Finally: |
| |
| $ sudo umount partition |
| |
| References: |
| [1] AN12212: "Software Solutions for Migration Guide from Aarch32 to |
| Aarch64" - Rev 0." |
