doc/README.mxc_hab

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 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 being generated by Freescale HAB tools.

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).

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)
		|
		--------------------------- (3)

(1)	Size of area in file u-boot.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.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 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.


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
as well as a signable version of the U-Boot image. The signature can
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
Freescales 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).

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:
 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:   00907400 00000000 0000cc00

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

The CST (Code Signing Tool) can be downloaded from NXP.
# Compile CSF and create signature
./cst --o csf-u-boot.bin < command_sequence_uboot.csf
./cst --o csf-SPL.bin < 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.MX6 in closed
configuration when the according SRK Table Hash has been flashed.

3. 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 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,
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.

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
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.