projects / oweals / u-boot.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
Merge tag 'arc-updates-for-2018.07-rc1' of git://git.denx.de/u-boot-arc
[oweals/u-boot.git] / doc / README.mxc_hab
diff --git a/doc/README.mxc_hab b/doc/README.mxc_hab
index e9340dd14cd4a6f687116712f5cee86a7513f555..a40ebf3e84bce1926482abab3a5c039b767b19e4 100644 (file)
--- a/doc/README.mxc_hab
+++ b/doc/README.mxc_hab
@@ -1,58 +1,110 @@
-High Assurance Boot (HAB) for i.MX6 CPUs
+1. High Assurance Boot (HAB) for i.MX CPUs
+------------------------------------------
 
 
-To authenticate U-Boot only by the CPU there is no code required in
-U-Boot itself. However, the U-Boot image to be programmed into the
+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).
 
 boot media needs to be properly constructed, i.e. it must contain a
 proper Command Sequence File (CSF).
 
-The Initial Vector Table contains a pointer to the CSF. Please see
-doc/README.imximage for how to prepare u-boot.imx.
+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
 
 
-The CSF itself is being generated by Freescale HAB tools.
+We don't want to explain how to create a PKI tree or SRK table as
+this is well explained in the Application Note.
 
 
-mkimage will output additional information about "HAB Blocks"
-which can be used in the Freescale tooling to authenticate U-Boot
-(entries in the CSF file).
+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
 
 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:   177ff400 00000000 0004dc00
-             ^^^^^^^^ ^^^^^^^^ ^^^^^^^^
-               |       |          |
-               |       |          -------- (1)
-               |       |
-               |       ------------------- (2)
+HAB Blocks:   0x177ff400 0x00000000 0x0004dc00
+             ^^^^^^^^^^ ^^^^^^^^^^ ^^^^^^^^^^
+               |          |          |
+               |          |          ----- (1)
+               |          |
+               |          ---------------- (2)
                |
                --------------------------- (3)
 
                |
                --------------------------- (3)
 
-(1)    Size of area in file u-boot.imx to sign
+(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.
        This area should include the IVT, the Boot Data the DCD
        and U-Boot itself.
-(2)    Start of area in u-boot.imx to sign
+(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.
 
 (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 Freescale HAB tools:
-cst --o U-Boot_CSF.bin < U-Boot.CSF
-objcopy -I binary -O binary --pad-to 0x2000 --gap-fill=0x00 \
-       U-Boot_CSF.bin U-Boot_CSF_pad.bin
-cat u-boot.imx U-Boot_CSF_pad.bin > u-boot-signed.imx
-
-NOTE: U-Boot_CSF.bin needs to be padded to the value specified in
-the imximage.cfg file.
-
-Setup U-Boot Image for Encrypted Boot
--------------------------------------
+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.
+
+4. Setup U-Boot Image for Encrypted Boot
+----------------------------------------
 An authenticated U-Boot image is used as starting point for
 An authenticated U-Boot image is used as starting point for
-Encrypted Boot. The image is encrypted by Freescale's Code
-Signing Tool (CST). The CST replaces only the image data of
-u-boot.imx with the encrypted data. The Initial Vector Table,
+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).
 DCD, and Boot data, remains in plaintext.
 
 The image data is encrypted with a Encryption Key (DEK).
@@ -63,12 +115,10 @@ 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
 
 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:
+needs to have the following configurations enabled in Kconfig:
 
 
-CONFIG_SECURE_BOOT
-CONFIG_SYS_FSL_SEC_COMPAT    4 /* HAB version */
-CONFIG_FSL_CAAM
-CONFIG_CMD_DEKBLOB
+CONFIG_SECURE_BOOT=y
+CONFIG_CMD_DEKBLOB=y
 
 Note: The encrypted boot feature is only supported by HABv4 or
 greater.
 
 Note: The encrypted boot feature is only supported by HABv4 or
 greater.
@@ -84,9 +134,7 @@ 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.
 
 to the host.Then the following commands are used to construct
 the final image.
 
-objcopy -I binary -O binary --pad-to 0x2000 --gap-fill=0x00 \
-    U-Boot_CSF.bin U-Boot_CSF_pad.bin
-cat u-boot.imx U-Boot_CSF_pad.bin > u-boot-signed.imx
+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
 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
Unnamed repository; edit this file 'description' to name the repository.