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>
(cherry picked from commit 3732dddfeddd989ca1fb930972f19303e3b67756)
diff --git a/doc/imx/habv4/csf_examples/mx6_mx7/csf_u-boot_enc.txt b/doc/imx/habv4/csf_examples/mx6_mx7/csf_u-boot_enc.txt
new file mode 100644
index 0000000..96083a6a
--- /dev/null
+++ b/doc/imx/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/habv4/csf_examples/mx6_mx7/csf_u-boot_sign_enc.txt b/doc/imx/habv4/csf_examples/mx6_mx7/csf_u-boot_sign_enc.txt
new file mode 100644
index 0000000..7e50802
--- /dev/null
+++ b/doc/imx/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/habv4/guides/mx6_mx7_encrypted_boot.txt b/doc/imx/habv4/guides/mx6_mx7_encrypted_boot.txt
new file mode 100644
index 0000000..d3f71b0
--- /dev/null
+++ b/doc/imx/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
