u-boot/doc/README.armada-secureboot

1 The trusted boot framework on Marvell Armada 38x
6 1. Overview of the trusted boot
8 3. Boot image layout
10 5. The secured boot flow
15 1. Overview of the trusted boot
18 The Armada's trusted boot framework enables the SoC to cryptographically verify
19 a specially prepared boot image. This can be used to establish a chain of trust
20 from the boot firmware all the way to the OS.
22 To achieve this, the Armada SoC requires a specially prepared boot image, which
24 pertaining to the boot process. Furthermore, a eFuse structure (a
27 Roughly, the secure boot process works as follows:
29 * Load the header block of the boot image, extract a special "root" public RSA
39 * If all checks pass successfully, boot the image.
47 In the special case of building a boot image containing U-Boot as the binary
48 image, which employs this trusted boot framework, the following tasks need to
52 2. Creation of a conforming boot image containing the U-Boot image as binary
56 (1) will be addressed later, (2) will be taken care of by U-Boot's build
58 data (essentially a series of U-Boot commands to be entered at the U-Boot
61 The documentation of the trusted boot mode is contained in part 1, chapter
69                          boot loader image.
72 	  Header block - The first part of the boot image, which contains the
73 			 image's headers (also known as "headers block", "boot
76                BootROM - The Armada's built-in boot firmware, which is
78 	    Boot image - The complete image the SoC's boot firmware loads
81 			 and data pertaining to the boot process (used for both
82 			 the regular and secured boot processes)
83 	  Binary image - The binary code payload of the boot image; in this
84 			 case the U-Boot's code (also known as "source image",
88 			 trusted boot (also known as "security header")
89      Secured boot mode - A special boot mode of the Armada SoC in which secured
90                          images are verified (non-secure images won't boot);
92     Trusted debug mode - A special mode for the trusted boot that allows
93 			 debugging of devices employing the trusted boot
96 Trusted boot framework - The ARMADA SoC's implementation of a secure verified
97                          boot process.
99 3. Boot image layout
102 +-- Boot image --------------------------------------------+
124 For the trusted boot framework, a additional header is added to the boot image.
125 The following data are relevant for the secure boot:
140 trusted boot process to enable and configure secure debugging, but they were
141 not tested in the current implementation of the trusted boot in U-Boot.
143 5. The secured boot flow
146 The steps in the boot flow that are relevant for the trusted boot framework
149 1) Check if trusted boot is enabled, and perform regular boot if it is not.
160 9) Continue the boot process as in the case of the regular boot.
174 To employ the trusted boot framework, cryptographic key material needs to be
176 secured boot image: The KAK private key and a CSK private key (both have to be
190 The generated files have to be placed in the U-Boot root directory.
193 be placed in the U-Boot root directory.
196 generate secured boot images containing arbitrary code. Hence, the private keys
201 The Kirkwook architecture in U-Boot employs a special board-specific
202 configuration file (kwbimage.cfg), which controls various boot image settings
203 that are interpreted by the BootROM, such as the boot medium. The support the
204 trusted boot framework, several new options were added to faciliate
205 configuration of the secured boot.
210 		KAK - The name of the KAK RSA private key file in the U-Boot
213 		      U-Boot root directory, without the trailing extension of
225        SEC_BOOT_DEV - The boot device from which the trusted boot is allowed to
230 		      correct eFuse values to a text file in the U-Boot root
242 To enable the generation of trusted boot images, the corresponding support
248 structure; production boot images may disable it).
251  -> [*] Build image for trusted boot
256 ### Build and test boot image
258 The creation of the boot image is done via the usual invocation of make (with a
259 suitably set CROSS_COMPILE environment variable, of course). The resulting boot
260 image u-boot-spl.kwb can then be tested, if so desired. The hdrparser from [5]
264 produced boot image and the following (mandatory) parameters:
266 ./hdrparser -k 0 -t u-boot-spl.kwb
268 Here we assume that the CSK index is 0 and the boot image file resides in the
279 | board won't boot anymore, and recovery is likely         |
285 the U-Boot top-level directory. It contains all the necessary commands to set
289 Sequentially executing the commands in this file at the U-Boot command prompt
297   pub_kak_hash.txt in the U-Boot top-level directory; be careful to account for
300 * Enable trusted boot by burning the corresponding fuse (WARNING: this must be
307 For the trusted boot, the fuse prog command has a special syntax, since the
363 [2] AN-383: ARMADA(R) 38x Families Secure Boot Mode Support; MV-S302501-00
370 [5] Marvell Armada 38x U-Boot support; November 25, 2015;
371     https://github.com/MarvellEmbeddedProcessors/u-boot-marvell