Merge git://git.denx.de/u-boot-imx
[platform/kernel/u-boot.git] / doc / README.ti-secure
1 README on how boot images are created for secure TI devices
2
3 CONFIG_TI_SECURE_DEVICE:
4 Secure TI devices require a boot image that is authenticated by ROM
5 code to function. Without this, even JTAG remains locked and the
6 device is essentially useless. In order to create a valid boot image for
7 a secure device from TI, the initial public software image must be signed
8 and combined with various headers, certificates, and other binary images.
9
10 Information on the details on the complete boot image format can be obtained
11 from Texas Instruments. The tools used to generate boot images for secure
12 devices are part of a secure development package (SECDEV) that can be
13 downloaded from:
14
15         http://www.ti.com/mysecuresoftware (login required)
16
17 The secure development package is access controlled due to NDA and export
18 control restrictions. Access must be requested and granted by TI before the
19 package is viewable and downloadable. Contact TI, either online or by way
20 of a local TI representative, to request access.
21
22 Booting of U-Boot SPL
23 =====================
24
25         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.
33
34         Within the SECDEV package exists an image creation script:
35
36         ${TI_SECURE_DEV_PKG}/scripts/create-boot-image.sh
37
38         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.
42
43         The script is basically the only required interface to the TI SECDEV
44         package for creating a bootable SPL image for secure TI devices.
45
46         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
78         Invoking the script for AM43xx Secure Devices
79         =============================================
80
81         create-boot-image.sh \
82                 <IMAGE_FLAG> <INPUT_FILE> <OUTPUT_FILE> <SPL_LOAD_ADDR>
83
84         <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
92
93         <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)
101         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
105         <SPL_LOAD_ADDR> is the address at which SOC ROM should load the
106         <INPUT_FILE>
107
108         Invoking the script for DRA7xx/AM57xx Secure Devices
109         ====================================================
110
111         create-boot-image.sh <IMAGE_TYPE> <INPUT_FILE> <OUTPUT_FILE>
112
113         <IMAGE_TYPE> is a value that specifies the type of the image to
114         generate OR the action the image generation tool will take. Valid
115         values are:
116                 X-LOADER - Generates an image for NOR or QSPI boot modes
117                 MLO - Generates an image for SD/MMC/eMMC boot modes
118                 ULO - Generates an image for USB/UART peripheral boot modes
119                 Note: ULO is not yet used by the u-boot build process
120
121         <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).
123
124         <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)
128         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)
133         u-boot-spl_HS_X-LOADER - boot image for all other flash memories
134                 including QSPI and NOR flash
135
136         Invoking the script for Keystone2 Secure Devices
137         =============================================
138
139         create-boot-image.sh \
140                 <UNUSED> <INPUT_FILE> <OUTPUT_FILE> <UNUSED>
141
142         <UNUSED> is currently ignored and reserved for future use.
143
144         <INPUT_FILE> is the full path and filename of the public world boot
145         loader binary file (only u-boot.bin is currently supported on
146         Keystone2 devices, u-boot-spl.bin is not currently supported).
147
148         <OUTPUT_FILE> is the full path and filename of the final secure image.
149         The output binary images should be used in place of the standard
150         non-secure binary images (see the platform-specific user's guides
151         and releases notes for how the non-secure images are typically used)
152         u-boot_HS_MLO - signed and encrypted boot image that can be used to
153                 boot from all media. Secure boot from SPI NOR flash is not
154                 currently supported.
155
156 Booting of Primary U-Boot (u-boot.img)
157 ======================================
158
159         The SPL image is responsible for loading the next stage boot loader,
160         which is the main u-boot image. For secure TI devices, the SPL will
161         be authenticated, as described above, as part of the particular
162         device's ROM boot process. In order to continue the secure boot
163         process, the authenticated SPL must authenticate the main u-boot
164         image that it loads.
165
166         The configurations for secure TI platforms are written to make the boot
167         process use the FIT image format for the u-boot.img (CONFIG_SPL_FRAMEWORK
168         and CONFIG_SPL_LOAD_FIT). With these configurations the binary
169         components that the SPL loads include a specific DTB image and u-boot
170         image. These DTB image may be one of many available to the boot
171         process. In order to secure these components so that they can be
172         authenticated by the SPL as they are loaded from the FIT image, the
173         build procedure for secure TI devices will secure these images before
174         they are integrated into the FIT image. When those images are extracted
175         from the FIT image at boot time, they are post-processed to verify that
176         they are still secure. The outlined security-related SPL post-processing
177         is enabled through the CONFIG_SPL_FIT_IMAGE_POST_PROCESS option which
178         must be enabled for the secure boot scheme to work. In order to allow
179         verifying proper operation of the secure boot chain in case of successful
180         authentication messages like "Authentication passed: CERT_U-BOOT-NOD" are
181         output by the SPL to the console for each blob that got extracted from the
182         FIT image. Note that the last part of this log message is the (truncated)
183         name of the signing certificate embedded into the blob that got processed.
184
185         The exact details of the how the images are secured is handled by the
186         SECDEV package. Within the SECDEV package exists a script to process
187         an input binary image:
188
189         ${TI_SECURE_DEV_PKG}/scripts/secure-binary-image.sh
190
191         This is called as part of the u-boot build process. As the secure
192         image formats and requirements can differ between the various secure
193         SOCs from TI, this script in the SECDEV package abstracts these
194         details. This script is essentially the only required interface to the
195         TI SECDEV package for creating a u-boot.img image for secure TI
196         devices.
197
198         The SPL/u-boot code contains calls to dedicated secure ROM functions
199         to perform the validation on the secured images. The details of the
200         interface to those functions is shown in the code. The summary
201         is that they are accessed by invoking an ARM secure monitor call to
202         the device's secure ROM (fixed read-only-memory that is secure and
203         only accessible when the ARM core is operating in the secure mode).
204
205         Invoking the secure-binary-image script for Secure Devices
206         ==========================================================
207
208         secure-binary-image.sh <INPUT_FILE> <OUTPUT_FILE>
209
210         <INPUT_FILE> is the full path and filename of the input binary image
211
212         <OUTPUT_FILE> is the full path and filename of the output secure image.