MLK-20270-1 doc: imx: habv4: Add Secure Boot documentation for i.MX8M and i.MX8MM devices

Add HABv4 documentation for i.MX8M and i.MX8MM targets covering the
following topics:

- How to sign an securely boot an flash.bin image.
- How to extend the root of trust for additional boot images.
- Add 2 CSF examples.

Reviewed-by: Utkarsh Gupta <utkarsh.gupta@nxp.com>
Signed-off-by: Breno Lima <breno.lima@nxp.com>
(cherry picked from commit cc63be298a3e5f44e417f4098c124715917d09e1)

3 files changed, 611 insertions, 0 deletions

diff --git a/doc/imx/hab/habv4/csf_examples/mx8m_mx8mm/csf_fit.txt b/doc/imx/hab/habv4/csf_examples/mx8m_mx8mm/csf_fit.txt
new file mode 100644
index 0000000000..d9218ab431
--- /dev/null
+++ b/doc/imx/hab/habv4/csf_examples/mx8m_mx8mm/csf_fit.txt
@@ -0,0 +1,36 @@
+[Header]
+    Version = 4.3
+    Hash Algorithm = sha256
+    Engine = CAAM
+    Engine Configuration = 0
+    Certificate Format = X509
+    Signature Format = CMS
+
+[Install SRK]
+    # Index of the key location in the SRK table to be installed
+    File = "../crts/SRK_1_2_3_4_table.bin"
+    Source index = 0
+
+[Install CSFK]
+    # Key used to authenticate the CSF data
+    File = "../crts/CSF1_1_sha256_2048_65537_v3_usr_crt.pem"
+
+[Authenticate CSF]
+
+[Install Key]
+    # Key slot index used to authenticate the key to be installed
+    Verification index = 0
+    # Target key slot in HAB key store where key will be installed
+    Target index = 2
+    # Key to install
+    File = "../crts/IMG1_1_sha256_2048_65537_v3_usr_crt.pem"
+
+[Authenticate Data]
+    # Key slot index used to authenticate the image data
+    Verification index = 2
+    # Authenticate Start Address, Offset, Length and file
+    Blocks = 0x401fcdc0 0x057c00 0x01020 "flash.bin", \
+             0x40200000 0x05AC00 0x9AAC8 "flash.bin", \
+             0x00910000 0x0F56C8 0x09139 "flash.bin", \
+             0xFE000000 0x0FE804 0x4D268 "flash.bin", \
+             0x4029AAC8 0x14BA6C 0x06DCF "flash.bin"
diff --git a/doc/imx/hab/habv4/csf_examples/mx8m_mx8mm/csf_spl.txt b/doc/imx/hab/habv4/csf_examples/mx8m_mx8mm/csf_spl.txt
new file mode 100644
index 0000000000..39adf7a3eb
--- /dev/null
+++ b/doc/imx/hab/habv4/csf_examples/mx8m_mx8mm/csf_spl.txt
@@ -0,0 +1,37 @@
+[Header]
+    Version = 4.3
+    Hash Algorithm = sha256
+    Engine = CAAM
+    Engine Configuration = 0
+    Certificate Format = X509
+    Signature Format = CMS
+
+[Install SRK]
+    # Index of the key location in the SRK table to be installed
+    File = "../crts/SRK_1_2_3_4_table.bin"
+    Source index = 0
+
+[Install CSFK]
+    # Key used to authenticate the CSF data
+    File = "../crts/CSF1_1_sha256_2048_65537_v3_usr_crt.pem"
+
+[Authenticate CSF]
+
+[Unlock]
+    # Leave Job Ring and DECO master ID registers Unlocked
+    Engine = CAAM
+    Features = MID
+
+[Install Key]
+    # Key slot index used to authenticate the key to be installed
+    Verification index = 0
+    # Target key slot in HAB key store where key will be installed
+    Target index = 2
+    # Key to install
+    File = "../crts/IMG1_1_sha256_2048_65537_v3_usr_crt.pem"
+
+[Authenticate Data]
+    # Key slot index used to authenticate the image data
+    Verification index = 2
+    # Authenticate Start Address, Offset, Length and file
+    Blocks = 0x7e0fc0 0x1a000 0x2a600 "flash.bin"
diff --git a/doc/imx/hab/habv4/guides/mx8m_mx8mm_secure_boot.txt b/doc/imx/hab/habv4/guides/mx8m_mx8mm_secure_boot.txt
new file mode 100644
index 0000000000..79cd10d78b
--- /dev/null
+++ b/doc/imx/hab/habv4/guides/mx8m_mx8mm_secure_boot.txt
@@ -0,0 +1,538 @@
+         +=======================================================+
+         +     i.MX8M, i.MX8MM Secure Boot guide using HABv4     +
+         +=======================================================+
+
+1. HABv4 secure boot process
+-----------------------------
+
+This document describes a step-by-step procedure on how to sign and securely
+boot a bootloader image on i.MX8M and i.MX8MM devices. It is assumed that
+the reader is familiar with basic HAB concepts and with the PKI tree generation.
+
+Details about HAB can be found in the application note AN4581[1] and in the
+introduction_habv4.txt document.
+
+1.1 Understanding the i.MX8M and i.MX8MM flash.bin image layout
+----------------------------------------------------------------
+
+Due to the new the architecture, multiple firmwares and softwares are required
+to boot i.MX8M and i.MX8MM devices. In order to store all the images in a
+single binary the FIT (Flattened Image Tree) image structure is used.
+
+The final image is generated by the imx-mkimage project, the tool combines all
+the input images in a FIT structure, generating a flash.bin image with an
+appropriate IVT set.
+
+For a secure boot process users should ensure all images included in flash.bin
+file are covered by a digital signature.
+
+- The diagram below illustrate a signed flash.bin image layout:
+
+                     +-----------------------------+
+                     |                             |
+                     |     *Signed HDMI/DP FW      |
+                     |                             |
+                     +-----------------------------+
+                     |           Padding           |
+             ------- +-----------------------------+ --------
+                 ^   |          IVT - SPL          |   ^
+          Signed |   +-----------------------------+   |
+           Data  |   |        u-boot-spl.bin       |   |
+                 |   |              +              |   |  SPL
+                 v   |           DDR FW            |   | Image
+             ------- +-----------------------------+   |
+                     |      CSF - SPL + DDR FW     |   v
+                     +-----------------------------+ --------
+                     |           Padding           |
+             ------- +-----------------------------+ --------
+          Signed ^   |          FDT - FIT          |   ^
+           Data  |   +-----------------------------+   |
+                 v   |          IVT - FIT          |   |
+             ------- +-----------------------------+   |
+                     |          CSF - FIT          |   |
+             ------- +-----------------------------+   |
+                 ^   |       u-boot-nodtb.bin      |   |  FIT
+                 |   |               +             |   | Image
+                 |   |          u-boot.bin         |   |
+          Signed |   +-----------------------------+   |
+           Data  |   |       OP-TEE (Optional)     |   |
+                 |   +-----------------------------+   |
+                 |   |        bl31.bin (ATF)       |   |
+                 |   +-----------------------------+   |
+                 v   |          u-boot.dtb         |   v
+             ------- +-----------------------------+ --------
+  * Only supported on i.MX8M series
+
+The boot flow on i.MX8M and i.MX8MM devices are slightly different when compared
+with i.MX6 and i.MX7 series, the diagram below illustrate the boot sequence
+overview:
+
+- i.MX8M and i.MX8MM devices boot flow:
+
+                  Secure World                     Non-Secure World
+                                         |
+                                         |
+  +------------+      +------------+     |
+  |     SPL    |      | i.MX 8M/MM |     |
+  |      +     | ---> |    ROM     |     |
+  |   DDR FW   |      |   + HAB    |     |
+  +------------+      +------------+     |
+                             |           |
+                             v           |
+                      +------------+     |
+                      |  *Signed   |     |
+                      | HDMI/DP FW |     |
+                      +------------+     |
+                             |           |
+                             v           |
+  +------------+      +------------+     |
+  | FIT Image: |      |     SPL    |     |
+  | ATF + TEE  | ---> |      +     |     |
+  |  + U-Boot  |      |   DDR FW   |     |      +-----------+
+  +------------+      +------------+     |      |   Linux   |
+                             |           |      +-----------+
+                             v           |            ^
+                      +------------+     |            |             +-------+
+                      |    ARM     |     |      +-----------+       | Linux |
+                      |  Trusted   | ----+--->  |   U-Boot  |  <--- |   +   |
+                      |  Firmware  |     |      +-----------+       |  DTB  |
+                      +------------+     |                          +-------+
+                             |           |
+                             v           |
+                       +----------+      |
+                       | **OP-TEE |      |
+                       +----------+      |
+  * Only supported on i.MX8M series
+  ** Optional
+
+On i.MX8M devices the HDMI firmware or DisplayPort firmware are the first image
+to boot on the device. These firmwares are signed and distributed by NXP, and
+are always authenticated regardless of security configuration. In case not
+required by the application the HDMI or DisplayPort controllers can be disabled
+by eFuses and the firmwares are not required anymore.
+
+The next images are not signed by NXP and users should follow the signing
+procedure as described in this document.
+
+The Second Program Loader (SPL) and DDR firmware are loaded and authenticated
+by the ROM code, these images are executed in the internal RAM and responsible
+for initializing essential features such as DDR, UART, PMIC and clock
+enablement.
+
+Once the DDR is available, the SPL code loads all the images included in the
+FIT structure to their specific execution addresses, the HAB APIs are called
+to extend the root of trust, authenticating the U-Boot, ARM trusted firmware
+(ATF) and OP-TEE (If included).
+
+The root of trust can be extended again at U-Boot level to authenticate Kernel
+and M4 images.
+
+1.2 Enabling the secure boot support in U-Boot
+-----------------------------------------------
+
+The first step is to generate an U-Boot image supporting the HAB features,
+similar to i.MX6 and i.MX7 series the U-Boot provides extra functions for
+HAB, such as the HAB status logs retrievement through the hab_status command
+and support to extend the root of trust.
+
+The support is enabled by adding the CONFIG_SECURE_BOOT to the build
+configuration:
+
+- Defconfig:
+
+  CONFIG_SECURE_BOOT=y
+
+- Kconfig:
+
+  ARM architecture -> Support i.MX HAB features
+
+1.3 Preparing the fit image
+----------------------------
+
+The imx-mkimage project is used to combines all the images in a single
+flash.bin binary, the following files are required:
+
+- U-Boot:
+  u-boot.bin
+  u-boot-nodtb.bin
+  u-boot-spl.bin
+  U-Boot DTB file (e.g. fsl-imx8mq-evk.dtb)
+
+- ATF image:
+  bl31.bin
+
+- DDR firmware:
+  lpddr4_pmu_train_1d_dmem.bin
+  lpddr4_pmu_train_1d_imem.bin
+  lpddr4_pmu_train_2d_dmem.bin
+  lpddr4_pmu_train_2d_imem.bin
+
+- HDMI firmware (Only in i.MX8M):
+  signed_hdmi_imx8m.bin
+
+- DisplayPort firmware (Only in i.MX8M):
+  signed_dp_imx8m.bin
+
+- OP-TEE (Optional):
+  tee.bin
+
+The procedure to build ATF and download the firmwares are out of the scope
+of this document, please refer to the Linux BSP Release Notes and AN12212[2]
+for further details.
+
+Copy all files to iMX8M directory and run the following command according to
+the target device, on this example we are building a HDMI target and also
+including the OP-TEE binary:
+
+- Assembly flash.bin binary:
+
+  $ make SOC=<SoC Name> flash_hdmi_spl_uboot
+
+The mkimage log can be used to calculate the authenticate image command
+parameters and CSF offsets:
+
+- imx-mkimage build log:
+
+  Loader IMAGE:
+   header_image_off 	0x1a000
+   dcd_off 		0x0
+   image_off 		0x1a040
+   csf_off 		0x44600
+   spl hab block: 	0x7e0fd0 0x1a000 0x2e600
+
+  Second Loader IMAGE:
+   sld_header_off 	0x57c00
+   sld_csf_off 		0x58c20
+   sld hab block: 	0x401fcdc0 0x57c00 0x1020
+
+Additional HAB information is provided by running the following command:
+
+- Printing HAB FIT information:
+
+  $ make SOC=<SoC Name> print_fit_hab
+
+  TEE_LOAD_ADDR=0xfe000000 ATF_LOAD_ADDR=0x00910000 ./print_fit_hab.sh \
+  0x60000 fsl-imx8mq-evk.dtb
+  0x40200000 0x5AC00 0x9AAC8
+  0x910000 0xF56C8 0x9139
+  0xFE000000 0xFE804 0x4D268
+  0x4029AAC8 0x14BA6C 0x6DCF
+
+1.4 Creating the CSF description file
+--------------------------------------
+
+The CSF contains all the commands that the ROM executes during the secure
+boot. These commands instruct the HAB 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/habv4/csf_examples/ directory.
+
+As explained in sections above the SPL is first authenticated by the ROM code
+and the root of trust is extended to the FIT image, hence two CSF files are
+necessary to completely sign an flash.bin image.
+
+The build log provided by imx-mkimage can be used to define the "Authenticate
+Data" parameter in CSF.
+
+- SPL "Authenticate Data" addresses in flash.bin build log:
+
+  spl hab block: 0x7e0fd0 0x1a000 0x2e600
+
+- "Authenticate Data" command in csf_spl.txt file:
+
+  Blocks = 0x7e0fd0 0x1a000 0x2e600 "flash.bin"
+
+- FIT image "Authenticate Data" addresses in flash.bin build log:
+
+  sld hab block: 0x401fcdc0 0x57c00 0x1020
+
+- FIT image "Authenticate Data" addresses in print_fit_hab build log:
+
+  0x40200000 0x5AC00 0x9AAC8
+  0x910000 0xF56C8 0x9139
+  0xFE000000 0xFE804 0x4D268
+  0x4029AAC8 0x14BA6C 0x6DCF
+
+- "Authenticate Data" command in csf_fit.txt file:
+
+  Blocks = 0x401fcdc0 0x057c00 0x01020 "flash.bin", \
+           0x40200000 0x05AC00 0x9AAC8 "flash.bin", \
+           0x00910000 0x0F56C8 0x09139 "flash.bin", \
+           0xFE000000 0x0FE804 0x4D268 "flash.bin", \
+           0x4029AAC8 0x14BA6C 0x06DCF "flash.bin"
+
+1.4.1 Avoiding Kernel crash in closed devices
+----------------------------------------------
+
+For devices prior to HAB v4.4.0, the HAB code locks the Job Ring and DECO
+master ID registers in closed configuration. In case the user specific
+application requires any changes in CAAM MID registers it's necessary to
+add the "Unlock CAAM MID" command in CSF file.
+
+The current NXP BSP implementation expects the CAAM registers to be unlocked
+when configuring CAAM to operate in non-secure TrustZone world.
+
+The Unlock command is already included by default in the signed HDMI and
+DisplayPort firmwares, on i.MX8MM devices or in case the HDMI or DisplayPort
+controllers are disabled, users must ensure this command is included in SPL CSF.
+
+- Add Unlock MID command in csf_spl.txt:
+
+  [Unlock]
+      Engine = CAAM
+      Features = MID
+
+1.5 Signing the flash.bin binary
+---------------------------------
+
+The CST tool is used for singing the flash.bin image and generating the CSF
+binary. Users should input the CSF description file created in the step above
+and receive a CSF binary, which contains the CSF commands, SRK table,
+signatures and certificates.
+
+- Create SPL CSF binary file:
+
+ $ ./cst -i csf_spl.txt -o csf_spl.bin
+
+- Create FIT CSF binary file:
+
+ $ ./cst -i csf_fit.txt -o csf_fit.bin
+
+1.6 Assembling the CSF in flash.bin binary
+-------------------------------------------
+
+The CSF binaries generated in the step above have to be inserted into the
+flash.bin image.
+
+The CSF offsets can be obtained from the flash.bin build log:
+
+- SPL CSF offset:
+
+  csf_off 0x44600
+
+- FIT CSF offset:
+
+  sld_csf_off 0x58c20
+
+The signed flash.bin image can be then assembled:
+
+- Create a flash.bin copy:
+
+  $ cp flash.bin signed_flash.bin
+
+- Insert csf_spl.bin in signed_flash.bin at 0x44600 offset:
+
+  $ dd if=csf_spl.bin of=signed_flash.bin seek=$((0x44600)) bs=1 conv=notrunc
+
+- Insert csf_fit.bin in signed_flash.bin at 0x58c20 offset:
+
+  $ dd if=csf_fit.bin of=signed_flash.bin seek=$((0x58c20)) bs=1 conv=notrunc
+
+- Flash signed flash.bin image:
+
+  $ sudo dd if=signed_flash.bin of=/dev/sd<x> bs=1K seek=33 && sync
+
+1.7 Programming SRK Hash
+-------------------------
+
+As explained in AN4581[1] and in introduction_habv4.txt document the SRK Hash
+fuse values are generated by the srktool and should be programmed in the
+SoC SRK_HASH[255: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:
+
+  $ hexdump -e '/4 "0x"' -e '/4 "%X""\n"' SRK_1_2_3_4_fuse.bin
+  0x20593752
+  0x6ACE6962
+  0x26E0D06C
+  0xFC600661
+  0x1240E88F
+  0x1209F144
+  0x831C8117
+  0x1190FD4D
+
+- Program SRK_HASH[255:0] fuses on i.MX8MQ and i.MX8MM devices:
+
+  => fuse prog 6 0 0x20593752
+  => fuse prog 6 1 0x6ACE6962
+  => fuse prog 6 2 0x26E0D06C
+  => fuse prog 6 3 0xFC600661
+  => fuse prog 7 0 0x1240E88F
+  => fuse prog 7 1 0x1209F144
+  => fuse prog 7 2 0x831C8117
+  => fuse prog 7 3 0x1190FD4D
+
+
+1.8 Verifying HAB events
+-------------------------
+
+The next step is to verify that the signatures included in flash.bin image is
+successfully processed without errors. HAB generates events when processing
+the commands if it encounters issues.
+
+The hab_status U-Boot command call the hab_report_event() and hab_status()
+HAB API functions to verify the processor security configuration and status.
+This command displays any events that were generated during the process.
+
+Prior to closing the device users should ensure no HAB events were found, as
+the example below:
+
+- Verify HAB events:
+
+  => hab_status
+
+  Secure boot disabled
+
+  HAB Configuration: 0xf0, HAB State: 0x66
+
+1.9 Closing the device
+-----------------------
+
+After the device successfully boots a signed image without generating any HAB
+events, it is safe to close the device. This is the last step in the HAB
+process, and is achieved by programming the SEC_CONFIG[1] fuse bit.
+
+Once the fuse is programmed, the chip does not load an image that has not been
+signed using the correct PKI tree.
+
+- Program SEC_CONFIG[1] fuse on i.MX8MQ and i.MX8MM devices:
+
+  => fuse prog 1 3 0x2000000
+
+1.10 Completely secure the device
+----------------------------------
+
+Additional fuses can be programmed for completely secure the device, more
+details about these fuses and their possible impact can be found at AN4581[1].
+
+- Program SRK_LOCK:
+
+  => fuse prog 0 0 0x200
+
+- Program DIR_BT_DIS:
+
+  => fuse prog 1 3 0x8000000
+
+- Program SJC_DISABLE:
+
+  => fuse prog 1 3 0x200000
+
+- JTAG_SMODE:
+
+  => fuse prog 1 3 0xC00000
+
+2. Authenticating additional boot images
+-----------------------------------------
+
+The High Assurance Boot (HAB) code located in the on-chip ROM provides an
+Application Programming Interface (API) making it possible to call back
+into the HAB code for authenticating additional boot images.
+
+The U-Boot is running in non-secure TrustZone world and to make use of this
+feature it's necessary to use a SIP call to the ATF, this is already
+implemented in hab.c code and it's transparent to the user.
+
+The process of signing an additional image is similar as in i.MX6 and i.MX7
+series devices, the steps below are using the Linux Kernel image as example.
+
+The diagram below illustrate the Image layout:
+
+            ------- +-----------------------------+ <-- *load_address
+                ^   |                             |
+                |   |                             |
+                |   |                             |
+                |   |                             |
+                |   |            Image            |
+         Signed |   |                             |
+          Data  |   |                             |
+                |   |                             |
+                |   +-----------------------------+
+                |   |    Padding to Image size    |
+                |   |          in header          |
+                |   +-----------------------------+ <-- *ivt
+                v   |     Image Vector Table      |
+            ------- +-----------------------------+ <-- *csf
+                    |                             |
+                    | Command Sequence File (CSF) |
+                    |                             |
+                    +-----------------------------+
+                    |     Padding (optional)      |
+                    +-----------------------------+
+
+2.1 Padding the image
+----------------------
+
+The Image must be padded to the size specified in the Image header, this can be
+achieved by using the od command.
+
+- Read Image size:
+
+  $ od -x -j 0x10 -N 0x4 --endian=little Image
+  0000020 5000 0145
+  0000024
+
+The tool objcopy can be used for padding the image.
+
+- Pad the Image:
+
+  $ objcopy -I binary -O binary --pad-to 0x1455000 --gap-fill=0x00 \
+	Image Image_pad.bin
+
+2.2 Generating Image Vector Table
+----------------------------------
+
+The HAB code requires an Image Vector Table (IVT) for determining the image
+length and the CSF location. Since Image does not include an IVT this has
+to be manually created and appended to the end of the padded Image, the
+script genIVT.pl in script_examples directory can be used as reference.
+
+- Generate IVT:
+
+  $ genIVT.pl
+
+Note: The load Address may change depending on the device.
+
+- Append the ivt.bin at the end of the padded Image:
+
+  $ cat Image_pad.bin ivt.bin > Image_pad_ivt.bin
+
+2.3 Signing the image
+----------------------
+
+A CSF file has to be created to sign the image. HAB does not allow to change
+the SRK once the first image is authenticated, so the same SRK key used in
+the initial image must be used when extending the root of trust.
+
+CSF examples are available in ../csf_examples/additional_images/ directory.
+
+- Create CSF binary file:
+
+  $ ./cst --i csf_additional_images.txt --o csf_Image.bin
+
+- Attach the CSF binary to the end of the image:
+
+  $ cat Image_pad_ivt.bin csf_Image.bin > Image_signed.bin
+
+2.4 Verifying HAB events
+-------------------------
+
+The U-Boot includes the hab_auth_img command which can be used for
+authenticating and troubleshooting the signed image, the Image must be
+loaded at the load address specified in the IVT.
+
+- Authenticate additional image:
+
+  => hab_auth_img <Load Address> <Image Size> <IVT Offset>
+
+If no HAB events were found the Image is successfully signed.
+
+References:
+[1] AN4581: "Secure Boot on i.MX 50, i.MX 53, i.MX 6 and i.MX 7 Series using
+ HABv4" - Rev 2.
+[2] AN12212: "Software Solutions for Migration Guide from Aarch32 to
+Aarch64" - Rev 0.