MLK-20553-2 doc: imx: ahab: Add AHAB secure boot documentation for i.MX 8 and 8X families
Add AHAB secure boot step-by-step guide for i.MX8 and i.MX8x families
devices.
Add 3 CSF example files:
- Example to sign flash.bin only using SRK keys.
- Example to sign flash.bin using a subordinate SGK key.
- Example to sign Linux image only using SRK keys.
Signed-off-by: Clement Le Marquis <clement.lemarquis@nxp.com>
Reviewed-by: Frank Zhang <frank.zhang@nxp.com>
Reviewed-by: Marius Grigoras <marius.grigoras@nxp.com>
Reviewed-by: Utkarsh Gupta <utkarsh.gupta@nxp.com>
(cherry picked from commit 7c46caba3b528b0399242f99612e5b094b1a4703)
diff --git a/doc/imx/ahab/csf_examples/csf_boot_image.txt b/doc/imx/ahab/csf_examples/csf_boot_image.txt
new file mode 100644
index 0000000..1f296f0
--- /dev/null
+++ b/doc/imx/ahab/csf_examples/csf_boot_image.txt
@@ -0,0 +1,21 @@
+[Header]
+Target = AHAB
+Version = 1.0
+
+[Install SRK]
+# SRK table generated by srktool
+File = "./release/crts/SRK_1_2_3_4_table.bin"
+# Public key certificate in PEM format
+Source = "./release/crts/SRK1_sha384_secp384r1_v3_usr_crt.pem"
+# Index of the public key certificate within the SRK table (0 .. 3)
+Source index = 0
+# Type of SRK set (NXP or OEM)
+Source set = OEM
+# bitmask of the revoked SRKs
+Revocations = 0x0
+
+[Authenticate Data]
+# Binary to be signed generated by mkimage
+File = "flash.bin"
+# Offsets = Container header Signature block (printed out by mkimage)
+Offsets = 0x400 0x590
diff --git a/doc/imx/ahab/csf_examples/csf_boot_image_sgk.txt b/doc/imx/ahab/csf_examples/csf_boot_image_sgk.txt
new file mode 100644
index 0000000..ec42f4f
--- /dev/null
+++ b/doc/imx/ahab/csf_examples/csf_boot_image_sgk.txt
@@ -0,0 +1,28 @@
+[Header]
+Target = AHAB
+Version = 1.0
+
+[Install SRK]
+# SRK table generated by srktool
+File = "./release/crts/SRK_1_2_3_4_table.bin"
+# Public key certificate in PEM format
+Source = "./release/crts/SRK1_sha384_secp384r1_v3_ca_crt.pem"
+# Index of the public key certificate within the SRK table (0 .. 3)
+Source index = 0
+# Type of SRK set (NXP or OEM)
+Source set = OEM
+# bitmask of the revoked SRKs
+Revocations = 0x0
+
+# Optional subordinate SGK key
+[Install Certificate]
+# Public key certificate in PEM format
+File = "./release/crts/SGK1_sha384_secp384r1_v3_usr_crt.pem"
+# bitmask of the permissions
+Permissions = 0x1
+
+[Authenticate Data]
+# Binary to be signed generated by mkimage
+File = "flash.bin"
+# Offsets = Container header Signature block (printed out by mkimage)
+Offsets = 0x400 0x590
diff --git a/doc/imx/ahab/csf_examples/csf_linux_img.txt b/doc/imx/ahab/csf_examples/csf_linux_img.txt
new file mode 100644
index 0000000..b5aa523
--- /dev/null
+++ b/doc/imx/ahab/csf_examples/csf_linux_img.txt
@@ -0,0 +1,21 @@
+[Header]
+Target = AHAB
+Version = 1.0
+
+[Install SRK]
+# SRK table generated by srktool
+File = "./release/crts/SRK_1_2_3_4_table.bin"
+# Public key certificate in PEM format
+Source = "./release/crts/SRK1_sha384_secp384r1_v3_usr_crt.pem"
+# Index of the public key certificate within the SRK table (0 .. 3)
+Source index = 0
+# Type of SRK set (NXP or OEM)
+Source set = OEM
+# bitmask of the revoked SRKs
+Revocations = 0x0
+
+[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
diff --git a/doc/imx/ahab/guides/mx8_mx8x_secure_boot.txt b/doc/imx/ahab/guides/mx8_mx8x_secure_boot.txt
new file mode 100644
index 0000000..3cdfd75
--- /dev/null
+++ b/doc/imx/ahab/guides/mx8_mx8x_secure_boot.txt
@@ -0,0 +1,398 @@
+ +=========================================================+
+ + 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) downloaded and built for your board
+ with debug monitor enabled.
+- 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. When you power on the board, you should have two
+serial consoles: one for U-Boot, another one for SCFW.
+
+Please note that SCU console may be replaced by the M4 console. In case the M4
+image is needed, a base board will be required to access the SCU console.
+
+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 the following command on
+the SCFW terminal:
+
+ >$ seco events
+
+Nothing should be returned after this command. If you get an error, please
+refer to examples below:
+
+0x0087EE00 = The container image is not signed.
+0x0087FA00 = The container image was signed with wrong key which are not
+ matching the OTP SRK hashes.
+
+In case your SRK fuses are not programmed yet the event 0x0087FA00 may also
+be displayed.
+
+Note: The SECO FW v1.1.0 is not logging an invalid image integrity as an event
+in open mode, in case your image does not boot after moving the lifecycle
+please review your image setup.
+
+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 32 (0x20) NXP open to 128 (0x80) OEM closed. Be
+aware this step can damage your board if a previous step failed. It is
+also irreversible. Run on the SCFW terminal:
+
+ >$ seco lifecycle 16
+
+Now reboot the target, and on the same terminal, run:
+
+ >$ seco info
+
+The lifecycle value should now be 128 (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."
