From dfe9ff9cc79b111992e7bf41ab13ff0b83bbcde9 Mon Sep 17 00:00:00 2001 From: Breno Matheus Lima Date: Wed, 10 Oct 2018 01:10:44 +0000 Subject: 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 --- doc/imx/README.mxc_hab | 144 ----------------------------------- doc/imx/hab/habv4/encrypted_boot.txt | 43 +++++++++++ doc/imx/hab/habv4/secure_boot.txt | 100 ++++++++++++++++++++++++ 3 files changed, 143 insertions(+), 144 deletions(-) delete mode 100644 doc/imx/README.mxc_hab create mode 100644 doc/imx/hab/habv4/encrypted_boot.txt create mode 100644 doc/imx/hab/habv4/secure_boot.txt (limited to 'doc') diff --git a/doc/imx/README.mxc_hab b/doc/imx/README.mxc_hab deleted file mode 100644 index a40ebf3e84..0000000000 --- a/doc/imx/README.mxc_hab +++ /dev/null @@ -1,144 +0,0 @@ -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. - -4. 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 -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 --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/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 +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 --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. -- cgit