MLK-20553-3 doc: imx: ahab: Add Secure Boot documentation for i.MX8 and i.MX8x SPL targets

The current U-Boot implementation includes SPL targets for i.MX8QM and
i.MXQXP MEK boards:

- imx8qxp_mek_spl_defconfig
- imx8qxp_mek_spl_fspi_defconfig
- imx8qm_mek_spl_defconfig
- imx8qm_mek_spl_fspi_defconfig

The U-Boot proper and ATF are included in an additional container being
necessary a different procedure for signing the flash.bin image.

Add a step-by-step guide covering the signing procedure.
Add a CSF example for the 3rd container.

Signed-off-by: Breno Lima <breno.lima@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 04505024d38eebbb5f39133b502c8e450ca40215)

2 files changed, 379 insertions, 0 deletions

diff --git a/doc/imx/hab/ahab/csf_examples/cst_uboot_atf.txt b/doc/imx/hab/ahab/csf_examples/cst_uboot_atf.txt
new file mode 100644
index 0000000000..c4d23bcce4
--- /dev/null
+++ b/doc/imx/hab/ahab/csf_examples/cst_uboot_atf.txt
@@ -0,0 +1,21 @@
+[Header]
+Target = AHAB
+Version = 1.0
+
+[Install SRK]
+# SRK table generated by srktool
+File = "../crts/SRK_1_2_3_4_table.bin"
+# Public key certificate in PEM format on this example only using SRK key
+Source = "../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 = "u-boot-atf-container.img"
+# Offsets = Container header  Signature block (printed out by mkimage)
+Offsets   = 0x0             0x110
diff --git a/doc/imx/hab/ahab/guides/mx8_mx8x_spl_secure_boot.txt b/doc/imx/hab/ahab/guides/mx8_mx8x_spl_secure_boot.txt
new file mode 100644
index 0000000000..f903358687
--- /dev/null
+++ b/doc/imx/hab/ahab/guides/mx8_mx8x_spl_secure_boot.txt
@@ -0,0 +1,358 @@
+     +=========================================================+
+     +        i.MX 8, i.MX 8X AHAB guide on SPL targets        +
+     +=========================================================+
+
+1. AHAB secure boot process
+----------------------------
+
+This document provides a step-by-step guide on how securely boot a flash.bin
+image generated by Secondary Program Loader (SPL) targets. It is assumed that
+the reader is familiar with basic AHAB concepts and with the PKI tree
+generation.
+
+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
+-----------------------------------------------------------
+
+The following files and projects are used to prepare a secure boot image
+for i.MX8/8x device:
+
+- imx-mkimage.
+- SECO Firmware.
+- U-Boot proper and SPL. (Please refer to section 1.2)
+- ARM Trusted Firmware (ATF).
+- System Controller Firmware (SCFW) with debug monitor enabled.
+- Cortex M binary. (Optional)
+- Kernel image. (Optional)
+- Code signing tools (CST).
+
+The procedure to download the SECO firmware and build U-Boot, SCFW and ATF are
+out of the scope of this document, please refer to the Linux BSP Release Notes
+and AN12212[1] for further details.
+
+1.2 Preparing U-Boot to support AHAB secure boot features
+----------------------------------------------------------
+
+The U-Boot provides an alternative SPL target for i.MX8 and i.MX8x devices. The
+SPL is intended to be used by applications that requires a initial bootloader
+prior to initialize the ARM Trusted Firmware (ATF) and the U-Boot proper.
+
+The U-Boot support AHAB functions that are essential to completely authenticate
+the flash.bin image. On SPL targets only the SCFW, SPL and M4 IMG are
+authenticated at SCU ROM level, in order to authenticate the ATF and U-Boot
+proper it's necessary to call the SCU API sc_misc_seco_authenticate() function
+at SPL level.
+
+The support is enabled by adding CONFIG_AHAB_BOOT to the defconfig file used
+by your target:
+
+  - Defconfig:
+    CONFIG_AHAB_BOOT=y
+  - Kconfig:
+    ARM architecture -> Support i.MX 8 AHAB features
+
+1.3 Building a SPL image supporting secure boot
+------------------------------------------------
+
+The boot image generated by SPL targets has three containers:
+
+             +---------------------------+ ---------
+             |   1st Container header    |   ^
+             |       and signature       |   |
+             +---------------------------+   |
+             | Padding for 1kB alignment |   |
+             +---------------------------+   |
+             |   2nd Container header    |   |
+             |       and signature       |   |
+             +---------------------------+   |
+             |          Padding          |   |  Authenticated at
+             +---------------------------+   |   SCU ROM Level
+             |          SECO FW          |   |
+             +---------------------------+   |
+             |          Padding          |   |
+             +---------------------------+   |
+             |      SCU FW + DCD Table   |   |
+             +---------------------------+   |
+             |       Cortex-M Image      |   |
+             +---------------------------+   |
+             |         SPL Image         |   v
+             +---------------------------+ ---------
+             |   3rd Container header    |   ^
+             |       and signature       |   |
+             +---------------------------+   |
+             |          Padding          |   | Authenticated
+             +---------------------------+   |  at SPL Level
+             |     U-Boot Proper IMG     |   |
+             +---------------------------+   |
+             |    ARM Trusted FW (ATF)   |   v
+             +---------------------------+ ---------
+
+The first container includes the SECO firmware which is signed using NXP keys,
+this container is authenticated by SECO ROM at SCU ROM level.
+
+The second container includes the SCFW, SPL and Cortex M SW images which are
+signed using OEM keys, this container is authenticated by SECO FW at SCU ROM
+level.
+
+The third container includes the U-Boot proper and the ATF. The SPL is in
+charge to load this container and also to interface with SCU requesting
+SECO FW to authenticate the additional container.
+
+The signing procedure is slightly different when compared with HABv4 series. On
+AHAB the signature is directly included in the container, the CST is
+responsible to sign and handle the "Signature Block":
+
+             +----------------------------+ ---------
+             |                            |  ^
+             |                            |  |
+             |      Container header      |  |
+             |                            |  |
+             |                            |  |
+             +---+----------------------- +  |
+             | S | Signature block header |  | Signed
+             | i +------------------------+  |
+             | g |                        |  |
+             | n |                        |  |
+             | a |        SRK table       |  |
+             | t |                        |  |
+             | u |                        |  v
+             | r +------------------------+ ---------
+             | e |       Signature        |
+             |   +------------------------+
+             | B |                        |
+             | l |        SGK Key         |
+             | o | Certificate (optional) |
+             | c |                        |
+             | k |                        |
+             +---+------------------------+
+
+In case using the optional subordinate SGK key, the container signature is
+verified against the SGK key certificate. This certificate is verified
+against the SRK table.
+
+In case not using the subordinate key, the container signature is verified
+against the SRK keys directly.
+
+1.4 Preparing the boot image
+-----------------------------
+
+1.4.1 Preparing the 3rd container
+----------------------------------
+
+The first step is to generate the third container including the U-Boot proper
+and ATF images.
+
+The imx-mkimage project includes a target which only generates this third
+container:
+
+- Generating the U-Boot proper + ATF container:
+
+  $ make SOC=<SoC Name> u-boot-atf-container.img
+
+The mkimage log provides the container and signature block offsets used by the
+CSF description file:
+
+  CST: CONTAINER 0 offset: 0x0
+  CST: CONTAINER 0: Signature Block: offset is at 0x110
+
+The u-boot-atf-container.img file is the third container which have to be
+signed using the Code Signing Tool (CST).
+
+1.4.2 Signing the 3rd container
+--------------------------------
+
+The CSF description file contains all the commands that the SECO executes
+during the secure boot procedure. These commands instruct the AHAB code 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.
+
+As explained in section above the mkimage log provides the container and
+signature block offsets used by the CSF description file:
+
+- "Authenticate Data" command in cst_uboot_atf.txt file:
+
+  [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 third container:
+
+  $ ./cst -i cst_uboot_atf.txt -o signed-u-boot-atf-container.img
+
+The signed-u-boot-atf-container.img have to be copied to imx-mkimage directory
+and renamed to u-boot-atf-container.img.
+
+1.4.3 Preparing the flash.bin image
+------------------------------------
+
+The signed 3rd container can be now used to create the final flash.bin image,
+be sure that your signed container were successfully replaced and is named
+as u-boot-atf-container.img.
+
+- Generating the flash.bin image:
+
+  $ make SOC=<SoC Name> flash_spl_container
+
+The mkimage log provides the container and signature block offsets used by the
+CSF description file:
+
+  CST: CONTAINER 0 offset: 0x400
+  CST: CONTAINER 0: Signature Block: offset is at 0x510
+
+The flash.bin file include three containers and the second container have to be
+signed using the Code Signing Tool (CST).
+
+1.4.4 Signing the flash.bin image
+----------------------------------
+
+As mentioned above the CSF description file contains all the commands that
+the SECO executes during the secure boot procedure.
+
+The procedure for signing the flash.bin image is similar as documented in
+mx8_mx8x_secure_boot.txt guide.
+
+- "Authenticate Data" command in csf_boot_image.txt file:
+
+  [Authenticate Data]
+  # Binary to be signed generated by mkimage
+  File = "flash.bin"
+  # Offsets = Container header  Signature block
+  Offsets   = 0x400             0x510
+
+- Sign the flash.bin container:
+
+ $ ./cst -i csf_boot_image.txt -o signed-flash.bin
+
+The signed-flash.bin image contains all the signatures and can be flashed in
+the device.
+
+1.5 Flashing the signed image
+------------------------------
+
+After completing all steps in section "1.4 Preparing the boot image" the
+signed flash.bin image can be flashed in the device:
+
+  $ sudo dd if=signed-flash.bin of=/dev/sd<X> bs=1k seek=32 && sync
+
+For the next steps you should be able to see U-Boot and SCFW consoles in your
+host PC. 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.6 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.7 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.8 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
+-----------------------------------
+
+The procedure for authenticating the OS container is similar as in Non-SPL
+targets, for a complete procedure please refer to mx8_mx8x_secure_boot.txt
+document available under doc/imx/hab/ahab/guides/ directory.
+
+References:
+[1] AN12212: "Software Solutions for Migration Guide from Aarch32 to
+              Aarch64" - Rev 0."