mx6_mx7_secure_boot.txt 15 KB

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