      +=========================================================+
      +  i.MX8M U-Boot HABv4 Secure Boot guide for SPL targets  +
      +=========================================================+

1. HABv4 secure boot process
-----------------------------

This document is an addendum of mx6_mx7_spl_secure_boot.txt guide describing
a step-by-step procedure on how to sign and securely boot an U-Boot image for
SPL targets on i.MX8M, i.MX8M Mini, i.MX8M Nano, i.MX8M Plus.

Details about HAB can be found in the application note AN4581[1] and in the
introduction_habv4.txt document.

1.1 Building a SPL target supporting secure boot
-------------------------------------------------

The U-Boot build for i.MX8M SoC makes use of Second Program Loader (SPL)
support, fitImage support and custom i.MX8M specific flash.bin container.
This leads to a generation of multiple intermediate build artifacts, the
U-Boot SPL, U-Boot binary, DT blob. These later two artifacts are bundled
with external ATF BL31 blob to form a fitImage. The fitImage is bundled
with SPL and external DDR and optional HDMI PHY initialization blobs to
form the final flash.bin container. The HABv4 can be used to authenticate
all of the input binaries separately.

Out of reset the ROM code authenticates the SPL and PHY initialization
blobs, combination of which is responsible for initializing essential
features such as DDR, UART, PMIC and clock enablement. Once the DDR is
available, the SPL code loads the secondary fitImage to its specific
address and call the HAB APIs to extend the root of trust on its
components.

The U-Boot SPL provides support to secure boot configuration and also
provide access to the HAB APIs exposed by the ROM vector table, the
U-Boot provides access to HAB APIs via SMC calls to ATF. The support
is enabled by selecting the CONFIG_IMX_HAB option.

When built with this configuration the U-Boot correctly pads combined
SPL and PHY initialization blob image, called u-boot-spl-ddr.bin, by
aligning to the next 0xC00 address, so the CSF signature data generated
by CST can be concatenated to the image.

The U-Boot also reserves space in the fitImage binary (u-boot.itb) between
the fitImage tree and external blobs included in it, so it can be used to
inject IVT and CST signatures used by SPL HAB calls to authenticate the
fitImage components.

The diagram below illustrate a signed SPL combined with DDR PHY
initialization firmware blobs part of flash.bin container layout.
This part is loaded to memory address ( CONFIG_SPL_TEXT_BASE - 0x40 ) and
authenticated the BootROM. The reason for the offset is so that the *entry
would be at memory address CONFIG_SPL_TEXT_BASE when BootROM executes the
code within it:

            ------- +-----------------------------+ <-- *start
                ^   |      Image Vector Table     |
                |   |         (0x20 bytes)        |
                |   +-----------------------------+ <-- *boot_data
                |   |          Boot Data          |
                |   +-----------------------------+
                |   |           Padding           |
         Signed |   |  to 0x40 bytes from *start  |
          Data  |   +-----------------------------+ <-- *entry
                |   |                             |
                |   |  SPL combined with DDR PHY  |
                |   |    initialization blobs     |
                |   |    (u-boot-spl-ddr.bin)     |
                |   |                             |
                |   +-----------------------------+
                v   |           Padding           |
            ------- +-----------------------------+ <-- *csf
                    |                             |
                    | Command Sequence File (CSF) |
                    |                             |
                    +-----------------------------+
                    |      Padding (optional)     |
                    +-----------------------------+

The diagram below illustrate a signed U-Boot binary, DT blob and external
ATF BL31 blob combined to form fitImage part of flash.bin container layout.
The *load_address is CONFIG_SPL_LOAD_FIT_ADDRESS, the fitImage is loaded
including all of its embedded data, authenticated using IVT+CSF concatenated
at the end of the fitImage at offset aligned to 4 kiB. The fitImage with
external data is not supported.

            ------- +-----------------------------+ <-- *load_address
                ^   |                             |
                |   |        fitImage tree        |
                |   |      with embedded data     |
                |   |        (cca. 1 MiB)         |
         Signed |   |                             |
  .-----  Tree  |   +-----------------------------+
  |       Data  |   | Padding to next 4k aligned  |
  |             |   |     from *load_address      |
  |             |   +-----------------------------+ <-- *ivt
  |             |   |     Image Vector Table      |
  |             v   |         (0x20 bytes)        |
  |         ------- +-----------------------------+ <-- *csf
  |                 | Command Sequence File (CSF) |
  |                 |  for all signed entries in  |
  '---------------->| the fitImage, tree and data |
                    |        (cca 6-7 kiB)        |
                    +-----------------------------+

