MLK-20061-1: doc: imx: habv4: Add Encrypted Boot documentation for i.MX 6 and i.MX 7 family devices

Add useful documentation for encrypted boot:
- Add 2 CSF examples for encrypt and sign
- How to encrypt and sign a U-Boot binary on closed device
- Why and how increase the PRIBLOB bitfield from CAAM SCFGR

Signed-off-by: Clement Le Marquis <clement.lemarquis@nxp.com>

3 files changed, 381 insertions, 0 deletions

diff --git a/doc/imx/hab/habv4/csf_examples/mx6_mx7/csf_u-boot_enc.txt b/doc/imx/hab/habv4/csf_examples/mx6_mx7/csf_u-boot_enc.txt
new file mode 100644
index 0000000000..96083a6a58
--- /dev/null
+++ b/doc/imx/hab/habv4/csf_examples/mx6_mx7/csf_u-boot_enc.txt
@@ -0,0 +1,50 @@
+[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
+    # This Authenticate Data command covers the IVT and DCD Data
+    # The image file referenced will remain unmodified by CST
+    Blocks = 0x877ff400 0x000 0xc00 "u-boot-dtb.imx"
+
+[Install Secret Key]
+    # Install the blob
+    Verification Index = 0
+    Target Index = 0
+    Key = "dek.bin"
+    Key Length = 128
+    # Start address + padding 0x2000 + length
+    Blob Address = 0x878a0000
+
+[Decrypt Data]
+    # The decrypt data command below causes CST to modify the input
+    # file and encrypt the specified block of data. This image file
+    # is a copy of the file used for the authentication command above
+    Verification Index = 0
+    Mac Bytes = 16
+    Blocks = 0x87800000 0x00000c00 0x9e000 "u-boot-dtb.imx-enc"
diff --git a/doc/imx/hab/habv4/csf_examples/mx6_mx7/csf_u-boot_sign_enc.txt b/doc/imx/hab/habv4/csf_examples/mx6_mx7/csf_u-boot_sign_enc.txt
new file mode 100644
index 0000000000..7e508020af
--- /dev/null
+++ b/doc/imx/hab/habv4/csf_examples/mx6_mx7/csf_u-boot_sign_enc.txt
@@ -0,0 +1,53 @@
+[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]
+    # This Authenticate Data commandcovers both clear and encrypted data.
+    # The image file referenced will remain unmodified by CST.
+    # Key slot index used to authenticate the image data
+    Verification index = 2
+    # Authenticate Start Address, Offset, Length and file
+    Blocks = 0x877ff400 0x000 0x0009ec00 "u-boot-dtb.imx-enc"
+
+[Install Secret Key]
+    # Install the blob - This will manage a new key that will not be used in
+    # the final image, so the file name has to be different
+    Verification Index = 0
+    Target Index = 0
+    Key = "dek-dummy.bin"
+    Key Length = 128
+    # Start address + padding 0x2000 + length
+    Blob Address = 0x878a000
+
+[Decrypt Data]
+    # The decrypt Data command is a place holder to ensure the
+    # CSF includes the decrypt data command from the first pass.
+    # The file that CST will encrypt will not be used, so the file
+    # name has to be different.
+    Verification Index = 0
+    Mac Bytes = 16
+    Blocks = 0x87800000 0x00000c00 0x9e000 "u-boot-dtb.imx-dummy"
diff --git a/doc/imx/hab/habv4/guides/mx6_mx7_encrypted_boot.txt b/doc/imx/hab/habv4/guides/mx6_mx7_encrypted_boot.txt
new file mode 100644
index 0000000000..d3f71b0a45
--- /dev/null
+++ b/doc/imx/hab/habv4/guides/mx6_mx7_encrypted_boot.txt
@@ -0,0 +1,278 @@
++==========================================================+
++   i.MX6, i.MX7 U-Boot Encrypted Boot guide using HABv4   +
++==========================================================+
+
+1. HABv4 Encrypted Boot process
+-------------------------------
+
+This document describes a step-by-step procedure on how to encrypt and
+sign an U-Boot image. It is assumed that the reader is familiar
+with basic HAB concepts and has already followed the mx6_mx7_secure_boot.txt
+guide and got a working closed device.
+
+Details about HAB and encrypted boot process can be found in application
+notes AN4581[1] and AN12056[2] and in the introduction_habv4.txt document.
+
+Before continuing, be sure to have fatwrite and dek_blob commands
+available in U-Boot. If not, enable them in Kconfig and rebuild
+U-Boot:
+
+- Defconfig
+
+  CONFIG_FAT_WRITE=y
+  CONFIG_CMD_DEKBLOB=y
+  CONFIG_CDM_PRIBLOB=y
+
+- Kconfig
+
+  File systems -> Enable FAT filesystem support-> Enable FAT filesystem
+  write support
+  ARM architecture -> Support the 'dek_blob' command
+  ARM architecture -> Support the set_priblob_bitfield command
+
+1.1 Building an encrypted U-Boot image
+--------------------------------------
+
+This U-Boot is built the same way the one from the secure document is,
+so it provides the same access the the HAB APIs, extra functions
+for HAB, etc...
+
+However, the layout of the new image is different, as a part of it is
+encrypted, and a DEK blob is appended at the end. The diagram below
+illustrates an encrypted u-boot-dtb.imx image layout:
+
+  ----------------------- +-----------------------------+ <--- *start
+         ^            ^   |      Image Vector Table     |
+         |            |   +-----------------------------+ <--- *boot_data
+         |            |   |          Boot Data          |
+         |      Plain |   +-----------------------------+ <--- *dcd
+         |       text |   |          DCD Table          |
+         |            |   +-----------------------------+
+  Signed |            v   |           Padding           |
+   data  |        ------- +-----------------------------+ <--- *entry
+         |            ^   |                             |
+         |            |   |                             |
+         |  Encrypted |   |        u-boot-dtb.bin       |
+         |       data |   |                             |
+         |            |   |                             |
+         |            |   +-----------------------------+
+         v            v   |           Padding           |
+  ----------------------- +-----------------------------+ <--- *csf
+                      ^   |    Command Sequence File    |
+               0x2000 |   |   (commands + SRK table +   |
+           (in bytes) |   | signatures + certificates + |
+                      v   |        Nonce + MAC)         |
+                  ------- +-----------------------------+
+                          |           Padding           |
+                          +-----------------------------+ <--- *csf + 0x2000
+                          |           DEK Blob          |
+                          +-----------------------------+
+                          |           Padding           |
+                          +-----------------------------+
+
+1.2 Get a secure boot working
+-----------------------------
+
+You need to go through all the steps described into the
+mx6_mx7_secure_boot.txt guide, and get a signed U-Boot which can
+boot successfully on a closed target. Otherwise, the following
+steps will not work.
+
+1.3 Compile the CST to enable the encrypting feature
+----------------------------------------------------
+
+The encrypting feature is not enabled by default. You need to
+execute the following commands to enable it:
+
+  $ sudo apt-get install libssl-dev openssl
+  $ cd <CST install directory>/code/back_end/src
+  $ gcc -o cst_encrypted -I ../hdr -L ../../../linux64/lib *.c
+    -lfrontend -lcrypto
+  $ cp cst_encrypted ../../../<where your original CST executable is>
+
+1.4 Creating the CSF description files
+--------------------------------------
+
+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, etc...
+
+CSF examples for encrypted boot are available under
+doc/imx/hab/habv4/csf_examples/ directory.
+
+For both CSF, first part is same compared to the CSF used for
+the secure boot step.
+Here we describe how to encrypt the U-Boot image and then sign it.
+
+1.4.1 csf_u-boot_enc.txt
+-------------------------
+
+This first CSF is used to encrypt the U-Boot image and generate the
+dek.bin file. The Authenticate Data command has to be modified, and
+two new commands have to be added:
+
+- Modify the Authenticate Data command to only cover IVT and DCD:
+
+  Blocks = 0x877ff400 0x00000000 0x00000c00 "u-boot-dtb.imx"
+
+- Add the new Install Secret Key command to generate the dek.bin
+  file and install the blob. The parameter which depends of your
+  configuration is the Blob Address. Padding of 0x2000 is
+  recommended. Following the csf_uboot.txt data for instance:
+
+  Blob Address = Authenticate Start Address + Padding + length
+               = 0x877ff400 + 0x2000 + 0x9ec00 = 0x878a0000
+
+- Add the new Decrypt Data command to encrypt the file. As the file
+  specified in parameter will be modified, we suggest to copy it.
+  Then modify the Blocks command depending of your U-Boot image.
+  In our example:
+
+  $ cp u-boot-dtb.imx u-boot-dtb.imx-enc
+  Block = (Authenticate start addr + 0xc00) 0xc00 (length - 0xc00)
+          u-boot-dtb.imx-enc
+        = (0x877ff400 + 0xc00) 0xc00 (0x9ec00 - 0xc00)
+          u-boot-dtb.imx-enc
+        = 0x87800000 0xc00 0x9e000 u-boot-dtb.imx-enc
+
+1.4.2 csf_u-boot_sign_enc.txt
+-----------------------------
+
+This second CSF is used to sign the encrypted U-Boot image previously
+generated (u-boot-dtb.imx-enc). The Authenticate Data part has also
+to be changed, the modifications are the following:
+
+- The Authenticate Data command is same compared to the one in
+  csf_uboot.txt file, except that this time, the file parameter
+  is the file previously encrypted: u-boot-dtb.imx-enc.
+
+  Blocks = 0x877ff400 0x000 0x0009ec00 "u-boot-dtb.imx-enc"
+
+- For the two new commands, we do not want to they modify our previously
+  signed/generated files. Therefore, for the Key parameter of the
+  Install Secret Key command, the value is now dek-dummy.bin, which
+  will generate a new dek file instead of erasing the previous one.
+  About the decrypt data command, you need to copy the u-boot-dtb.imx
+  file again in a u-boot-dtb.imx-dummy file, to not replace the
+  original encrypted file with an encrypted one:
+
+  Key = "dek-dummy.bin"
+  Blocks = 0x87800000 0x00000c00 0x9e000 "u-boot-dtb.imx-dummy"
+
+1.5 Encrypt the U-Boot image
+----------------------------
+
+The image is encrypted using the Code Signing Tool. It generates also
+a CSF binary and a dek.bin file, which will be used on the future
+steps below.
+
+- Create the CSF binary file and encrypt the U-Boot image
+
+  $ ./cst_encrypted -i csf_u-boot_enc.txt -o csf_u-boot_enc.bin
+
+1.6 Sign the encrypted U-Boot image
+-----------------------------------
+
+The image is then signed using the Code Signing Tool. It also
+generate a CSF binary, which will be used on the future steps below.
+
+- Create the CSF binary file and sign the encrypted U-Boot image
+
+  $ ./cst_encrypted -i csf_u-boot_sign_enc.txt -o csf_u-boot_sign_enc.bin
+
+1.7 Swap Nonce/MAC from csf_u-boot_enc.bin to csf_u-boot_sign_enc.bin
+---------------------------------------------------------------------
+
+First, calculate Nonce/MAC size based on MAC bytes value
+in CSF. As Mac bytes is 16:
+
+  Nonce/MAC size = Nonce size + MAC bytes + CSF header for Nonce/Mac
+                 = 12 + 16 + 8 = 36 bytes
+
+Then, calculate Nonce/MAC offset in CSF:
+
+  MAC offset = csf_u-boot-enc.bin size - Nonce/MAC size
+             = 3972 - 36 = 3936 Bytes
+
+In the next step, extract Nonce/NAC from the first CSF:
+
+  $ dd if=csf_u-boot_enc.bin of=noncemac.bin bs=1 skip=3936 count=36
+
+Finally, replace the MAC of csf_u-boot_sign_enc.bin with the extracted
+one:
+
+  $ dd if=noncemac.bin of=csf_u-boot_sign_enc.bin bs=1 seek=3936 count=36
+
+1.8 Generate encryptedu-boot with no dek
+----------------------------------------
+
+As described in the layout in the first part of this document, the
+final image is composed of these different parts padded to known
+values, to make it compliant with the CSF.
+
+First, pad the CSF to 0x2000:
+
+  $ objcopy -I binary -O binary --pad-to 0x2000 --gap-fill=0xff
+  csf_u-boot_sign_enc.bin csf_u-boot_sign_enc_padded.bin
+
+Then, append this file to the encrypted U-Boot image:
+
+  $ cat u-boot-dtb.imx-enc csf_u-boot_sign_enc_padded.bin >
+  u-boot_encrypted_no_dek.bin
+
+Pad this new file to width+offset (0x9ec00 + 0x2000 = 0xa0c00):
+
+  $ objcopy -I binary -O binary --pad-to 0xa0c00 --gap-fill=0x00
+  u-boot_encrypted_no_dek.bin u-boot_encrypted_no_dek_padded.bin
+
+1.9 Generate the DEK Blob
+-------------------------
+The missing part to get our final U-Boot encrypted image is a DEK
+blob. To generate it, copy the dek.bin file generated at step 1.5
+on the Boot partition of your SD Card. Then interrupt the boot
+and your chip. You need the fatwrite and dek_blob command, which
+should be enabled by the secure boot. If not, you have to enable
+them in Kconfig and recompile U-Boot
+
+Run the following commands:
+
+  => mmc list
+  FSL_SDHC: 0 (SD)   #index to use for mmc in following commands
+  => fatload mmc 0 0x80800000 dek.bin
+  => dek_blob 0x80800000 0x80801000 128
+  => fatwrite mmc 0 0x80801000 dek_blob.bin 0x48
+
+1.10 Finalize the encrypted U-Boot image
+----------------------------------------
+
+Finally, copy the generated dek_blob.bin file from your SDCard to
+your CST repository. Append it with the last padded file to get your
+final image:
+
+  $ cat u-boot_encrypted_no_dek_padded.bin dek_blob.bin >
+  u-boot_encrypted.bin
+
+If the image does not boot, please verify the size of your
+U-Boot image, the length specified into CSF and the padding values.
+
+2. About the PRIBLOB bitfield from CAAM SCFGR register
+------------------------------------------------------
+
+It is highly recommended to set the PRIBLOB bitfield from the CAAM
+SCFGR register to 0x3 once your encrypted U-Boot image is completed.
+To do so, a command has been implemented in u-boot:
+
+  => set_priblob_bitfield
+
+Once this bitfield is set to 0x3, it ensures cryptographic separation
+of private blob types avoiding any modification or replacement of
+DEK blobs. Newly created blobs will be incompatible with blobs
+required to decrypt an encrypted boot image. When the HAB later
+executes the command to decrypt the DEK, an incompatible DEK blob
+will be detected and cause an error. A substitute encrypted boot image
+will not be decrypted, and will not be executed.
+
+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] AN12056: "Encrypted Boot on HABv4 and CAAM Enabled Devices" - Rev. 1