doc/README.armada-secureboot - u-boot - Git at Google

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