xref: /openbmc/u-boot/doc/README.ti-secure (revision 2e8560797fc69a34c330a875da4f5d2992452f1e)
198350f7fSDaniel AllredREADME on how boot images are created for secure TI devices
298350f7fSDaniel Allred
398350f7fSDaniel AllredCONFIG_TI_SECURE_DEVICE:
498350f7fSDaniel AllredSecure TI devices require a boot image that is authenticated by ROM
598350f7fSDaniel Allredcode to function. Without this, even JTAG remains locked and the
698350f7fSDaniel Allreddevice is essentially useless. In order to create a valid boot image for
798350f7fSDaniel Allreda secure device from TI, the initial public software image must be signed
898350f7fSDaniel Allredand combined with various headers, certificates, and other binary images.
998350f7fSDaniel Allred
1098350f7fSDaniel AllredInformation on the details on the complete boot image format can be obtained
1198350f7fSDaniel Allredfrom Texas Instruments. The tools used to generate boot images for secure
1298350f7fSDaniel Allreddevices are part of a secure development package (SECDEV) that can be
1398350f7fSDaniel Allreddownloaded from:
1498350f7fSDaniel Allred
1598350f7fSDaniel Allred	http://www.ti.com/mysecuresoftware (login required)
1698350f7fSDaniel Allred
1798350f7fSDaniel AllredThe secure development package is access controlled due to NDA and export
1898350f7fSDaniel Allredcontrol restrictions. Access must be requested and granted by TI before the
1998350f7fSDaniel Allredpackage is viewable and downloadable. Contact TI, either online or by way
2098350f7fSDaniel Allredof a local TI representative, to request access.
2198350f7fSDaniel Allred
228662bea3SAndreas DannenbergBooting of U-Boot SPL
238662bea3SAndreas Dannenberg=====================
248662bea3SAndreas Dannenberg
258662bea3SAndreas Dannenberg	When CONFIG_TI_SECURE_DEVICE is set, the U-Boot SPL build process
268662bea3SAndreas Dannenberg	requires the presence and use of these tools in order to create a
278662bea3SAndreas Dannenberg	viable boot image. The build process will look for the environment
288662bea3SAndreas Dannenberg	variable TI_SECURE_DEV_PKG, which should be the path of the installed
298662bea3SAndreas Dannenberg	SECDEV package. If the TI_SECURE_DEV_PKG variable is not defined or
308662bea3SAndreas Dannenberg	if it is defined but doesn't point to a valid SECDEV package, a
318662bea3SAndreas Dannenberg	warning is issued during the build to indicate that a final secure
328662bea3SAndreas Dannenberg	bootable image was not created.
3398350f7fSDaniel Allred
3498350f7fSDaniel Allred	Within the SECDEV package exists an image creation script:
3598350f7fSDaniel Allred
3698350f7fSDaniel Allred	${TI_SECURE_DEV_PKG}/scripts/create-boot-image.sh
3798350f7fSDaniel Allred
388662bea3SAndreas Dannenberg	This is called as part of the SPL/u-boot build process. As the secure
398662bea3SAndreas Dannenberg	boot image formats and requirements differ between secure SOC from TI,
408662bea3SAndreas Dannenberg	the purpose of this script is to abstract these details as much as
418662bea3SAndreas Dannenberg	possible.
4298350f7fSDaniel Allred
438662bea3SAndreas Dannenberg	The script is basically the only required interface to the TI SECDEV
448662bea3SAndreas Dannenberg	package for creating a bootable SPL image for secure TI devices.
4598350f7fSDaniel Allred
46f7160eacSAndrew F. Davis	Invoking the script for AM33xx Secure Devices
47f7160eacSAndrew F. Davis	=============================================
48f7160eacSAndrew F. Davis
49f7160eacSAndrew F. Davis	create-boot-image.sh \
50f7160eacSAndrew F. Davis		<IMAGE_FLAG> <INPUT_FILE> <OUTPUT_FILE> <SPL_LOAD_ADDR>
51f7160eacSAndrew F. Davis
52f7160eacSAndrew F. Davis	<IMAGE_FLAG> is a value that specifies the type of the image to
53f7160eacSAndrew F. Davis	generate OR the action the image generation tool will take. Valid
54f7160eacSAndrew F. Davis	values are:
55f7160eacSAndrew F. Davis		SPI_X-LOADER - Generates an image for SPI flash (byte swapped)
56f7160eacSAndrew F. Davis		X-LOADER - Generates an image for non-XIP flash
57f7160eacSAndrew F. Davis		MLO - Generates an image for SD/MMC/eMMC media
58f7160eacSAndrew F. Davis		2ND - Generates an image for USB, UART and Ethernet
59f7160eacSAndrew F. Davis		XIP_X-LOADER - Generates a single stage u-boot for NOR/QSPI XiP
60f7160eacSAndrew F. Davis
61f7160eacSAndrew F. Davis	<INPUT_FILE> is the full path and filename of the public world boot
62f7160eacSAndrew F. Davis	loaderbinary file (depending on the boot media, this is usually
63f7160eacSAndrew F. Davis	either u-boot-spl.bin or u-boot.bin).
64f7160eacSAndrew F. Davis
65f7160eacSAndrew F. Davis	<OUTPUT_FILE> is the full path and filename of the final secure
66f7160eacSAndrew F. Davis	image. The output binary images should be used in place of the standard
67f7160eacSAndrew F. Davis	non-secure binary images (see the platform-specific user's guides and
68f7160eacSAndrew F. Davis	releases notes for how the non-secure images are typically used)
69f7160eacSAndrew F. Davis	u-boot-spl_HS_SPI_X-LOADER - byte swapped boot image for SPI flash
70f7160eacSAndrew F. Davis	u-boot-spl_HS_X-LOADER - boot image for NAND or SD/MMC/eMMC rawmode
71f7160eacSAndrew F. Davis	u-boot-spl_HS_MLO - boot image for SD/MMC/eMMC media
72f7160eacSAndrew F. Davis	u-boot-spl_HS_2ND - boot image for USB, UART and Ethernet
73f7160eacSAndrew F. Davis	u-boot_HS_XIP_X-LOADER - boot image for NOR or QSPI Xip flash
74f7160eacSAndrew F. Davis
75f7160eacSAndrew F. Davis	<SPL_LOAD_ADDR> is the address at which SOC ROM should load the
76f7160eacSAndrew F. Davis	<INPUT_FILE>
77f7160eacSAndrew F. Davis
7898350f7fSDaniel Allred	Invoking the script for AM43xx Secure Devices
7998350f7fSDaniel Allred	=============================================
8098350f7fSDaniel Allred
818662bea3SAndreas Dannenberg	create-boot-image.sh \
828662bea3SAndreas Dannenberg		<IMAGE_FLAG> <INPUT_FILE> <OUTPUT_FILE> <SPL_LOAD_ADDR>
8398350f7fSDaniel Allred
848662bea3SAndreas Dannenberg	<IMAGE_FLAG> is a value that specifies the type of the image to
858662bea3SAndreas Dannenberg	generate OR the action the image generation tool will take. Valid
868662bea3SAndreas Dannenberg	values are:
878662bea3SAndreas Dannenberg		SPI_X-LOADER - Generates an image for SPI flash (byte
888662bea3SAndreas Dannenberg			swapped)
898662bea3SAndreas Dannenberg		XIP_X-LOADER - Generates a single stage u-boot for
908662bea3SAndreas Dannenberg			NOR/QSPI XiP
9198350f7fSDaniel Allred		ISSW - Generates an image for all other boot modes
9298350f7fSDaniel Allred
938662bea3SAndreas Dannenberg	<INPUT_FILE> is the full path and filename of the public world boot
948662bea3SAndreas Dannenberg	loaderbinary file (depending on the boot media, this is usually
958662bea3SAndreas Dannenberg	either u-boot-spl.bin or u-boot.bin).
9698350f7fSDaniel Allred
978662bea3SAndreas Dannenberg	<OUTPUT_FILE> is the full path and filename of the final secure
988662bea3SAndreas Dannenberg	image. The output binary images should be used in place of the standard
998662bea3SAndreas Dannenberg	non-secure binary images (see the platform-specific user's guides and
1008662bea3SAndreas Dannenberg	releases notes for how the non-secure images are typically used)
10198350f7fSDaniel Allred	u-boot-spl_HS_SPI_X-LOADER - byte swapped boot image for SPI flash
10298350f7fSDaniel Allred	u-boot_HS_XIP_X-LOADER - boot image for NOR or QSPI flash
10398350f7fSDaniel Allred	u-boot-spl_HS_ISSW - boot image for all other boot media
10498350f7fSDaniel Allred
1058662bea3SAndreas Dannenberg	<SPL_LOAD_ADDR> is the address at which SOC ROM should load the
1068662bea3SAndreas Dannenberg	<INPUT_FILE>
10798350f7fSDaniel Allred
10898350f7fSDaniel Allred	Invoking the script for DRA7xx/AM57xx Secure Devices
10998350f7fSDaniel Allred	====================================================
11098350f7fSDaniel Allred
111*eca61ae7SAndrew F. Davis	create-boot-image.sh \
112*eca61ae7SAndrew F. Davis		<IMAGE_TYPE> <INPUT_FILE> <OUTPUT_FILE> <SPL_LOAD_ADDR>
11398350f7fSDaniel Allred
1148662bea3SAndreas Dannenberg	<IMAGE_TYPE> is a value that specifies the type of the image to
1158662bea3SAndreas Dannenberg	generate OR the action the image generation tool will take. Valid
1168662bea3SAndreas Dannenberg	values are:
11798350f7fSDaniel Allred		X-LOADER - Generates an image for NOR or QSPI boot modes
11898350f7fSDaniel Allred		MLO - Generates an image for SD/MMC/eMMC boot modes
11998350f7fSDaniel Allred		ULO - Generates an image for USB/UART peripheral boot modes
12098350f7fSDaniel Allred
1218662bea3SAndreas Dannenberg	<INPUT_FILE> is the full path and filename of the public world boot
1228662bea3SAndreas Dannenberg	loader binary file (for this platform, this is always u-boot-spl.bin).
12398350f7fSDaniel Allred
1248662bea3SAndreas Dannenberg	<OUTPUT_FILE> is the full path and filename of the final secure image.
1258662bea3SAndreas Dannenberg	The output binary images should be used in place of the standard
1268662bea3SAndreas Dannenberg	non-secure binary images (see the platform-specific user's guides
1278662bea3SAndreas Dannenberg	and releases notes for how the non-secure images are typically used)
12898350f7fSDaniel Allred	u-boot-spl_HS_MLO - boot image for SD/MMC/eMMC. This image is
12998350f7fSDaniel Allred		copied to a file named MLO, which is the name that
13098350f7fSDaniel Allred		the device ROM bootloader requires for loading from
13198350f7fSDaniel Allred		the FAT partition of an SD card (same as on
13298350f7fSDaniel Allred		non-secure devices)
133*eca61ae7SAndrew F. Davis	u-boot-spl_HS_ULO - boot image for USB/UART peripheral boot modes
13498350f7fSDaniel Allred	u-boot-spl_HS_X-LOADER - boot image for all other flash memories
13598350f7fSDaniel Allred		including QSPI and NOR flash
1368662bea3SAndreas Dannenberg
137*eca61ae7SAndrew F. Davis	<SPL_LOAD_ADDR> is the address at which SOC ROM should load the
138*eca61ae7SAndrew F. Davis	<INPUT_FILE>
139*eca61ae7SAndrew F. Davis
1404fce6554SMadan Srinivas	Invoking the script for Keystone2 Secure Devices
1414fce6554SMadan Srinivas	=============================================
1424fce6554SMadan Srinivas
1434fce6554SMadan Srinivas	create-boot-image.sh \
1444fce6554SMadan Srinivas		<UNUSED> <INPUT_FILE> <OUTPUT_FILE> <UNUSED>
1454fce6554SMadan Srinivas
1464fce6554SMadan Srinivas	<UNUSED> is currently ignored and reserved for future use.
1474fce6554SMadan Srinivas
1484fce6554SMadan Srinivas	<INPUT_FILE> is the full path and filename of the public world boot
1494fce6554SMadan Srinivas	loader binary file (only u-boot.bin is currently supported on
1504fce6554SMadan Srinivas	Keystone2 devices, u-boot-spl.bin is not currently supported).
1514fce6554SMadan Srinivas
1524fce6554SMadan Srinivas	<OUTPUT_FILE> is the full path and filename of the final secure image.
1534fce6554SMadan Srinivas	The output binary images should be used in place of the standard
1544fce6554SMadan Srinivas	non-secure binary images (see the platform-specific user's guides
1554fce6554SMadan Srinivas	and releases notes for how the non-secure images are typically used)
1564fce6554SMadan Srinivas	u-boot_HS_MLO - signed and encrypted boot image that can be used to
1574fce6554SMadan Srinivas		boot from all media. Secure boot from SPI NOR flash is not
1584fce6554SMadan Srinivas		currently supported.
1594fce6554SMadan Srinivas
1608662bea3SAndreas DannenbergBooting of Primary U-Boot (u-boot.img)
1618662bea3SAndreas Dannenberg======================================
1628662bea3SAndreas Dannenberg
1638662bea3SAndreas Dannenberg	The SPL image is responsible for loading the next stage boot loader,
1648662bea3SAndreas Dannenberg	which is the main u-boot image. For secure TI devices, the SPL will
1658662bea3SAndreas Dannenberg	be authenticated, as described above, as part of the particular
1668662bea3SAndreas Dannenberg	device's ROM boot process. In order to continue the secure boot
1678662bea3SAndreas Dannenberg	process, the authenticated SPL must authenticate the main u-boot
1688662bea3SAndreas Dannenberg	image that it loads.
1698662bea3SAndreas Dannenberg
1708662bea3SAndreas Dannenberg	The configurations for secure TI platforms are written to make the boot
1718662bea3SAndreas Dannenberg	process use the FIT image format for the u-boot.img (CONFIG_SPL_FRAMEWORK
1728662bea3SAndreas Dannenberg	and CONFIG_SPL_LOAD_FIT). With these configurations the binary
1738662bea3SAndreas Dannenberg	components that the SPL loads include a specific DTB image and u-boot
1748662bea3SAndreas Dannenberg	image. These DTB image may be one of many available to the boot
1758662bea3SAndreas Dannenberg	process. In order to secure these components so that they can be
1768662bea3SAndreas Dannenberg	authenticated by the SPL as they are loaded from the FIT image,	the
1778662bea3SAndreas Dannenberg	build procedure for secure TI devices will secure these images before
1788662bea3SAndreas Dannenberg	they are integrated into the FIT image. When those images are extracted
1798662bea3SAndreas Dannenberg	from the FIT image at boot time, they are post-processed to verify that
1808662bea3SAndreas Dannenberg	they are still secure. The outlined security-related SPL post-processing
1818662bea3SAndreas Dannenberg	is enabled through the CONFIG_SPL_FIT_IMAGE_POST_PROCESS option which
1828662bea3SAndreas Dannenberg	must be enabled for the secure boot scheme to work. In order to allow
1838662bea3SAndreas Dannenberg	verifying proper operation of the secure boot chain in case of successful
1848662bea3SAndreas Dannenberg	authentication messages like "Authentication passed: CERT_U-BOOT-NOD" are
1858662bea3SAndreas Dannenberg	output by the SPL to the console for each blob that got extracted from the
1868662bea3SAndreas Dannenberg	FIT image. Note that the last part of this log message is the (truncated)
1878662bea3SAndreas Dannenberg	name of the signing certificate embedded into the blob that got processed.
1888662bea3SAndreas Dannenberg
1898662bea3SAndreas Dannenberg	The exact details of the how the images are secured is handled by the
1908662bea3SAndreas Dannenberg	SECDEV package. Within the SECDEV package exists a script to process
1918662bea3SAndreas Dannenberg	an input binary image:
1928662bea3SAndreas Dannenberg
1938662bea3SAndreas Dannenberg	${TI_SECURE_DEV_PKG}/scripts/secure-binary-image.sh
1948662bea3SAndreas Dannenberg
1958662bea3SAndreas Dannenberg	This is called as part of the u-boot build process. As the secure
1968662bea3SAndreas Dannenberg	image formats and requirements can differ between the various secure
1978662bea3SAndreas Dannenberg	SOCs from TI, this script in the SECDEV package abstracts these
1988662bea3SAndreas Dannenberg	details. This script is essentially the only required interface to the
1998662bea3SAndreas Dannenberg	TI SECDEV package for creating a u-boot.img image for secure TI
2008662bea3SAndreas Dannenberg	devices.
2018662bea3SAndreas Dannenberg
2028662bea3SAndreas Dannenberg	The SPL/u-boot code contains calls to dedicated secure ROM functions
2038662bea3SAndreas Dannenberg	to perform the validation on the secured images. The details of the
2048662bea3SAndreas Dannenberg	interface to those functions is shown in the code. The summary
2058662bea3SAndreas Dannenberg	is that they are accessed by invoking an ARM secure monitor call to
2068662bea3SAndreas Dannenberg	the device's secure ROM (fixed read-only-memory that is secure and
2078662bea3SAndreas Dannenberg	only accessible when the ARM core is operating in the secure mode).
2088662bea3SAndreas Dannenberg
2098662bea3SAndreas Dannenberg	Invoking the secure-binary-image script for Secure Devices
2108662bea3SAndreas Dannenberg	==========================================================
2118662bea3SAndreas Dannenberg
2128662bea3SAndreas Dannenberg	secure-binary-image.sh <INPUT_FILE> <OUTPUT_FILE>
2138662bea3SAndreas Dannenberg
2148662bea3SAndreas Dannenberg	<INPUT_FILE> is the full path and filename of the input binary image
2158662bea3SAndreas Dannenberg
2168662bea3SAndreas Dannenberg	<OUTPUT_FILE> is the full path and filename of the output secure image.
217