MLK-19970-2 doc: imx: habv4: Add Secure Boot documentation for i.MX6 and i.MX7 family devices

Add HABv4 documentation for u-boot-dtb.imx targets covering the
following topics:

- How to sign an securely boot an u-boot-dtb.imx image.
- How to extend the root of trust for additional boot images.
- Add 3 CSF examples.
- Add IVT generation script example.

Reviewed-by: Ye Li <ye.li@nxp.com>
Reviewed-by: Utkarsh Gupta <utkarsh.gupta@nxp.com>
Signed-off-by: Breno Lima <breno.lima@nxp.com>

5 files changed, 503 insertions, 0 deletions

diff --git a/doc/imx/hab/habv4/csf_examples/additional_images/csf_additional_images.txt b/doc/imx/hab/habv4/csf_examples/additional_images/csf_additional_images.txt
new file mode 100644
index 0000000000..bbe489714b
--- /dev/null
+++ b/doc/imx/hab/habv4/csf_examples/additional_images/csf_additional_images.txt
@@ -0,0 +1,34 @@
+[Header]
+    Version = 4.2
+    Hash Algorithm = sha256
+    Engine Configuration = 0
+    Certificate Format = X509
+    Signature Format = CMS
+    Engine = CAAM
+
+[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 = 0x80800000 0x00000000 0x80EEA020 "zImage", \
+	     0x83800000 0x00000000 0x8380B927 "imx7d-sdb.dtb", \
+	     0x84000000 0x00000000 0x840425B8 "uTee-7dsdb"
diff --git a/doc/imx/hab/habv4/csf_examples/mx6_mx7/csf_uboot.txt b/doc/imx/hab/habv4/csf_examples/mx6_mx7/csf_uboot.txt
new file mode 100644
index 0000000000..39986243e4
--- /dev/null
+++ b/doc/imx/hab/habv4/csf_examples/mx6_mx7/csf_uboot.txt
@@ -0,0 +1,32 @@
+[Header]
+    Version = 4.2
+    Hash Algorithm = sha256
+    Engine Configuration = 0
+    Certificate Format = X509
+    Signature Format = CMS
+    Engine = CAAM
+
+[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 =  0x877ff400 0x00000000 0x0009ec00 "u-boot-dtb.imx"
diff --git a/doc/imx/hab/habv4/csf_examples/mx6_mx7/csf_uboot_fast_authentication.txt b/doc/imx/hab/habv4/csf_examples/mx6_mx7/csf_uboot_fast_authentication.txt
new file mode 100644
index 0000000000..cdb34bcf74
--- /dev/null
+++ b/doc/imx/hab/habv4/csf_examples/mx6_mx7/csf_uboot_fast_authentication.txt
@@ -0,0 +1,23 @@
+[Header]
+    Version = 4.2
+    Hash Algorithm = sha256
+    Engine Configuration = 0
+    Certificate Format = X509
+    Signature Format = CMS
+    Engine = CAAM
+
+[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 NOCAK]
+    File = "../crts/SRK1_sha256_2048_65537_v3_usr_crt.pem"
+
+[Authenticate CSF]
+
+[Authenticate Data]
+    # Key slot index 0 used to authenticate the image data
+    Verification index = 0
+    # Authenticate Start Address, Offset, Length and file
+    Blocks =  0x877ff400 0x00000000 0x0009ec00 "u-boot-dtb.imx"
diff --git a/doc/imx/hab/habv4/guides/mx6_mx7_secure_boot.txt b/doc/imx/hab/habv4/guides/mx6_mx7_secure_boot.txt
new file mode 100644
index 0000000000..16c63c1c76
--- /dev/null
+++ b/doc/imx/hab/habv4/guides/mx6_mx7_secure_boot.txt
@@ -0,0 +1,402 @@
+         +=======================================================+
+         +   i.MX6, i.MX7 U-Boot 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 an U-Boot image. 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 Building a u-boot-dtb.imx image supporting secure boot
+-----------------------------------------------------------
+
+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 provides extra functions for
+HAB, such as the HAB status logs retrievement through the hab_status command
+and support for extending the root of trust.
+
+The U-Boot also correctly pads the final image by aligning to the next 0xC00
+address, so the CSF signature data generated by CST can be concatenated to
+image.
+
+The diagram below illustrate a signed u-boot-dtb.imx image layout:
+
+            ------- +-----------------------------+ <-- *start
+                ^   |      Image Vector Table     |
+                |   +-----------------------------+ <-- *boot_data
+                |   |          Boot Data          |
+                |   +-----------------------------+ <-- *dcd
+                |   |          DCD Table          |
+                |   +-----------------------------+
+         Signed |   |           Padding           |
+          Data  |   +-----------------------------+ <-- *entry
+                |   |                             |
+                |   |                             |
+                |   |       u-boot-dtb.bin        |
+                |   |                             |
+                |   |                             |
+                |   +-----------------------------+
+                v   |           Padding           |
+            ------- +-----------------------------+ <-- *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 ROM executes during the secure
+boot. These commands instruct the HAB 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.
+
+A build log containing the "Authenticate Data" parameters is available after
+the U-Boot build, the example below is a log for mx7dsabresd_defconfig target:
+
+- mkimage build log:
+
+  $ cat u-boot-dtb.imx.log
+
+  Image Type:   Freescale IMX Boot Image
+  Image Ver:    2 (i.MX53/6/7 compatible)
+  Mode:         DCD
+  Data Size:    667648 Bytes = 652.00 KiB = 0.64 MiB
+  Load Address: 877ff420
+  Entry Point:  87800000
+  HAB Blocks:   877ff400 00000000 0009ec00
+                ^^^^^^^^ ^^^^^^^^ ^^^^^^^^
+                |        |        |
+                |        |        ------- (1)
+                |        |
+                |        ---------------- (2)
+                |
+                ------------------------- (3)
+
+  (1)   Size of area in file u-boot-dtb.imx to sign.
+        This area should include the IVT, the Boot Data the DCD
+        and the U-Boot itself.
+  (2)   Start of area in u-boot-dtb.imx to sign.
+  (3)   Start of area in RAM to authenticate.
+
+- In "Authenticate Data" CSF command users can copy and past the output
+  addresses:
+
+  Block = 0x877ff400 0x00000000 0x0009ec00 "u-boot-dtb.imx"
+
+1.4 Signing the U-Boot binary
+------------------------------
+
+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
+should receive a CSF binary, which contains the CSF commands, SRK table,
+signatures and certificates.
+
+- Create CSF binary file:
+
+  $ ./cst -i csf_uboot.txt -o csf_uboot.bin
+
+- Append CSF signature to the end of U-Boot image:
+
+  $ cat u-boot-dtb.imx csf_uboot.bin > u-boot-signed.imx
+
+The u-boot-signed.imx is the signed binary and should be flashed into the boot
+media.
+
+- Flash signed U-Boot binary:
+
+  $ sudo dd if=u-boot-signed.imx of=/dev/sd<x> bs=1K seek=1 && sync
+
+1.5 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, using i.MX6 series as example:
+
+  => fuse prog 3 0 0x20593752
+  => fuse prog 3 1 0x6ACE6962
+  => fuse prog 3 2 0x26E0D06C
+  => fuse prog 3 3 0xFC600661
+  => fuse prog 3 4 0x1240E88F
+  => fuse prog 3 5 0x1209F144
+  => fuse prog 3 6 0x831C8117
+  => fuse prog 3 7 0x1190FD4D
+
+The table below lists the SRK_HASH bank and word according to the i.MX device:
+
+    +-------------------+---------------+---------------+---------------+
+    |                   |  i.MX6 Series |    i.MX7D/S   |    i.MX7ULP   |
+    +-------------------+---------------+---------------+---------------+
+    | SRK_HASH[31:00]   | bank 3 word 0 | bank 6 word 0 | bank 5 word 0 |
+    +-------------------+---------------+---------------+---------------+
+    | SRK_HASH[63:32]   | bank 3 word 1 | bank 6 word 1 | bank 5 word 1 |
+    +-------------------+---------------+---------------+---------------+
+    | SRK_HASH[95:64]   | bank 3 word 2 | bank 6 word 2 | bank 5 word 2 |
+    +-------------------+---------------+---------------+---------------+
+    | SRK_HASH[127:96]  | bank 3 word 3 | bank 6 word 3 | bank 5 word 3 |
+    +-------------------+---------------+---------------+---------------+
+    | SRK_HASH[159:128] | bank 3 word 4 | bank 7 word 0 | bank 5 word 4 |
+    +-------------------+---------------+---------------+---------------+
+    | SRK_HASH[191:160] | bank 3 word 5 | bank 7 word 1 | bank 5 word 5 |
+    +-------------------+---------------+---------------+---------------+
+    | SRK_HASH[223:192] | bank 3 word 6 | bank 7 word 2 | bank 5 word 6 |
+    +-------------------+---------------+---------------+---------------+
+    | SRK_HASH[255:224] | bank 3 word 7 | bank 7 word 3 | bank 5 word 7 |
+    +-------------------+---------------+---------------+---------------+
+
+1.6 Verifying HAB events
+-------------------------
+
+The next step is to verify that the signature attached to U-Boot 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
+  No HAB Events Found!
+
+1.7 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, using i.MX6 series as example:
+
+  => fuse prog 0 6 0x00000002
+
+The table below list the SEC_CONFIG[1] bank and word according to the i.MX
+device:
+
+             +--------------+-----------------+------------+
+             |    Device    |  Bank and Word  |    Value   |
+             +--------------+-----------------+------------+
+             | i.MX6 Series |  bank 0 word 6  | 0x00000002 |
+             +--------------+-----------------+------------+
+             | i.MX7D/S     |  bank 1 word 3  | 0x02000000 |
+             +--------------+-----------------+------------+
+             | i.MX7ULP     |  bank 29 word 6 | 0x80000000 |
+             +--------------+-----------------+------------+
+
+1.8 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, using i.MX6 series as example:
+
+  => fuse prog 0 0 0x4000
+
+- Program DIR_BT_DIS, using i.MX6 series as example:
+
+  => fuse prog 0 6 0x8
+
+- Program SJC_DISABLE, using i.MX6 series as example:
+
+  => fuse prog 0 6 0x100000
+
+- JTAG_SMODE, using i.MX6 series as example:
+
+  => fuse prog 0 6 0xC00000
+
+The table below list the SRK_LOCK, DIR_BT_DIS, SJC_DISABLE, and JTAG_SMODE bank
+and word according to the i.MX device:
+
+              +--------------+---------------+------------+
+              |    Device    | Bank and Word |   Value    |
+              +--------------+---------------+------------+
+              |                  SRK_LOCK                 |
+              +-------------------------------------------+
+              | i.MX6 Series | bank 0 word 0 | 0x00004000 |
+              +--------------+---------------+------------+
+              | i.MX7D/S     | bank 0 word 0 | 0x00000200 |
+              +--------------+---------------+------------+
+              | i.MX7ULP     | bank 1 word 1 | 0x00000080 |
+              +--------------+---------------+------------+
+              |                 DIR_BT_DIS                |
+              +-------------------------------------------+
+              | i.MX6 Series | bank 0 word 6 | 0x00000008 |
+              +--------------+---------------+------------+
+              | i.MX7D/S     | bank 1 word 3 | 0x08000000 |
+              +--------------+---------------+------------+
+              | i.MX7ULP     | bank 1 word 1 | 0x00002000 |
+              +--------------+---------------+------------+
+              |                 SJC_DISABLE               |
+              +-------------------------------------------+
+              | i.MX6 Series | bank 0 word 6 | 0x00100000 |
+              +--------------+---------------+------------+
+              | i.MX7D/S     | bank 1 word 3 | 0x00200000 |
+              +--------------+---------------+------------+
+              | i.MX7ULP     | bank 1 word 1 | 0x00000020 |
+              +--------------+---------------+------------+
+              |                 JTAG_SMODE                |
+              +-------------------------------------------+
+              | i.MX6 Series | bank 0 word 6 | 0x00C00000 |
+              +--------------+---------------+------------+
+              | i.MX7D/S     | bank 1 word 3 | 0x00C00000 |
+              +--------------+---------------+------------+
+              | i.MX7ULP     | bank 1 word 1 | 0x000000C0 |
+              +--------------+---------------+------------+
+
+2. Extending the root of trust
+-------------------------------
+
+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 supports this feature and can be used to authenticate the Linux
+Kernel Image.
+
+The process of signing an additional image is similar to the U-Boot.
+The diagram below illustrate the zImage layout:
+
+            ------- +-----------------------------+ <-- *load_address
+                ^   |                             |
+                |   |                             |
+                |   |                             |
+                |   |                             |
+                |   |           zImage            |
+         Signed |   |                             |
+          Data  |   |                             |
+                |   |                             |
+                |   +-----------------------------+
+                |   |    Padding Next Boundary    |
+                |   +-----------------------------+ <-- *ivt
+                v   |     Image Vector Table      |
+            ------- +-----------------------------+ <-- *csf
+                    |                             |
+                    | Command Sequence File (CSF) |
+                    |                             |
+                    +-----------------------------+
+                    |     Padding (optional)      |
+                    +-----------------------------+
+
+2.1 Padding the image
+----------------------
+
+The zImage must be padded to the next boundary address (0x1000), for instance
+if the image size is 0x649920 it must be padded to 0x64A000.
+
+The tool objcopy can be used for padding the image.
+
+- Pad the zImage:
+
+  $ objcopy -I binary -O binary --pad-to 0x6EA000 --gap-fill=0x00 \
+	zImage zImage_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 zImage does not include an IVT this has
+to be manually created and appended to the end of the padded zImage, 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 zImage:
+
+  $ cat zImage_pad.bin ivt.bin > zImage_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
+U-Boot 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_zImage.bin
+
+- Attach the CSF binary to the end of the image:
+
+  $ cat zImage_pad_ivt.bin csf_zImage.bin > zImage_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, zImage 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 zImage 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.
diff --git a/doc/imx/hab/habv4/script_examples/genIVT.pl b/doc/imx/hab/habv4/script_examples/genIVT.pl
new file mode 100644
index 0000000000..84a4fcb16f
--- /dev/null
+++ b/doc/imx/hab/habv4/script_examples/genIVT.pl
@@ -0,0 +1,12 @@
+#! /usr/bin/perl -w
+use strict;
+open(my $out, '>:raw', 'ivt.bin') or die "Unable to open: $!";
+print $out pack("V", 0x412000D1); # Signature
+print $out pack("V", 0x80800000); # Load Address (*load_address)
+print $out pack("V", 0x0); # Reserved
+print $out pack("V", 0x0); # DCD pointer
+print $out pack("V", 0x0); # Boot Data
+print $out pack("V", 0x80EEA000); # Self Pointer (*ivt)
+print $out pack("V", 0x80EEA020); # CSF Pointer (*csf)
+print $out pack("V", 0x0); # Reserved
+close($out);