README.ti-secure 9.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212
  1. README on how boot images are created for secure TI devices
  2. CONFIG_TI_SECURE_DEVICE:
  3. Secure TI devices require a boot image that is authenticated by ROM
  4. code to function. Without this, even JTAG remains locked and the
  5. device is essentially useless. In order to create a valid boot image for
  6. a secure device from TI, the initial public software image must be signed
  7. and combined with various headers, certificates, and other binary images.
  8. Information on the details on the complete boot image format can be obtained
  9. from Texas Instruments. The tools used to generate boot images for secure
  10. devices are part of a secure development package (SECDEV) that can be
  11. downloaded from:
  12. http://www.ti.com/mysecuresoftware (login required)
  13. The secure development package is access controlled due to NDA and export
  14. control restrictions. Access must be requested and granted by TI before the
  15. package is viewable and downloadable. Contact TI, either online or by way
  16. of a local TI representative, to request access.
  17. Booting of U-Boot SPL
  18. =====================
  19. When CONFIG_TI_SECURE_DEVICE is set, the U-Boot SPL build process
  20. requires the presence and use of these tools in order to create a
  21. viable boot image. The build process will look for the environment
  22. variable TI_SECURE_DEV_PKG, which should be the path of the installed
  23. SECDEV package. If the TI_SECURE_DEV_PKG variable is not defined or
  24. if it is defined but doesn't point to a valid SECDEV package, a
  25. warning is issued during the build to indicate that a final secure
  26. bootable image was not created.
  27. Within the SECDEV package exists an image creation script:
  28. ${TI_SECURE_DEV_PKG}/scripts/create-boot-image.sh
  29. This is called as part of the SPL/u-boot build process. As the secure
  30. boot image formats and requirements differ between secure SOC from TI,
  31. the purpose of this script is to abstract these details as much as
  32. possible.
  33. The script is basically the only required interface to the TI SECDEV
  34. package for creating a bootable SPL image for secure TI devices.
  35. Invoking the script for AM33xx Secure Devices
  36. =============================================
  37. create-boot-image.sh \
  38. <IMAGE_FLAG> <INPUT_FILE> <OUTPUT_FILE> <SPL_LOAD_ADDR>
  39. <IMAGE_FLAG> is a value that specifies the type of the image to
  40. generate OR the action the image generation tool will take. Valid
  41. values are:
  42. SPI_X-LOADER - Generates an image for SPI flash (byte swapped)
  43. X-LOADER - Generates an image for non-XIP flash
  44. MLO - Generates an image for SD/MMC/eMMC media
  45. 2ND - Generates an image for USB, UART and Ethernet
  46. XIP_X-LOADER - Generates a single stage u-boot for NOR/QSPI XiP
  47. <INPUT_FILE> is the full path and filename of the public world boot
  48. loaderbinary file (depending on the boot media, this is usually
  49. either u-boot-spl.bin or u-boot.bin).
  50. <OUTPUT_FILE> is the full path and filename of the final secure
  51. image. The output binary images should be used in place of the standard
  52. non-secure binary images (see the platform-specific user's guides and
  53. releases notes for how the non-secure images are typically used)
  54. u-boot-spl_HS_SPI_X-LOADER - byte swapped boot image for SPI flash
  55. u-boot-spl_HS_X-LOADER - boot image for NAND or SD/MMC/eMMC rawmode
  56. u-boot-spl_HS_MLO - boot image for SD/MMC/eMMC media
  57. u-boot-spl_HS_2ND - boot image for USB, UART and Ethernet
  58. u-boot_HS_XIP_X-LOADER - boot image for NOR or QSPI Xip flash
  59. <SPL_LOAD_ADDR> is the address at which SOC ROM should load the
  60. <INPUT_FILE>
  61. Invoking the script for AM43xx Secure Devices
  62. =============================================
  63. create-boot-image.sh \
  64. <IMAGE_FLAG> <INPUT_FILE> <OUTPUT_FILE> <SPL_LOAD_ADDR>
  65. <IMAGE_FLAG> is a value that specifies the type of the image to
  66. generate OR the action the image generation tool will take. Valid
  67. values are:
  68. SPI_X-LOADER - Generates an image for SPI flash (byte
  69. swapped)
  70. XIP_X-LOADER - Generates a single stage u-boot for
  71. NOR/QSPI XiP
  72. ISSW - Generates an image for all other boot modes
  73. <INPUT_FILE> is the full path and filename of the public world boot
  74. loaderbinary file (depending on the boot media, this is usually
  75. either u-boot-spl.bin or u-boot.bin).
  76. <OUTPUT_FILE> is the full path and filename of the final secure
  77. image. The output binary images should be used in place of the standard
  78. non-secure binary images (see the platform-specific user's guides and
  79. releases notes for how the non-secure images are typically used)
  80. u-boot-spl_HS_SPI_X-LOADER - byte swapped boot image for SPI flash
  81. u-boot_HS_XIP_X-LOADER - boot image for NOR or QSPI flash
  82. u-boot-spl_HS_ISSW - boot image for all other boot media
  83. <SPL_LOAD_ADDR> is the address at which SOC ROM should load the
  84. <INPUT_FILE>
  85. Invoking the script for DRA7xx/AM57xx Secure Devices
  86. ====================================================
  87. create-boot-image.sh <IMAGE_TYPE> <INPUT_FILE> <OUTPUT_FILE>
  88. <IMAGE_TYPE> is a value that specifies the type of the image to
  89. generate OR the action the image generation tool will take. Valid
  90. values are:
  91. X-LOADER - Generates an image for NOR or QSPI boot modes
  92. MLO - Generates an image for SD/MMC/eMMC boot modes
  93. ULO - Generates an image for USB/UART peripheral boot modes
  94. Note: ULO is not yet used by the u-boot build process
  95. <INPUT_FILE> is the full path and filename of the public world boot
  96. loader binary file (for this platform, this is always u-boot-spl.bin).
  97. <OUTPUT_FILE> is the full path and filename of the final secure image.
  98. The output binary images should be used in place of the standard
  99. non-secure binary images (see the platform-specific user's guides
  100. and releases notes for how the non-secure images are typically used)
  101. u-boot-spl_HS_MLO - boot image for SD/MMC/eMMC. This image is
  102. copied to a file named MLO, which is the name that
  103. the device ROM bootloader requires for loading from
  104. the FAT partition of an SD card (same as on
  105. non-secure devices)
  106. u-boot-spl_HS_X-LOADER - boot image for all other flash memories
  107. including QSPI and NOR flash
  108. Invoking the script for Keystone2 Secure Devices
  109. =============================================
  110. create-boot-image.sh \
  111. <UNUSED> <INPUT_FILE> <OUTPUT_FILE> <UNUSED>
  112. <UNUSED> is currently ignored and reserved for future use.
  113. <INPUT_FILE> is the full path and filename of the public world boot
  114. loader binary file (only u-boot.bin is currently supported on
  115. Keystone2 devices, u-boot-spl.bin is not currently supported).
  116. <OUTPUT_FILE> is the full path and filename of the final secure image.
  117. The output binary images should be used in place of the standard
  118. non-secure binary images (see the platform-specific user's guides
  119. and releases notes for how the non-secure images are typically used)
  120. u-boot_HS_MLO - signed and encrypted boot image that can be used to
  121. boot from all media. Secure boot from SPI NOR flash is not
  122. currently supported.
  123. Booting of Primary U-Boot (u-boot.img)
  124. ======================================
  125. The SPL image is responsible for loading the next stage boot loader,
  126. which is the main u-boot image. For secure TI devices, the SPL will
  127. be authenticated, as described above, as part of the particular
  128. device's ROM boot process. In order to continue the secure boot
  129. process, the authenticated SPL must authenticate the main u-boot
  130. image that it loads.
  131. The configurations for secure TI platforms are written to make the boot
  132. process use the FIT image format for the u-boot.img (CONFIG_SPL_FRAMEWORK
  133. and CONFIG_SPL_LOAD_FIT). With these configurations the binary
  134. components that the SPL loads include a specific DTB image and u-boot
  135. image. These DTB image may be one of many available to the boot
  136. process. In order to secure these components so that they can be
  137. authenticated by the SPL as they are loaded from the FIT image, the
  138. build procedure for secure TI devices will secure these images before
  139. they are integrated into the FIT image. When those images are extracted
  140. from the FIT image at boot time, they are post-processed to verify that
  141. they are still secure. The outlined security-related SPL post-processing
  142. is enabled through the CONFIG_SPL_FIT_IMAGE_POST_PROCESS option which
  143. must be enabled for the secure boot scheme to work. In order to allow
  144. verifying proper operation of the secure boot chain in case of successful
  145. authentication messages like "Authentication passed: CERT_U-BOOT-NOD" are
  146. output by the SPL to the console for each blob that got extracted from the
  147. FIT image. Note that the last part of this log message is the (truncated)
  148. name of the signing certificate embedded into the blob that got processed.
  149. The exact details of the how the images are secured is handled by the
  150. SECDEV package. Within the SECDEV package exists a script to process
  151. an input binary image:
  152. ${TI_SECURE_DEV_PKG}/scripts/secure-binary-image.sh
  153. This is called as part of the u-boot build process. As the secure
  154. image formats and requirements can differ between the various secure
  155. SOCs from TI, this script in the SECDEV package abstracts these
  156. details. This script is essentially the only required interface to the
  157. TI SECDEV package for creating a u-boot.img image for secure TI
  158. devices.
  159. The SPL/u-boot code contains calls to dedicated secure ROM functions
  160. to perform the validation on the secured images. The details of the
  161. interface to those functions is shown in the code. The summary
  162. is that they are accessed by invoking an ARM secure monitor call to
  163. the device's secure ROM (fixed read-only-memory that is secure and
  164. only accessible when the ARM core is operating in the secure mode).
  165. Invoking the secure-binary-image script for Secure Devices
  166. ==========================================================
  167. secure-binary-image.sh <INPUT_FILE> <OUTPUT_FILE>
  168. <INPUT_FILE> is the full path and filename of the input binary image
  169. <OUTPUT_FILE> is the full path and filename of the output secure image.