doc: imx: habv4: Add Secure Boot guide for i.MX6 and i.MX7 SPL targets

The current U-Boot implementation includes SPL targets for
some NXP development boards:

- mx6sabreauto_defconfig
- mx6sabresd_defconfig
- mx6ul_14x14_evk_defconfig
- mx6ul_9x9_evk_defconfig

Add additional steps needed to completly secure the
bootloader image.

Signed-off-by: Breno Lima <breno.lima@nxp.com>

1 files changed, 181 insertions, 0 deletions

diff --git a/doc/imx/habv4/guides/mx6_mx7_spl_secure_boot.txt b/doc/imx/habv4/guides/mx6_mx7_spl_secure_boot.txt
new file mode 100644
index 0000000000..0d7931aac0
--- /dev/null
+++ b/doc/imx/habv4/guides/mx6_mx7_spl_secure_boot.txt
@@ -0,0 +1,181 @@
+      +===============================================================+
+      +  i.MX6, i.MX7 U-Boot HABv4 Secure Boot guide for SPL targets  +
+      +===============================================================+
+
+1. HABv4 secure boot process
+-----------------------------
+
+This document is an addendum of mx6_mx7_secure_boot.txt guide describing a
+step-by-step procedure on how to sign and securely boot an U-Boot image for
+SPL targets.
+
+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 provides Second Program Loader (SPL) support which generates two
+final images, SPL and U-Boot proper. The HABv4 can be used to authenticate
+both binaries.
+
+Out of reset the ROM code authenticates the SPL 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 U-Boot proper
+image to its specific execution address and call the HAB APIs to extend the
+root of trust.
+
+The U-Boot provides support to secure boot configuration and also provide
+access to the HAB APIs exposed by the ROM vector table, the support is
+enabled by selecting the CONFIG_SECURE_BOOT option.
+
+When built with this configuration the U-Boot correctly pads the final SPL
+image 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 append an Image Vector Table (IVT) in the final U-Boot proper
+binary (u-boot-ivt.img) so it can be used by HAB API in a post ROM stage.
+
+The diagram below illustrate a signed SPL image layout:
+
+            ------- +-----------------------------+ <-- *start
+                ^   |      Image Vector Table     |
+                |   +-----------------------------+ <-- *boot_data
+                |   |          Boot Data          |
+                |   +-----------------------------+
+         Signed |   |           Padding           |
+          Data  |   +-----------------------------+ <-- *entry
+                |   |                             |
+                |   |            SPL              |
+                |   |                             |
+                |   +-----------------------------+
+                v   |           Padding           |
+            ------- +-----------------------------+ <-- *csf
+                    |                             |
+                    | Command Sequence File (CSF) |
+                    |                             |
+                    +-----------------------------+
+                    |      Padding (optional)     |
+                    +-----------------------------+
+
+The diagram below illustrate a signed u-boot-ivt.img image layout:
+
+            ------- +-----------------------------+ <-- *load_address
+                ^   |                             |
+                |   |                             |
+                |   |         u-boot.img          |
+         Signed |   |                             |
+          Data  |   |                             |
+                |   +-----------------------------+
+                |   |    Padding Next Boundary    |
+                |   +-----------------------------+ <-- *ivt
+                v   |     Image Vector Table      |
+            ------- +-----------------------------+ <-- *csf
+                    |                             |
+                    | Command Sequence File (CSF) |
+                    |                             |
+                    +-----------------------------+
+                    |     Padding (optional)      |
+                    +-----------------------------+
+
+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_SECURE_BOOT to the
+build configuration:
+
+- Defconfig:
+
+  CONFIG_SECURE_BOOT=y
+
+- Kconfig:
+
+  ARM architecture -> Support i.MX HAB features
+
+1.3 Creating the CSF description file
+--------------------------------------
+
+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.
+
+CSF examples are available under doc/imx/habv4/csf_examples/ directory.
+
+Build logs containing the "Authenticate Data" parameters are available after
+the U-Boot build, the example below is a log for mx6sabresd_defconfig target:
+
+- SPL build log:
+
+  $ cat SPL.log
+  Image Type:   Freescale IMX Boot Image
+  Image Ver:    2 (i.MX53/6/7 compatible)
+  Mode:         DCD
+  Data Size:    69632 Bytes = 68.00 KiB = 0.07 MiB
+  Load Address: 00907420
+  Entry Point:  00908000
+  HAB Blocks:   0x00907400 0x00000000 0x0000ec00
+
+- u-boot-ivt.img build log:
+
+  $ cat u-boot-ivt.img.log
+  Image Name:   U-Boot 2019.01-00003-g78ee492eb3
+  Created:      Mon Jan 14 17:58:10 2019
+  Image Type:   ARM U-Boot Firmware with HABv4 IVT (uncompressed)
+  Data Size:    458688 Bytes = 447.94 KiB = 0.44 MiB
+  Load Address: 17800000
+  Entry Point:  00000000
+  HAB Blocks:   0x177fffc0   0x0000   0x0006e020
+
+As explained in section above the SPL is first authenticated by the ROM code
+and the root of trust is extended to the U-Boot image, hence two CSF files are
+necessary to completely sign a bootloader image.
+
+In "Authenticate Data" CSF command users can copy and past the output
+addresses, the csf_uboot.txt can be used as example:
+
+- In csf_SPL.txt:
+
+  Block = 0x00907400 0x00000000 0x0000ec00 "SPL"
+
+- In csf_uboot-ivt.txt:
+
+  Block = 0x177fffc0 0x0000 0x0006e020 "u-boot-ivt.img"
+
+1.4 Signing the images
+-----------------------
+
+The CST tool is used for singing the U-Boot binary and generating a 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
+
+- Append CSF signature to the end of SPL image:
+
+  $ cat SPL csf_SPL.bin > SPL-signed
+
+- Create U-Boot proper CSF binary file:
+
+  $ ./cst -i csf_uboot-ivt.txt -o csf_uboot-ivt.bin
+
+- Append CSF signature to the end of U-Boot proper image:
+
+  $ cat u-boot-ivt.img csf_uboot-ivt.bin > u-boot-signed.img
+
+The bootloader is signed and can be flashed into the boot media.
+
+1.5 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.