doc/README.mxc_hab

   1 High Assurance Boot (HAB) for i.MX6 CPUs
   2
   3 To enable the authenticated or encrypted boot mode of U-Boot, it is
   4 required to set the proper configuration for the target board. This
   5 is done by adding the following configuration in the defconfig file:
   6
   7 CONFIG_SECURE_BOOT=y
   8
   9 In addition, the U-Boot image to be programmed into the
  10 boot media needs to be properly constructed, i.e. it must contain a
  11 proper Command Sequence File (CSF).
  12
  13 The Initial Vector Table contains a pointer to the CSF. Please see
  14 doc/README.imximage for how to prepare u-boot.imx.
  15
  16 The CSF itself is being generated by Freescale HAB tools.
  17
  18 mkimage will output additional information about "HAB Blocks"
  19 which can be used in the Freescale tooling to authenticate U-Boot
  20 (entries in the CSF file).
  21
  22 Image Type:   Freescale IMX Boot Image
  23 Image Ver:    2 (i.MX53/6 compatible)
  24 Data Size:    327680 Bytes = 320.00 kB = 0.31 MB
  25 Load Address: 177ff420
  26 Entry Point:  17800000
  27 HAB Blocks:   177ff400 00000000 0004dc00
  28               ^^^^^^^^ ^^^^^^^^ ^^^^^^^^
  29                 |       |          |
  30                 |       |          -------- (1)
  31                 |       |
  32                 |       ------------------- (2)
  33                 |
  34                 --------------------------- (3)
  35
  36 (1)     Size of area in file u-boot.imx to sign
  37         This area should include the IVT, the Boot Data the DCD
  38         and U-Boot itself.
  39 (2)     Start of area in u-boot.imx to sign
  40 (3)     Start of area in RAM to authenticate
  41
  42 CONFIG_SECURE_BOOT currently enables only an additional command
  43 'hab_status' in U-Boot to retrieve the HAB status and events. This
  44 can be useful while developing and testing HAB.
  45
  46 Commands to generate a signed U-Boot using Freescale HAB tools:
  47 cst --o U-Boot_CSF.bin < U-Boot.CSF
  48 objcopy -I binary -O binary --pad-to 0x2000 --gap-fill=0x00 \
  49         U-Boot_CSF.bin U-Boot_CSF_pad.bin
  50 cat u-boot.imx U-Boot_CSF_pad.bin > u-boot-signed.imx
  51
  52 NOTE: U-Boot_CSF.bin needs to be padded to the value specified in
  53 the imximage.cfg file.
  54
  55 Setup U-Boot Image for Encrypted Boot
  56 -------------------------------------
  57 An authenticated U-Boot image is used as starting point for
  58 Encrypted Boot. The image is encrypted by Freescale's Code
  59 Signing Tool (CST). The CST replaces only the image data of
  60 u-boot.imx with the encrypted data. The Initial Vector Table,
  61 DCD, and Boot data, remains in plaintext.
  62
  63 The image data is encrypted with a Encryption Key (DEK).
  64 Therefore, this key is needed to decrypt the data during the
  65 booting process. The DEK is protected by wrapping it in a Blob,
  66 which needs to be appended to the U-Boot image and specified in
  67 the CSF file.
  68
  69 The DEK blob is generated by an authenticated U-Boot image with
  70 the dek_blob cmd enabled. The image used for DEK blob generation
  71 needs to have the following configurations enabled:
  72
  73 CONFIG_SECURE_BOOT
  74 CONFIG_SYS_FSL_SEC_COMPAT    4 /* HAB version */
  75 CONFIG_FSL_CAAM
  76 CONFIG_CMD_DEKBLOB
  77 CONFIG_SYS_FSL_SEC_LE
  78
  79 Note: The encrypted boot feature is only supported by HABv4 or
  80 greater.
  81
  82 The dek_blob command then can be used to generate the DEK blob of
  83 a DEK previously loaded in memory. The command is used as follows:
  84
  85 dek_blob <DEK address> <Output Address> <Key Size in Bits>
  86 example: dek_blob 0x10800000 0x10801000 192
  87
  88 The resulting DEK blob then is used to construct the encrypted
  89 U-Boot image. Note that the blob needs to be transferred back
  90 to the host.Then the following commands are used to construct
  91 the final image.
  92
  93 objcopy -I binary -O binary --pad-to 0x2000 --gap-fill=0x00 \
  94     U-Boot_CSF.bin U-Boot_CSF_pad.bin
  95 cat u-boot.imx U-Boot_CSF_pad.bin > u-boot-signed.imx
  96 objcopy -I binary -O binary --pad-to <blob_dst> --gap-fill=0x00 \
  97     u-boot-signed.imx u-boot-signed-pad.bin
  98 cat u-boot-signed-pad.imx DEK_blob.bin > u-boot-encrypted.imx
  99
 100     NOTE: u-boot-signed.bin needs to be padded to the value
 101     equivalent to the address in which the DEK blob is specified
 102     in the CSF.