+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>
projects / platform / kernel / u-boot.git / commitdiff