LFU-573-3 doc: imx8m: Update iMX8M secure boot and encrypted boot doc

Update the documents of iMX8M secure boot and encrypted boot to mention
the hash of FIT FDT and optional FIT FDT signature.
Add the steps for how to sign and generate FIT FDT signature.

Signed-off-by: Ye Li <ye.li@nxp.com>
Reviewed-by: Peng Fan <peng.fan@nxp.com>

Upstream-Status: Inappropriate [downstream specific]

Upstream U-Boot fixed this differently in combination with binman to
create the final bootcontainer.
Commit 6039e0edc854 ("imx: hab: Simplify the mechanism")

Backport from NXP downstream  [25fdc42caa30faa586a277162ae5373d3e2bc2be]

Signed-off-by: Max Krummenacher <max.krummenacher@toradex.com>

6 files changed, 190 insertions, 65 deletions

diff --git a/doc/imx/habv4/csf_examples/mx8m/csf_fit.txt b/doc/imx/habv4/csf_examples/mx8m/csf_fit.txt
index d9218ab431..ca91f1232a 100644
--- a/doc/imx/habv4/csf_examples/mx8m/csf_fit.txt
+++ b/doc/imx/habv4/csf_examples/mx8m/csf_fit.txt
@@ -30,7 +30,7 @@
     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"
+             0x40200000 0x05CC00 0x9AAC8 "flash.bin", \
+             0x00910000 0x0F76C8 0x09139 "flash.bin", \
+             0xFE000000 0x100804 0x4D268 "flash.bin", \
+             0x4029AAC8 0x14DA6C 0x06DCF "flash.bin"
diff --git a/doc/imx/habv4/csf_examples/mx8m/csf_fit_enc.txt b/doc/imx/habv4/csf_examples/mx8m/csf_fit_enc.txt
index be0b353084..55dcd1d6ce 100644
--- a/doc/imx/habv4/csf_examples/mx8m/csf_fit_enc.txt
+++ b/doc/imx/habv4/csf_examples/mx8m/csf_fit_enc.txt
@@ -44,6 +44,6 @@
     # is a copy of the file used for the authentication command above
     Verification Index = 0
     Mac Bytes = 16
