Lines Matching refs:the
6 1. Overview of the trusted boot
15 1. Overview of the trusted boot
18 The Armada's trusted boot framework enables the SoC to cryptographically verify
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
23 contains the relevant cryptographic data, as well as other information
24 pertaining to the boot process. Furthermore, a eFuse structure (a
25 one-time-writeable memory) need to be configured in the correct way.
27 Roughly, the secure boot process works as follows:
29 * Load the header block of the boot image, extract a special "root" public RSA
32 * Load an array of code signing public RSA keys from the header block, and
33 verify its RSA signature (contained in the header block as well) using the
35 * Choose a code signing key, and use it to verify the header block (excluding
36 the key array).
37 * Verify the binary image's signature (contained in the header block) using the
39 * If all checks pass successfully, boot the image.
43 * The SHA-256 value in the eFuse field verifies the "root" public key.
44 * The "root" public key verifies the code signing key array.
45 * The selected code signing key verifies the header block and the binary 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
51 1. Creation of the needed cryptographic key material.
52 2. Creation of a conforming boot image containing the U-Boot image as binary
54 3. Burning the necessary eFuse values.
57 system (some user configuration is required, though), and for (3) the necessary
58 data (essentially a series of U-Boot commands to be entered at the U-Boot
59 command prompt) will be created by the build system as well.
61 The documentation of the trusted boot mode is contained in part 1, chapter
62 7.2.5 in the functional specification [1], and in application note [2].
68 are used to sign and verify the secured header and the
71 to sign and verify the array of CSKs.
72 Header block - The first part of the boot image, which contains the
78 Boot image - The complete image the SoC's boot firmware loads
79 (contains the header block and the binary image)
80 Main header - The header in the header block containing information
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",
86 Secured header - The specialized header in the header block that
87 contains information and data pertaining to the
89 Secured boot mode - A special boot mode of the Armada SoC in which secured
91 the mode is activated by setting a eFuse field.
92 Trusted debug mode - A special mode for the trusted boot that allows
93 debugging of devices employing the trusted boot
94 framework in a secure manner (untested in the current
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:
127 KAK: The KAK is contained in the secured header in the form
130 Header block signature: The RSA signature of the header block (excluding the
131 CSK array), created using the selected CSK.
132 Binary image signature: The RSA signature of the binary image, created using
133 the selected CSK.
134 CSK array: The array of the 16 CSKs as RSA-2048 public keys in DER
136 CSK block signature: The RSA signature of the CSK array, created using the
139 NOTE: The JTAG delay, Box ID, and Flash ID header fields do play a role in the
141 not tested in the current implementation of the trusted boot in U-Boot.
146 The steps in the boot flow that are relevant for the trusted boot framework
150 2) Load the secured header, and verify its checksum.
151 3) Select the lowest valid CSK from CSK0 to CSK15.
152 4) Verify the SHA-256 hash of the KAK embedded in the secured header.
153 5) Verify the RSA signature of the CSK block from the secured header with the
155 6) Verify the header block signature (which excludes the CSK block) from the
156 secured header with the selected CSK.
157 7) Load the binary image to the main memory and verify its checksum.
158 8) Verify the binary image's RSA signature from the secured header with the
160 9) Continue the boot process as in the case of the regular boot.
162 NOTE: All RSA signatures are verified according to the PKCS #1 v2.1 standard
165 NOTE: The Box ID and Flash ID are checked after step 6, and the trusted debug
166 mode may be entered there, but since this mode is untested in the current
174 To employ the trusted boot framework, cryptographic key material needs to be
175 created. In the current implementation, two keys are needed to build a valid
177 2048 bit RSA keys in PEM format). Note that the usage of more than one CSK is
180 NOTE: Since the public key can be generated from the private key, it is
181 sufficient to store the private key for each key pair.
183 OpenSSL can be used to generate the needed files kwb_kak.key and kwb_csk.key
184 (the names of these files have to be configured, see the next section on
190 The generated files have to be placed in the U-Boot root directory.
192 Alternatively, instead of copying the files, symlinks to the private keys can
193 be placed in the U-Boot root directory.
195 WARNING: Knowledge of the KAK or CSK private key would enable an attacker to
196 generate secured boot images containing arbitrary code. Hence, the private keys
203 that are interpreted by the BootROM, such as the boot medium. The support the
205 configuration of the secured boot.
207 The configuration file's layout has been retained, only the following new
210 KAK - The name of the KAK RSA private key file in the U-Boot
211 root directory, without the trailing extension of ".key".
212 CSK - The name of the (active) CSK RSA private key file in the
213 U-Boot root directory, without the trailing extension of
221 CSK_INDEX - The index of the active CSK (a integer value).
222 SEC_SPECIALIZED_IMG - Flag to indicate whether to include the BoxID and FlashID
223 in the image (that is, whether to use the trusted debug
225 SEC_BOOT_DEV - The boot device from which the trusted boot is allowed to
228 additional ID values, consult the documentation in [1].
229 SEC_FUSE_DUMP - Dump the "fuse prog" commands necessary for writing the
230 correct eFuse values to a text file in the U-Boot root
231 directory. The parameter is the architecture for which to
232 dump the commands (currently only "a38x" is supported).
234 The parameter values may be hardcoded into the file, but it is also possible to
236 reading configuration values from Kconfig options or from the board config
237 file, and generating the actual kwbimage.cfg from this template using Makefile
242 To enable the generation of trusted boot images, the corresponding support
243 needs to be activated, and a index for the active CSK needs to be selected as
246 Furthermore, eFuse writing support has to be activated in order to burn the
247 eFuse structure's values (this option is just needed for programming the eFuse
258 The creation of the boot image is done via the usual invocation of make (with a
261 can be used for this purpose. To build the tool, invoke make in the
263 hdrparser executable. A test can be conducted by calling hdrparser with the
264 produced boot image and the following (mandatory) parameters:
268 Here we assume that the CSK index is 0 and the boot image file resides in the
271 ("PASSED"), and, finally, that the overall test was successful
272 ("T E S T S U C C E E D E D" in the last line of output).
277 | WARNING: Burning the eFuse structure is a irreversible |
278 | operation! Should wrong or corrupted values be used, the |
283 After the build process has finished, and the SEC_FUSE_DUMP option was set in
284 the kwbimage.cfg was set, a text file kwb_fuses_a38x.txt should be present in
285 the U-Boot top-level directory. It contains all the necessary commands to set
286 the eFuse structure to the values needed for the used KAK digest, as well as
287 the CSK index, Flash ID and Box ID that were selected in kwbimage.cfg.
289 Sequentially executing the commands in this file at the U-Boot command prompt
290 will write these values to the eFuse structure.
292 If the SEC_FUSE_DUMP option was not set, the commands needed to burn the fuses
294 rough overview of the process is:
296 * Burn the KAK public key hash. The hash itself can be found in the file
297 pub_kak_hash.txt in the U-Boot top-level directory; be careful to account for
298 the endianness!
299 * Burn the CSK selection, BoxID, and FlashID
300 * Enable trusted boot by burning the corresponding fuse (WARNING: this must be
301 the last fuse line written!)
302 * Lock the unused fuse lines
304 The command to employ is the "fuse prog" command previously enabled by setting
305 the corresponding configuration option.
307 For the trusted boot, the fuse prog command has a special syntax, since the
311 operations to the fuse line, where the individual 32 bit words are identified
315 (0-2): The first and second words are the values to be written to the fuse
316 line, and the third is a lock flag, which is supposed to lock the fuse line
317 when set to 1. Writes to the first and second words are memoized between
318 function calls, and the fuse line is only really written and locked (on writing
319 the third word) if both words were previously set, so that "incomplete" writes
320 are prevented. An exception to this is a single write to the third word (index
321 2) without previously writing neither the first nor the second word, which
322 locks the fuse line without setting any value; this is needed to lock the
325 As an example, to write the value 0011223344556677 to fuse line 10, we would
326 use the following command:
330 Here 10 is the fuse line number, 0 is the index of the first word to be
331 written, 00112233 and 44556677 are the values to be written to the fuse line
332 (first and second word) and the trailing 1 is the value for the third word
333 responsible for locking the line.
339 Here 11 is the fuse number, 2 is the index of the first word to be written
340 (notice that we only write to word 2 here; the third word for fuse line
341 locking), and the 1 is the value for the word we are writing to.
343 WARNING: According to application note [4], the VHV pin of the SoC must be
346 on a N-channel or P-channel FET and a free GPIO pin of the SoC) to achieve
347 this, but a jumper-based circuit should suffice as well. Regardless of the
348 chosen circuit, the issue needs to be addressed accordingly!
353 * Add the ability to populate more than one CSK