.. _uboot_trusted:

Trusted Boot (Secure Mode)
==========================

This document describes how to build/burn and update Secure Trusted image with
Key generating and updating, assuming that the SoC being used is already
supported in U-Boot & ATF.

The trusted boot document describes the following components:

- eFuse module - Allows burning boot device, authentication key digest,
  encryption key, etc.
- Boot image format - Provides the trusted boot information to BootROM.
- Work flow - Guide how to build and burn Secure Trusted images to target
  board.
- Authentication Keys Generation and selection - Provides method to generate
  and select authentication keys.

A38x platforms
~~~~~~~~~~~~~~
Please refer to Application Note
- AN-383: ARMADA 38x/39x Families Secure Boot Mode Support

eFuses
-------
The eFuse command module and driver provides RW access to SoC eFuses through
the "efuse" command for A3700 platform or "fuse" command for A7K/8K platform.
In order to enable this SW component, the following configuration entry should
be set by using "make menuconfig"::

A8K platforms
~~~~~~~~~~~~~
Command Location:
	-> command line interface
		-> Device access commands
			-> fuse
Driver Location:
	-> Device Drivers
		-> EFUSE Support

A3700 platforms
~~~~~~~~~~~~~~~
Command Location:
	-> Command line interface
		-> MVEBU commands
			-> efuse
Driver Location:
	-> ARM architecture
		-> MVEBU Common SoC Utilities
			-> eFuse support

The above configuration enables the eFuse driver and eFuse command module.
Refer to SoC and BootROM manuals for details about supported eFuses
and their role in the trusted boot flow.
Since the eFuse command module and driver are only used for simplified access
to eFuse HW values, the presence of these components in the final trusted boot
image is not required.

A8K platforms
~~~~~~~~~~~~~
The AES-256 key is visible only during the efuse burn session. It will be hidden
after reset and accessible only on early boot stages by the internal BootROM
procedures.
Trying to read efuse values of AES-256 key will return zeros.
Note that if the JTAG is permanently enabled in A8K efuse, the AES-256 key
becomes hidden for everyone, including the BootROM. Therefore when JTAG is
enabled permanently by eFuse, the boot image should not be encrypted, since
BootROM decryption will always fail unless a zero-key was used for image
encryption.

A3700 platforms
~~~~~~~~~~~~~~~
The AES-256 KEY can be hidden by setting the "DEV_DEPLOY" bits, these bits are
set by the customer when deploying their products which will set the chip to
trusted mode.

Boot Image Format
-----------------
The boot image should be properly formatted for the trusted boot mode, so
the BootROM extracts the required information from the image headers and uses it
for authentication against eFuse values and digital signatures and for image
decryption.
Various platforms use different BootROMs and boot image formats.
For specific details refer to the SoC functional specification, BootROM manual
and to the section related to a selected platform below.
Refer to ATF build documentation for enabling secure image output.

A8K platforms
~~~~~~~~~~~~~
Refer to A8K functional specification for details about trusted boot image
components.
The secure image configuration is defined by a file sec_img_xx.cfg located in
ATF folder "tools/doimage/secure". The xx in the configuration file name is
either 7K or 8K for targeting Armada-80x0 or Aramda-70x0 platform setup
accordingly.
The configuration file has a standard INI file format and defines the following
options:

- kak_key_file - The string containing path to the Keys Authentication Key file
		in PEM format. This parameter is mandatory.

- csk_key_file	- Array of string containing paths to Code Signing Key files in
		PEM format. This array has to include at least a single key used
		for signing the boot image and prolog. The key index is defined
		by the file location in this array.
		Empty key paths should be coded as "*" strings to make the
		entire array size of 16 strings. This parameter is mandatory.

- csk_key_index - The integer value in range of 0 to 15 defining the CSK file
		from the above array to be used for creating image and prolog
		signatures.
		This parameter is optional and if omitted defaults to 0.

- aes_key_file	- The string containing the path to the AES-256 symmetric key
		file in ASCII text format.
 		The boot image will be encrypted if this parameter is included
		in the configuration or left unencrypted if the parameter is
		omitted.
		This parameter is optional.

- efuse_disable - Boolean parameter defining whether to disable access to efuses
		in secure boot mode or not.
		Can be either "true" or "false". The efuse access policy is
		enforced by the BootROM.
		This parameter is optional and if omitted defaults to "true".

