doc/imx/habv4/guides/mx6_mx7_secure_boot.txt

   1          +=======================================================+
   2          +   i.MX6, i.MX7 U-Boot Secure Boot guide using HABv4   +
   3          +=======================================================+
   4
   5 1. HABv4 secure boot process
   6 -----------------------------
   7
   8 This document describes a step-by-step procedure on how to sign and securely
   9 boot an U-Boot image for non-SPL targets. It is assumed that the reader is
  10 familiar with basic HAB concepts and with the PKI tree generation.
  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 u-boot-dtb.imx image supporting secure boot
  16 -----------------------------------------------------------
  17
  18 The U-Boot provides support to secure boot configuration and also provide
  19 access to the HAB APIs exposed by the ROM vector table, the support is
  20 enabled by selecting the CONFIG_SECURE_BOOT option.
  21
  22 When built with this configuration, the U-Boot provides extra functions for
  23 HAB, such as the HAB status logs retrievement through the hab_status command
  24 and support for extending the root of trust.
  25
  26 The U-Boot also correctly pads the final image by aligning to the next 0xC00
  27 address, so the CSF signature data generated by CST can be concatenated to
  28 image.
  29
  30 The diagram below illustrate a signed u-boot-dtb.imx image layout:
  31
  32             ------- +-----------------------------+ <-- *start
  33                 ^   |      Image Vector Table     |
  34                 |   +-----------------------------+ <-- *boot_data
  35                 |   |          Boot Data          |
  36                 |   +-----------------------------+ <-- *dcd
  37                 |   |          DCD Table          |
  38                 |   +-----------------------------+
  39          Signed |   |           Padding           |
  40           Data  |   +-----------------------------+ <-- *entry
  41                 |   |                             |
  42                 |   |                             |
  43                 |   |       u-boot-dtb.bin        |
  44                 |   |                             |
  45                 |   |                             |
  46                 |   +-----------------------------+
  47                 v   |           Padding           |
  48             ------- +-----------------------------+ <-- *csf
  49                     |                             |
  50                     | Command Sequence File (CSF) |
  51                     |                             |
  52                     +-----------------------------+
  53                     |      Padding (optional)     |
  54                     +-----------------------------+
  55
  56 1.2 Enabling the secure boot support
  57 -------------------------------------
  58
  59 The first step is to generate an U-Boot image supporting the HAB features
  60 mentioned above, this can be achieved by adding CONFIG_SECURE_BOOT to the
  61 build configuration:
  62
  63 - Defconfig:
  64
  65   CONFIG_SECURE_BOOT=y
  66
  67 - Kconfig:
  68
  69   ARM architecture -> Support i.MX HAB features
  70
  71 1.3 Creating the CSF description file
  72 --------------------------------------
  73
  74 The CSF contains all the commands that the HAB executes during the secure
  75 boot. These commands instruct the HAB on which memory areas of the image
  76 to authenticate, which keys to install, use and etc.
  77
  78 CSF examples are available under doc/imx/habv4/csf_examples/ directory.
  79
  80 A build log containing the "Authenticate Data" parameters is available after
  81 the U-Boot build, the example below is a log for mx7dsabresd_defconfig target:
  82
  83 - mkimage build log:
  84
  85   $ cat u-boot-dtb.imx.log
  86
  87   Image Type:   Freescale IMX Boot Image
  88   Image Ver:    2 (i.MX53/6/7 compatible)
  89   Mode:         DCD
  90   Data Size:    667648 Bytes = 652.00 KiB = 0.64 MiB
  91   Load Address: 877ff420
  92   Entry Point:  87800000
  93   HAB Blocks:   0x877ff400 0x00000000 0x0009ec00
  94                 ^^^^^^^^^^ ^^^^^^^^^^ ^^^^^^^^^^
  95                 |          |          |
  96                 |          |          ------- (1)
  97                 |          |
  98                 |          ------------------ (2)
  99                 |
 100                 ----------------------------- (3)
 101
 102   (1)   Size of area in file u-boot-dtb.imx to sign.
 103         This area should include the IVT, the Boot Data the DCD
 104         and the U-Boot itself.
 105   (2)   Start of area in u-boot-dtb.imx to sign.
 106   (3)   Start of area in RAM to authenticate.
 107
 108 - In "Authenticate Data" CSF command users can copy and past the output
 109   addresses:
 110
 111   Block = 0x877ff400 0x00000000 0x0009ec00 "u-boot-dtb.imx"
 112
 113 1.4 Signing the U-Boot binary
 114 ------------------------------
 115
 116 The CST tool is used for singing the U-Boot binary and generating a CSF binary,
 117 users should input the CSF description file created in the step above and
 118 should receive a CSF binary, which contains the CSF commands, SRK table,
 119 signatures and certificates.
 120
 121 - Create CSF binary file:
 122
 123   $ ./cst -i csf_uboot.txt -o csf_uboot.bin
 124
 125 - Append CSF signature to the end of U-Boot image:
 126
 127   $ cat u-boot-dtb.imx csf_uboot.bin > u-boot-signed.imx
 128
 129 The u-boot-signed.imx is the signed binary and should be flashed into the boot
 130 media.
 131
 132 - Flash signed U-Boot binary:
 133
 134   $ sudo dd if=u-boot-signed.imx of=/dev/sd<x> bs=1K seek=1 && sync
 135
 136 1.5 Programming SRK Hash
 137 -------------------------
 138
 139 As explained in AN4581[1] and in introduction_habv4.txt document the SRK Hash
 140 fuse values are generated by the srktool and should be programmed in the
 141 SoC SRK_HASH[255:0] fuses.
 142
 143 Be careful when programming these values, as this data is the basis for the
 144 root of trust. An error in SRK Hash results in a part that does not boot.
 145
 146 The U-Boot fuse tool can be used for programming eFuses on i.MX SoCs.
 147
 148 - Dump SRK Hash fuses values in host machine:
 149
 150   $ hexdump -e '/4 "0x"' -e '/4 "%X""\n"' SRK_1_2_3_4_fuse.bin
 151   0x20593752
 152   0x6ACE6962
 153   0x26E0D06C
 154   0xFC600661
 155   0x1240E88F
 156   0x1209F144
 157   0x831C8117
 158   0x1190FD4D
 159
 160 - Program SRK_HASH[255:0] fuses, using i.MX6 series as example:
 161
 162   => fuse prog 3 0 0x20593752
 163   => fuse prog 3 1 0x6ACE6962
 164   => fuse prog 3 2 0x26E0D06C
 165   => fuse prog 3 3 0xFC600661
 166   => fuse prog 3 4 0x1240E88F
 167   => fuse prog 3 5 0x1209F144
 168   => fuse prog 3 6 0x831C8117
 169   => fuse prog 3 7 0x1190FD4D
 170
 171 The table below lists the SRK_HASH bank and word according to the i.MX device:
 172
 173     +-------------------+---------------+---------------+---------------+
 174     |                   |  i.MX6 Series |    i.MX7D/S   |    i.MX7ULP   |
 175     +-------------------+---------------+---------------+---------------+
 176     | SRK_HASH[31:00]   | bank 3 word 0 | bank 6 word 0 | bank 5 word 0 |
 177     +-------------------+---------------+---------------+---------------+
 178     | SRK_HASH[63:32]   | bank 3 word 1 | bank 6 word 1 | bank 5 word 1 |
 179     +-------------------+---------------+---------------+---------------+
 180     | SRK_HASH[95:64]   | bank 3 word 2 | bank 6 word 2 | bank 5 word 2 |
 181     +-------------------+---------------+---------------+---------------+
 182     | SRK_HASH[127:96]  | bank 3 word 3 | bank 6 word 3 | bank 5 word 3 |
 183     +-------------------+---------------+---------------+---------------+
 184     | SRK_HASH[159:128] | bank 3 word 4 | bank 7 word 0 | bank 5 word 4 |
 185     +-------------------+---------------+---------------+---------------+
 186     | SRK_HASH[191:160] | bank 3 word 5 | bank 7 word 1 | bank 5 word 5 |
 187     +-------------------+---------------+---------------+---------------+
 188     | SRK_HASH[223:192] | bank 3 word 6 | bank 7 word 2 | bank 5 word 6 |
 189     +-------------------+---------------+---------------+---------------+
 190     | SRK_HASH[255:224] | bank 3 word 7 | bank 7 word 3 | bank 5 word 7 |
 191     +-------------------+---------------+---------------+---------------+
 192
 193 1.6 Verifying HAB events
 194 -------------------------
 195
 196 The next step is to verify that the signature attached to U-Boot is
 197 successfully processed without errors. HAB generates events when processing
 198 the commands if it encounters issues.
 199
 200 The hab_status U-Boot command call the hab_report_event() and hab_status()
 201 HAB API functions to verify the processor security configuration and status.
 202 This command displays any events that were generated during the process.
 203
 204 Prior to closing the device users should ensure no HAB events were found, as
 205 the example below:
 206
 207 - Verify HAB events:
 208
 209   => hab_status
 210
 211   Secure boot disabled
 212
 213   HAB Configuration: 0xf0, HAB State: 0x66
 214   No HAB Events Found!
 215
 216 1.7 Closing the device
 217 -----------------------
 218
 219 After the device successfully boots a signed image without generating any HAB
 220 events, it is safe to close the device. This is the last step in the HAB
 221 process, and is achieved by programming the SEC_CONFIG[1] fuse bit.
 222
 223 Once the fuse is programmed, the chip does not load an image that has not been
 224 signed using the correct PKI tree.
 225
 226 - Program SEC_CONFIG[1] fuse, using i.MX6 series as example:
 227
 228   => fuse prog 0 6 0x00000002
 229
 230 The table below list the SEC_CONFIG[1] bank and word according to the i.MX
 231 device:
 232
 233              +--------------+-----------------+------------+
 234              |    Device    |  Bank and Word  |    Value   |
 235              +--------------+-----------------+------------+
 236              | i.MX6 Series |  bank 0 word 6  | 0x00000002 |
 237              +--------------+-----------------+------------+
 238              | i.MX7D/S     |  bank 1 word 3  | 0x02000000 |
 239              +--------------+-----------------+------------+
 240              | i.MX7ULP     |  bank 29 word 6 | 0x80000000 |
 241              +--------------+-----------------+------------+
 242
 243 1.8 Completely secure the device
 244 ---------------------------------
 245
 246 Additional fuses can be programmed for completely secure the device, more
 247 details about these fuses and their possible impact can be found at AN4581[1].
 248
 249 - Program SRK_LOCK, using i.MX6 series as example:
 250
 251   => fuse prog 0 0 0x4000
 252
 253 - Program DIR_BT_DIS, using i.MX6 series as example:
 254
 255   => fuse prog 0 6 0x8
 256
 257 - Program SJC_DISABLE, using i.MX6 series as example:
 258
 259   => fuse prog 0 6 0x100000
 260
 261 - JTAG_SMODE, using i.MX6 series as example:
 262
 263   => fuse prog 0 6 0xC00000
 264
 265 The table below list the SRK_LOCK, DIR_BT_DIS, SJC_DISABLE, and JTAG_SMODE bank
 266 and word according to the i.MX device:
 267
 268               +--------------+---------------+------------+
 269               |    Device    | Bank and Word |   Value    |
 270               +--------------+---------------+------------+
 271               |                  SRK_LOCK                 |
 272               +-------------------------------------------+
 273               | i.MX6 Series | bank 0 word 0 | 0x00004000 |
 274               +--------------+---------------+------------+
 275               | i.MX7D/S     | bank 0 word 0 | 0x00000200 |
 276               +--------------+---------------+------------+
 277               | i.MX7ULP     | bank 1 word 1 | 0x00000080 |
 278               +--------------+---------------+------------+
 279               |                 DIR_BT_DIS                |
 280               +-------------------------------------------+
 281               | i.MX6 Series | bank 0 word 6 | 0x00000008 |
 282               +--------------+---------------+------------+
 283               | i.MX7D/S     | bank 1 word 3 | 0x08000000 |
 284               +--------------+---------------+------------+
 285               | i.MX7ULP     | bank 1 word 1 | 0x00002000 |
 286               +--------------+---------------+------------+
 287               |                 SJC_DISABLE               |
 288               +-------------------------------------------+
 289               | i.MX6 Series | bank 0 word 6 | 0x00100000 |
 290               +--------------+---------------+------------+
 291               | i.MX7D/S     | bank 1 word 3 | 0x00200000 |
 292               +--------------+---------------+------------+
 293               | i.MX7ULP     | bank 1 word 1 | 0x00000020 |
 294               +--------------+---------------+------------+
 295               |                 JTAG_SMODE                |
 296               +-------------------------------------------+
 297               | i.MX6 Series | bank 0 word 6 | 0x00C00000 |
 298               +--------------+---------------+------------+
 299               | i.MX7D/S     | bank 1 word 3 | 0x00C00000 |
 300               +--------------+---------------+------------+
 301               | i.MX7ULP     | bank 1 word 1 | 0x000000C0 |
 302               +--------------+---------------+------------+
 303
 304 2. Extending the root of trust
 305 -------------------------------
 306
 307 The High Assurance Boot (HAB) code located in the on-chip ROM provides an
 308 Application Programming Interface (API) making it possible to call back
 309 into the HAB code for authenticating additional boot images.
 310
 311 The U-Boot supports this feature and can be used to authenticate the Linux
 312 Kernel Image.
 313
 314 The process of signing an additional image is similar to the U-Boot.
 315 The diagram below illustrate the zImage layout:
 316
 317             ------- +-----------------------------+ <-- *load_address
 318                 ^   |                             |
 319                 |   |                             |
 320                 |   |                             |
 321                 |   |                             |
 322                 |   |           zImage            |
 323          Signed |   |                             |
 324           Data  |   |                             |
 325                 |   |                             |
 326                 |   +-----------------------------+
 327                 |   |    Padding Next Boundary    |
 328                 |   +-----------------------------+ <-- *ivt
 329                 v   |     Image Vector Table      |
 330             ------- +-----------------------------+ <-- *csf
 331                     |                             |
 332                     | Command Sequence File (CSF) |
 333                     |                             |
 334                     +-----------------------------+
 335                     |     Padding (optional)      |
 336                     +-----------------------------+
 337
 338 2.1 Padding the image
 339 ----------------------
 340
 341 The zImage must be padded to the next boundary address (0x1000), for instance
 342 if the image size is 0x649920 it must be padded to 0x64A000.
 343
 344 The tool objcopy can be used for padding the image.
 345
 346 - Pad the zImage:
 347
 348   $ objcopy -I binary -O binary --pad-to 0x64A000 --gap-fill=0x00 \
 349         zImage zImage_pad.bin
 350
 351 2.2 Generating Image Vector Table
 352 ----------------------------------
 353
 354 The HAB code requires an Image Vector Table (IVT) for determining the image
 355 length and the CSF location. Since zImage does not include an IVT this has
 356 to be manually created and appended to the end of the padded zImage, the
 357 script genIVT.pl in script_examples directory can be used as reference.
 358
 359 - Generate IVT:
 360
 361   $ genIVT.pl
 362
 363 Note: The load Address may change depending on the device.
 364
 365 - Append the ivt.bin at the end of the padded zImage:
 366
 367   $ cat zImage_pad.bin ivt.bin > zImage_pad_ivt.bin
 368
 369 2.3 Signing the image
 370 ----------------------
 371
 372 A CSF file has to be created to sign the image. HAB does not allow to change
 373 the SRK once the first image is authenticated, so the same SRK key used in
 374 U-Boot must be used when extending the root of trust.
 375
 376 CSF examples are available in ../csf_examples/additional_images/
 377 directory.
 378
 379 - Create CSF binary file:
 380
 381   $ ./cst --i csf_additional_images.txt --o csf_zImage.bin
 382
 383 - Attach the CSF binary to the end of the image:
 384
 385   $ cat zImage_pad_ivt.bin csf_zImage.bin > zImage_signed.bin
 386
 387 2.4 Verifying HAB events
 388 -------------------------
 389
 390 The U-Boot includes the hab_auth_img command which can be used for
 391 authenticating and troubleshooting the signed image, zImage must be
 392 loaded at the load address specified in the IVT.
 393
 394 - Authenticate additional image:
 395
 396   => hab_auth_img <Load Address> <Image Size> <IVT Offset>
 397
 398 If no HAB events were found the zImage is successfully signed.
 399
 400 References:
 401 [1] AN4581: "Secure Boot on i.MX 50, i.MX 53, i.MX 6 and i.MX 7 Series using
 402  HABv4" - Rev 2.