blob: 27c0eaa77f14f783904188785a099dbe81b0e264 [file] [log] [blame]
Daniel Allred98350f72016-05-19 19:10:41 -05001README on how boot images are created for secure TI devices
2
3CONFIG_TI_SECURE_DEVICE:
4Secure TI devices require a boot image that is authenticated by ROM
5code to function. Without this, even JTAG remains locked and the
6device is essentially useless. In order to create a valid boot image for
7a secure device from TI, the initial public software image must be signed
8and combined with various headers, certificates, and other binary images.
9
10Information on the details on the complete boot image format can be obtained
11from Texas Instruments. The tools used to generate boot images for secure
12devices are part of a secure development package (SECDEV) that can be
13downloaded from:
14
15 http://www.ti.com/mysecuresoftware (login required)
16
17The secure development package is access controlled due to NDA and export
18control restrictions. Access must be requested and granted by TI before the
19package is viewable and downloadable. Contact TI, either online or by way
20of a local TI representative, to request access.
21
Andreas Dannenberg8662bea2016-06-27 09:19:24 -050022Booting of U-Boot SPL
23=====================
Daniel Allred98350f72016-05-19 19:10:41 -050024
Andreas Dannenberg8662bea2016-06-27 09:19:24 -050025 When CONFIG_TI_SECURE_DEVICE is set, the U-Boot SPL build process
26 requires the presence and use of these tools in order to create a
27 viable boot image. The build process will look for the environment
28 variable TI_SECURE_DEV_PKG, which should be the path of the installed
29 SECDEV package. If the TI_SECURE_DEV_PKG variable is not defined or
30 if it is defined but doesn't point to a valid SECDEV package, a
31 warning is issued during the build to indicate that a final secure
32 bootable image was not created.
Daniel Allred98350f72016-05-19 19:10:41 -050033
Andreas Dannenberg8662bea2016-06-27 09:19:24 -050034 Within the SECDEV package exists an image creation script:
Daniel Allred98350f72016-05-19 19:10:41 -050035
Andreas Dannenberg8662bea2016-06-27 09:19:24 -050036 ${TI_SECURE_DEV_PKG}/scripts/create-boot-image.sh
Daniel Allred98350f72016-05-19 19:10:41 -050037
Andreas Dannenberg8662bea2016-06-27 09:19:24 -050038 This is called as part of the SPL/u-boot build process. As the secure
39 boot image formats and requirements differ between secure SOC from TI,
40 the purpose of this script is to abstract these details as much as
41 possible.
Daniel Allred98350f72016-05-19 19:10:41 -050042
Andreas Dannenberg8662bea2016-06-27 09:19:24 -050043 The script is basically the only required interface to the TI SECDEV
44 package for creating a bootable SPL image for secure TI devices.
Daniel Allred98350f72016-05-19 19:10:41 -050045
Andrew F. Davisf7160ea2016-08-30 14:06:22 -050046 Invoking the script for AM33xx Secure Devices
47 =============================================
48
49 create-boot-image.sh \
50 <IMAGE_FLAG> <INPUT_FILE> <OUTPUT_FILE> <SPL_LOAD_ADDR>
51
52 <IMAGE_FLAG> is a value that specifies the type of the image to
53 generate OR the action the image generation tool will take. Valid
54 values are:
55 SPI_X-LOADER - Generates an image for SPI flash (byte swapped)
56 X-LOADER - Generates an image for non-XIP flash
57 MLO - Generates an image for SD/MMC/eMMC media
58 2ND - Generates an image for USB, UART and Ethernet
59 XIP_X-LOADER - Generates a single stage u-boot for NOR/QSPI XiP
60
61 <INPUT_FILE> is the full path and filename of the public world boot
62 loaderbinary file (depending on the boot media, this is usually
63 either u-boot-spl.bin or u-boot.bin).
64
65 <OUTPUT_FILE> is the full path and filename of the final secure
66 image. The output binary images should be used in place of the standard
67 non-secure binary images (see the platform-specific user's guides and
68 releases notes for how the non-secure images are typically used)
69 u-boot-spl_HS_SPI_X-LOADER - byte swapped boot image for SPI flash
70 u-boot-spl_HS_X-LOADER - boot image for NAND or SD/MMC/eMMC rawmode
71 u-boot-spl_HS_MLO - boot image for SD/MMC/eMMC media
72 u-boot-spl_HS_2ND - boot image for USB, UART and Ethernet
73 u-boot_HS_XIP_X-LOADER - boot image for NOR or QSPI Xip flash
74
75 <SPL_LOAD_ADDR> is the address at which SOC ROM should load the
76 <INPUT_FILE>
77
Andreas Dannenberg8662bea2016-06-27 09:19:24 -050078 Invoking the script for AM43xx Secure Devices
79 =============================================
Daniel Allred98350f72016-05-19 19:10:41 -050080
Andreas Dannenberg8662bea2016-06-27 09:19:24 -050081 create-boot-image.sh \
82 <IMAGE_FLAG> <INPUT_FILE> <OUTPUT_FILE> <SPL_LOAD_ADDR>
Daniel Allred98350f72016-05-19 19:10:41 -050083
Andreas Dannenberg8662bea2016-06-27 09:19:24 -050084 <IMAGE_FLAG> is a value that specifies the type of the image to
85 generate OR the action the image generation tool will take. Valid
86 values are:
87 SPI_X-LOADER - Generates an image for SPI flash (byte
88 swapped)
89 XIP_X-LOADER - Generates a single stage u-boot for
90 NOR/QSPI XiP
91 ISSW - Generates an image for all other boot modes
Daniel Allred98350f72016-05-19 19:10:41 -050092
Andreas Dannenberg8662bea2016-06-27 09:19:24 -050093 <INPUT_FILE> is the full path and filename of the public world boot
94 loaderbinary file (depending on the boot media, this is usually
95 either u-boot-spl.bin or u-boot.bin).
96
97 <OUTPUT_FILE> is the full path and filename of the final secure
98 image. The output binary images should be used in place of the standard
99 non-secure binary images (see the platform-specific user's guides and
100 releases notes for how the non-secure images are typically used)
Daniel Allred98350f72016-05-19 19:10:41 -0500101 u-boot-spl_HS_SPI_X-LOADER - byte swapped boot image for SPI flash
102 u-boot_HS_XIP_X-LOADER - boot image for NOR or QSPI flash
103 u-boot-spl_HS_ISSW - boot image for all other boot media
104
Andreas Dannenberg8662bea2016-06-27 09:19:24 -0500105 <SPL_LOAD_ADDR> is the address at which SOC ROM should load the
106 <INPUT_FILE>
Daniel Allred98350f72016-05-19 19:10:41 -0500107
Andreas Dannenberg8662bea2016-06-27 09:19:24 -0500108 Invoking the script for DRA7xx/AM57xx Secure Devices
109 ====================================================
Daniel Allred98350f72016-05-19 19:10:41 -0500110
Andrew F. Daviseca61ae2019-01-28 11:43:26 -0600111 create-boot-image.sh \
112 <IMAGE_TYPE> <INPUT_FILE> <OUTPUT_FILE> <SPL_LOAD_ADDR>
Daniel Allred98350f72016-05-19 19:10:41 -0500113
Andreas Dannenberg8662bea2016-06-27 09:19:24 -0500114 <IMAGE_TYPE> is a value that specifies the type of the image to
115 generate OR the action the image generation tool will take. Valid
116 values are:
117 X-LOADER - Generates an image for NOR or QSPI boot modes
118 MLO - Generates an image for SD/MMC/eMMC boot modes
119 ULO - Generates an image for USB/UART peripheral boot modes
Daniel Allred98350f72016-05-19 19:10:41 -0500120
Andreas Dannenberg8662bea2016-06-27 09:19:24 -0500121 <INPUT_FILE> is the full path and filename of the public world boot
122 loader binary file (for this platform, this is always u-boot-spl.bin).
Daniel Allred98350f72016-05-19 19:10:41 -0500123
Andreas Dannenberg8662bea2016-06-27 09:19:24 -0500124 <OUTPUT_FILE> is the full path and filename of the final secure image.
125 The output binary images should be used in place of the standard
126 non-secure binary images (see the platform-specific user's guides
127 and releases notes for how the non-secure images are typically used)
Daniel Allred98350f72016-05-19 19:10:41 -0500128 u-boot-spl_HS_MLO - boot image for SD/MMC/eMMC. This image is
129 copied to a file named MLO, which is the name that
130 the device ROM bootloader requires for loading from
131 the FAT partition of an SD card (same as on
132 non-secure devices)
Andrew F. Daviseca61ae2019-01-28 11:43:26 -0600133 u-boot-spl_HS_ULO - boot image for USB/UART peripheral boot modes
Daniel Allred98350f72016-05-19 19:10:41 -0500134 u-boot-spl_HS_X-LOADER - boot image for all other flash memories
135 including QSPI and NOR flash
Andreas Dannenberg8662bea2016-06-27 09:19:24 -0500136
Andrew F. Daviseca61ae2019-01-28 11:43:26 -0600137 <SPL_LOAD_ADDR> is the address at which SOC ROM should load the
138 <INPUT_FILE>
139
Madan Srinivas4fce6552017-04-07 10:00:07 -0500140 Invoking the script for Keystone2 Secure Devices
Andrew F. Davis74ee9dc2019-04-12 12:54:48 -0400141 ================================================
Madan Srinivas4fce6552017-04-07 10:00:07 -0500142
143 create-boot-image.sh \
144 <UNUSED> <INPUT_FILE> <OUTPUT_FILE> <UNUSED>
145
146 <UNUSED> is currently ignored and reserved for future use.
147
148 <INPUT_FILE> is the full path and filename of the public world boot
149 loader binary file (only u-boot.bin is currently supported on
150 Keystone2 devices, u-boot-spl.bin is not currently supported).
151
152 <OUTPUT_FILE> is the full path and filename of the final secure image.
153 The output binary images should be used in place of the standard
154 non-secure binary images (see the platform-specific user's guides
155 and releases notes for how the non-secure images are typically used)
156 u-boot_HS_MLO - signed and encrypted boot image that can be used to
157 boot from all media. Secure boot from SPI NOR flash is not
158 currently supported.
159
Andrew F. Davis74ee9dc2019-04-12 12:54:48 -0400160 Invoking the script for K3 Secure Devices
161 =========================================
162
163 The signing steps required to produce a bootable SPL image on secure
164 K3 TI devices are the same as those performed on non-secure devices.
165 The only difference is the key is not checked on non-secure devices so
166 a dummy key is used when building U-Boot for those devices. For secure
167 K3 TI devices simply use the real hardware key for your device. This
168 real key can be set with the Kconfig option "K3_KEY". The environment
169 variable TI_SECURE_DEV_PKG is also searched for real keys when the
170 build targets secure devices.
171
Andreas Dannenberg8662bea2016-06-27 09:19:24 -0500172Booting of Primary U-Boot (u-boot.img)
173======================================
174
175 The SPL image is responsible for loading the next stage boot loader,
176 which is the main u-boot image. For secure TI devices, the SPL will
177 be authenticated, as described above, as part of the particular
178 device's ROM boot process. In order to continue the secure boot
179 process, the authenticated SPL must authenticate the main u-boot
180 image that it loads.
181
182 The configurations for secure TI platforms are written to make the boot
183 process use the FIT image format for the u-boot.img (CONFIG_SPL_FRAMEWORK
184 and CONFIG_SPL_LOAD_FIT). With these configurations the binary
185 components that the SPL loads include a specific DTB image and u-boot
186 image. These DTB image may be one of many available to the boot
187 process. In order to secure these components so that they can be
188 authenticated by the SPL as they are loaded from the FIT image, the
189 build procedure for secure TI devices will secure these images before
190 they are integrated into the FIT image. When those images are extracted
191 from the FIT image at boot time, they are post-processed to verify that
192 they are still secure. The outlined security-related SPL post-processing
193 is enabled through the CONFIG_SPL_FIT_IMAGE_POST_PROCESS option which
194 must be enabled for the secure boot scheme to work. In order to allow
195 verifying proper operation of the secure boot chain in case of successful
Andrew F. Davis74ee9dc2019-04-12 12:54:48 -0400196 authentication messages like "Authentication passed" are output by the
197 SPL to the console for each blob that got extracted from the FIT image.
Andreas Dannenberg8662bea2016-06-27 09:19:24 -0500198
199 The exact details of the how the images are secured is handled by the
200 SECDEV package. Within the SECDEV package exists a script to process
201 an input binary image:
202
203 ${TI_SECURE_DEV_PKG}/scripts/secure-binary-image.sh
204
205 This is called as part of the u-boot build process. As the secure
206 image formats and requirements can differ between the various secure
207 SOCs from TI, this script in the SECDEV package abstracts these
208 details. This script is essentially the only required interface to the
209 TI SECDEV package for creating a u-boot.img image for secure TI
210 devices.
211
212 The SPL/u-boot code contains calls to dedicated secure ROM functions
213 to perform the validation on the secured images. The details of the
214 interface to those functions is shown in the code. The summary
215 is that they are accessed by invoking an ARM secure monitor call to
216 the device's secure ROM (fixed read-only-memory that is secure and
217 only accessible when the ARM core is operating in the secure mode).
218
219 Invoking the secure-binary-image script for Secure Devices
220 ==========================================================
221
222 secure-binary-image.sh <INPUT_FILE> <OUTPUT_FILE>
223
224 <INPUT_FILE> is the full path and filename of the input binary image
225
226 <OUTPUT_FILE> is the full path and filename of the output secure image.