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