1 +=======================================================+ 2 + i.MX6, i.MX7 U-Boot Secure Boot guide using HABv4 + 3 +=======================================================+ 4 51. HABv4 secure boot process 6----------------------------- 7 8This document describes a step-by-step procedure on how to sign and securely 9boot an U-Boot image for non-SPL targets. It is assumed that the reader is 10familiar with basic HAB concepts and with the PKI tree generation. 11 12Details about HAB can be found in the application note AN4581[1] and in the 13introduction_habv4.txt document. 14 151.1 Building a u-boot-dtb.imx image supporting secure boot 16----------------------------------------------------------- 17 18The U-Boot provides support to secure boot configuration and also provide 19access to the HAB APIs exposed by the ROM vector table, the support is 20enabled by selecting the CONFIG_IMX_HAB option. 21 22When built with this configuration, the U-Boot provides extra functions for 23HAB, such as the HAB status logs retrievement through the hab_status command 24and support for extending the root of trust. 25 26The U-Boot also correctly pads the final image by aligning to the next 0xC00 27address, so the CSF signature data generated by CST can be concatenated to 28image. 29 30The 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 561.2 Enabling the secure boot support 57------------------------------------- 58 59The first step is to generate an U-Boot image supporting the HAB features 60mentioned above, this can be achieved by adding CONFIG_IMX_HAB to the 61build configuration: 62 63- Defconfig: 64 65 CONFIG_IMX_HAB=y 66 67- Kconfig: 68 69 ARM architecture -> Support i.MX HAB features 70 711.3 Creating the CSF description file 72-------------------------------------- 73 74The CSF contains all the commands that the HAB executes during the secure 75boot. These commands instruct the HAB on which memory areas of the image 76to authenticate, which keys to install, use and etc. 77 78CSF examples are available under doc/imx/habv4/csf_examples/ directory. 79 80A build log containing the "Authenticate Data" parameters is available after 81the 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 1131.4 Signing the U-Boot binary 114------------------------------ 115 116The CST tool is used for singing the U-Boot binary and generating a CSF binary, 117users should input the CSF description file created in the step above and 118should receive a CSF binary, which contains the CSF commands, SRK table, 119signatures 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 129The u-boot-signed.imx is the signed binary and should be flashed into the boot 130media. 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 1361.5 Programming SRK Hash 137------------------------- 138 139As explained in AN4581[1] and in introduction_habv4.txt document the SRK Hash 140fuse values are generated by the srktool and should be programmed in the 141SoC SRK_HASH[255:0] fuses. 142 143Be careful when programming these values, as this data is the basis for the 144root of trust. An error in SRK Hash results in a part that does not boot. 145 146The 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 171The 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 1931.6 Verifying HAB events 194------------------------- 195 196The next step is to verify that the signature attached to U-Boot is 197successfully processed without errors. HAB generates events when processing 198the commands if it encounters issues. 199 200The hab_status U-Boot command call the hab_report_event() and hab_status() 201HAB API functions to verify the processor security configuration and status. 202This command displays any events that were generated during the process. 203 204Prior to closing the device users should ensure no HAB events were found, as 205the 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 2161.7 Closing the device 217----------------------- 218 219After the device successfully boots a signed image without generating any HAB 220events, it is safe to close the device. This is the last step in the HAB 221process, and is achieved by programming the SEC_CONFIG[1] fuse bit. 222 223Once the fuse is programmed, the chip does not load an image that has not been 224signed 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 230The table below list the SEC_CONFIG[1] bank and word according to the i.MX 231device: 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 2431.8 Completely secure the device 244--------------------------------- 245 246Additional fuses can be programmed for completely secure the device, more 247details 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 265The table below list the SRK_LOCK, DIR_BT_DIS, SJC_DISABLE, and JTAG_SMODE bank 266and 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 3042. Extending the root of trust 305------------------------------- 306 307The High Assurance Boot (HAB) code located in the on-chip ROM provides an 308Application Programming Interface (API) making it possible to call back 309into the HAB code for authenticating additional boot images. 310 311The U-Boot supports this feature and can be used to authenticate the Linux 312Kernel Image. 313 314The process of signing an additional image is similar to the U-Boot. 315The 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 3382.1 Padding the image 339---------------------- 340 341The zImage must be padded to the next boundary address (0x1000), for instance 342if the image size is 0x649920 it must be padded to 0x64A000. 343 344The 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 3512.2 Generating Image Vector Table 352---------------------------------- 353 354The HAB code requires an Image Vector Table (IVT) for determining the image 355length and the CSF location. Since zImage does not include an IVT this has 356to be manually created and appended to the end of the padded zImage, the 357script genIVT.pl in script_examples directory can be used as reference. 358 359- Generate IVT: 360 361 $ genIVT.pl 362 363Note: 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 3692.3 Signing the image 370---------------------- 371 372A CSF file has to be created to sign the image. HAB does not allow to change 373the SRK once the first image is authenticated, so the same SRK key used in 374U-Boot must be used when extending the root of trust. 375 376CSF examples are available in ../csf_examples/additional_images/ 377directory. 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 3872.4 Verifying HAB events 388------------------------- 389 390The U-Boot includes the hab_auth_img command which can be used for 391authenticating and troubleshooting the signed image, zImage must be 392loaded 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 398If no HAB events were found the zImage is successfully signed. 399 400References: 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. 403