doc: mxc_hab: Update i.MX HAB documentation

The README.mxc_hab is outdated and need improvements, add the following
modifications:

- Reorganize document and remove duplicate content
- Add CST download link
- Update CST package name
- Align command lines with CST v2.3.3
- Update U-Boot binary name
- Remove CSF padding since is not documented in AN4581

Signed-off-by: Breno Lima <breno.lima@nxp.com>
This commit is contained in:
Breno Lima 2018-02-22 00:42:56 +00:00 committed by Stefano Babic
parent b887f0a68e
commit 6d7403bf72

View File

@ -11,14 +11,22 @@ In addition, the U-Boot image to be programmed into the
boot media needs to be properly constructed, i.e. it must contain a boot media needs to be properly constructed, i.e. it must contain a
proper Command Sequence File (CSF). proper Command Sequence File (CSF).
The Initial Vector Table contains a pointer to the CSF. Please see The CSF itself is generated by the i.MX High Assurance Boot Reference
doc/README.imximage for how to prepare u-boot.imx. Code Signing Tool.
https://www.nxp.com/webapp/sps/download/license.jsp?colCode=IMX_CST_TOOL
The CSF itself is being generated by Freescale HAB tools. More information about the CSF and HAB can be found in the AN4581.
https://www.nxp.com/docs/en/application-note/AN4581.pdf
mkimage will output additional information about "HAB Blocks" We don't want to explain how to create a PKI tree or SRK table as
which can be used in the Freescale tooling to authenticate U-Boot this is well explained in the Application Note.
(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 Type: Freescale IMX Boot Image
Image Ver: 2 (i.MX53/6 compatible) Image Ver: 2 (i.MX53/6 compatible)
@ -34,46 +42,35 @@ HAB Blocks: 177ff400 00000000 0004dc00
| |
--------------------------- (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 This area should include the IVT, the Boot Data the DCD
and U-Boot itself. 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 (3) Start of area in RAM to authenticate
CONFIG_SECURE_BOOT currently enables only an additional command CONFIG_SECURE_BOOT currently enables only an additional command
'hab_status' in U-Boot to retrieve the HAB status and events. This 'hab_status' in U-Boot to retrieve the HAB status and events. This
can be useful while developing and testing HAB. can be useful while developing and testing HAB.
Commands to generate a signed U-Boot using Freescale HAB tools: Commands to generate a signed U-Boot using i.MX HAB CST tool:
cst --o U-Boot_CSF.bin < U-Boot.CSF # Compile CSF and create signature
objcopy -I binary -O binary --pad-to 0x2000 --gap-fill=0x00 \ cst --o csf-u-boot.bin --i command_sequence_uboot.csf
U-Boot_CSF.bin U-Boot_CSF_pad.bin # Append compiled CSF to Binary
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
NOTE: U-Boot_CSF.bin needs to be padded to the value specified in 3. Secure Boot on SPL targets
the imximage.cfg file. -----------------------------
2. Using Secure Boot on i.MX6 machines with SPL support
-------------------------------------------------------
This version of U-Boot is able to build a signable version of the SPL 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 as well as a signable version of the U-Boot image. The signature can
be verified through High Assurance Boot (HAB). be verified through High Assurance Boot (HAB).
CONFIG_SECURE_BOOT is needed to build those two binaries.
After building, you need to create a command sequence file and use After building, you need to create a command sequence file and use
Freescales Code Signing Tool to sign both binaries. After creation, i.MX HAB Code Signing Tool to sign both binaries. After creation,
the mkimage tool outputs the required information about the HAB Blocks the mkimage tool outputs the required information about the HAB Blocks
parameter for the CSF. During the build, the information is preserved 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). in log files named as the binaries. (SPL.log and u-boot-ivt.log).
More information about the CSF and HAB can be found in the AN4581.
https://cache.freescale.com/files/32bit/doc/app_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.
Example Output of the SPL (imximage) creation: Example Output of the SPL (imximage) creation:
Image Type: Freescale IMX Boot Image Image Type: Freescale IMX Boot Image
Image Ver: 2 (i.MX53/6/7 compatible) Image Ver: 2 (i.MX53/6/7 compatible)
@ -92,23 +89,22 @@ Example Output of the u-boot-ivt.img (firmware_ivt) creation:
Entry Point: 00000000 Entry Point: 00000000
HAB Blocks: 0x177fffc0 0x0000 0x00054020 HAB Blocks: 0x177fffc0 0x0000 0x00054020
The CST (Code Signing Tool) can be downloaded from NXP.
# Compile CSF and create signature # Compile CSF and create signature
./cst --o csf-u-boot.bin < command_sequence_uboot.csf cst --o csf-u-boot.bin --i command_sequence_uboot.csf
./cst --o csf-SPL.bin < command_sequence_spl.csf cst --o csf-SPL.bin --i command_sequence_spl.csf
# Append compiled CSF to Binary # Append compiled CSF to Binary
cat SPL csf-SPL.bin > SPL-signed cat SPL csf-SPL.bin > SPL-signed
cat u-boot-ivt.img csf-u-boot.bin > u-boot-signed.img cat u-boot-ivt.img csf-u-boot.bin > u-boot-signed.img
These two signed binaries can be used on an i.MX6 in closed These two signed binaries can be used on an i.MX in closed
configuration when the according SRK Table Hash has been flashed. configuration when the according SRK Table Hash has been flashed.
3. Setup U-Boot Image for Encrypted Boot 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 Encrypted Boot. The image is encrypted by i.MX Code Signing
Signing Tool (CST). The CST replaces only the image data of Tool (CST). The CST replaces only the image data of
u-boot.imx with the encrypted data. The Initial Vector Table, u-boot-dtb.imx with the encrypted data. The Initial Vector Table,
DCD, and Boot data, remains in plaintext. DCD, and Boot data, remains in plaintext.
The image data is encrypted with a Encryption Key (DEK). The image data is encrypted with a Encryption Key (DEK).
@ -138,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 to the host.Then the following commands are used to construct
the final image. the final image.
objcopy -I binary -O binary --pad-to 0x2000 --gap-fill=0x00 \ cat u-boot-dtb.imx csf-u-boot.bin > u-boot-signed.imx
U-Boot_CSF.bin U-Boot_CSF_pad.bin
cat u-boot.imx U-Boot_CSF_pad.bin > u-boot-signed.imx
objcopy -I binary -O binary --pad-to <blob_dst> --gap-fill=0x00 \ objcopy -I binary -O binary --pad-to <blob_dst> --gap-fill=0x00 \
u-boot-signed.imx u-boot-signed-pad.bin u-boot-signed.imx u-boot-signed-pad.bin
cat u-boot-signed-pad.imx DEK_blob.bin > u-boot-encrypted.imx cat u-boot-signed-pad.imx DEK_blob.bin > u-boot-encrypted.imx