-    Blocks = 0x40200000 0x5AC00 0xB8940 "flash-spl-fit-enc.bin", \
-             0x920000 0x113540 0xA160 "flash-spl-fit-enc.bin", \
-             0xBE000000 0x11D6A0 0x48520 "flash-spl-fit-enc.bin"
+    Blocks = 0x40200000 0x5CC00 0xB8940 "flash-spl-fit-enc.bin", \
+             0x920000 0x115540 0xA160 "flash-spl-fit-enc.bin", \
+             0xBE000000 0x11F6A0 0x48520 "flash-spl-fit-enc.bin"
diff --git a/doc/imx/habv4/csf_examples/mx8m/csf_fit_fdt.txt b/doc/imx/habv4/csf_examples/mx8m/csf_fit_fdt.txt
new file mode 100644
index 0000000000..dd88843dee
--- /dev/null
+++ b/doc/imx/habv4/csf_examples/mx8m/csf_fit_fdt.txt
@@ -0,0 +1,32 @@
+[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 = 0x401fadc0 0x57c00 0x3020 "signed-flash.bin"
diff --git a/doc/imx/habv4/csf_examples/mx8m/csf_fit_sign_enc.txt b/doc/imx/habv4/csf_examples/mx8m/csf_fit_sign_enc.txt
index 9a41c8bb40..b699b4dbf3 100644
--- a/doc/imx/habv4/csf_examples/mx8m/csf_fit_sign_enc.txt
+++ b/doc/imx/habv4/csf_examples/mx8m/csf_fit_sign_enc.txt
@@ -27,9 +27,9 @@
 [Authenticate Data]
     Verification index = 2
     Blocks = 0x401fcdc0 0x57c00 0x1020 "flash-spl-fit-enc.bin", \
-             0x40200000 0x5AC00 0xB8940 "flash-spl-fit-enc.bin", \
-             0x920000 0x113540 0xA160 "flash-spl-fit-enc.bin", \
-             0xBE000000 0x11D6A0 0x48520 "flash-spl-fit-enc.bin"
+             0x40200000 0x5CC00 0xB8940 "flash-spl-fit-enc.bin", \
+             0x920000 0x115540 0xA160 "flash-spl-fit-enc.bin", \
+             0xBE000000 0x11F6A0 0x48520 "flash-spl-fit-enc.bin"
 
 [Install Secret Key]
     # Install the blob
@@ -47,7 +47,7 @@
     # is a copy of the file used for the authentication command above
     Verification Index = 0
     Mac Bytes = 16
-    Blocks = 0x40200000 0x5AC00 0xB8940 "flash-spl-fit-enc-dummy.bin", \
-             0x920000 0x113540 0xA160 "flash-spl-fit-enc-dummy.bin", \
-             0xBE000000 0x11D6A0 0x48520 "flash-spl-fit-enc-dummy.bin"
+    Blocks = 0x40200000 0x5CC00 0xB8940 "flash-spl-fit-enc-dummy.bin", \
+             0x920000 0x115540 0xA160 "flash-spl-fit-enc-dummy.bin", \
+             0xBE000000 0x11F6A0 0x48520 "flash-spl-fit-enc-dummy.bin"
 
diff --git a/doc/imx/habv4/guides/mx8m_encrypted_boot.txt b/doc/imx/habv4/guides/mx8m_encrypted_boot.txt
index bb9b6b80f0..5a5f2bd835 100644
--- a/doc/imx/habv4/guides/mx8m_encrypted_boot.txt
+++ b/doc/imx/habv4/guides/mx8m_encrypted_boot.txt
@@ -41,19 +41,25 @@ The diagram below illustrates an encrypted flash.bin image layout:
  Signed |    ------- +-----------------------------+   |
   Data  |    Enc  ^  |        u-boot-spl.bin       |   |
         |    Data |  |              +              |   |  SPL
-        v         v  |           DDR FW            |   | Image
+        |         |  |           DDR FW            |   | Image
+        |         |  |              +              |   |
+        v         v  |       Hash of FIT FDT       |   |
   ------------------ +-----------------------------+   |
                      |      CSF - SPL + DDR FW     |   v
                      +-----------------------------+ --------
                      |           DEK Blob          |
                      +-----------------------------+
                      |           Padding           |
-             ------- +-----------------------------+ --------
-          Signed ^   |          FDT - FIT          |   ^
-           Data  |   +-----------------------------+   |
-                 v   |          IVT - FIT          |   |
-             ------- +-----------------------------+   |
-                     |          CSF - FIT          |   |
+  ------------------ +-----------------------------+ --------
+        ^ Signed ^   |          FDT - FIT          |   ^
+        |   Data |   +-----------------------------+   |
+ Signed |        v   |          IVT - FIT          |   |
+  Data  |    ------- +-----------------------------+   |
+(optional)           |          CSF - FIT          |   |
+        |            +-----------------------------+   |
+        v            |  IVT - FIT FDT (optional)   |   |
+  ------------------ +-----------------------------+   |
+                     |  CSF - FIT FDT (optional)   |   |
   ------------------ +-----------------------------+   |
                 ^    |       u-boot-nodtb.bin      |   | FIT
                 |    +-----------------------------+   | Image
@@ -81,6 +87,7 @@ by following one of the methods below:
   CONFIG_CMD_DEKBLOB=y
   CONFIG_IMX_OPTEE_DEK_ENCAP=y
   CONFIG_CMD_PRIBLOB=y
+  CONFIG_IMX_SPL_FIT_FDT_SIGNATURE=y (Optional, for FIT FDT signature only)
 
 - Kconfig
 
@@ -166,7 +173,9 @@ Command Sequence File (CSF):
   Second Loader IMAGE:
    sld_header_off 	0x57c00
    sld_csf_off 		0x58c20
-   sld hab block: 	0x401fcdc0 0x57c00 0x1020
+   sld hab block:   0x401fadc0 0x57c00 0x1020
+   fit-fdt csf_off     0x5ac20
+   fit-fdt hab block:  0x401fadc0 0x57c00 0x3020
 
 - Additional HAB information is provided by running the following command:
 
@@ -176,10 +185,10 @@ Command Sequence File (CSF):
   ./../scripts/pad_image.sh u-boot-nodtb.bin fsl-imx8mm-evk.dtb
   TEE_LOAD_ADDR=0xbe000000 ATF_LOAD_ADDR=0x00920000 VERSION=v1 \
   ./print_fit_hab.sh 0x60000 fsl-imx8mm-evk.dtb
-  0x40200000 0x5AC00 0xB0318
-  0x402B0318 0x10AF18 0x8628
-  0x920000 0x113540 0xA160
-  0xBE000000 0x11D6A0 0x48520
+  0x40200000 0x5CC00 0xB0318
+  0x402B0318 0x10CF18 0x8628
+  0x920000 0x115540 0xA160
+  0xBE000000 0x11F6A0 0x48520
 
 1.6 Creating the CSF description file for SPL + DDR FW image
 -------------------------------------------------------------
@@ -332,7 +341,7 @@ file.
 
   [Authenticate Data]
     ...
-    Blocks = 0x401FCDC0 0x57C00 0x1020 "flash-spl-enc.bin"
+    Blocks = 0x401FADC0 0x57C00 0x1020 "flash-spl-enc.bin"
 
 - Add the Install Secret Key command to generate the dek_fit.bin file and
   install the blob. The Blob Address is a fixed address defined in imx-mkimage
@@ -356,10 +365,10 @@ file.
 
   imx-mkimage output:
 
-    0x40200000 0x5AC00 0xB0318 ──┬── Total length = 0xB0318 + 0x8628 = 0xB8940
-    0x402B0318 0x10AF18 0x8628 ──┘
-    0x920000 0x113540 0xA160
-    0xBE000000 0x11D6A0 0x48520
+    0x40200000 0x5CC00 0xB0318 ──┬── Total length = 0xB0318 + 0x8628 = 0xB8940
+    0x402B0318 0x10CF18 0x8628 ──┘
+    0x920000 0x115540 0xA160
+    0xBE000000 0x11F6A0 0x48520
 
   Decrypt data in csf_fit_enc.txt:
 
@@ -367,9 +376,9 @@ file.
 
   [Decrypt Data]
     ...
-    Blocks = 0x40200000 0x5AC00 0xB8940 "flash-spl-fit-enc.bin", \
-             0x920000 0x113540 0xA160 "flash-spl-fit-enc.bin", \
-             0xBE000000 0x11D6A0 0x48520 "flash-spl-fit-enc.bin"
+    Blocks = 0x40200000 0x5CC00 0xB8940 "flash-spl-fit-enc.bin", \
+             0x920000 0x115540 0xA160 "flash-spl-fit-enc.bin", \
+             0xBE000000 0x11F6A0 0x48520 "flash-spl-fit-enc.bin"
 
 1.8.2 csf_fit_sign_enc.txt
 ---------------------------
@@ -384,10 +393,10 @@ The second CSF is used to sign the encrypted FIT image previously generated
 
   [Authenticate Data]
     ...
-    Blocks = 0x401fcdc0 0x57c00 0x1020 "flash-spl-fit-enc.bin"
-	     0x40200000 0x5AC00 0xB8940 "flash-spl-fit-enc.bin", \
-             0x920000 0x113540 0xA160 "flash-spl-fit-enc.bin", \
-             0xBE000000 0x11D6A0 0x48520 "flash-spl-fit-enc.bin"
+    Blocks = 0x401fadc0 0x57c00 0x1020 "flash-spl-fit-enc.bin"
+	     0x40200000 0x5CC00 0xB8940 "flash-spl-fit-enc.bin", \
+             0x920000 0x115540 0xA160 "flash-spl-fit-enc.bin", \
+             0xBE000000 0x11F6A0 0x48520 "flash-spl-fit-enc.bin"
 
 
 - Add the Install Secret Key command to generate a dummy DEK blob file,
@@ -408,9 +417,28 @@ The second CSF is used to sign the encrypted FIT image previously generated
 
   [Decrypt Data]
     ...
-    Blocks = 0x40200000 0x5AC00 0xB8940 "flash-spl-fit-enc-dummy.bin", \
-             0x920000 0x113540 0xA160"flash-spl-fit-enc-dummy.bin", \
-             0xBE000000 0x11D6A0 0x48520 "flash-spl-fit-enc-dummy.bin"
+    Blocks = 0x40200000 0x5CC00 0xB8940 "flash-spl-fit-enc-dummy.bin", \
+             0x920000 0x115540 0xA160"flash-spl-fit-enc-dummy.bin", \
+             0xBE000000 0x11F6A0 0x48520 "flash-spl-fit-enc-dummy.bin"
+
+1.8.3 (Optional) csf_fit_fdt.txt
+---------------------------
+
+When optional FIT FDT signature is used, user needs third CSF to sign encrypted-flash.bin
+generated by 1.11.2. Because FIT FDT structure is not encrypted, so this step will not
+encrypt any data.
+
+- FIT FDT signature "Authenticate Data" addresses in flash.bin build log:
+
+  fit-fdt hab block:  0x401fadc0 0x57c00 0x3020
+
+- "Authenticate Data" command in csf_fit_fdt.txt file:
+
+  For example:
+
+  [Authenticate Data]
+    ...
+    Blocks = 0x401fadc0 0x57c00 0x3020 "encrypted-flash.bin"
 
 1.9 Encrypting and signing the FIT image
 -----------------------------------------
@@ -503,6 +531,10 @@ The CSF offsets can be obtained from the flash.bin build log:
 
   sld_csf_off 0x58c20
 
+- (Optional) FIT FDT CSF offset:
+
+  fit-fdt csf_off  0x5ac20
+
 The encrypted flash.bin image can be then assembled:
 
 - Create a flash-spl-fit-enc.bin copy:
@@ -539,7 +571,21 @@ The encrypted flash.bin image can be then assembled:
 
   $ dd if=dek_fit_blob.bin of=encrypted-flash.bin seek=$((0x165BC0)) bs=1 conv=notrunc
 
-1.11.3 Flash encrypted boot image
+1.11.3 (Optional) Create and Insert FIT FDT CSF
+-----------------------------------
+
+If FIT FDT signature is used, users need to continue sign the encrypted-flash.bin
+with csf_fit_fdt.txt CSF file
+
+- Create FIT FDT CSF binary file
+
+  $ ./cst -i csf_fit_fdt.txt -o csf_fit_fdt.bin
+
+- Insert csf_fit_fdt.bin in encrypted-flash.bin at 0x5ac20 offset:
+
+  $ dd if=csf_fit_fdt.bin of=encrypted-flash.bin seek=$((0x5ac20)) bs=1 conv=notrunc
+
+1.11.4 Flash encrypted boot image
 -----------------------------------
 
 - Flash encrypted image in SDCard:
diff --git a/doc/imx/habv4/guides/mx8m_secure_boot.txt b/doc/imx/habv4/guides/mx8m_secure_boot.txt
index dbc8bcd1d5..8a6ac62dac 100644
--- a/doc/imx/habv4/guides/mx8m_secure_boot.txt
+++ b/doc/imx/habv4/guides/mx8m_secure_boot.txt
@@ -39,17 +39,23 @@ file are covered by a digital signature.
           Signed |   +-----------------------------+   |
            Data  |   |        u-boot-spl.bin       |   |
                  |   |              +              |   |  SPL
-                 v   |           DDR FW            |   | Image
+                 |   |           DDR FW            |   | Image
+                 |   |              +              |   |
+                 v   |      Hash of FIT FDT        |   |
              ------- +-----------------------------+   |
                      |      CSF - SPL + DDR FW     |   v
                      +-----------------------------+ --------
                      |           Padding           |
-             ------- +-----------------------------+ --------
-          Signed ^   |          FDT - FIT          |   ^
-           Data  |   +-----------------------------+   |
-                 v   |          IVT - FIT          |   |
-             ------- +-----------------------------+   |
-                     |          CSF - FIT          |   |
+   ----------------- +-----------------------------+ --------
+        ^ Signed ^   |          FDT - FIT          |   ^
+        |  Data  |   +-----------------------------+   |
+        |        v   |          IVT - FIT          |   |
+ Signed |     -------+-----------------------------+   |
+  Data  |            |          CSF - FIT          |   |
+(optional)           +-----------------------------+   |
+        v            |  IVT - FIT FDT (optional)   |   |
+   ----------------- +-----------------------------+   |
+                     |  CSF - FIT FDT (optional)   |   |
              ------- +-----------------------------+   |  FIT
                  ^   |       u-boot-nodtb.bin      |   | Image
                  |   +-----------------------------+   |
@@ -124,6 +130,17 @@ to extend the root of trust, authenticating the U-Boot, ARM trusted firmware
 The root of trust can be extended again at U-Boot level to authenticate Kernel
 and M4 images.
 
+Note:
+FIT uses a FDT structure to describe the images loading information. In SPL image,
+the Hash of the FIT FDT structure is appended after DDR firmware. By default,
+SPL will verify the Hash before parsing the FIT FDT structure to load images.
+It means SPL image having to bind with FIT image. Users who need to decouple SPL
+image with FIT image, for example upgrading FIT image individually, could use
+optional FIT FDT signature. The FIT FDT signature approach generates another
+signature to FIT image, see the IVT - FIT FDT (optional) and CSF - FIT FDT (optional)
+in the signed flash.bin image layout. SPL will authenticate the FIT FDT structure
+before parsing it to load images.
+
 1.2 Enabling the secure boot support in U-Boot
 -----------------------------------------------
 
@@ -138,6 +155,7 @@ configuration:
 - Defconfig:
 
   CONFIG_IMX_HAB=y
+  CONFIG_IMX_SPL_FIT_FDT_SIGNATURE=y (Optional, for FIT FDT signature only)
 
 - Kconfig:
 
@@ -204,9 +222,11 @@ parameters and CSF offsets:
    spl hab block: 	0x7e0fd0 0x1a000 0x2e600
 
   Second Loader IMAGE:
-   sld_header_off 	0x57c00
-   sld_csf_off 		0x58c20
-   sld hab block: 	0x401fcdc0 0x57c00 0x1020
+   sld_header_off  0x57c00
+   sld_csf_off        0x58c20
+   sld hab block:    0x401fadc0 0x57c00 0x1020
+   fit-fdt csf_off  0x5ac20
+   fit-fdt hab block:  0x401fadc0 0x57c00 0x3020
 
 Additional HAB information is provided by running the following command:
 
@@ -216,10 +236,10 @@ Additional HAB information is provided by running the following command:
 
   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
+  0x40200000 0x5CC00 0x9AAC8
+  0x910000 0xF76C8 0x9139
+  0xFE000000 0x100804 0x4D268
+  0x4029AAC8 0x14DA6C 0x6DCF
 
 If problems are encountered while using mkimage, please refer to the Linux
 User Guide which can be found alongside the latest Linux BSP release.
@@ -238,7 +258,7 @@ this document. Please refer to introduction_habv4.txt for keys,
 certificates, SRK table, and SRK hash generation.
 The resulting file locations should be inserted into the CSF files like this:
 
-- Insertion into both csf_spl.txt and csf_fit.txt
+- Insertion into both csf_spl.txt, csf_fit.txt, and csf_fit_fdt.txt (optional)
 
 For Example:
 
@@ -281,10 +301,10 @@ needed again for binary insertion.
 
 - FIT image "Authenticate Data" addresses in print_fit_hab build log:
 
-  0x40200000 0x5AC00 0x9AAC8
-  0x910000 0xF56C8 0x9139
-  0xFE000000 0xFE804 0x4D268
-  0x4029AAC8 0x14BA6C 0x6DCF
+  0x40200000 0x5CC00 0x9AAC8
+  0x910000 0xF76C8 0x9139
+  0xFE000000 0x100804 0x4D268
+  0x4029AAC8 0x14DA6C 0x6DCF
 
 - "Authenticate Data" command in csf_fit.txt file:
 
@@ -292,11 +312,23 @@ needed again for binary insertion.
 
   [Authenticate Data]
     ...
-    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"
+    Blocks = 0x401fadc0 0x057c00 0x1020 "flash.bin", \
+           0x40200000 0x05CC00 0x9AAC8 "flash.bin", \
+           0x00910000 0x0F76C8 0x09139 "flash.bin", \
+           0xFE000000 0x100804 0x4D268 "flash.bin", \
+           0x4029AAC8 0x14DA6C 0x06DCF "flash.bin"
+
+- (Optional) FIT FDT signature "Authenticate Data" addresses in flash.bin build log:
+
+   fit-fdt hab block:  0x401fadc0 0x57c00 0x3020
+
+- (Optional) "Authenticate Data" command in csf_fit_fdt.txt file:
+
+  For example:
+
+  [Authenticate Data]
+    ...
+    Blocks = 0x401fadc0 0x57c00 0x3020 "signed-flash.bin"
 
 1.4.1 Avoiding Kernel crash in closed devices
 ----------------------------------------------
@@ -352,6 +384,10 @@ The CSF offsets can be obtained from the flash.bin build log:
 
   sld_csf_off 0x58c20
 
+- (Optional) FIT FDT CSF offset:
+
+  fit-fdt csf_off  0x5ac20
+
 The signed flash.bin image can be then assembled:
 
 - Create a flash.bin copy:
@@ -366,6 +402,17 @@ The signed flash.bin image can be then assembled:
 
   $ dd if=csf_fit.bin of=signed_flash.bin seek=$((0x58c20)) bs=1 conv=notrunc
 
+(Optional) If FIT FDT signature is used, users need to continue sign the signed_flash.bin
+with csf_fit_fdt.txt CSF file
+
+- (Optional) Create FIT FDT CSF binary file (must after signed_flash.bin is generated):
+
+ $ ./cst -i csf_fit_fdt.txt -o csf_fit_fdt.bin
+
+- (Optional) Insert csf_fit_fdt.bin in signed_flash.bin at 0x5ac20 offset:
+
+  $ dd if=csf_fit_fdt.bin of=signed_flash.bin seek=$((0x5ac20)) bs=1 conv=notrunc
+
 - Flash signed flash.bin image:
 
   $ sudo dd if=signed_flash.bin of=/dev/sd<x> bs=1K seek=33 && sync