| 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-with-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-with-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> |