doc/imx/habv4/guides/mx6_mx7_spl_secure_boot.txt

   1       +===============================================================+
   2       +  i.MX6, i.MX7 U-Boot HABv4 Secure Boot guide for SPL targets  +
   3       +===============================================================+
   4
   5 1. HABv4 secure boot process
   6 -----------------------------
   7
   8 This document is an addendum of mx6_mx7_secure_boot.txt guide describing a
   9 step-by-step procedure on how to sign and securely boot an U-Boot image for
  10 SPL targets.
  11
  12 Details about HAB can be found in the application note AN4581[1] and in the
  13 introduction_habv4.txt document.
  14
  15 1.1 Building a SPL target supporting secure boot
  16 -------------------------------------------------
  17
  18 The U-Boot provides Second Program Loader (SPL) support which generates two
  19 final images, SPL and U-Boot proper. The HABv4 can be used to authenticate
  20 both binaries.
  21
  22 Out of reset the ROM code authenticates the SPL which is responsible for
  23 initializing essential features such as DDR, UART, PMIC and clock
  24 enablement. Once the DDR is available, the SPL code loads the U-Boot proper
  25 image to its specific execution address and call the HAB APIs to extend the
  26 root of trust.
  27
  28 The U-Boot provides support to secure boot configuration and also provide
  29 access to the HAB APIs exposed by the ROM vector table, the support is
  30 enabled by selecting the CONFIG_SECURE_BOOT option.
  31
  32 When built with this configuration the U-Boot correctly pads the final SPL
  33 image by aligning to the next 0xC00 address, so the CSF signature data
  34 generated by CST can be concatenated to the image.
  35
  36 The U-Boot also append an Image Vector Table (IVT) in the final U-Boot proper
  37 binary (u-boot-ivt.img) so it can be used by HAB API in a post ROM stage.
  38
  39 The diagram below illustrate a signed SPL image layout:
  40
  41             ------- +-----------------------------+ <-- *start
  42                 ^   |      Image Vector Table     |
  43                 |   +-----------------------------+ <-- *boot_data
  44                 |   |          Boot Data          |
  45                 |   +-----------------------------+
  46          Signed |   |           Padding           |
  47           Data  |   +-----------------------------+ <-- *entry
  48                 |   |                             |
  49                 |   |            SPL              |
  50                 |   |                             |
  51                 |   +-----------------------------+
  52                 v   |           Padding           |
  53             ------- +-----------------------------+ <-- *csf
  54                     |                             |
  55                     | Command Sequence File (CSF) |
  56                     |                             |
  57                     +-----------------------------+
  58                     |      Padding (optional)     |
  59                     +-----------------------------+
  60
  61 The diagram below illustrate a signed u-boot-ivt.img image layout:
  62
  63             ------- +-----------------------------+ <-- *load_address
  64                 ^   |                             |
  65                 |   |                             |
  66                 |   |         u-boot.img          |
  67          Signed |   |                             |
  68           Data  |   |                             |
  69                 |   +-----------------------------+
  70                 |   |    Padding Next Boundary    |
  71                 |   +-----------------------------+ <-- *ivt
  72                 v   |     Image Vector Table      |
  73             ------- +-----------------------------+ <-- *csf
  74                     |                             |
  75                     | Command Sequence File (CSF) |
  76                     |                             |
  77                     +-----------------------------+
  78                     |     Padding (optional)      |
  79                     +-----------------------------+
  80
  81 1.2 Enabling the secure boot support
  82 -------------------------------------
  83
  84 The first step is to generate an U-Boot image supporting the HAB features
  85 mentioned above, this can be achieved by adding CONFIG_SECURE_BOOT to the
  86 build configuration:
  87
  88 - Defconfig:
  89
  90   CONFIG_SECURE_BOOT=y
  91
  92 - Kconfig:
  93
  94   ARM architecture -> Support i.MX HAB features
  95
  96 1.3 Creating the CSF description file
  97 --------------------------------------
  98
  99 The CSF contains all the commands that the HAB executes during the secure
 100 boot. These commands instruct the HAB code on which memory areas of the image
 101 to authenticate, which keys to install, use and etc.
 102
 103 CSF examples are available under doc/imx/habv4/csf_examples/ directory.
 104
 105 Build logs containing the "Authenticate Data" parameters are available after
 106 the U-Boot build, the example below is a log for mx6sabresd_defconfig target:
 107
 108 - SPL build log:
 109
 110   $ cat SPL.log
 111   Image Type:   Freescale IMX Boot Image
 112   Image Ver:    2 (i.MX53/6/7 compatible)
 113   Mode:         DCD
 114   Data Size:    69632 Bytes = 68.00 KiB = 0.07 MiB
 115   Load Address: 00907420
 116   Entry Point:  00908000
 117   HAB Blocks:   0x00907400 0x00000000 0x0000ec00
 118
 119 - u-boot-ivt.img build log:
 120
 121   $ cat u-boot-ivt.img.log
 122   Image Name:   U-Boot 2019.01-00003-g78ee492eb3
 123   Created:      Mon Jan 14 17:58:10 2019
 124   Image Type:   ARM U-Boot Firmware with HABv4 IVT (uncompressed)
 125   Data Size:    458688 Bytes = 447.94 KiB = 0.44 MiB
 126   Load Address: 17800000
 127   Entry Point:  00000000
 128   HAB Blocks:   0x177fffc0   0x0000   0x0006e020
 129
 130 As explained in section above the SPL is first authenticated by the ROM code
 131 and the root of trust is extended to the U-Boot image, hence two CSF files are
 132 necessary to completely sign a bootloader image.
 133
 134 In "Authenticate Data" CSF command users can copy and past the output
 135 addresses, the csf_uboot.txt can be used as example:
 136
 137 - In csf_SPL.txt:
 138
 139   Block = 0x00907400 0x00000000 0x0000ec00 "SPL"
 140
 141 - In csf_uboot-ivt.txt:
 142
 143   Block = 0x177fffc0 0x0000 0x0006e020 "u-boot-ivt.img"
 144
 145 1.4 Signing the images
 146 -----------------------
 147
 148 The CST tool is used for singing the U-Boot binary and generating a CSF binary,
 149 users should input the CSF description file created in the step above and
 150 receive a CSF binary, which contains the CSF commands, SRK table, signatures
 151 and certificates.
 152
 153 - Create SPL CSF binary file:
 154
 155   $ ./cst -i csf_SPL.txt -o csf_SPL.bin
 156
 157 - Append CSF signature to the end of SPL image:
 158
 159   $ cat SPL csf_SPL.bin > SPL-signed
 160
 161 - Create U-Boot proper CSF binary file:
 162
 163   $ ./cst -i csf_uboot-ivt.txt -o csf_uboot-ivt.bin
 164
 165 - Append CSF signature to the end of U-Boot proper image:
 166
 167   $ cat u-boot-ivt.img csf_uboot-ivt.bin > u-boot-signed.img
 168
 169 The bootloader is signed and can be flashed into the boot media.
 170
 171 1.5 Closing the device
 172 -----------------------
 173
 174 The procedure for closing the device is similar as in Non-SPL targets, for a
 175 complete procedure please refer to section "1.5 Programming SRK Hash" in
 176 mx6_mx7_secure_boot.txt document available under doc/imx/habv4/guides/
 177 directory.
 178
 179 References:
 180 [1] AN4581: "Secure Boot on i.MX 50, i.MX 53, i.MX 6 and i.MX 7 Series using
 181  HABv4" - Rev 2.