View source for STM32MP15 secure boot

<noinclude>
{{ArticleMainWriter|EricS}}
{{ArticleApprovedVersion | EricS | LionelD(Passed 17Jan'19), GeraldB (Passed 17Jan'19), MounaB(Done 27Jun'18) | No previous approved version | BrunoB - 30Jan'19 - 10394 | 01Feb'19}}
[[Category:Trusted Firmware-A (TF-A)| 03]]
</noinclude>
== Purpose ==
Secure boot is a key feature to guarantee a secure platform. <br><br />
[[Boot_chains_overview#STM32MP_boot_sequence|STM32MP1 boot sequence]] supports a trusted boot chain that ensures that the loaded images are authenticated and checked in integrity before being used.
{{Warning| The secure boot feature availability is indicated in the ''security'' field of the chip [[STM32MP15_microprocessor#Part_number_codification|part number]].}}

== Authentication processing ==
STM32 MPU provides authentication processing with ECDSA <ref>https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm</ref> verification algorithm, based on  ECC <ref>https://en.wikipedia.org/wiki/Elliptic-curve_cryptography</ref>. ECDSA offers better result than RSA with a smaller key. STM32 MPU relies on a 256 bits ECDSA key.<br>

Two algorithms are supported for ECDSA calculation:
* P-256 NIST
* Brainpool 256
The algorithm selection is done via the signed binary header, as shown in [[STM32MP15_secure_boot#STM32_Header|STM32 header]] (subchapter in this same article).

The EDCSA verification follows the process below:<br>
[[File:Bootrom_Authentication.png|810px|center|link=]]

=== Key generation ===
First step is to generate the ECC pair of keys with [[KeyGen_tool|STM32 KeyGen tool]]. This is the key pair that will be used to sign the images. <br>
The tool also generates a third file containing the public key hash (PKH) that will be used to authenticate the public key on the target.

=== Key registration===
{{Warning| Make sure that a device with Secure boot enabled is used: this is mentionned in the [[STM32MP15_microprocessor#Part_number_codification|part number]], otherwise the device will become permanently unusable.}}
==== Register hash public key ====
First step to enable the authentication is to burn the [[STM32MP15_ROM_code_overview#OTP WORD 24 to 31 - Public Key Hash (PKH)|OTP WORD 24 to 31]] in [[BSEC internal peripheral|BSEC]] with the corresponding public key hash (PKH, output file from [[KeyGen_tool|STM32 KeyGen]]).
OpenSTLinux embeds a '''stm32key''' tool that can be called from [[U-Boot_overview#U-Boot command line interface (CLI)|U-Boot command line interface]] to program the PKH into the OTP.<br />

PKH file (publicKeyhash.bin) must be available in a filesystem partition (like bootfs) on a storage device (like sdcard) before proceeding.

  {{Board$}} ext4load mmc 0:4 0xc0000000 publicKeyhash.bin                  {{highlight|Load hash file from mmc 0 partition 4 (ext4) in DDR}}
  32 bytes read in 50 ms (0 Bytes/s)

  {{Board$}} stm32key read 0xc0000000                                       {{highlight|Read loaded key from DDR to confirm it is valid (without writing it in OTP)}}
  OTP value 24: 12345678
  OTP value 25: 12345678
  OTP value 26: 12345678
  OTP value 27: 12345678
  OTP value 28: 12345678
  OTP value 29: 12345678
  OTP value 30: 12345678
  OTP value 31: 12345678

{{Warning| If hash key is ok, the key in OTP can be fused}}
  {{Board$}} stm32key fuse -y 0xc0000000                                    {{highlight|Write the key in OTP}}

The device now contains the hash to authenticate images.

=== Image signing ===
In a second step, FSBL and SSBL binaries must be signed. [[Signing_tool|STM32 Signing tool]] allows to fill the STM32 binary header that is parsed by the embedded software to authenticate each binary.

==== STM32 Header ==== 
[[File:STM32_header.png | right]]

Each signed binary image includes a specific STM32 header added on top of the binary data. The header includes the authentication information.<br>
<br>
{|
! Name !! Length !! Byte Offset !! Description
|-
| Magic number || 32 bits || 0 || ‘S’ ; ‘T’ ; ‘M’ ; 0x32
|-
| Image Signature || 512 bits || 4 || ECDSA signature for image authentication<sup>1</sup>
|-
| Image Checksum || 32 bits || 68 || Checksum of the payload<sup>2</sup>
|-
| Header version || 32 bits || 72 || Header version v1.0 = 0x00010000<br>    Byte0: reserved<br>    Byte1:major version = 0x01  <br>    Byte2: minor version = 0x00 <br>    Byte3: reserved
|-
| Image Length || 32 bits || 76 || Length of image in bytes<sup>3</sup>
|-
| Image Entry  Point || 32 bits || 80 || Entry point of image
|-
| Reserved1 || 32 bits || 84 || Reserved
|-
| Load address || 32 bits || 88 || Load address of image<sup>4</sup>
|-
| Reserved2 || 32 bits || 92 || Reserved
|-
| Version Number || 32 bits || 96 || Image Version (monotonic number)<sup>5</sup>
|-
| Option flags || 32 bits || 100 || b0=1: no signature verification<sup>6</sup>
|-
| ECDSA Algorithm || 32 bits || 104 || 1: P-256 NIST ; 2: brainpool 256
|-
| ECDSA Public key || 512 bits || 108 || ECDSA public key to be used to verify the signature.<sup>7</sup><br>      
|-
| Padding || 84 Bytes || 172 || Reserved padding bytes<sup>8</sup>. Must all be set to 0
|-
| BinaryType || 1 Byte || 255 || Used to check the binary type<br>0x00: U-Boot <br>0x10-0x1F: TF-A <br>0x20-0X2F: OPTEE <br>0x30: Copro

|}

:<sup>1</sup> Signature is calculated from first byte of header version field to last byte of image given by image length field.<br>
:<sup>2</sup> 32-bit sum of all payload bytes accessed as 8-bit unsigned numbers, discarding any overflow bits. Used to check the downloaded image integrity when signature is not used (if b0=1 in Option flags).<br>
:<sup>3</sup> Length is the length of the built image, it does not include the length of the STM32 header.<br>
:<sup>4</sup> This field is used by ROM code for specific executable images.<br>
:<sup>5</sup> Image version is an anti rollback monotonic counter. The ROM code checks that it is higher or equal to the  [[STM32MP15_ROM_code_overview#OTP WORD 4 - Monotonic counter|monotonic counter stored in OTP]].
:<sup>6</sup> Enabling signature verification is mandatory on [[STM32MP15_ROM_code_overview#Device states|secure closed chips]].<br>
:<sup>7</sup> Hash of (algorithm+pubKey) is stored in [[STM32MP15_ROM_code_overview#OTP WORD 24 to 31 - Public Key Hash (PKH)|OTP WORD 24 to 31]].
:<sup>8</sup> This padding forces Header size to 0x100 bytes.

<br clear=all>

=== Image programming ===
Once the images are signed, they can be programmed into the flash on the target board with [[STM32CubeProgrammer]].

=== PKH check ===
Before really starting the authentication process, the ROM code compares the hash of the public key carried in the STM32 header with the one that was provisionned in OTP.

=== Authentication ===
==== Bootrom authentication ====
Using a '''signed''' binary, the ROM code authenticates and starts the FSBL. 

If the authentication fails, the ROM code enters into a serial boot loop indicated by the blinking Error LED (cf [[STM32MP15 ROM code overview#Common debug and error cases|Bootrom common debug and error cases]])

The [[STM32MP15 ROM code overview|ROM code]] provides secure services to the FSBL for image authentication with the same ECC pair of keys, so there is no need to support ECDSA algorithm in FSBL.

==== TF-A authentication ====
TF-A is the FSBL used by the Trusted boot chain. It is in charge of loading and verifying U-boot and (if used) OP-TEE image binaries.

Each time a '''signed''' binary is used, TF-A will print the following status:

<pre>
INFO:    Check signature on Non-Full-Secured platform
</pre>

If the image authentication fails the boot stage traps the CPU and no more trace is displayed.

=== Closing the device ===
''Notice that this last step is not shown in the diagram above.''

Without any other modification, the device is able to perform image authentication but non authenticated images can still be used and executed: the device is still opened, let's see this as a kind of test mode to check that the PKH is properly set.

As soon as the authentication process is confirmed, the device can be closed and the user forced to use signed images.

[[STM32MP15 ROM code overview#OTP WORD 0|OTP WORD0]] bit 6 is the OTP bit that closes the device. Burning this bit will lock authentication processing and force authentication from the Boot ROM.
Non signed binaries will not be supported anymore on the target.

To program this bit, the [[STM32CubeProgrammer_release_note|STM32CubeProgrammer]] or [[U-Boot_overview#U-Boot command line interface (CLI)|U-Boot command line interface]] can be used.

Here is how to proceed with U-Boot:
  {{Board$}} fuse prog 0 0x0 0x40
{{Warning| Once this bit is written the platform is locked}}

<references/>