Merge git://www.denx.de/git/u-boot-marvell

1 files changed, 373 insertions, 0 deletions

diff --git a/doc/README.armada-secureboot b/doc/README.armada-secureboot
new file mode 100644
index 00000000000..157cb5a231a
--- /dev/null
+++ b/doc/README.armada-secureboot
@@ -0,0 +1,373 @@
+The trusted boot framework on Marvell Armada 38x
+================================================
+
+Contents:
+
+1. Overview of the trusted boot
+2. Terminology
+3. Boot image layout
+4. The secured header
+5. The secured boot flow
+6. Usage example
+7. Work to be done
+8. Bibliography
+
+1. Overview of the trusted boot
+-------------------------------
+
+The Armada's trusted boot framework enables the SoC to cryptographically verify
+a specially prepared boot image. This can be used to establish a chain of trust
+from the boot firmware all the way to the OS.
+
+To achieve this, the Armada SoC requires a specially prepared boot image, which
+contains the relevant cryptographic data, as well as other information
+pertaining to the boot process. Furthermore, a eFuse structure (a
+one-time-writeable memory) need to be configured in the correct way.
+
+Roughly, the secure boot process works as follows:
+
+* Load the header block of the boot image, extract a special "root" public RSA
+  key from it, and verify its SHA-256 hash against a SHA-256 stored in a eFuse
+  field.
+* Load an array of code signing public RSA keys from the header block, and
+  verify its RSA signature (contained in the header block as well) using the
+  "root" RSA key.
+* Choose a code signing key, and use it to verify the header block (excluding
+  the key array).
+* Verify the binary image's signature (contained in the header block) using the
+  code signing key.
+* If all checks pass successfully, boot the image.
+
+The chain of trust is thus as follows:
+
+* The SHA-256 value in the eFuse field verifies the "root" public key.
+* The "root" public key verifies the code signing key array.
+* The selected code signing key verifies the header block and the binary image.
+
+In the special case of building a boot image containing U-Boot as the binary
+image, which employs this trusted boot framework, the following tasks need to
+be addressed:
+
+1. Creation of the needed cryptographic key material.
+2. Creation of a conforming boot image containing the U-Boot image as binary
+   image.
+3. Burning the necessary eFuse values.
+
+(1) will be addressed later, (2) will be taken care of by U-Boot's build
+system (some user configuration is required, though), and for (3) the necessary
+data (essentially a series of U-Boot commands to be entered at the U-Boot
+command prompt) will be created by the build system as well.
+
+The documentation of the trusted boot mode is contained in part 1, chapter
+7.2.5 in the functional specification [1], and in application note [2].
+
+2. Terminology
+--------------
+
+	           CSK - Code Signing Key(s): An array of RSA key pairs, which
+                         are used to sign and verify the secured header and the
+                         boot loader image.
+	           KAK - Key Authentication Key: A RSA key pair, which is used
+                         to sign and verify the array of CSKs.
+	  Header block - The first part of the boot image, which contains the
+			 image's headers (also known as "headers block", "boot
+			 header", and "image header")
+                 eFuse - A one-time-writeable memory.
+               BootROM - The Armada's built-in boot firmware, which is
+                         responsible for verifying and starting secure images.
+	    Boot image - The complete image the SoC's boot firmware loads
+			 (contains the header block and the binary image)
+	   Main header - The header in the header block containing information
+			 and data pertaining to the boot process (used for both
+			 the regular and secured boot processes)
+	  Binary image - The binary code payload of the boot image; in this
+			 case the U-Boot's code (also known as "source image",
+			 or just "image")
+	Secured header - The specialized header in the header block that
+			 contains information and data pertaining to the
+			 trusted boot (also known as "security header")
+     Secured boot mode - A special boot mode of the Armada SoC in which secured
+                         images are verified (non-secure images won't boot);
+                         the mode is activated by setting a eFuse field.
+    Trusted debug mode - A special mode for the trusted boot that allows
+			 debugging of devices employing the trusted boot
+			 framework in a secure manner (untested in the current
+			 implementation).
+Trusted boot framework - The ARMADA SoC's implementation of a secure verified
+                         boot process.
+
+3. Boot image layout
+--------------------
+
++-- Boot image --------------------------------------------+
+|                                                          |
+| +-- Header block --------------------------------------+ |
+| | Main header                                          | |
+| +------------------------------------------------------+ |
+| | Secured header                                       | |
+| +------------------------------------------------------+ |
+| | BIN header(s)                                        | |
+| +------------------------------------------------------+ |
+| | REG header(s)                                        | |
+| +------------------------------------------------------+ |
+| | Padding                                              | |
+| +------------------------------------------------------+ |
+|                                                          |
+| +------------------------------------------------------+ |
+| | Binary image + checksum                              | |
+| +------------------------------------------------------+ |
++----------------------------------------------------------+
+
+4. The secured header
+---------------------
+
+For the trusted boot framework, a additional header is added to the boot image.
+The following data are relevant for the secure boot:
+
+		   KAK: The KAK is contained in the secured header in the form
+		        of a RSA-2048 public key in DER format with a length of
+			524 bytes.
+Header block signature: The RSA signature of the header block (excluding the
+                        CSK array), created using the selected CSK.
+Binary image signature: The RSA signature of the binary image, created using
+                        the selected CSK.
+             CSK array: The array of the 16 CSKs as RSA-2048 public keys in DER
+	                format with a length of 8384 = 16 * 524 bytes.
+   CSK block signature: The RSA signature of the CSK array, created using the
+                        KAK.
+
+NOTE: The JTAG delay, Box ID, and Flash ID header fields do play a role in the
+trusted boot process to enable and configure secure debugging, but they were
+not tested in the current implementation of the trusted boot in U-Boot.
+
+5. The secured boot flow
+------------------------
+
+The steps in the boot flow that are relevant for the trusted boot framework
+proceed as follows:
+
+1) Check if trusted boot is enabled, and perform regular boot if it is not.
+2) Load the secured header, and verify its checksum.
+3) Select the lowest valid CSK from CSK0 to CSK15.
+4) Verify the SHA-256 hash of the KAK embedded in the secured header.
+5) Verify the RSA signature of the CSK block from the secured header with the
+   KAK.
+6) Verify the header block signature (which excludes the CSK block) from the
+   secured header with the selected CSK.
+7) Load the binary image to the main memory and verify its checksum.
+8) Verify the binary image's RSA signature from the secured header with the
+   selected CSK.
+9) Continue the boot process as in the case of the regular boot.
+
+NOTE: All RSA signatures are verified according to the PKCS #1 v2.1 standard
+described in [3].
+
+NOTE: The Box ID and Flash ID are checked after step 6, and the trusted debug
+mode may be entered there, but since this mode is untested in the current
+implementation, it is not described further.
+
+6. Usage example
+----------------
+
+### Create key material
+
+To employ the trusted boot framework, cryptographic key material needs to be
+created. In the current implementation, two keys are needed to build a valid
+secured boot image: The KAK private key and a CSK private key (both have to be
+2048 bit RSA keys in PEM format). Note that the usage of more than one CSK is
+currently not supported.
+
+NOTE: Since the public key can be generated from the private key, it is
+sufficient to store the private key for each key pair.
+
+OpenSSL can be used to generate the needed files kwb_kak.key and kwb_csk.key
+(the names of these files have to be configured, see the next section on
+kwbimage.cfg settings):
+
+openssl genrsa -out kwb_kak.key 2048
+openssl genrsa -out kwb_csk.key 2048
+
+The generated files have to be placed in the U-Boot root directory.
+
+Alternatively, instead of copying the files, symlinks to the private keys can
+be placed in the U-Boot root directory.
+
+WARNING: Knowledge of the KAK or CSK private key would enable an attacker to
+generate secured boot images containing arbitrary code. Hence, the private keys
+should be carefully guarded.
+
+### Create/Modifiy kwbimage.cfg
+
+The Kirkwook architecture in U-Boot employs a special board-specific
+configuration file (kwbimage.cfg), which controls various boot image settings
+that are interpreted by the BootROM, such as the boot medium. The support the
+trusted boot framework, several new options were added to faciliate
+configuration of the secured boot.
+
+The configuration file's layout has been retained, only the following new
+options were added:
+
+		KAK - The name of the KAK RSA private key file in the U-Boot
+                      root directory, without the trailing extension of ".key".
+		CSK - The name of the (active) CSK RSA private key file in the
+		      U-Boot root directory, without the trailing extension of
+		      ".key".
+	     BOX_ID - The BoxID to be used for trusted debugging (a integer
+	              value).
+	   FLASH_ID - The FlashID to be used for trusted debugging (a integer
+	              value).
+	 JTAG_DELAY - The JTAG delay to be used for trusted debugging (a
+	              integer value).
+          CSK_INDEX - The index of the active CSK (a integer value).
+SEC_SPECIALIZED_IMG - Flag to indicate whether to include the BoxID and FlashID
+		      in the image (that is, whether to use the trusted debug
+		      mode or not); no parameters.
+       SEC_BOOT_DEV - The boot device from which the trusted boot is allowed to
+		      proceed, identified via a numeric ID. The tested values
+		      are 0x34 = NOR flash, 0x31 = SDIO/MMC card; for
+		      additional ID values, consult the documentation in [1].
+      SEC_FUSE_DUMP - Dump the "fuse prog" commands necessary for writing the
+		      correct eFuse values to a text file in the U-Boot root
+		      directory. The parameter is the architecture for which to
+		      dump the commands (currently only "a38x" is supported).
+
+The parameter values may be hardcoded into the file, but it is also possible to
+employ a dynamic approach of creating a Autoconf-like kwbimage.cfg.in, then
+reading configuration values from Kconfig options or from the board config
+file, and generating the actual kwbimage.cfg from this template using Makefile
+mechanisms (see board/gdsys/a38x/Makefile as an example for this approach).
+
+### Set config options
+
+To enable the generation of trusted boot images, the corresponding support
+needs to be activated, and a index for the active CSK needs to be selected as
+well.
+
+Furthermore, eFuse writing support has to be activated in order to burn the
+eFuse structure's values (this option is just needed for programming the eFuse
+structure; production boot images may disable it).
+
+ARM architecture
+ -> [*] Build image for trusted boot
+    (0)   Index of active CSK
+ -> [*] Enable eFuse support
+    [ ]   Fake eFuse access (dry run)
+
+### Build and test boot image
+
+The creation of the boot image is done via the usual invocation of make (with a
+suitably set CROSS_COMPILE environment variable, of course). The resulting boot
+image u-boot-spl.kwb can then be tested, if so desired. The hdrparser from [5]
+can be used for this purpose. To build the tool, invoke make in the
+'tools/marvell/doimage_mv' directory of [5], which builds a stand-alone
+hdrparser executable. A test can be conducted by calling hdrparser with the
+produced boot image and the following (mandatory) parameters:
+
+./hdrparser -k 0 -t u-boot-spl.kwb
+
+Here we assume that the CSK index is 0 and the boot image file resides in the
+same directory (adapt accordingly if needed). The tool should report that all
+checksums are valid ("GOOD"), that all signature verifications succeed
+("PASSED"), and, finally, that the overall test was successful
+("T E S T   S U C C E E D E D" in the last line of output).
+
+### Burn eFuse structure
+
++----------------------------------------------------------+
+| WARNING: Burning the eFuse structure is a irreversible   |
+| operation! Should wrong or corrupted values be used, the |
+| board won't boot anymore, and recovery is likely         |
+| impossible!                                              |
++----------------------------------------------------------+
+
+After the build process has finished, and the SEC_FUSE_DUMP option was set in
+the kwbimage.cfg was set, a text file kwb_fuses_a38x.txt should be present in
+the U-Boot top-level directory. It contains all the necessary commands to set
+the eFuse structure to the values needed for the used KAK digest, as well as
+the CSK index, Flash ID and Box ID that were selected in kwbimage.cfg.
+
+Sequentially executing the commands in this file at the U-Boot command prompt
+will write these values to the eFuse structure.
+
+If the SEC_FUSE_DUMP option was not set, the commands needed to burn the fuses
+have to be crafted by hand. The needed fuse lines can be looked up in [1]; a
+rough overview of the process is:
+
+* Burn the KAK public key hash. The hash itself can be found in the file
+  pub_kak_hash.txt in the U-Boot top-level directory; be careful to account for
+  the endianness!
+* Burn the CSK selection, BoxID, and FlashID
+* Enable trusted boot by burning the corresponding fuse (WARNING: this must be
+  the last fuse line written!)
+* Lock the unused fuse lines
+
+The command to employ is the "fuse prog" command previously enabled by setting
+the corresponding configuration option.
+
+For the trusted boot, the fuse prog command has a special syntax, since the
+ARMADA SoC demands that whole fuse lines (64 bit values) have to be written as
+a whole. The fuse prog command itself allows lists of 32 bit words to be
+written at a time, but this is translated to a series of single 32 bit write
+operations to the fuse line, where the individual 32 bit words are identified
+by a "word" counter that is increased for each write.
+
+To work around this restriction, we interpret each line to have three "words"
+(0-2): The first and second words are the values to be written to the fuse
+line, and the third is a lock flag, which is supposed to lock the fuse line
+when set to 1. Writes to the first and second words are memoized between
+function calls, and the fuse line is only really written and locked (on writing
+the third word) if both words were previously set, so that "incomplete" writes
+are prevented. An exception to this is a single write to the third word (index
+2) without previously writing neither the first nor the second word, which
+locks the fuse line without setting any value; this is needed to lock the
+unused fuse lines.
+
+As an example, to write the value 0011223344556677 to fuse line 10, we would
+use the following command:
+
+fuse prog -y 10 0 00112233 44556677 1
+
+Here 10 is the fuse line number, 0 is the index of the first word to be
+written, 00112233 and 44556677 are the values to be written to the fuse line
+(first and second word) and the trailing 1 is the value for the third word
+responsible for locking the line.
+
+A "lock-only" command would look like this:
+
+fuse prog -y 11 2 1
+
+Here 11 is the fuse number, 2 is the index of the first word to be written
+(notice that we only write to word 2 here; the third word for fuse line
+locking), and the 1 is the value for the word we are writing to.
+
+WARNING: According to application note [4], the VHV pin of the SoC must be
+connected to a 1.8V source during eFuse programming, but *must* be disconnected
+for normal operation. The AN [4] describes a software-controlled circuit (based
+on a N-channel or P-channel FET and a free GPIO pin of the SoC) to achieve
+this, but a jumper-based circuit should suffice as well. Regardless of the
+chosen circuit, the issue needs to be addressed accordingly!
+
+7. Work to be done
+------------------
+
+* Add the ability to populate more than one CSK
+* Test secure debug
+* Test on Armada XP
+
+8. Bibliography
+---------------
+
+[1] ARMADA(R) 38x Family High-Performance Single/Dual CPU System on Chip
+    Functional Specification; MV-S109094-00, Rev. C; August 2, 2015,
+    Preliminary
+[2] AN-383: ARMADA(R) 38x Families Secure Boot Mode Support; MV-S302501-00
+    Rev.  A; March 11, 2015, Preliminary
+[3] Public-Key Cryptography Standards (PKCS) #1: RSA Cryptography
+    Specifications Version 2.1; February 2003;
+    https://www.ietf.org/rfc/rfc3447.txt
+[4] AN-389: ARMADA(R) VHV Power; MV-S302545-00 Rev. B; January 28, 2016,
+    Released
+[5] Marvell Armada 38x U-Boot support; November 25, 2015;
+    https://github.com/MarvellEmbeddedProcessors/u-boot-marvell
+
+2017-01-05, Mario Six <mario.six@gdsys.cc>