u-boot/doc/README.armada-secureboot

16 -------------------------------
25 one-time-writeable memory) need to be configured in the correct way.
30   key from it, and verify its SHA-256 hash against a SHA-256 stored in a eFuse
32 * Load an array of code signing public RSA keys from the header block, and
34   "root" RSA key.
35 * Choose a code signing key, and use it to verify the header block (excluding
36   the key array).
38   code signing key.
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
51 1. Creation of the needed cryptographic key material.
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
65 --------------
67 	           CSK - Code Signing Key(s): An array of RSA key pairs, which
70 	           KAK - Key Authentication Key: A RSA key pair, which is used
72 	  Header block - The first part of the boot image, which contains the
75                  eFuse - A one-time-writeable memory.
76                BootROM - The Armada's built-in boot firmware, which is
78 	    Boot image - The complete image the SoC's boot firmware loads
80 	   Main header - The header in the header block containing information
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
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
96 Trusted boot framework - The ARMADA SoC's implementation of a secure verified
100 --------------------
102 +-- Boot image --------------------------------------------+
104 | +-- Header block --------------------------------------+ |
106 | +------------------------------------------------------+ |
108 | +------------------------------------------------------+ |
110 | +------------------------------------------------------+ |
112 | +------------------------------------------------------+ |
114 | +------------------------------------------------------+ |
116 | +------------------------------------------------------+ |
118 | +------------------------------------------------------+ |
119 +----------------------------------------------------------+
122 ---------------------
128 		        of a RSA-2048 public key in DER format with a length of
134              CSK array: The array of the 16 CSKs as RSA-2048 public keys in DER
141 not tested in the current implementation of the trusted boot in U-Boot.
144 ------------------------
152 4) Verify the SHA-256 hash of the KAK embedded in the secured header.
170 ----------------
172 ### Create key material
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
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
187 openssl genrsa -out kwb_kak.key 2048
188 openssl genrsa -out kwb_csk.key 2048
190 The generated files have to be placed in the U-Boot root directory.
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
201 The Kirkwook architecture in U-Boot employs a special board-specific
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
217 	   FLASH_ID - The FlashID to be used for trusted debugging (a integer
219 	 JTAG_DELAY - The JTAG delay to be used for trusted debugging (a
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
225        SEC_BOOT_DEV - The boot device from which the trusted boot is allowed to
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
235 employ a dynamic approach of creating a Autoconf-like kwbimage.cfg.in, then
251  -> [*] Build image for trusted boot
253  -> [*] Enable eFuse support
260 image u-boot-spl.kwb can then be tested, if so desired. The hdrparser from [5]
262 'tools/marvell/doimage_mv' directory of [5], which builds a stand-alone
266 ./hdrparser -k 0 -t u-boot-spl.kwb
276 +----------------------------------------------------------+
281 +----------------------------------------------------------+
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
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
315 (0-2): The first and second words are the values to be written to the fuse
328 fuse prog -y 10 0 00112233 44556677 1
335 A "lock-only" command would look like this:
337 fuse prog -y 11 2 1
345 for normal operation. The AN [4] describes a software-controlled circuit (based
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
351 ------------------
358 ---------------
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,
363 [2] AN-383: ARMADA(R) 38x Families Secure Boot Mode Support; MV-S302501-00
365 [3] Public-Key Cryptography Standards (PKCS) #1: RSA Cryptography
368 [4] AN-389: ARMADA(R) VHV Power; MV-S302545-00 Rev. B; January 28, 2016,
370 [5] Marvell Armada 38x U-Boot support; November 25, 2015;
371     https://github.com/MarvellEmbeddedProcessors/u-boot-marvell
373 2017-01-05, Mario Six <mario.six@gdsys.cc>