summaryrefslogtreecommitdiff
path: root/doc/imx/hab/habv4
diff options
context:
space:
mode:
authorBreno Matheus Lima <breno.lima@nxp.com>2018-10-10 01:10:44 +0000
committerStefano Babic <sbabic@denx.de>2018-10-22 14:22:42 +0200
commitdfe9ff9cc79b111992e7bf41ab13ff0b83bbcde9 (patch)
treeb5ce4660bd363182c013b284f0bddd429857b570 /doc/imx/hab/habv4
parent843400fd267cf465d0119cc9623edd28deb40108 (diff)
doc: imx: hab: Reorganize High Assurance Boot documentation
The current High Assurance Boot document README.mxc_hab include details for the following features in a single file: - HAB Secure Boot - HAB Encrypted Boot Split HAB documentation in a specific directory for a cleaner documentation structure, subsequent patches will include more content in HAB documentation. Signed-off-by: Breno Lima <breno.lima@nxp.com>
Diffstat (limited to 'doc/imx/hab/habv4')
-rw-r--r--doc/imx/hab/habv4/encrypted_boot.txt43
-rw-r--r--doc/imx/hab/habv4/secure_boot.txt100
2 files changed, 143 insertions, 0 deletions
diff --git a/doc/imx/hab/habv4/encrypted_boot.txt b/doc/imx/hab/habv4/encrypted_boot.txt
new file mode 100644
index 0000000000..c59d204d38
--- /dev/null
+++ b/doc/imx/hab/habv4/encrypted_boot.txt
@@ -0,0 +1,43 @@
+1. Setup U-Boot Image for Encrypted Boot
+----------------------------------------
+An authenticated U-Boot image is used as starting point for
+Encrypted Boot. The image is encrypted by i.MX Code Signing
+Tool (CST). The CST replaces only the image data of
+u-boot-dtb.imx with the encrypted data. The Initial Vector Table,
+DCD, and Boot data, remains in plaintext.
+
+The image data is encrypted with a Encryption Key (DEK).
+Therefore, this key is needed to decrypt the data during the
+booting process. The DEK is protected by wrapping it in a Blob,
+which needs to be appended to the U-Boot image and specified in
+the CSF file.
+
+The DEK blob is generated by an authenticated U-Boot image with
+the dek_blob cmd enabled. The image used for DEK blob generation
+needs to have the following configurations enabled in Kconfig:
+
+CONFIG_SECURE_BOOT=y
+CONFIG_CMD_DEKBLOB=y
+
+Note: The encrypted boot feature is only supported by HABv4 or
+greater.
+
+The dek_blob command then can be used to generate the DEK blob of
+a DEK previously loaded in memory. The command is used as follows:
+
+dek_blob <DEK address> <Output Address> <Key Size in Bits>
+example: dek_blob 0x10800000 0x10801000 192
+
+The resulting DEK blob then is used to construct the encrypted
+U-Boot image. Note that the blob needs to be transferred back
+to the host.Then the following commands are used to construct
+the final image.
+
+cat u-boot-dtb.imx csf-u-boot.bin > u-boot-signed.imx
+objcopy -I binary -O binary --pad-to <blob_dst> --gap-fill=0x00 \
+ u-boot-signed.imx u-boot-signed-pad.bin
+cat u-boot-signed-pad.imx DEK_blob.bin > u-boot-encrypted.imx
+
+ NOTE: u-boot-signed.bin needs to be padded to the value
+ equivalent to the address in which the DEK blob is specified
+ in the CSF.
diff --git a/doc/imx/hab/habv4/secure_boot.txt b/doc/imx/hab/habv4/secure_boot.txt
new file mode 100644
index 0000000000..ae68dc8040
--- /dev/null
+++ b/doc/imx/hab/habv4/secure_boot.txt
@@ -0,0 +1,100 @@
+1. High Assurance Boot (HAB) for i.MX CPUs
+------------------------------------------
+
+To enable the authenticated or encrypted boot mode of U-Boot, it is
+required to set the proper configuration for the target board. This
+is done by adding the following configuration in the defconfig file:
+
+CONFIG_SECURE_BOOT=y
+
+In addition, the U-Boot image to be programmed into the
+boot media needs to be properly constructed, i.e. it must contain a
+proper Command Sequence File (CSF).
+
+The CSF itself is generated by the i.MX High Assurance Boot Reference
+Code Signing Tool.
+https://www.nxp.com/webapp/sps/download/license.jsp?colCode=IMX_CST_TOOL
+
+More information about the CSF and HAB can be found in the AN4581.
+https://www.nxp.com/docs/en/application-note/AN4581.pdf
+
+We don't want to explain how to create a PKI tree or SRK table as
+this is well explained in the Application Note.
+
+2. Secure Boot on non-SPL targets
+---------------------------------
+
+On non-SPL targets a singe U-Boot binary is generated, mkimage will
+output additional information about "HAB Blocks" which can be used
+in the CST to authenticate the U-Boot image (entries in the CSF file).
+
+Image Type: Freescale IMX Boot Image
+Image Ver: 2 (i.MX53/6 compatible)
+Data Size: 327680 Bytes = 320.00 kB = 0.31 MB
+Load Address: 177ff420
+Entry Point: 17800000
+HAB Blocks: 0x177ff400 0x00000000 0x0004dc00
+ ^^^^^^^^^^ ^^^^^^^^^^ ^^^^^^^^^^
+ | | |
+ | | ----- (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 U-Boot itself.
+(2) Start of area in u-boot-dtb.imx to sign
+(3) Start of area in RAM to authenticate
+
+CONFIG_SECURE_BOOT currently enables only an additional command
+'hab_status' in U-Boot to retrieve the HAB status and events. This
+can be useful while developing and testing HAB.
+
+Commands to generate a signed U-Boot using i.MX HAB CST tool:
+# Compile CSF and create signature
+cst --o csf-u-boot.bin --i command_sequence_uboot.csf
+# Append compiled CSF to Binary
+cat u-boot-dtb.imx csf-u-boot.bin > u-boot-signed.imx
+
+3. Secure Boot on SPL targets
+-----------------------------
+
+This version of U-Boot is able to build a signable version of the SPL
+as well as a signable version of the U-Boot image. The signature can
+be verified through High Assurance Boot (HAB).
+
+After building, you need to create a command sequence file and use
+i.MX HAB Code Signing Tool to sign both binaries. After creation,
+the mkimage tool outputs the required information about the HAB Blocks
+parameter for the CSF. During the build, the information is preserved
+in log files named as the binaries. (SPL.log and u-boot-ivt.log).
+
+Example Output of the SPL (imximage) creation:
+ Image Type: Freescale IMX Boot Image
+ Image Ver: 2 (i.MX53/6/7 compatible)
+ Mode: DCD
+ Data Size: 61440 Bytes = 60.00 kB = 0.06 MB
+ Load Address: 00907420
+ Entry Point: 00908000
+ HAB Blocks: 0x00907400 0x00000000 0x0000cc00
+
+Example Output of the u-boot-ivt.img (firmware_ivt) creation:
+ Image Name: U-Boot 2016.11-rc1-31589-g2a4411
+ Created: Sat Nov 5 21:53:28 2016
+ Image Type: ARM U-Boot Firmware with HABv4 IVT (uncompressed)
+ Data Size: 352192 Bytes = 343.94 kB = 0.34 MB
+ Load Address: 17800000
+ Entry Point: 00000000
+ HAB Blocks: 0x177fffc0 0x0000 0x00054020
+
+# Compile CSF and create signature
+cst --o csf-u-boot.bin --i command_sequence_uboot.csf
+cst --o csf-SPL.bin --i command_sequence_spl.csf
+# Append compiled CSF to Binary
+cat SPL csf-SPL.bin > SPL-signed
+cat u-boot-ivt.img csf-u-boot.bin > u-boot-signed.img
+
+These two signed binaries can be used on an i.MX in closed
+configuration when the according SRK Table Hash has been flashed.