1 +=========================================================+ 2 + i.MX8M U-Boot HABv4 Secure Boot guide for SPL targets + 3 +=========================================================+ 4 51. HABv4 secure boot process 6----------------------------- 7 8This document is an addendum of mx6_mx7_spl_secure_boot.txt guide describing 9a step-by-step procedure on how to sign and securely boot an U-Boot image for 10SPL targets on i.MX8M, i.MX8M Mini, i.MX8M Nano, i.MX8M Plus. 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 SPL target supporting secure boot 16------------------------------------------------- 17 18The U-Boot build for i.MX8M SoC makes use of Second Program Loader (SPL) 19support, fitImage support and custom i.MX8M specific flash.bin container. 20This leads to a generation of multiple intermediate build artifacts, the 21U-Boot SPL, U-Boot binary, DT blob. These later two artifacts are bundled 22with external ATF BL31 blob to form a fitImage. The fitImage is bundled 23with SPL and external DDR and optional HDMI PHY initialization blobs to 24form the final flash.bin container. The HABv4 can be used to authenticate 25all of the input binaries separately. 26 27Out of reset the ROM code authenticates the SPL and PHY initialization 28blobs, combination of which is responsible for initializing essential 29features such as DDR, UART, PMIC and clock enablement. Once the DDR is 30available, the SPL code loads the secondary fitImage to its specific 31address and call the HAB APIs to extend the root of trust on its 32components. 33 34The U-Boot SPL provides support to secure boot configuration and also 35provide access to the HAB APIs exposed by the ROM vector table, the 36U-Boot provides access to HAB APIs via SMC calls to ATF. The support 37is enabled by selecting the CONFIG_IMX_HAB option. 38 39When built with this configuration the U-Boot correctly pads combined 40SPL and PHY initialization blob image, called u-boot-spl-ddr.bin, by 41aligning to the next 0xC00 address, so the CSF signature data generated 42by CST can be concatenated to the image. 43 44The U-Boot also reserves space in the fitImage binary (u-boot.itb) between 45the fitImage tree and external blobs included in it, so it can be used to 46inject IVT and CST signatures used by SPL HAB calls to authenticate the 47fitImage components. 48 49The diagram below illustrate a signed SPL combined with DDR PHY 50initialization firmware blobs part of flash.bin container layout. 51This part is loaded to memory address ( CONFIG_SPL_TEXT_BASE - 0x40 ) and 52authenticated the BootROM. The reason for the offset is so that the *entry 53would be at memory address CONFIG_SPL_TEXT_BASE when BootROM executes the 54code within it: 55 56 ------- +-----------------------------+ <-- *start 57 ^ | Image Vector Table | 58 | | (0x20 bytes) | 59 | +-----------------------------+ <-- *boot_data 60 | | Boot Data | 61 | +-----------------------------+ 62 | | Padding | 63 Signed | | to 0x40 bytes from *start | 64 Data | +-----------------------------+ <-- *entry 65 | | | 66 | | SPL combined with DDR PHY | 67 | | initialization blobs | 68 | | (u-boot-spl-ddr.bin) | 69 | | | 70 | +-----------------------------+ 71 v | Padding | 72 ------- +-----------------------------+ <-- *csf 73 | | 74 | Command Sequence File (CSF) | 75 | | 76 +-----------------------------+ 77 | Padding (optional) | 78 +-----------------------------+ 79 80The diagram below illustrate a signed U-Boot binary, DT blob and external 81ATF BL31 blob combined to form fitImage part of flash.bin container layout. 82The *load_address is CONFIG_SPL_LOAD_FIT_ADDRESS, the fitImage is loaded 83including all of its embedded data, authenticated using IVT+CSF concatenated 84at the end of the fitImage at offset aligned to 4 kiB. The fitImage with 85external data is not supported. 86 87 ------- +-----------------------------+ <-- *load_address 88 ^ | | 89 | | fitImage tree | 90 | | with embedded data | 91 | | (cca. 1 MiB) | 92 Signed | | | 93 .----- Tree | +-----------------------------+ 94 | Data | | Padding to next 4k aligned | 95 | | | from *load_address | 96 | | +-----------------------------+ <-- *ivt 97 | | | Image Vector Table | 98 | v | (0x20 bytes) | 99 | ------- +-----------------------------+ <-- *csf 100 | | Command Sequence File (CSF) | 101 | | for all signed entries in | 102 '---------------->| the fitImage, tree and data | 103 | (cca 6-7 kiB) | 104 +-----------------------------+ 105 106The diagram below illustrate a combined flash.bin container layout: 107 108 +-----------------------------+ 109 | Signed SPL part | 110 +-----------------------------+ 111 | Signed fitImage part | 112 +-----------------------------+ 113 1141.2 Enabling the secure boot support 115------------------------------------- 116 117The first step is to generate an U-Boot image supporting the HAB features 118mentioned above, this can be achieved by adding CONFIG_IMX_HAB to the 119build configuration: 120 121- Defconfig: 122 123 CONFIG_IMX_HAB=y 124 125- Kconfig: 126 127 ARM architecture -> Support i.MX HAB features 128 1291.3 Signing the images 130----------------------- 131 132The CSF contains all the commands that the HAB executes during the secure 133boot. These commands instruct the HAB code on which memory areas of the image 134to authenticate, which keys to install, use and etc. 135 136CSF examples are available under doc/imx/habv4/csf_examples/ directory. 137 138CSF "Blocks" line for csf_spl.txt can be generated as follows: 139 140``` 141spl_block_base=$(printf "0x%x" $(( $(sed -n "/CONFIG_SPL_TEXT_BASE=/ s@.*=@@p" .config) - 0x40)) ) 142spl_block_size=$(printf "0x%x" $(stat -tc %s u-boot-spl-ddr.bin)) 143sed -i "/Blocks = / s@.*@ Blocks = $spl_block_base 0x0 $spl_block_size \"flash.bin\"@" csf_spl.txt 144``` 145 146The resulting line looks as follows: 147``` 148 Blocks = 0x7e0fc0 0x0 0x306f0 "flash.bin" 149``` 150 151The columns mean: 152 - CONFIG_SPL_TEXT_BASE - 0x40 -- Start address of signed data, in DRAM 153 - 0x0 -- Start address of signed data, in "flash.bin" 154 - 0x306f0 -- Length of signed data, in "flash.bin" 155 - Filename -- "flash.bin" 156 157To generate signature for the SPL part of flash.bin container, use CST: 158``` 159cst -i csf_spl.tmp -o csf_spl.bin 160``` 161 162The newly generated CST blob has to be patched into existing flash.bin 163container. Conveniently, flash.bin IVT contains physical address of the 164CSF blob. Remember, the SPL part of flash.bin container is loaded by the 165BootROM at CONFIG_SPL_TEXT_BASE - 0x40 , so the offset of CSF blob in 166the fitImage can be calculated and inserted into the flash.bin in the 167correct location as follows: 168``` 169# offset = IVT_HEADER[6 = CSF address] - CONFIG_SPL_TEXT_BASE - 0x40 170spl_csf_offset=$(xxd -s 24 -l 4 -e flash.bin | cut -d " " -f 2 | sed "s@^@0x@") 171spl_bin_offset=$(xxd -s 4 -l 4 -e flash.bin | cut -d " " -f 2 | sed "s@^@0x@") 172spl_dd_offset=$((${spl_csf_offset} - ${spl_bin_offset} + 0x40)) 173dd if=csf_spl.bin of=flash.bin bs=1 seek=${spl_dd_offset} conv=notrunc 174``` 175 176CSF "Blocks" line for csf_fit.txt can be generated as follows: 177``` 178# fitImage 179fit_block_base=$(printf "0x%x" $(sed -n "/CONFIG_SPL_LOAD_FIT_ADDRESS=/ s@.*=@@p" .config) ) 180fit_block_offset=$(printf "0x%s" $(fdtget -t x u-boot.dtb /binman/imx-boot/uboot offset)) 181fit_block_size=$(printf "0x%x" $(( ( ( $(stat -tc %s u-boot.itb) + 0x1000 - 0x1 ) & ~(0x1000 - 0x1)) + 0x20 )) ) 182sed -i "/Blocks = / s@.*@ Blocks = $fit_block_base $fit_block_offset $fit_block_size \"flash.bin\"@" csf_fit.tmp 183``` 184 185The fitImage part of flash.bin requires separate IVT. Generate the IVT and 186patch it into the correct aligned location of flash.bin as follows: 187``` 188# IVT 189ivt_ptr_base=$(printf "%08x" ${fit_block_base} | sed "s@\(..\)\(..\)\(..\)\(..\)@0x\4\3\2\1@") 190ivt_block_base=$(printf "%08x" $(( ${fit_block_base} + ${fit_block_size} - 0x20 )) | sed "s@\(..\)\(..\)\(..\)\(..\)@0x\4\3\2\1@") 191csf_block_base=$(printf "%08x" $(( ${fit_block_base} + ${fit_block_size} )) | sed "s@\(..\)\(..\)\(..\)\(..\)@0x\4\3\2\1@") 192ivt_block_offset=$((${fit_block_offset} + ${fit_block_size} - 0x20)) 193csf_block_offset=$((${ivt_block_offset} + 0x20)) 194 195echo "0xd1002041 ${ivt_block_base} 0x00000000 0x00000000 0x00000000 ${ivt_block_base} ${csf_block_base} 0x00000000" | xxd -r -p > ivt.bin 196dd if=ivt.bin of=flash.bin bs=1 seek=${ivt_block_offset} conv=notrunc 197``` 198 199To generate CSF signature for the fitImage part of flash.bin container, use CST: 200``` 201cst -i csf_fit.tmp -o csf_fit.bin 202``` 203 204Finally, patch the CSF signature into the fitImage right past the IVT: 205``` 206dd if=csf_fit.bin of=flash.bin bs=1 seek=${csf_block_offset} conv=notrunc 207``` 208 209The entire script is available in doc/imx/habv4/csf_examples/mx8m/csf.sh 210and can be used as follows to modify flash.bin to be signed 211(adjust paths as needed): 212``` 213export CST_DIR=/usr/src/cst-3.3.1/ 214export CSF_KEY=$CST_DIR/crts/CSF1_1_sha256_4096_65537_v3_usr_crt.pem 215export IMG_KEY=$CST_DIR/crts/IMG1_1_sha256_4096_65537_v3_usr_crt.pem 216export SRK_TABLE=$CST_DIR/crts/SRK_1_2_3_4_table.bin 217export PATH=$CST_DIR/linux64/bin:$PATH 218/bin/sh doc/imx/habv4/csf_examples/mx8m/csf.sh 219``` 220 2211.4 Closing the device 222----------------------- 223 224The procedure for closing the device is similar as in Non-SPL targets, for a 225complete procedure please refer to section "1.5 Programming SRK Hash" in 226mx6_mx7_secure_boot.txt document available under doc/imx/habv4/guides/ 227directory. 228 229References: 230[1] AN4581: "Secure Boot on i.MX 50, i.MX 53, i.MX 6 and i.MX 7 Series using 231 HABv4" - Rev 2. 232