diff options
author | Clement Le Marquis <clement.lemarquis@nxp.com> | 2018-11-28 13:10:22 +0100 |
---|---|---|
committer | Ye Li <ye.li@nxp.com> | 2018-12-13 17:48:27 -0800 |
commit | a83dc28deed19de1a50ef42fed553cd26e4c590d (patch) | |
tree | 79f7a2cc50a55998cdc5ae723e347a79abc326aa /doc | |
parent | c9a3780acc0401eba688fe43ad7cf4e5df4f5c38 (diff) |
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)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/imx/hab/ahab/csf_examples/csf_boot_image.txt | 21 | ||||
-rw-r--r-- | doc/imx/hab/ahab/csf_examples/csf_boot_image_sgk.txt | 28 | ||||
-rw-r--r-- | doc/imx/hab/ahab/csf_examples/csf_linux_img.txt | 21 | ||||
-rw-r--r-- | doc/imx/hab/ahab/guides/mx8_mx8x_secure_boot.txt | 398 |
4 files changed, 468 insertions, 0 deletions
diff --git a/doc/imx/hab/ahab/csf_examples/csf_boot_image.txt b/doc/imx/hab/ahab/csf_examples/csf_boot_image.txt new file mode 100644 index 00000000000..1f296f09007 --- /dev/null +++ b/doc/imx/hab/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/hab/ahab/csf_examples/csf_boot_image_sgk.txt b/doc/imx/hab/ahab/csf_examples/csf_boot_image_sgk.txt new file mode 100644 index 00000000000..ec42f4f09ea --- /dev/null +++ b/doc/imx/hab/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/hab/ahab/csf_examples/csf_linux_img.txt b/doc/imx/hab/ahab/csf_examples/csf_linux_img.txt new file mode 100644 index 00000000000..b5aa5238023 --- /dev/null +++ b/doc/imx/hab/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/hab/ahab/guides/mx8_mx8x_secure_boot.txt b/doc/imx/hab/ahab/guides/mx8_mx8x_secure_boot.txt new file mode 100644 index 00000000000..3cdfd75c8e4 --- /dev/null +++ b/doc/imx/hab/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." |