xref: /openbmc/u-boot/doc/README.ti-secure (revision b419e872)
1README 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
22Booting 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 AM43xx 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
56			swapped)
57		XIP_X-LOADER - Generates a single stage u-boot for
58			NOR/QSPI XiP
59		ISSW - Generates an image for all other boot modes
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_HS_XIP_X-LOADER - boot image for NOR or QSPI flash
71	u-boot-spl_HS_ISSW - boot image for all other boot media
72
73	<SPL_LOAD_ADDR> is the address at which SOC ROM should load the
74	<INPUT_FILE>
75
76	Invoking the script for DRA7xx/AM57xx Secure Devices
77	====================================================
78
79	create-boot-image.sh <IMAGE_TYPE> <INPUT_FILE> <OUTPUT_FILE>
80
81	<IMAGE_TYPE> is a value that specifies the type of the image to
82	generate OR the action the image generation tool will take. Valid
83	values are:
84		X-LOADER - Generates an image for NOR or QSPI boot modes
85		MLO - Generates an image for SD/MMC/eMMC boot modes
86		ULO - Generates an image for USB/UART peripheral boot modes
87		Note: ULO is not yet used by the u-boot build process
88
89	<INPUT_FILE> is the full path and filename of the public world boot
90	loader binary file (for this platform, this is always u-boot-spl.bin).
91
92	<OUTPUT_FILE> is the full path and filename of the final secure image.
93	The output binary images should be used in place of the standard
94	non-secure binary images (see the platform-specific user's guides
95	and releases notes for how the non-secure images are typically used)
96	u-boot-spl_HS_MLO - boot image for SD/MMC/eMMC. This image is
97		copied to a file named MLO, which is the name that
98		the device ROM bootloader requires for loading from
99		the FAT partition of an SD card (same as on
100		non-secure devices)
101	u-boot-spl_HS_X-LOADER - boot image for all other flash memories
102		including QSPI and NOR flash
103
104Booting of Primary U-Boot (u-boot.img)
105======================================
106
107	The SPL image is responsible for loading the next stage boot loader,
108	which is the main u-boot image. For secure TI devices, the SPL will
109	be authenticated, as described above, as part of the particular
110	device's ROM boot process. In order to continue the secure boot
111	process, the authenticated SPL must authenticate the main u-boot
112	image that it loads.
113
114	The configurations for secure TI platforms are written to make the boot
115	process use the FIT image format for the u-boot.img (CONFIG_SPL_FRAMEWORK
116	and CONFIG_SPL_LOAD_FIT). With these configurations the binary
117	components that the SPL loads include a specific DTB image and u-boot
118	image. These DTB image may be one of many available to the boot
119	process. In order to secure these components so that they can be
120	authenticated by the SPL as they are loaded from the FIT image,	the
121	build procedure for secure TI devices will secure these images before
122	they are integrated into the FIT image. When those images are extracted
123	from the FIT image at boot time, they are post-processed to verify that
124	they are still secure. The outlined security-related SPL post-processing
125	is enabled through the CONFIG_SPL_FIT_IMAGE_POST_PROCESS option which
126	must be enabled for the secure boot scheme to work. In order to allow
127	verifying proper operation of the secure boot chain in case of successful
128	authentication messages like "Authentication passed: CERT_U-BOOT-NOD" are
129	output by the SPL to the console for each blob that got extracted from the
130	FIT image. Note that the last part of this log message is the (truncated)
131	name of the signing certificate embedded into the blob that got processed.
132
133	The exact details of the how the images are secured is handled by the
134	SECDEV package. Within the SECDEV package exists a script to process
135	an input binary image:
136
137	${TI_SECURE_DEV_PKG}/scripts/secure-binary-image.sh
138
139	This is called as part of the u-boot build process. As the secure
140	image formats and requirements can differ between the various secure
141	SOCs from TI, this script in the SECDEV package abstracts these
142	details. This script is essentially the only required interface to the
143	TI SECDEV package for creating a u-boot.img image for secure TI
144	devices.
145
146	The SPL/u-boot code contains calls to dedicated secure ROM functions
147	to perform the validation on the secured images. The details of the
148	interface to those functions is shown in the code. The summary
149	is that they are accessed by invoking an ARM secure monitor call to
150	the device's secure ROM (fixed read-only-memory that is secure and
151	only accessible when the ARM core is operating in the secure mode).
152
153	Invoking the secure-binary-image script for Secure Devices
154	==========================================================
155
156	secure-binary-image.sh <INPUT_FILE> <OUTPUT_FILE>
157
158	<INPUT_FILE> is the full path and filename of the input binary image
159
160	<OUTPUT_FILE> is the full path and filename of the output secure image.
161