1The trusted boot framework on Marvell Armada 38x
2================================================
3
4Contents:
5
61. Overview of the trusted boot
72. Terminology
83. Boot image layout
94. The secured header
105. The secured boot flow
116. Usage example
127. Work to be done
138. Bibliography
14
151. Overview of the trusted boot
16-------------------------------
17
18The Armada's trusted boot framework enables the SoC to cryptographically verify
19a specially prepared boot image. This can be used to establish a chain of trust
20from the boot firmware all the way to the OS.
21
22To achieve this, the Armada SoC requires a specially prepared boot image, which
23contains the relevant cryptographic data, as well as other information
24pertaining to the boot process. Furthermore, a eFuse structure (a
25one-time-writeable memory) need to be configured in the correct way.
26
27Roughly, the secure boot process works as follows:
28
29* Load the header block of the boot image, extract a special "root" public RSA
30  key from it, and verify its SHA-256 hash against a SHA-256 stored in a eFuse
31  field.
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
34  "root" RSA key.
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
38  code signing key.
39* If all checks pass successfully, boot the image.
40
41The chain of trust is thus as follows:
42
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.
46
47In the special case of building a boot image containing U-Boot as the binary
48image, which employs this trusted boot framework, the following tasks need to
49be addressed:
50
511. Creation of the needed cryptographic key material.
522. Creation of a conforming boot image containing the U-Boot image as binary
53   image.
543. Burning the necessary eFuse values.
55
56(1) will be addressed later, (2) will be taken care of by U-Boot's build
57system (some user configuration is required, though), and for (3) the necessary
58data (essentially a series of U-Boot commands to be entered at the U-Boot
59command prompt) will be created by the build system as well.
60
61The documentation of the trusted boot mode is contained in part 1, chapter
627.2.5 in the functional specification [1], and in application note [2].
63
642. Terminology
65--------------
66
67	           CSK - Code Signing Key(s): An array of RSA key pairs, which
68                         are used to sign and verify the secured header and the
69                         boot loader image.
70	           KAK - Key Authentication Key: A RSA key pair, which is used
71                         to sign and verify the array of CSKs.
72	  Header block - The first part of the boot image, which contains the
73			 image's headers (also known as "headers block", "boot
74			 header", and "image header")
75                 eFuse - A one-time-writeable memory.
76               BootROM - The Armada's built-in boot firmware, which is
77                         responsible for verifying and starting secure images.
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",
85			 or just "image")
86	Secured header - The specialized header in the header block that
87			 contains information and data pertaining to the
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);
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
95			 implementation).
96Trusted boot framework - The ARMADA SoC's implementation of a secure verified
97                         boot process.
98
993. Boot image layout
100--------------------
101
102+-- Boot image --------------------------------------------+
103|                                                          |
104| +-- Header block --------------------------------------+ |
105| | Main header                                          | |
106| +------------------------------------------------------+ |
107| | Secured header                                       | |
108| +------------------------------------------------------+ |
109| | BIN header(s)                                        | |
110| +------------------------------------------------------+ |
111| | REG header(s)                                        | |
112| +------------------------------------------------------+ |
113| | Padding                                              | |
114| +------------------------------------------------------+ |
115|                                                          |
116| +------------------------------------------------------+ |
117| | Binary image + checksum                              | |
118| +------------------------------------------------------+ |
119+----------------------------------------------------------+
120
1214. The secured header
122---------------------
123
124For the trusted boot framework, a additional header is added to the boot image.
125The following data are relevant for the secure boot:
126
127		   KAK: The KAK is contained in the secured header in the form
128		        of a RSA-2048 public key in DER format with a length of
129			524 bytes.
130Header block signature: The RSA signature of the header block (excluding the
131                        CSK array), created using the selected CSK.
132Binary 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
135	                format with a length of 8384 = 16 * 524 bytes.
136   CSK block signature: The RSA signature of the CSK array, created using the
137                        KAK.
138
139NOTE: The JTAG delay, Box ID, and Flash ID header fields do play a role in the
140trusted boot process to enable and configure secure debugging, but they were
141not tested in the current implementation of the trusted boot in U-Boot.
142
1435. The secured boot flow
144------------------------
145
146The steps in the boot flow that are relevant for the trusted boot framework
147proceed as follows:
148
1491) Check if trusted boot is enabled, and perform regular boot if it is not.
1502) Load the secured header, and verify its checksum.
1513) Select the lowest valid CSK from CSK0 to CSK15.
1524) Verify the SHA-256 hash of the KAK embedded in the secured header.
1535) Verify the RSA signature of the CSK block from the secured header with the
154   KAK.
1556) Verify the header block signature (which excludes the CSK block) from the
156   secured header with the selected CSK.
1577) Load the binary image to the main memory and verify its checksum.
1588) Verify the binary image's RSA signature from the secured header with the
159   selected CSK.
1609) Continue the boot process as in the case of the regular boot.
161
162NOTE: All RSA signatures are verified according to the PKCS #1 v2.1 standard
163described in [3].
164
165NOTE: The Box ID and Flash ID are checked after step 6, and the trusted debug
166mode may be entered there, but since this mode is untested in the current
167implementation, it is not described further.
168
1696. Usage example
170----------------
171
172### Create key material
173
174To employ the trusted boot framework, cryptographic key material needs to be
175created. In the current implementation, two keys are needed to build a valid
176secured boot image: The KAK private key and a CSK private key (both have to be
1772048 bit RSA keys in PEM format). Note that the usage of more than one CSK is
178currently not supported.
179
180NOTE: Since the public key can be generated from the private key, it is
181sufficient to store the private key for each key pair.
182
183OpenSSL 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
185kwbimage.cfg settings):
186
187openssl genrsa -out kwb_kak.key 2048
188openssl genrsa -out kwb_csk.key 2048
189
190The generated files have to be placed in the U-Boot root directory.
191
192Alternatively, instead of copying the files, symlinks to the private keys can
193be placed in the U-Boot root directory.
194
195WARNING: Knowledge of the KAK or CSK private key would enable an attacker to
196generate secured boot images containing arbitrary code. Hence, the private keys
197should be carefully guarded.
198
199### Create/Modifiy kwbimage.cfg
200
201The Kirkwook architecture in U-Boot employs a special board-specific
202configuration file (kwbimage.cfg), which controls various boot image settings
203that are interpreted by the BootROM, such as the boot medium. The support the
204trusted boot framework, several new options were added to faciliate
205configuration of the secured boot.
206
207The configuration file's layout has been retained, only the following new
208options were added:
209
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
214		      ".key".
215	     BOX_ID - The BoxID to be used for trusted debugging (a integer
216	              value).
217	   FLASH_ID - The FlashID to be used for trusted debugging (a integer
218	              value).
219	 JTAG_DELAY - The JTAG delay to be used for trusted debugging (a
220	              integer value).
221          CSK_INDEX - The index of the active CSK (a integer value).
222SEC_SPECIALIZED_IMG - Flag to indicate whether to include the BoxID and FlashID
223		      in the image (that is, whether to use the trusted debug
224		      mode or not); no parameters.
225       SEC_BOOT_DEV - The boot device from which the trusted boot is allowed to
226		      proceed, identified via a numeric ID. The tested values
227		      are 0x34 = NOR flash, 0x31 = SDIO/MMC card; for
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).
233
234The parameter values may be hardcoded into the file, but it is also possible to
235employ a dynamic approach of creating a Autoconf-like kwbimage.cfg.in, then
236reading configuration values from Kconfig options or from the board config
237file, and generating the actual kwbimage.cfg from this template using Makefile
238mechanisms (see board/gdsys/a38x/Makefile as an example for this approach).
239
240### Set config options
241
242To enable the generation of trusted boot images, the corresponding support
243needs to be activated, and a index for the active CSK needs to be selected as
244well.
245
246Furthermore, eFuse writing support has to be activated in order to burn the
247eFuse structure's values (this option is just needed for programming the eFuse
248structure; production boot images may disable it).
249
250ARM architecture
251 -> [*] Build image for trusted boot
252    (0)   Index of active CSK
253 -> [*] Enable eFuse support
254    [ ]   Fake eFuse access (dry run)
255
256### Build and test boot image
257
258The creation of the boot image is done via the usual invocation of make (with a
259suitably set CROSS_COMPILE environment variable, of course). The resulting boot
260image u-boot-spl.kwb can then be tested, if so desired. The hdrparser from [5]
261can be used for this purpose. To build the tool, invoke make in the
262'tools/marvell/doimage_mv' directory of [5], which builds a stand-alone
263hdrparser executable. A test can be conducted by calling hdrparser with the
264produced boot image and the following (mandatory) parameters:
265
266./hdrparser -k 0 -t u-boot-spl.kwb
267
268Here we assume that the CSK index is 0 and the boot image file resides in the
269same directory (adapt accordingly if needed). The tool should report that all
270checksums are valid ("GOOD"), that all signature verifications succeed
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).
273
274### Burn eFuse structure
275
276+----------------------------------------------------------+
277| WARNING: Burning the eFuse structure is a irreversible   |
278| operation! Should wrong or corrupted values be used, the |
279| board won't boot anymore, and recovery is likely         |
280| impossible!                                              |
281+----------------------------------------------------------+
282
283After the build process has finished, and the SEC_FUSE_DUMP option was set in
284the kwbimage.cfg was set, a text file kwb_fuses_a38x.txt should be present in
285the U-Boot top-level directory. It contains all the necessary commands to set
286the eFuse structure to the values needed for the used KAK digest, as well as
287the CSK index, Flash ID and Box ID that were selected in kwbimage.cfg.
288
289Sequentially executing the commands in this file at the U-Boot command prompt
290will write these values to the eFuse structure.
291
292If the SEC_FUSE_DUMP option was not set, the commands needed to burn the fuses
293have to be crafted by hand. The needed fuse lines can be looked up in [1]; a
294rough overview of the process is:
295
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
303
304The command to employ is the "fuse prog" command previously enabled by setting
305the corresponding configuration option.
306
307For the trusted boot, the fuse prog command has a special syntax, since the
308ARMADA SoC demands that whole fuse lines (64 bit values) have to be written as
309a whole. The fuse prog command itself allows lists of 32 bit words to be
310written at a time, but this is translated to a series of single 32 bit write
311operations to the fuse line, where the individual 32 bit words are identified
312by a "word" counter that is increased for each write.
313
314To work around this restriction, we interpret each line to have three "words"
315(0-2): The first and second words are the values to be written to the fuse
316line, and the third is a lock flag, which is supposed to lock the fuse line
317when set to 1. Writes to the first and second words are memoized between
318function calls, and the fuse line is only really written and locked (on writing
319the third word) if both words were previously set, so that "incomplete" writes
320are prevented. An exception to this is a single write to the third word (index
3212) without previously writing neither the first nor the second word, which
322locks the fuse line without setting any value; this is needed to lock the
323unused fuse lines.
324
325As an example, to write the value 0011223344556677 to fuse line 10, we would
326use the following command:
327
328fuse prog -y 10 0 00112233 44556677 1
329
330Here 10 is the fuse line number, 0 is the index of the first word to be
331written, 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
333responsible for locking the line.
334
335A "lock-only" command would look like this:
336
337fuse prog -y 11 2 1
338
339Here 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
341locking), and the 1 is the value for the word we are writing to.
342
343WARNING: According to application note [4], the VHV pin of the SoC must be
344connected to a 1.8V source during eFuse programming, but *must* be disconnected
345for normal operation. The AN [4] describes a software-controlled circuit (based
346on a N-channel or P-channel FET and a free GPIO pin of the SoC) to achieve
347this, but a jumper-based circuit should suffice as well. Regardless of the
348chosen circuit, the issue needs to be addressed accordingly!
349
3507. Work to be done
351------------------
352
353* Add the ability to populate more than one CSK
354* Test secure debug
355* Test on Armada XP
356
3578. Bibliography
358---------------
359
360[1] ARMADA(R) 38x Family High-Performance Single/Dual CPU System on Chip
361    Functional Specification; MV-S109094-00, Rev. C; August 2, 2015,
362    Preliminary
363[2] AN-383: ARMADA(R) 38x Families Secure Boot Mode Support; MV-S302501-00
364    Rev.  A; March 11, 2015, Preliminary
365[3] Public-Key Cryptography Standards (PKCS) #1: RSA Cryptography
366    Specifications Version 2.1; February 2003;
367    https://www.ietf.org/rfc/rfc3447.txt
368[4] AN-389: ARMADA(R) VHV Power; MV-S302545-00 Rev. B; January 28, 2016,
369    Released
370[5] Marvell Armada 38x U-Boot support; November 25, 2015;
371    https://github.com/MarvellEmbeddedProcessors/u-boot-marvell
372
3732017-01-05, Mario Six <mario.six@gdsys.cc>
374