- jtag		- Parameters defining the JTAG behavior in trusted boot mode.
		There are two parameters enclosed in curly brackets - "enable"
		and "delay".
		The "jtag.enable" boolean parameter allows to enable the JTAG
		support in trusted boot mode (valid values "true" and "false").
		The second parameter - "jtag.delay" (integer) defines delay
		in milliseconds the BootROM waits before enabling the JTAG
		connection in the HW. These parameters are optional and if
		omitted default to "false" and 0 respectfully.

- box_id	- 4 byte hexadecimal number to be used as box ID.
		This value will be part of the secure extension in the trusted
		boot image and should match the value burned in the appropriate
		efuse field.
		This parameter is optional and if omitted defaults to 0.

- flash_id	- 4 byte hexadecimal number to be used as the flash ID.
		This value will be part of the secure extension in trusted boot
		image and should match the value burned in the appropriate efuse
		field.
		This parameter is optional and if omitted defaults to 0.

- control	- Array of hexadecimal addresses to be set on each CP connected
		to an AP in trusted mode.
		It is required to add two addresses for each connected CP.
		The first address points to the CP SecureBootControl register
		and the second address points to the CP EfuseBurnControl
		register.
		Refer to your SoC documentation for details. For instance,
		Armada-7040 SoC has a single CP connected to AP, so this array
		has to list 2 register addresses. The Armada-8040 has two CPS
		connected to AP, so this array has to include 4 register
		addresses.
		This parameter is optional.


A3700 platforms
~~~~~~~~~~~~~~~
Please refer to MARVELL WIRELESS Trusted Platform Tools Packages functional
specification for details about trusted boot image components.
The secure image configuration is defined by a single file atf_timN.txt located
in the build folder. This file will be generated after compilation.
There are some files in the A3700_utils/tim folder which are used for
trusted image boot.

- aes-256.txt - This file includes AES-256 encryption key values. This key
		is used to do Encryption/Decryption on wtmi and obmi images
		which should be programmed into efuse. it can be updated by the
		image provider.

- kak.txt - The file including (DSA Algorithm ID/Hash Algorithm ID/Key Size
		in bits/RSA Public Exponent/RSA System Modulus/RSA Private Key)
		is used to signature the TIM file, and will generate the OEM key
		in "otphash.txt" The file is generated by Key Generation command
		by KeyGeneration.txt file stored in tools/wtp/key folder.
		This file is mandatory and can be updated according to
		requirements for updating the Secure Trusted image.

- CSK[0-F].txt	- These files contain different CSK Key information (Hash
		Algorithm ID/Key Size in bits/Public Key Size in bits/Encrypt
		Algorithm ID/RSA System Modulus). These files are also generated
		by the Key Generation command with KeyGeneration.txt by setting
		different parameters(i.e. Seed...).

- timnsign.txt- This file defines which key is used to signature the TIMH file.
		Indicate the CSK_INDEX of this file in fuse. All of parameters
		(DSA Algorithm ID/Hash Algorithm ID/Key Size in bits/RSA Public
		Exponent/RSA System Modulus/RSA Private Key) in the file should
		be aligned with one of 16 KEY files in the tools/wtp/key folder.
		This file is mandatory and and can be updated according to
		requirements for updating Secure Trusted image.

Work flow - Target Preparation
------------------------------
After the trusted boot mode is selected by the SoC eFuse, the BootROM enforces
security checks upon boot image load. Therefore a right work flow is essential
for target preparation and preventing the system from self-locking.

A8K platforms
~~~~~~~~~~~~~

1. Build an image for trusted boot mode using the configuration file described
   above and any additional settings required by ATF.
   The image encryption option should not be used in this build, since the
   resulting image should be compatible with non-trusted systems.
2. Burn the image on the target board and boot it. The secure header will be
   bypassed in non-trusted boot mode and the system will start as usual.
3. Enable eFuse burning in the HW by connecting 1.8V source to AP_VHV, CP0_VHV
   and CP1_VHV pins.
   For example on A8K-DB Rev1.4 platform it is done by shortening on-board
   jumpers JP36 and JP42.
   Please refer to your Marvell Development Board manual or consult Marvell
   representative
   for the details about VHV connection setup on other supported HW platforms.