The diagram below illustrate a combined flash.bin container layout:

                    +-----------------------------+
                    |       Signed SPL part       |
                    +-----------------------------+
                    |     Signed fitImage part    |
                    +-----------------------------+

1.2 Enabling the secure boot support
-------------------------------------

The first step is to generate an U-Boot image supporting the HAB features
mentioned above, this can be achieved by adding CONFIG_IMX_HAB to the
build configuration:

- Defconfig:

  CONFIG_IMX_HAB=y
  CONFIG_FSL_CAAM=y
  CONFIG_ARCH_MISC_INIT=y
  CONFIG_SPL_CRYPTO=y

- Kconfig:

  ARM architecture -> Support i.MX HAB features

1.3 Signing the images
-----------------------

The CSF contains all the commands that the HAB 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. The CSF is generated
using the CST Code Signing Tool based on input configuration file. This tool
input configuration file is generated using binman, and the tool is invoked
from binman as well.

The SPL and fitImage sections of the generated image are signed separately.
The signing is activated by wrapping SPL and fitImage sections into nxp-imx8mcst
etype, which is done automatically in arch/arm/dts/imx8m{m,n,p,q}-u-boot.dtsi
in case CONFIG_IMX_HAB Kconfig symbol is enabled.

Per default the HAB keys and certificates need to be located in the build
directory, this means creating a symbolic link or copying the following files
from the HAB keys directory flat (e.g. removing the `keys` and `cert`
subdirectory) into the u-boot build directory for the CST Code Signing Tool to
locate them:

- `crts/SRK_1_2_3_4_table.bin`
- `crts/CSF1_1_sha256_4096_65537_v3_usr_crt.pem`
- `keys/CSF1_1_sha256_4096_65537_v3_usr_key.pem`
- `crts/IMG1_1_sha256_4096_65537_v3_usr_crt.pem`
- `keys/IMG1_1_sha256_4096_65537_v3_usr_key.pem`
- `keys/key_pass.txt`

The paths to the SRK table and the certificates can be modified via changes to
the nxp_imx8mcst device tree node(s), however the other files are required by
the CST tools as well, and will be searched for in relation to them.

Build of flash.bin target then produces a signed flash.bin automatically.

The nxp-imx8mcst etype is configurable using either DT properties or environment
variables. The following DT properties and environment variables are supported.
Note that environment variables override DT properties.

+--------------------+-----------+------------------------------------------------------------------+
| DT property        | Variable  | Description                                                      |
+====================+===========+==================================================================+
| nxp,loader-address |           | SPL base address                                                 |
+--------------------+-----------+------------------------------------------------------------------+
| nxp,srk-table      | SRK_TABLE | full path to SRK_1_2_3_4_table.bin                               |
+--------------------+-----------+------------------------------------------------------------------+
| nxp,csf-crt        | CSF_KEY   | full path to the CSF Key CSF1_1_sha256_4096_65537_v3_usr_crt.pem |
+--------------------+-----------+------------------------------------------------------------------+
| nxp,img-crt        | IMG_KEY   | full path to the IMG Key IMG1_1_sha256_4096_65537_v3_usr_crt.pem |
+--------------------+-----------+------------------------------------------------------------------+

Environment variables can be set as follows to point the build process
to external key material:
```
export CST_DIR=/usr/src/cst-3.3.1/
export CSF_KEY=$CST_DIR/crts/CSF1_1_sha256_4096_65537_v3_usr_crt.pem
export IMG_KEY=$CST_DIR/crts/IMG1_1_sha256_4096_65537_v3_usr_crt.pem
export SRK_TABLE=$CST_DIR/crts/SRK_1_2_3_4_table.bin
make flash.bin
```

1.4 Closing the device
-----------------------

The procedure for closing the device is similar as in Non-SPL targets, for a
complete procedure please refer to section "1.5 Programming SRK Hash" in
mx6_mx7_secure_boot.txt document available under doc/imx/habv4/guides/
directory.

References:
[1] AN4581: "Secure Boot on i.MX 50, i.MX 53, i.MX 6 and i.MX 7 Series using
 HABv4" - Rev 2.
