Home | History | Annotate | Download | only in doc
      1 1. High Assurance Boot (HAB) for i.MX CPUs
      2 ------------------------------------------
      3 
      4 To enable the authenticated or encrypted boot mode of U-Boot, it is
      5 required to set the proper configuration for the target board. This
      6 is done by adding the following configuration in the defconfig file:
      7 
      8 CONFIG_SECURE_BOOT=y
      9 
     10 In addition, the U-Boot image to be programmed into the
     11 boot media needs to be properly constructed, i.e. it must contain a
     12 proper Command Sequence File (CSF).
     13 
     14 The CSF itself is generated by the i.MX High Assurance Boot Reference
     15 Code Signing Tool.
     16 https://www.nxp.com/webapp/sps/download/license.jsp?colCode=IMX_CST_TOOL
     17 
     18 More information about the CSF and HAB can be found in the AN4581.
     19 https://www.nxp.com/docs/en/application-note/AN4581.pdf
     20 
     21 We don't want to explain how to create a PKI tree or SRK table as
     22 this is well explained in the Application Note.
     23 
     24 2. Secure Boot on non-SPL targets
     25 ---------------------------------
     26 
     27 On non-SPL targets a singe U-Boot binary is generated, mkimage will
     28 output additional information about "HAB Blocks" which can be used
     29 in the CST to authenticate the U-Boot image (entries in the CSF file).
     30 
     31 Image Type:   Freescale IMX Boot Image
     32 Image Ver:    2 (i.MX53/6 compatible)
     33 Data Size:    327680 Bytes = 320.00 kB = 0.31 MB
     34 Load Address: 177ff420
     35 Entry Point:  17800000
     36 HAB Blocks:   0x177ff400 0x00000000 0x0004dc00
     37 	      ^^^^^^^^^^ ^^^^^^^^^^ ^^^^^^^^^^
     38 		|	   |	      |
     39 		|	   |	      ----- (1)
     40 		|	   |
     41 		|	   ---------------- (2)
     42 		|
     43 		--------------------------- (3)
     44 
     45 (1)	Size of area in file u-boot-dtb.imx to sign
     46 	This area should include the IVT, the Boot Data the DCD
     47 	and U-Boot itself.
     48 (2)	Start of area in u-boot-dtb.imx to sign
     49 (3)	Start of area in RAM to authenticate
     50 
     51 CONFIG_SECURE_BOOT currently enables only an additional command
     52 'hab_status' in U-Boot to retrieve the HAB status and events. This
     53 can be useful while developing and testing HAB.
     54 
     55 Commands to generate a signed U-Boot using i.MX HAB CST tool:
     56 # Compile CSF and create signature
     57 cst --o csf-u-boot.bin --i command_sequence_uboot.csf
     58 # Append compiled CSF to Binary
     59 cat u-boot-dtb.imx csf-u-boot.bin > u-boot-signed.imx
     60 
     61 3. Secure Boot on SPL targets
     62 -----------------------------
     63 
     64 This version of U-Boot is able to build a signable version of the SPL
     65 as well as a signable version of the U-Boot image. The signature can
     66 be verified through High Assurance Boot (HAB).
     67 
     68 After building, you need to create a command sequence file and use
     69 i.MX HAB Code Signing Tool to sign both binaries. After creation,
     70 the mkimage tool outputs the required information about the HAB Blocks
     71 parameter for the CSF. During the build, the information is preserved
     72 in log files named as the binaries. (SPL.log and u-boot-ivt.log).
     73 
     74 Example Output of the SPL (imximage) creation:
     75  Image Type:   Freescale IMX Boot Image
     76  Image Ver:    2 (i.MX53/6/7 compatible)
     77  Mode:         DCD
     78  Data Size:    61440 Bytes = 60.00 kB = 0.06 MB
     79  Load Address: 00907420
     80  Entry Point:  00908000
     81  HAB Blocks:   0x00907400 0x00000000 0x0000cc00
     82 
     83 Example Output of the u-boot-ivt.img (firmware_ivt) creation:
     84  Image Name:   U-Boot 2016.11-rc1-31589-g2a4411
     85  Created:      Sat Nov  5 21:53:28 2016
     86  Image Type:   ARM U-Boot Firmware with HABv4 IVT (uncompressed)
     87  Data Size:    352192 Bytes = 343.94 kB = 0.34 MB
     88  Load Address: 17800000
     89  Entry Point:  00000000
     90  HAB Blocks:   0x177fffc0   0x0000   0x00054020
     91 
     92 # Compile CSF and create signature
     93 cst --o csf-u-boot.bin --i command_sequence_uboot.csf
     94 cst --o csf-SPL.bin --i command_sequence_spl.csf
     95 # Append compiled CSF to Binary
     96 cat SPL csf-SPL.bin > SPL-signed
     97 cat u-boot-ivt.img csf-u-boot.bin > u-boot-signed.img
     98 
     99 These two signed binaries can be used on an i.MX in closed
    100 configuration when the according SRK Table Hash has been flashed.
    101 
    102 4. Setup U-Boot Image for Encrypted Boot
    103 ----------------------------------------
    104 An authenticated U-Boot image is used as starting point for
    105 Encrypted Boot. The image is encrypted by i.MX Code Signing
    106 Tool (CST). The CST replaces only the image data of
    107 u-boot-dtb.imx with the encrypted data. The Initial Vector Table,
    108 DCD, and Boot data, remains in plaintext.
    109 
    110 The image data is encrypted with a Encryption Key (DEK).
    111 Therefore, this key is needed to decrypt the data during the
    112 booting process. The DEK is protected by wrapping it in a Blob,
    113 which needs to be appended to the U-Boot image and specified in
    114 the CSF file.
    115 
    116 The DEK blob is generated by an authenticated U-Boot image with
    117 the dek_blob cmd enabled. The image used for DEK blob generation
    118 needs to have the following configurations enabled in Kconfig:
    119 
    120 CONFIG_SECURE_BOOT=y
    121 CONFIG_CMD_DEKBLOB=y
    122 
    123 Note: The encrypted boot feature is only supported by HABv4 or
    124 greater.
    125 
    126 The dek_blob command then can be used to generate the DEK blob of
    127 a DEK previously loaded in memory. The command is used as follows:
    128 
    129 dek_blob <DEK address> <Output Address> <Key Size in Bits>
    130 example: dek_blob 0x10800000 0x10801000 192
    131 
    132 The resulting DEK blob then is used to construct the encrypted
    133 U-Boot image. Note that the blob needs to be transferred back
    134 to the host.Then the following commands are used to construct
    135 the final image.
    136 
    137 cat u-boot-dtb.imx csf-u-boot.bin > u-boot-signed.imx
    138 objcopy -I binary -O binary --pad-to <blob_dst> --gap-fill=0x00 \
    139     u-boot-signed.imx u-boot-signed-pad.bin
    140 cat u-boot-signed-pad.imx DEK_blob.bin > u-boot-encrypted.imx
    141 
    142     NOTE: u-boot-signed.bin needs to be padded to the value
    143     equivalent to the address in which the DEK blob is specified
    144     in the CSF.
    145