4. Burn all required efuses to each efuse rows using "fuse prog" commands.
   The trusted boot enable efuse should be burned last since any further
   modifications to the SoC efuses will not be possible afterwards.
   See the efuse programming example(HD and LD efuse rows) for A8K device below.
   uboot fuse command::

	/* HD efuse rows(64bits width) programming */
	/* prog KAK_DIGEST key to efuse */
	fuse prog -y 25 0 <KAK_DIGEST bit 31-0>    <KAK_DIGEST bit 55-32>   0x1
	fuse prog -y 26 0 <KAK_DIGEST bit 95-56>   <KAK_DIGEST bit 111-96>  0x1
	fuse prog -y 27 0 <KAK_DIGEST bit 143-112> <KAK_DIGEST bit 167-144> 0x1
	fuse prog -y 28 0 <KAK_DIGEST bit 199-168> <KAK_DIGEST bit 223-200> 0x1
	fuse prog -y 29 0 <KAK_DIGEST bit 255-224> 0x0 0x1

	For example:
	KAK key hash
	8B3732C8F03D0C407F34200C206CA36B0701E47C9074034EDE97FBFF5BA6D778
	fuse prog -y 25 0 0xC832378B 0x000C3DF0 0x1
	fuse prog -y 26 0 0x20347F40 0x006C200C 0x1
	fuse prog -y 27 0 0x01076BA3 0x00907CE4 0x1
	fuse prog -y 28 0 0xDE4E0374 0x00FFFB97 0x1
	fuse prog -y 29 0 0x78D7A65B 0x0 0x1

	/* prog AES key to efuse */
	fuse prog -y 32 0 <AES_KEY bit 31-0>    <AES_KEY bit 55-32>   0x1
	fuse prog -y 33 0 <AES_KEY bit 95-56>   <AES_KEY bit 111-96>  0x1
	fuse prog -y 34 0 <AES_KEY bit 143-112> <AES_KEY bit 167-144> 0x1
	fuse prog -y 35 0 <AES_KEY bit 199-168> <AES_KEY bit 223-200> 0x1
	fuse prog -y 36 0 <AES_KEY bit 255-224> 0x0 0x1

	For example:
	AES key
	ABCDEF1234567890ABCDEF1234567890ABCDEF1234567890ABCDEF1234567890
	fuse prog -y 32 0 0x12EFCDAB 0x00785634 0x1
	fuse prog -y 33 0 0xEFCDAB90 0x00563412 0x1
	fuse prog -y 34 0 0xCDAB9078 0x003412EF 0x1
	fuse prog -y 35 0 0xAB907856 0x0012EFCD 0x1
	fuse prog -y 36 0 0x90785634 0x0 0x1

	/* prog efuse row to select CSK valid - the first empty row specifies
	 * the CSK index
	 */
	fuse prog -y 37~50 0 0x00000001 0x00000000 0x1

	For example:
	/* prog efuse row to select CSK 3 valid,need to set bit[0] in the efuse
	 * rows 37, 38 and 39 to non zero values and leave the efuse row 40
	 * intact
	 */
	fuse prog -y 37 0 0x00000001 0x00000000 0x1
	fuse prog -y 38 0 0x00000001 0x00000000 0x1
	fuse prog -y 39 0 0x00000001 0x00000000 0x1

	/* prog flash ID to efuse row 30 */
	fuse prog -y 30 0 0xbaddf00d 0x00000000 0x1

	/* prog Box ID to efuse row 31 */
	fuse prog -y 31 0 0xdeadbeef 0x00000000 0x1

	/* LD efuse rows(256bits width) programming */
	/* For A8k SoCs, both AP and SB0/1 have LD0 and LD1 efuse rows.
	 * Only LD1 rows could be programmed.
	 * Efuse row 65 is AP LD1 while row 67 is SB0 LD1. Row 69 is SB1 LD1.
	 * /
	fuse prog -y <RowIndex> 0 <bit 31-0> <bit 63-32> <bit 95-64>
	<bit 127-96> <bit 159-128> <bit 191-160> <bit 223-192> <bit 255-224>

	Below example shows secure boot fusing to select CP0_SPI as boot device.

	/* enable trusted boot and disable JTAG permanent, select boot device
	 * (from AP perspective, here the value is 0x0 which means IHB to select
	 * device. Please see Table(Boot Source Options) for boot device
	 * selection in functional specifications document), enable CPU
	 * Wakeup/Enable in AP LD1.
	 */
	fuse prog -y 65 0 0x00000001 0x0000C000 0x00000000 0x00000000
			  0x00000000 0x00000000 0x00000000 0x00000000

	.. ATTENTION!::
	Devices based on AP807 have different AP LD1 CPU-wakeup related fields.
	For instance, the Armada-3900 DB board with boot device on AP SPI should
	be programmed in the following way (boot device 0x2)::

	fuse prog -y 65 0 0x00000011 0x00003000 0x00000000 0x00000000
			  0x00000000 0x00000000 0x00000000 0x00000000

	.. Note::
	When the secure boot device is located on AP interface, the value of CP
	efuse specifying the boot device is not taken into account by the BootROM.
	Therefore if, like in the example above, the secure boot device is AP SPI,
	the CP (SB) efuse boot device may have any value.

	Next example is for AP807-based SoCs with secure boot device on CP0_SPI::

	fuse prog -y 65 0 0x00000001 0x00003000 0x00000000 0x00000000
			  0x00000000 0x00000000 0x00000000 0x00000000

	/* enable trusted boot and disable JTAG permanent, select boot device
	 * (from SB perspective, the value is 0x32 which means boot from CP0_SPI
	 * Please see the HW sepcificaiton document for a list of supported
	 * values), disable ICU message LD1 in SB0
	 */
	fuse prog -y 67 0 0x000000c9 0x00000001 0x00000000 0x00000000
			  0x00000000 0x00000000 0x00000000 0x00000000

	/* enable trusted boot and disable JTAG permanent, select boot device
	 * (from SB perspective, the value is 0x32 which means boot from CP0_SPI
	 * Please see the HW sepcificaiton document for a list of supported
	 * values), disable ICU message LD1 in SB1
	 */
	fuse prog -y 69 0 0x000000c9 0x00000001 0x00000000 0x00000000
			  0x00000000 0x00000000 0x00000000 0x00000000

   .. Note::
	HD_efuse (bank ID 0~63's bit56-63 must be 0x0 according to Functional
	Specification document). Efuse row 64,66,68 are LD0 and read-only.

