mx8_mx8x_encrypted_boot.txt 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293
  1. +=========================================================+
  2. + i.MX 8, i.MX 8X Encrypted Boot guide using AHAB +
  3. +=========================================================+
  4. 1. AHAB Encrypted Boot process
  5. -------------------------------
  6. This document describes a step-by-step procedure on how to encrypt and sign a
  7. bootloader image for i.MX8/8x family devices. It is assumed that the reader
  8. is familiar with basic AHAB concepts and has already closed the device,
  9. step-by-step procedure can be found in mx8_mx8x_secure_boot.txt and
  10. mx8_mx8x_spl_secure_boot.txt guides.
  11. The steps described in this document were based in i.MX8QM device, the same
  12. concept can be applied to others processors in i.MX8/8X family devices.
  13. 1.1 Understanding the encrypted image signature block
  14. ------------------------------------------------------
  15. As described in mx8_mx8x_secure_boot.txt guide a single binary is used to boot
  16. the device. The imx-mkimage tool combines all the input images in a container
  17. structure, generating a flash.bin binary.
  18. AHAB is able to decrypt image containers by calling SECO authentication
  19. functions, the image must be encrypted by CST and the resulting DEK (Data
  20. Encryption Key) must be encapsulated and included into the container signature
  21. block:
  22. +----------------------------+
  23. | | ^
  24. | | |
  25. | Container header | |
  26. | | |
  27. | | |
  28. +---+------------------------+ |
  29. | S | Signature block header | | Signed
  30. | i +------------------------+ |
  31. | g | | |
  32. | n | | |
  33. | a | SRK table | |
  34. | t | | |
  35. | u | | v
  36. | r +------------------------+
  37. | e | Signature |
  38. | +------------------------+
  39. | B | |
  40. | l | SGK Key |
  41. | o | Certificate (optional) |
  42. | c | |
  43. | k +------------------------+
  44. | | DEK Blob |
  45. +---+------------------------+
  46. 1.1.1 Understanding and generating the DEK blob
  47. ------------------------------------------------
  48. The encrypted boot image requires a DEK blob on each time AHAB is used to
  49. decrypt an image. The DEK blob is used as a security layer to wrap and store
  50. the DEK off-chip using the OTPMK which is unique per device.
  51. On i.MX8/8x devices the DEK blob is generated using the SECO API, the following
  52. funtion is available in U-Boot and can be executed through dek_blob command:
  53. - sc_seco_gen_key_blob(sc_ipc_t ipc, uint32_t id, sc_faddr_t load_addr,
  54. sc_faddr_t export_addr, uint16_t max_size)
  55. Details in API usage can be found in SCFW API guide [1].
  56. 1.2 Enabling the encrypted boot support in U-Boot
  57. --------------------------------------------------
  58. For deploying an encrypted boot image additional U-Boot tools are needed,
  59. please be sure to have the following features enabled, this can be achieved
  60. by following one of the methods below:
  61. - Defconfig:
  62. CONFIG_AHAB_BOOT=y
  63. CONFIG_CMD_DEKBLOB=y
  64. CONFIG_IMX_SECO_DEK_ENCAP=y
  65. CONFIG_FAT_WRITE=y
  66. - Kconfig:
  67. ARM architecture -> Support i.MX8 AHAB features
  68. ARM architecture -> Support the 'dek_blob' command
  69. File systems -> Enable FAT filesystem support-> Enable FAT filesystem
  70. write support
  71. 1.3 Enabling the encrypted boot support in CST
  72. -----------------------------------------------
  73. The encryption feature is not enabled by default in Code Signing tools (CST).
  74. The CST backend must be recompiled, execute the following commands to enable
  75. encryption support in CST:
  76. $ sudo apt-get install libssl-dev openssl
  77. $ cd <CST install directory>/code/back_end/src
  78. $ gcc -o cst_encrypted -I ../hdr -L ../../../linux64/lib *.c
  79. -lfrontend -lcrypto
  80. $ cp cst_encrypted ../../../linux64/bin/
  81. 1.4 Preparing the image container
  82. ----------------------------------
  83. The container generation is explained in and mx8_mx8x_secure_boot.txt and
  84. mx8_mx8x_spl_secure_boot.txt guides. This document is based in imx-mkimage
  85. flash target (2 containers in flash.bin).
  86. - Assembly flash.bin binary:
  87. $ make SOC=<SoC Name> flash
  88. The mkimage log is used during the encrypted boot procedure to create the
  89. Command Sequence File (CSF):
  90. CST: CONTAINER 0 offset: 0x400
  91. CST: CONTAINER 0: Signature Block: offset is at 0x590
  92. DONE.
  93. Note: Please copy image to offset: IVT_OFFSET + IMAGE_OFFSET
  94. 1.6 Creating the CSF description to encrypt the 2nd container
  95. --------------------------------------------------------------
  96. The csf_enc_boot_image.txt available under ahab/csf_examples/ can be used as
  97. example for encrypting the flash.bin binary, the main change is the Install
  98. Secret Key command that must be added after Authenticate Data command.
  99. [Install Secret Key]
  100. Key = "dek.bin"
  101. Key Length = 128
  102. #Key Identifier = 0x1234CAFE
  103. Image Indexes = 0xFFFFFFFE
  104. By default all images are encrypted and image indexes parameter can be used
  105. to mask the images indexes that must be encrypted, on this example only the
  106. 2nd container will be encrypted.
  107. Optionally users can provide a key identifier that must match the value
  108. provided during the blob generation, by default its value is zero.
  109. 1.7 Encrypting the 2nd container
  110. ---------------------------------
  111. The image is encrypted using the Code Signing Tool. The tool generates the
  112. encrypted image and a random dek.bin file.
  113. - Encrypt flash.bin binary:
  114. $ ./cst_encrypted -i csf_enc_boot_image.txt -o enc_flash.bin
  115. The DEK BLOB must be inserted at offset 0x7c0 (its expected size is 72 bytes)
  116. CSF Processed successfully and signed image available in enc_boot_image.bin
  117. The output log will be used in a later step to insert the DEK blob into the
  118. signature block.
  119. 1.8 Generating the DEK Blob
  120. ----------------------------
  121. The DEK must be encapsulated into a CAAM blob so it can be included into the
  122. final encrypted binary. The U-Boot provides a tool called dek_blob which is
  123. calling the SECO blob encapsulation API.
  124. Copy the dek.bin in SDCard FAT partition and run the following commands from
  125. U-Boot prompt:
  126. => mmc list
  127. FSL_SDHC: 1 (SD)
  128. FSL_SDHC: 2
  129. => fatload mmc 1:1 0x80280000 dek.bin
  130. => dek_blob 0x80280000 0x80280100 128
  131. => fatwrite mmc 1:1 0x80280100 dek_blob.bin 0x48
  132. In host PC copy the generated dek_blob.bin to the CST directory.
  133. 1.9 Assembling the encrypted image
  134. -----------------------------------
  135. The DEK blob generated in the step above have to be inserted into the container
  136. signature block.
  137. The CSF log is used to determine the DEK Blob offset:
  138. The DEK BLOB must be inserted at offset 0x7c0 (its expected size is 72 bytes)
  139. CSF Processed successfully and signed image available in enc_boot_image.bin
  140. - Insert DEK Blob into container signature block:
  141. $ dd if=dek_blob.bin of=enc_flash.bin bs=1 seek=$((0x7c0)) conv=notrunc
  142. 1.10 Flashing the encrypted boot image
  143. ---------------------------------------
  144. The same offset is used for encrypted boot images, in case booting from
  145. eMMC/SDCard the offset is 32K.
  146. - Flash encrypted image in SDCard:
  147. $ sudo dd if=enc_flash.bin of=/dev/sd<x> bs=1K seek=32 && sync
  148. 2.0 Encrypting a standalone container
  149. --------------------------------------
  150. CST is also able to encrypt additional images containers, the steps documented
  151. in this section are based in OS container but can be also applied to SPL
  152. targets and 3rd containers.
  153. 2.1 Creating the OS container
  154. ------------------------------
  155. As explained in mx8_mx8x_secure_boot.txt guide the imx-mkimage tool is used to
  156. generate an image container for OS images, the mkimage log is used during the
  157. encrypted boot procedure to create the Command Sequence File (CSF).
  158. - Creating OS container:
  159. $ make SOC=<SoC Name> flash_kernel
  160. ...
  161. CST: CONTAINER 0 offset: 0x0
  162. CST: CONTAINER 0: Signature Block: offset is at 0x110
  163. 2.2 Creating the CSF description file for standalone container
  164. ---------------------------------------------------------------
  165. The Image Indexes parameter is used to mask the images that are encrypted by
  166. CST, as a single container is used for OS images the Image Indexes command can
  167. be commented or set to 0xFFFFFFFF.
  168. [Install Secret Key]
  169. Key = "dek_os.bin"
  170. Key Length = 128
  171. #Key Identifier = 0x1234CAFE
  172. Image Indexes = 0xFFFFFFFF
  173. 2.3 Encrypting the standalone container
  174. ----------------------------------------
  175. As explained in section 1.7 the CST generates the encrypted image and a random
  176. dek.bin file.
  177. - Encrypt the standalone container:
  178. $ ./cst_encrypted -i csf_linux_img.txt -o enc_flash_os.bin
  179. The DEK BLOB must be inserted at offset 0x340 (its expected size is 72 bytes)
  180. CSF Processed successfully and signed image available in enc_flash_os.bin
  181. The output log will be used in a later step to insert the DEK blob into the
  182. signature block.
  183. 2.4 Generating the DEK Blob for standalone container
  184. ----------------------------------------------------
  185. Similar to section 1.8 the DEK must be encapsulated into a CAAM blob so it can
  186. be included into the final encrypted binary.
  187. Copy the dek_os.bin in SDCard FAT partition and run the following commands from
  188. U-Boot prompt:
  189. => mmc list
  190. FSL_SDHC: 1 (SD)
  191. FSL_SDHC: 2
  192. => fatload mmc 1:1 0x80280000 dek_os.bin
  193. => dek_blob 0x80280000 0x80280100 128
  194. => fatwrite mmc 1:1 0x80280100 dek_blob_os.bin 0x48
  195. In host PC copy the generated dek_blob_os.bin to the CST directory.
  196. 2.5 Assembling the encrypted image
  197. -----------------------------------
  198. The DEK blob generated in the step above have to be inserted into the container
  199. signature block.
  200. The CSF log is used to determine the DEK Blob offset:
  201. The DEK BLOB must be inserted at offset 0x340 (its expected size is 72 bytes)
  202. CSF Processed successfully and signed image available in enc_flash_os.bin
  203. - Insert DEK Blob into container signature block:
  204. $ dd if=dek_blob_os.bin of=enc_flash_os.bin bs=1 seek=$((0x340)) conv=notrunc
  205. 2.6 Copy encrypted image to SDCard
  206. -----------------------------------
  207. The encrypted container can be copied to SDCard FAT partition, please note
  208. that U-Boot requires signed and encrypted containers to be named as
  209. os_cntr_signed.bin.
  210. $ sudo cp enc_flash_os.bin /media/UserID/Boot\ imx8/os_cntr_signed.bin
  211. References:
  212. [1] SCFW API guide: "System Controller Firmware API Reference Guide - Rev 1.5"