5. Verify the efuse values for correct efuse rows using "fuse read" commands.
6. Restart the system and ensure the secure boot authentication stage has been
   passed.
7. If the image encryption option is required, build a new image with image
   encryption enabled and burn it to the system boot device using the regular
   "bubt" command.

A3700 platforms
~~~~~~~~~~~~~~~
1. Create an UNTRUSTED boot image with eFuse command module support (as stated
   in the "eFuses" chapter above) and burn it on the target flash device using
   the regular "bubt" command.
2. Create a TRUSTED boot image with Encryption option (as stated in "Boot image
   format" chapter above)and save it for later use. Actually, encryption option
   is enabled by default to "AES-256-CBC"(only AES-256 CBC is supported).
3. Boot the target board with the UNTRUSTED boot image.
4. Run the below commands in uboot before burning TRUSTED boot image
	a. efuse write ENCRYPTION <binary value> (it always is 10 -- enable
	   encryption for primary type image)
	b. efuse write AES256_KEY <AES-256 key value>
	c. efuse write BOOT_DEVICE <device_type>
	d. efuse write KAK_DIGEST <otphash_value>
	e. efuse write CSK_INDEX <key_index>
	f. efuse write OPER_MODE <mode_type> (mode_type should be always 2).
	g. efuse DEV_DEPLOY <deploy_value> (1 - enable/0 - disable), this
	   command will set the chip into trusted mode.
	   It will also hide the AES-256 key.
5. Burn the TRUSTED boot image using regular "bubt" command.
6. Reset the board and verify that the trusted boot mode works.

.. Note::
	a. binary value: supports 00/01/10/11 disable/.../enable encryption for
	   primary type image/...
	b. AES-256 value: AES-256 symmetric encryption key in HEX format.
	   The values are in the aes-256.txt file.
	c. device_type: SPINOR, SPINAND, EMMCNORM..., select device flash
	   according to requirement.
	   After selecting device_type by efuse, the device could not be changed
	   anymore. The device flash is locked.
	d. otphash_value: OEM key generated by tbb tool when signature the TIM
	   header with kak.txt
	e. key_index: Range 0 to 15 in DEC format to select which CSK KEY is
	   used.
	f. mode_type: Operation mode in range of 0 to 3, where mode 2 is Trusted
	   boot, security check is performed on the boot device content
	g. deploy_value: Enable(1) this feature will mask AES-256 KEY value. The
	   command is optional. When secure trusted images need to hide AES-256
	   KEY value to stop reading.

<otphash_value>
   When the trusted boot image is created, the the TBB tool saves the OEM key
   in OtpHash.txt. This digest value is otphash_value which is used for efuse
   KAK_DIGEST command.
   The OtpHash.txt file lists the otphash_value in groups of 4-bytes values,
   organized in the following
   order::

       LSB
       ...
       ...
       MSB

   These otphash_value should be converted to a single 32-bytes value for
   eFuse burning::

       MSB ... ... ... LSB.

   For instance, the following otphash_value::

       0x1887C298
       0x59C9AFD9
       0x6E814E34
       0x25CD518B
       0x3CDB7EED
       0x33CC58B1
       0x2C69997A
       0xC27B7242

   Will be used in the following form in eFuse KAK digest write command::

       efuse write KAK_DIGEST C27B72422C69997A33CC58B13CDB7EED25CD518B6E814E3459C9AFD91887C298

<key_index>
   key_index is the index of the "timnsign.txt", refer to "timnsign.txt" in the
   previous chapter for detailed description.
   For instance, the following sample content is from timnsign.txt::

      DSA Algorithm ID:                7		; Signed with CSK6
      Hash Algorithm ID:               32
      Key Size in bits:                2048
      RSA Public Exponent
	  ... ... ... ...(aligned with CSK6 file)
	  ... ... ... ...
	  RSA System Modulus:
	  ... ... ... ...(aligned with CSK6 file)
	  ... ... ... ...
	  RSA Private Key:
	  ... ... ... ...(aligned with CSK6 file)
	  ... ... ... ...

   The key_index will be used in the following form in eFuse CSK_INDEX
   write command::

      efuse write CSK_INDEX 6

i.e.

Default commands before bubt Secure Trusted boot image::

	efuse write ENCRYPTION 10
	efuse write AES256_KEY 0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF
	efuse write BOOT_DEVICE SPINOR
	efuse write KAK_DIGEST C27B72422C69997A33CC58B13CDB7EED25CD518B6E814E3459C9AFD91887C298
	efuse write CSK_INDEX 6
	efuse write OPER_MODE 2


Authentication/Encryption Keys Generation and Selection
-------------------------------------------------------

A3700 platforms
~~~~~~~~~~~~~~~

A3700 platform supports selecting 16 authentication key files(CSK[0-F].txt
in the A3700_utils/tim/trusted/keys/ folder) for trusted boot.
All of the authentication keys files must be generated by TBB tool before
building Secure Trusted image.

KAK.txt (Keysignauture file) is also generated by using the same Key Generation
command.

From the above chapters decriptions, in order to update the authentication keys
of the Secure Trusted Image, we could update two files (kak.txt/timnsign.txt)
stored in the A3700_utils/tim folder.
Please follow the below steps to update these files.

1. Key Generation command::

       tbb_linux.exe -G <<path\>KeyGeneration.txt>

   Normally KeyGenernation.txt is stored in the A3700_utils/tim/trusted/keys/
   folder. If the file is a directory other than the directory from which TBB
   is executed, then a file path must also be provided.

2. KeyGeneration.txt

   Content::

	Seed: Trusted platform
	Key ID: DSIG
	Encrypt Algorithm ID: 7
	Hash Algorithm ID: 32
	Key Size: 2048
	Output Binary Filename:
	Output Text Filename: ./KAK.txt

   - Seed - The ASCII seed value can be any continuous ASCII alphanumeric
	sequence delimited by white-space. TBB hashes the ASCII seed value to
	a 32-bit value and uses that value to seed the random number generator.

   - Key ID - The ASCII tag can be any 4-character string. i.e. DSIG -- means
	that it will be created for digital signature.

   - Encrypt Algorithm ID - i.e.7 = PKCS_2_2(ippcp). Currenlty, only 7 is
	supported.

   - Hash Algorithm ID - Hash Algorithm uses the Hash Algorithm ID to hash the
	data associated with the key.
	i.e. 20 = SHA160, 32 = SHA256, 64 = SHA512. Our A3700 use 32 as default.

   - Key Size - For PKCS, the supported key sixe in bits is 2048.

   - Output Binary Filename - if blank, no binary file is generated.
	Normally, we keep this empty.

   - Output Text Filename - if a path\filename is provided, TBB outputs an
	ASCII txt file containing the generated key components.

3. Update kak.txt files according the KAK.txt file. Copy the KAK.txt to
   the A3700_utils/tim/trusted folder and update some parameters
   Rename KAK.txt to kak.txt in the A3700_utils/tim folder.
   Change the kak.txt file headers in the content:

       Key ID: DSIG
       Encrypt Algorithm ID: 7
       ... ... ... ...

   to below format::

       DSA Algorithm ID:                7		; Signed with KAK
       ... ... ... ...

   The kak.txt is used to be generated to OtpHash.txt mentioned in the above
   chapter.

4. Update timnsign.txt file content to select CSK_Index

   Update all parameters(DSA Algorithm ID/Hash Algorithm ID/Key Size in bits
   /RSA Public Exponent/RSA System Modulus/RSA Private Key) value in
   timnsign.txt according to CSK[0-F].txt files located in tools/wtp/key folder.
   For instance, if you decide to use CSKA file (eFsue write CSK_INDEX 10),
   you should update timnsign.txt's parameters aligned with CSKA.txt file.
