Wiki-DB - User contributions [en]

DHCOM STM32MP15 Secure Boot

2022-03-22T12:24:39Z

Dkierner: Undo revision 3657 by Dkierner (talk)

<div class="toclimit-3">__TOC__</div>

== Introduction ==

=== Abbreviations ===

{| class="wikitable sortable"
|-
! Abbreviation !! Description
|-
| BSI || Bundesamt für Sicherheit in der Informationstechnik
|-
| CoM || Computer on module
|-
| FIT || Flattened Image Tree
|-
| FSBL || Fist Stage Bootloader (TF-A or U-Boot SPL)
|-
| OTP || One Time Programmable (eFuses)
|-
| OP-TEE || Open Portable Trusted Execution Environment
|-
| PKH || Public Key Hash
|-
| ROM || Read-Only Memory
|-
| RSA || Rivest, Shamir und Adleman (asynchronous encryption)
|-
| SHA || Secure Hash Algorithm
|-
| SoC || System on chip
|-
| SoM || System on module
|-
| SSBL || Second Stage Bootloader (U-Boot)
|-
| TF-A || Trusted Firmware A
|}

=== Secure Boot ===

The term Secure Boot originally comes from the UEFI specification<ref name="UEFI specification" /> and describes a secure boot process in which only signed software is loaded and executed during the boot process.

Secure Boot is a necessary cornerstone for enforcing security mechanisms in a trusted computing environment.
Enforcing the execution of signed software only during the boot process, as long as the chain of trust is secure, can guarantee that said software is free from tampering, as any manipulation will invalidate the software's signature and prevent the software from being executed.

[[File:Secure Boot Generic en.png|600px|Secure Boot Generic]]

The figure [[Media:Secure Boot Generic en.png|Secure Boot Generic]] shows an example of a secure boot process that leads to a reset in the event of an error in the signature check. Each stage uses the certificate and signature to check the origin and integrity of the next stage. On success, the next stage is executed, and in the event of an error, this always leads to a defined error state. In the simplest case, the certificates are integrated into the binary image of the previous stage.

Program code and certificate need to be trustworthy and therefore protected against tampering in each stage, otherwise the secure boot chain can be compromised. Except for the first stage, all binary images are protected against third-party tampering by the signature. As this is practically impossible for the first stage, manipulation protection has to be enforced by hardware measures to make said stage immutable, with the first stage's program code and the verification certificate for the second stage being stored in read-only memory (ROM).

=== Basic and trusted boot in the context of Secure Boot ===

When booting Linux on the STM32MP1 SoC with U-Boot SPL and U-Boot only, STM speaks of "Basic Boot"<ref name="Basic Boot" />.
However, if Linux is booted with a combination of TF-A, U-Boot and OP-TEE, STM refers to this as "Trusted Boot"<ref name="Trusted Boot" />.

{| class="wikitable"
|-
! Boot chain !! Description
|-
| Basic boot || BootROM -> U-Boot SPL -> U-Boot -> Linux
|-
| Trusted boot || BootROM -> TF-A -> U-Boot + OP-TEE -> Linux
|}

== Secure Boot in Basic Boot with BootROM authentication and Verified Boot ==

This Secure Boot implementation does use the the BootROM integrated image authentication to authenticate the U-Boot SPL as FSBL.
Authentication of U-Boot as SSBL by the U-Boot SPL and authentication of the Linux kernel, Device Tree and ramdisk by U-Boot is done using the open source implementation [[#Verified Boot|Verified Boot]].

This also means that everything from U-Boot SPL onwards is platform independent, as we do not rely on hardware specific implementations.

=== Verified Boot ===

Developers of Google's Chromium project worked out a concept for the Verified Boot called Secure Boot mechanism on the basis of the boot loader "Das U-Boot".
They use the existing infrastructure of the FIT images and for the system configuration at runtime via a Device Tree.
The description language for the FIT images was extended by an additional signature node and the Device Tree of the platform was used to store the certificate(s) for the authentication of the images.
The signature node can be used to sign individual subimages as well as combinations of individual subimages in the FIT image.
The tool <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight> takes care the signature creation for the FIT images and the addition of the certificate in a Device Tree.

With Verified Boot, the Device Tree with included public key is integrated into the program image of the stage, which accomplishes the authentication and is thus very similar to the general procedure shown in figure [[Media:Secure Boot Generic en.png|Secure Boot Generic]].
The number of public keys that can be integrated is theoretically unlimited, but they must be distinguishable by name.

==== Technical details of Verified Boot ====

{| class="wikitable"
|-
| '''Name'''
| Verified Boot
|-
| '''Implementierung'''
| Software (Open Source)
|-
| '''Hash algorithms'''
|
* SHA1 (deprecated)<ref name="BSI TR-02102" />
* SHA256
* SHA384
* SHA512
|-
| '''Crypto algorithms
|
* RSA2048 (deprecated as of 2024)<ref name="BSI TR-02102" />
* RSA4096

* ECDSA256 (currently limited to U-Boot SPL)
|-
| '''Number of key pairs'''
| unlimited
|-
|}

==== In-depth references for Verified Boot ====


===== Flatten Image Tree =====
* [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT U-Boot Documentation: doc/uImage.FIT]
* [https://source.denx.de/u-boot/u-boot/-/commit/d5934ad7 U-Boot Commit d5934ad7: "new uImage: Add dual format uImage support framework"]
* ...
* [https://source.denx.de/u-boot/u-boot/-/commit/3310c549 U-Boot Commit d5934ad7: "new uImage: Add new uImage format documentation and examples"]

===== Verified Boot =====

* [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT/signature.txt U-Boot Documentation: doc/uImage.FIT/signature.txt]
* [https://source.denx.de/u-boot/u-boot/-/commit/3e569a6b U-Boot Commit 3e569a6b: "image: Add signing infrastructure"]
* [https://source.denx.de/u-boot/u-boot/-/commit/56518e71 U-Boot Commit 56518e71: "image: Support signing of images"]
* [https://source.denx.de/u-boot/u-boot/-/commit/4d098529 U-Boot Commit 4d098529: "image: Add support for signing of FIT configurations"]

===== ECDSA signature verification =====

<div style="color:red">TODO: Mention ECDSA limitations</div>
Note: This has currently some limitations!


* [https://source.denx.de/u-boot/u-boot/-/commit/928a8be7 U-Boot Commit 928a8be7: "lib: ecdsa: Implement UCLASS_ECDSA verification on target"]
* [https://source.denx.de/u-boot/u-boot/-/commit/ee870859 U-Boot Commit ee870859: "arm: stm32mp1: Implement ECDSA signature verification"]

=== Tutorial: Secure boot from BootROM to Linux with basic boot ===

==== System requirements and needed tools ====

The following table lists all requirements to create the key pairs and build the signed images with embedded public keys.

{| class="wikitable"
|-
! Category !! Description
|-
| '''Host operating system''' ||
* Linux (Debian 9, Ubuntu 18.04 or higher prefered)
|-
| '''Debian packages''' ||
* bison
* device-tree-compiler
* flex
* gcc-arm-linux-gnueabihf (>= gcc 6)
* git
* make
* openssl
* swig
|-
| '''STM32 Tools''' ||
* [https://www.st.com/en/development-tools/stm32cubeprog.html STM32CubeProgrammer]
** STM32MP_KeyGen_CLI
** STM32MP_SigningTool_CLI
|}

<div style="color:red">TODO: Should we give host setup instructions?</div>

==== Add STM32CubeProrammer binaries to user environment ====
<syntaxhighlight lang="shell">
export PATH=${PATH}:~/STMicroelectronics/STM32Cube/STM32CubeProgrammer/bin
</syntaxhighlight>


==== Intended use of the four generated key pairs ====

We've decided to create and use as few certificates as reasonable to ensure a high level of security.
Therefore, we chose a separate key pair for each boot stage and also a separate key pair for image and configuration nodes.
If you're confused about the difference between image and configuration nodes, head over to [[#Flatten Image Tree|Flatten Image Tree]] to refresh your knowledge.
The exact purpose of the four key pairs generated for Verified Boot is described in the following table.

{| class="wikitable"
|-
! File name !! Intended use
|-
| '''fsbl-img''' || Authenticate image nodes of FIT images loaded by U-Boot SPL (U-Boot, Device Tree, firmware)
|-
| '''fsbl-cfg''' || Authenticate config nodes of FIT images loaded by U-Boot SPL (U-Boot + Device Tree + firmware)
|-
| '''ssbl-img''' || Authenticate image nodes of FIT images loaded by U-Boot (Kernel, Device Tree, InitRamFS)
|-
| '''ssbl-cfg''' || Authenticate config nodes of FIT images loaded by U-Boot (Kernel + Device Tree + InitRamFS)
|-
|}

==== Created/Modified files in the U-Boot source for Verified Boot ====

The created or modified files to build U-Boot with Verified Boot on STM32MP15 are described in the following table.

{| class="wikitable"
|-
! File
! Description
|-
| build_signed_uboot.sh
| Shell script that automates the creation of key pairs, the modification of FIT source files and Device Tree's and building of U-Boot SPL and U-Boot.
|-
| board/dhelectronics/dh_stm32mp1/u-boot-dhco?.its
| FIT source files with defined U-Boot image and Device Tree's for DHSOM platforms.
|-
| board/dhelectronics/dh_stm32mp1/linux-dhcom.its
| Dummy FIT source file with defined dummy kernel image and dummy Device Tree for DHSOM platforms.<br>To avoid relying on a built kernel image on a fixed path, we created this dummy, since adding the public keys with <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight> requires a valid FIT source file.
|-
| configs/stm32mp15_dhco?_secure_defconfig
| Example U-Boot defconfig's with enabled <syntaxhighlight lang="shell" inline>CONFIG_FIT_SIGNATURE</syntaxhighlight> and <syntaxhighlight lang="shell" inline>CONFIG_SPL_FIT_SIGNATURE</syntaxhighlight>.
|}

==== Build Verified Boot enabled U-Boot SPL and U-Boot ====

To build the U-Boot SPL and U-Boot images, you need to check out the source code and run a build script that automates everything from key generation to image creation and signing.

===== Checkout source code for Verified Boot =====

<div style="color:red">TODO: Replace my personal GitLab by a public available repository</div>
Checkout the branch <syntaxhighlight lang="shell" inline>v2022.01_dhcom_secure_boot</syntaxhighlight> in my personal GitLab repository with:

<syntaxhighlight lang="shell">
git clone git@dhplgl01:jneuhauser/u-boot.git -b v2022.01_stm32mp1_dhcom_secure_boot
</syntaxhighlight>

If you already have a cloned U-Boot source code, you can also fetch it into your existing repository with:

<syntaxhighlight lang="shell">
cd /path/to/u-boot
git remote add jneuhauser git@dhplgl01:jneuhauser/u-boot.git
git fetch jneuhauser
git checkout v2022.01_dhcom_secure_boot
</syntaxhighlight>

===== Run the build script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> =====

The shell script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> included in the U-Boot source performs the following steps.
# Prebuild U-Boat SPL and U-Boat to build the required tools and Device Tree's
# Generate the [[#Intended use of the four generated key pairs|four key pairs]] if not already created
# Generate/Modify FIT image source files for Linux (dummy) and U-Boot
# Add public keys to the built Device Tree's used by U-Boot SPL and U-Boot
# Rebuild U-Boot SPL and U-Boot with new Device Tree's containing the public keys

The script supports the following environment variables to configure the target architecture, the cross compiler, the defconfig, the key algorithm, the key directory, and a key postfix:
{| class="wikitable sortable"
|-
! Name !! Description !! Default
|-
| ARCH || Target architecture for the U-Boot build || arm
|-
| CROSS_COMPILE || Used cross compiler to build U-Boot || arm-linux-gnueabihf-
|-
| DEFCONFIG || Used defconfig for the U-Boot build || stm32mp15_dhcom_secure_defconfig
|-
| KEY_ALGO || Signature algorithm used for Verified Boot || rsa
|-
| KEY_DIR || Directory where the key pairs are stored || ../keys
|-
| KEY_POSTFIX || Postfix which is appended to the key names || -$(date +%F)
|}

To perform the steps mentioned above, you just need to run the shell script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> like below.
In this example, we override the default value for <syntaxhighlight lang="shell" inline>KEY_POSTFIX</syntaxhighlight> with <syntaxhighlight lang="shell" inline>-testing</syntaxhighlight> to append this string to the [[#Intended use of the four generated key pairs|four key file names]].
The script has debug output enabled by default, which should output all the statements in the script itself and the output of the commands used in the script.
If you have any problems with the script, feel free to get in touch with [mailto:info@dh-electronics.com us] and attach a logfile.

<syntaxhighlight lang="shell">
cd /path/to/u-boot
KEY_POSTFIX="-testing" ./build_signed_uboot.sh | tee build_signed_uboot.log
</syntaxhighlight>

If this process completes without errors, there are two boot loader images in the root directory of the U-Boot source.
{| class="wikitable sortable"
|-
! File name !! Stage !! Description
|-
| u-boot-spl.stm32 || FSBL || U-Boot SPL binary with appended Device Tree and prepended STM32 image header<ref name="STM32 image header" />.
|-
| u-boot.itb || SSBL || U-Boot and Device Tree's contained in a signed FIT image.
|}

==== Generate key pair and sign U-Boot SPL for BootROM authentication ====

To sign the U-Boot SPL as SSBL image for authentication with the BootROM we have to use the STM32 tools <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight> and <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight>.

===== Generate key pair with <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight> =====

All STM32MP15 SoCs only support one key pair for authenticating images through the BootROM.
To generate a ECDSA key pair for the STM32MP Secure Boot use the tool <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight><ref name="KeyGen_tool" />:
<syntaxhighlight lang="shell">
STM32MP_KeyGen_CLI --absolute-path "$(pwd)" --password <a secure password>
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Key Generator v2.9.0
-------------------------------------------------------------------

Prime256v1 curve is selected.
AES_256_cbc algorithm is selected for private key encryption
Generating Prime256v1 keys...
Private key PEM file created
Public key PEM file created
public key hash file created
Keys generated successfully.
+ public key: publicKey.pem
+ private key: privateKey.pem
+ public hash key: publicKeyhash.bin
</syntaxhighlight>

===== Sign U-Boot SPL with <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight> =====

To add the public key and the image signature to our built U-Boot SPL binary with STM32 image header, we are using the tool <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight><ref name="Signing_tool" /> to update the existing STM32 image header of <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> with the required details.
<syntaxhighlight lang="shell">
STM32MP_SigningTool_CLI --binary-image /path/to/u-boot/u-boot-spl.stm32 --public-key publicKey.pem --private-key privateKey.pem --password <a secure password> --output /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Signing Tool v2.9.0
-------------------------------------------------------------------

Prime256v1 curve is selected.
Header version 1 preparation ...
Reading Private Key File...
ECDSA signature generated.
Signature verification: SUCCESS
The Signed image file generated successfully: /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>

You can check the STM32 image header details with:
<syntaxhighlight lang="shell">
STM32MP_SigningTool_CLI --dump-header /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Signing Tool v2.9.0
-------------------------------------------------------------------

Header description:

Magic: 0x53544d32
Signature: c8 30 a0 62 2d 6d 4e 1b b9 f7 fe 38 27 65 e0 44 f0 f5 9d e6 8a a6 02 cb 74 52 26 9c 1e e9 07 17
1a c7 da 8e 96 fa 82 d3 b1 dc d5 3a 05 0e 87 83 94 4d 47 ad 17 07 88 0d b5 ae 2e 38 1d 90 22 ad
Checksum: 0xa8ca85
Header version: 0x10000
Size: 0x22dec
Load address: 0x2ffc2500
Entry point: 0x2ffc2500
Image version: 0x0
Option flags: 0x0
ECDSA Algo: 0x1
ECDSA pub key: 3b 71 8e 59 f1 ee 4c a8 4b 72 5f 4a 1c 63 8b 6e b8 01 ec 1a 3f 8c 98 2f d2 1d 77 f9 09 10 8f 04
30 da 5c 3a 24 53 0d 71 93 f0 a5 d9 c9 a7 27 b4 5f a5 c4 4d 55 8b 7a 25 e3 03 ef ca 87 ff 04 25
Binary type: 0x0
</syntaxhighlight>
The difference to an unsigned STM32 image header is that the values for "Signature" and "ECDSA pub key" are not all zeros and that "Option flags" is 0x0 for enabled signature verification instead of 0x1 for disabled signature verification.

==== Write U-Boot SPL and U-Boot to your boot media ====

The first step to verify that the built U-Boot SPL and U-Boot works as expected is to program both images to your boot media.
Depending on the boot configuration, your DHSOM will boot from the module's SPI-NOR flash, from the module's or baseboard's eMMC or from an SD card.
The boot configuration is always defined by the boot pins by default, because the boot pins have no alternative function on the STM32MP15 SoCs.

<div style="color:red">TODO: How can a user determine the used boot media?</div>
<div style="color:red">TODO: How to enforce boot media on Secure Boot enabled devices?</div>

===== Write U-Boot SPL and U-Boot to the SPI-NOR flash of the SoM =====

The following '''commands for the U-Boot Shell''' calculate some addresses based on the image offsets expected by the BootROM, load the required images from SD card or via TFTP into memory and finally write the prepared memory into the SPI-NOR flash on the SoM.

Prepare for loading <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> into memory:
<syntaxhighlight lang="shell">
mw.b ${loadaddr} 0xff 0x200000
setexpr fsbl1addr ${loadaddr} + 0x0
setexpr fsbl2addr ${loadaddr} + 0x40000
setexpr ssbl1addr ${loadaddr} + 0x80000
</syntaxhighlight>

Load <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> from SD card:
<syntaxhighlight lang="shell">
load mmc 0:4 ${fsbl1addr} u-boot-spl.stm32
load mmc 0:4 ${fsbl2addr} u-boot-spl.stm32
load mmc 0:4 ${ssbl1addr} u-boot.itb
</syntaxhighlight>

Load <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> from tftp server:
<syntaxhighlight lang="shell">
setenv serverip 10.20.30.1
setenv ipaddr 10.20.30.100
setenv netmask 255.255.255.0
tftp ${fsbl1addr} ${serverip}:u-boot-spl.stm32
tftp ${fsbl2addr} ${serverip}:u-boot-spl.stm32
tftp ${ssbl1addr} ${serverip}:u-boot.itb
</syntaxhighlight>

Check for magic numbers of expected image headers and conditionally program the SPI-NOR flash:
<syntaxhighlight lang="shell">
if itest *${fsbl1addr} == 0x324d5453 && itest *${fsbl2addr} == 0x324d5453 && itest *${ssbl1addr} == 0xedfe0dd0; then
sf probe && sf update ${loadaddr} 0 0x200000
fi
</syntaxhighlight>

===== Write U-Boot SPL and U-Boot to an SD card =====

<div style="color:red">TODO:</div>


===== Write U-Boot SPL and U-Boot to the eMMC =====

<div style="color:red">TODO:</div>


==== Enroll, test and enforce BootROM image authentication ====

To enroll, test and enforce image authentication by the BootROM you need to program the PKH into the OTP of the STM32MP15 SoC.
The <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> file that you created in the [[#Generate key pair with STM32MP_KeyGen_CLI|Generate key pair with STM32MP_KeyGen_CLI]] step contains the PKH in binary format for use with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> U-Boot command.
If the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command does fail or is not available on the target U-Boot, you can also write the PKH manually with the more generic <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command into the OTP.

===== Program public key hash to eFuses =====

The following '''commands for the U-Boot Shell''' load the file <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> into memory and program the contained PKH to the OTP of the STM32MP15 SoC.
The used command <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> writes and locks the words of the OTP automatically without knowing anything about the OTP layout/addresses.
If this fails or the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command is not available, you can also write and lock the OTP with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command

====== Program <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> into OTP with <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command ======

Load <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> from SD card:
<syntaxhighlight lang="shell">
load mmc 0:4 ${loadaddr} publicKeyhash.bin
</syntaxhighlight>

Or load <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> per TFTP:
<syntaxhighlight lang="shell">
setenv serverip 10.20.30.1
setenv ipaddr 10.20.30.100
setenv netmask 255.255.255.0
tftp ${loadaddr} ${serverip}:publicKeyhash.bin
</syntaxhighlight>

Show the contents of <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight>:
<syntaxhighlight lang="shell">
stm32key read ${loadaddr}
</syntaxhighlight>
<syntaxhighlight lang="console">
Read KEY at 0xc2000000
OTP value 24: 4e31bbcd
OTP value 25: 51e827dd
OTP value 26: 3511f521
OTP value 27: fd9c11a2
OTP value 28: 5b997b82
OTP value 29: 8150adc5
OTP value 30: a9c68fa9
OTP value 31: 72a3ba74
</syntaxhighlight>

Write the contents of <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> to OTP with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command:
<syntaxhighlight lang="shell">
stm32key fuse ${loadaddr}
</syntaxhighlight>
<syntaxhighlight lang="console">
TODO: Add output
</syntaxhighlight>

====== Program PKH manually into OTP with <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command ======

Generate fuse command with hexdump from file <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> on linux host:
<div style="color:red">Warning: Do not use the example output! Only use your unique values for programming the PKH in the OTP!</div>
<syntaxhighlight lang="shell">
echo fuse prog -y 0 0x18 $(hexdump -e '/4 "0x"' -e '/1 "%x"' -e '" "' /path/to/publicKeyhash.bin)
</syntaxhighlight>
<syntaxhighlight lang="console">
fuse prog -y 0 0x18 0x4e31bbcd 0x51e827dd 0x3511f521 0xfd9c11a2 0x5b997b82 0x8150adc5 0xa9c68fa9 0x72a3ba74
</syntaxhighlight>

Write the PKH into OTP manually with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<div style="color:red">Warning: Do not use the example command! Only use your unique values for programming the PKH in the OTP!</div>
<syntaxhighlight lang="shell">
fuse prog -y 0 0x18 0x4e31bbcd 0x51e827dd 0x3511f521 0xfd9c11a2 0x5b997b82 0x8150adc5 0xa9c68fa9 0x72a3ba74
</syntaxhighlight>

Lock the related OTP words manually with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<syntaxhighlight lang="shell">
fuse prog -y 0 0x10000018 1 1 1 1 1 1 1 1
</syntaxhighlight>

===== Test BootROM image authentication =====

To verify the image authentication by the BootROM with the programmed PKH and the programmed signed images, you must reboot your device.

On the third line of the U-Boot SPL output, check the BootROM authentication status.
The status output should look like this: <syntaxhighlight lang="console" inline>Bootrom authentication: succeeded</syntaxhighlight>.
Note the <syntaxhighlight lang="console" inline>succeeded</syntaxhighlight> status for successful authentication of the U-Boot SPL image by the BootROM.

The following output shows successful authentication of the U-Boot-SPL image in line 3, as well as successful authentication of the used configuration in line 7 and the U-Boot and Device Tree subimages in lines 8 and 9 of the U-Boot-FIT image.
<syntaxhighlight lang="console" line highlight="3,7-9">
U-Boot SPL 2022.01-00012-g6c5892c90c28 (Feb 16 2022 - 11:11:16 +0100)
Model: STMicroelectronics STM32MP15xx DHCOM Premium Developer Kit (2)
Bootrom authentication: succeeded
Code: SoM:rev=1,ddr3=3 Board:rev=0
RAM: DDR3L 32bits 2x4Gb 533MHz
Trying to boot from SPI
## Checking hash(es) for config config-2 ... sha256,rsa4096:fsbl-cfg-2022-02-16+ OK
## Checking hash(es) for Image uboot ... sha256,rsa4096:fsbl-img-2022-02-16+ sha256+ OK
## Checking hash(es) for Image fdt-1 ... sha256,rsa4096:fsbl-img-2022-02-16+ sha256+ OK
</syntaxhighlight>

===== Enforce BootROM image authentication =====

Without any further changes, the BootROM is able to perform authentication of the FSBL image, but unauthenticated images can still be used and executed.
The device is still open, let's see this as a kind of test mode to check if the PKH is set correctly.

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

The 6th bit in the 1st word of the OTP is responsible that the BootROM only accepts signed images.
Burning this bit enforces authentication of images by the BootROM and unsigned binaries are no longer supported on the target device.

To program this bit, the U-Boot Shell can be used with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command or with the more general <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command.

With usage of the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command:
<div style="color:red">Warning: After running the following command, your device will only be able to boot signed images!</div>
<syntaxhighlight lang="shell">
stm32key close
</syntaxhighlight>

Or with usage of the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<div style="color:red">Warning: After running the following command, your device will only be able to boot signed images!</div>
<syntaxhighlight lang="shell">
fuse prog 0 0x0 0x40
</syntaxhighlight>

== Secure Boot in Trusted Boot with BootROM authentication, TF-A and OP-TEE ==

<div style="color:red">TODO:</div>
# Add support for STM32MP15 DHCOM in <ref name="TF-A" />
# Add support for STM32MP15 DHCOM in <ref name="OP-TEE/optee_os" />
# Create stm32mp15_dhcom_trusted_defconfig???
# Integrate STM32MP15 DHCOM into <ref name="OP-TEE/build" />

== References ==

<references>
<ref name="UEFI specification">[http://www.uefi.org/specifications http://www.uefi.org/specifications]</ref>
<ref name="Basic Boot">[https://source.denx.de/u-boot/u-boot/-/blob/master/configs/stm32mp15_basic_defconfig U-Boot Source stm32mp15_basic_defconfig]</ref>
<ref name="Trusted Boot">[https://source.denx.de/u-boot/u-boot/-/blob/master/configs/stm32mp15_trusted_defconfig U-Boot Source stm32mp15_trusted_defconfig]</ref>
<ref name="BSI TR-02102">[https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.pdf BSI - Technische Richtlinie, "Kryptographische Algorithmen und Schlüssellängen", BSI TR-02102-1]</ref>
<ref name="STM32 image header">[https://wiki.st.com/stm32mpu/wiki/STM32_header_for_binary_files STM32 header for binary files]</ref>
<ref name="KeyGen_tool">[https://wiki.st.com/stm32mpu/wiki/KeyGen_tool STM32MP KeyGen tool]</ref>
<ref name="Signing_tool">[https://wiki.st.com/stm32mpu/wiki/Signing_tool STM32MP Signing tool]</ref>
<ref name="TF-A">[https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/ Trusted Firmware-A (TF-A)]</ref>
<ref name="OP-TEE/optee_os">[https://github.com/OP-TEE/optee_os OP-TEE Trusted OS]</ref>
<ref name="OP-TEE/build">[https://github.com/OP-TEE/build Makefiles to use OP-TEE on various platforms]</ref>
</references>

DHCOM STM32MP15 Secure Boot

2022-03-22T12:01:40Z

Dkierner: Add separate out directory for the STM32_MP_SigningTool_CLI instruction /* Sign U-Boot SPL with STM32MP_SigningTool_CLI */

<div class="toclimit-3">__TOC__</div>

== Introduction ==

=== Abbreviations ===

{| class="wikitable sortable"
|-
! Abbreviation !! Description
|-
| BSI || Bundesamt für Sicherheit in der Informationstechnik
|-
| CoM || Computer on module
|-
| FIT || Flattened Image Tree
|-
| FSBL || Fist Stage Bootloader (TF-A or U-Boot SPL)
|-
| OTP || One Time Programmable (eFuses)
|-
| OP-TEE || Open Portable Trusted Execution Environment
|-
| PKH || Public Key Hash
|-
| ROM || Read-Only Memory
|-
| RSA || Rivest, Shamir und Adleman (asynchronous encryption)
|-
| SHA || Secure Hash Algorithm
|-
| SoC || System on chip
|-
| SoM || System on module
|-
| SSBL || Second Stage Bootloader (U-Boot)
|-
| TF-A || Trusted Firmware A
|}

=== Secure Boot ===

The term Secure Boot originally comes from the UEFI specification<ref name="UEFI specification" /> and describes a secure boot process in which only signed software is loaded and executed during the boot process.

Secure Boot is a necessary cornerstone for enforcing security mechanisms in a trusted computing environment.
Enforcing the execution of signed software only during the boot process, as long as the chain of trust is secure, can guarantee that said software is free from tampering, as any manipulation will invalidate the software's signature and prevent the software from being executed.

[[File:Secure Boot Generic en.png|600px|Secure Boot Generic]]

The figure [[Media:Secure Boot Generic en.png|Secure Boot Generic]] shows an example of a secure boot process that leads to a reset in the event of an error in the signature check. Each stage uses the certificate and signature to check the origin and integrity of the next stage. On success, the next stage is executed, and in the event of an error, this always leads to a defined error state. In the simplest case, the certificates are integrated into the binary image of the previous stage.

Program code and certificate need to be trustworthy and therefore protected against tampering in each stage, otherwise the secure boot chain can be compromised. Except for the first stage, all binary images are protected against third-party tampering by the signature. As this is practically impossible for the first stage, manipulation protection has to be enforced by hardware measures to make said stage immutable, with the first stage's program code and the verification certificate for the second stage being stored in read-only memory (ROM).

=== Basic and trusted boot in the context of Secure Boot ===

When booting Linux on the STM32MP1 SoC with U-Boot SPL and U-Boot only, STM speaks of "Basic Boot"<ref name="Basic Boot" />.
However, if Linux is booted with a combination of TF-A, U-Boot and OP-TEE, STM refers to this as "Trusted Boot"<ref name="Trusted Boot" />.

{| class="wikitable"
|-
! Boot chain !! Description
|-
| Basic boot || BootROM -> U-Boot SPL -> U-Boot -> Linux
|-
| Trusted boot || BootROM -> TF-A -> U-Boot + OP-TEE -> Linux
|}

== Secure Boot in Basic Boot with BootROM authentication and Verified Boot ==

This Secure Boot implementation does use the the BootROM integrated image authentication to authenticate the U-Boot SPL as FSBL.
Authentication of U-Boot as SSBL by the U-Boot SPL and authentication of the Linux kernel, Device Tree and ramdisk by U-Boot is done using the open source implementation [[#Verified Boot|Verified Boot]].

This also means that everything from U-Boot SPL onwards is platform independent, as we do not rely on hardware specific implementations.

=== Verified Boot ===

Developers of Google's Chromium project worked out a concept for the Verified Boot called Secure Boot mechanism on the basis of the boot loader "Das U-Boot".
They use the existing infrastructure of the FIT images and for the system configuration at runtime via a Device Tree.
The description language for the FIT images was extended by an additional signature node and the Device Tree of the platform was used to store the certificate(s) for the authentication of the images.
The signature node can be used to sign individual subimages as well as combinations of individual subimages in the FIT image.
The tool <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight> takes care the signature creation for the FIT images and the addition of the certificate in a Device Tree.

With Verified Boot, the Device Tree with included public key is integrated into the program image of the stage, which accomplishes the authentication and is thus very similar to the general procedure shown in figure [[Media:Secure Boot Generic en.png|Secure Boot Generic]].
The number of public keys that can be integrated is theoretically unlimited, but they must be distinguishable by name.

==== Technical details of Verified Boot ====

{| class="wikitable"
|-
| '''Name'''
| Verified Boot
|-
| '''Implementierung'''
| Software (Open Source)
|-
| '''Hash algorithms'''
|
* SHA1 (deprecated)<ref name="BSI TR-02102" />
* SHA256
* SHA384
* SHA512
|-
| '''Crypto algorithms
|
* RSA2048 (deprecated as of 2024)<ref name="BSI TR-02102" />
* RSA4096

* ECDSA256 (currently limited to U-Boot SPL)
|-
| '''Number of key pairs'''
| unlimited
|-
|}

==== In-depth references for Verified Boot ====


===== Flatten Image Tree =====
* [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT U-Boot Documentation: doc/uImage.FIT]
* [https://source.denx.de/u-boot/u-boot/-/commit/d5934ad7 U-Boot Commit d5934ad7: "new uImage: Add dual format uImage support framework"]
* ...
* [https://source.denx.de/u-boot/u-boot/-/commit/3310c549 U-Boot Commit d5934ad7: "new uImage: Add new uImage format documentation and examples"]

===== Verified Boot =====

* [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT/signature.txt U-Boot Documentation: doc/uImage.FIT/signature.txt]
* [https://source.denx.de/u-boot/u-boot/-/commit/3e569a6b U-Boot Commit 3e569a6b: "image: Add signing infrastructure"]
* [https://source.denx.de/u-boot/u-boot/-/commit/56518e71 U-Boot Commit 56518e71: "image: Support signing of images"]
* [https://source.denx.de/u-boot/u-boot/-/commit/4d098529 U-Boot Commit 4d098529: "image: Add support for signing of FIT configurations"]

===== ECDSA signature verification =====

<div style="color:red">TODO: Mention ECDSA limitations</div>
Note: This has currently some limitations!


* [https://source.denx.de/u-boot/u-boot/-/commit/928a8be7 U-Boot Commit 928a8be7: "lib: ecdsa: Implement UCLASS_ECDSA verification on target"]
* [https://source.denx.de/u-boot/u-boot/-/commit/ee870859 U-Boot Commit ee870859: "arm: stm32mp1: Implement ECDSA signature verification"]

=== Tutorial: Secure boot from BootROM to Linux with basic boot ===

==== System requirements and needed tools ====

The following table lists all requirements to create the key pairs and build the signed images with embedded public keys.

{| class="wikitable"
|-
! Category !! Description
|-
| '''Host operating system''' ||
* Linux (Debian 9, Ubuntu 18.04 or higher prefered)
|-
| '''Debian packages''' ||
* bison
* device-tree-compiler
* flex
* gcc-arm-linux-gnueabihf (>= gcc 6)
* git
* make
* openssl
* swig
|-
| '''STM32 Tools''' ||
* [https://www.st.com/en/development-tools/stm32cubeprog.html STM32CubeProgrammer]
** STM32MP_KeyGen_CLI
** STM32MP_SigningTool_CLI
|}

<div style="color:red">TODO: Should we give host setup instructions?</div>

==== Add STM32CubeProrammer binaries to user environment ====
<syntaxhighlight lang="shell">
export PATH=${PATH}:~/STMicroelectronics/STM32Cube/STM32CubeProgrammer/bin
</syntaxhighlight>


==== Intended use of the four generated key pairs ====

We've decided to create and use as few certificates as reasonable to ensure a high level of security.
Therefore, we chose a separate key pair for each boot stage and also a separate key pair for image and configuration nodes.
If you're confused about the difference between image and configuration nodes, head over to [[#Flatten Image Tree|Flatten Image Tree]] to refresh your knowledge.
The exact purpose of the four key pairs generated for Verified Boot is described in the following table.

{| class="wikitable"
|-
! File name !! Intended use
|-
| '''fsbl-img''' || Authenticate image nodes of FIT images loaded by U-Boot SPL (U-Boot, Device Tree, firmware)
|-
| '''fsbl-cfg''' || Authenticate config nodes of FIT images loaded by U-Boot SPL (U-Boot + Device Tree + firmware)
|-
| '''ssbl-img''' || Authenticate image nodes of FIT images loaded by U-Boot (Kernel, Device Tree, InitRamFS)
|-
| '''ssbl-cfg''' || Authenticate config nodes of FIT images loaded by U-Boot (Kernel + Device Tree + InitRamFS)
|-
|}

==== Created/Modified files in the U-Boot source for Verified Boot ====

The created or modified files to build U-Boot with Verified Boot on STM32MP15 are described in the following table.

{| class="wikitable"
|-
! File
! Description
|-
| build_signed_uboot.sh
| Shell script that automates the creation of key pairs, the modification of FIT source files and Device Tree's and building of U-Boot SPL and U-Boot.
|-
| board/dhelectronics/dh_stm32mp1/u-boot-dhco?.its
| FIT source files with defined U-Boot image and Device Tree's for DHSOM platforms.
|-
| board/dhelectronics/dh_stm32mp1/linux-dhcom.its
| Dummy FIT source file with defined dummy kernel image and dummy Device Tree for DHSOM platforms.<br>To avoid relying on a built kernel image on a fixed path, we created this dummy, since adding the public keys with <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight> requires a valid FIT source file.
|-
| configs/stm32mp15_dhco?_secure_defconfig
| Example U-Boot defconfig's with enabled <syntaxhighlight lang="shell" inline>CONFIG_FIT_SIGNATURE</syntaxhighlight> and <syntaxhighlight lang="shell" inline>CONFIG_SPL_FIT_SIGNATURE</syntaxhighlight>.
|}

==== Build Verified Boot enabled U-Boot SPL and U-Boot ====

To build the U-Boot SPL and U-Boot images, you need to check out the source code and run a build script that automates everything from key generation to image creation and signing.

===== Checkout source code for Verified Boot =====

<div style="color:red">TODO: Replace my personal GitLab by a public available repository</div>
Checkout the branch <syntaxhighlight lang="shell" inline>v2022.01_dhcom_secure_boot</syntaxhighlight> in my personal GitLab repository with:

<syntaxhighlight lang="shell">
git clone git@dhplgl01:jneuhauser/u-boot.git -b v2022.01_stm32mp1_dhcom_secure_boot
</syntaxhighlight>

If you already have a cloned U-Boot source code, you can also fetch it into your existing repository with:

<syntaxhighlight lang="shell">
cd /path/to/u-boot
git remote add jneuhauser git@dhplgl01:jneuhauser/u-boot.git
git fetch jneuhauser
git checkout v2022.01_dhcom_secure_boot
</syntaxhighlight>

===== Run the build script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> =====

The shell script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> included in the U-Boot source performs the following steps.
# Prebuild U-Boat SPL and U-Boat to build the required tools and Device Tree's
# Generate the [[#Intended use of the four generated key pairs|four key pairs]] if not already created
# Generate/Modify FIT image source files for Linux (dummy) and U-Boot
# Add public keys to the built Device Tree's used by U-Boot SPL and U-Boot
# Rebuild U-Boot SPL and U-Boot with new Device Tree's containing the public keys

The script supports the following environment variables to configure the target architecture, the cross compiler, the defconfig, the key algorithm, the key directory, and a key postfix:
{| class="wikitable sortable"
|-
! Name !! Description !! Default
|-
| ARCH || Target architecture for the U-Boot build || arm
|-
| CROSS_COMPILE || Used cross compiler to build U-Boot || arm-linux-gnueabihf-
|-
| DEFCONFIG || Used defconfig for the U-Boot build || stm32mp15_dhcom_secure_defconfig
|-
| KEY_ALGO || Signature algorithm used for Verified Boot || rsa
|-
| KEY_DIR || Directory where the key pairs are stored || ../keys
|-
| KEY_POSTFIX || Postfix which is appended to the key names || -$(date +%F)
|}

To perform the steps mentioned above, you just need to run the shell script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> like below.
In this example, we override the default value for <syntaxhighlight lang="shell" inline>KEY_POSTFIX</syntaxhighlight> with <syntaxhighlight lang="shell" inline>-testing</syntaxhighlight> to append this string to the [[#Intended use of the four generated key pairs|four key file names]].
The script has debug output enabled by default, which should output all the statements in the script itself and the output of the commands used in the script.
If you have any problems with the script, feel free to get in touch with [mailto:info@dh-electronics.com us] and attach a logfile.

<syntaxhighlight lang="shell">
cd /path/to/u-boot
KEY_POSTFIX="-testing" ./build_signed_uboot.sh | tee build_signed_uboot.log
</syntaxhighlight>

If this process completes without errors, there are two boot loader images in the root directory of the U-Boot source.
{| class="wikitable sortable"
|-
! File name !! Stage !! Description
|-
| u-boot-spl.stm32 || FSBL || U-Boot SPL binary with appended Device Tree and prepended STM32 image header<ref name="STM32 image header" />.
|-
| u-boot.itb || SSBL || U-Boot and Device Tree's contained in a signed FIT image.
|}

==== Generate key pair and sign U-Boot SPL for BootROM authentication ====

To sign the U-Boot SPL as SSBL image for authentication with the BootROM we have to use the STM32 tools <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight> and <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight>.

===== Generate key pair with <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight> =====

All STM32MP15 SoCs only support one key pair for authenticating images through the BootROM.
To generate a ECDSA key pair for the STM32MP Secure Boot use the tool <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight><ref name="KeyGen_tool" />:
<syntaxhighlight lang="shell">
STM32MP_KeyGen_CLI --absolute-path "$(pwd)" --password <a secure password>
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Key Generator v2.9.0
-------------------------------------------------------------------

Prime256v1 curve is selected.
AES_256_cbc algorithm is selected for private key encryption
Generating Prime256v1 keys...
Private key PEM file created
Public key PEM file created
public key hash file created
Keys generated successfully.
+ public key: publicKey.pem
+ private key: privateKey.pem
+ public hash key: publicKeyhash.bin
</syntaxhighlight>

===== Sign U-Boot SPL with <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight> =====

To add the public key and the image signature to our built U-Boot SPL binary with STM32 image header, we are using the tool <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight><ref name="Signing_tool" /> to update the existing STM32 image header of <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> with the required details.
<syntaxhighlight lang="shell">
mkdir out
STM32MP_SigningTool_CLI --binary-image /path/to/u-boot/u-boot-spl.stm32 --public-key publicKey.pem --private-key privateKey.pem --password <a secure password> --output out/u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Signing Tool v2.9.0
-------------------------------------------------------------------

Prime256v1 curve is selected.
Header version 1 preparation ...
Reading Private Key File...
ECDSA signature generated.
Signature verification: SUCCESS
The Signed image file generated successfully: /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>

You can check the STM32 image header details with:
<syntaxhighlight lang="shell">
STM32MP_SigningTool_CLI --dump-header /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Signing Tool v2.9.0
-------------------------------------------------------------------

Header description:

Magic: 0x53544d32
Signature: c8 30 a0 62 2d 6d 4e 1b b9 f7 fe 38 27 65 e0 44 f0 f5 9d e6 8a a6 02 cb 74 52 26 9c 1e e9 07 17
1a c7 da 8e 96 fa 82 d3 b1 dc d5 3a 05 0e 87 83 94 4d 47 ad 17 07 88 0d b5 ae 2e 38 1d 90 22 ad
Checksum: 0xa8ca85
Header version: 0x10000
Size: 0x22dec
Load address: 0x2ffc2500
Entry point: 0x2ffc2500
Image version: 0x0
Option flags: 0x0
ECDSA Algo: 0x1
ECDSA pub key: 3b 71 8e 59 f1 ee 4c a8 4b 72 5f 4a 1c 63 8b 6e b8 01 ec 1a 3f 8c 98 2f d2 1d 77 f9 09 10 8f 04
30 da 5c 3a 24 53 0d 71 93 f0 a5 d9 c9 a7 27 b4 5f a5 c4 4d 55 8b 7a 25 e3 03 ef ca 87 ff 04 25
Binary type: 0x0
</syntaxhighlight>
The difference to an unsigned STM32 image header is that the values for "Signature" and "ECDSA pub key" are not all zeros and that "Option flags" is 0x0 for enabled signature verification instead of 0x1 for disabled signature verification.

==== Write U-Boot SPL and U-Boot to your boot media ====

The first step to verify that the built U-Boot SPL and U-Boot works as expected is to program both images to your boot media.
Depending on the boot configuration, your DHSOM will boot from the module's SPI-NOR flash, from the module's or baseboard's eMMC or from an SD card.
The boot configuration is always defined by the boot pins by default, because the boot pins have no alternative function on the STM32MP15 SoCs.

<div style="color:red">TODO: How can a user determine the used boot media?</div>
<div style="color:red">TODO: How to enforce boot media on Secure Boot enabled devices?</div>

===== Write U-Boot SPL and U-Boot to the SPI-NOR flash of the SoM =====

The following '''commands for the U-Boot Shell''' calculate some addresses based on the image offsets expected by the BootROM, load the required images from SD card or via TFTP into memory and finally write the prepared memory into the SPI-NOR flash on the SoM.

Prepare for loading <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> into memory:
<syntaxhighlight lang="shell">
mw.b ${loadaddr} 0xff 0x200000
setexpr fsbl1addr ${loadaddr} + 0x0
setexpr fsbl2addr ${loadaddr} + 0x40000
setexpr ssbl1addr ${loadaddr} + 0x80000
</syntaxhighlight>

Load <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> from SD card:
<syntaxhighlight lang="shell">
load mmc 0:4 ${fsbl1addr} u-boot-spl.stm32
load mmc 0:4 ${fsbl2addr} u-boot-spl.stm32
load mmc 0:4 ${ssbl1addr} u-boot.itb
</syntaxhighlight>

Load <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> from tftp server:
<syntaxhighlight lang="shell">
setenv serverip 10.20.30.1
setenv ipaddr 10.20.30.100
setenv netmask 255.255.255.0
tftp ${fsbl1addr} ${serverip}:u-boot-spl.stm32
tftp ${fsbl2addr} ${serverip}:u-boot-spl.stm32
tftp ${ssbl1addr} ${serverip}:u-boot.itb
</syntaxhighlight>

Check for magic numbers of expected image headers and conditionally program the SPI-NOR flash:
<syntaxhighlight lang="shell">
if itest *${fsbl1addr} == 0x324d5453 && itest *${fsbl2addr} == 0x324d5453 && itest *${ssbl1addr} == 0xedfe0dd0; then
sf probe && sf update ${loadaddr} 0 0x200000
fi
</syntaxhighlight>

===== Write U-Boot SPL and U-Boot to an SD card =====

<div style="color:red">TODO:</div>


===== Write U-Boot SPL and U-Boot to the eMMC =====

<div style="color:red">TODO:</div>


==== Enroll, test and enforce BootROM image authentication ====

To enroll, test and enforce image authentication by the BootROM you need to program the PKH into the OTP of the STM32MP15 SoC.
The <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> file that you created in the [[#Generate key pair with STM32MP_KeyGen_CLI|Generate key pair with STM32MP_KeyGen_CLI]] step contains the PKH in binary format for use with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> U-Boot command.
If the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command does fail or is not available on the target U-Boot, you can also write the PKH manually with the more generic <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command into the OTP.

===== Program public key hash to eFuses =====

The following '''commands for the U-Boot Shell''' load the file <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> into memory and program the contained PKH to the OTP of the STM32MP15 SoC.
The used command <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> writes and locks the words of the OTP automatically without knowing anything about the OTP layout/addresses.
If this fails or the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command is not available, you can also write and lock the OTP with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command

====== Program <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> into OTP with <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command ======

Load <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> from SD card:
<syntaxhighlight lang="shell">
load mmc 0:4 ${loadaddr} publicKeyhash.bin
</syntaxhighlight>

Or load <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> per TFTP:
<syntaxhighlight lang="shell">
setenv serverip 10.20.30.1
setenv ipaddr 10.20.30.100
setenv netmask 255.255.255.0
tftp ${loadaddr} ${serverip}:publicKeyhash.bin
</syntaxhighlight>

Show the contents of <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight>:
<syntaxhighlight lang="shell">
stm32key read ${loadaddr}
</syntaxhighlight>
<syntaxhighlight lang="console">
Read KEY at 0xc2000000
OTP value 24: 4e31bbcd
OTP value 25: 51e827dd
OTP value 26: 3511f521
OTP value 27: fd9c11a2
OTP value 28: 5b997b82
OTP value 29: 8150adc5
OTP value 30: a9c68fa9
OTP value 31: 72a3ba74
</syntaxhighlight>

Write the contents of <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> to OTP with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command:
<syntaxhighlight lang="shell">
stm32key fuse ${loadaddr}
</syntaxhighlight>
<syntaxhighlight lang="console">
TODO: Add output
</syntaxhighlight>

====== Program PKH manually into OTP with <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command ======

Generate fuse command with hexdump from file <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> on linux host:
<div style="color:red">Warning: Do not use the example output! Only use your unique values for programming the PKH in the OTP!</div>
<syntaxhighlight lang="shell">
echo fuse prog -y 0 0x18 $(hexdump -e '/4 "0x"' -e '/1 "%x"' -e '" "' /path/to/publicKeyhash.bin)
</syntaxhighlight>
<syntaxhighlight lang="console">
fuse prog -y 0 0x18 0x4e31bbcd 0x51e827dd 0x3511f521 0xfd9c11a2 0x5b997b82 0x8150adc5 0xa9c68fa9 0x72a3ba74
</syntaxhighlight>

Write the PKH into OTP manually with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<div style="color:red">Warning: Do not use the example command! Only use your unique values for programming the PKH in the OTP!</div>
<syntaxhighlight lang="shell">
fuse prog -y 0 0x18 0x4e31bbcd 0x51e827dd 0x3511f521 0xfd9c11a2 0x5b997b82 0x8150adc5 0xa9c68fa9 0x72a3ba74
</syntaxhighlight>

Lock the related OTP words manually with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<syntaxhighlight lang="shell">
fuse prog -y 0 0x10000018 1 1 1 1 1 1 1 1
</syntaxhighlight>

===== Test BootROM image authentication =====

To verify the image authentication by the BootROM with the programmed PKH and the programmed signed images, you must reboot your device.

On the third line of the U-Boot SPL output, check the BootROM authentication status.
The status output should look like this: <syntaxhighlight lang="console" inline>Bootrom authentication: succeeded</syntaxhighlight>.
Note the <syntaxhighlight lang="console" inline>succeeded</syntaxhighlight> status for successful authentication of the U-Boot SPL image by the BootROM.

The following output shows successful authentication of the U-Boot-SPL image in line 3, as well as successful authentication of the used configuration in line 7 and the U-Boot and Device Tree subimages in lines 8 and 9 of the U-Boot-FIT image.
<syntaxhighlight lang="console" line highlight="3,7-9">
U-Boot SPL 2022.01-00012-g6c5892c90c28 (Feb 16 2022 - 11:11:16 +0100)
Model: STMicroelectronics STM32MP15xx DHCOM Premium Developer Kit (2)
Bootrom authentication: succeeded
Code: SoM:rev=1,ddr3=3 Board:rev=0
RAM: DDR3L 32bits 2x4Gb 533MHz
Trying to boot from SPI
## Checking hash(es) for config config-2 ... sha256,rsa4096:fsbl-cfg-2022-02-16+ OK
## Checking hash(es) for Image uboot ... sha256,rsa4096:fsbl-img-2022-02-16+ sha256+ OK
## Checking hash(es) for Image fdt-1 ... sha256,rsa4096:fsbl-img-2022-02-16+ sha256+ OK
</syntaxhighlight>

===== Enforce BootROM image authentication =====

Without any further changes, the BootROM is able to perform authentication of the FSBL image, but unauthenticated images can still be used and executed.
The device is still open, let's see this as a kind of test mode to check if the PKH is set correctly.

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

The 6th bit in the 1st word of the OTP is responsible that the BootROM only accepts signed images.
Burning this bit enforces authentication of images by the BootROM and unsigned binaries are no longer supported on the target device.

To program this bit, the U-Boot Shell can be used with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command or with the more general <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command.

With usage of the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command:
<div style="color:red">Warning: After running the following command, your device will only be able to boot signed images!</div>
<syntaxhighlight lang="shell">
stm32key close
</syntaxhighlight>

Or with usage of the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<div style="color:red">Warning: After running the following command, your device will only be able to boot signed images!</div>
<syntaxhighlight lang="shell">
fuse prog 0 0x0 0x40
</syntaxhighlight>

== Secure Boot in Trusted Boot with BootROM authentication, TF-A and OP-TEE ==

<div style="color:red">TODO:</div>
# Add support for STM32MP15 DHCOM in <ref name="TF-A" />
# Add support for STM32MP15 DHCOM in <ref name="OP-TEE/optee_os" />
# Create stm32mp15_dhcom_trusted_defconfig???
# Integrate STM32MP15 DHCOM into <ref name="OP-TEE/build" />

== References ==

<references>
<ref name="UEFI specification">[http://www.uefi.org/specifications http://www.uefi.org/specifications]</ref>
<ref name="Basic Boot">[https://source.denx.de/u-boot/u-boot/-/blob/master/configs/stm32mp15_basic_defconfig U-Boot Source stm32mp15_basic_defconfig]</ref>
<ref name="Trusted Boot">[https://source.denx.de/u-boot/u-boot/-/blob/master/configs/stm32mp15_trusted_defconfig U-Boot Source stm32mp15_trusted_defconfig]</ref>
<ref name="BSI TR-02102">[https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.pdf BSI - Technische Richtlinie, "Kryptographische Algorithmen und Schlüssellängen", BSI TR-02102-1]</ref>
<ref name="STM32 image header">[https://wiki.st.com/stm32mpu/wiki/STM32_header_for_binary_files STM32 header for binary files]</ref>
<ref name="KeyGen_tool">[https://wiki.st.com/stm32mpu/wiki/KeyGen_tool STM32MP KeyGen tool]</ref>
<ref name="Signing_tool">[https://wiki.st.com/stm32mpu/wiki/Signing_tool STM32MP Signing tool]</ref>
<ref name="TF-A">[https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/ Trusted Firmware-A (TF-A)]</ref>
<ref name="OP-TEE/optee_os">[https://github.com/OP-TEE/optee_os OP-TEE Trusted OS]</ref>
<ref name="OP-TEE/build">[https://github.com/OP-TEE/build Makefiles to use OP-TEE on various platforms]</ref>
</references>

DHCOM STM32MP15 Secure Boot

2022-03-22T11:55:09Z

Dkierner: Add instruction for adding the STM32CubeProgrammer tools to the user PATH-variable /* Tutorial: Secure boot from BootROM to Linux with basic boot */

DHCOM STM32MP15 Secure Boot

2022-03-22T11:20:39Z

Dkierner: Fix plural in /* Run the build script build_signed_uboot.sh */

<div class="toclimit-3">__TOC__</div>

== Introduction ==

=== Abbreviations ===

{| class="wikitable sortable"
|-
! Abbreviation !! Description
|-
| BSI || Bundesamt für Sicherheit in der Informationstechnik
|-
| CoM || Computer on module
|-
| FIT || Flattened Image Tree
|-
| FSBL || Fist Stage Bootloader (TF-A or U-Boot SPL)
|-
| OTP || One Time Programmable (eFuses)
|-
| OP-TEE || Open Portable Trusted Execution Environment
|-
| PKH || Public Key Hash
|-
| ROM || Read-Only Memory
|-
| RSA || Rivest, Shamir und Adleman (asynchronous encryption)
|-
| SHA || Secure Hash Algorithm
|-
| SoC || System on chip
|-
| SoM || System on module
|-
| SSBL || Second Stage Bootloader (U-Boot)
|-
| TF-A || Trusted Firmware A
|}

=== Secure Boot ===

The term Secure Boot originally comes from the UEFI specification<ref name="UEFI specification" /> and describes a secure boot process in which only signed software is loaded and executed during the boot process.

Secure Boot is a necessary cornerstone for enforcing security mechanisms in a trusted computing environment.
Enforcing the execution of signed software only during the boot process, as long as the chain of trust is secure, can guarantee that said software is free from tampering, as any manipulation will invalidate the software's signature and prevent the software from being executed.

[[File:Secure Boot Generic en.png|600px|Secure Boot Generic]]

The figure [[Media:Secure Boot Generic en.png|Secure Boot Generic]] shows an example of a secure boot process that leads to a reset in the event of an error in the signature check. Each stage uses the certificate and signature to check the origin and integrity of the next stage. On success, the next stage is executed, and in the event of an error, this always leads to a defined error state. In the simplest case, the certificates are integrated into the binary image of the previous stage.

Program code and certificate need to be trustworthy and therefore protected against tampering in each stage, otherwise the secure boot chain can be compromised. Except for the first stage, all binary images are protected against third-party tampering by the signature. As this is practically impossible for the first stage, manipulation protection has to be enforced by hardware measures to make said stage immutable, with the first stage's program code and the verification certificate for the second stage being stored in read-only memory (ROM).

=== Basic and trusted boot in the context of Secure Boot ===

When booting Linux on the STM32MP1 SoC with U-Boot SPL and U-Boot only, STM speaks of "Basic Boot"<ref name="Basic Boot" />.
However, if Linux is booted with a combination of TF-A, U-Boot and OP-TEE, STM refers to this as "Trusted Boot"<ref name="Trusted Boot" />.

{| class="wikitable"
|-
! Boot chain !! Description
|-
| Basic boot || BootROM -> U-Boot SPL -> U-Boot -> Linux
|-
| Trusted boot || BootROM -> TF-A -> U-Boot + OP-TEE -> Linux
|}

== Secure Boot in Basic Boot with BootROM authentication and Verified Boot ==

This Secure Boot implementation does use the the BootROM integrated image authentication to authenticate the U-Boot SPL as FSBL.
Authentication of U-Boot as SSBL by the U-Boot SPL and authentication of the Linux kernel, Device Tree and ramdisk by U-Boot is done using the open source implementation [[#Verified Boot|Verified Boot]].

This also means that everything from U-Boot SPL onwards is platform independent, as we do not rely on hardware specific implementations.

=== Verified Boot ===

Developers of Google's Chromium project worked out a concept for the Verified Boot called Secure Boot mechanism on the basis of the boot loader "Das U-Boot".
They use the existing infrastructure of the FIT images and for the system configuration at runtime via a Device Tree.
The description language for the FIT images was extended by an additional signature node and the Device Tree of the platform was used to store the certificate(s) for the authentication of the images.
The signature node can be used to sign individual subimages as well as combinations of individual subimages in the FIT image.
The tool <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight> takes care the signature creation for the FIT images and the addition of the certificate in a Device Tree.

With Verified Boot, the Device Tree with included public key is integrated into the program image of the stage, which accomplishes the authentication and is thus very similar to the general procedure shown in figure [[Media:Secure Boot Generic en.png|Secure Boot Generic]].
The number of public keys that can be integrated is theoretically unlimited, but they must be distinguishable by name.

==== Technical details of Verified Boot ====

{| class="wikitable"
|-
| '''Name'''
| Verified Boot
|-
| '''Implementierung'''
| Software (Open Source)
|-
| '''Hash algorithms'''
|
* SHA1 (deprecated)<ref name="BSI TR-02102" />
* SHA256
* SHA384
* SHA512
|-
| '''Crypto algorithms
|
* RSA2048 (deprecated as of 2024)<ref name="BSI TR-02102" />
* RSA4096

* ECDSA256 (currently limited to U-Boot SPL)
|-
| '''Number of key pairs'''
| unlimited
|-
|}

==== In-depth references for Verified Boot ====


===== Flatten Image Tree =====
* [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT U-Boot Documentation: doc/uImage.FIT]
* [https://source.denx.de/u-boot/u-boot/-/commit/d5934ad7 U-Boot Commit d5934ad7: "new uImage: Add dual format uImage support framework"]
* ...
* [https://source.denx.de/u-boot/u-boot/-/commit/3310c549 U-Boot Commit d5934ad7: "new uImage: Add new uImage format documentation and examples"]

===== Verified Boot =====

* [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT/signature.txt U-Boot Documentation: doc/uImage.FIT/signature.txt]
* [https://source.denx.de/u-boot/u-boot/-/commit/3e569a6b U-Boot Commit 3e569a6b: "image: Add signing infrastructure"]
* [https://source.denx.de/u-boot/u-boot/-/commit/56518e71 U-Boot Commit 56518e71: "image: Support signing of images"]
* [https://source.denx.de/u-boot/u-boot/-/commit/4d098529 U-Boot Commit 4d098529: "image: Add support for signing of FIT configurations"]

===== ECDSA signature verification =====

<div style="color:red">TODO: Mention ECDSA limitations</div>
Note: This has currently some limitations!


* [https://source.denx.de/u-boot/u-boot/-/commit/928a8be7 U-Boot Commit 928a8be7: "lib: ecdsa: Implement UCLASS_ECDSA verification on target"]
* [https://source.denx.de/u-boot/u-boot/-/commit/ee870859 U-Boot Commit ee870859: "arm: stm32mp1: Implement ECDSA signature verification"]

=== Tutorial: Secure boot from BootROM to Linux with basic boot ===

==== System requirements and needed tools ====

The following table lists all requirements to create the key pairs and build the signed images with embedded public keys.

{| class="wikitable"
|-
! Category !! Description
|-
| '''Host operating system''' ||
* Linux (Debian 9, Ubuntu 18.04 or higher prefered)
|-
| '''Debian packages''' ||
* bison
* device-tree-compiler
* flex
* gcc-arm-linux-gnueabihf (>= gcc 6)
* git
* make
* openssl
* swig
|-
| '''STM32 Tools''' ||
* [https://www.st.com/en/development-tools/stm32cubeprog.html STM32CubeProgrammer]
** STM32MP_KeyGen_CLI
** STM32MP_SigningTool_CLI
|}

<div style="color:red">TODO: Should we give host setup instructions?</div>


==== Intended use of the four generated key pairs ====

We've decided to create and use as few certificates as reasonable to ensure a high level of security.
Therefore, we chose a separate key pair for each boot stage and also a separate key pair for image and configuration nodes.
If you're confused about the difference between image and configuration nodes, head over to [[#Flatten Image Tree|Flatten Image Tree]] to refresh your knowledge.
The exact purpose of the four key pairs generated for Verified Boot is described in the following table.

{| class="wikitable"
|-
! File name !! Intended use
|-
| '''fsbl-img''' || Authenticate image nodes of FIT images loaded by U-Boot SPL (U-Boot, Device Tree, firmware)
|-
| '''fsbl-cfg''' || Authenticate config nodes of FIT images loaded by U-Boot SPL (U-Boot + Device Tree + firmware)
|-
| '''ssbl-img''' || Authenticate image nodes of FIT images loaded by U-Boot (Kernel, Device Tree, InitRamFS)
|-
| '''ssbl-cfg''' || Authenticate config nodes of FIT images loaded by U-Boot (Kernel + Device Tree + InitRamFS)
|-
|}

==== Created/Modified files in the U-Boot source for Verified Boot ====

The created or modified files to build U-Boot with Verified Boot on STM32MP15 are described in the following table.

{| class="wikitable"
|-
! File
! Description
|-
| build_signed_uboot.sh
| Shell script that automates the creation of key pairs, the modification of FIT source files and Device Tree's and building of U-Boot SPL and U-Boot.
|-
| board/dhelectronics/dh_stm32mp1/u-boot-dhco?.its
| FIT source files with defined U-Boot image and Device Tree's for DHSOM platforms.
|-
| board/dhelectronics/dh_stm32mp1/linux-dhcom.its
| Dummy FIT source file with defined dummy kernel image and dummy Device Tree for DHSOM platforms.<br>To avoid relying on a built kernel image on a fixed path, we created this dummy, since adding the public keys with <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight> requires a valid FIT source file.
|-
| configs/stm32mp15_dhco?_secure_defconfig
| Example U-Boot defconfig's with enabled <syntaxhighlight lang="shell" inline>CONFIG_FIT_SIGNATURE</syntaxhighlight> and <syntaxhighlight lang="shell" inline>CONFIG_SPL_FIT_SIGNATURE</syntaxhighlight>.
|}

==== Build Verified Boot enabled U-Boot SPL and U-Boot ====

To build the U-Boot SPL and U-Boot images, you need to check out the source code and run a build script that automates everything from key generation to image creation and signing.

===== Checkout source code for Verified Boot =====

<div style="color:red">TODO: Replace my personal GitLab by a public available repository</div>
Checkout the branch <syntaxhighlight lang="shell" inline>v2022.01_dhcom_secure_boot</syntaxhighlight> in my personal GitLab repository with:

<syntaxhighlight lang="shell">
git clone git@dhplgl01:jneuhauser/u-boot.git -b v2022.01_stm32mp1_dhcom_secure_boot
</syntaxhighlight>

If you already have a cloned U-Boot source code, you can also fetch it into your existing repository with:

<syntaxhighlight lang="shell">
cd /path/to/u-boot
git remote add jneuhauser git@dhplgl01:jneuhauser/u-boot.git
git fetch jneuhauser
git checkout v2022.01_dhcom_secure_boot
</syntaxhighlight>

===== Run the build script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> =====

The shell script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> included in the U-Boot source performs the following steps.
# Prebuild U-Boat SPL and U-Boat to build the required tools and Device Tree's
# Generate the [[#Intended use of the four generated key pairs|four key pairs]] if not already created
# Generate/Modify FIT image source files for Linux (dummy) and U-Boot
# Add public keys to the built Device Tree's used by U-Boot SPL and U-Boot
# Rebuild U-Boot SPL and U-Boot with new Device Tree's containing the public keys

The script supports the following environment variables to configure the target architecture, the cross compiler, the defconfig, the key algorithm, the key directory, and a key postfix:
{| class="wikitable sortable"
|-
! Name !! Description !! Default
|-
| ARCH || Target architecture for the U-Boot build || arm
|-
| CROSS_COMPILE || Used cross compiler to build U-Boot || arm-linux-gnueabihf-
|-
| DEFCONFIG || Used defconfig for the U-Boot build || stm32mp15_dhcom_secure_defconfig
|-
| KEY_ALGO || Signature algorithm used for Verified Boot || rsa
|-
| KEY_DIR || Directory where the key pairs are stored || ../keys
|-
| KEY_POSTFIX || Postfix which is appended to the key names || -$(date +%F)
|}

To perform the steps mentioned above, you just need to run the shell script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> like below.
In this example, we override the default value for <syntaxhighlight lang="shell" inline>KEY_POSTFIX</syntaxhighlight> with <syntaxhighlight lang="shell" inline>-testing</syntaxhighlight> to append this string to the [[#Intended use of the four generated key pairs|four key file names]].
The script has debug output enabled by default, which should output all the statements in the script itself and the output of the commands used in the script.
If you have any problems with the script, feel free to get in touch with [mailto:info@dh-electronics.com us] and attach a logfile.

<syntaxhighlight lang="shell">
cd /path/to/u-boot
KEY_POSTFIX="-testing" ./build_signed_uboot.sh | tee build_signed_uboot.log
</syntaxhighlight>

If this process completes without errors, there are two boot loader images in the root directory of the U-Boot source.
{| class="wikitable sortable"
|-
! File name !! Stage !! Description
|-
| u-boot-spl.stm32 || FSBL || U-Boot SPL binary with appended Device Tree and prepended STM32 image header<ref name="STM32 image header" />.
|-
| u-boot.itb || SSBL || U-Boot and Device Tree's contained in a signed FIT image.
|}

==== Generate key pair and sign U-Boot SPL for BootROM authentication ====

To sign the U-Boot SPL as SSBL image for authentication with the BootROM we have to use the STM32 tools <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight> and <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight>.

===== Generate key pair with <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight> =====

All STM32MP15 SoCs only support one key pair for authenticating images through the BootROM.
To generate a ECDSA key pair for the STM32MP Secure Boot use the tool <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight><ref name="KeyGen_tool" />:
<syntaxhighlight lang="shell">
STM32MP_KeyGen_CLI --absolute-path "$(pwd)" --password <a secure password>
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Key Generator v2.9.0
-------------------------------------------------------------------

Prime256v1 curve is selected.
AES_256_cbc algorithm is selected for private key encryption
Generating Prime256v1 keys...
Private key PEM file created
Public key PEM file created
public key hash file created
Keys generated successfully.
+ public key: publicKey.pem
+ private key: privateKey.pem
+ public hash key: publicKeyhash.bin
</syntaxhighlight>

===== Sign U-Boot SPL with <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight> =====

To add the public key and the image signature to our built U-Boot SPL binary with STM32 image header, we are using the tool <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight><ref name="Signing_tool" /> to update the existing STM32 image header of <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> with the required details.
<syntaxhighlight lang="shell">
STM32MP_SigningTool_CLI --binary-image /path/to/u-boot/u-boot-spl.stm32 --public-key publicKey.pem --private-key privateKey.pem --password <a secure password> --output /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Signing Tool v2.9.0
-------------------------------------------------------------------

Prime256v1 curve is selected.
Header version 1 preparation ...
Reading Private Key File...
ECDSA signature generated.
Signature verification: SUCCESS
The Signed image file generated successfully: /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>

You can check the STM32 image header details with:
<syntaxhighlight lang="shell">
STM32MP_SigningTool_CLI --dump-header /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Signing Tool v2.9.0
-------------------------------------------------------------------

Header description:

Magic: 0x53544d32
Signature: c8 30 a0 62 2d 6d 4e 1b b9 f7 fe 38 27 65 e0 44 f0 f5 9d e6 8a a6 02 cb 74 52 26 9c 1e e9 07 17
1a c7 da 8e 96 fa 82 d3 b1 dc d5 3a 05 0e 87 83 94 4d 47 ad 17 07 88 0d b5 ae 2e 38 1d 90 22 ad
Checksum: 0xa8ca85
Header version: 0x10000
Size: 0x22dec
Load address: 0x2ffc2500
Entry point: 0x2ffc2500
Image version: 0x0
Option flags: 0x0
ECDSA Algo: 0x1
ECDSA pub key: 3b 71 8e 59 f1 ee 4c a8 4b 72 5f 4a 1c 63 8b 6e b8 01 ec 1a 3f 8c 98 2f d2 1d 77 f9 09 10 8f 04
30 da 5c 3a 24 53 0d 71 93 f0 a5 d9 c9 a7 27 b4 5f a5 c4 4d 55 8b 7a 25 e3 03 ef ca 87 ff 04 25
Binary type: 0x0
</syntaxhighlight>
The difference to an unsigned STM32 image header is that the values for "Signature" and "ECDSA pub key" are not all zeros and that "Option flags" is 0x0 for enabled signature verification instead of 0x1 for disabled signature verification.

==== Write U-Boot SPL and U-Boot to your boot media ====

The first step to verify that the built U-Boot SPL and U-Boot works as expected is to program both images to your boot media.
Depending on the boot configuration, your DHSOM will boot from the module's SPI-NOR flash, from the module's or baseboard's eMMC or from an SD card.
The boot configuration is always defined by the boot pins by default, because the boot pins have no alternative function on the STM32MP15 SoCs.

<div style="color:red">TODO: How can a user determine the used boot media?</div>
<div style="color:red">TODO: How to enforce boot media on Secure Boot enabled devices?</div>

===== Write U-Boot SPL and U-Boot to the SPI-NOR flash of the SoM =====

The following '''commands for the U-Boot Shell''' calculate some addresses based on the image offsets expected by the BootROM, load the required images from SD card or via TFTP into memory and finally write the prepared memory into the SPI-NOR flash on the SoM.

Prepare for loading <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> into memory:
<syntaxhighlight lang="shell">
mw.b ${loadaddr} 0xff 0x200000
setexpr fsbl1addr ${loadaddr} + 0x0
setexpr fsbl2addr ${loadaddr} + 0x40000
setexpr ssbl1addr ${loadaddr} + 0x80000
</syntaxhighlight>

Load <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> from SD card:
<syntaxhighlight lang="shell">
load mmc 0:4 ${fsbl1addr} u-boot-spl.stm32
load mmc 0:4 ${fsbl2addr} u-boot-spl.stm32
load mmc 0:4 ${ssbl1addr} u-boot.itb
</syntaxhighlight>

Load <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> from tftp server:
<syntaxhighlight lang="shell">
setenv serverip 10.20.30.1
setenv ipaddr 10.20.30.100
setenv netmask 255.255.255.0
tftp ${fsbl1addr} ${serverip}:u-boot-spl.stm32
tftp ${fsbl2addr} ${serverip}:u-boot-spl.stm32
tftp ${ssbl1addr} ${serverip}:u-boot.itb
</syntaxhighlight>

Check for magic numbers of expected image headers and conditionally program the SPI-NOR flash:
<syntaxhighlight lang="shell">
if itest *${fsbl1addr} == 0x324d5453 && itest *${fsbl2addr} == 0x324d5453 && itest *${ssbl1addr} == 0xedfe0dd0; then
sf probe && sf update ${loadaddr} 0 0x200000
fi
</syntaxhighlight>

===== Write U-Boot SPL and U-Boot to an SD card =====

<div style="color:red">TODO:</div>


===== Write U-Boot SPL and U-Boot to the eMMC =====

<div style="color:red">TODO:</div>


==== Enroll, test and enforce BootROM image authentication ====

To enroll, test and enforce image authentication by the BootROM you need to program the PKH into the OTP of the STM32MP15 SoC.
The <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> file that you created in the [[#Generate key pair with STM32MP_KeyGen_CLI|Generate key pair with STM32MP_KeyGen_CLI]] step contains the PKH in binary format for use with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> U-Boot command.
If the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command does fail or is not available on the target U-Boot, you can also write the PKH manually with the more generic <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command into the OTP.

===== Program public key hash to eFuses =====

The following '''commands for the U-Boot Shell''' load the file <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> into memory and program the contained PKH to the OTP of the STM32MP15 SoC.
The used command <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> writes and locks the words of the OTP automatically without knowing anything about the OTP layout/addresses.
If this fails or the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command is not available, you can also write and lock the OTP with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command

====== Program <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> into OTP with <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command ======

Load <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> from SD card:
<syntaxhighlight lang="shell">
load mmc 0:4 ${loadaddr} publicKeyhash.bin
</syntaxhighlight>

Or load <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> per TFTP:
<syntaxhighlight lang="shell">
setenv serverip 10.20.30.1
setenv ipaddr 10.20.30.100
setenv netmask 255.255.255.0
tftp ${loadaddr} ${serverip}:publicKeyhash.bin
</syntaxhighlight>

Show the contents of <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight>:
<syntaxhighlight lang="shell">
stm32key read ${loadaddr}
</syntaxhighlight>
<syntaxhighlight lang="console">
Read KEY at 0xc2000000
OTP value 24: 4e31bbcd
OTP value 25: 51e827dd
OTP value 26: 3511f521
OTP value 27: fd9c11a2
OTP value 28: 5b997b82
OTP value 29: 8150adc5
OTP value 30: a9c68fa9
OTP value 31: 72a3ba74
</syntaxhighlight>

Write the contents of <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> to OTP with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command:
<syntaxhighlight lang="shell">
stm32key fuse ${loadaddr}
</syntaxhighlight>
<syntaxhighlight lang="console">
TODO: Add output
</syntaxhighlight>

====== Program PKH manually into OTP with <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command ======

Generate fuse command with hexdump from file <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> on linux host:
<div style="color:red">Warning: Do not use the example output! Only use your unique values for programming the PKH in the OTP!</div>
<syntaxhighlight lang="shell">
echo fuse prog -y 0 0x18 $(hexdump -e '/4 "0x"' -e '/1 "%x"' -e '" "' /path/to/publicKeyhash.bin)
</syntaxhighlight>
<syntaxhighlight lang="console">
fuse prog -y 0 0x18 0x4e31bbcd 0x51e827dd 0x3511f521 0xfd9c11a2 0x5b997b82 0x8150adc5 0xa9c68fa9 0x72a3ba74
</syntaxhighlight>

Write the PKH into OTP manually with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<div style="color:red">Warning: Do not use the example command! Only use your unique values for programming the PKH in the OTP!</div>
<syntaxhighlight lang="shell">
fuse prog -y 0 0x18 0x4e31bbcd 0x51e827dd 0x3511f521 0xfd9c11a2 0x5b997b82 0x8150adc5 0xa9c68fa9 0x72a3ba74
</syntaxhighlight>

Lock the related OTP words manually with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<syntaxhighlight lang="shell">
fuse prog -y 0 0x10000018 1 1 1 1 1 1 1 1
</syntaxhighlight>

===== Test BootROM image authentication =====

To verify the image authentication by the BootROM with the programmed PKH and the programmed signed images, you must reboot your device.

On the third line of the U-Boot SPL output, check the BootROM authentication status.
The status output should look like this: <syntaxhighlight lang="console" inline>Bootrom authentication: succeeded</syntaxhighlight>.
Note the <syntaxhighlight lang="console" inline>succeeded</syntaxhighlight> status for successful authentication of the U-Boot SPL image by the BootROM.

The following output shows successful authentication of the U-Boot-SPL image in line 3, as well as successful authentication of the used configuration in line 7 and the U-Boot and Device Tree subimages in lines 8 and 9 of the U-Boot-FIT image.
<syntaxhighlight lang="console" line highlight="3,7-9">
U-Boot SPL 2022.01-00012-g6c5892c90c28 (Feb 16 2022 - 11:11:16 +0100)
Model: STMicroelectronics STM32MP15xx DHCOM Premium Developer Kit (2)
Bootrom authentication: succeeded
Code: SoM:rev=1,ddr3=3 Board:rev=0
RAM: DDR3L 32bits 2x4Gb 533MHz
Trying to boot from SPI
## Checking hash(es) for config config-2 ... sha256,rsa4096:fsbl-cfg-2022-02-16+ OK
## Checking hash(es) for Image uboot ... sha256,rsa4096:fsbl-img-2022-02-16+ sha256+ OK
## Checking hash(es) for Image fdt-1 ... sha256,rsa4096:fsbl-img-2022-02-16+ sha256+ OK
</syntaxhighlight>

===== Enforce BootROM image authentication =====

Without any further changes, the BootROM is able to perform authentication of the FSBL image, but unauthenticated images can still be used and executed.
The device is still open, let's see this as a kind of test mode to check if the PKH is set correctly.

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

The 6th bit in the 1st word of the OTP is responsible that the BootROM only accepts signed images.
Burning this bit enforces authentication of images by the BootROM and unsigned binaries are no longer supported on the target device.

To program this bit, the U-Boot Shell can be used with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command or with the more general <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command.

With usage of the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command:
<div style="color:red">Warning: After running the following command, your device will only be able to boot signed images!</div>
<syntaxhighlight lang="shell">
stm32key close
</syntaxhighlight>

Or with usage of the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<div style="color:red">Warning: After running the following command, your device will only be able to boot signed images!</div>
<syntaxhighlight lang="shell">
fuse prog 0 0x0 0x40
</syntaxhighlight>

== Secure Boot in Trusted Boot with BootROM authentication, TF-A and OP-TEE ==

<div style="color:red">TODO:</div>
# Add support for STM32MP15 DHCOM in <ref name="TF-A" />
# Add support for STM32MP15 DHCOM in <ref name="OP-TEE/optee_os" />
# Create stm32mp15_dhcom_trusted_defconfig???
# Integrate STM32MP15 DHCOM into <ref name="OP-TEE/build" />

== References ==

<references>
<ref name="UEFI specification">[http://www.uefi.org/specifications http://www.uefi.org/specifications]</ref>
<ref name="Basic Boot">[https://source.denx.de/u-boot/u-boot/-/blob/master/configs/stm32mp15_basic_defconfig U-Boot Source stm32mp15_basic_defconfig]</ref>
<ref name="Trusted Boot">[https://source.denx.de/u-boot/u-boot/-/blob/master/configs/stm32mp15_trusted_defconfig U-Boot Source stm32mp15_trusted_defconfig]</ref>
<ref name="BSI TR-02102">[https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.pdf BSI - Technische Richtlinie, "Kryptographische Algorithmen und Schlüssellängen", BSI TR-02102-1]</ref>
<ref name="STM32 image header">[https://wiki.st.com/stm32mpu/wiki/STM32_header_for_binary_files STM32 header for binary files]</ref>
<ref name="KeyGen_tool">[https://wiki.st.com/stm32mpu/wiki/KeyGen_tool STM32MP KeyGen tool]</ref>
<ref name="Signing_tool">[https://wiki.st.com/stm32mpu/wiki/Signing_tool STM32MP Signing tool]</ref>
<ref name="TF-A">[https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/ Trusted Firmware-A (TF-A)]</ref>
<ref name="OP-TEE/optee_os">[https://github.com/OP-TEE/optee_os OP-TEE Trusted OS]</ref>
<ref name="OP-TEE/build">[https://github.com/OP-TEE/build Makefiles to use OP-TEE on various platforms]</ref>
</references>

DHCOM STM32MP15 Secure Boot

2022-03-22T11:18:37Z

Dkierner: Add swig to required debian packages /* System requirements and needed tools */

<div class="toclimit-3">__TOC__</div>

== Introduction ==

=== Abbreviations ===

{| class="wikitable sortable"
|-
! Abbreviation !! Description
|-
| BSI || Bundesamt für Sicherheit in der Informationstechnik
|-
| CoM || Computer on module
|-
| FIT || Flattened Image Tree
|-
| FSBL || Fist Stage Bootloader (TF-A or U-Boot SPL)
|-
| OTP || One Time Programmable (eFuses)
|-
| OP-TEE || Open Portable Trusted Execution Environment
|-
| PKH || Public Key Hash
|-
| ROM || Read-Only Memory
|-
| RSA || Rivest, Shamir und Adleman (asynchronous encryption)
|-
| SHA || Secure Hash Algorithm
|-
| SoC || System on chip
|-
| SoM || System on module
|-
| SSBL || Second Stage Bootloader (U-Boot)
|-
| TF-A || Trusted Firmware A
|}

=== Secure Boot ===

The term Secure Boot originally comes from the UEFI specification<ref name="UEFI specification" /> and describes a secure boot process in which only signed software is loaded and executed during the boot process.

Secure Boot is a necessary cornerstone for enforcing security mechanisms in a trusted computing environment.
Enforcing the execution of signed software only during the boot process, as long as the chain of trust is secure, can guarantee that said software is free from tampering, as any manipulation will invalidate the software's signature and prevent the software from being executed.

[[File:Secure Boot Generic en.png|600px|Secure Boot Generic]]

The figure [[Media:Secure Boot Generic en.png|Secure Boot Generic]] shows an example of a secure boot process that leads to a reset in the event of an error in the signature check. Each stage uses the certificate and signature to check the origin and integrity of the next stage. On success, the next stage is executed, and in the event of an error, this always leads to a defined error state. In the simplest case, the certificates are integrated into the binary image of the previous stage.

Program code and certificate need to be trustworthy and therefore protected against tampering in each stage, otherwise the secure boot chain can be compromised. Except for the first stage, all binary images are protected against third-party tampering by the signature. As this is practically impossible for the first stage, manipulation protection has to be enforced by hardware measures to make said stage immutable, with the first stage's program code and the verification certificate for the second stage being stored in read-only memory (ROM).

=== Basic and trusted boot in the context of Secure Boot ===

When booting Linux on the STM32MP1 SoC with U-Boot SPL and U-Boot only, STM speaks of "Basic Boot"<ref name="Basic Boot" />.
However, if Linux is booted with a combination of TF-A, U-Boot and OP-TEE, STM refers to this as "Trusted Boot"<ref name="Trusted Boot" />.

{| class="wikitable"
|-
! Boot chain !! Description
|-
| Basic boot || BootROM -> U-Boot SPL -> U-Boot -> Linux
|-
| Trusted boot || BootROM -> TF-A -> U-Boot + OP-TEE -> Linux
|}

== Secure Boot in Basic Boot with BootROM authentication and Verified Boot ==

This Secure Boot implementation does use the the BootROM integrated image authentication to authenticate the U-Boot SPL as FSBL.
Authentication of U-Boot as SSBL by the U-Boot SPL and authentication of the Linux kernel, Device Tree and ramdisk by U-Boot is done using the open source implementation [[#Verified Boot|Verified Boot]].

This also means that everything from U-Boot SPL onwards is platform independent, as we do not rely on hardware specific implementations.

=== Verified Boot ===

Developers of Google's Chromium project worked out a concept for the Verified Boot called Secure Boot mechanism on the basis of the boot loader "Das U-Boot".
They use the existing infrastructure of the FIT images and for the system configuration at runtime via a Device Tree.
The description language for the FIT images was extended by an additional signature node and the Device Tree of the platform was used to store the certificate(s) for the authentication of the images.
The signature node can be used to sign individual subimages as well as combinations of individual subimages in the FIT image.
The tool <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight> takes care the signature creation for the FIT images and the addition of the certificate in a Device Tree.

With Verified Boot, the Device Tree with included public key is integrated into the program image of the stage, which accomplishes the authentication and is thus very similar to the general procedure shown in figure [[Media:Secure Boot Generic en.png|Secure Boot Generic]].
The number of public keys that can be integrated is theoretically unlimited, but they must be distinguishable by name.

==== Technical details of Verified Boot ====

{| class="wikitable"
|-
| '''Name'''
| Verified Boot
|-
| '''Implementierung'''
| Software (Open Source)
|-
| '''Hash algorithms'''
|
* SHA1 (deprecated)<ref name="BSI TR-02102" />
* SHA256
* SHA384
* SHA512
|-
| '''Crypto algorithms
|
* RSA2048 (deprecated as of 2024)<ref name="BSI TR-02102" />
* RSA4096

* ECDSA256 (currently limited to U-Boot SPL)
|-
| '''Number of key pairs'''
| unlimited
|-
|}

==== In-depth references for Verified Boot ====


===== Flatten Image Tree =====
* [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT U-Boot Documentation: doc/uImage.FIT]
* [https://source.denx.de/u-boot/u-boot/-/commit/d5934ad7 U-Boot Commit d5934ad7: "new uImage: Add dual format uImage support framework"]
* ...
* [https://source.denx.de/u-boot/u-boot/-/commit/3310c549 U-Boot Commit d5934ad7: "new uImage: Add new uImage format documentation and examples"]

===== Verified Boot =====

* [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT/signature.txt U-Boot Documentation: doc/uImage.FIT/signature.txt]
* [https://source.denx.de/u-boot/u-boot/-/commit/3e569a6b U-Boot Commit 3e569a6b: "image: Add signing infrastructure"]
* [https://source.denx.de/u-boot/u-boot/-/commit/56518e71 U-Boot Commit 56518e71: "image: Support signing of images"]
* [https://source.denx.de/u-boot/u-boot/-/commit/4d098529 U-Boot Commit 4d098529: "image: Add support for signing of FIT configurations"]

===== ECDSA signature verification =====

<div style="color:red">TODO: Mention ECDSA limitations</div>
Note: This has currently some limitations!


* [https://source.denx.de/u-boot/u-boot/-/commit/928a8be7 U-Boot Commit 928a8be7: "lib: ecdsa: Implement UCLASS_ECDSA verification on target"]
* [https://source.denx.de/u-boot/u-boot/-/commit/ee870859 U-Boot Commit ee870859: "arm: stm32mp1: Implement ECDSA signature verification"]

=== Tutorial: Secure boot from BootROM to Linux with basic boot ===

==== System requirements and needed tools ====

The following table lists all requirements to create the key pairs and build the signed images with embedded public keys.

{| class="wikitable"
|-
! Category !! Description
|-
| '''Host operating system''' ||
* Linux (Debian 9, Ubuntu 18.04 or higher prefered)
|-
| '''Debian packages''' ||
* bison
* device-tree-compiler
* flex
* gcc-arm-linux-gnueabihf (>= gcc 6)
* git
* make
* openssl
* swig
|-
| '''STM32 Tools''' ||
* [https://www.st.com/en/development-tools/stm32cubeprog.html STM32CubeProgrammer]
** STM32MP_KeyGen_CLI
** STM32MP_SigningTool_CLI
|}

<div style="color:red">TODO: Should we give host setup instructions?</div>


==== Intended use of the four generated key pairs ====

We've decided to create and use as few certificates as reasonable to ensure a high level of security.
Therefore, we chose a separate key pair for each boot stage and also a separate key pair for image and configuration nodes.
If you're confused about the difference between image and configuration nodes, head over to [[#Flatten Image Tree|Flatten Image Tree]] to refresh your knowledge.
The exact purpose of the four key pairs generated for Verified Boot is described in the following table.

{| class="wikitable"
|-
! File name !! Intended use
|-
| '''fsbl-img''' || Authenticate image nodes of FIT images loaded by U-Boot SPL (U-Boot, Device Tree, firmware)
|-
| '''fsbl-cfg''' || Authenticate config nodes of FIT images loaded by U-Boot SPL (U-Boot + Device Tree + firmware)
|-
| '''ssbl-img''' || Authenticate image nodes of FIT images loaded by U-Boot (Kernel, Device Tree, InitRamFS)
|-
| '''ssbl-cfg''' || Authenticate config nodes of FIT images loaded by U-Boot (Kernel + Device Tree + InitRamFS)
|-
|}

==== Created/Modified files in the U-Boot source for Verified Boot ====

The created or modified files to build U-Boot with Verified Boot on STM32MP15 are described in the following table.

{| class="wikitable"
|-
! File
! Description
|-
| build_signed_uboot.sh
| Shell script that automates the creation of key pairs, the modification of FIT source files and Device Tree's and building of U-Boot SPL and U-Boot.
|-
| board/dhelectronics/dh_stm32mp1/u-boot-dhco?.its
| FIT source files with defined U-Boot image and Device Tree's for DHSOM platforms.
|-
| board/dhelectronics/dh_stm32mp1/linux-dhcom.its
| Dummy FIT source file with defined dummy kernel image and dummy Device Tree for DHSOM platforms.<br>To avoid relying on a built kernel image on a fixed path, we created this dummy, since adding the public keys with <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight> requires a valid FIT source file.
|-
| configs/stm32mp15_dhco?_secure_defconfig
| Example U-Boot defconfig's with enabled <syntaxhighlight lang="shell" inline>CONFIG_FIT_SIGNATURE</syntaxhighlight> and <syntaxhighlight lang="shell" inline>CONFIG_SPL_FIT_SIGNATURE</syntaxhighlight>.
|}

==== Build Verified Boot enabled U-Boot SPL and U-Boot ====

To build the U-Boot SPL and U-Boot images, you need to check out the source code and run a build script that automates everything from key generation to image creation and signing.

===== Checkout source code for Verified Boot =====

<div style="color:red">TODO: Replace my personal GitLab by a public available repository</div>
Checkout the branch <syntaxhighlight lang="shell" inline>v2022.01_dhcom_secure_boot</syntaxhighlight> in my personal GitLab repository with:

<syntaxhighlight lang="shell">
git clone git@dhplgl01:jneuhauser/u-boot.git -b v2022.01_stm32mp1_dhcom_secure_boot
</syntaxhighlight>

If you already have a cloned U-Boot source code, you can also fetch it into your existing repository with:

<syntaxhighlight lang="shell">
cd /path/to/u-boot
git remote add jneuhauser git@dhplgl01:jneuhauser/u-boot.git
git fetch jneuhauser
git checkout v2022.01_dhcom_secure_boot
</syntaxhighlight>

===== Run the build script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> =====

The shell script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> included in the U-Boot source performs the following steps.
# Prebuild U-Boat SPL and U-Boat to build the required tools and Device Tree's
# Generate the [[#Intended use of the four generated key pairs|four key pairs]] if not already created
# Generate/Modify FIT image source files for Linux (dummy) and U-Boot
# Add public keys to the built Device Tree's used by U-Boot SPL and U-Boot
# Rebuild U-Boot SPL and U-Boot with new Device Tree's containing the public keys

The script supports the following environment variables to configure the target architecture, the cross compiler, the defconfig, the key algorithm, the key directory, and a key postfix:
{| class="wikitable sortable"
|-
! Name !! Description !! Default
|-
| ARCH || Target architecture for the U-Boot build || arm
|-
| CROSS_COMPILE || Used cross compiler to build U-Boot || arm-linux-gnueabihf-
|-
| DEFCONFIG || Used defconfig for the U-Boot build || stm32mp15_dhcom_secure_defconfig
|-
| KEY_ALGO || Signature algorithm used for Verified Boot || rsa
|-
| KEY_DIR || Directory where the key pairs are stored || ../keys
|-
| KEY_POSTFIX || Postfix which is appended to the key names || -$(date +%F)
|}

To perform the steps mentioned above, you just need to run the shell script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> like below.
In this example, we override the default value for <syntaxhighlight lang="shell" inline>KEY_POSTFIX</syntaxhighlight> with <syntaxhighlight lang="shell" inline>-testing</syntaxhighlight> to append this string to the [[#Intended use of the four generated key pairs|four key file names]].
The script has debug output enabled by default, which should output all the statements in the script itself and the output of the commands used in the script.
If you have any problems with the script, feel free to get in touch with [mailto:info@dh-electronics.com us] and attach a logfile.

<syntaxhighlight lang="shell">
cd /path/to/u-boot
KEY_POSTFIX="-testing" ./build_signed_uboot.sh | tee build_signed_uboot.log
</syntaxhighlight>

If this process completes without error, there are two boot loader images in the root directory of the U-Boot source.
{| class="wikitable sortable"
|-
! File name !! Stage !! Description
|-
| u-boot-spl.stm32 || FSBL || U-Boot SPL binary with appended Device Tree and prepended STM32 image header<ref name="STM32 image header" />.
|-
| u-boot.itb || SSBL || U-Boot and Device Tree's contained in a signed FIT image.
|}

==== Generate key pair and sign U-Boot SPL for BootROM authentication ====

To sign the U-Boot SPL as SSBL image for authentication with the BootROM we have to use the STM32 tools <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight> and <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight>.

===== Generate key pair with <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight> =====

All STM32MP15 SoCs only support one key pair for authenticating images through the BootROM.
To generate a ECDSA key pair for the STM32MP Secure Boot use the tool <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight><ref name="KeyGen_tool" />:
<syntaxhighlight lang="shell">
STM32MP_KeyGen_CLI --absolute-path "$(pwd)" --password <a secure password>
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Key Generator v2.9.0
-------------------------------------------------------------------

Prime256v1 curve is selected.
AES_256_cbc algorithm is selected for private key encryption
Generating Prime256v1 keys...
Private key PEM file created
Public key PEM file created
public key hash file created
Keys generated successfully.
+ public key: publicKey.pem
+ private key: privateKey.pem
+ public hash key: publicKeyhash.bin
</syntaxhighlight>

===== Sign U-Boot SPL with <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight> =====

To add the public key and the image signature to our built U-Boot SPL binary with STM32 image header, we are using the tool <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight><ref name="Signing_tool" /> to update the existing STM32 image header of <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> with the required details.
<syntaxhighlight lang="shell">
STM32MP_SigningTool_CLI --binary-image /path/to/u-boot/u-boot-spl.stm32 --public-key publicKey.pem --private-key privateKey.pem --password <a secure password> --output /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Signing Tool v2.9.0
-------------------------------------------------------------------

Prime256v1 curve is selected.
Header version 1 preparation ...
Reading Private Key File...
ECDSA signature generated.
Signature verification: SUCCESS
The Signed image file generated successfully: /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>

You can check the STM32 image header details with:
<syntaxhighlight lang="shell">
STM32MP_SigningTool_CLI --dump-header /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Signing Tool v2.9.0
-------------------------------------------------------------------

Header description:

Magic: 0x53544d32
Signature: c8 30 a0 62 2d 6d 4e 1b b9 f7 fe 38 27 65 e0 44 f0 f5 9d e6 8a a6 02 cb 74 52 26 9c 1e e9 07 17
1a c7 da 8e 96 fa 82 d3 b1 dc d5 3a 05 0e 87 83 94 4d 47 ad 17 07 88 0d b5 ae 2e 38 1d 90 22 ad
Checksum: 0xa8ca85
Header version: 0x10000
Size: 0x22dec
Load address: 0x2ffc2500
Entry point: 0x2ffc2500
Image version: 0x0
Option flags: 0x0
ECDSA Algo: 0x1
ECDSA pub key: 3b 71 8e 59 f1 ee 4c a8 4b 72 5f 4a 1c 63 8b 6e b8 01 ec 1a 3f 8c 98 2f d2 1d 77 f9 09 10 8f 04
30 da 5c 3a 24 53 0d 71 93 f0 a5 d9 c9 a7 27 b4 5f a5 c4 4d 55 8b 7a 25 e3 03 ef ca 87 ff 04 25
Binary type: 0x0
</syntaxhighlight>
The difference to an unsigned STM32 image header is that the values for "Signature" and "ECDSA pub key" are not all zeros and that "Option flags" is 0x0 for enabled signature verification instead of 0x1 for disabled signature verification.

==== Write U-Boot SPL and U-Boot to your boot media ====

The first step to verify that the built U-Boot SPL and U-Boot works as expected is to program both images to your boot media.
Depending on the boot configuration, your DHSOM will boot from the module's SPI-NOR flash, from the module's or baseboard's eMMC or from an SD card.
The boot configuration is always defined by the boot pins by default, because the boot pins have no alternative function on the STM32MP15 SoCs.

<div style="color:red">TODO: How can a user determine the used boot media?</div>
<div style="color:red">TODO: How to enforce boot media on Secure Boot enabled devices?</div>

===== Write U-Boot SPL and U-Boot to the SPI-NOR flash of the SoM =====

The following '''commands for the U-Boot Shell''' calculate some addresses based on the image offsets expected by the BootROM, load the required images from SD card or via TFTP into memory and finally write the prepared memory into the SPI-NOR flash on the SoM.

Prepare for loading <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> into memory:
<syntaxhighlight lang="shell">
mw.b ${loadaddr} 0xff 0x200000
setexpr fsbl1addr ${loadaddr} + 0x0
setexpr fsbl2addr ${loadaddr} + 0x40000
setexpr ssbl1addr ${loadaddr} + 0x80000
</syntaxhighlight>

Load <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> from SD card:
<syntaxhighlight lang="shell">
load mmc 0:4 ${fsbl1addr} u-boot-spl.stm32
load mmc 0:4 ${fsbl2addr} u-boot-spl.stm32
load mmc 0:4 ${ssbl1addr} u-boot.itb
</syntaxhighlight>

Load <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> from tftp server:
<syntaxhighlight lang="shell">
setenv serverip 10.20.30.1
setenv ipaddr 10.20.30.100
setenv netmask 255.255.255.0
tftp ${fsbl1addr} ${serverip}:u-boot-spl.stm32
tftp ${fsbl2addr} ${serverip}:u-boot-spl.stm32
tftp ${ssbl1addr} ${serverip}:u-boot.itb
</syntaxhighlight>

Check for magic numbers of expected image headers and conditionally program the SPI-NOR flash:
<syntaxhighlight lang="shell">
if itest *${fsbl1addr} == 0x324d5453 && itest *${fsbl2addr} == 0x324d5453 && itest *${ssbl1addr} == 0xedfe0dd0; then
sf probe && sf update ${loadaddr} 0 0x200000
fi
</syntaxhighlight>

===== Write U-Boot SPL and U-Boot to an SD card =====

<div style="color:red">TODO:</div>


===== Write U-Boot SPL and U-Boot to the eMMC =====

<div style="color:red">TODO:</div>


==== Enroll, test and enforce BootROM image authentication ====

To enroll, test and enforce image authentication by the BootROM you need to program the PKH into the OTP of the STM32MP15 SoC.
The <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> file that you created in the [[#Generate key pair with STM32MP_KeyGen_CLI|Generate key pair with STM32MP_KeyGen_CLI]] step contains the PKH in binary format for use with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> U-Boot command.
If the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command does fail or is not available on the target U-Boot, you can also write the PKH manually with the more generic <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command into the OTP.

===== Program public key hash to eFuses =====

The following '''commands for the U-Boot Shell''' load the file <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> into memory and program the contained PKH to the OTP of the STM32MP15 SoC.
The used command <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> writes and locks the words of the OTP automatically without knowing anything about the OTP layout/addresses.
If this fails or the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command is not available, you can also write and lock the OTP with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command

====== Program <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> into OTP with <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command ======

Load <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> from SD card:
<syntaxhighlight lang="shell">
load mmc 0:4 ${loadaddr} publicKeyhash.bin
</syntaxhighlight>

Or load <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> per TFTP:
<syntaxhighlight lang="shell">
setenv serverip 10.20.30.1
setenv ipaddr 10.20.30.100
setenv netmask 255.255.255.0
tftp ${loadaddr} ${serverip}:publicKeyhash.bin
</syntaxhighlight>

Show the contents of <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight>:
<syntaxhighlight lang="shell">
stm32key read ${loadaddr}
</syntaxhighlight>
<syntaxhighlight lang="console">
Read KEY at 0xc2000000
OTP value 24: 4e31bbcd
OTP value 25: 51e827dd
OTP value 26: 3511f521
OTP value 27: fd9c11a2
OTP value 28: 5b997b82
OTP value 29: 8150adc5
OTP value 30: a9c68fa9
OTP value 31: 72a3ba74
</syntaxhighlight>

Write the contents of <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> to OTP with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command:
<syntaxhighlight lang="shell">
stm32key fuse ${loadaddr}
</syntaxhighlight>
<syntaxhighlight lang="console">
TODO: Add output
</syntaxhighlight>

====== Program PKH manually into OTP with <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command ======

Generate fuse command with hexdump from file <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> on linux host:
<div style="color:red">Warning: Do not use the example output! Only use your unique values for programming the PKH in the OTP!</div>
<syntaxhighlight lang="shell">
echo fuse prog -y 0 0x18 $(hexdump -e '/4 "0x"' -e '/1 "%x"' -e '" "' /path/to/publicKeyhash.bin)
</syntaxhighlight>
<syntaxhighlight lang="console">
fuse prog -y 0 0x18 0x4e31bbcd 0x51e827dd 0x3511f521 0xfd9c11a2 0x5b997b82 0x8150adc5 0xa9c68fa9 0x72a3ba74
</syntaxhighlight>

Write the PKH into OTP manually with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<div style="color:red">Warning: Do not use the example command! Only use your unique values for programming the PKH in the OTP!</div>
<syntaxhighlight lang="shell">
fuse prog -y 0 0x18 0x4e31bbcd 0x51e827dd 0x3511f521 0xfd9c11a2 0x5b997b82 0x8150adc5 0xa9c68fa9 0x72a3ba74
</syntaxhighlight>

Lock the related OTP words manually with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<syntaxhighlight lang="shell">
fuse prog -y 0 0x10000018 1 1 1 1 1 1 1 1
</syntaxhighlight>

===== Test BootROM image authentication =====

To verify the image authentication by the BootROM with the programmed PKH and the programmed signed images, you must reboot your device.

On the third line of the U-Boot SPL output, check the BootROM authentication status.
The status output should look like this: <syntaxhighlight lang="console" inline>Bootrom authentication: succeeded</syntaxhighlight>.
Note the <syntaxhighlight lang="console" inline>succeeded</syntaxhighlight> status for successful authentication of the U-Boot SPL image by the BootROM.

The following output shows successful authentication of the U-Boot-SPL image in line 3, as well as successful authentication of the used configuration in line 7 and the U-Boot and Device Tree subimages in lines 8 and 9 of the U-Boot-FIT image.
<syntaxhighlight lang="console" line highlight="3,7-9">
U-Boot SPL 2022.01-00012-g6c5892c90c28 (Feb 16 2022 - 11:11:16 +0100)
Model: STMicroelectronics STM32MP15xx DHCOM Premium Developer Kit (2)
Bootrom authentication: succeeded
Code: SoM:rev=1,ddr3=3 Board:rev=0
RAM: DDR3L 32bits 2x4Gb 533MHz
Trying to boot from SPI
## Checking hash(es) for config config-2 ... sha256,rsa4096:fsbl-cfg-2022-02-16+ OK
## Checking hash(es) for Image uboot ... sha256,rsa4096:fsbl-img-2022-02-16+ sha256+ OK
## Checking hash(es) for Image fdt-1 ... sha256,rsa4096:fsbl-img-2022-02-16+ sha256+ OK
</syntaxhighlight>

===== Enforce BootROM image authentication =====

Without any further changes, the BootROM is able to perform authentication of the FSBL image, but unauthenticated images can still be used and executed.
The device is still open, let's see this as a kind of test mode to check if the PKH is set correctly.

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

The 6th bit in the 1st word of the OTP is responsible that the BootROM only accepts signed images.
Burning this bit enforces authentication of images by the BootROM and unsigned binaries are no longer supported on the target device.

To program this bit, the U-Boot Shell can be used with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command or with the more general <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command.

With usage of the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command:
<div style="color:red">Warning: After running the following command, your device will only be able to boot signed images!</div>
<syntaxhighlight lang="shell">
stm32key close
</syntaxhighlight>

Or with usage of the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<div style="color:red">Warning: After running the following command, your device will only be able to boot signed images!</div>
<syntaxhighlight lang="shell">
fuse prog 0 0x0 0x40
</syntaxhighlight>

== Secure Boot in Trusted Boot with BootROM authentication, TF-A and OP-TEE ==

<div style="color:red">TODO:</div>
# Add support for STM32MP15 DHCOM in <ref name="TF-A" />
# Add support for STM32MP15 DHCOM in <ref name="OP-TEE/optee_os" />
# Create stm32mp15_dhcom_trusted_defconfig???
# Integrate STM32MP15 DHCOM into <ref name="OP-TEE/build" />

== References ==

<references>
<ref name="UEFI specification">[http://www.uefi.org/specifications http://www.uefi.org/specifications]</ref>
<ref name="Basic Boot">[https://source.denx.de/u-boot/u-boot/-/blob/master/configs/stm32mp15_basic_defconfig U-Boot Source stm32mp15_basic_defconfig]</ref>
<ref name="Trusted Boot">[https://source.denx.de/u-boot/u-boot/-/blob/master/configs/stm32mp15_trusted_defconfig U-Boot Source stm32mp15_trusted_defconfig]</ref>
<ref name="BSI TR-02102">[https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.pdf BSI - Technische Richtlinie, "Kryptographische Algorithmen und Schlüssellängen", BSI TR-02102-1]</ref>
<ref name="STM32 image header">[https://wiki.st.com/stm32mpu/wiki/STM32_header_for_binary_files STM32 header for binary files]</ref>
<ref name="KeyGen_tool">[https://wiki.st.com/stm32mpu/wiki/KeyGen_tool STM32MP KeyGen tool]</ref>
<ref name="Signing_tool">[https://wiki.st.com/stm32mpu/wiki/Signing_tool STM32MP Signing tool]</ref>
<ref name="TF-A">[https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/ Trusted Firmware-A (TF-A)]</ref>
<ref name="OP-TEE/optee_os">[https://github.com/OP-TEE/optee_os OP-TEE Trusted OS]</ref>
<ref name="OP-TEE/build">[https://github.com/OP-TEE/build Makefiles to use OP-TEE on various platforms]</ref>
</references>

DHCOM STM32MP15 Secure Boot

2022-03-22T11:12:33Z

Dkierner: Fix branch name in "git clone" command /* Checkout source code for Verified Boot */

<div class="toclimit-3">__TOC__</div>

== Introduction ==

=== Abbreviations ===

{| class="wikitable sortable"
|-
! Abbreviation !! Description
|-
| BSI || Bundesamt für Sicherheit in der Informationstechnik
|-
| CoM || Computer on module
|-
| FIT || Flattened Image Tree
|-
| FSBL || Fist Stage Bootloader (TF-A or U-Boot SPL)
|-
| OTP || One Time Programmable (eFuses)
|-
| OP-TEE || Open Portable Trusted Execution Environment
|-
| PKH || Public Key Hash
|-
| ROM || Read-Only Memory
|-
| RSA || Rivest, Shamir und Adleman (asynchronous encryption)
|-
| SHA || Secure Hash Algorithm
|-
| SoC || System on chip
|-
| SoM || System on module
|-
| SSBL || Second Stage Bootloader (U-Boot)
|-
| TF-A || Trusted Firmware A
|}

=== Secure Boot ===

The term Secure Boot originally comes from the UEFI specification<ref name="UEFI specification" /> and describes a secure boot process in which only signed software is loaded and executed during the boot process.

Secure Boot is a necessary cornerstone for enforcing security mechanisms in a trusted computing environment.
Enforcing the execution of signed software only during the boot process, as long as the chain of trust is secure, can guarantee that said software is free from tampering, as any manipulation will invalidate the software's signature and prevent the software from being executed.

[[File:Secure Boot Generic en.png|600px|Secure Boot Generic]]

The figure [[Media:Secure Boot Generic en.png|Secure Boot Generic]] shows an example of a secure boot process that leads to a reset in the event of an error in the signature check. Each stage uses the certificate and signature to check the origin and integrity of the next stage. On success, the next stage is executed, and in the event of an error, this always leads to a defined error state. In the simplest case, the certificates are integrated into the binary image of the previous stage.

Program code and certificate need to be trustworthy and therefore protected against tampering in each stage, otherwise the secure boot chain can be compromised. Except for the first stage, all binary images are protected against third-party tampering by the signature. As this is practically impossible for the first stage, manipulation protection has to be enforced by hardware measures to make said stage immutable, with the first stage's program code and the verification certificate for the second stage being stored in read-only memory (ROM).

=== Basic and trusted boot in the context of Secure Boot ===

When booting Linux on the STM32MP1 SoC with U-Boot SPL and U-Boot only, STM speaks of "Basic Boot"<ref name="Basic Boot" />.
However, if Linux is booted with a combination of TF-A, U-Boot and OP-TEE, STM refers to this as "Trusted Boot"<ref name="Trusted Boot" />.

{| class="wikitable"
|-
! Boot chain !! Description
|-
| Basic boot || BootROM -> U-Boot SPL -> U-Boot -> Linux
|-
| Trusted boot || BootROM -> TF-A -> U-Boot + OP-TEE -> Linux
|}

== Secure Boot in Basic Boot with BootROM authentication and Verified Boot ==

This Secure Boot implementation does use the the BootROM integrated image authentication to authenticate the U-Boot SPL as FSBL.
Authentication of U-Boot as SSBL by the U-Boot SPL and authentication of the Linux kernel, Device Tree and ramdisk by U-Boot is done using the open source implementation [[#Verified Boot|Verified Boot]].

This also means that everything from U-Boot SPL onwards is platform independent, as we do not rely on hardware specific implementations.

=== Verified Boot ===

Developers of Google's Chromium project worked out a concept for the Verified Boot called Secure Boot mechanism on the basis of the boot loader "Das U-Boot".
They use the existing infrastructure of the FIT images and for the system configuration at runtime via a Device Tree.
The description language for the FIT images was extended by an additional signature node and the Device Tree of the platform was used to store the certificate(s) for the authentication of the images.
The signature node can be used to sign individual subimages as well as combinations of individual subimages in the FIT image.
The tool <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight> takes care the signature creation for the FIT images and the addition of the certificate in a Device Tree.

With Verified Boot, the Device Tree with included public key is integrated into the program image of the stage, which accomplishes the authentication and is thus very similar to the general procedure shown in figure [[Media:Secure Boot Generic en.png|Secure Boot Generic]].
The number of public keys that can be integrated is theoretically unlimited, but they must be distinguishable by name.

==== Technical details of Verified Boot ====

{| class="wikitable"
|-
| '''Name'''
| Verified Boot
|-
| '''Implementierung'''
| Software (Open Source)
|-
| '''Hash algorithms'''
|
* SHA1 (deprecated)<ref name="BSI TR-02102" />
* SHA256
* SHA384
* SHA512
|-
| '''Crypto algorithms
|
* RSA2048 (deprecated as of 2024)<ref name="BSI TR-02102" />
* RSA4096

* ECDSA256 (currently limited to U-Boot SPL)
|-
| '''Number of key pairs'''
| unlimited
|-
|}

==== In-depth references for Verified Boot ====


===== Flatten Image Tree =====
* [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT U-Boot Documentation: doc/uImage.FIT]
* [https://source.denx.de/u-boot/u-boot/-/commit/d5934ad7 U-Boot Commit d5934ad7: "new uImage: Add dual format uImage support framework"]
* ...
* [https://source.denx.de/u-boot/u-boot/-/commit/3310c549 U-Boot Commit d5934ad7: "new uImage: Add new uImage format documentation and examples"]

===== Verified Boot =====

* [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT/signature.txt U-Boot Documentation: doc/uImage.FIT/signature.txt]
* [https://source.denx.de/u-boot/u-boot/-/commit/3e569a6b U-Boot Commit 3e569a6b: "image: Add signing infrastructure"]
* [https://source.denx.de/u-boot/u-boot/-/commit/56518e71 U-Boot Commit 56518e71: "image: Support signing of images"]
* [https://source.denx.de/u-boot/u-boot/-/commit/4d098529 U-Boot Commit 4d098529: "image: Add support for signing of FIT configurations"]

===== ECDSA signature verification =====

<div style="color:red">TODO: Mention ECDSA limitations</div>
Note: This has currently some limitations!


* [https://source.denx.de/u-boot/u-boot/-/commit/928a8be7 U-Boot Commit 928a8be7: "lib: ecdsa: Implement UCLASS_ECDSA verification on target"]
* [https://source.denx.de/u-boot/u-boot/-/commit/ee870859 U-Boot Commit ee870859: "arm: stm32mp1: Implement ECDSA signature verification"]

=== Tutorial: Secure boot from BootROM to Linux with basic boot ===

==== System requirements and needed tools ====

The following table lists all requirements to create the key pairs and build the signed images with embedded public keys.

{| class="wikitable"
|-
! Category !! Description
|-
| '''Host operating system''' ||
* Linux (Debian 9, Ubuntu 18.04 or higher prefered)
|-
| '''Debian packages''' ||
* bison
* device-tree-compiler
* flex
* gcc-arm-linux-gnueabihf (>= gcc 6)
* git
* make
* openssl
|-
| '''STM32 Tools''' ||
* [https://www.st.com/en/development-tools/stm32cubeprog.html STM32CubeProgrammer]
** STM32MP_KeyGen_CLI
** STM32MP_SigningTool_CLI
|}

<div style="color:red">TODO: Should we give host setup instructions?</div>


==== Intended use of the four generated key pairs ====

We've decided to create and use as few certificates as reasonable to ensure a high level of security.
Therefore, we chose a separate key pair for each boot stage and also a separate key pair for image and configuration nodes.
If you're confused about the difference between image and configuration nodes, head over to [[#Flatten Image Tree|Flatten Image Tree]] to refresh your knowledge.
The exact purpose of the four key pairs generated for Verified Boot is described in the following table.

{| class="wikitable"
|-
! File name !! Intended use
|-
| '''fsbl-img''' || Authenticate image nodes of FIT images loaded by U-Boot SPL (U-Boot, Device Tree, firmware)
|-
| '''fsbl-cfg''' || Authenticate config nodes of FIT images loaded by U-Boot SPL (U-Boot + Device Tree + firmware)
|-
| '''ssbl-img''' || Authenticate image nodes of FIT images loaded by U-Boot (Kernel, Device Tree, InitRamFS)
|-
| '''ssbl-cfg''' || Authenticate config nodes of FIT images loaded by U-Boot (Kernel + Device Tree + InitRamFS)
|-
|}

==== Created/Modified files in the U-Boot source for Verified Boot ====

The created or modified files to build U-Boot with Verified Boot on STM32MP15 are described in the following table.

{| class="wikitable"
|-
! File
! Description
|-
| build_signed_uboot.sh
| Shell script that automates the creation of key pairs, the modification of FIT source files and Device Tree's and building of U-Boot SPL and U-Boot.
|-
| board/dhelectronics/dh_stm32mp1/u-boot-dhco?.its
| FIT source files with defined U-Boot image and Device Tree's for DHSOM platforms.
|-
| board/dhelectronics/dh_stm32mp1/linux-dhcom.its
| Dummy FIT source file with defined dummy kernel image and dummy Device Tree for DHSOM platforms.<br>To avoid relying on a built kernel image on a fixed path, we created this dummy, since adding the public keys with <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight> requires a valid FIT source file.
|-
| configs/stm32mp15_dhco?_secure_defconfig
| Example U-Boot defconfig's with enabled <syntaxhighlight lang="shell" inline>CONFIG_FIT_SIGNATURE</syntaxhighlight> and <syntaxhighlight lang="shell" inline>CONFIG_SPL_FIT_SIGNATURE</syntaxhighlight>.
|}

==== Build Verified Boot enabled U-Boot SPL and U-Boot ====

To build the U-Boot SPL and U-Boot images, you need to check out the source code and run a build script that automates everything from key generation to image creation and signing.

===== Checkout source code for Verified Boot =====

<div style="color:red">TODO: Replace my personal GitLab by a public available repository</div>
Checkout the branch <syntaxhighlight lang="shell" inline>v2022.01_dhcom_secure_boot</syntaxhighlight> in my personal GitLab repository with:

<syntaxhighlight lang="shell">
git clone git@dhplgl01:jneuhauser/u-boot.git -b v2022.01_stm32mp1_dhcom_secure_boot
</syntaxhighlight>

If you already have a cloned U-Boot source code, you can also fetch it into your existing repository with:

<syntaxhighlight lang="shell">
cd /path/to/u-boot
git remote add jneuhauser git@dhplgl01:jneuhauser/u-boot.git
git fetch jneuhauser
git checkout v2022.01_dhcom_secure_boot
</syntaxhighlight>

===== Run the build script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> =====

The shell script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> included in the U-Boot source performs the following steps.
# Prebuild U-Boat SPL and U-Boat to build the required tools and Device Tree's
# Generate the [[#Intended use of the four generated key pairs|four key pairs]] if not already created
# Generate/Modify FIT image source files for Linux (dummy) and U-Boot
# Add public keys to the built Device Tree's used by U-Boot SPL and U-Boot
# Rebuild U-Boot SPL and U-Boot with new Device Tree's containing the public keys

The script supports the following environment variables to configure the target architecture, the cross compiler, the defconfig, the key algorithm, the key directory, and a key postfix:
{| class="wikitable sortable"
|-
! Name !! Description !! Default
|-
| ARCH || Target architecture for the U-Boot build || arm
|-
| CROSS_COMPILE || Used cross compiler to build U-Boot || arm-linux-gnueabihf-
|-
| DEFCONFIG || Used defconfig for the U-Boot build || stm32mp15_dhcom_secure_defconfig
|-
| KEY_ALGO || Signature algorithm used for Verified Boot || rsa
|-
| KEY_DIR || Directory where the key pairs are stored || ../keys
|-
| KEY_POSTFIX || Postfix which is appended to the key names || -$(date +%F)
|}

To perform the steps mentioned above, you just need to run the shell script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> like below.
In this example, we override the default value for <syntaxhighlight lang="shell" inline>KEY_POSTFIX</syntaxhighlight> with <syntaxhighlight lang="shell" inline>-testing</syntaxhighlight> to append this string to the [[#Intended use of the four generated key pairs|four key file names]].
The script has debug output enabled by default, which should output all the statements in the script itself and the output of the commands used in the script.
If you have any problems with the script, feel free to get in touch with [mailto:info@dh-electronics.com us] and attach a logfile.

<syntaxhighlight lang="shell">
cd /path/to/u-boot
KEY_POSTFIX="-testing" ./build_signed_uboot.sh | tee build_signed_uboot.log
</syntaxhighlight>

If this process completes without error, there are two boot loader images in the root directory of the U-Boot source.
{| class="wikitable sortable"
|-
! File name !! Stage !! Description
|-
| u-boot-spl.stm32 || FSBL || U-Boot SPL binary with appended Device Tree and prepended STM32 image header<ref name="STM32 image header" />.
|-
| u-boot.itb || SSBL || U-Boot and Device Tree's contained in a signed FIT image.
|}

==== Generate key pair and sign U-Boot SPL for BootROM authentication ====

To sign the U-Boot SPL as SSBL image for authentication with the BootROM we have to use the STM32 tools <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight> and <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight>.

===== Generate key pair with <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight> =====

All STM32MP15 SoCs only support one key pair for authenticating images through the BootROM.
To generate a ECDSA key pair for the STM32MP Secure Boot use the tool <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight><ref name="KeyGen_tool" />:
<syntaxhighlight lang="shell">
STM32MP_KeyGen_CLI --absolute-path "$(pwd)" --password <a secure password>
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Key Generator v2.9.0
-------------------------------------------------------------------

Prime256v1 curve is selected.
AES_256_cbc algorithm is selected for private key encryption
Generating Prime256v1 keys...
Private key PEM file created
Public key PEM file created
public key hash file created
Keys generated successfully.
+ public key: publicKey.pem
+ private key: privateKey.pem
+ public hash key: publicKeyhash.bin
</syntaxhighlight>

===== Sign U-Boot SPL with <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight> =====

To add the public key and the image signature to our built U-Boot SPL binary with STM32 image header, we are using the tool <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight><ref name="Signing_tool" /> to update the existing STM32 image header of <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> with the required details.
<syntaxhighlight lang="shell">
STM32MP_SigningTool_CLI --binary-image /path/to/u-boot/u-boot-spl.stm32 --public-key publicKey.pem --private-key privateKey.pem --password <a secure password> --output /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Signing Tool v2.9.0
-------------------------------------------------------------------

Prime256v1 curve is selected.
Header version 1 preparation ...
Reading Private Key File...
ECDSA signature generated.
Signature verification: SUCCESS
The Signed image file generated successfully: /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>

You can check the STM32 image header details with:
<syntaxhighlight lang="shell">
STM32MP_SigningTool_CLI --dump-header /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Signing Tool v2.9.0
-------------------------------------------------------------------

Header description:

Magic: 0x53544d32
Signature: c8 30 a0 62 2d 6d 4e 1b b9 f7 fe 38 27 65 e0 44 f0 f5 9d e6 8a a6 02 cb 74 52 26 9c 1e e9 07 17
1a c7 da 8e 96 fa 82 d3 b1 dc d5 3a 05 0e 87 83 94 4d 47 ad 17 07 88 0d b5 ae 2e 38 1d 90 22 ad
Checksum: 0xa8ca85
Header version: 0x10000
Size: 0x22dec
Load address: 0x2ffc2500
Entry point: 0x2ffc2500
Image version: 0x0
Option flags: 0x0
ECDSA Algo: 0x1
ECDSA pub key: 3b 71 8e 59 f1 ee 4c a8 4b 72 5f 4a 1c 63 8b 6e b8 01 ec 1a 3f 8c 98 2f d2 1d 77 f9 09 10 8f 04
30 da 5c 3a 24 53 0d 71 93 f0 a5 d9 c9 a7 27 b4 5f a5 c4 4d 55 8b 7a 25 e3 03 ef ca 87 ff 04 25
Binary type: 0x0
</syntaxhighlight>
The difference to an unsigned STM32 image header is that the values for "Signature" and "ECDSA pub key" are not all zeros and that "Option flags" is 0x0 for enabled signature verification instead of 0x1 for disabled signature verification.

==== Write U-Boot SPL and U-Boot to your boot media ====

The first step to verify that the built U-Boot SPL and U-Boot works as expected is to program both images to your boot media.
Depending on the boot configuration, your DHSOM will boot from the module's SPI-NOR flash, from the module's or baseboard's eMMC or from an SD card.
The boot configuration is always defined by the boot pins by default, because the boot pins have no alternative function on the STM32MP15 SoCs.

<div style="color:red">TODO: How can a user determine the used boot media?</div>
<div style="color:red">TODO: How to enforce boot media on Secure Boot enabled devices?</div>

===== Write U-Boot SPL and U-Boot to the SPI-NOR flash of the SoM =====

The following '''commands for the U-Boot Shell''' calculate some addresses based on the image offsets expected by the BootROM, load the required images from SD card or via TFTP into memory and finally write the prepared memory into the SPI-NOR flash on the SoM.

Prepare for loading <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> into memory:
<syntaxhighlight lang="shell">
mw.b ${loadaddr} 0xff 0x200000
setexpr fsbl1addr ${loadaddr} + 0x0
setexpr fsbl2addr ${loadaddr} + 0x40000
setexpr ssbl1addr ${loadaddr} + 0x80000
</syntaxhighlight>

Load <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> from SD card:
<syntaxhighlight lang="shell">
load mmc 0:4 ${fsbl1addr} u-boot-spl.stm32
load mmc 0:4 ${fsbl2addr} u-boot-spl.stm32
load mmc 0:4 ${ssbl1addr} u-boot.itb
</syntaxhighlight>

Load <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> from tftp server:
<syntaxhighlight lang="shell">
setenv serverip 10.20.30.1
setenv ipaddr 10.20.30.100
setenv netmask 255.255.255.0
tftp ${fsbl1addr} ${serverip}:u-boot-spl.stm32
tftp ${fsbl2addr} ${serverip}:u-boot-spl.stm32
tftp ${ssbl1addr} ${serverip}:u-boot.itb
</syntaxhighlight>

Check for magic numbers of expected image headers and conditionally program the SPI-NOR flash:
<syntaxhighlight lang="shell">
if itest *${fsbl1addr} == 0x324d5453 && itest *${fsbl2addr} == 0x324d5453 && itest *${ssbl1addr} == 0xedfe0dd0; then
sf probe && sf update ${loadaddr} 0 0x200000
fi
</syntaxhighlight>

===== Write U-Boot SPL and U-Boot to an SD card =====

<div style="color:red">TODO:</div>


===== Write U-Boot SPL and U-Boot to the eMMC =====

<div style="color:red">TODO:</div>


==== Enroll, test and enforce BootROM image authentication ====

To enroll, test and enforce image authentication by the BootROM you need to program the PKH into the OTP of the STM32MP15 SoC.
The <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> file that you created in the [[#Generate key pair with STM32MP_KeyGen_CLI|Generate key pair with STM32MP_KeyGen_CLI]] step contains the PKH in binary format for use with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> U-Boot command.
If the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command does fail or is not available on the target U-Boot, you can also write the PKH manually with the more generic <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command into the OTP.

===== Program public key hash to eFuses =====

The following '''commands for the U-Boot Shell''' load the file <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> into memory and program the contained PKH to the OTP of the STM32MP15 SoC.
The used command <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> writes and locks the words of the OTP automatically without knowing anything about the OTP layout/addresses.
If this fails or the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command is not available, you can also write and lock the OTP with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command

====== Program <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> into OTP with <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command ======

Load <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> from SD card:
<syntaxhighlight lang="shell">
load mmc 0:4 ${loadaddr} publicKeyhash.bin
</syntaxhighlight>

Or load <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> per TFTP:
<syntaxhighlight lang="shell">
setenv serverip 10.20.30.1
setenv ipaddr 10.20.30.100
setenv netmask 255.255.255.0
tftp ${loadaddr} ${serverip}:publicKeyhash.bin
</syntaxhighlight>

Show the contents of <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight>:
<syntaxhighlight lang="shell">
stm32key read ${loadaddr}
</syntaxhighlight>
<syntaxhighlight lang="console">
Read KEY at 0xc2000000
OTP value 24: 4e31bbcd
OTP value 25: 51e827dd
OTP value 26: 3511f521
OTP value 27: fd9c11a2
OTP value 28: 5b997b82
OTP value 29: 8150adc5
OTP value 30: a9c68fa9
OTP value 31: 72a3ba74
</syntaxhighlight>

Write the contents of <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> to OTP with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command:
<syntaxhighlight lang="shell">
stm32key fuse ${loadaddr}
</syntaxhighlight>
<syntaxhighlight lang="console">
TODO: Add output
</syntaxhighlight>

====== Program PKH manually into OTP with <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command ======

Generate fuse command with hexdump from file <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> on linux host:
<div style="color:red">Warning: Do not use the example output! Only use your unique values for programming the PKH in the OTP!</div>
<syntaxhighlight lang="shell">
echo fuse prog -y 0 0x18 $(hexdump -e '/4 "0x"' -e '/1 "%x"' -e '" "' /path/to/publicKeyhash.bin)
</syntaxhighlight>
<syntaxhighlight lang="console">
fuse prog -y 0 0x18 0x4e31bbcd 0x51e827dd 0x3511f521 0xfd9c11a2 0x5b997b82 0x8150adc5 0xa9c68fa9 0x72a3ba74
</syntaxhighlight>

Write the PKH into OTP manually with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<div style="color:red">Warning: Do not use the example command! Only use your unique values for programming the PKH in the OTP!</div>
<syntaxhighlight lang="shell">
fuse prog -y 0 0x18 0x4e31bbcd 0x51e827dd 0x3511f521 0xfd9c11a2 0x5b997b82 0x8150adc5 0xa9c68fa9 0x72a3ba74
</syntaxhighlight>

Lock the related OTP words manually with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<syntaxhighlight lang="shell">
fuse prog -y 0 0x10000018 1 1 1 1 1 1 1 1
</syntaxhighlight>

===== Test BootROM image authentication =====

To verify the image authentication by the BootROM with the programmed PKH and the programmed signed images, you must reboot your device.

On the third line of the U-Boot SPL output, check the BootROM authentication status.
The status output should look like this: <syntaxhighlight lang="console" inline>Bootrom authentication: succeeded</syntaxhighlight>.
Note the <syntaxhighlight lang="console" inline>succeeded</syntaxhighlight> status for successful authentication of the U-Boot SPL image by the BootROM.

The following output shows successful authentication of the U-Boot-SPL image in line 3, as well as successful authentication of the used configuration in line 7 and the U-Boot and Device Tree subimages in lines 8 and 9 of the U-Boot-FIT image.
<syntaxhighlight lang="console" line highlight="3,7-9">
U-Boot SPL 2022.01-00012-g6c5892c90c28 (Feb 16 2022 - 11:11:16 +0100)
Model: STMicroelectronics STM32MP15xx DHCOM Premium Developer Kit (2)
Bootrom authentication: succeeded
Code: SoM:rev=1,ddr3=3 Board:rev=0
RAM: DDR3L 32bits 2x4Gb 533MHz
Trying to boot from SPI
## Checking hash(es) for config config-2 ... sha256,rsa4096:fsbl-cfg-2022-02-16+ OK
## Checking hash(es) for Image uboot ... sha256,rsa4096:fsbl-img-2022-02-16+ sha256+ OK
## Checking hash(es) for Image fdt-1 ... sha256,rsa4096:fsbl-img-2022-02-16+ sha256+ OK
</syntaxhighlight>

===== Enforce BootROM image authentication =====

Without any further changes, the BootROM is able to perform authentication of the FSBL image, but unauthenticated images can still be used and executed.
The device is still open, let's see this as a kind of test mode to check if the PKH is set correctly.

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

The 6th bit in the 1st word of the OTP is responsible that the BootROM only accepts signed images.
Burning this bit enforces authentication of images by the BootROM and unsigned binaries are no longer supported on the target device.

To program this bit, the U-Boot Shell can be used with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command or with the more general <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command.

With usage of the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command:
<div style="color:red">Warning: After running the following command, your device will only be able to boot signed images!</div>
<syntaxhighlight lang="shell">
stm32key close
</syntaxhighlight>

Or with usage of the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<div style="color:red">Warning: After running the following command, your device will only be able to boot signed images!</div>
<syntaxhighlight lang="shell">
fuse prog 0 0x0 0x40
</syntaxhighlight>

== Secure Boot in Trusted Boot with BootROM authentication, TF-A and OP-TEE ==

<div style="color:red">TODO:</div>
# Add support for STM32MP15 DHCOM in <ref name="TF-A" />
# Add support for STM32MP15 DHCOM in <ref name="OP-TEE/optee_os" />
# Create stm32mp15_dhcom_trusted_defconfig???
# Integrate STM32MP15 DHCOM into <ref name="OP-TEE/build" />

== References ==

<references>
<ref name="UEFI specification">[http://www.uefi.org/specifications http://www.uefi.org/specifications]</ref>
<ref name="Basic Boot">[https://source.denx.de/u-boot/u-boot/-/blob/master/configs/stm32mp15_basic_defconfig U-Boot Source stm32mp15_basic_defconfig]</ref>
<ref name="Trusted Boot">[https://source.denx.de/u-boot/u-boot/-/blob/master/configs/stm32mp15_trusted_defconfig U-Boot Source stm32mp15_trusted_defconfig]</ref>
<ref name="BSI TR-02102">[https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.pdf BSI - Technische Richtlinie, "Kryptographische Algorithmen und Schlüssellängen", BSI TR-02102-1]</ref>
<ref name="STM32 image header">[https://wiki.st.com/stm32mpu/wiki/STM32_header_for_binary_files STM32 header for binary files]</ref>
<ref name="KeyGen_tool">[https://wiki.st.com/stm32mpu/wiki/KeyGen_tool STM32MP KeyGen tool]</ref>
<ref name="Signing_tool">[https://wiki.st.com/stm32mpu/wiki/Signing_tool STM32MP Signing tool]</ref>
<ref name="TF-A">[https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/ Trusted Firmware-A (TF-A)]</ref>
<ref name="OP-TEE/optee_os">[https://github.com/OP-TEE/optee_os OP-TEE Trusted OS]</ref>
<ref name="OP-TEE/build">[https://github.com/OP-TEE/build Makefiles to use OP-TEE on various platforms]</ref>
</references>

DHCOM STM32MP15 Secure Boot

2022-03-22T10:52:45Z

Dkierner: Fix prepositions in /* Program publicKeyhash.bin into OTP with stm32key command */

<div class="toclimit-3">__TOC__</div>

== Introduction ==

=== Abbreviations ===

{| class="wikitable sortable"
|-
! Abbreviation !! Description
|-
| BSI || Bundesamt für Sicherheit in der Informationstechnik
|-
| CoM || Computer on module
|-
| FIT || Flattened Image Tree
|-
| FSBL || Fist Stage Bootloader (TF-A or U-Boot SPL)
|-
| OTP || One Time Programmable (eFuses)
|-
| OP-TEE || Open Portable Trusted Execution Environment
|-
| PKH || Public Key Hash
|-
| ROM || Read-Only Memory
|-
| RSA || Rivest, Shamir und Adleman (asynchronous encryption)
|-
| SHA || Secure Hash Algorithm
|-
| SoC || System on chip
|-
| SoM || System on module
|-
| SSBL || Second Stage Bootloader (U-Boot)
|-
| TF-A || Trusted Firmware A
|}

=== Secure Boot ===

The term Secure Boot originally comes from the UEFI specification<ref name="UEFI specification" /> and describes a secure boot process in which only signed software is loaded and executed during the boot process.

Secure Boot is a necessary cornerstone for enforcing security mechanisms in a trusted computing environment.
Enforcing the execution of signed software only during the boot process, as long as the chain of trust is secure, can guarantee that said software is free from tampering, as any manipulation will invalidate the software's signature and prevent the software from being executed.

[[File:Secure Boot Generic en.png|600px|Secure Boot Generic]]

The figure [[Media:Secure Boot Generic en.png|Secure Boot Generic]] shows an example of a secure boot process that leads to a reset in the event of an error in the signature check. Each stage uses the certificate and signature to check the origin and integrity of the next stage. On success, the next stage is executed, and in the event of an error, this always leads to a defined error state. In the simplest case, the certificates are integrated into the binary image of the previous stage.

Program code and certificate need to be trustworthy and therefore protected against tampering in each stage, otherwise the secure boot chain can be compromised. Except for the first stage, all binary images are protected against third-party tampering by the signature. As this is practically impossible for the first stage, manipulation protection has to be enforced by hardware measures to make said stage immutable, with the first stage's program code and the verification certificate for the second stage being stored in read-only memory (ROM).

=== Basic and trusted boot in the context of Secure Boot ===

When booting Linux on the STM32MP1 SoC with U-Boot SPL and U-Boot only, STM speaks of "Basic Boot"<ref name="Basic Boot" />.
However, if Linux is booted with a combination of TF-A, U-Boot and OP-TEE, STM refers to this as "Trusted Boot"<ref name="Trusted Boot" />.

{| class="wikitable"
|-
! Boot chain !! Description
|-
| Basic boot || BootROM -> U-Boot SPL -> U-Boot -> Linux
|-
| Trusted boot || BootROM -> TF-A -> U-Boot + OP-TEE -> Linux
|}

== Secure Boot in Basic Boot with BootROM authentication and Verified Boot ==

This Secure Boot implementation does use the the BootROM integrated image authentication to authenticate the U-Boot SPL as FSBL.
Authentication of U-Boot as SSBL by the U-Boot SPL and authentication of the Linux kernel, Device Tree and ramdisk by U-Boot is done using the open source implementation [[#Verified Boot|Verified Boot]].

This also means that everything from U-Boot SPL onwards is platform independent, as we do not rely on hardware specific implementations.

=== Verified Boot ===

Developers of Google's Chromium project worked out a concept for the Verified Boot called Secure Boot mechanism on the basis of the boot loader "Das U-Boot".
They use the existing infrastructure of the FIT images and for the system configuration at runtime via a Device Tree.
The description language for the FIT images was extended by an additional signature node and the Device Tree of the platform was used to store the certificate(s) for the authentication of the images.
The signature node can be used to sign individual subimages as well as combinations of individual subimages in the FIT image.
The tool <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight> takes care the signature creation for the FIT images and the addition of the certificate in a Device Tree.

With Verified Boot, the Device Tree with included public key is integrated into the program image of the stage, which accomplishes the authentication and is thus very similar to the general procedure shown in figure [[Media:Secure Boot Generic en.png|Secure Boot Generic]].
The number of public keys that can be integrated is theoretically unlimited, but they must be distinguishable by name.

==== Technical details of Verified Boot ====

{| class="wikitable"
|-
| '''Name'''
| Verified Boot
|-
| '''Implementierung'''
| Software (Open Source)
|-
| '''Hash algorithms'''
|
* SHA1 (deprecated)<ref name="BSI TR-02102" />
* SHA256
* SHA384
* SHA512
|-
| '''Crypto algorithms
|
* RSA2048 (deprecated as of 2024)<ref name="BSI TR-02102" />
* RSA4096

* ECDSA256 (currently limited to U-Boot SPL)
|-
| '''Number of key pairs'''
| unlimited
|-
|}

==== In-depth references for Verified Boot ====


===== Flatten Image Tree =====
* [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT U-Boot Documentation: doc/uImage.FIT]
* [https://source.denx.de/u-boot/u-boot/-/commit/d5934ad7 U-Boot Commit d5934ad7: "new uImage: Add dual format uImage support framework"]
* ...
* [https://source.denx.de/u-boot/u-boot/-/commit/3310c549 U-Boot Commit d5934ad7: "new uImage: Add new uImage format documentation and examples"]

===== Verified Boot =====

* [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT/signature.txt U-Boot Documentation: doc/uImage.FIT/signature.txt]
* [https://source.denx.de/u-boot/u-boot/-/commit/3e569a6b U-Boot Commit 3e569a6b: "image: Add signing infrastructure"]
* [https://source.denx.de/u-boot/u-boot/-/commit/56518e71 U-Boot Commit 56518e71: "image: Support signing of images"]
* [https://source.denx.de/u-boot/u-boot/-/commit/4d098529 U-Boot Commit 4d098529: "image: Add support for signing of FIT configurations"]

===== ECDSA signature verification =====

<div style="color:red">TODO: Mention ECDSA limitations</div>
Note: This has currently some limitations!


* [https://source.denx.de/u-boot/u-boot/-/commit/928a8be7 U-Boot Commit 928a8be7: "lib: ecdsa: Implement UCLASS_ECDSA verification on target"]
* [https://source.denx.de/u-boot/u-boot/-/commit/ee870859 U-Boot Commit ee870859: "arm: stm32mp1: Implement ECDSA signature verification"]

=== Tutorial: Secure boot from BootROM to Linux with basic boot ===

==== System requirements and needed tools ====

The following table lists all requirements to create the key pairs and build the signed images with embedded public keys.

{| class="wikitable"
|-
! Category !! Description
|-
| '''Host operating system''' ||
* Linux (Debian 9, Ubuntu 18.04 or higher prefered)
|-
| '''Debian packages''' ||
* bison
* device-tree-compiler
* flex
* gcc-arm-linux-gnueabihf (>= gcc 6)
* git
* make
* openssl
|-
| '''STM32 Tools''' ||
* [https://www.st.com/en/development-tools/stm32cubeprog.html STM32CubeProgrammer]
** STM32MP_KeyGen_CLI
** STM32MP_SigningTool_CLI
|}

<div style="color:red">TODO: Should we give host setup instructions?</div>


==== Intended use of the four generated key pairs ====

We've decided to create and use as few certificates as reasonable to ensure a high level of security.
Therefore, we chose a separate key pair for each boot stage and also a separate key pair for image and configuration nodes.
If you're confused about the difference between image and configuration nodes, head over to [[#Flatten Image Tree|Flatten Image Tree]] to refresh your knowledge.
The exact purpose of the four key pairs generated for Verified Boot is described in the following table.

{| class="wikitable"
|-
! File name !! Intended use
|-
| '''fsbl-img''' || Authenticate image nodes of FIT images loaded by U-Boot SPL (U-Boot, Device Tree, firmware)
|-
| '''fsbl-cfg''' || Authenticate config nodes of FIT images loaded by U-Boot SPL (U-Boot + Device Tree + firmware)
|-
| '''ssbl-img''' || Authenticate image nodes of FIT images loaded by U-Boot (Kernel, Device Tree, InitRamFS)
|-
| '''ssbl-cfg''' || Authenticate config nodes of FIT images loaded by U-Boot (Kernel + Device Tree + InitRamFS)
|-
|}

==== Created/Modified files in the U-Boot source for Verified Boot ====

The created or modified files to build U-Boot with Verified Boot on STM32MP15 are described in the following table.

{| class="wikitable"
|-
! File
! Description
|-
| build_signed_uboot.sh
| Shell script that automates the creation of key pairs, the modification of FIT source files and Device Tree's and building of U-Boot SPL and U-Boot.
|-
| board/dhelectronics/dh_stm32mp1/u-boot-dhco?.its
| FIT source files with defined U-Boot image and Device Tree's for DHSOM platforms.
|-
| board/dhelectronics/dh_stm32mp1/linux-dhcom.its
| Dummy FIT source file with defined dummy kernel image and dummy Device Tree for DHSOM platforms.<br>To avoid relying on a built kernel image on a fixed path, we created this dummy, since adding the public keys with <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight> requires a valid FIT source file.
|-
| configs/stm32mp15_dhco?_secure_defconfig
| Example U-Boot defconfig's with enabled <syntaxhighlight lang="shell" inline>CONFIG_FIT_SIGNATURE</syntaxhighlight> and <syntaxhighlight lang="shell" inline>CONFIG_SPL_FIT_SIGNATURE</syntaxhighlight>.
|}

==== Build Verified Boot enabled U-Boot SPL and U-Boot ====

To build the U-Boot SPL and U-Boot images, you need to check out the source code and run a build script that automates everything from key generation to image creation and signing.

===== Checkout source code for Verified Boot =====

<div style="color:red">TODO: Replace my personal GitLab by a public available repository</div>
Checkout the branch <syntaxhighlight lang="shell" inline>v2022.01_dhcom_secure_boot</syntaxhighlight> in my personal GitLab repository with:

<syntaxhighlight lang="shell">
git clone git@dhplgl01:jneuhauser/u-boot.git -b v2022.01_dhcom_secure_boot
</syntaxhighlight>

If you already have a cloned U-Boot source code, you can also fetch it into your existing repository with:

<syntaxhighlight lang="shell">
cd /path/to/u-boot
git remote add jneuhauser git@dhplgl01:jneuhauser/u-boot.git
git fetch jneuhauser
git checkout v2022.01_dhcom_secure_boot
</syntaxhighlight>

===== Run the build script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> =====

The shell script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> included in the U-Boot source performs the following steps.
# Prebuild U-Boat SPL and U-Boat to build the required tools and Device Tree's
# Generate the [[#Intended use of the four generated key pairs|four key pairs]] if not already created
# Generate/Modify FIT image source files for Linux (dummy) and U-Boot
# Add public keys to the built Device Tree's used by U-Boot SPL and U-Boot
# Rebuild U-Boot SPL and U-Boot with new Device Tree's containing the public keys

The script supports the following environment variables to configure the target architecture, the cross compiler, the defconfig, the key algorithm, the key directory, and a key postfix:
{| class="wikitable sortable"
|-
! Name !! Description !! Default
|-
| ARCH || Target architecture for the U-Boot build || arm
|-
| CROSS_COMPILE || Used cross compiler to build U-Boot || arm-linux-gnueabihf-
|-
| DEFCONFIG || Used defconfig for the U-Boot build || stm32mp15_dhcom_secure_defconfig
|-
| KEY_ALGO || Signature algorithm used for Verified Boot || rsa
|-
| KEY_DIR || Directory where the key pairs are stored || ../keys
|-
| KEY_POSTFIX || Postfix which is appended to the key names || -$(date +%F)
|}

To perform the steps mentioned above, you just need to run the shell script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> like below.
In this example, we override the default value for <syntaxhighlight lang="shell" inline>KEY_POSTFIX</syntaxhighlight> with <syntaxhighlight lang="shell" inline>-testing</syntaxhighlight> to append this string to the [[#Intended use of the four generated key pairs|four key file names]].
The script has debug output enabled by default, which should output all the statements in the script itself and the output of the commands used in the script.
If you have any problems with the script, feel free to get in touch with [mailto:info@dh-electronics.com us] and attach a logfile.

<syntaxhighlight lang="shell">
cd /path/to/u-boot
KEY_POSTFIX="-testing" ./build_signed_uboot.sh | tee build_signed_uboot.log
</syntaxhighlight>

If this process completes without error, there are two boot loader images in the root directory of the U-Boot source.
{| class="wikitable sortable"
|-
! File name !! Stage !! Description
|-
| u-boot-spl.stm32 || FSBL || U-Boot SPL binary with appended Device Tree and prepended STM32 image header<ref name="STM32 image header" />.
|-
| u-boot.itb || SSBL || U-Boot and Device Tree's contained in a signed FIT image.
|}

==== Generate key pair and sign U-Boot SPL for BootROM authentication ====

To sign the U-Boot SPL as SSBL image for authentication with the BootROM we have to use the STM32 tools <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight> and <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight>.

===== Generate key pair with <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight> =====

All STM32MP15 SoCs only support one key pair for authenticating images through the BootROM.
To generate a ECDSA key pair for the STM32MP Secure Boot use the tool <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight><ref name="KeyGen_tool" />:
<syntaxhighlight lang="shell">
STM32MP_KeyGen_CLI --absolute-path "$(pwd)" --password <a secure password>
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Key Generator v2.9.0
-------------------------------------------------------------------

Prime256v1 curve is selected.
AES_256_cbc algorithm is selected for private key encryption
Generating Prime256v1 keys...
Private key PEM file created
Public key PEM file created
public key hash file created
Keys generated successfully.
+ public key: publicKey.pem
+ private key: privateKey.pem
+ public hash key: publicKeyhash.bin
</syntaxhighlight>

===== Sign U-Boot SPL with <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight> =====

To add the public key and the image signature to our built U-Boot SPL binary with STM32 image header, we are using the tool <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight><ref name="Signing_tool" /> to update the existing STM32 image header of <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> with the required details.
<syntaxhighlight lang="shell">
STM32MP_SigningTool_CLI --binary-image /path/to/u-boot/u-boot-spl.stm32 --public-key publicKey.pem --private-key privateKey.pem --password <a secure password> --output /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Signing Tool v2.9.0
-------------------------------------------------------------------

Prime256v1 curve is selected.
Header version 1 preparation ...
Reading Private Key File...
ECDSA signature generated.
Signature verification: SUCCESS
The Signed image file generated successfully: /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>

You can check the STM32 image header details with:
<syntaxhighlight lang="shell">
STM32MP_SigningTool_CLI --dump-header /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Signing Tool v2.9.0
-------------------------------------------------------------------

Header description:

Magic: 0x53544d32
Signature: c8 30 a0 62 2d 6d 4e 1b b9 f7 fe 38 27 65 e0 44 f0 f5 9d e6 8a a6 02 cb 74 52 26 9c 1e e9 07 17
1a c7 da 8e 96 fa 82 d3 b1 dc d5 3a 05 0e 87 83 94 4d 47 ad 17 07 88 0d b5 ae 2e 38 1d 90 22 ad
Checksum: 0xa8ca85
Header version: 0x10000
Size: 0x22dec
Load address: 0x2ffc2500
Entry point: 0x2ffc2500
Image version: 0x0
Option flags: 0x0
ECDSA Algo: 0x1
ECDSA pub key: 3b 71 8e 59 f1 ee 4c a8 4b 72 5f 4a 1c 63 8b 6e b8 01 ec 1a 3f 8c 98 2f d2 1d 77 f9 09 10 8f 04
30 da 5c 3a 24 53 0d 71 93 f0 a5 d9 c9 a7 27 b4 5f a5 c4 4d 55 8b 7a 25 e3 03 ef ca 87 ff 04 25
Binary type: 0x0
</syntaxhighlight>
The difference to an unsigned STM32 image header is that the values for "Signature" and "ECDSA pub key" are not all zeros and that "Option flags" is 0x0 for enabled signature verification instead of 0x1 for disabled signature verification.

==== Write U-Boot SPL and U-Boot to your boot media ====

The first step to verify that the built U-Boot SPL and U-Boot works as expected is to program both images to your boot media.
Depending on the boot configuration, your DHSOM will boot from the module's SPI-NOR flash, from the module's or baseboard's eMMC or from an SD card.
The boot configuration is always defined by the boot pins by default, because the boot pins have no alternative function on the STM32MP15 SoCs.

<div style="color:red">TODO: How can a user determine the used boot media?</div>
<div style="color:red">TODO: How to enforce boot media on Secure Boot enabled devices?</div>

===== Write U-Boot SPL and U-Boot to the SPI-NOR flash of the SoM =====

The following '''commands for the U-Boot Shell''' calculate some addresses based on the image offsets expected by the BootROM, load the required images from SD card or via TFTP into memory and finally write the prepared memory into the SPI-NOR flash on the SoM.

Prepare for loading <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> into memory:
<syntaxhighlight lang="shell">
mw.b ${loadaddr} 0xff 0x200000
setexpr fsbl1addr ${loadaddr} + 0x0
setexpr fsbl2addr ${loadaddr} + 0x40000
setexpr ssbl1addr ${loadaddr} + 0x80000
</syntaxhighlight>

Load <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> from SD card:
<syntaxhighlight lang="shell">
load mmc 0:4 ${fsbl1addr} u-boot-spl.stm32
load mmc 0:4 ${fsbl2addr} u-boot-spl.stm32
load mmc 0:4 ${ssbl1addr} u-boot.itb
</syntaxhighlight>

Load <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> from tftp server:
<syntaxhighlight lang="shell">
setenv serverip 10.20.30.1
setenv ipaddr 10.20.30.100
setenv netmask 255.255.255.0
tftp ${fsbl1addr} ${serverip}:u-boot-spl.stm32
tftp ${fsbl2addr} ${serverip}:u-boot-spl.stm32
tftp ${ssbl1addr} ${serverip}:u-boot.itb
</syntaxhighlight>

Check for magic numbers of expected image headers and conditionally program the SPI-NOR flash:
<syntaxhighlight lang="shell">
if itest *${fsbl1addr} == 0x324d5453 && itest *${fsbl2addr} == 0x324d5453 && itest *${ssbl1addr} == 0xedfe0dd0; then
sf probe && sf update ${loadaddr} 0 0x200000
fi
</syntaxhighlight>

===== Write U-Boot SPL and U-Boot to an SD card =====

<div style="color:red">TODO:</div>


===== Write U-Boot SPL and U-Boot to the eMMC =====

<div style="color:red">TODO:</div>


==== Enroll, test and enforce BootROM image authentication ====

To enroll, test and enforce image authentication by the BootROM you need to program the PKH into the OTP of the STM32MP15 SoC.
The <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> file that you created in the [[#Generate key pair with STM32MP_KeyGen_CLI|Generate key pair with STM32MP_KeyGen_CLI]] step contains the PKH in binary format for use with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> U-Boot command.
If the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command does fail or is not available on the target U-Boot, you can also write the PKH manually with the more generic <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command into the OTP.

===== Program public key hash to eFuses =====

The following '''commands for the U-Boot Shell''' load the file <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> into memory and program the contained PKH to the OTP of the STM32MP15 SoC.
The used command <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> writes and locks the words of the OTP automatically without knowing anything about the OTP layout/addresses.
If this fails or the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command is not available, you can also write and lock the OTP with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command

====== Program <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> into OTP with <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command ======

Load <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> from SD card:
<syntaxhighlight lang="shell">
load mmc 0:4 ${loadaddr} publicKeyhash.bin
</syntaxhighlight>

Or load <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> per TFTP:
<syntaxhighlight lang="shell">
setenv serverip 10.20.30.1
setenv ipaddr 10.20.30.100
setenv netmask 255.255.255.0
tftp ${loadaddr} ${serverip}:publicKeyhash.bin
</syntaxhighlight>

Show the contents of <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight>:
<syntaxhighlight lang="shell">
stm32key read ${loadaddr}
</syntaxhighlight>
<syntaxhighlight lang="console">
Read KEY at 0xc2000000
OTP value 24: 4e31bbcd
OTP value 25: 51e827dd
OTP value 26: 3511f521
OTP value 27: fd9c11a2
OTP value 28: 5b997b82
OTP value 29: 8150adc5
OTP value 30: a9c68fa9
OTP value 31: 72a3ba74
</syntaxhighlight>

Write the contents of <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> to OTP with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command:
<syntaxhighlight lang="shell">
stm32key fuse ${loadaddr}
</syntaxhighlight>
<syntaxhighlight lang="console">
TODO: Add output
</syntaxhighlight>

====== Program PKH manually into OTP with <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command ======

Generate fuse command with hexdump from file <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> on linux host:
<div style="color:red">Warning: Do not use the example output! Only use your unique values for programming the PKH in the OTP!</div>
<syntaxhighlight lang="shell">
echo fuse prog -y 0 0x18 $(hexdump -e '/4 "0x"' -e '/1 "%x"' -e '" "' /path/to/publicKeyhash.bin)
</syntaxhighlight>
<syntaxhighlight lang="console">
fuse prog -y 0 0x18 0x4e31bbcd 0x51e827dd 0x3511f521 0xfd9c11a2 0x5b997b82 0x8150adc5 0xa9c68fa9 0x72a3ba74
</syntaxhighlight>

Write the PKH into OTP manually with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<div style="color:red">Warning: Do not use the example command! Only use your unique values for programming the PKH in the OTP!</div>
<syntaxhighlight lang="shell">
fuse prog -y 0 0x18 0x4e31bbcd 0x51e827dd 0x3511f521 0xfd9c11a2 0x5b997b82 0x8150adc5 0xa9c68fa9 0x72a3ba74
</syntaxhighlight>

Lock the related OTP words manually with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<syntaxhighlight lang="shell">
fuse prog -y 0 0x10000018 1 1 1 1 1 1 1 1
</syntaxhighlight>

===== Test BootROM image authentication =====

To verify the image authentication by the BootROM with the programmed PKH and the programmed signed images, you must reboot your device.

On the third line of the U-Boot SPL output, check the BootROM authentication status.
The status output should look like this: <syntaxhighlight lang="console" inline>Bootrom authentication: succeeded</syntaxhighlight>.
Note the <syntaxhighlight lang="console" inline>succeeded</syntaxhighlight> status for successful authentication of the U-Boot SPL image by the BootROM.

The following output shows successful authentication of the U-Boot-SPL image in line 3, as well as successful authentication of the used configuration in line 7 and the U-Boot and Device Tree subimages in lines 8 and 9 of the U-Boot-FIT image.
<syntaxhighlight lang="console" line highlight="3,7-9">
U-Boot SPL 2022.01-00012-g6c5892c90c28 (Feb 16 2022 - 11:11:16 +0100)
Model: STMicroelectronics STM32MP15xx DHCOM Premium Developer Kit (2)
Bootrom authentication: succeeded
Code: SoM:rev=1,ddr3=3 Board:rev=0
RAM: DDR3L 32bits 2x4Gb 533MHz
Trying to boot from SPI
## Checking hash(es) for config config-2 ... sha256,rsa4096:fsbl-cfg-2022-02-16+ OK
## Checking hash(es) for Image uboot ... sha256,rsa4096:fsbl-img-2022-02-16+ sha256+ OK
## Checking hash(es) for Image fdt-1 ... sha256,rsa4096:fsbl-img-2022-02-16+ sha256+ OK
</syntaxhighlight>

===== Enforce BootROM image authentication =====

Without any further changes, the BootROM is able to perform authentication of the FSBL image, but unauthenticated images can still be used and executed.
The device is still open, let's see this as a kind of test mode to check if the PKH is set correctly.

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

The 6th bit in the 1st word of the OTP is responsible that the BootROM only accepts signed images.
Burning this bit enforces authentication of images by the BootROM and unsigned binaries are no longer supported on the target device.

To program this bit, the U-Boot Shell can be used with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command or with the more general <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command.

With usage of the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command:
<div style="color:red">Warning: After running the following command, your device will only be able to boot signed images!</div>
<syntaxhighlight lang="shell">
stm32key close
</syntaxhighlight>

Or with usage of the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<div style="color:red">Warning: After running the following command, your device will only be able to boot signed images!</div>
<syntaxhighlight lang="shell">
fuse prog 0 0x0 0x40
</syntaxhighlight>

== Secure Boot in Trusted Boot with BootROM authentication, TF-A and OP-TEE ==

<div style="color:red">TODO:</div>
# Add support for STM32MP15 DHCOM in <ref name="TF-A" />
# Add support for STM32MP15 DHCOM in <ref name="OP-TEE/optee_os" />
# Create stm32mp15_dhcom_trusted_defconfig???
# Integrate STM32MP15 DHCOM into <ref name="OP-TEE/build" />

== References ==

<references>
<ref name="UEFI specification">[http://www.uefi.org/specifications http://www.uefi.org/specifications]</ref>
<ref name="Basic Boot">[https://source.denx.de/u-boot/u-boot/-/blob/master/configs/stm32mp15_basic_defconfig U-Boot Source stm32mp15_basic_defconfig]</ref>
<ref name="Trusted Boot">[https://source.denx.de/u-boot/u-boot/-/blob/master/configs/stm32mp15_trusted_defconfig U-Boot Source stm32mp15_trusted_defconfig]</ref>
<ref name="BSI TR-02102">[https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.pdf BSI - Technische Richtlinie, "Kryptographische Algorithmen und Schlüssellängen", BSI TR-02102-1]</ref>
<ref name="STM32 image header">[https://wiki.st.com/stm32mpu/wiki/STM32_header_for_binary_files STM32 header for binary files]</ref>
<ref name="KeyGen_tool">[https://wiki.st.com/stm32mpu/wiki/KeyGen_tool STM32MP KeyGen tool]</ref>
<ref name="Signing_tool">[https://wiki.st.com/stm32mpu/wiki/Signing_tool STM32MP Signing tool]</ref>
<ref name="TF-A">[https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/ Trusted Firmware-A (TF-A)]</ref>
<ref name="OP-TEE/optee_os">[https://github.com/OP-TEE/optee_os OP-TEE Trusted OS]</ref>
<ref name="OP-TEE/build">[https://github.com/OP-TEE/build Makefiles to use OP-TEE on various platforms]</ref>
</references>

DHCOM STM32MP15 Secure Boot

2022-03-22T10:49:47Z

Dkierner: Fix plural of SoC /* Write U-Boot SPL and U-Boot to your boot media */

<div class="toclimit-3">__TOC__</div>

== Introduction ==

=== Abbreviations ===

{| class="wikitable sortable"
|-
! Abbreviation !! Description
|-
| BSI || Bundesamt für Sicherheit in der Informationstechnik
|-
| CoM || Computer on module
|-
| FIT || Flattened Image Tree
|-
| FSBL || Fist Stage Bootloader (TF-A or U-Boot SPL)
|-
| OTP || One Time Programmable (eFuses)
|-
| OP-TEE || Open Portable Trusted Execution Environment
|-
| PKH || Public Key Hash
|-
| ROM || Read-Only Memory
|-
| RSA || Rivest, Shamir und Adleman (asynchronous encryption)
|-
| SHA || Secure Hash Algorithm
|-
| SoC || System on chip
|-
| SoM || System on module
|-
| SSBL || Second Stage Bootloader (U-Boot)
|-
| TF-A || Trusted Firmware A
|}

=== Secure Boot ===

The term Secure Boot originally comes from the UEFI specification<ref name="UEFI specification" /> and describes a secure boot process in which only signed software is loaded and executed during the boot process.

Secure Boot is a necessary cornerstone for enforcing security mechanisms in a trusted computing environment.
Enforcing the execution of signed software only during the boot process, as long as the chain of trust is secure, can guarantee that said software is free from tampering, as any manipulation will invalidate the software's signature and prevent the software from being executed.

[[File:Secure Boot Generic en.png|600px|Secure Boot Generic]]

The figure [[Media:Secure Boot Generic en.png|Secure Boot Generic]] shows an example of a secure boot process that leads to a reset in the event of an error in the signature check. Each stage uses the certificate and signature to check the origin and integrity of the next stage. On success, the next stage is executed, and in the event of an error, this always leads to a defined error state. In the simplest case, the certificates are integrated into the binary image of the previous stage.

Program code and certificate need to be trustworthy and therefore protected against tampering in each stage, otherwise the secure boot chain can be compromised. Except for the first stage, all binary images are protected against third-party tampering by the signature. As this is practically impossible for the first stage, manipulation protection has to be enforced by hardware measures to make said stage immutable, with the first stage's program code and the verification certificate for the second stage being stored in read-only memory (ROM).

=== Basic and trusted boot in the context of Secure Boot ===

When booting Linux on the STM32MP1 SoC with U-Boot SPL and U-Boot only, STM speaks of "Basic Boot"<ref name="Basic Boot" />.
However, if Linux is booted with a combination of TF-A, U-Boot and OP-TEE, STM refers to this as "Trusted Boot"<ref name="Trusted Boot" />.

{| class="wikitable"
|-
! Boot chain !! Description
|-
| Basic boot || BootROM -> U-Boot SPL -> U-Boot -> Linux
|-
| Trusted boot || BootROM -> TF-A -> U-Boot + OP-TEE -> Linux
|}

== Secure Boot in Basic Boot with BootROM authentication and Verified Boot ==

This Secure Boot implementation does use the the BootROM integrated image authentication to authenticate the U-Boot SPL as FSBL.
Authentication of U-Boot as SSBL by the U-Boot SPL and authentication of the Linux kernel, Device Tree and ramdisk by U-Boot is done using the open source implementation [[#Verified Boot|Verified Boot]].

This also means that everything from U-Boot SPL onwards is platform independent, as we do not rely on hardware specific implementations.

=== Verified Boot ===

Developers of Google's Chromium project worked out a concept for the Verified Boot called Secure Boot mechanism on the basis of the boot loader "Das U-Boot".
They use the existing infrastructure of the FIT images and for the system configuration at runtime via a Device Tree.
The description language for the FIT images was extended by an additional signature node and the Device Tree of the platform was used to store the certificate(s) for the authentication of the images.
The signature node can be used to sign individual subimages as well as combinations of individual subimages in the FIT image.
The tool <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight> takes care the signature creation for the FIT images and the addition of the certificate in a Device Tree.

With Verified Boot, the Device Tree with included public key is integrated into the program image of the stage, which accomplishes the authentication and is thus very similar to the general procedure shown in figure [[Media:Secure Boot Generic en.png|Secure Boot Generic]].
The number of public keys that can be integrated is theoretically unlimited, but they must be distinguishable by name.

==== Technical details of Verified Boot ====

{| class="wikitable"
|-
| '''Name'''
| Verified Boot
|-
| '''Implementierung'''
| Software (Open Source)
|-
| '''Hash algorithms'''
|
* SHA1 (deprecated)<ref name="BSI TR-02102" />
* SHA256
* SHA384
* SHA512
|-
| '''Crypto algorithms
|
* RSA2048 (deprecated as of 2024)<ref name="BSI TR-02102" />
* RSA4096

* ECDSA256 (currently limited to U-Boot SPL)
|-
| '''Number of key pairs'''
| unlimited
|-
|}

==== In-depth references for Verified Boot ====


===== Flatten Image Tree =====
* [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT U-Boot Documentation: doc/uImage.FIT]
* [https://source.denx.de/u-boot/u-boot/-/commit/d5934ad7 U-Boot Commit d5934ad7: "new uImage: Add dual format uImage support framework"]
* ...
* [https://source.denx.de/u-boot/u-boot/-/commit/3310c549 U-Boot Commit d5934ad7: "new uImage: Add new uImage format documentation and examples"]

===== Verified Boot =====

* [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT/signature.txt U-Boot Documentation: doc/uImage.FIT/signature.txt]
* [https://source.denx.de/u-boot/u-boot/-/commit/3e569a6b U-Boot Commit 3e569a6b: "image: Add signing infrastructure"]
* [https://source.denx.de/u-boot/u-boot/-/commit/56518e71 U-Boot Commit 56518e71: "image: Support signing of images"]
* [https://source.denx.de/u-boot/u-boot/-/commit/4d098529 U-Boot Commit 4d098529: "image: Add support for signing of FIT configurations"]

===== ECDSA signature verification =====

<div style="color:red">TODO: Mention ECDSA limitations</div>
Note: This has currently some limitations!


* [https://source.denx.de/u-boot/u-boot/-/commit/928a8be7 U-Boot Commit 928a8be7: "lib: ecdsa: Implement UCLASS_ECDSA verification on target"]
* [https://source.denx.de/u-boot/u-boot/-/commit/ee870859 U-Boot Commit ee870859: "arm: stm32mp1: Implement ECDSA signature verification"]

=== Tutorial: Secure boot from BootROM to Linux with basic boot ===

==== System requirements and needed tools ====

The following table lists all requirements to create the key pairs and build the signed images with embedded public keys.

{| class="wikitable"
|-
! Category !! Description
|-
| '''Host operating system''' ||
* Linux (Debian 9, Ubuntu 18.04 or higher prefered)
|-
| '''Debian packages''' ||
* bison
* device-tree-compiler
* flex
* gcc-arm-linux-gnueabihf (>= gcc 6)
* git
* make
* openssl
|-
| '''STM32 Tools''' ||
* [https://www.st.com/en/development-tools/stm32cubeprog.html STM32CubeProgrammer]
** STM32MP_KeyGen_CLI
** STM32MP_SigningTool_CLI
|}

<div style="color:red">TODO: Should we give host setup instructions?</div>


==== Intended use of the four generated key pairs ====

We've decided to create and use as few certificates as reasonable to ensure a high level of security.
Therefore, we chose a separate key pair for each boot stage and also a separate key pair for image and configuration nodes.
If you're confused about the difference between image and configuration nodes, head over to [[#Flatten Image Tree|Flatten Image Tree]] to refresh your knowledge.
The exact purpose of the four key pairs generated for Verified Boot is described in the following table.

{| class="wikitable"
|-
! File name !! Intended use
|-
| '''fsbl-img''' || Authenticate image nodes of FIT images loaded by U-Boot SPL (U-Boot, Device Tree, firmware)
|-
| '''fsbl-cfg''' || Authenticate config nodes of FIT images loaded by U-Boot SPL (U-Boot + Device Tree + firmware)
|-
| '''ssbl-img''' || Authenticate image nodes of FIT images loaded by U-Boot (Kernel, Device Tree, InitRamFS)
|-
| '''ssbl-cfg''' || Authenticate config nodes of FIT images loaded by U-Boot (Kernel + Device Tree + InitRamFS)
|-
|}

==== Created/Modified files in the U-Boot source for Verified Boot ====

The created or modified files to build U-Boot with Verified Boot on STM32MP15 are described in the following table.

{| class="wikitable"
|-
! File
! Description
|-
| build_signed_uboot.sh
| Shell script that automates the creation of key pairs, the modification of FIT source files and Device Tree's and building of U-Boot SPL and U-Boot.
|-
| board/dhelectronics/dh_stm32mp1/u-boot-dhco?.its
| FIT source files with defined U-Boot image and Device Tree's for DHSOM platforms.
|-
| board/dhelectronics/dh_stm32mp1/linux-dhcom.its
| Dummy FIT source file with defined dummy kernel image and dummy Device Tree for DHSOM platforms.<br>To avoid relying on a built kernel image on a fixed path, we created this dummy, since adding the public keys with <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight> requires a valid FIT source file.
|-
| configs/stm32mp15_dhco?_secure_defconfig
| Example U-Boot defconfig's with enabled <syntaxhighlight lang="shell" inline>CONFIG_FIT_SIGNATURE</syntaxhighlight> and <syntaxhighlight lang="shell" inline>CONFIG_SPL_FIT_SIGNATURE</syntaxhighlight>.
|}

==== Build Verified Boot enabled U-Boot SPL and U-Boot ====

To build the U-Boot SPL and U-Boot images, you need to check out the source code and run a build script that automates everything from key generation to image creation and signing.

===== Checkout source code for Verified Boot =====

<div style="color:red">TODO: Replace my personal GitLab by a public available repository</div>
Checkout the branch <syntaxhighlight lang="shell" inline>v2022.01_dhcom_secure_boot</syntaxhighlight> in my personal GitLab repository with:

<syntaxhighlight lang="shell">
git clone git@dhplgl01:jneuhauser/u-boot.git -b v2022.01_dhcom_secure_boot
</syntaxhighlight>

If you already have a cloned U-Boot source code, you can also fetch it into your existing repository with:

<syntaxhighlight lang="shell">
cd /path/to/u-boot
git remote add jneuhauser git@dhplgl01:jneuhauser/u-boot.git
git fetch jneuhauser
git checkout v2022.01_dhcom_secure_boot
</syntaxhighlight>

===== Run the build script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> =====

The shell script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> included in the U-Boot source performs the following steps.
# Prebuild U-Boat SPL and U-Boat to build the required tools and Device Tree's
# Generate the [[#Intended use of the four generated key pairs|four key pairs]] if not already created
# Generate/Modify FIT image source files for Linux (dummy) and U-Boot
# Add public keys to the built Device Tree's used by U-Boot SPL and U-Boot
# Rebuild U-Boot SPL and U-Boot with new Device Tree's containing the public keys

The script supports the following environment variables to configure the target architecture, the cross compiler, the defconfig, the key algorithm, the key directory, and a key postfix:
{| class="wikitable sortable"
|-
! Name !! Description !! Default
|-
| ARCH || Target architecture for the U-Boot build || arm
|-
| CROSS_COMPILE || Used cross compiler to build U-Boot || arm-linux-gnueabihf-
|-
| DEFCONFIG || Used defconfig for the U-Boot build || stm32mp15_dhcom_secure_defconfig
|-
| KEY_ALGO || Signature algorithm used for Verified Boot || rsa
|-
| KEY_DIR || Directory where the key pairs are stored || ../keys
|-
| KEY_POSTFIX || Postfix which is appended to the key names || -$(date +%F)
|}

To perform the steps mentioned above, you just need to run the shell script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> like below.
In this example, we override the default value for <syntaxhighlight lang="shell" inline>KEY_POSTFIX</syntaxhighlight> with <syntaxhighlight lang="shell" inline>-testing</syntaxhighlight> to append this string to the [[#Intended use of the four generated key pairs|four key file names]].
The script has debug output enabled by default, which should output all the statements in the script itself and the output of the commands used in the script.
If you have any problems with the script, feel free to get in touch with [mailto:info@dh-electronics.com us] and attach a logfile.

<syntaxhighlight lang="shell">
cd /path/to/u-boot
KEY_POSTFIX="-testing" ./build_signed_uboot.sh | tee build_signed_uboot.log
</syntaxhighlight>

If this process completes without error, there are two boot loader images in the root directory of the U-Boot source.
{| class="wikitable sortable"
|-
! File name !! Stage !! Description
|-
| u-boot-spl.stm32 || FSBL || U-Boot SPL binary with appended Device Tree and prepended STM32 image header<ref name="STM32 image header" />.
|-
| u-boot.itb || SSBL || U-Boot and Device Tree's contained in a signed FIT image.
|}

==== Generate key pair and sign U-Boot SPL for BootROM authentication ====

To sign the U-Boot SPL as SSBL image for authentication with the BootROM we have to use the STM32 tools <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight> and <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight>.

===== Generate key pair with <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight> =====

All STM32MP15 SoCs only support one key pair for authenticating images through the BootROM.
To generate a ECDSA key pair for the STM32MP Secure Boot use the tool <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight><ref name="KeyGen_tool" />:
<syntaxhighlight lang="shell">
STM32MP_KeyGen_CLI --absolute-path "$(pwd)" --password <a secure password>
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Key Generator v2.9.0
-------------------------------------------------------------------

Prime256v1 curve is selected.
AES_256_cbc algorithm is selected for private key encryption
Generating Prime256v1 keys...
Private key PEM file created
Public key PEM file created
public key hash file created
Keys generated successfully.
+ public key: publicKey.pem
+ private key: privateKey.pem
+ public hash key: publicKeyhash.bin
</syntaxhighlight>

===== Sign U-Boot SPL with <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight> =====

To add the public key and the image signature to our built U-Boot SPL binary with STM32 image header, we are using the tool <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight><ref name="Signing_tool" /> to update the existing STM32 image header of <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> with the required details.
<syntaxhighlight lang="shell">
STM32MP_SigningTool_CLI --binary-image /path/to/u-boot/u-boot-spl.stm32 --public-key publicKey.pem --private-key privateKey.pem --password <a secure password> --output /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Signing Tool v2.9.0
-------------------------------------------------------------------

Prime256v1 curve is selected.
Header version 1 preparation ...
Reading Private Key File...
ECDSA signature generated.
Signature verification: SUCCESS
The Signed image file generated successfully: /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>

You can check the STM32 image header details with:
<syntaxhighlight lang="shell">
STM32MP_SigningTool_CLI --dump-header /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Signing Tool v2.9.0
-------------------------------------------------------------------

Header description:

Magic: 0x53544d32
Signature: c8 30 a0 62 2d 6d 4e 1b b9 f7 fe 38 27 65 e0 44 f0 f5 9d e6 8a a6 02 cb 74 52 26 9c 1e e9 07 17
1a c7 da 8e 96 fa 82 d3 b1 dc d5 3a 05 0e 87 83 94 4d 47 ad 17 07 88 0d b5 ae 2e 38 1d 90 22 ad
Checksum: 0xa8ca85
Header version: 0x10000
Size: 0x22dec
Load address: 0x2ffc2500
Entry point: 0x2ffc2500
Image version: 0x0
Option flags: 0x0
ECDSA Algo: 0x1
ECDSA pub key: 3b 71 8e 59 f1 ee 4c a8 4b 72 5f 4a 1c 63 8b 6e b8 01 ec 1a 3f 8c 98 2f d2 1d 77 f9 09 10 8f 04
30 da 5c 3a 24 53 0d 71 93 f0 a5 d9 c9 a7 27 b4 5f a5 c4 4d 55 8b 7a 25 e3 03 ef ca 87 ff 04 25
Binary type: 0x0
</syntaxhighlight>
The difference to an unsigned STM32 image header is that the values for "Signature" and "ECDSA pub key" are not all zeros and that "Option flags" is 0x0 for enabled signature verification instead of 0x1 for disabled signature verification.

==== Write U-Boot SPL and U-Boot to your boot media ====

The first step to verify that the built U-Boot SPL and U-Boot works as expected is to program both images to your boot media.
Depending on the boot configuration, your DHSOM will boot from the module's SPI-NOR flash, from the module's or baseboard's eMMC or from an SD card.
The boot configuration is always defined by the boot pins by default, because the boot pins have no alternative function on the STM32MP15 SoCs.

<div style="color:red">TODO: How can a user determine the used boot media?</div>
<div style="color:red">TODO: How to enforce boot media on Secure Boot enabled devices?</div>

===== Write U-Boot SPL and U-Boot to the SPI-NOR flash of the SoM =====

The following '''commands for the U-Boot Shell''' calculate some addresses based on the image offsets expected by the BootROM, load the required images from SD card or via TFTP into memory and finally write the prepared memory into the SPI-NOR flash on the SoM.

Prepare for loading <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> into memory:
<syntaxhighlight lang="shell">
mw.b ${loadaddr} 0xff 0x200000
setexpr fsbl1addr ${loadaddr} + 0x0
setexpr fsbl2addr ${loadaddr} + 0x40000
setexpr ssbl1addr ${loadaddr} + 0x80000
</syntaxhighlight>

Load <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> from SD card:
<syntaxhighlight lang="shell">
load mmc 0:4 ${fsbl1addr} u-boot-spl.stm32
load mmc 0:4 ${fsbl2addr} u-boot-spl.stm32
load mmc 0:4 ${ssbl1addr} u-boot.itb
</syntaxhighlight>

Load <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> from tftp server:
<syntaxhighlight lang="shell">
setenv serverip 10.20.30.1
setenv ipaddr 10.20.30.100
setenv netmask 255.255.255.0
tftp ${fsbl1addr} ${serverip}:u-boot-spl.stm32
tftp ${fsbl2addr} ${serverip}:u-boot-spl.stm32
tftp ${ssbl1addr} ${serverip}:u-boot.itb
</syntaxhighlight>

Check for magic numbers of expected image headers and conditionally program the SPI-NOR flash:
<syntaxhighlight lang="shell">
if itest *${fsbl1addr} == 0x324d5453 && itest *${fsbl2addr} == 0x324d5453 && itest *${ssbl1addr} == 0xedfe0dd0; then
sf probe && sf update ${loadaddr} 0 0x200000
fi
</syntaxhighlight>

===== Write U-Boot SPL and U-Boot to an SD card =====

<div style="color:red">TODO:</div>


===== Write U-Boot SPL and U-Boot to the eMMC =====

<div style="color:red">TODO:</div>


==== Enroll, test and enforce BootROM image authentication ====

To enroll, test and enforce image authentication by the BootROM you need to program the PKH into the OTP of the STM32MP15 SoC.
The <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> file that you created in the [[#Generate key pair with STM32MP_KeyGen_CLI|Generate key pair with STM32MP_KeyGen_CLI]] step contains the PKH in binary format for use with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> U-Boot command.
If the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command does fail or is not available on the target U-Boot, you can also write the PKH manually with the more generic <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command into the OTP.

===== Program public key hash to eFuses =====

The following '''commands for the U-Boot Shell''' load the file <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> into memory and program the contained PKH to the OTP of the STM32MP15 SoC.
The used command <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> writes and locks the words of the OTP automatically without knowing anything about the OTP layout/addresses.
If this fails or the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command is not available, you can also write and lock the OTP with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command

====== Program <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> into OTP with <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command ======

Load <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> by SD card:
<syntaxhighlight lang="shell">
load mmc 0:4 ${loadaddr} publicKeyhash.bin
</syntaxhighlight>

Or load <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> by TFTP:
<syntaxhighlight lang="shell">
setenv serverip 10.20.30.1
setenv ipaddr 10.20.30.100
setenv netmask 255.255.255.0
tftp ${loadaddr} ${serverip}:publicKeyhash.bin
</syntaxhighlight>

Show the contents of <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight>:
<syntaxhighlight lang="shell">
stm32key read ${loadaddr}
</syntaxhighlight>
<syntaxhighlight lang="console">
Read KEY at 0xc2000000
OTP value 24: 4e31bbcd
OTP value 25: 51e827dd
OTP value 26: 3511f521
OTP value 27: fd9c11a2
OTP value 28: 5b997b82
OTP value 29: 8150adc5
OTP value 30: a9c68fa9
OTP value 31: 72a3ba74
</syntaxhighlight>

Write the contents of <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> to OTP with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command:
<syntaxhighlight lang="shell">
stm32key fuse ${loadaddr}
</syntaxhighlight>
<syntaxhighlight lang="console">
TODO: Add output
</syntaxhighlight>

====== Program PKH manually into OTP with <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command ======

Generate fuse command with hexdump from file <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> on linux host:
<div style="color:red">Warning: Do not use the example output! Only use your unique values for programming the PKH in the OTP!</div>
<syntaxhighlight lang="shell">
echo fuse prog -y 0 0x18 $(hexdump -e '/4 "0x"' -e '/1 "%x"' -e '" "' /path/to/publicKeyhash.bin)
</syntaxhighlight>
<syntaxhighlight lang="console">
fuse prog -y 0 0x18 0x4e31bbcd 0x51e827dd 0x3511f521 0xfd9c11a2 0x5b997b82 0x8150adc5 0xa9c68fa9 0x72a3ba74
</syntaxhighlight>

Write the PKH into OTP manually with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<div style="color:red">Warning: Do not use the example command! Only use your unique values for programming the PKH in the OTP!</div>
<syntaxhighlight lang="shell">
fuse prog -y 0 0x18 0x4e31bbcd 0x51e827dd 0x3511f521 0xfd9c11a2 0x5b997b82 0x8150adc5 0xa9c68fa9 0x72a3ba74
</syntaxhighlight>

Lock the related OTP words manually with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<syntaxhighlight lang="shell">
fuse prog -y 0 0x10000018 1 1 1 1 1 1 1 1
</syntaxhighlight>

===== Test BootROM image authentication =====

To verify the image authentication by the BootROM with the programmed PKH and the programmed signed images, you must reboot your device.

On the third line of the U-Boot SPL output, check the BootROM authentication status.
The status output should look like this: <syntaxhighlight lang="console" inline>Bootrom authentication: succeeded</syntaxhighlight>.
Note the <syntaxhighlight lang="console" inline>succeeded</syntaxhighlight> status for successful authentication of the U-Boot SPL image by the BootROM.

The following output shows successful authentication of the U-Boot-SPL image in line 3, as well as successful authentication of the used configuration in line 7 and the U-Boot and Device Tree subimages in lines 8 and 9 of the U-Boot-FIT image.
<syntaxhighlight lang="console" line highlight="3,7-9">
U-Boot SPL 2022.01-00012-g6c5892c90c28 (Feb 16 2022 - 11:11:16 +0100)
Model: STMicroelectronics STM32MP15xx DHCOM Premium Developer Kit (2)
Bootrom authentication: succeeded
Code: SoM:rev=1,ddr3=3 Board:rev=0
RAM: DDR3L 32bits 2x4Gb 533MHz
Trying to boot from SPI
## Checking hash(es) for config config-2 ... sha256,rsa4096:fsbl-cfg-2022-02-16+ OK
## Checking hash(es) for Image uboot ... sha256,rsa4096:fsbl-img-2022-02-16+ sha256+ OK
## Checking hash(es) for Image fdt-1 ... sha256,rsa4096:fsbl-img-2022-02-16+ sha256+ OK
</syntaxhighlight>

===== Enforce BootROM image authentication =====

Without any further changes, the BootROM is able to perform authentication of the FSBL image, but unauthenticated images can still be used and executed.
The device is still open, let's see this as a kind of test mode to check if the PKH is set correctly.

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

The 6th bit in the 1st word of the OTP is responsible that the BootROM only accepts signed images.
Burning this bit enforces authentication of images by the BootROM and unsigned binaries are no longer supported on the target device.

To program this bit, the U-Boot Shell can be used with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command or with the more general <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command.

With usage of the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command:
<div style="color:red">Warning: After running the following command, your device will only be able to boot signed images!</div>
<syntaxhighlight lang="shell">
stm32key close
</syntaxhighlight>

Or with usage of the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<div style="color:red">Warning: After running the following command, your device will only be able to boot signed images!</div>
<syntaxhighlight lang="shell">
fuse prog 0 0x0 0x40
</syntaxhighlight>

== Secure Boot in Trusted Boot with BootROM authentication, TF-A and OP-TEE ==

<div style="color:red">TODO:</div>
# Add support for STM32MP15 DHCOM in <ref name="TF-A" />
# Add support for STM32MP15 DHCOM in <ref name="OP-TEE/optee_os" />
# Create stm32mp15_dhcom_trusted_defconfig???
# Integrate STM32MP15 DHCOM into <ref name="OP-TEE/build" />

== References ==

<references>
<ref name="UEFI specification">[http://www.uefi.org/specifications http://www.uefi.org/specifications]</ref>
<ref name="Basic Boot">[https://source.denx.de/u-boot/u-boot/-/blob/master/configs/stm32mp15_basic_defconfig U-Boot Source stm32mp15_basic_defconfig]</ref>
<ref name="Trusted Boot">[https://source.denx.de/u-boot/u-boot/-/blob/master/configs/stm32mp15_trusted_defconfig U-Boot Source stm32mp15_trusted_defconfig]</ref>
<ref name="BSI TR-02102">[https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.pdf BSI - Technische Richtlinie, "Kryptographische Algorithmen und Schlüssellängen", BSI TR-02102-1]</ref>
<ref name="STM32 image header">[https://wiki.st.com/stm32mpu/wiki/STM32_header_for_binary_files STM32 header for binary files]</ref>
<ref name="KeyGen_tool">[https://wiki.st.com/stm32mpu/wiki/KeyGen_tool STM32MP KeyGen tool]</ref>
<ref name="Signing_tool">[https://wiki.st.com/stm32mpu/wiki/Signing_tool STM32MP Signing tool]</ref>
<ref name="TF-A">[https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/ Trusted Firmware-A (TF-A)]</ref>
<ref name="OP-TEE/optee_os">[https://github.com/OP-TEE/optee_os OP-TEE Trusted OS]</ref>
<ref name="OP-TEE/build">[https://github.com/OP-TEE/build Makefiles to use OP-TEE on various platforms]</ref>
</references>

DHCOM STM32MP15 Secure Boot

2022-03-22T10:39:45Z

Dkierner: Replace example password with a reminder to use a secure password /* Sign U-Boot SPL with STM32MP_SigningTool_CLI */

<div class="toclimit-3">__TOC__</div>

== Introduction ==

=== Abbreviations ===

{| class="wikitable sortable"
|-
! Abbreviation !! Description
|-
| BSI || Bundesamt für Sicherheit in der Informationstechnik
|-
| CoM || Computer on module
|-
| FIT || Flattened Image Tree
|-
| FSBL || Fist Stage Bootloader (TF-A or U-Boot SPL)
|-
| OTP || One Time Programmable (eFuses)
|-
| OP-TEE || Open Portable Trusted Execution Environment
|-
| PKH || Public Key Hash
|-
| ROM || Read-Only Memory
|-
| RSA || Rivest, Shamir und Adleman (asynchronous encryption)
|-
| SHA || Secure Hash Algorithm
|-
| SoC || System on chip
|-
| SoM || System on module
|-
| SSBL || Second Stage Bootloader (U-Boot)
|-
| TF-A || Trusted Firmware A
|}

=== Secure Boot ===

The term Secure Boot originally comes from the UEFI specification<ref name="UEFI specification" /> and describes a secure boot process in which only signed software is loaded and executed during the boot process.

Secure Boot is a necessary cornerstone for enforcing security mechanisms in a trusted computing environment.
Enforcing the execution of signed software only during the boot process, as long as the chain of trust is secure, can guarantee that said software is free from tampering, as any manipulation will invalidate the software's signature and prevent the software from being executed.

[[File:Secure Boot Generic en.png|600px|Secure Boot Generic]]

The figure [[Media:Secure Boot Generic en.png|Secure Boot Generic]] shows an example of a secure boot process that leads to a reset in the event of an error in the signature check. Each stage uses the certificate and signature to check the origin and integrity of the next stage. On success, the next stage is executed, and in the event of an error, this always leads to a defined error state. In the simplest case, the certificates are integrated into the binary image of the previous stage.

Program code and certificate need to be trustworthy and therefore protected against tampering in each stage, otherwise the secure boot chain can be compromised. Except for the first stage, all binary images are protected against third-party tampering by the signature. As this is practically impossible for the first stage, manipulation protection has to be enforced by hardware measures to make said stage immutable, with the first stage's program code and the verification certificate for the second stage being stored in read-only memory (ROM).

=== Basic and trusted boot in the context of Secure Boot ===

When booting Linux on the STM32MP1 SoC with U-Boot SPL and U-Boot only, STM speaks of "Basic Boot"<ref name="Basic Boot" />.
However, if Linux is booted with a combination of TF-A, U-Boot and OP-TEE, STM refers to this as "Trusted Boot"<ref name="Trusted Boot" />.

{| class="wikitable"
|-
! Boot chain !! Description
|-
| Basic boot || BootROM -> U-Boot SPL -> U-Boot -> Linux
|-
| Trusted boot || BootROM -> TF-A -> U-Boot + OP-TEE -> Linux
|}

== Secure Boot in Basic Boot with BootROM authentication and Verified Boot ==

This Secure Boot implementation does use the the BootROM integrated image authentication to authenticate the U-Boot SPL as FSBL.
Authentication of U-Boot as SSBL by the U-Boot SPL and authentication of the Linux kernel, Device Tree and ramdisk by U-Boot is done using the open source implementation [[#Verified Boot|Verified Boot]].

This also means that everything from U-Boot SPL onwards is platform independent, as we do not rely on hardware specific implementations.

=== Verified Boot ===

Developers of Google's Chromium project worked out a concept for the Verified Boot called Secure Boot mechanism on the basis of the boot loader "Das U-Boot".
They use the existing infrastructure of the FIT images and for the system configuration at runtime via a Device Tree.
The description language for the FIT images was extended by an additional signature node and the Device Tree of the platform was used to store the certificate(s) for the authentication of the images.
The signature node can be used to sign individual subimages as well as combinations of individual subimages in the FIT image.
The tool <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight> takes care the signature creation for the FIT images and the addition of the certificate in a Device Tree.

With Verified Boot, the Device Tree with included public key is integrated into the program image of the stage, which accomplishes the authentication and is thus very similar to the general procedure shown in figure [[Media:Secure Boot Generic en.png|Secure Boot Generic]].
The number of public keys that can be integrated is theoretically unlimited, but they must be distinguishable by name.

==== Technical details of Verified Boot ====

{| class="wikitable"
|-
| '''Name'''
| Verified Boot
|-
| '''Implementierung'''
| Software (Open Source)
|-
| '''Hash algorithms'''
|
* SHA1 (deprecated)<ref name="BSI TR-02102" />
* SHA256
* SHA384
* SHA512
|-
| '''Crypto algorithms
|
* RSA2048 (deprecated as of 2024)<ref name="BSI TR-02102" />
* RSA4096

* ECDSA256 (currently limited to U-Boot SPL)
|-
| '''Number of key pairs'''
| unlimited
|-
|}

==== In-depth references for Verified Boot ====


===== Flatten Image Tree =====
* [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT U-Boot Documentation: doc/uImage.FIT]
* [https://source.denx.de/u-boot/u-boot/-/commit/d5934ad7 U-Boot Commit d5934ad7: "new uImage: Add dual format uImage support framework"]
* ...
* [https://source.denx.de/u-boot/u-boot/-/commit/3310c549 U-Boot Commit d5934ad7: "new uImage: Add new uImage format documentation and examples"]

===== Verified Boot =====

* [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT/signature.txt U-Boot Documentation: doc/uImage.FIT/signature.txt]
* [https://source.denx.de/u-boot/u-boot/-/commit/3e569a6b U-Boot Commit 3e569a6b: "image: Add signing infrastructure"]
* [https://source.denx.de/u-boot/u-boot/-/commit/56518e71 U-Boot Commit 56518e71: "image: Support signing of images"]
* [https://source.denx.de/u-boot/u-boot/-/commit/4d098529 U-Boot Commit 4d098529: "image: Add support for signing of FIT configurations"]

===== ECDSA signature verification =====

<div style="color:red">TODO: Mention ECDSA limitations</div>
Note: This has currently some limitations!


* [https://source.denx.de/u-boot/u-boot/-/commit/928a8be7 U-Boot Commit 928a8be7: "lib: ecdsa: Implement UCLASS_ECDSA verification on target"]
* [https://source.denx.de/u-boot/u-boot/-/commit/ee870859 U-Boot Commit ee870859: "arm: stm32mp1: Implement ECDSA signature verification"]

=== Tutorial: Secure boot from BootROM to Linux with basic boot ===

==== System requirements and needed tools ====

The following table lists all requirements to create the key pairs and build the signed images with embedded public keys.

{| class="wikitable"
|-
! Category !! Description
|-
| '''Host operating system''' ||
* Linux (Debian 9, Ubuntu 18.04 or higher prefered)
|-
| '''Debian packages''' ||
* bison
* device-tree-compiler
* flex
* gcc-arm-linux-gnueabihf (>= gcc 6)
* git
* make
* openssl
|-
| '''STM32 Tools''' ||
* [https://www.st.com/en/development-tools/stm32cubeprog.html STM32CubeProgrammer]
** STM32MP_KeyGen_CLI
** STM32MP_SigningTool_CLI
|}

<div style="color:red">TODO: Should we give host setup instructions?</div>


==== Intended use of the four generated key pairs ====

We've decided to create and use as few certificates as reasonable to ensure a high level of security.
Therefore, we chose a separate key pair for each boot stage and also a separate key pair for image and configuration nodes.
If you're confused about the difference between image and configuration nodes, head over to [[#Flatten Image Tree|Flatten Image Tree]] to refresh your knowledge.
The exact purpose of the four key pairs generated for Verified Boot is described in the following table.

{| class="wikitable"
|-
! File name !! Intended use
|-
| '''fsbl-img''' || Authenticate image nodes of FIT images loaded by U-Boot SPL (U-Boot, Device Tree, firmware)
|-
| '''fsbl-cfg''' || Authenticate config nodes of FIT images loaded by U-Boot SPL (U-Boot + Device Tree + firmware)
|-
| '''ssbl-img''' || Authenticate image nodes of FIT images loaded by U-Boot (Kernel, Device Tree, InitRamFS)
|-
| '''ssbl-cfg''' || Authenticate config nodes of FIT images loaded by U-Boot (Kernel + Device Tree + InitRamFS)
|-
|}

==== Created/Modified files in the U-Boot source for Verified Boot ====

The created or modified files to build U-Boot with Verified Boot on STM32MP15 are described in the following table.

{| class="wikitable"
|-
! File
! Description
|-
| build_signed_uboot.sh
| Shell script that automates the creation of key pairs, the modification of FIT source files and Device Tree's and building of U-Boot SPL and U-Boot.
|-
| board/dhelectronics/dh_stm32mp1/u-boot-dhco?.its
| FIT source files with defined U-Boot image and Device Tree's for DHSOM platforms.
|-
| board/dhelectronics/dh_stm32mp1/linux-dhcom.its
| Dummy FIT source file with defined dummy kernel image and dummy Device Tree for DHSOM platforms.<br>To avoid relying on a built kernel image on a fixed path, we created this dummy, since adding the public keys with <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight> requires a valid FIT source file.
|-
| configs/stm32mp15_dhco?_secure_defconfig
| Example U-Boot defconfig's with enabled <syntaxhighlight lang="shell" inline>CONFIG_FIT_SIGNATURE</syntaxhighlight> and <syntaxhighlight lang="shell" inline>CONFIG_SPL_FIT_SIGNATURE</syntaxhighlight>.
|}

==== Build Verified Boot enabled U-Boot SPL and U-Boot ====

To build the U-Boot SPL and U-Boot images, you need to check out the source code and run a build script that automates everything from key generation to image creation and signing.

===== Checkout source code for Verified Boot =====

<div style="color:red">TODO: Replace my personal GitLab by a public available repository</div>
Checkout the branch <syntaxhighlight lang="shell" inline>v2022.01_dhcom_secure_boot</syntaxhighlight> in my personal GitLab repository with:

<syntaxhighlight lang="shell">
git clone git@dhplgl01:jneuhauser/u-boot.git -b v2022.01_dhcom_secure_boot
</syntaxhighlight>

If you already have a cloned U-Boot source code, you can also fetch it into your existing repository with:

<syntaxhighlight lang="shell">
cd /path/to/u-boot
git remote add jneuhauser git@dhplgl01:jneuhauser/u-boot.git
git fetch jneuhauser
git checkout v2022.01_dhcom_secure_boot
</syntaxhighlight>

===== Run the build script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> =====

The shell script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> included in the U-Boot source performs the following steps.
# Prebuild U-Boat SPL and U-Boat to build the required tools and Device Tree's
# Generate the [[#Intended use of the four generated key pairs|four key pairs]] if not already created
# Generate/Modify FIT image source files for Linux (dummy) and U-Boot
# Add public keys to the built Device Tree's used by U-Boot SPL and U-Boot
# Rebuild U-Boot SPL and U-Boot with new Device Tree's containing the public keys

The script supports the following environment variables to configure the target architecture, the cross compiler, the defconfig, the key algorithm, the key directory, and a key postfix:
{| class="wikitable sortable"
|-
! Name !! Description !! Default
|-
| ARCH || Target architecture for the U-Boot build || arm
|-
| CROSS_COMPILE || Used cross compiler to build U-Boot || arm-linux-gnueabihf-
|-
| DEFCONFIG || Used defconfig for the U-Boot build || stm32mp15_dhcom_secure_defconfig
|-
| KEY_ALGO || Signature algorithm used for Verified Boot || rsa
|-
| KEY_DIR || Directory where the key pairs are stored || ../keys
|-
| KEY_POSTFIX || Postfix which is appended to the key names || -$(date +%F)
|}

To perform the steps mentioned above, you just need to run the shell script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> like below.
In this example, we override the default value for <syntaxhighlight lang="shell" inline>KEY_POSTFIX</syntaxhighlight> with <syntaxhighlight lang="shell" inline>-testing</syntaxhighlight> to append this string to the [[#Intended use of the four generated key pairs|four key file names]].
The script has debug output enabled by default, which should output all the statements in the script itself and the output of the commands used in the script.
If you have any problems with the script, feel free to get in touch with [mailto:info@dh-electronics.com us] and attach a logfile.

<syntaxhighlight lang="shell">
cd /path/to/u-boot
KEY_POSTFIX="-testing" ./build_signed_uboot.sh | tee build_signed_uboot.log
</syntaxhighlight>

If this process completes without error, there are two boot loader images in the root directory of the U-Boot source.
{| class="wikitable sortable"
|-
! File name !! Stage !! Description
|-
| u-boot-spl.stm32 || FSBL || U-Boot SPL binary with appended Device Tree and prepended STM32 image header<ref name="STM32 image header" />.
|-
| u-boot.itb || SSBL || U-Boot and Device Tree's contained in a signed FIT image.
|}

==== Generate key pair and sign U-Boot SPL for BootROM authentication ====

To sign the U-Boot SPL as SSBL image for authentication with the BootROM we have to use the STM32 tools <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight> and <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight>.

===== Generate key pair with <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight> =====

All STM32MP15 SoCs only support one key pair for authenticating images through the BootROM.
To generate a ECDSA key pair for the STM32MP Secure Boot use the tool <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight><ref name="KeyGen_tool" />:
<syntaxhighlight lang="shell">
STM32MP_KeyGen_CLI --absolute-path "$(pwd)" --password <a secure password>
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Key Generator v2.9.0
-------------------------------------------------------------------

Prime256v1 curve is selected.
AES_256_cbc algorithm is selected for private key encryption
Generating Prime256v1 keys...
Private key PEM file created
Public key PEM file created
public key hash file created
Keys generated successfully.
+ public key: publicKey.pem
+ private key: privateKey.pem
+ public hash key: publicKeyhash.bin
</syntaxhighlight>

===== Sign U-Boot SPL with <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight> =====

To add the public key and the image signature to our built U-Boot SPL binary with STM32 image header, we are using the tool <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight><ref name="Signing_tool" /> to update the existing STM32 image header of <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> with the required details.
<syntaxhighlight lang="shell">
STM32MP_SigningTool_CLI --binary-image /path/to/u-boot/u-boot-spl.stm32 --public-key publicKey.pem --private-key privateKey.pem --password <a secure password> --output /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Signing Tool v2.9.0
-------------------------------------------------------------------

Prime256v1 curve is selected.
Header version 1 preparation ...
Reading Private Key File...
ECDSA signature generated.
Signature verification: SUCCESS
The Signed image file generated successfully: /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>

You can check the STM32 image header details with:
<syntaxhighlight lang="shell">
STM32MP_SigningTool_CLI --dump-header /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Signing Tool v2.9.0
-------------------------------------------------------------------

Header description:

Magic: 0x53544d32
Signature: c8 30 a0 62 2d 6d 4e 1b b9 f7 fe 38 27 65 e0 44 f0 f5 9d e6 8a a6 02 cb 74 52 26 9c 1e e9 07 17
1a c7 da 8e 96 fa 82 d3 b1 dc d5 3a 05 0e 87 83 94 4d 47 ad 17 07 88 0d b5 ae 2e 38 1d 90 22 ad
Checksum: 0xa8ca85
Header version: 0x10000
Size: 0x22dec
Load address: 0x2ffc2500
Entry point: 0x2ffc2500
Image version: 0x0
Option flags: 0x0
ECDSA Algo: 0x1
ECDSA pub key: 3b 71 8e 59 f1 ee 4c a8 4b 72 5f 4a 1c 63 8b 6e b8 01 ec 1a 3f 8c 98 2f d2 1d 77 f9 09 10 8f 04
30 da 5c 3a 24 53 0d 71 93 f0 a5 d9 c9 a7 27 b4 5f a5 c4 4d 55 8b 7a 25 e3 03 ef ca 87 ff 04 25
Binary type: 0x0
</syntaxhighlight>
The difference to an unsigned STM32 image header is that the values for "Signature" and "ECDSA pub key" are not all zeros and that "Option flags" is 0x0 for enabled signature verification instead of 0x1 for disabled signature verification.

==== Write U-Boot SPL and U-Boot to your boot media ====

The first step to verify that the built U-Boot SPL and U-Boot works as expected is to program both images to your boot media.
Depending on the boot configuration, your DHSOM will boot from the module's SPI-NOR flash, from the module's or baseboard's eMMC or from an SD card.
The boot configuration is always defined by the boot pins by default, because the boot pins have no alternative function on the STM32MP15 SoC's.

<div style="color:red">TODO: How can a user determine the used boot media?</div>
<div style="color:red">TODO: How to enforce boot media on Secure Boot enabled devices?</div>

===== Write U-Boot SPL and U-Boot to the SPI-NOR flash of the SoM =====

The following '''commands for the U-Boot Shell''' calculate some addresses based on the image offsets expected by the BootROM, load the required images from SD card or via TFTP into memory and finally write the prepared memory into the SPI-NOR flash on the SoM.

Prepare for loading <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> into memory:
<syntaxhighlight lang="shell">
mw.b ${loadaddr} 0xff 0x200000
setexpr fsbl1addr ${loadaddr} + 0x0
setexpr fsbl2addr ${loadaddr} + 0x40000
setexpr ssbl1addr ${loadaddr} + 0x80000
</syntaxhighlight>

Load <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> from SD card:
<syntaxhighlight lang="shell">
load mmc 0:4 ${fsbl1addr} u-boot-spl.stm32
load mmc 0:4 ${fsbl2addr} u-boot-spl.stm32
load mmc 0:4 ${ssbl1addr} u-boot.itb
</syntaxhighlight>

Load <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> from tftp server:
<syntaxhighlight lang="shell">
setenv serverip 10.20.30.1
setenv ipaddr 10.20.30.100
setenv netmask 255.255.255.0
tftp ${fsbl1addr} ${serverip}:u-boot-spl.stm32
tftp ${fsbl2addr} ${serverip}:u-boot-spl.stm32
tftp ${ssbl1addr} ${serverip}:u-boot.itb
</syntaxhighlight>

Check for magic numbers of expected image headers and conditionally program the SPI-NOR flash:
<syntaxhighlight lang="shell">
if itest *${fsbl1addr} == 0x324d5453 && itest *${fsbl2addr} == 0x324d5453 && itest *${ssbl1addr} == 0xedfe0dd0; then
sf probe && sf update ${loadaddr} 0 0x200000
fi
</syntaxhighlight>

===== Write U-Boot SPL and U-Boot to an SD card =====

<div style="color:red">TODO:</div>


===== Write U-Boot SPL and U-Boot to the eMMC =====

<div style="color:red">TODO:</div>


==== Enroll, test and enforce BootROM image authentication ====

To enroll, test and enforce image authentication by the BootROM you need to program the PKH into the OTP of the STM32MP15 SoC.
The <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> file that you created in the [[#Generate key pair with STM32MP_KeyGen_CLI|Generate key pair with STM32MP_KeyGen_CLI]] step contains the PKH in binary format for use with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> U-Boot command.
If the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command does fail or is not available on the target U-Boot, you can also write the PKH manually with the more generic <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command into the OTP.

===== Program public key hash to eFuses =====

The following '''commands for the U-Boot Shell''' load the file <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> into memory and program the contained PKH to the OTP of the STM32MP15 SoC.
The used command <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> writes and locks the words of the OTP automatically without knowing anything about the OTP layout/addresses.
If this fails or the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command is not available, you can also write and lock the OTP with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command

====== Program <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> into OTP with <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command ======

Load <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> by SD card:
<syntaxhighlight lang="shell">
load mmc 0:4 ${loadaddr} publicKeyhash.bin
</syntaxhighlight>

Or load <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> by TFTP:
<syntaxhighlight lang="shell">
setenv serverip 10.20.30.1
setenv ipaddr 10.20.30.100
setenv netmask 255.255.255.0
tftp ${loadaddr} ${serverip}:publicKeyhash.bin
</syntaxhighlight>

Show the contents of <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight>:
<syntaxhighlight lang="shell">
stm32key read ${loadaddr}
</syntaxhighlight>
<syntaxhighlight lang="console">
Read KEY at 0xc2000000
OTP value 24: 4e31bbcd
OTP value 25: 51e827dd
OTP value 26: 3511f521
OTP value 27: fd9c11a2
OTP value 28: 5b997b82
OTP value 29: 8150adc5
OTP value 30: a9c68fa9
OTP value 31: 72a3ba74
</syntaxhighlight>

Write the contents of <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> to OTP with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command:
<syntaxhighlight lang="shell">
stm32key fuse ${loadaddr}
</syntaxhighlight>
<syntaxhighlight lang="console">
TODO: Add output
</syntaxhighlight>

====== Program PKH manually into OTP with <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command ======

Generate fuse command with hexdump from file <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> on linux host:
<div style="color:red">Warning: Do not use the example output! Only use your unique values for programming the PKH in the OTP!</div>
<syntaxhighlight lang="shell">
echo fuse prog -y 0 0x18 $(hexdump -e '/4 "0x"' -e '/1 "%x"' -e '" "' /path/to/publicKeyhash.bin)
</syntaxhighlight>
<syntaxhighlight lang="console">
fuse prog -y 0 0x18 0x4e31bbcd 0x51e827dd 0x3511f521 0xfd9c11a2 0x5b997b82 0x8150adc5 0xa9c68fa9 0x72a3ba74
</syntaxhighlight>

Write the PKH into OTP manually with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<div style="color:red">Warning: Do not use the example command! Only use your unique values for programming the PKH in the OTP!</div>
<syntaxhighlight lang="shell">
fuse prog -y 0 0x18 0x4e31bbcd 0x51e827dd 0x3511f521 0xfd9c11a2 0x5b997b82 0x8150adc5 0xa9c68fa9 0x72a3ba74
</syntaxhighlight>

Lock the related OTP words manually with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<syntaxhighlight lang="shell">
fuse prog -y 0 0x10000018 1 1 1 1 1 1 1 1
</syntaxhighlight>

===== Test BootROM image authentication =====

To verify the image authentication by the BootROM with the programmed PKH and the programmed signed images, you must reboot your device.

On the third line of the U-Boot SPL output, check the BootROM authentication status.
The status output should look like this: <syntaxhighlight lang="console" inline>Bootrom authentication: succeeded</syntaxhighlight>.
Note the <syntaxhighlight lang="console" inline>succeeded</syntaxhighlight> status for successful authentication of the U-Boot SPL image by the BootROM.

The following output shows successful authentication of the U-Boot-SPL image in line 3, as well as successful authentication of the used configuration in line 7 and the U-Boot and Device Tree subimages in lines 8 and 9 of the U-Boot-FIT image.
<syntaxhighlight lang="console" line highlight="3,7-9">
U-Boot SPL 2022.01-00012-g6c5892c90c28 (Feb 16 2022 - 11:11:16 +0100)
Model: STMicroelectronics STM32MP15xx DHCOM Premium Developer Kit (2)
Bootrom authentication: succeeded
Code: SoM:rev=1,ddr3=3 Board:rev=0
RAM: DDR3L 32bits 2x4Gb 533MHz
Trying to boot from SPI
## Checking hash(es) for config config-2 ... sha256,rsa4096:fsbl-cfg-2022-02-16+ OK
## Checking hash(es) for Image uboot ... sha256,rsa4096:fsbl-img-2022-02-16+ sha256+ OK
## Checking hash(es) for Image fdt-1 ... sha256,rsa4096:fsbl-img-2022-02-16+ sha256+ OK
</syntaxhighlight>

===== Enforce BootROM image authentication =====

Without any further changes, the BootROM is able to perform authentication of the FSBL image, but unauthenticated images can still be used and executed.
The device is still open, let's see this as a kind of test mode to check if the PKH is set correctly.

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

The 6th bit in the 1st word of the OTP is responsible that the BootROM only accepts signed images.
Burning this bit enforces authentication of images by the BootROM and unsigned binaries are no longer supported on the target device.

To program this bit, the U-Boot Shell can be used with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command or with the more general <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command.

With usage of the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command:
<div style="color:red">Warning: After running the following command, your device will only be able to boot signed images!</div>
<syntaxhighlight lang="shell">
stm32key close
</syntaxhighlight>

Or with usage of the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<div style="color:red">Warning: After running the following command, your device will only be able to boot signed images!</div>
<syntaxhighlight lang="shell">
fuse prog 0 0x0 0x40
</syntaxhighlight>

== Secure Boot in Trusted Boot with BootROM authentication, TF-A and OP-TEE ==

<div style="color:red">TODO:</div>
# Add support for STM32MP15 DHCOM in <ref name="TF-A" />
# Add support for STM32MP15 DHCOM in <ref name="OP-TEE/optee_os" />
# Create stm32mp15_dhcom_trusted_defconfig???
# Integrate STM32MP15 DHCOM into <ref name="OP-TEE/build" />

== References ==

<references>
<ref name="UEFI specification">[http://www.uefi.org/specifications http://www.uefi.org/specifications]</ref>
<ref name="Basic Boot">[https://source.denx.de/u-boot/u-boot/-/blob/master/configs/stm32mp15_basic_defconfig U-Boot Source stm32mp15_basic_defconfig]</ref>
<ref name="Trusted Boot">[https://source.denx.de/u-boot/u-boot/-/blob/master/configs/stm32mp15_trusted_defconfig U-Boot Source stm32mp15_trusted_defconfig]</ref>
<ref name="BSI TR-02102">[https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.pdf BSI - Technische Richtlinie, "Kryptographische Algorithmen und Schlüssellängen", BSI TR-02102-1]</ref>
<ref name="STM32 image header">[https://wiki.st.com/stm32mpu/wiki/STM32_header_for_binary_files STM32 header for binary files]</ref>
<ref name="KeyGen_tool">[https://wiki.st.com/stm32mpu/wiki/KeyGen_tool STM32MP KeyGen tool]</ref>
<ref name="Signing_tool">[https://wiki.st.com/stm32mpu/wiki/Signing_tool STM32MP Signing tool]</ref>
<ref name="TF-A">[https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/ Trusted Firmware-A (TF-A)]</ref>
<ref name="OP-TEE/optee_os">[https://github.com/OP-TEE/optee_os OP-TEE Trusted OS]</ref>
<ref name="OP-TEE/build">[https://github.com/OP-TEE/build Makefiles to use OP-TEE on various platforms]</ref>
</references>

DHCOM STM32MP15 Secure Boot

2022-03-22T10:36:11Z

Dkierner: Replace example password with a reminder to use a secure password /* Generate key pair with STM32MP_KeyGen_CLI */

<div class="toclimit-3">__TOC__</div>

== Introduction ==

=== Abbreviations ===

{| class="wikitable sortable"
|-
! Abbreviation !! Description
|-
| BSI || Bundesamt für Sicherheit in der Informationstechnik
|-
| CoM || Computer on module
|-
| FIT || Flattened Image Tree
|-
| FSBL || Fist Stage Bootloader (TF-A or U-Boot SPL)
|-
| OTP || One Time Programmable (eFuses)
|-
| OP-TEE || Open Portable Trusted Execution Environment
|-
| PKH || Public Key Hash
|-
| ROM || Read-Only Memory
|-
| RSA || Rivest, Shamir und Adleman (asynchronous encryption)
|-
| SHA || Secure Hash Algorithm
|-
| SoC || System on chip
|-
| SoM || System on module
|-
| SSBL || Second Stage Bootloader (U-Boot)
|-
| TF-A || Trusted Firmware A
|}

=== Secure Boot ===

The term Secure Boot originally comes from the UEFI specification<ref name="UEFI specification" /> and describes a secure boot process in which only signed software is loaded and executed during the boot process.

Secure Boot is a necessary cornerstone for enforcing security mechanisms in a trusted computing environment.
Enforcing the execution of signed software only during the boot process, as long as the chain of trust is secure, can guarantee that said software is free from tampering, as any manipulation will invalidate the software's signature and prevent the software from being executed.

[[File:Secure Boot Generic en.png|600px|Secure Boot Generic]]

The figure [[Media:Secure Boot Generic en.png|Secure Boot Generic]] shows an example of a secure boot process that leads to a reset in the event of an error in the signature check. Each stage uses the certificate and signature to check the origin and integrity of the next stage. On success, the next stage is executed, and in the event of an error, this always leads to a defined error state. In the simplest case, the certificates are integrated into the binary image of the previous stage.

Program code and certificate need to be trustworthy and therefore protected against tampering in each stage, otherwise the secure boot chain can be compromised. Except for the first stage, all binary images are protected against third-party tampering by the signature. As this is practically impossible for the first stage, manipulation protection has to be enforced by hardware measures to make said stage immutable, with the first stage's program code and the verification certificate for the second stage being stored in read-only memory (ROM).

=== Basic and trusted boot in the context of Secure Boot ===

When booting Linux on the STM32MP1 SoC with U-Boot SPL and U-Boot only, STM speaks of "Basic Boot"<ref name="Basic Boot" />.
However, if Linux is booted with a combination of TF-A, U-Boot and OP-TEE, STM refers to this as "Trusted Boot"<ref name="Trusted Boot" />.

{| class="wikitable"
|-
! Boot chain !! Description
|-
| Basic boot || BootROM -> U-Boot SPL -> U-Boot -> Linux
|-
| Trusted boot || BootROM -> TF-A -> U-Boot + OP-TEE -> Linux
|}

== Secure Boot in Basic Boot with BootROM authentication and Verified Boot ==

This Secure Boot implementation does use the the BootROM integrated image authentication to authenticate the U-Boot SPL as FSBL.
Authentication of U-Boot as SSBL by the U-Boot SPL and authentication of the Linux kernel, Device Tree and ramdisk by U-Boot is done using the open source implementation [[#Verified Boot|Verified Boot]].

This also means that everything from U-Boot SPL onwards is platform independent, as we do not rely on hardware specific implementations.

=== Verified Boot ===

Developers of Google's Chromium project worked out a concept for the Verified Boot called Secure Boot mechanism on the basis of the boot loader "Das U-Boot".
They use the existing infrastructure of the FIT images and for the system configuration at runtime via a Device Tree.
The description language for the FIT images was extended by an additional signature node and the Device Tree of the platform was used to store the certificate(s) for the authentication of the images.
The signature node can be used to sign individual subimages as well as combinations of individual subimages in the FIT image.
The tool <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight> takes care the signature creation for the FIT images and the addition of the certificate in a Device Tree.

With Verified Boot, the Device Tree with included public key is integrated into the program image of the stage, which accomplishes the authentication and is thus very similar to the general procedure shown in figure [[Media:Secure Boot Generic en.png|Secure Boot Generic]].
The number of public keys that can be integrated is theoretically unlimited, but they must be distinguishable by name.

==== Technical details of Verified Boot ====

{| class="wikitable"
|-
| '''Name'''
| Verified Boot
|-
| '''Implementierung'''
| Software (Open Source)
|-
| '''Hash algorithms'''
|
* SHA1 (deprecated)<ref name="BSI TR-02102" />
* SHA256
* SHA384
* SHA512
|-
| '''Crypto algorithms
|
* RSA2048 (deprecated as of 2024)<ref name="BSI TR-02102" />
* RSA4096

* ECDSA256 (currently limited to U-Boot SPL)
|-
| '''Number of key pairs'''
| unlimited
|-
|}

==== In-depth references for Verified Boot ====


===== Flatten Image Tree =====
* [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT U-Boot Documentation: doc/uImage.FIT]
* [https://source.denx.de/u-boot/u-boot/-/commit/d5934ad7 U-Boot Commit d5934ad7: "new uImage: Add dual format uImage support framework"]
* ...
* [https://source.denx.de/u-boot/u-boot/-/commit/3310c549 U-Boot Commit d5934ad7: "new uImage: Add new uImage format documentation and examples"]

===== Verified Boot =====

* [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT/signature.txt U-Boot Documentation: doc/uImage.FIT/signature.txt]
* [https://source.denx.de/u-boot/u-boot/-/commit/3e569a6b U-Boot Commit 3e569a6b: "image: Add signing infrastructure"]
* [https://source.denx.de/u-boot/u-boot/-/commit/56518e71 U-Boot Commit 56518e71: "image: Support signing of images"]
* [https://source.denx.de/u-boot/u-boot/-/commit/4d098529 U-Boot Commit 4d098529: "image: Add support for signing of FIT configurations"]

===== ECDSA signature verification =====

<div style="color:red">TODO: Mention ECDSA limitations</div>
Note: This has currently some limitations!


* [https://source.denx.de/u-boot/u-boot/-/commit/928a8be7 U-Boot Commit 928a8be7: "lib: ecdsa: Implement UCLASS_ECDSA verification on target"]
* [https://source.denx.de/u-boot/u-boot/-/commit/ee870859 U-Boot Commit ee870859: "arm: stm32mp1: Implement ECDSA signature verification"]

=== Tutorial: Secure boot from BootROM to Linux with basic boot ===

==== System requirements and needed tools ====

The following table lists all requirements to create the key pairs and build the signed images with embedded public keys.

{| class="wikitable"
|-
! Category !! Description
|-
| '''Host operating system''' ||
* Linux (Debian 9, Ubuntu 18.04 or higher prefered)
|-
| '''Debian packages''' ||
* bison
* device-tree-compiler
* flex
* gcc-arm-linux-gnueabihf (>= gcc 6)
* git
* make
* openssl
|-
| '''STM32 Tools''' ||
* [https://www.st.com/en/development-tools/stm32cubeprog.html STM32CubeProgrammer]
** STM32MP_KeyGen_CLI
** STM32MP_SigningTool_CLI
|}

<div style="color:red">TODO: Should we give host setup instructions?</div>


==== Intended use of the four generated key pairs ====

We've decided to create and use as few certificates as reasonable to ensure a high level of security.
Therefore, we chose a separate key pair for each boot stage and also a separate key pair for image and configuration nodes.
If you're confused about the difference between image and configuration nodes, head over to [[#Flatten Image Tree|Flatten Image Tree]] to refresh your knowledge.
The exact purpose of the four key pairs generated for Verified Boot is described in the following table.

{| class="wikitable"
|-
! File name !! Intended use
|-
| '''fsbl-img''' || Authenticate image nodes of FIT images loaded by U-Boot SPL (U-Boot, Device Tree, firmware)
|-
| '''fsbl-cfg''' || Authenticate config nodes of FIT images loaded by U-Boot SPL (U-Boot + Device Tree + firmware)
|-
| '''ssbl-img''' || Authenticate image nodes of FIT images loaded by U-Boot (Kernel, Device Tree, InitRamFS)
|-
| '''ssbl-cfg''' || Authenticate config nodes of FIT images loaded by U-Boot (Kernel + Device Tree + InitRamFS)
|-
|}

==== Created/Modified files in the U-Boot source for Verified Boot ====

The created or modified files to build U-Boot with Verified Boot on STM32MP15 are described in the following table.

{| class="wikitable"
|-
! File
! Description
|-
| build_signed_uboot.sh
| Shell script that automates the creation of key pairs, the modification of FIT source files and Device Tree's and building of U-Boot SPL and U-Boot.
|-
| board/dhelectronics/dh_stm32mp1/u-boot-dhco?.its
| FIT source files with defined U-Boot image and Device Tree's for DHSOM platforms.
|-
| board/dhelectronics/dh_stm32mp1/linux-dhcom.its
| Dummy FIT source file with defined dummy kernel image and dummy Device Tree for DHSOM platforms.<br>To avoid relying on a built kernel image on a fixed path, we created this dummy, since adding the public keys with <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight> requires a valid FIT source file.
|-
| configs/stm32mp15_dhco?_secure_defconfig
| Example U-Boot defconfig's with enabled <syntaxhighlight lang="shell" inline>CONFIG_FIT_SIGNATURE</syntaxhighlight> and <syntaxhighlight lang="shell" inline>CONFIG_SPL_FIT_SIGNATURE</syntaxhighlight>.
|}

==== Build Verified Boot enabled U-Boot SPL and U-Boot ====

To build the U-Boot SPL and U-Boot images, you need to check out the source code and run a build script that automates everything from key generation to image creation and signing.

===== Checkout source code for Verified Boot =====

<div style="color:red">TODO: Replace my personal GitLab by a public available repository</div>
Checkout the branch <syntaxhighlight lang="shell" inline>v2022.01_dhcom_secure_boot</syntaxhighlight> in my personal GitLab repository with:

<syntaxhighlight lang="shell">
git clone git@dhplgl01:jneuhauser/u-boot.git -b v2022.01_dhcom_secure_boot
</syntaxhighlight>

If you already have a cloned U-Boot source code, you can also fetch it into your existing repository with:

<syntaxhighlight lang="shell">
cd /path/to/u-boot
git remote add jneuhauser git@dhplgl01:jneuhauser/u-boot.git
git fetch jneuhauser
git checkout v2022.01_dhcom_secure_boot
</syntaxhighlight>

===== Run the build script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> =====

The shell script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> included in the U-Boot source performs the following steps.
# Prebuild U-Boat SPL and U-Boat to build the required tools and Device Tree's
# Generate the [[#Intended use of the four generated key pairs|four key pairs]] if not already created
# Generate/Modify FIT image source files for Linux (dummy) and U-Boot
# Add public keys to the built Device Tree's used by U-Boot SPL and U-Boot
# Rebuild U-Boot SPL and U-Boot with new Device Tree's containing the public keys

The script supports the following environment variables to configure the target architecture, the cross compiler, the defconfig, the key algorithm, the key directory, and a key postfix:
{| class="wikitable sortable"
|-
! Name !! Description !! Default
|-
| ARCH || Target architecture for the U-Boot build || arm
|-
| CROSS_COMPILE || Used cross compiler to build U-Boot || arm-linux-gnueabihf-
|-
| DEFCONFIG || Used defconfig for the U-Boot build || stm32mp15_dhcom_secure_defconfig
|-
| KEY_ALGO || Signature algorithm used for Verified Boot || rsa
|-
| KEY_DIR || Directory where the key pairs are stored || ../keys
|-
| KEY_POSTFIX || Postfix which is appended to the key names || -$(date +%F)
|}

To perform the steps mentioned above, you just need to run the shell script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> like below.
In this example, we override the default value for <syntaxhighlight lang="shell" inline>KEY_POSTFIX</syntaxhighlight> with <syntaxhighlight lang="shell" inline>-testing</syntaxhighlight> to append this string to the [[#Intended use of the four generated key pairs|four key file names]].
The script has debug output enabled by default, which should output all the statements in the script itself and the output of the commands used in the script.
If you have any problems with the script, feel free to get in touch with [mailto:info@dh-electronics.com us] and attach a logfile.

<syntaxhighlight lang="shell">
cd /path/to/u-boot
KEY_POSTFIX="-testing" ./build_signed_uboot.sh | tee build_signed_uboot.log
</syntaxhighlight>

If this process completes without error, there are two boot loader images in the root directory of the U-Boot source.
{| class="wikitable sortable"
|-
! File name !! Stage !! Description
|-
| u-boot-spl.stm32 || FSBL || U-Boot SPL binary with appended Device Tree and prepended STM32 image header<ref name="STM32 image header" />.
|-
| u-boot.itb || SSBL || U-Boot and Device Tree's contained in a signed FIT image.
|}

==== Generate key pair and sign U-Boot SPL for BootROM authentication ====

To sign the U-Boot SPL as SSBL image for authentication with the BootROM we have to use the STM32 tools <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight> and <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight>.

===== Generate key pair with <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight> =====

All STM32MP15 SoCs only support one key pair for authenticating images through the BootROM.
To generate a ECDSA key pair for the STM32MP Secure Boot use the tool <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight><ref name="KeyGen_tool" />:
<syntaxhighlight lang="shell">
STM32MP_KeyGen_CLI --absolute-path "$(pwd)" --password <a secure password>
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Key Generator v2.9.0
-------------------------------------------------------------------

Prime256v1 curve is selected.
AES_256_cbc algorithm is selected for private key encryption
Generating Prime256v1 keys...
Private key PEM file created
Public key PEM file created
public key hash file created
Keys generated successfully.
+ public key: publicKey.pem
+ private key: privateKey.pem
+ public hash key: publicKeyhash.bin
</syntaxhighlight>

===== Sign U-Boot SPL with <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight> =====

To add the public key and the image signature to our built U-Boot SPL binary with STM32 image header, we are using the tool <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight><ref name="Signing_tool" /> to update the existing STM32 image header of <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> with the required details.
<syntaxhighlight lang="shell">
STM32MP_SigningTool_CLI --binary-image /path/to/u-boot/u-boot-spl.stm32 --public-key publicKey.pem --private-key privateKey.pem --password 12345678 --output /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Signing Tool v2.9.0
-------------------------------------------------------------------

Prime256v1 curve is selected.
Header version 1 preparation ...
Reading Private Key File...
ECDSA signature generated.
Signature verification: SUCCESS
The Signed image file generated successfully: /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>

You can check the STM32 image header details with:
<syntaxhighlight lang="shell">
STM32MP_SigningTool_CLI --dump-header /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Signing Tool v2.9.0
-------------------------------------------------------------------

Header description:

Magic: 0x53544d32
Signature: c8 30 a0 62 2d 6d 4e 1b b9 f7 fe 38 27 65 e0 44 f0 f5 9d e6 8a a6 02 cb 74 52 26 9c 1e e9 07 17
1a c7 da 8e 96 fa 82 d3 b1 dc d5 3a 05 0e 87 83 94 4d 47 ad 17 07 88 0d b5 ae 2e 38 1d 90 22 ad
Checksum: 0xa8ca85
Header version: 0x10000
Size: 0x22dec
Load address: 0x2ffc2500
Entry point: 0x2ffc2500
Image version: 0x0
Option flags: 0x0
ECDSA Algo: 0x1
ECDSA pub key: 3b 71 8e 59 f1 ee 4c a8 4b 72 5f 4a 1c 63 8b 6e b8 01 ec 1a 3f 8c 98 2f d2 1d 77 f9 09 10 8f 04
30 da 5c 3a 24 53 0d 71 93 f0 a5 d9 c9 a7 27 b4 5f a5 c4 4d 55 8b 7a 25 e3 03 ef ca 87 ff 04 25
Binary type: 0x0
</syntaxhighlight>
The difference to an unsigned STM32 image header is that the values for "Signature" and "ECDSA pub key" are not all zeros and that "Option flags" is 0x0 for enabled signature verification instead of 0x1 for disabled signature verification.

==== Write U-Boot SPL and U-Boot to your boot media ====

The first step to verify that the built U-Boot SPL and U-Boot works as expected is to program both images to your boot media.
Depending on the boot configuration, your DHSOM will boot from the module's SPI-NOR flash, from the module's or baseboard's eMMC or from an SD card.
The boot configuration is always defined by the boot pins by default, because the boot pins have no alternative function on the STM32MP15 SoC's.

<div style="color:red">TODO: How can a user determine the used boot media?</div>
<div style="color:red">TODO: How to enforce boot media on Secure Boot enabled devices?</div>

===== Write U-Boot SPL and U-Boot to the SPI-NOR flash of the SoM =====

The following '''commands for the U-Boot Shell''' calculate some addresses based on the image offsets expected by the BootROM, load the required images from SD card or via TFTP into memory and finally write the prepared memory into the SPI-NOR flash on the SoM.

Prepare for loading <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> into memory:
<syntaxhighlight lang="shell">
mw.b ${loadaddr} 0xff 0x200000
setexpr fsbl1addr ${loadaddr} + 0x0
setexpr fsbl2addr ${loadaddr} + 0x40000
setexpr ssbl1addr ${loadaddr} + 0x80000
</syntaxhighlight>

Load <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> from SD card:
<syntaxhighlight lang="shell">
load mmc 0:4 ${fsbl1addr} u-boot-spl.stm32
load mmc 0:4 ${fsbl2addr} u-boot-spl.stm32
load mmc 0:4 ${ssbl1addr} u-boot.itb
</syntaxhighlight>

Load <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> from tftp server:
<syntaxhighlight lang="shell">
setenv serverip 10.20.30.1
setenv ipaddr 10.20.30.100
setenv netmask 255.255.255.0
tftp ${fsbl1addr} ${serverip}:u-boot-spl.stm32
tftp ${fsbl2addr} ${serverip}:u-boot-spl.stm32
tftp ${ssbl1addr} ${serverip}:u-boot.itb
</syntaxhighlight>

Check for magic numbers of expected image headers and conditionally program the SPI-NOR flash:
<syntaxhighlight lang="shell">
if itest *${fsbl1addr} == 0x324d5453 && itest *${fsbl2addr} == 0x324d5453 && itest *${ssbl1addr} == 0xedfe0dd0; then
sf probe && sf update ${loadaddr} 0 0x200000
fi
</syntaxhighlight>

===== Write U-Boot SPL and U-Boot to an SD card =====

<div style="color:red">TODO:</div>


===== Write U-Boot SPL and U-Boot to the eMMC =====

<div style="color:red">TODO:</div>


==== Enroll, test and enforce BootROM image authentication ====

To enroll, test and enforce image authentication by the BootROM you need to program the PKH into the OTP of the STM32MP15 SoC.
The <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> file that you created in the [[#Generate key pair with STM32MP_KeyGen_CLI|Generate key pair with STM32MP_KeyGen_CLI]] step contains the PKH in binary format for use with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> U-Boot command.
If the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command does fail or is not available on the target U-Boot, you can also write the PKH manually with the more generic <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command into the OTP.

===== Program public key hash to eFuses =====

The following '''commands for the U-Boot Shell''' load the file <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> into memory and program the contained PKH to the OTP of the STM32MP15 SoC.
The used command <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> writes and locks the words of the OTP automatically without knowing anything about the OTP layout/addresses.
If this fails or the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command is not available, you can also write and lock the OTP with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command

====== Program <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> into OTP with <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command ======

Load <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> by SD card:
<syntaxhighlight lang="shell">
load mmc 0:4 ${loadaddr} publicKeyhash.bin
</syntaxhighlight>

Or load <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> by TFTP:
<syntaxhighlight lang="shell">
setenv serverip 10.20.30.1
setenv ipaddr 10.20.30.100
setenv netmask 255.255.255.0
tftp ${loadaddr} ${serverip}:publicKeyhash.bin
</syntaxhighlight>

Show the contents of <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight>:
<syntaxhighlight lang="shell">
stm32key read ${loadaddr}
</syntaxhighlight>
<syntaxhighlight lang="console">
Read KEY at 0xc2000000
OTP value 24: 4e31bbcd
OTP value 25: 51e827dd
OTP value 26: 3511f521
OTP value 27: fd9c11a2
OTP value 28: 5b997b82
OTP value 29: 8150adc5
OTP value 30: a9c68fa9
OTP value 31: 72a3ba74
</syntaxhighlight>

Write the contents of <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> to OTP with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command:
<syntaxhighlight lang="shell">
stm32key fuse ${loadaddr}
</syntaxhighlight>
<syntaxhighlight lang="console">
TODO: Add output
</syntaxhighlight>

====== Program PKH manually into OTP with <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command ======

Generate fuse command with hexdump from file <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> on linux host:
<div style="color:red">Warning: Do not use the example output! Only use your unique values for programming the PKH in the OTP!</div>
<syntaxhighlight lang="shell">
echo fuse prog -y 0 0x18 $(hexdump -e '/4 "0x"' -e '/1 "%x"' -e '" "' /path/to/publicKeyhash.bin)
</syntaxhighlight>
<syntaxhighlight lang="console">
fuse prog -y 0 0x18 0x4e31bbcd 0x51e827dd 0x3511f521 0xfd9c11a2 0x5b997b82 0x8150adc5 0xa9c68fa9 0x72a3ba74
</syntaxhighlight>

Write the PKH into OTP manually with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<div style="color:red">Warning: Do not use the example command! Only use your unique values for programming the PKH in the OTP!</div>
<syntaxhighlight lang="shell">
fuse prog -y 0 0x18 0x4e31bbcd 0x51e827dd 0x3511f521 0xfd9c11a2 0x5b997b82 0x8150adc5 0xa9c68fa9 0x72a3ba74
</syntaxhighlight>

Lock the related OTP words manually with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<syntaxhighlight lang="shell">
fuse prog -y 0 0x10000018 1 1 1 1 1 1 1 1
</syntaxhighlight>

===== Test BootROM image authentication =====

To verify the image authentication by the BootROM with the programmed PKH and the programmed signed images, you must reboot your device.

On the third line of the U-Boot SPL output, check the BootROM authentication status.
The status output should look like this: <syntaxhighlight lang="console" inline>Bootrom authentication: succeeded</syntaxhighlight>.
Note the <syntaxhighlight lang="console" inline>succeeded</syntaxhighlight> status for successful authentication of the U-Boot SPL image by the BootROM.

The following output shows successful authentication of the U-Boot-SPL image in line 3, as well as successful authentication of the used configuration in line 7 and the U-Boot and Device Tree subimages in lines 8 and 9 of the U-Boot-FIT image.
<syntaxhighlight lang="console" line highlight="3,7-9">
U-Boot SPL 2022.01-00012-g6c5892c90c28 (Feb 16 2022 - 11:11:16 +0100)
Model: STMicroelectronics STM32MP15xx DHCOM Premium Developer Kit (2)
Bootrom authentication: succeeded
Code: SoM:rev=1,ddr3=3 Board:rev=0
RAM: DDR3L 32bits 2x4Gb 533MHz
Trying to boot from SPI
## Checking hash(es) for config config-2 ... sha256,rsa4096:fsbl-cfg-2022-02-16+ OK
## Checking hash(es) for Image uboot ... sha256,rsa4096:fsbl-img-2022-02-16+ sha256+ OK
## Checking hash(es) for Image fdt-1 ... sha256,rsa4096:fsbl-img-2022-02-16+ sha256+ OK
</syntaxhighlight>

===== Enforce BootROM image authentication =====

Without any further changes, the BootROM is able to perform authentication of the FSBL image, but unauthenticated images can still be used and executed.
The device is still open, let's see this as a kind of test mode to check if the PKH is set correctly.

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

The 6th bit in the 1st word of the OTP is responsible that the BootROM only accepts signed images.
Burning this bit enforces authentication of images by the BootROM and unsigned binaries are no longer supported on the target device.

To program this bit, the U-Boot Shell can be used with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command or with the more general <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command.

With usage of the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command:
<div style="color:red">Warning: After running the following command, your device will only be able to boot signed images!</div>
<syntaxhighlight lang="shell">
stm32key close
</syntaxhighlight>

Or with usage of the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<div style="color:red">Warning: After running the following command, your device will only be able to boot signed images!</div>
<syntaxhighlight lang="shell">
fuse prog 0 0x0 0x40
</syntaxhighlight>

== Secure Boot in Trusted Boot with BootROM authentication, TF-A and OP-TEE ==

<div style="color:red">TODO:</div>
# Add support for STM32MP15 DHCOM in <ref name="TF-A" />
# Add support for STM32MP15 DHCOM in <ref name="OP-TEE/optee_os" />
# Create stm32mp15_dhcom_trusted_defconfig???
# Integrate STM32MP15 DHCOM into <ref name="OP-TEE/build" />

== References ==

<references>
<ref name="UEFI specification">[http://www.uefi.org/specifications http://www.uefi.org/specifications]</ref>
<ref name="Basic Boot">[https://source.denx.de/u-boot/u-boot/-/blob/master/configs/stm32mp15_basic_defconfig U-Boot Source stm32mp15_basic_defconfig]</ref>
<ref name="Trusted Boot">[https://source.denx.de/u-boot/u-boot/-/blob/master/configs/stm32mp15_trusted_defconfig U-Boot Source stm32mp15_trusted_defconfig]</ref>
<ref name="BSI TR-02102">[https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.pdf BSI - Technische Richtlinie, "Kryptographische Algorithmen und Schlüssellängen", BSI TR-02102-1]</ref>
<ref name="STM32 image header">[https://wiki.st.com/stm32mpu/wiki/STM32_header_for_binary_files STM32 header for binary files]</ref>
<ref name="KeyGen_tool">[https://wiki.st.com/stm32mpu/wiki/KeyGen_tool STM32MP KeyGen tool]</ref>
<ref name="Signing_tool">[https://wiki.st.com/stm32mpu/wiki/Signing_tool STM32MP Signing tool]</ref>
<ref name="TF-A">[https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/ Trusted Firmware-A (TF-A)]</ref>
<ref name="OP-TEE/optee_os">[https://github.com/OP-TEE/optee_os OP-TEE Trusted OS]</ref>
<ref name="OP-TEE/build">[https://github.com/OP-TEE/build Makefiles to use OP-TEE on various platforms]</ref>
</references>

DHCOM STM32MP15 Secure Boot

2022-03-22T10:31:47Z

Dkierner: Reword /* Generate key pair with STM32MP_KeyGen_CLI */

<div class="toclimit-3">__TOC__</div>

== Introduction ==

=== Abbreviations ===

{| class="wikitable sortable"
|-
! Abbreviation !! Description
|-
| BSI || Bundesamt für Sicherheit in der Informationstechnik
|-
| CoM || Computer on module
|-
| FIT || Flattened Image Tree
|-
| FSBL || Fist Stage Bootloader (TF-A or U-Boot SPL)
|-
| OTP || One Time Programmable (eFuses)
|-
| OP-TEE || Open Portable Trusted Execution Environment
|-
| PKH || Public Key Hash
|-
| ROM || Read-Only Memory
|-
| RSA || Rivest, Shamir und Adleman (asynchronous encryption)
|-
| SHA || Secure Hash Algorithm
|-
| SoC || System on chip
|-
| SoM || System on module
|-
| SSBL || Second Stage Bootloader (U-Boot)
|-
| TF-A || Trusted Firmware A
|}

=== Secure Boot ===

The term Secure Boot originally comes from the UEFI specification<ref name="UEFI specification" /> and describes a secure boot process in which only signed software is loaded and executed during the boot process.

Secure Boot is a necessary cornerstone for enforcing security mechanisms in a trusted computing environment.
Enforcing the execution of signed software only during the boot process, as long as the chain of trust is secure, can guarantee that said software is free from tampering, as any manipulation will invalidate the software's signature and prevent the software from being executed.

[[File:Secure Boot Generic en.png|600px|Secure Boot Generic]]

The figure [[Media:Secure Boot Generic en.png|Secure Boot Generic]] shows an example of a secure boot process that leads to a reset in the event of an error in the signature check. Each stage uses the certificate and signature to check the origin and integrity of the next stage. On success, the next stage is executed, and in the event of an error, this always leads to a defined error state. In the simplest case, the certificates are integrated into the binary image of the previous stage.

Program code and certificate need to be trustworthy and therefore protected against tampering in each stage, otherwise the secure boot chain can be compromised. Except for the first stage, all binary images are protected against third-party tampering by the signature. As this is practically impossible for the first stage, manipulation protection has to be enforced by hardware measures to make said stage immutable, with the first stage's program code and the verification certificate for the second stage being stored in read-only memory (ROM).

=== Basic and trusted boot in the context of Secure Boot ===

When booting Linux on the STM32MP1 SoC with U-Boot SPL and U-Boot only, STM speaks of "Basic Boot"<ref name="Basic Boot" />.
However, if Linux is booted with a combination of TF-A, U-Boot and OP-TEE, STM refers to this as "Trusted Boot"<ref name="Trusted Boot" />.

{| class="wikitable"
|-
! Boot chain !! Description
|-
| Basic boot || BootROM -> U-Boot SPL -> U-Boot -> Linux
|-
| Trusted boot || BootROM -> TF-A -> U-Boot + OP-TEE -> Linux
|}

== Secure Boot in Basic Boot with BootROM authentication and Verified Boot ==

This Secure Boot implementation does use the the BootROM integrated image authentication to authenticate the U-Boot SPL as FSBL.
Authentication of U-Boot as SSBL by the U-Boot SPL and authentication of the Linux kernel, Device Tree and ramdisk by U-Boot is done using the open source implementation [[#Verified Boot|Verified Boot]].

This also means that everything from U-Boot SPL onwards is platform independent, as we do not rely on hardware specific implementations.

=== Verified Boot ===

Developers of Google's Chromium project worked out a concept for the Verified Boot called Secure Boot mechanism on the basis of the boot loader "Das U-Boot".
They use the existing infrastructure of the FIT images and for the system configuration at runtime via a Device Tree.
The description language for the FIT images was extended by an additional signature node and the Device Tree of the platform was used to store the certificate(s) for the authentication of the images.
The signature node can be used to sign individual subimages as well as combinations of individual subimages in the FIT image.
The tool <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight> takes care the signature creation for the FIT images and the addition of the certificate in a Device Tree.

With Verified Boot, the Device Tree with included public key is integrated into the program image of the stage, which accomplishes the authentication and is thus very similar to the general procedure shown in figure [[Media:Secure Boot Generic en.png|Secure Boot Generic]].
The number of public keys that can be integrated is theoretically unlimited, but they must be distinguishable by name.

==== Technical details of Verified Boot ====

{| class="wikitable"
|-
| '''Name'''
| Verified Boot
|-
| '''Implementierung'''
| Software (Open Source)
|-
| '''Hash algorithms'''
|
* SHA1 (deprecated)<ref name="BSI TR-02102" />
* SHA256
* SHA384
* SHA512
|-
| '''Crypto algorithms
|
* RSA2048 (deprecated as of 2024)<ref name="BSI TR-02102" />
* RSA4096

* ECDSA256 (currently limited to U-Boot SPL)
|-
| '''Number of key pairs'''
| unlimited
|-
|}

==== In-depth references for Verified Boot ====


===== Flatten Image Tree =====
* [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT U-Boot Documentation: doc/uImage.FIT]
* [https://source.denx.de/u-boot/u-boot/-/commit/d5934ad7 U-Boot Commit d5934ad7: "new uImage: Add dual format uImage support framework"]
* ...
* [https://source.denx.de/u-boot/u-boot/-/commit/3310c549 U-Boot Commit d5934ad7: "new uImage: Add new uImage format documentation and examples"]

===== Verified Boot =====

* [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT/signature.txt U-Boot Documentation: doc/uImage.FIT/signature.txt]
* [https://source.denx.de/u-boot/u-boot/-/commit/3e569a6b U-Boot Commit 3e569a6b: "image: Add signing infrastructure"]
* [https://source.denx.de/u-boot/u-boot/-/commit/56518e71 U-Boot Commit 56518e71: "image: Support signing of images"]
* [https://source.denx.de/u-boot/u-boot/-/commit/4d098529 U-Boot Commit 4d098529: "image: Add support for signing of FIT configurations"]

===== ECDSA signature verification =====

<div style="color:red">TODO: Mention ECDSA limitations</div>
Note: This has currently some limitations!


* [https://source.denx.de/u-boot/u-boot/-/commit/928a8be7 U-Boot Commit 928a8be7: "lib: ecdsa: Implement UCLASS_ECDSA verification on target"]
* [https://source.denx.de/u-boot/u-boot/-/commit/ee870859 U-Boot Commit ee870859: "arm: stm32mp1: Implement ECDSA signature verification"]

=== Tutorial: Secure boot from BootROM to Linux with basic boot ===

==== System requirements and needed tools ====

The following table lists all requirements to create the key pairs and build the signed images with embedded public keys.

{| class="wikitable"
|-
! Category !! Description
|-
| '''Host operating system''' ||
* Linux (Debian 9, Ubuntu 18.04 or higher prefered)
|-
| '''Debian packages''' ||
* bison
* device-tree-compiler
* flex
* gcc-arm-linux-gnueabihf (>= gcc 6)
* git
* make
* openssl
|-
| '''STM32 Tools''' ||
* [https://www.st.com/en/development-tools/stm32cubeprog.html STM32CubeProgrammer]
** STM32MP_KeyGen_CLI
** STM32MP_SigningTool_CLI
|}

<div style="color:red">TODO: Should we give host setup instructions?</div>


==== Intended use of the four generated key pairs ====

We've decided to create and use as few certificates as reasonable to ensure a high level of security.
Therefore, we chose a separate key pair for each boot stage and also a separate key pair for image and configuration nodes.
If you're confused about the difference between image and configuration nodes, head over to [[#Flatten Image Tree|Flatten Image Tree]] to refresh your knowledge.
The exact purpose of the four key pairs generated for Verified Boot is described in the following table.

{| class="wikitable"
|-
! File name !! Intended use
|-
| '''fsbl-img''' || Authenticate image nodes of FIT images loaded by U-Boot SPL (U-Boot, Device Tree, firmware)
|-
| '''fsbl-cfg''' || Authenticate config nodes of FIT images loaded by U-Boot SPL (U-Boot + Device Tree + firmware)
|-
| '''ssbl-img''' || Authenticate image nodes of FIT images loaded by U-Boot (Kernel, Device Tree, InitRamFS)
|-
| '''ssbl-cfg''' || Authenticate config nodes of FIT images loaded by U-Boot (Kernel + Device Tree + InitRamFS)
|-
|}

==== Created/Modified files in the U-Boot source for Verified Boot ====

The created or modified files to build U-Boot with Verified Boot on STM32MP15 are described in the following table.

{| class="wikitable"
|-
! File
! Description
|-
| build_signed_uboot.sh
| Shell script that automates the creation of key pairs, the modification of FIT source files and Device Tree's and building of U-Boot SPL and U-Boot.
|-
| board/dhelectronics/dh_stm32mp1/u-boot-dhco?.its
| FIT source files with defined U-Boot image and Device Tree's for DHSOM platforms.
|-
| board/dhelectronics/dh_stm32mp1/linux-dhcom.its
| Dummy FIT source file with defined dummy kernel image and dummy Device Tree for DHSOM platforms.<br>To avoid relying on a built kernel image on a fixed path, we created this dummy, since adding the public keys with <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight> requires a valid FIT source file.
|-
| configs/stm32mp15_dhco?_secure_defconfig
| Example U-Boot defconfig's with enabled <syntaxhighlight lang="shell" inline>CONFIG_FIT_SIGNATURE</syntaxhighlight> and <syntaxhighlight lang="shell" inline>CONFIG_SPL_FIT_SIGNATURE</syntaxhighlight>.
|}

==== Build Verified Boot enabled U-Boot SPL and U-Boot ====

To build the U-Boot SPL and U-Boot images, you need to check out the source code and run a build script that automates everything from key generation to image creation and signing.

===== Checkout source code for Verified Boot =====

<div style="color:red">TODO: Replace my personal GitLab by a public available repository</div>
Checkout the branch <syntaxhighlight lang="shell" inline>v2022.01_dhcom_secure_boot</syntaxhighlight> in my personal GitLab repository with:

<syntaxhighlight lang="shell">
git clone git@dhplgl01:jneuhauser/u-boot.git -b v2022.01_dhcom_secure_boot
</syntaxhighlight>

If you already have a cloned U-Boot source code, you can also fetch it into your existing repository with:

<syntaxhighlight lang="shell">
cd /path/to/u-boot
git remote add jneuhauser git@dhplgl01:jneuhauser/u-boot.git
git fetch jneuhauser
git checkout v2022.01_dhcom_secure_boot
</syntaxhighlight>

===== Run the build script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> =====

The shell script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> included in the U-Boot source performs the following steps.
# Prebuild U-Boat SPL and U-Boat to build the required tools and Device Tree's
# Generate the [[#Intended use of the four generated key pairs|four key pairs]] if not already created
# Generate/Modify FIT image source files for Linux (dummy) and U-Boot
# Add public keys to the built Device Tree's used by U-Boot SPL and U-Boot
# Rebuild U-Boot SPL and U-Boot with new Device Tree's containing the public keys

The script supports the following environment variables to configure the target architecture, the cross compiler, the defconfig, the key algorithm, the key directory, and a key postfix:
{| class="wikitable sortable"
|-
! Name !! Description !! Default
|-
| ARCH || Target architecture for the U-Boot build || arm
|-
| CROSS_COMPILE || Used cross compiler to build U-Boot || arm-linux-gnueabihf-
|-
| DEFCONFIG || Used defconfig for the U-Boot build || stm32mp15_dhcom_secure_defconfig
|-
| KEY_ALGO || Signature algorithm used for Verified Boot || rsa
|-
| KEY_DIR || Directory where the key pairs are stored || ../keys
|-
| KEY_POSTFIX || Postfix which is appended to the key names || -$(date +%F)
|}

To perform the steps mentioned above, you just need to run the shell script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> like below.
In this example, we override the default value for <syntaxhighlight lang="shell" inline>KEY_POSTFIX</syntaxhighlight> with <syntaxhighlight lang="shell" inline>-testing</syntaxhighlight> to append this string to the [[#Intended use of the four generated key pairs|four key file names]].
The script has debug output enabled by default, which should output all the statements in the script itself and the output of the commands used in the script.
If you have any problems with the script, feel free to get in touch with [mailto:info@dh-electronics.com us] and attach a logfile.

<syntaxhighlight lang="shell">
cd /path/to/u-boot
KEY_POSTFIX="-testing" ./build_signed_uboot.sh | tee build_signed_uboot.log
</syntaxhighlight>

If this process completes without error, there are two boot loader images in the root directory of the U-Boot source.
{| class="wikitable sortable"
|-
! File name !! Stage !! Description
|-
| u-boot-spl.stm32 || FSBL || U-Boot SPL binary with appended Device Tree and prepended STM32 image header<ref name="STM32 image header" />.
|-
| u-boot.itb || SSBL || U-Boot and Device Tree's contained in a signed FIT image.
|}

==== Generate key pair and sign U-Boot SPL for BootROM authentication ====

To sign the U-Boot SPL as SSBL image for authentication with the BootROM we have to use the STM32 tools <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight> and <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight>.

===== Generate key pair with <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight> =====

All STM32MP15 SoCs only support one key pair for authenticating images through the BootROM.
To generate a ECDSA key pair for the STM32MP Secure Boot use the tool <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight><ref name="KeyGen_tool" />:
<syntaxhighlight lang="shell">
STM32MP_KeyGen_CLI --absolute-path "$(pwd)" --password 12345678
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Key Generator v2.9.0
-------------------------------------------------------------------

Prime256v1 curve is selected.
AES_256_cbc algorithm is selected for private key encryption
Generating Prime256v1 keys...
Private key PEM file created
Public key PEM file created
public key hash file created
Keys generated successfully.
+ public key: publicKey.pem
+ private key: privateKey.pem
+ public hash key: publicKeyhash.bin
</syntaxhighlight>

===== Sign U-Boot SPL with <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight> =====

To add the public key and the image signature to our built U-Boot SPL binary with STM32 image header, we are using the tool <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight><ref name="Signing_tool" /> to update the existing STM32 image header of <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> with the required details.
<syntaxhighlight lang="shell">
STM32MP_SigningTool_CLI --binary-image /path/to/u-boot/u-boot-spl.stm32 --public-key publicKey.pem --private-key privateKey.pem --password 12345678 --output /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Signing Tool v2.9.0
-------------------------------------------------------------------

Prime256v1 curve is selected.
Header version 1 preparation ...
Reading Private Key File...
ECDSA signature generated.
Signature verification: SUCCESS
The Signed image file generated successfully: /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>

You can check the STM32 image header details with:
<syntaxhighlight lang="shell">
STM32MP_SigningTool_CLI --dump-header /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Signing Tool v2.9.0
-------------------------------------------------------------------

Header description:

Magic: 0x53544d32
Signature: c8 30 a0 62 2d 6d 4e 1b b9 f7 fe 38 27 65 e0 44 f0 f5 9d e6 8a a6 02 cb 74 52 26 9c 1e e9 07 17
1a c7 da 8e 96 fa 82 d3 b1 dc d5 3a 05 0e 87 83 94 4d 47 ad 17 07 88 0d b5 ae 2e 38 1d 90 22 ad
Checksum: 0xa8ca85
Header version: 0x10000
Size: 0x22dec
Load address: 0x2ffc2500
Entry point: 0x2ffc2500
Image version: 0x0
Option flags: 0x0
ECDSA Algo: 0x1
ECDSA pub key: 3b 71 8e 59 f1 ee 4c a8 4b 72 5f 4a 1c 63 8b 6e b8 01 ec 1a 3f 8c 98 2f d2 1d 77 f9 09 10 8f 04
30 da 5c 3a 24 53 0d 71 93 f0 a5 d9 c9 a7 27 b4 5f a5 c4 4d 55 8b 7a 25 e3 03 ef ca 87 ff 04 25
Binary type: 0x0
</syntaxhighlight>
The difference to an unsigned STM32 image header is that the values for "Signature" and "ECDSA pub key" are not all zeros and that "Option flags" is 0x0 for enabled signature verification instead of 0x1 for disabled signature verification.

==== Write U-Boot SPL and U-Boot to your boot media ====

The first step to verify that the built U-Boot SPL and U-Boot works as expected is to program both images to your boot media.
Depending on the boot configuration, your DHSOM will boot from the module's SPI-NOR flash, from the module's or baseboard's eMMC or from an SD card.
The boot configuration is always defined by the boot pins by default, because the boot pins have no alternative function on the STM32MP15 SoC's.

<div style="color:red">TODO: How can a user determine the used boot media?</div>
<div style="color:red">TODO: How to enforce boot media on Secure Boot enabled devices?</div>

===== Write U-Boot SPL and U-Boot to the SPI-NOR flash of the SoM =====

The following '''commands for the U-Boot Shell''' calculate some addresses based on the image offsets expected by the BootROM, load the required images from SD card or via TFTP into memory and finally write the prepared memory into the SPI-NOR flash on the SoM.

Prepare for loading <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> into memory:
<syntaxhighlight lang="shell">
mw.b ${loadaddr} 0xff 0x200000
setexpr fsbl1addr ${loadaddr} + 0x0
setexpr fsbl2addr ${loadaddr} + 0x40000
setexpr ssbl1addr ${loadaddr} + 0x80000
</syntaxhighlight>

Load <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> from SD card:
<syntaxhighlight lang="shell">
load mmc 0:4 ${fsbl1addr} u-boot-spl.stm32
load mmc 0:4 ${fsbl2addr} u-boot-spl.stm32
load mmc 0:4 ${ssbl1addr} u-boot.itb
</syntaxhighlight>

Load <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> from tftp server:
<syntaxhighlight lang="shell">
setenv serverip 10.20.30.1
setenv ipaddr 10.20.30.100
setenv netmask 255.255.255.0
tftp ${fsbl1addr} ${serverip}:u-boot-spl.stm32
tftp ${fsbl2addr} ${serverip}:u-boot-spl.stm32
tftp ${ssbl1addr} ${serverip}:u-boot.itb
</syntaxhighlight>

Check for magic numbers of expected image headers and conditionally program the SPI-NOR flash:
<syntaxhighlight lang="shell">
if itest *${fsbl1addr} == 0x324d5453 && itest *${fsbl2addr} == 0x324d5453 && itest *${ssbl1addr} == 0xedfe0dd0; then
sf probe && sf update ${loadaddr} 0 0x200000
fi
</syntaxhighlight>

===== Write U-Boot SPL and U-Boot to an SD card =====

<div style="color:red">TODO:</div>


===== Write U-Boot SPL and U-Boot to the eMMC =====

<div style="color:red">TODO:</div>


==== Enroll, test and enforce BootROM image authentication ====

To enroll, test and enforce image authentication by the BootROM you need to program the PKH into the OTP of the STM32MP15 SoC.
The <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> file that you created in the [[#Generate key pair with STM32MP_KeyGen_CLI|Generate key pair with STM32MP_KeyGen_CLI]] step contains the PKH in binary format for use with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> U-Boot command.
If the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command does fail or is not available on the target U-Boot, you can also write the PKH manually with the more generic <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command into the OTP.

===== Program public key hash to eFuses =====

The following '''commands for the U-Boot Shell''' load the file <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> into memory and program the contained PKH to the OTP of the STM32MP15 SoC.
The used command <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> writes and locks the words of the OTP automatically without knowing anything about the OTP layout/addresses.
If this fails or the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command is not available, you can also write and lock the OTP with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command

====== Program <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> into OTP with <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command ======

Load <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> by SD card:
<syntaxhighlight lang="shell">
load mmc 0:4 ${loadaddr} publicKeyhash.bin
</syntaxhighlight>

Or load <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> by TFTP:
<syntaxhighlight lang="shell">
setenv serverip 10.20.30.1
setenv ipaddr 10.20.30.100
setenv netmask 255.255.255.0
tftp ${loadaddr} ${serverip}:publicKeyhash.bin
</syntaxhighlight>

Show the contents of <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight>:
<syntaxhighlight lang="shell">
stm32key read ${loadaddr}
</syntaxhighlight>
<syntaxhighlight lang="console">
Read KEY at 0xc2000000
OTP value 24: 4e31bbcd
OTP value 25: 51e827dd
OTP value 26: 3511f521
OTP value 27: fd9c11a2
OTP value 28: 5b997b82
OTP value 29: 8150adc5
OTP value 30: a9c68fa9
OTP value 31: 72a3ba74
</syntaxhighlight>

Write the contents of <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> to OTP with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command:
<syntaxhighlight lang="shell">
stm32key fuse ${loadaddr}
</syntaxhighlight>
<syntaxhighlight lang="console">
TODO: Add output
</syntaxhighlight>

====== Program PKH manually into OTP with <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command ======

Generate fuse command with hexdump from file <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> on linux host:
<div style="color:red">Warning: Do not use the example output! Only use your unique values for programming the PKH in the OTP!</div>
<syntaxhighlight lang="shell">
echo fuse prog -y 0 0x18 $(hexdump -e '/4 "0x"' -e '/1 "%x"' -e '" "' /path/to/publicKeyhash.bin)
</syntaxhighlight>
<syntaxhighlight lang="console">
fuse prog -y 0 0x18 0x4e31bbcd 0x51e827dd 0x3511f521 0xfd9c11a2 0x5b997b82 0x8150adc5 0xa9c68fa9 0x72a3ba74
</syntaxhighlight>

Write the PKH into OTP manually with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<div style="color:red">Warning: Do not use the example command! Only use your unique values for programming the PKH in the OTP!</div>
<syntaxhighlight lang="shell">
fuse prog -y 0 0x18 0x4e31bbcd 0x51e827dd 0x3511f521 0xfd9c11a2 0x5b997b82 0x8150adc5 0xa9c68fa9 0x72a3ba74
</syntaxhighlight>

Lock the related OTP words manually with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<syntaxhighlight lang="shell">
fuse prog -y 0 0x10000018 1 1 1 1 1 1 1 1
</syntaxhighlight>

===== Test BootROM image authentication =====

To verify the image authentication by the BootROM with the programmed PKH and the programmed signed images, you must reboot your device.

On the third line of the U-Boot SPL output, check the BootROM authentication status.
The status output should look like this: <syntaxhighlight lang="console" inline>Bootrom authentication: succeeded</syntaxhighlight>.
Note the <syntaxhighlight lang="console" inline>succeeded</syntaxhighlight> status for successful authentication of the U-Boot SPL image by the BootROM.

The following output shows successful authentication of the U-Boot-SPL image in line 3, as well as successful authentication of the used configuration in line 7 and the U-Boot and Device Tree subimages in lines 8 and 9 of the U-Boot-FIT image.
<syntaxhighlight lang="console" line highlight="3,7-9">
U-Boot SPL 2022.01-00012-g6c5892c90c28 (Feb 16 2022 - 11:11:16 +0100)
Model: STMicroelectronics STM32MP15xx DHCOM Premium Developer Kit (2)
Bootrom authentication: succeeded
Code: SoM:rev=1,ddr3=3 Board:rev=0
RAM: DDR3L 32bits 2x4Gb 533MHz
Trying to boot from SPI
## Checking hash(es) for config config-2 ... sha256,rsa4096:fsbl-cfg-2022-02-16+ OK
## Checking hash(es) for Image uboot ... sha256,rsa4096:fsbl-img-2022-02-16+ sha256+ OK
## Checking hash(es) for Image fdt-1 ... sha256,rsa4096:fsbl-img-2022-02-16+ sha256+ OK
</syntaxhighlight>

===== Enforce BootROM image authentication =====

Without any further changes, the BootROM is able to perform authentication of the FSBL image, but unauthenticated images can still be used and executed.
The device is still open, let's see this as a kind of test mode to check if the PKH is set correctly.

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

The 6th bit in the 1st word of the OTP is responsible that the BootROM only accepts signed images.
Burning this bit enforces authentication of images by the BootROM and unsigned binaries are no longer supported on the target device.

To program this bit, the U-Boot Shell can be used with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command or with the more general <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command.

With usage of the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command:
<div style="color:red">Warning: After running the following command, your device will only be able to boot signed images!</div>
<syntaxhighlight lang="shell">
stm32key close
</syntaxhighlight>

Or with usage of the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<div style="color:red">Warning: After running the following command, your device will only be able to boot signed images!</div>
<syntaxhighlight lang="shell">
fuse prog 0 0x0 0x40
</syntaxhighlight>

== Secure Boot in Trusted Boot with BootROM authentication, TF-A and OP-TEE ==

<div style="color:red">TODO:</div>
# Add support for STM32MP15 DHCOM in <ref name="TF-A" />
# Add support for STM32MP15 DHCOM in <ref name="OP-TEE/optee_os" />
# Create stm32mp15_dhcom_trusted_defconfig???
# Integrate STM32MP15 DHCOM into <ref name="OP-TEE/build" />

== References ==

<references>
<ref name="UEFI specification">[http://www.uefi.org/specifications http://www.uefi.org/specifications]</ref>
<ref name="Basic Boot">[https://source.denx.de/u-boot/u-boot/-/blob/master/configs/stm32mp15_basic_defconfig U-Boot Source stm32mp15_basic_defconfig]</ref>
<ref name="Trusted Boot">[https://source.denx.de/u-boot/u-boot/-/blob/master/configs/stm32mp15_trusted_defconfig U-Boot Source stm32mp15_trusted_defconfig]</ref>
<ref name="BSI TR-02102">[https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.pdf BSI - Technische Richtlinie, "Kryptographische Algorithmen und Schlüssellängen", BSI TR-02102-1]</ref>
<ref name="STM32 image header">[https://wiki.st.com/stm32mpu/wiki/STM32_header_for_binary_files STM32 header for binary files]</ref>
<ref name="KeyGen_tool">[https://wiki.st.com/stm32mpu/wiki/KeyGen_tool STM32MP KeyGen tool]</ref>
<ref name="Signing_tool">[https://wiki.st.com/stm32mpu/wiki/Signing_tool STM32MP Signing tool]</ref>
<ref name="TF-A">[https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/ Trusted Firmware-A (TF-A)]</ref>
<ref name="OP-TEE/optee_os">[https://github.com/OP-TEE/optee_os OP-TEE Trusted OS]</ref>
<ref name="OP-TEE/build">[https://github.com/OP-TEE/build Makefiles to use OP-TEE on various platforms]</ref>
</references>

DHCOM STM32MP15 Secure Boot

2022-03-22T10:23:27Z

Dkierner: Fix contact info /* Run the build script build_signed_uboot.sh */

<div class="toclimit-3">__TOC__</div>

== Introduction ==

=== Abbreviations ===

{| class="wikitable sortable"
|-
! Abbreviation !! Description
|-
| BSI || Bundesamt für Sicherheit in der Informationstechnik
|-
| CoM || Computer on module
|-
| FIT || Flattened Image Tree
|-
| FSBL || Fist Stage Bootloader (TF-A or U-Boot SPL)
|-
| OTP || One Time Programmable (eFuses)
|-
| OP-TEE || Open Portable Trusted Execution Environment
|-
| PKH || Public Key Hash
|-
| ROM || Read-Only Memory
|-
| RSA || Rivest, Shamir und Adleman (asynchronous encryption)
|-
| SHA || Secure Hash Algorithm
|-
| SoC || System on chip
|-
| SoM || System on module
|-
| SSBL || Second Stage Bootloader (U-Boot)
|-
| TF-A || Trusted Firmware A
|}

=== Secure Boot ===

The term Secure Boot originally comes from the UEFI specification<ref name="UEFI specification" /> and describes a secure boot process in which only signed software is loaded and executed during the boot process.

Secure Boot is a necessary cornerstone for enforcing security mechanisms in a trusted computing environment.
Enforcing the execution of signed software only during the boot process, as long as the chain of trust is secure, can guarantee that said software is free from tampering, as any manipulation will invalidate the software's signature and prevent the software from being executed.

[[File:Secure Boot Generic en.png|600px|Secure Boot Generic]]

The figure [[Media:Secure Boot Generic en.png|Secure Boot Generic]] shows an example of a secure boot process that leads to a reset in the event of an error in the signature check. Each stage uses the certificate and signature to check the origin and integrity of the next stage. On success, the next stage is executed, and in the event of an error, this always leads to a defined error state. In the simplest case, the certificates are integrated into the binary image of the previous stage.

Program code and certificate need to be trustworthy and therefore protected against tampering in each stage, otherwise the secure boot chain can be compromised. Except for the first stage, all binary images are protected against third-party tampering by the signature. As this is practically impossible for the first stage, manipulation protection has to be enforced by hardware measures to make said stage immutable, with the first stage's program code and the verification certificate for the second stage being stored in read-only memory (ROM).

=== Basic and trusted boot in the context of Secure Boot ===

When booting Linux on the STM32MP1 SoC with U-Boot SPL and U-Boot only, STM speaks of "Basic Boot"<ref name="Basic Boot" />.
However, if Linux is booted with a combination of TF-A, U-Boot and OP-TEE, STM refers to this as "Trusted Boot"<ref name="Trusted Boot" />.

{| class="wikitable"
|-
! Boot chain !! Description
|-
| Basic boot || BootROM -> U-Boot SPL -> U-Boot -> Linux
|-
| Trusted boot || BootROM -> TF-A -> U-Boot + OP-TEE -> Linux
|}

== Secure Boot in Basic Boot with BootROM authentication and Verified Boot ==

This Secure Boot implementation does use the the BootROM integrated image authentication to authenticate the U-Boot SPL as FSBL.
Authentication of U-Boot as SSBL by the U-Boot SPL and authentication of the Linux kernel, Device Tree and ramdisk by U-Boot is done using the open source implementation [[#Verified Boot|Verified Boot]].

This also means that everything from U-Boot SPL onwards is platform independent, as we do not rely on hardware specific implementations.

=== Verified Boot ===

Developers of Google's Chromium project worked out a concept for the Verified Boot called Secure Boot mechanism on the basis of the boot loader "Das U-Boot".
They use the existing infrastructure of the FIT images and for the system configuration at runtime via a Device Tree.
The description language for the FIT images was extended by an additional signature node and the Device Tree of the platform was used to store the certificate(s) for the authentication of the images.
The signature node can be used to sign individual subimages as well as combinations of individual subimages in the FIT image.
The tool <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight> takes care the signature creation for the FIT images and the addition of the certificate in a Device Tree.

With Verified Boot, the Device Tree with included public key is integrated into the program image of the stage, which accomplishes the authentication and is thus very similar to the general procedure shown in figure [[Media:Secure Boot Generic en.png|Secure Boot Generic]].
The number of public keys that can be integrated is theoretically unlimited, but they must be distinguishable by name.

==== Technical details of Verified Boot ====

{| class="wikitable"
|-
| '''Name'''
| Verified Boot
|-
| '''Implementierung'''
| Software (Open Source)
|-
| '''Hash algorithms'''
|
* SHA1 (deprecated)<ref name="BSI TR-02102" />
* SHA256
* SHA384
* SHA512
|-
| '''Crypto algorithms
|
* RSA2048 (deprecated as of 2024)<ref name="BSI TR-02102" />
* RSA4096

* ECDSA256 (currently limited to U-Boot SPL)
|-
| '''Number of key pairs'''
| unlimited
|-
|}

==== In-depth references for Verified Boot ====


===== Flatten Image Tree =====
* [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT U-Boot Documentation: doc/uImage.FIT]
* [https://source.denx.de/u-boot/u-boot/-/commit/d5934ad7 U-Boot Commit d5934ad7: "new uImage: Add dual format uImage support framework"]
* ...
* [https://source.denx.de/u-boot/u-boot/-/commit/3310c549 U-Boot Commit d5934ad7: "new uImage: Add new uImage format documentation and examples"]

===== Verified Boot =====

* [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT/signature.txt U-Boot Documentation: doc/uImage.FIT/signature.txt]
* [https://source.denx.de/u-boot/u-boot/-/commit/3e569a6b U-Boot Commit 3e569a6b: "image: Add signing infrastructure"]
* [https://source.denx.de/u-boot/u-boot/-/commit/56518e71 U-Boot Commit 56518e71: "image: Support signing of images"]
* [https://source.denx.de/u-boot/u-boot/-/commit/4d098529 U-Boot Commit 4d098529: "image: Add support for signing of FIT configurations"]

===== ECDSA signature verification =====

<div style="color:red">TODO: Mention ECDSA limitations</div>
Note: This has currently some limitations!


* [https://source.denx.de/u-boot/u-boot/-/commit/928a8be7 U-Boot Commit 928a8be7: "lib: ecdsa: Implement UCLASS_ECDSA verification on target"]
* [https://source.denx.de/u-boot/u-boot/-/commit/ee870859 U-Boot Commit ee870859: "arm: stm32mp1: Implement ECDSA signature verification"]

=== Tutorial: Secure boot from BootROM to Linux with basic boot ===

==== System requirements and needed tools ====

The following table lists all requirements to create the key pairs and build the signed images with embedded public keys.

{| class="wikitable"
|-
! Category !! Description
|-
| '''Host operating system''' ||
* Linux (Debian 9, Ubuntu 18.04 or higher prefered)
|-
| '''Debian packages''' ||
* bison
* device-tree-compiler
* flex
* gcc-arm-linux-gnueabihf (>= gcc 6)
* git
* make
* openssl
|-
| '''STM32 Tools''' ||
* [https://www.st.com/en/development-tools/stm32cubeprog.html STM32CubeProgrammer]
** STM32MP_KeyGen_CLI
** STM32MP_SigningTool_CLI
|}

<div style="color:red">TODO: Should we give host setup instructions?</div>


==== Intended use of the four generated key pairs ====

We've decided to create and use as few certificates as reasonable to ensure a high level of security.
Therefore, we chose a separate key pair for each boot stage and also a separate key pair for image and configuration nodes.
If you're confused about the difference between image and configuration nodes, head over to [[#Flatten Image Tree|Flatten Image Tree]] to refresh your knowledge.
The exact purpose of the four key pairs generated for Verified Boot is described in the following table.

{| class="wikitable"
|-
! File name !! Intended use
|-
| '''fsbl-img''' || Authenticate image nodes of FIT images loaded by U-Boot SPL (U-Boot, Device Tree, firmware)
|-
| '''fsbl-cfg''' || Authenticate config nodes of FIT images loaded by U-Boot SPL (U-Boot + Device Tree + firmware)
|-
| '''ssbl-img''' || Authenticate image nodes of FIT images loaded by U-Boot (Kernel, Device Tree, InitRamFS)
|-
| '''ssbl-cfg''' || Authenticate config nodes of FIT images loaded by U-Boot (Kernel + Device Tree + InitRamFS)
|-
|}

==== Created/Modified files in the U-Boot source for Verified Boot ====

The created or modified files to build U-Boot with Verified Boot on STM32MP15 are described in the following table.

{| class="wikitable"
|-
! File
! Description
|-
| build_signed_uboot.sh
| Shell script that automates the creation of key pairs, the modification of FIT source files and Device Tree's and building of U-Boot SPL and U-Boot.
|-
| board/dhelectronics/dh_stm32mp1/u-boot-dhco?.its
| FIT source files with defined U-Boot image and Device Tree's for DHSOM platforms.
|-
| board/dhelectronics/dh_stm32mp1/linux-dhcom.its
| Dummy FIT source file with defined dummy kernel image and dummy Device Tree for DHSOM platforms.<br>To avoid relying on a built kernel image on a fixed path, we created this dummy, since adding the public keys with <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight> requires a valid FIT source file.
|-
| configs/stm32mp15_dhco?_secure_defconfig
| Example U-Boot defconfig's with enabled <syntaxhighlight lang="shell" inline>CONFIG_FIT_SIGNATURE</syntaxhighlight> and <syntaxhighlight lang="shell" inline>CONFIG_SPL_FIT_SIGNATURE</syntaxhighlight>.
|}

==== Build Verified Boot enabled U-Boot SPL and U-Boot ====

To build the U-Boot SPL and U-Boot images, you need to check out the source code and run a build script that automates everything from key generation to image creation and signing.

===== Checkout source code for Verified Boot =====

<div style="color:red">TODO: Replace my personal GitLab by a public available repository</div>
Checkout the branch <syntaxhighlight lang="shell" inline>v2022.01_dhcom_secure_boot</syntaxhighlight> in my personal GitLab repository with:

<syntaxhighlight lang="shell">
git clone git@dhplgl01:jneuhauser/u-boot.git -b v2022.01_dhcom_secure_boot
</syntaxhighlight>

If you already have a cloned U-Boot source code, you can also fetch it into your existing repository with:

<syntaxhighlight lang="shell">
cd /path/to/u-boot
git remote add jneuhauser git@dhplgl01:jneuhauser/u-boot.git
git fetch jneuhauser
git checkout v2022.01_dhcom_secure_boot
</syntaxhighlight>

===== Run the build script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> =====

The shell script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> included in the U-Boot source performs the following steps.
# Prebuild U-Boat SPL and U-Boat to build the required tools and Device Tree's
# Generate the [[#Intended use of the four generated key pairs|four key pairs]] if not already created
# Generate/Modify FIT image source files for Linux (dummy) and U-Boot
# Add public keys to the built Device Tree's used by U-Boot SPL and U-Boot
# Rebuild U-Boot SPL and U-Boot with new Device Tree's containing the public keys

The script supports the following environment variables to configure the target architecture, the cross compiler, the defconfig, the key algorithm, the key directory, and a key postfix:
{| class="wikitable sortable"
|-
! Name !! Description !! Default
|-
| ARCH || Target architecture for the U-Boot build || arm
|-
| CROSS_COMPILE || Used cross compiler to build U-Boot || arm-linux-gnueabihf-
|-
| DEFCONFIG || Used defconfig for the U-Boot build || stm32mp15_dhcom_secure_defconfig
|-
| KEY_ALGO || Signature algorithm used for Verified Boot || rsa
|-
| KEY_DIR || Directory where the key pairs are stored || ../keys
|-
| KEY_POSTFIX || Postfix which is appended to the key names || -$(date +%F)
|}

To perform the steps mentioned above, you just need to run the shell script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> like below.
In this example, we override the default value for <syntaxhighlight lang="shell" inline>KEY_POSTFIX</syntaxhighlight> with <syntaxhighlight lang="shell" inline>-testing</syntaxhighlight> to append this string to the [[#Intended use of the four generated key pairs|four key file names]].
The script has debug output enabled by default, which should output all the statements in the script itself and the output of the commands used in the script.
If you have any problems with the script, feel free to get in touch with [mailto:info@dh-electronics.com us] and attach a logfile.

<syntaxhighlight lang="shell">
cd /path/to/u-boot
KEY_POSTFIX="-testing" ./build_signed_uboot.sh | tee build_signed_uboot.log
</syntaxhighlight>

If this process completes without error, there are two boot loader images in the root directory of the U-Boot source.
{| class="wikitable sortable"
|-
! File name !! Stage !! Description
|-
| u-boot-spl.stm32 || FSBL || U-Boot SPL binary with appended Device Tree and prepended STM32 image header<ref name="STM32 image header" />.
|-
| u-boot.itb || SSBL || U-Boot and Device Tree's contained in a signed FIT image.
|}

==== Generate key pair and sign U-Boot SPL for BootROM authentication ====

To sign the U-Boot SPL as SSBL image for authentication with the BootROM we have to use the STM32 tools <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight> and <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight>.

===== Generate key pair with <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight> =====

All STM32MP15 SoC's only support one key pair for authenticating images through the BootROM.
To generate ECDSA key pairs for the STM32MP Secure Boot we are using the tool <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight><ref name="KeyGen_tool" /> to generate a single key pair.
<syntaxhighlight lang="shell">
STM32MP_KeyGen_CLI --absolute-path "$(pwd)" --password 12345678
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Key Generator v2.9.0
-------------------------------------------------------------------

Prime256v1 curve is selected.
AES_256_cbc algorithm is selected for private key encryption
Generating Prime256v1 keys...
Private key PEM file created
Public key PEM file created
public key hash file created
Keys generated successfully.
+ public key: publicKey.pem
+ private key: privateKey.pem
+ public hash key: publicKeyhash.bin
</syntaxhighlight>

===== Sign U-Boot SPL with <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight> =====

To add the public key and the image signature to our built U-Boot SPL binary with STM32 image header, we are using the tool <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight><ref name="Signing_tool" /> to update the existing STM32 image header of <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> with the required details.
<syntaxhighlight lang="shell">
STM32MP_SigningTool_CLI --binary-image /path/to/u-boot/u-boot-spl.stm32 --public-key publicKey.pem --private-key privateKey.pem --password 12345678 --output /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Signing Tool v2.9.0
-------------------------------------------------------------------

Prime256v1 curve is selected.
Header version 1 preparation ...
Reading Private Key File...
ECDSA signature generated.
Signature verification: SUCCESS
The Signed image file generated successfully: /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>

You can check the STM32 image header details with:
<syntaxhighlight lang="shell">
STM32MP_SigningTool_CLI --dump-header /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Signing Tool v2.9.0
-------------------------------------------------------------------

Header description:

Magic: 0x53544d32
Signature: c8 30 a0 62 2d 6d 4e 1b b9 f7 fe 38 27 65 e0 44 f0 f5 9d e6 8a a6 02 cb 74 52 26 9c 1e e9 07 17
1a c7 da 8e 96 fa 82 d3 b1 dc d5 3a 05 0e 87 83 94 4d 47 ad 17 07 88 0d b5 ae 2e 38 1d 90 22 ad
Checksum: 0xa8ca85
Header version: 0x10000
Size: 0x22dec
Load address: 0x2ffc2500
Entry point: 0x2ffc2500
Image version: 0x0
Option flags: 0x0
ECDSA Algo: 0x1
ECDSA pub key: 3b 71 8e 59 f1 ee 4c a8 4b 72 5f 4a 1c 63 8b 6e b8 01 ec 1a 3f 8c 98 2f d2 1d 77 f9 09 10 8f 04
30 da 5c 3a 24 53 0d 71 93 f0 a5 d9 c9 a7 27 b4 5f a5 c4 4d 55 8b 7a 25 e3 03 ef ca 87 ff 04 25
Binary type: 0x0
</syntaxhighlight>
The difference to an unsigned STM32 image header is that the values for "Signature" and "ECDSA pub key" are not all zeros and that "Option flags" is 0x0 for enabled signature verification instead of 0x1 for disabled signature verification.

==== Write U-Boot SPL and U-Boot to your boot media ====

The first step to verify that the built U-Boot SPL and U-Boot works as expected is to program both images to your boot media.
Depending on the boot configuration, your DHSOM will boot from the module's SPI-NOR flash, from the module's or baseboard's eMMC or from an SD card.
The boot configuration is always defined by the boot pins by default, because the boot pins have no alternative function on the STM32MP15 SoC's.

<div style="color:red">TODO: How can a user determine the used boot media?</div>
<div style="color:red">TODO: How to enforce boot media on Secure Boot enabled devices?</div>

===== Write U-Boot SPL and U-Boot to the SPI-NOR flash of the SoM =====

The following '''commands for the U-Boot Shell''' calculate some addresses based on the image offsets expected by the BootROM, load the required images from SD card or via TFTP into memory and finally write the prepared memory into the SPI-NOR flash on the SoM.

Prepare for loading <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> into memory:
<syntaxhighlight lang="shell">
mw.b ${loadaddr} 0xff 0x200000
setexpr fsbl1addr ${loadaddr} + 0x0
setexpr fsbl2addr ${loadaddr} + 0x40000
setexpr ssbl1addr ${loadaddr} + 0x80000
</syntaxhighlight>

Load <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> from SD card:
<syntaxhighlight lang="shell">
load mmc 0:4 ${fsbl1addr} u-boot-spl.stm32
load mmc 0:4 ${fsbl2addr} u-boot-spl.stm32
load mmc 0:4 ${ssbl1addr} u-boot.itb
</syntaxhighlight>

Load <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> from tftp server:
<syntaxhighlight lang="shell">
setenv serverip 10.20.30.1
setenv ipaddr 10.20.30.100
setenv netmask 255.255.255.0
tftp ${fsbl1addr} ${serverip}:u-boot-spl.stm32
tftp ${fsbl2addr} ${serverip}:u-boot-spl.stm32
tftp ${ssbl1addr} ${serverip}:u-boot.itb
</syntaxhighlight>

Check for magic numbers of expected image headers and conditionally program the SPI-NOR flash:
<syntaxhighlight lang="shell">
if itest *${fsbl1addr} == 0x324d5453 && itest *${fsbl2addr} == 0x324d5453 && itest *${ssbl1addr} == 0xedfe0dd0; then
sf probe && sf update ${loadaddr} 0 0x200000
fi
</syntaxhighlight>

===== Write U-Boot SPL and U-Boot to an SD card =====

<div style="color:red">TODO:</div>


===== Write U-Boot SPL and U-Boot to the eMMC =====

<div style="color:red">TODO:</div>


==== Enroll, test and enforce BootROM image authentication ====

To enroll, test and enforce image authentication by the BootROM you need to program the PKH into the OTP of the STM32MP15 SoC.
The <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> file that you created in the [[#Generate key pair with STM32MP_KeyGen_CLI|Generate key pair with STM32MP_KeyGen_CLI]] step contains the PKH in binary format for use with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> U-Boot command.
If the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command does fail or is not available on the target U-Boot, you can also write the PKH manually with the more generic <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command into the OTP.

===== Program public key hash to eFuses =====

The following '''commands for the U-Boot Shell''' load the file <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> into memory and program the contained PKH to the OTP of the STM32MP15 SoC.
The used command <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> writes and locks the words of the OTP automatically without knowing anything about the OTP layout/addresses.
If this fails or the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command is not available, you can also write and lock the OTP with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command

====== Program <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> into OTP with <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command ======

Load <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> by SD card:
<syntaxhighlight lang="shell">
load mmc 0:4 ${loadaddr} publicKeyhash.bin
</syntaxhighlight>

Or load <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> by TFTP:
<syntaxhighlight lang="shell">
setenv serverip 10.20.30.1
setenv ipaddr 10.20.30.100
setenv netmask 255.255.255.0
tftp ${loadaddr} ${serverip}:publicKeyhash.bin
</syntaxhighlight>

Show the contents of <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight>:
<syntaxhighlight lang="shell">
stm32key read ${loadaddr}
</syntaxhighlight>
<syntaxhighlight lang="console">
Read KEY at 0xc2000000
OTP value 24: 4e31bbcd
OTP value 25: 51e827dd
OTP value 26: 3511f521
OTP value 27: fd9c11a2
OTP value 28: 5b997b82
OTP value 29: 8150adc5
OTP value 30: a9c68fa9
OTP value 31: 72a3ba74
</syntaxhighlight>

Write the contents of <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> to OTP with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command:
<syntaxhighlight lang="shell">
stm32key fuse ${loadaddr}
</syntaxhighlight>
<syntaxhighlight lang="console">
TODO: Add output
</syntaxhighlight>

====== Program PKH manually into OTP with <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command ======

Generate fuse command with hexdump from file <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> on linux host:
<div style="color:red">Warning: Do not use the example output! Only use your unique values for programming the PKH in the OTP!</div>
<syntaxhighlight lang="shell">
echo fuse prog -y 0 0x18 $(hexdump -e '/4 "0x"' -e '/1 "%x"' -e '" "' /path/to/publicKeyhash.bin)
</syntaxhighlight>
<syntaxhighlight lang="console">
fuse prog -y 0 0x18 0x4e31bbcd 0x51e827dd 0x3511f521 0xfd9c11a2 0x5b997b82 0x8150adc5 0xa9c68fa9 0x72a3ba74
</syntaxhighlight>

Write the PKH into OTP manually with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<div style="color:red">Warning: Do not use the example command! Only use your unique values for programming the PKH in the OTP!</div>
<syntaxhighlight lang="shell">
fuse prog -y 0 0x18 0x4e31bbcd 0x51e827dd 0x3511f521 0xfd9c11a2 0x5b997b82 0x8150adc5 0xa9c68fa9 0x72a3ba74
</syntaxhighlight>

Lock the related OTP words manually with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<syntaxhighlight lang="shell">
fuse prog -y 0 0x10000018 1 1 1 1 1 1 1 1
</syntaxhighlight>

===== Test BootROM image authentication =====

To verify the image authentication by the BootROM with the programmed PKH and the programmed signed images, you must reboot your device.

On the third line of the U-Boot SPL output, check the BootROM authentication status.
The status output should look like this: <syntaxhighlight lang="console" inline>Bootrom authentication: succeeded</syntaxhighlight>.
Note the <syntaxhighlight lang="console" inline>succeeded</syntaxhighlight> status for successful authentication of the U-Boot SPL image by the BootROM.

The following output shows successful authentication of the U-Boot-SPL image in line 3, as well as successful authentication of the used configuration in line 7 and the U-Boot and Device Tree subimages in lines 8 and 9 of the U-Boot-FIT image.
<syntaxhighlight lang="console" line highlight="3,7-9">
U-Boot SPL 2022.01-00012-g6c5892c90c28 (Feb 16 2022 - 11:11:16 +0100)
Model: STMicroelectronics STM32MP15xx DHCOM Premium Developer Kit (2)
Bootrom authentication: succeeded
Code: SoM:rev=1,ddr3=3 Board:rev=0
RAM: DDR3L 32bits 2x4Gb 533MHz
Trying to boot from SPI
## Checking hash(es) for config config-2 ... sha256,rsa4096:fsbl-cfg-2022-02-16+ OK
## Checking hash(es) for Image uboot ... sha256,rsa4096:fsbl-img-2022-02-16+ sha256+ OK
## Checking hash(es) for Image fdt-1 ... sha256,rsa4096:fsbl-img-2022-02-16+ sha256+ OK
</syntaxhighlight>

===== Enforce BootROM image authentication =====

Without any further changes, the BootROM is able to perform authentication of the FSBL image, but unauthenticated images can still be used and executed.
The device is still open, let's see this as a kind of test mode to check if the PKH is set correctly.

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

The 6th bit in the 1st word of the OTP is responsible that the BootROM only accepts signed images.
Burning this bit enforces authentication of images by the BootROM and unsigned binaries are no longer supported on the target device.

To program this bit, the U-Boot Shell can be used with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command or with the more general <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command.

With usage of the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command:
<div style="color:red">Warning: After running the following command, your device will only be able to boot signed images!</div>
<syntaxhighlight lang="shell">
stm32key close
</syntaxhighlight>

Or with usage of the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<div style="color:red">Warning: After running the following command, your device will only be able to boot signed images!</div>
<syntaxhighlight lang="shell">
fuse prog 0 0x0 0x40
</syntaxhighlight>

== Secure Boot in Trusted Boot with BootROM authentication, TF-A and OP-TEE ==

<div style="color:red">TODO:</div>
# Add support for STM32MP15 DHCOM in <ref name="TF-A" />
# Add support for STM32MP15 DHCOM in <ref name="OP-TEE/optee_os" />
# Create stm32mp15_dhcom_trusted_defconfig???
# Integrate STM32MP15 DHCOM into <ref name="OP-TEE/build" />

== References ==

<references>
<ref name="UEFI specification">[http://www.uefi.org/specifications http://www.uefi.org/specifications]</ref>
<ref name="Basic Boot">[https://source.denx.de/u-boot/u-boot/-/blob/master/configs/stm32mp15_basic_defconfig U-Boot Source stm32mp15_basic_defconfig]</ref>
<ref name="Trusted Boot">[https://source.denx.de/u-boot/u-boot/-/blob/master/configs/stm32mp15_trusted_defconfig U-Boot Source stm32mp15_trusted_defconfig]</ref>
<ref name="BSI TR-02102">[https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.pdf BSI - Technische Richtlinie, "Kryptographische Algorithmen und Schlüssellängen", BSI TR-02102-1]</ref>
<ref name="STM32 image header">[https://wiki.st.com/stm32mpu/wiki/STM32_header_for_binary_files STM32 header for binary files]</ref>
<ref name="KeyGen_tool">[https://wiki.st.com/stm32mpu/wiki/KeyGen_tool STM32MP KeyGen tool]</ref>
<ref name="Signing_tool">[https://wiki.st.com/stm32mpu/wiki/Signing_tool STM32MP Signing tool]</ref>
<ref name="TF-A">[https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/ Trusted Firmware-A (TF-A)]</ref>
<ref name="OP-TEE/optee_os">[https://github.com/OP-TEE/optee_os OP-TEE Trusted OS]</ref>
<ref name="OP-TEE/build">[https://github.com/OP-TEE/build Makefiles to use OP-TEE on various platforms]</ref>
</references>

DHCOM STM32MP15 Secure Boot

2022-03-22T10:19:12Z

Dkierner: Fix preposition in /* Checkout source code for Verified Boot */

<div class="toclimit-3">__TOC__</div>

== Introduction ==

=== Abbreviations ===

{| class="wikitable sortable"
|-
! Abbreviation !! Description
|-
| BSI || Bundesamt für Sicherheit in der Informationstechnik
|-
| CoM || Computer on module
|-
| FIT || Flattened Image Tree
|-
| FSBL || Fist Stage Bootloader (TF-A or U-Boot SPL)
|-
| OTP || One Time Programmable (eFuses)
|-
| OP-TEE || Open Portable Trusted Execution Environment
|-
| PKH || Public Key Hash
|-
| ROM || Read-Only Memory
|-
| RSA || Rivest, Shamir und Adleman (asynchronous encryption)
|-
| SHA || Secure Hash Algorithm
|-
| SoC || System on chip
|-
| SoM || System on module
|-
| SSBL || Second Stage Bootloader (U-Boot)
|-
| TF-A || Trusted Firmware A
|}

=== Secure Boot ===

The term Secure Boot originally comes from the UEFI specification<ref name="UEFI specification" /> and describes a secure boot process in which only signed software is loaded and executed during the boot process.

Secure Boot is a necessary cornerstone for enforcing security mechanisms in a trusted computing environment.
Enforcing the execution of signed software only during the boot process, as long as the chain of trust is secure, can guarantee that said software is free from tampering, as any manipulation will invalidate the software's signature and prevent the software from being executed.

[[File:Secure Boot Generic en.png|600px|Secure Boot Generic]]

The figure [[Media:Secure Boot Generic en.png|Secure Boot Generic]] shows an example of a secure boot process that leads to a reset in the event of an error in the signature check. Each stage uses the certificate and signature to check the origin and integrity of the next stage. On success, the next stage is executed, and in the event of an error, this always leads to a defined error state. In the simplest case, the certificates are integrated into the binary image of the previous stage.

Program code and certificate need to be trustworthy and therefore protected against tampering in each stage, otherwise the secure boot chain can be compromised. Except for the first stage, all binary images are protected against third-party tampering by the signature. As this is practically impossible for the first stage, manipulation protection has to be enforced by hardware measures to make said stage immutable, with the first stage's program code and the verification certificate for the second stage being stored in read-only memory (ROM).

=== Basic and trusted boot in the context of Secure Boot ===

When booting Linux on the STM32MP1 SoC with U-Boot SPL and U-Boot only, STM speaks of "Basic Boot"<ref name="Basic Boot" />.
However, if Linux is booted with a combination of TF-A, U-Boot and OP-TEE, STM refers to this as "Trusted Boot"<ref name="Trusted Boot" />.

{| class="wikitable"
|-
! Boot chain !! Description
|-
| Basic boot || BootROM -> U-Boot SPL -> U-Boot -> Linux
|-
| Trusted boot || BootROM -> TF-A -> U-Boot + OP-TEE -> Linux
|}

== Secure Boot in Basic Boot with BootROM authentication and Verified Boot ==

This Secure Boot implementation does use the the BootROM integrated image authentication to authenticate the U-Boot SPL as FSBL.
Authentication of U-Boot as SSBL by the U-Boot SPL and authentication of the Linux kernel, Device Tree and ramdisk by U-Boot is done using the open source implementation [[#Verified Boot|Verified Boot]].

This also means that everything from U-Boot SPL onwards is platform independent, as we do not rely on hardware specific implementations.

=== Verified Boot ===

Developers of Google's Chromium project worked out a concept for the Verified Boot called Secure Boot mechanism on the basis of the boot loader "Das U-Boot".
They use the existing infrastructure of the FIT images and for the system configuration at runtime via a Device Tree.
The description language for the FIT images was extended by an additional signature node and the Device Tree of the platform was used to store the certificate(s) for the authentication of the images.
The signature node can be used to sign individual subimages as well as combinations of individual subimages in the FIT image.
The tool <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight> takes care the signature creation for the FIT images and the addition of the certificate in a Device Tree.

With Verified Boot, the Device Tree with included public key is integrated into the program image of the stage, which accomplishes the authentication and is thus very similar to the general procedure shown in figure [[Media:Secure Boot Generic en.png|Secure Boot Generic]].
The number of public keys that can be integrated is theoretically unlimited, but they must be distinguishable by name.

==== Technical details of Verified Boot ====

{| class="wikitable"
|-
| '''Name'''
| Verified Boot
|-
| '''Implementierung'''
| Software (Open Source)
|-
| '''Hash algorithms'''
|
* SHA1 (deprecated)<ref name="BSI TR-02102" />
* SHA256
* SHA384
* SHA512
|-
| '''Crypto algorithms
|
* RSA2048 (deprecated as of 2024)<ref name="BSI TR-02102" />
* RSA4096

* ECDSA256 (currently limited to U-Boot SPL)
|-
| '''Number of key pairs'''
| unlimited
|-
|}

==== In-depth references for Verified Boot ====


===== Flatten Image Tree =====
* [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT U-Boot Documentation: doc/uImage.FIT]
* [https://source.denx.de/u-boot/u-boot/-/commit/d5934ad7 U-Boot Commit d5934ad7: "new uImage: Add dual format uImage support framework"]
* ...
* [https://source.denx.de/u-boot/u-boot/-/commit/3310c549 U-Boot Commit d5934ad7: "new uImage: Add new uImage format documentation and examples"]

===== Verified Boot =====

* [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT/signature.txt U-Boot Documentation: doc/uImage.FIT/signature.txt]
* [https://source.denx.de/u-boot/u-boot/-/commit/3e569a6b U-Boot Commit 3e569a6b: "image: Add signing infrastructure"]
* [https://source.denx.de/u-boot/u-boot/-/commit/56518e71 U-Boot Commit 56518e71: "image: Support signing of images"]
* [https://source.denx.de/u-boot/u-boot/-/commit/4d098529 U-Boot Commit 4d098529: "image: Add support for signing of FIT configurations"]

===== ECDSA signature verification =====

<div style="color:red">TODO: Mention ECDSA limitations</div>
Note: This has currently some limitations!


* [https://source.denx.de/u-boot/u-boot/-/commit/928a8be7 U-Boot Commit 928a8be7: "lib: ecdsa: Implement UCLASS_ECDSA verification on target"]
* [https://source.denx.de/u-boot/u-boot/-/commit/ee870859 U-Boot Commit ee870859: "arm: stm32mp1: Implement ECDSA signature verification"]

=== Tutorial: Secure boot from BootROM to Linux with basic boot ===

==== System requirements and needed tools ====

The following table lists all requirements to create the key pairs and build the signed images with embedded public keys.

{| class="wikitable"
|-
! Category !! Description
|-
| '''Host operating system''' ||
* Linux (Debian 9, Ubuntu 18.04 or higher prefered)
|-
| '''Debian packages''' ||
* bison
* device-tree-compiler
* flex
* gcc-arm-linux-gnueabihf (>= gcc 6)
* git
* make
* openssl
|-
| '''STM32 Tools''' ||
* [https://www.st.com/en/development-tools/stm32cubeprog.html STM32CubeProgrammer]
** STM32MP_KeyGen_CLI
** STM32MP_SigningTool_CLI
|}

<div style="color:red">TODO: Should we give host setup instructions?</div>


==== Intended use of the four generated key pairs ====

We've decided to create and use as few certificates as reasonable to ensure a high level of security.
Therefore, we chose a separate key pair for each boot stage and also a separate key pair for image and configuration nodes.
If you're confused about the difference between image and configuration nodes, head over to [[#Flatten Image Tree|Flatten Image Tree]] to refresh your knowledge.
The exact purpose of the four key pairs generated for Verified Boot is described in the following table.

{| class="wikitable"
|-
! File name !! Intended use
|-
| '''fsbl-img''' || Authenticate image nodes of FIT images loaded by U-Boot SPL (U-Boot, Device Tree, firmware)
|-
| '''fsbl-cfg''' || Authenticate config nodes of FIT images loaded by U-Boot SPL (U-Boot + Device Tree + firmware)
|-
| '''ssbl-img''' || Authenticate image nodes of FIT images loaded by U-Boot (Kernel, Device Tree, InitRamFS)
|-
| '''ssbl-cfg''' || Authenticate config nodes of FIT images loaded by U-Boot (Kernel + Device Tree + InitRamFS)
|-
|}

==== Created/Modified files in the U-Boot source for Verified Boot ====

The created or modified files to build U-Boot with Verified Boot on STM32MP15 are described in the following table.

{| class="wikitable"
|-
! File
! Description
|-
| build_signed_uboot.sh
| Shell script that automates the creation of key pairs, the modification of FIT source files and Device Tree's and building of U-Boot SPL and U-Boot.
|-
| board/dhelectronics/dh_stm32mp1/u-boot-dhco?.its
| FIT source files with defined U-Boot image and Device Tree's for DHSOM platforms.
|-
| board/dhelectronics/dh_stm32mp1/linux-dhcom.its
| Dummy FIT source file with defined dummy kernel image and dummy Device Tree for DHSOM platforms.<br>To avoid relying on a built kernel image on a fixed path, we created this dummy, since adding the public keys with <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight> requires a valid FIT source file.
|-
| configs/stm32mp15_dhco?_secure_defconfig
| Example U-Boot defconfig's with enabled <syntaxhighlight lang="shell" inline>CONFIG_FIT_SIGNATURE</syntaxhighlight> and <syntaxhighlight lang="shell" inline>CONFIG_SPL_FIT_SIGNATURE</syntaxhighlight>.
|}

==== Build Verified Boot enabled U-Boot SPL and U-Boot ====

To build the U-Boot SPL and U-Boot images, you need to check out the source code and run a build script that automates everything from key generation to image creation and signing.

===== Checkout source code for Verified Boot =====

<div style="color:red">TODO: Replace my personal GitLab by a public available repository</div>
Checkout the branch <syntaxhighlight lang="shell" inline>v2022.01_dhcom_secure_boot</syntaxhighlight> in my personal GitLab repository with:

<syntaxhighlight lang="shell">
git clone git@dhplgl01:jneuhauser/u-boot.git -b v2022.01_dhcom_secure_boot
</syntaxhighlight>

If you already have a cloned U-Boot source code, you can also fetch it into your existing repository with:

<syntaxhighlight lang="shell">
cd /path/to/u-boot
git remote add jneuhauser git@dhplgl01:jneuhauser/u-boot.git
git fetch jneuhauser
git checkout v2022.01_dhcom_secure_boot
</syntaxhighlight>

===== Run the build script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> =====

The shell script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> included in the U-Boot source performs the following steps.
# Prebuild U-Boat SPL and U-Boat to build the required tools and Device Tree's
# Generate the [[#Intended use of the four generated key pairs|four key pairs]] if not already created
# Generate/Modify FIT image source files for Linux (dummy) and U-Boot
# Add public keys to the built Device Tree's used by U-Boot SPL and U-Boot
# Rebuild U-Boot SPL and U-Boot with new Device Tree's containing the public keys

The script supports the following environment variables to configure the target architecture, the cross compiler, the defconfig, the key algorithm, the key directory, and a key postfix:
{| class="wikitable sortable"
|-
! Name !! Description !! Default
|-
| ARCH || Target architecture for the U-Boot build || arm
|-
| CROSS_COMPILE || Used cross compiler to build U-Boot || arm-linux-gnueabihf-
|-
| DEFCONFIG || Used defconfig for the U-Boot build || stm32mp15_dhcom_secure_defconfig
|-
| KEY_ALGO || Signature algorithm used for Verified Boot || rsa
|-
| KEY_DIR || Directory where the key pairs are stored || ../keys
|-
| KEY_POSTFIX || Postfix which is appended to the key names || -$(date +%F)
|}

To perform the steps mentioned above, you just need to run the shell script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> like below.
In this example, we override the default value for <syntaxhighlight lang="shell" inline>KEY_POSTFIX</syntaxhighlight> with <syntaxhighlight lang="shell" inline>-testing</syntaxhighlight> to append this string to the [[#Intended use of the four generated key pairs|four key file names]].
The script has debug output enabled by default, which should output all the statements in the script itself and the output of the commands used in the script.
If you have any problems with the script, feel free to get in touch with the script author [mailto:jneuhauser@dh-electronics.com Johann Neuhauser] and attach a logfile.

<syntaxhighlight lang="shell">
cd /path/to/u-boot
KEY_POSTFIX="-testing" ./build_signed_uboot.sh | tee build_signed_uboot.log
</syntaxhighlight>

If this process completes without error, there are two boot loader images in the root directory of the U-Boot source.
{| class="wikitable sortable"
|-
! File name !! Stage !! Description
|-
| u-boot-spl.stm32 || FSBL || U-Boot SPL binary with appended Device Tree and prepended STM32 image header<ref name="STM32 image header" />.
|-
| u-boot.itb || SSBL || U-Boot and Device Tree's contained in a signed FIT image.
|}

==== Generate key pair and sign U-Boot SPL for BootROM authentication ====

To sign the U-Boot SPL as SSBL image for authentication with the BootROM we have to use the STM32 tools <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight> and <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight>.

===== Generate key pair with <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight> =====

All STM32MP15 SoC's only support one key pair for authenticating images through the BootROM.
To generate ECDSA key pairs for the STM32MP Secure Boot we are using the tool <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight><ref name="KeyGen_tool" /> to generate a single key pair.
<syntaxhighlight lang="shell">
STM32MP_KeyGen_CLI --absolute-path "$(pwd)" --password 12345678
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Key Generator v2.9.0
-------------------------------------------------------------------

Prime256v1 curve is selected.
AES_256_cbc algorithm is selected for private key encryption
Generating Prime256v1 keys...
Private key PEM file created
Public key PEM file created
public key hash file created
Keys generated successfully.
+ public key: publicKey.pem
+ private key: privateKey.pem
+ public hash key: publicKeyhash.bin
</syntaxhighlight>

===== Sign U-Boot SPL with <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight> =====

To add the public key and the image signature to our built U-Boot SPL binary with STM32 image header, we are using the tool <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight><ref name="Signing_tool" /> to update the existing STM32 image header of <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> with the required details.
<syntaxhighlight lang="shell">
STM32MP_SigningTool_CLI --binary-image /path/to/u-boot/u-boot-spl.stm32 --public-key publicKey.pem --private-key privateKey.pem --password 12345678 --output /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Signing Tool v2.9.0
-------------------------------------------------------------------

Prime256v1 curve is selected.
Header version 1 preparation ...
Reading Private Key File...
ECDSA signature generated.
Signature verification: SUCCESS
The Signed image file generated successfully: /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>

You can check the STM32 image header details with:
<syntaxhighlight lang="shell">
STM32MP_SigningTool_CLI --dump-header /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Signing Tool v2.9.0
-------------------------------------------------------------------

Header description:

Magic: 0x53544d32
Signature: c8 30 a0 62 2d 6d 4e 1b b9 f7 fe 38 27 65 e0 44 f0 f5 9d e6 8a a6 02 cb 74 52 26 9c 1e e9 07 17
1a c7 da 8e 96 fa 82 d3 b1 dc d5 3a 05 0e 87 83 94 4d 47 ad 17 07 88 0d b5 ae 2e 38 1d 90 22 ad
Checksum: 0xa8ca85
Header version: 0x10000
Size: 0x22dec
Load address: 0x2ffc2500
Entry point: 0x2ffc2500
Image version: 0x0
Option flags: 0x0
ECDSA Algo: 0x1
ECDSA pub key: 3b 71 8e 59 f1 ee 4c a8 4b 72 5f 4a 1c 63 8b 6e b8 01 ec 1a 3f 8c 98 2f d2 1d 77 f9 09 10 8f 04
30 da 5c 3a 24 53 0d 71 93 f0 a5 d9 c9 a7 27 b4 5f a5 c4 4d 55 8b 7a 25 e3 03 ef ca 87 ff 04 25
Binary type: 0x0
</syntaxhighlight>
The difference to an unsigned STM32 image header is that the values for "Signature" and "ECDSA pub key" are not all zeros and that "Option flags" is 0x0 for enabled signature verification instead of 0x1 for disabled signature verification.

==== Write U-Boot SPL and U-Boot to your boot media ====

The first step to verify that the built U-Boot SPL and U-Boot works as expected is to program both images to your boot media.
Depending on the boot configuration, your DHSOM will boot from the module's SPI-NOR flash, from the module's or baseboard's eMMC or from an SD card.
The boot configuration is always defined by the boot pins by default, because the boot pins have no alternative function on the STM32MP15 SoC's.

<div style="color:red">TODO: How can a user determine the used boot media?</div>
<div style="color:red">TODO: How to enforce boot media on Secure Boot enabled devices?</div>

===== Write U-Boot SPL and U-Boot to the SPI-NOR flash of the SoM =====

The following '''commands for the U-Boot Shell''' calculate some addresses based on the image offsets expected by the BootROM, load the required images from SD card or via TFTP into memory and finally write the prepared memory into the SPI-NOR flash on the SoM.

Prepare for loading <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> into memory:
<syntaxhighlight lang="shell">
mw.b ${loadaddr} 0xff 0x200000
setexpr fsbl1addr ${loadaddr} + 0x0
setexpr fsbl2addr ${loadaddr} + 0x40000
setexpr ssbl1addr ${loadaddr} + 0x80000
</syntaxhighlight>

Load <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> from SD card:
<syntaxhighlight lang="shell">
load mmc 0:4 ${fsbl1addr} u-boot-spl.stm32
load mmc 0:4 ${fsbl2addr} u-boot-spl.stm32
load mmc 0:4 ${ssbl1addr} u-boot.itb
</syntaxhighlight>

Load <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> from tftp server:
<syntaxhighlight lang="shell">
setenv serverip 10.20.30.1
setenv ipaddr 10.20.30.100
setenv netmask 255.255.255.0
tftp ${fsbl1addr} ${serverip}:u-boot-spl.stm32
tftp ${fsbl2addr} ${serverip}:u-boot-spl.stm32
tftp ${ssbl1addr} ${serverip}:u-boot.itb
</syntaxhighlight>

Check for magic numbers of expected image headers and conditionally program the SPI-NOR flash:
<syntaxhighlight lang="shell">
if itest *${fsbl1addr} == 0x324d5453 && itest *${fsbl2addr} == 0x324d5453 && itest *${ssbl1addr} == 0xedfe0dd0; then
sf probe && sf update ${loadaddr} 0 0x200000
fi
</syntaxhighlight>

===== Write U-Boot SPL and U-Boot to an SD card =====

<div style="color:red">TODO:</div>


===== Write U-Boot SPL and U-Boot to the eMMC =====

<div style="color:red">TODO:</div>


==== Enroll, test and enforce BootROM image authentication ====

To enroll, test and enforce image authentication by the BootROM you need to program the PKH into the OTP of the STM32MP15 SoC.
The <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> file that you created in the [[#Generate key pair with STM32MP_KeyGen_CLI|Generate key pair with STM32MP_KeyGen_CLI]] step contains the PKH in binary format for use with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> U-Boot command.
If the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command does fail or is not available on the target U-Boot, you can also write the PKH manually with the more generic <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command into the OTP.

===== Program public key hash to eFuses =====

The following '''commands for the U-Boot Shell''' load the file <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> into memory and program the contained PKH to the OTP of the STM32MP15 SoC.
The used command <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> writes and locks the words of the OTP automatically without knowing anything about the OTP layout/addresses.
If this fails or the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command is not available, you can also write and lock the OTP with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command

====== Program <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> into OTP with <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command ======

Load <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> by SD card:
<syntaxhighlight lang="shell">
load mmc 0:4 ${loadaddr} publicKeyhash.bin
</syntaxhighlight>

Or load <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> by TFTP:
<syntaxhighlight lang="shell">
setenv serverip 10.20.30.1
setenv ipaddr 10.20.30.100
setenv netmask 255.255.255.0
tftp ${loadaddr} ${serverip}:publicKeyhash.bin
</syntaxhighlight>

Show the contents of <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight>:
<syntaxhighlight lang="shell">
stm32key read ${loadaddr}
</syntaxhighlight>
<syntaxhighlight lang="console">
Read KEY at 0xc2000000
OTP value 24: 4e31bbcd
OTP value 25: 51e827dd
OTP value 26: 3511f521
OTP value 27: fd9c11a2
OTP value 28: 5b997b82
OTP value 29: 8150adc5
OTP value 30: a9c68fa9
OTP value 31: 72a3ba74
</syntaxhighlight>

Write the contents of <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> to OTP with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command:
<syntaxhighlight lang="shell">
stm32key fuse ${loadaddr}
</syntaxhighlight>
<syntaxhighlight lang="console">
TODO: Add output
</syntaxhighlight>

====== Program PKH manually into OTP with <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command ======

Generate fuse command with hexdump from file <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> on linux host:
<div style="color:red">Warning: Do not use the example output! Only use your unique values for programming the PKH in the OTP!</div>
<syntaxhighlight lang="shell">
echo fuse prog -y 0 0x18 $(hexdump -e '/4 "0x"' -e '/1 "%x"' -e '" "' /path/to/publicKeyhash.bin)
</syntaxhighlight>
<syntaxhighlight lang="console">
fuse prog -y 0 0x18 0x4e31bbcd 0x51e827dd 0x3511f521 0xfd9c11a2 0x5b997b82 0x8150adc5 0xa9c68fa9 0x72a3ba74
</syntaxhighlight>

Write the PKH into OTP manually with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<div style="color:red">Warning: Do not use the example command! Only use your unique values for programming the PKH in the OTP!</div>
<syntaxhighlight lang="shell">
fuse prog -y 0 0x18 0x4e31bbcd 0x51e827dd 0x3511f521 0xfd9c11a2 0x5b997b82 0x8150adc5 0xa9c68fa9 0x72a3ba74
</syntaxhighlight>

Lock the related OTP words manually with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<syntaxhighlight lang="shell">
fuse prog -y 0 0x10000018 1 1 1 1 1 1 1 1
</syntaxhighlight>

===== Test BootROM image authentication =====

To verify the image authentication by the BootROM with the programmed PKH and the programmed signed images, you must reboot your device.

On the third line of the U-Boot SPL output, check the BootROM authentication status.
The status output should look like this: <syntaxhighlight lang="console" inline>Bootrom authentication: succeeded</syntaxhighlight>.
Note the <syntaxhighlight lang="console" inline>succeeded</syntaxhighlight> status for successful authentication of the U-Boot SPL image by the BootROM.

The following output shows successful authentication of the U-Boot-SPL image in line 3, as well as successful authentication of the used configuration in line 7 and the U-Boot and Device Tree subimages in lines 8 and 9 of the U-Boot-FIT image.
<syntaxhighlight lang="console" line highlight="3,7-9">
U-Boot SPL 2022.01-00012-g6c5892c90c28 (Feb 16 2022 - 11:11:16 +0100)
Model: STMicroelectronics STM32MP15xx DHCOM Premium Developer Kit (2)
Bootrom authentication: succeeded
Code: SoM:rev=1,ddr3=3 Board:rev=0
RAM: DDR3L 32bits 2x4Gb 533MHz
Trying to boot from SPI
## Checking hash(es) for config config-2 ... sha256,rsa4096:fsbl-cfg-2022-02-16+ OK
## Checking hash(es) for Image uboot ... sha256,rsa4096:fsbl-img-2022-02-16+ sha256+ OK
## Checking hash(es) for Image fdt-1 ... sha256,rsa4096:fsbl-img-2022-02-16+ sha256+ OK
</syntaxhighlight>

===== Enforce BootROM image authentication =====

Without any further changes, the BootROM is able to perform authentication of the FSBL image, but unauthenticated images can still be used and executed.
The device is still open, let's see this as a kind of test mode to check if the PKH is set correctly.

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

The 6th bit in the 1st word of the OTP is responsible that the BootROM only accepts signed images.
Burning this bit enforces authentication of images by the BootROM and unsigned binaries are no longer supported on the target device.

To program this bit, the U-Boot Shell can be used with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command or with the more general <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command.

With usage of the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command:
<div style="color:red">Warning: After running the following command, your device will only be able to boot signed images!</div>
<syntaxhighlight lang="shell">
stm32key close
</syntaxhighlight>

Or with usage of the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<div style="color:red">Warning: After running the following command, your device will only be able to boot signed images!</div>
<syntaxhighlight lang="shell">
fuse prog 0 0x0 0x40
</syntaxhighlight>

== Secure Boot in Trusted Boot with BootROM authentication, TF-A and OP-TEE ==

<div style="color:red">TODO:</div>
# Add support for STM32MP15 DHCOM in <ref name="TF-A" />
# Add support for STM32MP15 DHCOM in <ref name="OP-TEE/optee_os" />
# Create stm32mp15_dhcom_trusted_defconfig???
# Integrate STM32MP15 DHCOM into <ref name="OP-TEE/build" />

== References ==

<references>
<ref name="UEFI specification">[http://www.uefi.org/specifications http://www.uefi.org/specifications]</ref>
<ref name="Basic Boot">[https://source.denx.de/u-boot/u-boot/-/blob/master/configs/stm32mp15_basic_defconfig U-Boot Source stm32mp15_basic_defconfig]</ref>
<ref name="Trusted Boot">[https://source.denx.de/u-boot/u-boot/-/blob/master/configs/stm32mp15_trusted_defconfig U-Boot Source stm32mp15_trusted_defconfig]</ref>
<ref name="BSI TR-02102">[https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.pdf BSI - Technische Richtlinie, "Kryptographische Algorithmen und Schlüssellängen", BSI TR-02102-1]</ref>
<ref name="STM32 image header">[https://wiki.st.com/stm32mpu/wiki/STM32_header_for_binary_files STM32 header for binary files]</ref>
<ref name="KeyGen_tool">[https://wiki.st.com/stm32mpu/wiki/KeyGen_tool STM32MP KeyGen tool]</ref>
<ref name="Signing_tool">[https://wiki.st.com/stm32mpu/wiki/Signing_tool STM32MP Signing tool]</ref>
<ref name="TF-A">[https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/ Trusted Firmware-A (TF-A)]</ref>
<ref name="OP-TEE/optee_os">[https://github.com/OP-TEE/optee_os OP-TEE Trusted OS]</ref>
<ref name="OP-TEE/build">[https://github.com/OP-TEE/build Makefiles to use OP-TEE on various platforms]</ref>
</references>

DHCOM STM32MP15 Secure Boot

2022-03-22T10:04:59Z

Dkierner: Correct full stop to colon in: /* Run the build script build_signed_uboot.sh */

<div class="toclimit-3">__TOC__</div>

== Introduction ==

=== Abbreviations ===

{| class="wikitable sortable"
|-
! Abbreviation !! Description
|-
| BSI || Bundesamt für Sicherheit in der Informationstechnik
|-
| CoM || Computer on module
|-
| FIT || Flattened Image Tree
|-
| FSBL || Fist Stage Bootloader (TF-A or U-Boot SPL)
|-
| OTP || One Time Programmable (eFuses)
|-
| OP-TEE || Open Portable Trusted Execution Environment
|-
| PKH || Public Key Hash
|-
| ROM || Read-Only Memory
|-
| RSA || Rivest, Shamir und Adleman (asynchronous encryption)
|-
| SHA || Secure Hash Algorithm
|-
| SoC || System on chip
|-
| SoM || System on module
|-
| SSBL || Second Stage Bootloader (U-Boot)
|-
| TF-A || Trusted Firmware A
|}

=== Secure Boot ===

The term Secure Boot originally comes from the UEFI specification<ref name="UEFI specification" /> and describes a secure boot process in which only signed software is loaded and executed during the boot process.

Secure Boot is a necessary cornerstone for enforcing security mechanisms in a trusted computing environment.
Enforcing the execution of signed software only during the boot process, as long as the chain of trust is secure, can guarantee that said software is free from tampering, as any manipulation will invalidate the software's signature and prevent the software from being executed.

[[File:Secure Boot Generic en.png|600px|Secure Boot Generic]]

The figure [[Media:Secure Boot Generic en.png|Secure Boot Generic]] shows an example of a secure boot process that leads to a reset in the event of an error in the signature check. Each stage uses the certificate and signature to check the origin and integrity of the next stage. On success, the next stage is executed, and in the event of an error, this always leads to a defined error state. In the simplest case, the certificates are integrated into the binary image of the previous stage.

Program code and certificate need to be trustworthy and therefore protected against tampering in each stage, otherwise the secure boot chain can be compromised. Except for the first stage, all binary images are protected against third-party tampering by the signature. As this is practically impossible for the first stage, manipulation protection has to be enforced by hardware measures to make said stage immutable, with the first stage's program code and the verification certificate for the second stage being stored in read-only memory (ROM).

=== Basic and trusted boot in the context of Secure Boot ===

When booting Linux on the STM32MP1 SoC with U-Boot SPL and U-Boot only, STM speaks of "Basic Boot"<ref name="Basic Boot" />.
However, if Linux is booted with a combination of TF-A, U-Boot and OP-TEE, STM refers to this as "Trusted Boot"<ref name="Trusted Boot" />.

{| class="wikitable"
|-
! Boot chain !! Description
|-
| Basic boot || BootROM -> U-Boot SPL -> U-Boot -> Linux
|-
| Trusted boot || BootROM -> TF-A -> U-Boot + OP-TEE -> Linux
|}

== Secure Boot in Basic Boot with BootROM authentication and Verified Boot ==

This Secure Boot implementation does use the the BootROM integrated image authentication to authenticate the U-Boot SPL as FSBL.
Authentication of U-Boot as SSBL by the U-Boot SPL and authentication of the Linux kernel, Device Tree and ramdisk by U-Boot is done using the open source implementation [[#Verified Boot|Verified Boot]].

This also means that everything from U-Boot SPL onwards is platform independent, as we do not rely on hardware specific implementations.

=== Verified Boot ===

Developers of Google's Chromium project worked out a concept for the Verified Boot called Secure Boot mechanism on the basis of the boot loader "Das U-Boot".
They use the existing infrastructure of the FIT images and for the system configuration at runtime via a Device Tree.
The description language for the FIT images was extended by an additional signature node and the Device Tree of the platform was used to store the certificate(s) for the authentication of the images.
The signature node can be used to sign individual subimages as well as combinations of individual subimages in the FIT image.
The tool <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight> takes care the signature creation for the FIT images and the addition of the certificate in a Device Tree.

With Verified Boot, the Device Tree with included public key is integrated into the program image of the stage, which accomplishes the authentication and is thus very similar to the general procedure shown in figure [[Media:Secure Boot Generic en.png|Secure Boot Generic]].
The number of public keys that can be integrated is theoretically unlimited, but they must be distinguishable by name.

==== Technical details of Verified Boot ====

{| class="wikitable"
|-
| '''Name'''
| Verified Boot
|-
| '''Implementierung'''
| Software (Open Source)
|-
| '''Hash algorithms'''
|
* SHA1 (deprecated)<ref name="BSI TR-02102" />
* SHA256
* SHA384
* SHA512
|-
| '''Crypto algorithms
|
* RSA2048 (deprecated as of 2024)<ref name="BSI TR-02102" />
* RSA4096

* ECDSA256 (currently limited to U-Boot SPL)
|-
| '''Number of key pairs'''
| unlimited
|-
|}

==== In-depth references for Verified Boot ====


===== Flatten Image Tree =====
* [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT U-Boot Documentation: doc/uImage.FIT]
* [https://source.denx.de/u-boot/u-boot/-/commit/d5934ad7 U-Boot Commit d5934ad7: "new uImage: Add dual format uImage support framework"]
* ...
* [https://source.denx.de/u-boot/u-boot/-/commit/3310c549 U-Boot Commit d5934ad7: "new uImage: Add new uImage format documentation and examples"]

===== Verified Boot =====

* [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT/signature.txt U-Boot Documentation: doc/uImage.FIT/signature.txt]
* [https://source.denx.de/u-boot/u-boot/-/commit/3e569a6b U-Boot Commit 3e569a6b: "image: Add signing infrastructure"]
* [https://source.denx.de/u-boot/u-boot/-/commit/56518e71 U-Boot Commit 56518e71: "image: Support signing of images"]
* [https://source.denx.de/u-boot/u-boot/-/commit/4d098529 U-Boot Commit 4d098529: "image: Add support for signing of FIT configurations"]

===== ECDSA signature verification =====

<div style="color:red">TODO: Mention ECDSA limitations</div>
Note: This has currently some limitations!


* [https://source.denx.de/u-boot/u-boot/-/commit/928a8be7 U-Boot Commit 928a8be7: "lib: ecdsa: Implement UCLASS_ECDSA verification on target"]
* [https://source.denx.de/u-boot/u-boot/-/commit/ee870859 U-Boot Commit ee870859: "arm: stm32mp1: Implement ECDSA signature verification"]

=== Tutorial: Secure boot from BootROM to Linux with basic boot ===

==== System requirements and needed tools ====

The following table lists all requirements to create the key pairs and build the signed images with embedded public keys.

{| class="wikitable"
|-
! Category !! Description
|-
| '''Host operating system''' ||
* Linux (Debian 9, Ubuntu 18.04 or higher prefered)
|-
| '''Debian packages''' ||
* bison
* device-tree-compiler
* flex
* gcc-arm-linux-gnueabihf (>= gcc 6)
* git
* make
* openssl
|-
| '''STM32 Tools''' ||
* [https://www.st.com/en/development-tools/stm32cubeprog.html STM32CubeProgrammer]
** STM32MP_KeyGen_CLI
** STM32MP_SigningTool_CLI
|}

<div style="color:red">TODO: Should we give host setup instructions?</div>


==== Intended use of the four generated key pairs ====

We've decided to create and use as few certificates as reasonable to ensure a high level of security.
Therefore, we chose a separate key pair for each boot stage and also a separate key pair for image and configuration nodes.
If you're confused about the difference between image and configuration nodes, head over to [[#Flatten Image Tree|Flatten Image Tree]] to refresh your knowledge.
The exact purpose of the four key pairs generated for Verified Boot is described in the following table.

{| class="wikitable"
|-
! File name !! Intended use
|-
| '''fsbl-img''' || Authenticate image nodes of FIT images loaded by U-Boot SPL (U-Boot, Device Tree, firmware)
|-
| '''fsbl-cfg''' || Authenticate config nodes of FIT images loaded by U-Boot SPL (U-Boot + Device Tree + firmware)
|-
| '''ssbl-img''' || Authenticate image nodes of FIT images loaded by U-Boot (Kernel, Device Tree, InitRamFS)
|-
| '''ssbl-cfg''' || Authenticate config nodes of FIT images loaded by U-Boot (Kernel + Device Tree + InitRamFS)
|-
|}

==== Created/Modified files in the U-Boot source for Verified Boot ====

The created or modified files to build U-Boot with Verified Boot on STM32MP15 are described in the following table.

{| class="wikitable"
|-
! File
! Description
|-
| build_signed_uboot.sh
| Shell script that automates the creation of key pairs, the modification of FIT source files and Device Tree's and building of U-Boot SPL and U-Boot.
|-
| board/dhelectronics/dh_stm32mp1/u-boot-dhco?.its
| FIT source files with defined U-Boot image and Device Tree's for DHSOM platforms.
|-
| board/dhelectronics/dh_stm32mp1/linux-dhcom.its
| Dummy FIT source file with defined dummy kernel image and dummy Device Tree for DHSOM platforms.<br>To avoid relying on a built kernel image on a fixed path, we created this dummy, since adding the public keys with <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight> requires a valid FIT source file.
|-
| configs/stm32mp15_dhco?_secure_defconfig
| Example U-Boot defconfig's with enabled <syntaxhighlight lang="shell" inline>CONFIG_FIT_SIGNATURE</syntaxhighlight> and <syntaxhighlight lang="shell" inline>CONFIG_SPL_FIT_SIGNATURE</syntaxhighlight>.
|}

==== Build Verified Boot enabled U-Boot SPL and U-Boot ====

To build the U-Boot SPL and U-Boot images, you need to check out the source code and run a build script that automates everything from key generation to image creation and signing.

===== Checkout source code for Verified Boot =====

<div style="color:red">TODO: Replace my personal GitLab by a public available repository</div>
Checkout the branch <syntaxhighlight lang="shell" inline>v2022.01_dhcom_secure_boot</syntaxhighlight> of my personal GitLab repository with:

<syntaxhighlight lang="shell">
git clone git@dhplgl01:jneuhauser/u-boot.git -b v2022.01_dhcom_secure_boot
</syntaxhighlight>

If you already have a cloned U-Boot source code, you can also fetch it into your existing repository with:

<syntaxhighlight lang="shell">
cd /path/to/u-boot
git remote add jneuhauser git@dhplgl01:jneuhauser/u-boot.git
git fetch jneuhauser
git checkout v2022.01_dhcom_secure_boot
</syntaxhighlight>

===== Run the build script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> =====

The shell script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> included in the U-Boot source performs the following steps.
# Prebuild U-Boat SPL and U-Boat to build the required tools and Device Tree's
# Generate the [[#Intended use of the four generated key pairs|four key pairs]] if not already created
# Generate/Modify FIT image source files for Linux (dummy) and U-Boot
# Add public keys to the built Device Tree's used by U-Boot SPL and U-Boot
# Rebuild U-Boot SPL and U-Boot with new Device Tree's containing the public keys

The script supports the following environment variables to configure the target architecture, the cross compiler, the defconfig, the key algorithm, the key directory, and a key postfix:
{| class="wikitable sortable"
|-
! Name !! Description !! Default
|-
| ARCH || Target architecture for the U-Boot build || arm
|-
| CROSS_COMPILE || Used cross compiler to build U-Boot || arm-linux-gnueabihf-
|-
| DEFCONFIG || Used defconfig for the U-Boot build || stm32mp15_dhcom_secure_defconfig
|-
| KEY_ALGO || Signature algorithm used for Verified Boot || rsa
|-
| KEY_DIR || Directory where the key pairs are stored || ../keys
|-
| KEY_POSTFIX || Postfix which is appended to the key names || -$(date +%F)
|}

To perform the steps mentioned above, you just need to run the shell script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> like below.
In this example, we override the default value for <syntaxhighlight lang="shell" inline>KEY_POSTFIX</syntaxhighlight> with <syntaxhighlight lang="shell" inline>-testing</syntaxhighlight> to append this string to the [[#Intended use of the four generated key pairs|four key file names]].
The script has debug output enabled by default, which should output all the statements in the script itself and the output of the commands used in the script.
If you have any problems with the script, feel free to get in touch with the script author [mailto:jneuhauser@dh-electronics.com Johann Neuhauser] and attach a logfile.

<syntaxhighlight lang="shell">
cd /path/to/u-boot
KEY_POSTFIX="-testing" ./build_signed_uboot.sh | tee build_signed_uboot.log
</syntaxhighlight>

If this process completes without error, there are two boot loader images in the root directory of the U-Boot source.
{| class="wikitable sortable"
|-
! File name !! Stage !! Description
|-
| u-boot-spl.stm32 || FSBL || U-Boot SPL binary with appended Device Tree and prepended STM32 image header<ref name="STM32 image header" />.
|-
| u-boot.itb || SSBL || U-Boot and Device Tree's contained in a signed FIT image.
|}

==== Generate key pair and sign U-Boot SPL for BootROM authentication ====

To sign the U-Boot SPL as SSBL image for authentication with the BootROM we have to use the STM32 tools <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight> and <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight>.

===== Generate key pair with <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight> =====

All STM32MP15 SoC's only support one key pair for authenticating images through the BootROM.
To generate ECDSA key pairs for the STM32MP Secure Boot we are using the tool <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight><ref name="KeyGen_tool" /> to generate a single key pair.
<syntaxhighlight lang="shell">
STM32MP_KeyGen_CLI --absolute-path "$(pwd)" --password 12345678
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Key Generator v2.9.0
-------------------------------------------------------------------

Prime256v1 curve is selected.
AES_256_cbc algorithm is selected for private key encryption
Generating Prime256v1 keys...
Private key PEM file created
Public key PEM file created
public key hash file created
Keys generated successfully.
+ public key: publicKey.pem
+ private key: privateKey.pem
+ public hash key: publicKeyhash.bin
</syntaxhighlight>

===== Sign U-Boot SPL with <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight> =====

To add the public key and the image signature to our built U-Boot SPL binary with STM32 image header, we are using the tool <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight><ref name="Signing_tool" /> to update the existing STM32 image header of <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> with the required details.
<syntaxhighlight lang="shell">
STM32MP_SigningTool_CLI --binary-image /path/to/u-boot/u-boot-spl.stm32 --public-key publicKey.pem --private-key privateKey.pem --password 12345678 --output /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Signing Tool v2.9.0
-------------------------------------------------------------------

Prime256v1 curve is selected.
Header version 1 preparation ...
Reading Private Key File...
ECDSA signature generated.
Signature verification: SUCCESS
The Signed image file generated successfully: /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>

You can check the STM32 image header details with:
<syntaxhighlight lang="shell">
STM32MP_SigningTool_CLI --dump-header /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Signing Tool v2.9.0
-------------------------------------------------------------------

Header description:

Magic: 0x53544d32
Signature: c8 30 a0 62 2d 6d 4e 1b b9 f7 fe 38 27 65 e0 44 f0 f5 9d e6 8a a6 02 cb 74 52 26 9c 1e e9 07 17
1a c7 da 8e 96 fa 82 d3 b1 dc d5 3a 05 0e 87 83 94 4d 47 ad 17 07 88 0d b5 ae 2e 38 1d 90 22 ad
Checksum: 0xa8ca85
Header version: 0x10000
Size: 0x22dec
Load address: 0x2ffc2500
Entry point: 0x2ffc2500
Image version: 0x0
Option flags: 0x0
ECDSA Algo: 0x1
ECDSA pub key: 3b 71 8e 59 f1 ee 4c a8 4b 72 5f 4a 1c 63 8b 6e b8 01 ec 1a 3f 8c 98 2f d2 1d 77 f9 09 10 8f 04
30 da 5c 3a 24 53 0d 71 93 f0 a5 d9 c9 a7 27 b4 5f a5 c4 4d 55 8b 7a 25 e3 03 ef ca 87 ff 04 25
Binary type: 0x0
</syntaxhighlight>
The difference to an unsigned STM32 image header is that the values for "Signature" and "ECDSA pub key" are not all zeros and that "Option flags" is 0x0 for enabled signature verification instead of 0x1 for disabled signature verification.

==== Write U-Boot SPL and U-Boot to your boot media ====

The first step to verify that the built U-Boot SPL and U-Boot works as expected is to program both images to your boot media.
Depending on the boot configuration, your DHSOM will boot from the module's SPI-NOR flash, from the module's or baseboard's eMMC or from an SD card.
The boot configuration is always defined by the boot pins by default, because the boot pins have no alternative function on the STM32MP15 SoC's.

<div style="color:red">TODO: How can a user determine the used boot media?</div>
<div style="color:red">TODO: How to enforce boot media on Secure Boot enabled devices?</div>

===== Write U-Boot SPL and U-Boot to the SPI-NOR flash of the SoM =====

The following '''commands for the U-Boot Shell''' calculate some addresses based on the image offsets expected by the BootROM, load the required images from SD card or via TFTP into memory and finally write the prepared memory into the SPI-NOR flash on the SoM.

Prepare for loading <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> into memory:
<syntaxhighlight lang="shell">
mw.b ${loadaddr} 0xff 0x200000
setexpr fsbl1addr ${loadaddr} + 0x0
setexpr fsbl2addr ${loadaddr} + 0x40000
setexpr ssbl1addr ${loadaddr} + 0x80000
</syntaxhighlight>

Load <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> from SD card:
<syntaxhighlight lang="shell">
load mmc 0:4 ${fsbl1addr} u-boot-spl.stm32
load mmc 0:4 ${fsbl2addr} u-boot-spl.stm32
load mmc 0:4 ${ssbl1addr} u-boot.itb
</syntaxhighlight>

Load <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> from tftp server:
<syntaxhighlight lang="shell">
setenv serverip 10.20.30.1
setenv ipaddr 10.20.30.100
setenv netmask 255.255.255.0
tftp ${fsbl1addr} ${serverip}:u-boot-spl.stm32
tftp ${fsbl2addr} ${serverip}:u-boot-spl.stm32
tftp ${ssbl1addr} ${serverip}:u-boot.itb
</syntaxhighlight>

Check for magic numbers of expected image headers and conditionally program the SPI-NOR flash:
<syntaxhighlight lang="shell">
if itest *${fsbl1addr} == 0x324d5453 && itest *${fsbl2addr} == 0x324d5453 && itest *${ssbl1addr} == 0xedfe0dd0; then
sf probe && sf update ${loadaddr} 0 0x200000
fi
</syntaxhighlight>

===== Write U-Boot SPL and U-Boot to an SD card =====

<div style="color:red">TODO:</div>


===== Write U-Boot SPL and U-Boot to the eMMC =====

<div style="color:red">TODO:</div>


==== Enroll, test and enforce BootROM image authentication ====

To enroll, test and enforce image authentication by the BootROM you need to program the PKH into the OTP of the STM32MP15 SoC.
The <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> file that you created in the [[#Generate key pair with STM32MP_KeyGen_CLI|Generate key pair with STM32MP_KeyGen_CLI]] step contains the PKH in binary format for use with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> U-Boot command.
If the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command does fail or is not available on the target U-Boot, you can also write the PKH manually with the more generic <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command into the OTP.

===== Program public key hash to eFuses =====

The following '''commands for the U-Boot Shell''' load the file <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> into memory and program the contained PKH to the OTP of the STM32MP15 SoC.
The used command <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> writes and locks the words of the OTP automatically without knowing anything about the OTP layout/addresses.
If this fails or the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command is not available, you can also write and lock the OTP with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command

====== Program <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> into OTP with <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command ======

Load <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> by SD card:
<syntaxhighlight lang="shell">
load mmc 0:4 ${loadaddr} publicKeyhash.bin
</syntaxhighlight>

Or load <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> by TFTP:
<syntaxhighlight lang="shell">
setenv serverip 10.20.30.1
setenv ipaddr 10.20.30.100
setenv netmask 255.255.255.0
tftp ${loadaddr} ${serverip}:publicKeyhash.bin
</syntaxhighlight>

Show the contents of <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight>:
<syntaxhighlight lang="shell">
stm32key read ${loadaddr}
</syntaxhighlight>
<syntaxhighlight lang="console">
Read KEY at 0xc2000000
OTP value 24: 4e31bbcd
OTP value 25: 51e827dd
OTP value 26: 3511f521
OTP value 27: fd9c11a2
OTP value 28: 5b997b82
OTP value 29: 8150adc5
OTP value 30: a9c68fa9
OTP value 31: 72a3ba74
</syntaxhighlight>

Write the contents of <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> to OTP with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command:
<syntaxhighlight lang="shell">
stm32key fuse ${loadaddr}
</syntaxhighlight>
<syntaxhighlight lang="console">
TODO: Add output
</syntaxhighlight>

====== Program PKH manually into OTP with <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command ======

Generate fuse command with hexdump from file <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> on linux host:
<div style="color:red">Warning: Do not use the example output! Only use your unique values for programming the PKH in the OTP!</div>
<syntaxhighlight lang="shell">
echo fuse prog -y 0 0x18 $(hexdump -e '/4 "0x"' -e '/1 "%x"' -e '" "' /path/to/publicKeyhash.bin)
</syntaxhighlight>
<syntaxhighlight lang="console">
fuse prog -y 0 0x18 0x4e31bbcd 0x51e827dd 0x3511f521 0xfd9c11a2 0x5b997b82 0x8150adc5 0xa9c68fa9 0x72a3ba74
</syntaxhighlight>

Write the PKH into OTP manually with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<div style="color:red">Warning: Do not use the example command! Only use your unique values for programming the PKH in the OTP!</div>
<syntaxhighlight lang="shell">
fuse prog -y 0 0x18 0x4e31bbcd 0x51e827dd 0x3511f521 0xfd9c11a2 0x5b997b82 0x8150adc5 0xa9c68fa9 0x72a3ba74
</syntaxhighlight>

Lock the related OTP words manually with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<syntaxhighlight lang="shell">
fuse prog -y 0 0x10000018 1 1 1 1 1 1 1 1
</syntaxhighlight>

===== Test BootROM image authentication =====

To verify the image authentication by the BootROM with the programmed PKH and the programmed signed images, you must reboot your device.

On the third line of the U-Boot SPL output, check the BootROM authentication status.
The status output should look like this: <syntaxhighlight lang="console" inline>Bootrom authentication: succeeded</syntaxhighlight>.
Note the <syntaxhighlight lang="console" inline>succeeded</syntaxhighlight> status for successful authentication of the U-Boot SPL image by the BootROM.

The following output shows successful authentication of the U-Boot-SPL image in line 3, as well as successful authentication of the used configuration in line 7 and the U-Boot and Device Tree subimages in lines 8 and 9 of the U-Boot-FIT image.
<syntaxhighlight lang="console" line highlight="3,7-9">
U-Boot SPL 2022.01-00012-g6c5892c90c28 (Feb 16 2022 - 11:11:16 +0100)
Model: STMicroelectronics STM32MP15xx DHCOM Premium Developer Kit (2)
Bootrom authentication: succeeded
Code: SoM:rev=1,ddr3=3 Board:rev=0
RAM: DDR3L 32bits 2x4Gb 533MHz
Trying to boot from SPI
## Checking hash(es) for config config-2 ... sha256,rsa4096:fsbl-cfg-2022-02-16+ OK
## Checking hash(es) for Image uboot ... sha256,rsa4096:fsbl-img-2022-02-16+ sha256+ OK
## Checking hash(es) for Image fdt-1 ... sha256,rsa4096:fsbl-img-2022-02-16+ sha256+ OK
</syntaxhighlight>

===== Enforce BootROM image authentication =====

Without any further changes, the BootROM is able to perform authentication of the FSBL image, but unauthenticated images can still be used and executed.
The device is still open, let's see this as a kind of test mode to check if the PKH is set correctly.

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

The 6th bit in the 1st word of the OTP is responsible that the BootROM only accepts signed images.
Burning this bit enforces authentication of images by the BootROM and unsigned binaries are no longer supported on the target device.

To program this bit, the U-Boot Shell can be used with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command or with the more general <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command.

With usage of the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command:
<div style="color:red">Warning: After running the following command, your device will only be able to boot signed images!</div>
<syntaxhighlight lang="shell">
stm32key close
</syntaxhighlight>

Or with usage of the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<div style="color:red">Warning: After running the following command, your device will only be able to boot signed images!</div>
<syntaxhighlight lang="shell">
fuse prog 0 0x0 0x40
</syntaxhighlight>

== Secure Boot in Trusted Boot with BootROM authentication, TF-A and OP-TEE ==

<div style="color:red">TODO:</div>
# Add support for STM32MP15 DHCOM in <ref name="TF-A" />
# Add support for STM32MP15 DHCOM in <ref name="OP-TEE/optee_os" />
# Create stm32mp15_dhcom_trusted_defconfig???
# Integrate STM32MP15 DHCOM into <ref name="OP-TEE/build" />

== References ==

<references>
<ref name="UEFI specification">[http://www.uefi.org/specifications http://www.uefi.org/specifications]</ref>
<ref name="Basic Boot">[https://source.denx.de/u-boot/u-boot/-/blob/master/configs/stm32mp15_basic_defconfig U-Boot Source stm32mp15_basic_defconfig]</ref>
<ref name="Trusted Boot">[https://source.denx.de/u-boot/u-boot/-/blob/master/configs/stm32mp15_trusted_defconfig U-Boot Source stm32mp15_trusted_defconfig]</ref>
<ref name="BSI TR-02102">[https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.pdf BSI - Technische Richtlinie, "Kryptographische Algorithmen und Schlüssellängen", BSI TR-02102-1]</ref>
<ref name="STM32 image header">[https://wiki.st.com/stm32mpu/wiki/STM32_header_for_binary_files STM32 header for binary files]</ref>
<ref name="KeyGen_tool">[https://wiki.st.com/stm32mpu/wiki/KeyGen_tool STM32MP KeyGen tool]</ref>
<ref name="Signing_tool">[https://wiki.st.com/stm32mpu/wiki/Signing_tool STM32MP Signing tool]</ref>
<ref name="TF-A">[https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/ Trusted Firmware-A (TF-A)]</ref>
<ref name="OP-TEE/optee_os">[https://github.com/OP-TEE/optee_os OP-TEE Trusted OS]</ref>
<ref name="OP-TEE/build">[https://github.com/OP-TEE/build Makefiles to use OP-TEE on various platforms]</ref>
</references>

DHCOM STM32MP15 Secure Boot

2022-03-22T09:53:35Z

Dkierner: Fix links to /* Verified Boot */

<div class="toclimit-3">__TOC__</div>

== Introduction ==

=== Abbreviations ===

{| class="wikitable sortable"
|-
! Abbreviation !! Description
|-
| BSI || Bundesamt für Sicherheit in der Informationstechnik
|-
| CoM || Computer on module
|-
| FIT || Flattened Image Tree
|-
| FSBL || Fist Stage Bootloader (TF-A or U-Boot SPL)
|-
| OTP || One Time Programmable (eFuses)
|-
| OP-TEE || Open Portable Trusted Execution Environment
|-
| PKH || Public Key Hash
|-
| ROM || Read-Only Memory
|-
| RSA || Rivest, Shamir und Adleman (asynchronous encryption)
|-
| SHA || Secure Hash Algorithm
|-
| SoC || System on chip
|-
| SoM || System on module
|-
| SSBL || Second Stage Bootloader (U-Boot)
|-
| TF-A || Trusted Firmware A
|}

=== Secure Boot ===

The term Secure Boot originally comes from the UEFI specification<ref name="UEFI specification" /> and describes a secure boot process in which only signed software is loaded and executed during the boot process.

Secure Boot is a necessary cornerstone for enforcing security mechanisms in a trusted computing environment.
Enforcing the execution of signed software only during the boot process, as long as the chain of trust is secure, can guarantee that said software is free from tampering, as any manipulation will invalidate the software's signature and prevent the software from being executed.

[[File:Secure Boot Generic en.png|600px|Secure Boot Generic]]

The figure [[Media:Secure Boot Generic en.png|Secure Boot Generic]] shows an example of a secure boot process that leads to a reset in the event of an error in the signature check. Each stage uses the certificate and signature to check the origin and integrity of the next stage. On success, the next stage is executed, and in the event of an error, this always leads to a defined error state. In the simplest case, the certificates are integrated into the binary image of the previous stage.

Program code and certificate need to be trustworthy and therefore protected against tampering in each stage, otherwise the secure boot chain can be compromised. Except for the first stage, all binary images are protected against third-party tampering by the signature. As this is practically impossible for the first stage, manipulation protection has to be enforced by hardware measures to make said stage immutable, with the first stage's program code and the verification certificate for the second stage being stored in read-only memory (ROM).

=== Basic and trusted boot in the context of Secure Boot ===

When booting Linux on the STM32MP1 SoC with U-Boot SPL and U-Boot only, STM speaks of "Basic Boot"<ref name="Basic Boot" />.
However, if Linux is booted with a combination of TF-A, U-Boot and OP-TEE, STM refers to this as "Trusted Boot"<ref name="Trusted Boot" />.

{| class="wikitable"
|-
! Boot chain !! Description
|-
| Basic boot || BootROM -> U-Boot SPL -> U-Boot -> Linux
|-
| Trusted boot || BootROM -> TF-A -> U-Boot + OP-TEE -> Linux
|}

== Secure Boot in Basic Boot with BootROM authentication and Verified Boot ==

This Secure Boot implementation does use the the BootROM integrated image authentication to authenticate the U-Boot SPL as FSBL.
Authentication of U-Boot as SSBL by the U-Boot SPL and authentication of the Linux kernel, Device Tree and ramdisk by U-Boot is done using the open source implementation [[#Verified Boot|Verified Boot]].

This also means that everything from U-Boot SPL onwards is platform independent, as we do not rely on hardware specific implementations.

=== Verified Boot ===

Developers of Google's Chromium project worked out a concept for the Verified Boot called Secure Boot mechanism on the basis of the boot loader "Das U-Boot".
They use the existing infrastructure of the FIT images and for the system configuration at runtime via a Device Tree.
The description language for the FIT images was extended by an additional signature node and the Device Tree of the platform was used to store the certificate(s) for the authentication of the images.
The signature node can be used to sign individual subimages as well as combinations of individual subimages in the FIT image.
The tool <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight> takes care the signature creation for the FIT images and the addition of the certificate in a Device Tree.

With Verified Boot, the Device Tree with included public key is integrated into the program image of the stage, which accomplishes the authentication and is thus very similar to the general procedure shown in figure [[Media:Secure Boot Generic en.png|Secure Boot Generic]].
The number of public keys that can be integrated is theoretically unlimited, but they must be distinguishable by name.

==== Technical details of Verified Boot ====

{| class="wikitable"
|-
| '''Name'''
| Verified Boot
|-
| '''Implementierung'''
| Software (Open Source)
|-
| '''Hash algorithms'''
|
* SHA1 (deprecated)<ref name="BSI TR-02102" />
* SHA256
* SHA384
* SHA512
|-
| '''Crypto algorithms
|
* RSA2048 (deprecated as of 2024)<ref name="BSI TR-02102" />
* RSA4096

* ECDSA256 (currently limited to U-Boot SPL)
|-
| '''Number of key pairs'''
| unlimited
|-
|}

==== In-depth references for Verified Boot ====


===== Flatten Image Tree =====
* [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT U-Boot Documentation: doc/uImage.FIT]
* [https://source.denx.de/u-boot/u-boot/-/commit/d5934ad7 U-Boot Commit d5934ad7: "new uImage: Add dual format uImage support framework"]
* ...
* [https://source.denx.de/u-boot/u-boot/-/commit/3310c549 U-Boot Commit d5934ad7: "new uImage: Add new uImage format documentation and examples"]

===== Verified Boot =====

* [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT/signature.txt U-Boot Documentation: doc/uImage.FIT/signature.txt]
* [https://source.denx.de/u-boot/u-boot/-/commit/3e569a6b U-Boot Commit 3e569a6b: "image: Add signing infrastructure"]
* [https://source.denx.de/u-boot/u-boot/-/commit/56518e71 U-Boot Commit 56518e71: "image: Support signing of images"]
* [https://source.denx.de/u-boot/u-boot/-/commit/4d098529 U-Boot Commit 4d098529: "image: Add support for signing of FIT configurations"]

===== ECDSA signature verification =====

<div style="color:red">TODO: Mention ECDSA limitations</div>
Note: This has currently some limitations!


* [https://source.denx.de/u-boot/u-boot/-/commit/928a8be7 U-Boot Commit 928a8be7: "lib: ecdsa: Implement UCLASS_ECDSA verification on target"]
* [https://source.denx.de/u-boot/u-boot/-/commit/ee870859 U-Boot Commit ee870859: "arm: stm32mp1: Implement ECDSA signature verification"]

=== Tutorial: Secure boot from BootROM to Linux with basic boot ===

==== System requirements and needed tools ====

The following table lists all requirements to create the key pairs and build the signed images with embedded public keys.

{| class="wikitable"
|-
! Category !! Description
|-
| '''Host operating system''' ||
* Linux (Debian 9, Ubuntu 18.04 or higher prefered)
|-
| '''Debian packages''' ||
* bison
* device-tree-compiler
* flex
* gcc-arm-linux-gnueabihf (>= gcc 6)
* git
* make
* openssl
|-
| '''STM32 Tools''' ||
* [https://www.st.com/en/development-tools/stm32cubeprog.html STM32CubeProgrammer]
** STM32MP_KeyGen_CLI
** STM32MP_SigningTool_CLI
|}

<div style="color:red">TODO: Should we give host setup instructions?</div>


==== Intended use of the four generated key pairs ====

We've decided to create and use as few certificates as reasonable to ensure a high level of security.
Therefore, we chose a separate key pair for each boot stage and also a separate key pair for image and configuration nodes.
If you're confused about the difference between image and configuration nodes, head over to [[#Flatten Image Tree|Flatten Image Tree]] to refresh your knowledge.
The exact purpose of the four key pairs generated for Verified Boot is described in the following table.

{| class="wikitable"
|-
! File name !! Intended use
|-
| '''fsbl-img''' || Authenticate image nodes of FIT images loaded by U-Boot SPL (U-Boot, Device Tree, firmware)
|-
| '''fsbl-cfg''' || Authenticate config nodes of FIT images loaded by U-Boot SPL (U-Boot + Device Tree + firmware)
|-
| '''ssbl-img''' || Authenticate image nodes of FIT images loaded by U-Boot (Kernel, Device Tree, InitRamFS)
|-
| '''ssbl-cfg''' || Authenticate config nodes of FIT images loaded by U-Boot (Kernel + Device Tree + InitRamFS)
|-
|}

==== Created/Modified files in the U-Boot source for Verified Boot ====

The created or modified files to build U-Boot with Verified Boot on STM32MP15 are described in the following table.

{| class="wikitable"
|-
! File
! Description
|-
| build_signed_uboot.sh
| Shell script that automates the creation of key pairs, the modification of FIT source files and Device Tree's and building of U-Boot SPL and U-Boot.
|-
| board/dhelectronics/dh_stm32mp1/u-boot-dhco?.its
| FIT source files with defined U-Boot image and Device Tree's for DHSOM platforms.
|-
| board/dhelectronics/dh_stm32mp1/linux-dhcom.its
| Dummy FIT source file with defined dummy kernel image and dummy Device Tree for DHSOM platforms.<br>To avoid relying on a built kernel image on a fixed path, we created this dummy, since adding the public keys with <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight> requires a valid FIT source file.
|-
| configs/stm32mp15_dhco?_secure_defconfig
| Example U-Boot defconfig's with enabled <syntaxhighlight lang="shell" inline>CONFIG_FIT_SIGNATURE</syntaxhighlight> and <syntaxhighlight lang="shell" inline>CONFIG_SPL_FIT_SIGNATURE</syntaxhighlight>.
|}

==== Build Verified Boot enabled U-Boot SPL and U-Boot ====

To build the U-Boot SPL and U-Boot images, you need to check out the source code and run a build script that automates everything from key generation to image creation and signing.

===== Checkout source code for Verified Boot =====

<div style="color:red">TODO: Replace my personal GitLab by a public available repository</div>
Checkout the branch <syntaxhighlight lang="shell" inline>v2022.01_dhcom_secure_boot</syntaxhighlight> of my personal GitLab repository with:

<syntaxhighlight lang="shell">
git clone git@dhplgl01:jneuhauser/u-boot.git -b v2022.01_dhcom_secure_boot
</syntaxhighlight>

If you already have a cloned U-Boot source code, you can also fetch it into your existing repository with:

<syntaxhighlight lang="shell">
cd /path/to/u-boot
git remote add jneuhauser git@dhplgl01:jneuhauser/u-boot.git
git fetch jneuhauser
git checkout v2022.01_dhcom_secure_boot
</syntaxhighlight>

===== Run the build script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> =====

The shell script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> included in the U-Boot source performs the following steps.
# Prebuild U-Boat SPL and U-Boat to build the required tools and Device Tree's
# Generate the [[#Intended use of the four generated key pairs|four key pairs]] if not already created
# Generate/Modify FIT image source files for Linux (dummy) and U-Boot
# Add public keys to the built Device Tree's used by U-Boot SPL and U-Boot
# Rebuild U-Boot SPL and U-Boot with new Device Tree's containing the public keys

The script supports the following environment variables to configure the target architecture, the cross compiler, the defconfig, the key algorithm, the key directory, and a key postfix.
{| class="wikitable sortable"
|-
! Name !! Description !! Default
|-
| ARCH || Target architecture for the U-Boot build || arm
|-
| CROSS_COMPILE || Used cross compiler to build U-Boot || arm-linux-gnueabihf-
|-
| DEFCONFIG || Used defconfig for the U-Boot build || stm32mp15_dhcom_secure_defconfig
|-
| KEY_ALGO || Signature algorithm used for Verified Boot || rsa
|-
| KEY_DIR || Directory where the key pairs are stored || ../keys
|-
| KEY_POSTFIX || Postfix which is appended to the key names || -$(date +%F)
|}

To perform the steps mentioned above, you just need to run the shell script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> like below.
In this example, we override the default value for <syntaxhighlight lang="shell" inline>KEY_POSTFIX</syntaxhighlight> with <syntaxhighlight lang="shell" inline>-testing</syntaxhighlight> to append this string to the [[#Intended use of the four generated key pairs|four key file names]].
The script has debug output enabled by default, which should output all the statements in the script itself and the output of the commands used in the script.
If you have any problems with the script, feel free to get in touch with the script author [mailto:jneuhauser@dh-electronics.com Johann Neuhauser] and attach a logfile.

<syntaxhighlight lang="shell">
cd /path/to/u-boot
KEY_POSTFIX="-testing" ./build_signed_uboot.sh | tee build_signed_uboot.log
</syntaxhighlight>

If this process completes without error, there are two boot loader images in the root directory of the U-Boot source.
{| class="wikitable sortable"
|-
! File name !! Stage !! Description
|-
| u-boot-spl.stm32 || FSBL || U-Boot SPL binary with appended Device Tree and prepended STM32 image header<ref name="STM32 image header" />.
|-
| u-boot.itb || SSBL || U-Boot and Device Tree's contained in a signed FIT image.
|}

==== Generate key pair and sign U-Boot SPL for BootROM authentication ====

To sign the U-Boot SPL as SSBL image for authentication with the BootROM we have to use the STM32 tools <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight> and <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight>.

===== Generate key pair with <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight> =====

All STM32MP15 SoC's only support one key pair for authenticating images through the BootROM.
To generate ECDSA key pairs for the STM32MP Secure Boot we are using the tool <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight><ref name="KeyGen_tool" /> to generate a single key pair.
<syntaxhighlight lang="shell">
STM32MP_KeyGen_CLI --absolute-path "$(pwd)" --password 12345678
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Key Generator v2.9.0
-------------------------------------------------------------------

Prime256v1 curve is selected.
AES_256_cbc algorithm is selected for private key encryption
Generating Prime256v1 keys...
Private key PEM file created
Public key PEM file created
public key hash file created
Keys generated successfully.
+ public key: publicKey.pem
+ private key: privateKey.pem
+ public hash key: publicKeyhash.bin
</syntaxhighlight>

===== Sign U-Boot SPL with <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight> =====

To add the public key and the image signature to our built U-Boot SPL binary with STM32 image header, we are using the tool <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight><ref name="Signing_tool" /> to update the existing STM32 image header of <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> with the required details.
<syntaxhighlight lang="shell">
STM32MP_SigningTool_CLI --binary-image /path/to/u-boot/u-boot-spl.stm32 --public-key publicKey.pem --private-key privateKey.pem --password 12345678 --output /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Signing Tool v2.9.0
-------------------------------------------------------------------

Prime256v1 curve is selected.
Header version 1 preparation ...
Reading Private Key File...
ECDSA signature generated.
Signature verification: SUCCESS
The Signed image file generated successfully: /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>

You can check the STM32 image header details with:
<syntaxhighlight lang="shell">
STM32MP_SigningTool_CLI --dump-header /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Signing Tool v2.9.0
-------------------------------------------------------------------

Header description:

Magic: 0x53544d32
Signature: c8 30 a0 62 2d 6d 4e 1b b9 f7 fe 38 27 65 e0 44 f0 f5 9d e6 8a a6 02 cb 74 52 26 9c 1e e9 07 17
1a c7 da 8e 96 fa 82 d3 b1 dc d5 3a 05 0e 87 83 94 4d 47 ad 17 07 88 0d b5 ae 2e 38 1d 90 22 ad
Checksum: 0xa8ca85
Header version: 0x10000
Size: 0x22dec
Load address: 0x2ffc2500
Entry point: 0x2ffc2500
Image version: 0x0
Option flags: 0x0
ECDSA Algo: 0x1
ECDSA pub key: 3b 71 8e 59 f1 ee 4c a8 4b 72 5f 4a 1c 63 8b 6e b8 01 ec 1a 3f 8c 98 2f d2 1d 77 f9 09 10 8f 04
30 da 5c 3a 24 53 0d 71 93 f0 a5 d9 c9 a7 27 b4 5f a5 c4 4d 55 8b 7a 25 e3 03 ef ca 87 ff 04 25
Binary type: 0x0
</syntaxhighlight>
The difference to an unsigned STM32 image header is that the values for "Signature" and "ECDSA pub key" are not all zeros and that "Option flags" is 0x0 for enabled signature verification instead of 0x1 for disabled signature verification.

==== Write U-Boot SPL and U-Boot to your boot media ====

The first step to verify that the built U-Boot SPL and U-Boot works as expected is to program both images to your boot media.
Depending on the boot configuration, your DHSOM will boot from the module's SPI-NOR flash, from the module's or baseboard's eMMC or from an SD card.
The boot configuration is always defined by the boot pins by default, because the boot pins have no alternative function on the STM32MP15 SoC's.

<div style="color:red">TODO: How can a user determine the used boot media?</div>
<div style="color:red">TODO: How to enforce boot media on Secure Boot enabled devices?</div>

===== Write U-Boot SPL and U-Boot to the SPI-NOR flash of the SoM =====

The following '''commands for the U-Boot Shell''' calculate some addresses based on the image offsets expected by the BootROM, load the required images from SD card or via TFTP into memory and finally write the prepared memory into the SPI-NOR flash on the SoM.

Prepare for loading <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> into memory:
<syntaxhighlight lang="shell">
mw.b ${loadaddr} 0xff 0x200000
setexpr fsbl1addr ${loadaddr} + 0x0
setexpr fsbl2addr ${loadaddr} + 0x40000
setexpr ssbl1addr ${loadaddr} + 0x80000
</syntaxhighlight>

Load <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> from SD card:
<syntaxhighlight lang="shell">
load mmc 0:4 ${fsbl1addr} u-boot-spl.stm32
load mmc 0:4 ${fsbl2addr} u-boot-spl.stm32
load mmc 0:4 ${ssbl1addr} u-boot.itb
</syntaxhighlight>

Load <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> from tftp server:
<syntaxhighlight lang="shell">
setenv serverip 10.20.30.1
setenv ipaddr 10.20.30.100
setenv netmask 255.255.255.0
tftp ${fsbl1addr} ${serverip}:u-boot-spl.stm32
tftp ${fsbl2addr} ${serverip}:u-boot-spl.stm32
tftp ${ssbl1addr} ${serverip}:u-boot.itb
</syntaxhighlight>

Check for magic numbers of expected image headers and conditionally program the SPI-NOR flash:
<syntaxhighlight lang="shell">
if itest *${fsbl1addr} == 0x324d5453 && itest *${fsbl2addr} == 0x324d5453 && itest *${ssbl1addr} == 0xedfe0dd0; then
sf probe && sf update ${loadaddr} 0 0x200000
fi
</syntaxhighlight>

===== Write U-Boot SPL and U-Boot to an SD card =====

<div style="color:red">TODO:</div>


===== Write U-Boot SPL and U-Boot to the eMMC =====

<div style="color:red">TODO:</div>


==== Enroll, test and enforce BootROM image authentication ====

To enroll, test and enforce image authentication by the BootROM you need to program the PKH into the OTP of the STM32MP15 SoC.
The <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> file that you created in the [[#Generate key pair with STM32MP_KeyGen_CLI|Generate key pair with STM32MP_KeyGen_CLI]] step contains the PKH in binary format for use with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> U-Boot command.
If the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command does fail or is not available on the target U-Boot, you can also write the PKH manually with the more generic <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command into the OTP.

===== Program public key hash to eFuses =====

The following '''commands for the U-Boot Shell''' load the file <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> into memory and program the contained PKH to the OTP of the STM32MP15 SoC.
The used command <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> writes and locks the words of the OTP automatically without knowing anything about the OTP layout/addresses.
If this fails or the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command is not available, you can also write and lock the OTP with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command

====== Program <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> into OTP with <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command ======

Load <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> by SD card:
<syntaxhighlight lang="shell">
load mmc 0:4 ${loadaddr} publicKeyhash.bin
</syntaxhighlight>

Or load <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> by TFTP:
<syntaxhighlight lang="shell">
setenv serverip 10.20.30.1
setenv ipaddr 10.20.30.100
setenv netmask 255.255.255.0
tftp ${loadaddr} ${serverip}:publicKeyhash.bin
</syntaxhighlight>

Show the contents of <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight>:
<syntaxhighlight lang="shell">
stm32key read ${loadaddr}
</syntaxhighlight>
<syntaxhighlight lang="console">
Read KEY at 0xc2000000
OTP value 24: 4e31bbcd
OTP value 25: 51e827dd
OTP value 26: 3511f521
OTP value 27: fd9c11a2
OTP value 28: 5b997b82
OTP value 29: 8150adc5
OTP value 30: a9c68fa9
OTP value 31: 72a3ba74
</syntaxhighlight>

Write the contents of <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> to OTP with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command:
<syntaxhighlight lang="shell">
stm32key fuse ${loadaddr}
</syntaxhighlight>
<syntaxhighlight lang="console">
TODO: Add output
</syntaxhighlight>

====== Program PKH manually into OTP with <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command ======

Generate fuse command with hexdump from file <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> on linux host:
<div style="color:red">Warning: Do not use the example output! Only use your unique values for programming the PKH in the OTP!</div>
<syntaxhighlight lang="shell">
echo fuse prog -y 0 0x18 $(hexdump -e '/4 "0x"' -e '/1 "%x"' -e '" "' /path/to/publicKeyhash.bin)
</syntaxhighlight>
<syntaxhighlight lang="console">
fuse prog -y 0 0x18 0x4e31bbcd 0x51e827dd 0x3511f521 0xfd9c11a2 0x5b997b82 0x8150adc5 0xa9c68fa9 0x72a3ba74
</syntaxhighlight>

Write the PKH into OTP manually with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<div style="color:red">Warning: Do not use the example command! Only use your unique values for programming the PKH in the OTP!</div>
<syntaxhighlight lang="shell">
fuse prog -y 0 0x18 0x4e31bbcd 0x51e827dd 0x3511f521 0xfd9c11a2 0x5b997b82 0x8150adc5 0xa9c68fa9 0x72a3ba74
</syntaxhighlight>

Lock the related OTP words manually with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<syntaxhighlight lang="shell">
fuse prog -y 0 0x10000018 1 1 1 1 1 1 1 1
</syntaxhighlight>

===== Test BootROM image authentication =====

To verify the image authentication by the BootROM with the programmed PKH and the programmed signed images, you must reboot your device.

On the third line of the U-Boot SPL output, check the BootROM authentication status.
The status output should look like this: <syntaxhighlight lang="console" inline>Bootrom authentication: succeeded</syntaxhighlight>.
Note the <syntaxhighlight lang="console" inline>succeeded</syntaxhighlight> status for successful authentication of the U-Boot SPL image by the BootROM.

The following output shows successful authentication of the U-Boot-SPL image in line 3, as well as successful authentication of the used configuration in line 7 and the U-Boot and Device Tree subimages in lines 8 and 9 of the U-Boot-FIT image.
<syntaxhighlight lang="console" line highlight="3,7-9">
U-Boot SPL 2022.01-00012-g6c5892c90c28 (Feb 16 2022 - 11:11:16 +0100)
Model: STMicroelectronics STM32MP15xx DHCOM Premium Developer Kit (2)
Bootrom authentication: succeeded
Code: SoM:rev=1,ddr3=3 Board:rev=0
RAM: DDR3L 32bits 2x4Gb 533MHz
Trying to boot from SPI
## Checking hash(es) for config config-2 ... sha256,rsa4096:fsbl-cfg-2022-02-16+ OK
## Checking hash(es) for Image uboot ... sha256,rsa4096:fsbl-img-2022-02-16+ sha256+ OK
## Checking hash(es) for Image fdt-1 ... sha256,rsa4096:fsbl-img-2022-02-16+ sha256+ OK
</syntaxhighlight>

===== Enforce BootROM image authentication =====

Without any further changes, the BootROM is able to perform authentication of the FSBL image, but unauthenticated images can still be used and executed.
The device is still open, let's see this as a kind of test mode to check if the PKH is set correctly.

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

The 6th bit in the 1st word of the OTP is responsible that the BootROM only accepts signed images.
Burning this bit enforces authentication of images by the BootROM and unsigned binaries are no longer supported on the target device.

To program this bit, the U-Boot Shell can be used with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command or with the more general <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command.

With usage of the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command:
<div style="color:red">Warning: After running the following command, your device will only be able to boot signed images!</div>
<syntaxhighlight lang="shell">
stm32key close
</syntaxhighlight>

Or with usage of the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<div style="color:red">Warning: After running the following command, your device will only be able to boot signed images!</div>
<syntaxhighlight lang="shell">
fuse prog 0 0x0 0x40
</syntaxhighlight>

== Secure Boot in Trusted Boot with BootROM authentication, TF-A and OP-TEE ==

<div style="color:red">TODO:</div>
# Add support for STM32MP15 DHCOM in <ref name="TF-A" />
# Add support for STM32MP15 DHCOM in <ref name="OP-TEE/optee_os" />
# Create stm32mp15_dhcom_trusted_defconfig???
# Integrate STM32MP15 DHCOM into <ref name="OP-TEE/build" />

== References ==

<references>
<ref name="UEFI specification">[http://www.uefi.org/specifications http://www.uefi.org/specifications]</ref>
<ref name="Basic Boot">[https://source.denx.de/u-boot/u-boot/-/blob/master/configs/stm32mp15_basic_defconfig U-Boot Source stm32mp15_basic_defconfig]</ref>
<ref name="Trusted Boot">[https://source.denx.de/u-boot/u-boot/-/blob/master/configs/stm32mp15_trusted_defconfig U-Boot Source stm32mp15_trusted_defconfig]</ref>
<ref name="BSI TR-02102">[https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.pdf BSI - Technische Richtlinie, "Kryptographische Algorithmen und Schlüssellängen", BSI TR-02102-1]</ref>
<ref name="STM32 image header">[https://wiki.st.com/stm32mpu/wiki/STM32_header_for_binary_files STM32 header for binary files]</ref>
<ref name="KeyGen_tool">[https://wiki.st.com/stm32mpu/wiki/KeyGen_tool STM32MP KeyGen tool]</ref>
<ref name="Signing_tool">[https://wiki.st.com/stm32mpu/wiki/Signing_tool STM32MP Signing tool]</ref>
<ref name="TF-A">[https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/ Trusted Firmware-A (TF-A)]</ref>
<ref name="OP-TEE/optee_os">[https://github.com/OP-TEE/optee_os OP-TEE Trusted OS]</ref>
<ref name="OP-TEE/build">[https://github.com/OP-TEE/build Makefiles to use OP-TEE on various platforms]</ref>
</references>

DHCOM STM32MP15 Secure Boot

2022-03-22T09:34:20Z

Dkierner: Shorten title of /* What does Secure Boot mean? */

<div class="toclimit-3">__TOC__</div>

== Introduction ==

=== Abbreviations ===

{| class="wikitable sortable"
|-
! Abbreviation !! Description
|-
| BSI || Bundesamt für Sicherheit in der Informationstechnik
|-
| CoM || Computer on module
|-
| FIT || Flattened Image Tree
|-
| FSBL || Fist Stage Bootloader (TF-A or U-Boot SPL)
|-
| OTP || One Time Programmable (eFuses)
|-
| OP-TEE || Open Portable Trusted Execution Environment
|-
| PKH || Public Key Hash
|-
| ROM || Read-Only Memory
|-
| RSA || Rivest, Shamir und Adleman (asynchronous encryption)
|-
| SHA || Secure Hash Algorithm
|-
| SoC || System on chip
|-
| SoM || System on module
|-
| SSBL || Second Stage Bootloader (U-Boot)
|-
| TF-A || Trusted Firmware A
|}

=== Secure Boot ===

The term Secure Boot originally comes from the UEFI specification<ref name="UEFI specification" /> and describes a secure boot process in which only signed software is loaded and executed during the boot process.

Secure Boot is a necessary cornerstone for enforcing security mechanisms in a trusted computing environment.
Enforcing the execution of signed software only during the boot process, as long as the chain of trust is secure, can guarantee that said software is free from tampering, as any manipulation will invalidate the software's signature and prevent the software from being executed.

[[File:Secure Boot Generic en.png|600px|Secure Boot Generic]]

The figure [[Media:Secure Boot Generic en.png|Secure Boot Generic]] shows an example of a secure boot process that leads to a reset in the event of an error in the signature check. Each stage uses the certificate and signature to check the origin and integrity of the next stage. On success, the next stage is executed, and in the event of an error, this always leads to a defined error state. In the simplest case, the certificates are integrated into the binary image of the previous stage.

Program code and certificate need to be trustworthy and therefore protected against tampering in each stage, otherwise the secure boot chain can be compromised. Except for the first stage, all binary images are protected against third-party tampering by the signature. As this is practically impossible for the first stage, manipulation protection has to be enforced by hardware measures to make said stage immutable, with the first stage's program code and the verification certificate for the second stage being stored in read-only memory (ROM).

=== Basic and trusted boot in the context of Secure Boot ===

When booting Linux on the STM32MP1 SoC with U-Boot SPL and U-Boot only, STM speaks of "Basic Boot"<ref name="Basic Boot" />.
However, if Linux is booted with a combination of TF-A, U-Boot and OP-TEE, STM refers to this as "Trusted Boot"<ref name="Trusted Boot" />.

{| class="wikitable"
|-
! Boot chain !! Description
|-
| Basic boot || BootROM -> U-Boot SPL -> U-Boot -> Linux
|-
| Trusted boot || BootROM -> TF-A -> U-Boot + OP-TEE -> Linux
|}

== Secure Boot in Basic Boot with BootROM authentication and Verified Boot ==

This Secure Boot implementation does use the the BootROM integrated image authentication to authenticate the U-Boot SPL as FSBL.
Authentication of U-Boot as SSBL by the U-Boot SPL and authentication of the Linux kernel, Device Tree and ramdisk by U-Boot is done using the open source implementation [[#What is meant by Verified Boot?|Verified Boot]].

This also means that everything from U-Boot SPL onwards is platform independent, as we do not rely on hardware specific implementations.

=== Verified Boot ===

Developers of Google's Chromium project worked out a concept for the Verified Boot called Secure Boot mechanism on the basis of the boot loader "Das U-Boot".
They use the existing infrastructure of the FIT images and for the system configuration at runtime via a Device Tree.
The description language for the FIT images was extended by an additional signature node and the Device Tree of the platform was used to store the certificate(s) for the authentication of the images.
The signature node can be used to sign individual subimages as well as combinations of individual subimages in the FIT image.
The tool <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight> takes care the signature creation for the FIT images and the addition of the certificate in a Device Tree.

With Verified Boot, the Device Tree with included public key is integrated into the program image of the stage, which accomplishes the authentication and is thus very similar to the general procedure shown in figure [[Media:Secure Boot Generic en.png|Secure Boot Generic]].
The number of public keys that can be integrated is theoretically unlimited, but they must be distinguishable by name.

==== Technical details of Verified Boot ====

{| class="wikitable"
|-
| '''Name'''
| Verified Boot
|-
| '''Implementierung'''
| Software (Open Source)
|-
| '''Hash algorithms'''
|
* SHA1 (deprecated)<ref name="BSI TR-02102" />
* SHA256
* SHA384
* SHA512
|-
| '''Crypto algorithms
|
* RSA2048 (deprecated as of 2024)<ref name="BSI TR-02102" />
* RSA4096

* ECDSA256 (currently limited to U-Boot SPL)
|-
| '''Number of key pairs'''
| unlimited
|-
|}

==== In-depth references for Verified Boot ====


===== Flatten Image Tree =====
* [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT U-Boot Documentation: doc/uImage.FIT]
* [https://source.denx.de/u-boot/u-boot/-/commit/d5934ad7 U-Boot Commit d5934ad7: "new uImage: Add dual format uImage support framework"]
* ...
* [https://source.denx.de/u-boot/u-boot/-/commit/3310c549 U-Boot Commit d5934ad7: "new uImage: Add new uImage format documentation and examples"]

===== Verified Boot =====

* [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT/signature.txt U-Boot Documentation: doc/uImage.FIT/signature.txt]
* [https://source.denx.de/u-boot/u-boot/-/commit/3e569a6b U-Boot Commit 3e569a6b: "image: Add signing infrastructure"]
* [https://source.denx.de/u-boot/u-boot/-/commit/56518e71 U-Boot Commit 56518e71: "image: Support signing of images"]
* [https://source.denx.de/u-boot/u-boot/-/commit/4d098529 U-Boot Commit 4d098529: "image: Add support for signing of FIT configurations"]

===== ECDSA signature verification =====

<div style="color:red">TODO: Mention ECDSA limitations</div>
Note: This has currently some limitations!


* [https://source.denx.de/u-boot/u-boot/-/commit/928a8be7 U-Boot Commit 928a8be7: "lib: ecdsa: Implement UCLASS_ECDSA verification on target"]
* [https://source.denx.de/u-boot/u-boot/-/commit/ee870859 U-Boot Commit ee870859: "arm: stm32mp1: Implement ECDSA signature verification"]

=== Tutorial: Secure boot from BootROM to Linux with basic boot ===

==== System requirements and needed tools ====

The following table lists all requirements to create the key pairs and build the signed images with embedded public keys.

{| class="wikitable"
|-
! Category !! Description
|-
| '''Host operating system''' ||
* Linux (Debian 9, Ubuntu 18.04 or higher prefered)
|-
| '''Debian packages''' ||
* bison
* device-tree-compiler
* flex
* gcc-arm-linux-gnueabihf (>= gcc 6)
* git
* make
* openssl
|-
| '''STM32 Tools''' ||
* [https://www.st.com/en/development-tools/stm32cubeprog.html STM32CubeProgrammer]
** STM32MP_KeyGen_CLI
** STM32MP_SigningTool_CLI
|}

<div style="color:red">TODO: Should we give host setup instructions?</div>


==== Intended use of the four generated key pairs ====

We've decided to create and use as few certificates as reasonable to ensure a high level of security.
Therefore, we chose a separate key pair for each boot stage and also a separate key pair for image and configuration nodes.
If you're confused about the difference between image and configuration nodes, head over to [[#Flatten Image Tree|Flatten Image Tree]] to refresh your knowledge.
The exact purpose of the four key pairs generated for Verified Boot is described in the following table.

{| class="wikitable"
|-
! File name !! Intended use
|-
| '''fsbl-img''' || Authenticate image nodes of FIT images loaded by U-Boot SPL (U-Boot, Device Tree, firmware)
|-
| '''fsbl-cfg''' || Authenticate config nodes of FIT images loaded by U-Boot SPL (U-Boot + Device Tree + firmware)
|-
| '''ssbl-img''' || Authenticate image nodes of FIT images loaded by U-Boot (Kernel, Device Tree, InitRamFS)
|-
| '''ssbl-cfg''' || Authenticate config nodes of FIT images loaded by U-Boot (Kernel + Device Tree + InitRamFS)
|-
|}

==== Created/Modified files in the U-Boot source for Verified Boot ====

The created or modified files to build U-Boot with Verified Boot on STM32MP15 are described in the following table.

{| class="wikitable"
|-
! File
! Description
|-
| build_signed_uboot.sh
| Shell script that automates the creation of key pairs, the modification of FIT source files and Device Tree's and building of U-Boot SPL and U-Boot.
|-
| board/dhelectronics/dh_stm32mp1/u-boot-dhco?.its
| FIT source files with defined U-Boot image and Device Tree's for DHSOM platforms.
|-
| board/dhelectronics/dh_stm32mp1/linux-dhcom.its
| Dummy FIT source file with defined dummy kernel image and dummy Device Tree for DHSOM platforms.<br>To avoid relying on a built kernel image on a fixed path, we created this dummy, since adding the public keys with <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight> requires a valid FIT source file.
|-
| configs/stm32mp15_dhco?_secure_defconfig
| Example U-Boot defconfig's with enabled <syntaxhighlight lang="shell" inline>CONFIG_FIT_SIGNATURE</syntaxhighlight> and <syntaxhighlight lang="shell" inline>CONFIG_SPL_FIT_SIGNATURE</syntaxhighlight>.
|}

==== Build Verified Boot enabled U-Boot SPL and U-Boot ====

To build the U-Boot SPL and U-Boot images, you need to check out the source code and run a build script that automates everything from key generation to image creation and signing.

===== Checkout source code for Verified Boot =====

<div style="color:red">TODO: Replace my personal GitLab by a public available repository</div>
Checkout the branch <syntaxhighlight lang="shell" inline>v2022.01_dhcom_secure_boot</syntaxhighlight> of my personal GitLab repository with:

<syntaxhighlight lang="shell">
git clone git@dhplgl01:jneuhauser/u-boot.git -b v2022.01_dhcom_secure_boot
</syntaxhighlight>

If you already have a cloned U-Boot source code, you can also fetch it into your existing repository with:

<syntaxhighlight lang="shell">
cd /path/to/u-boot
git remote add jneuhauser git@dhplgl01:jneuhauser/u-boot.git
git fetch jneuhauser
git checkout v2022.01_dhcom_secure_boot
</syntaxhighlight>

===== Run the build script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> =====

The shell script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> included in the U-Boot source performs the following steps.
# Prebuild U-Boat SPL and U-Boat to build the required tools and Device Tree's
# Generate the [[#Intended use of the four generated key pairs|four key pairs]] if not already created
# Generate/Modify FIT image source files for Linux (dummy) and U-Boot
# Add public keys to the built Device Tree's used by U-Boot SPL and U-Boot
# Rebuild U-Boot SPL and U-Boot with new Device Tree's containing the public keys

The script supports the following environment variables to configure the target architecture, the cross compiler, the defconfig, the key algorithm, the key directory, and a key postfix.
{| class="wikitable sortable"
|-
! Name !! Description !! Default
|-
| ARCH || Target architecture for the U-Boot build || arm
|-
| CROSS_COMPILE || Used cross compiler to build U-Boot || arm-linux-gnueabihf-
|-
| DEFCONFIG || Used defconfig for the U-Boot build || stm32mp15_dhcom_secure_defconfig
|-
| KEY_ALGO || Signature algorithm used for Verified Boot || rsa
|-
| KEY_DIR || Directory where the key pairs are stored || ../keys
|-
| KEY_POSTFIX || Postfix which is appended to the key names || -$(date +%F)
|}

To perform the steps mentioned above, you just need to run the shell script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> like below.
In this example, we override the default value for <syntaxhighlight lang="shell" inline>KEY_POSTFIX</syntaxhighlight> with <syntaxhighlight lang="shell" inline>-testing</syntaxhighlight> to append this string to the [[#Intended use of the four generated key pairs|four key file names]].
The script has debug output enabled by default, which should output all the statements in the script itself and the output of the commands used in the script.
If you have any problems with the script, feel free to get in touch with the script author [mailto:jneuhauser@dh-electronics.com Johann Neuhauser] and attach a logfile.

<syntaxhighlight lang="shell">
cd /path/to/u-boot
KEY_POSTFIX="-testing" ./build_signed_uboot.sh | tee build_signed_uboot.log
</syntaxhighlight>

If this process completes without error, there are two boot loader images in the root directory of the U-Boot source.
{| class="wikitable sortable"
|-
! File name !! Stage !! Description
|-
| u-boot-spl.stm32 || FSBL || U-Boot SPL binary with appended Device Tree and prepended STM32 image header<ref name="STM32 image header" />.
|-
| u-boot.itb || SSBL || U-Boot and Device Tree's contained in a signed FIT image.
|}

==== Generate key pair and sign U-Boot SPL for BootROM authentication ====

To sign the U-Boot SPL as SSBL image for authentication with the BootROM we have to use the STM32 tools <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight> and <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight>.

===== Generate key pair with <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight> =====

All STM32MP15 SoC's only support one key pair for authenticating images through the BootROM.
To generate ECDSA key pairs for the STM32MP Secure Boot we are using the tool <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight><ref name="KeyGen_tool" /> to generate a single key pair.
<syntaxhighlight lang="shell">
STM32MP_KeyGen_CLI --absolute-path "$(pwd)" --password 12345678
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Key Generator v2.9.0
-------------------------------------------------------------------

Prime256v1 curve is selected.
AES_256_cbc algorithm is selected for private key encryption
Generating Prime256v1 keys...
Private key PEM file created
Public key PEM file created
public key hash file created
Keys generated successfully.
+ public key: publicKey.pem
+ private key: privateKey.pem
+ public hash key: publicKeyhash.bin
</syntaxhighlight>

===== Sign U-Boot SPL with <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight> =====

To add the public key and the image signature to our built U-Boot SPL binary with STM32 image header, we are using the tool <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight><ref name="Signing_tool" /> to update the existing STM32 image header of <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> with the required details.
<syntaxhighlight lang="shell">
STM32MP_SigningTool_CLI --binary-image /path/to/u-boot/u-boot-spl.stm32 --public-key publicKey.pem --private-key privateKey.pem --password 12345678 --output /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Signing Tool v2.9.0
-------------------------------------------------------------------

Prime256v1 curve is selected.
Header version 1 preparation ...
Reading Private Key File...
ECDSA signature generated.
Signature verification: SUCCESS
The Signed image file generated successfully: /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>

You can check the STM32 image header details with:
<syntaxhighlight lang="shell">
STM32MP_SigningTool_CLI --dump-header /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Signing Tool v2.9.0
-------------------------------------------------------------------

Header description:

Magic: 0x53544d32
Signature: c8 30 a0 62 2d 6d 4e 1b b9 f7 fe 38 27 65 e0 44 f0 f5 9d e6 8a a6 02 cb 74 52 26 9c 1e e9 07 17
1a c7 da 8e 96 fa 82 d3 b1 dc d5 3a 05 0e 87 83 94 4d 47 ad 17 07 88 0d b5 ae 2e 38 1d 90 22 ad
Checksum: 0xa8ca85
Header version: 0x10000
Size: 0x22dec
Load address: 0x2ffc2500
Entry point: 0x2ffc2500
Image version: 0x0
Option flags: 0x0
ECDSA Algo: 0x1
ECDSA pub key: 3b 71 8e 59 f1 ee 4c a8 4b 72 5f 4a 1c 63 8b 6e b8 01 ec 1a 3f 8c 98 2f d2 1d 77 f9 09 10 8f 04
30 da 5c 3a 24 53 0d 71 93 f0 a5 d9 c9 a7 27 b4 5f a5 c4 4d 55 8b 7a 25 e3 03 ef ca 87 ff 04 25
Binary type: 0x0
</syntaxhighlight>
The difference to an unsigned STM32 image header is that the values for "Signature" and "ECDSA pub key" are not all zeros and that "Option flags" is 0x0 for enabled signature verification instead of 0x1 for disabled signature verification.

==== Write U-Boot SPL and U-Boot to your boot media ====

The first step to verify that the built U-Boot SPL and U-Boot works as expected is to program both images to your boot media.
Depending on the boot configuration, your DHSOM will boot from the module's SPI-NOR flash, from the module's or baseboard's eMMC or from an SD card.
The boot configuration is always defined by the boot pins by default, because the boot pins have no alternative function on the STM32MP15 SoC's.

<div style="color:red">TODO: How can a user determine the used boot media?</div>
<div style="color:red">TODO: How to enforce boot media on Secure Boot enabled devices?</div>

===== Write U-Boot SPL and U-Boot to the SPI-NOR flash of the SoM =====

The following '''commands for the U-Boot Shell''' calculate some addresses based on the image offsets expected by the BootROM, load the required images from SD card or via TFTP into memory and finally write the prepared memory into the SPI-NOR flash on the SoM.

Prepare for loading <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> into memory:
<syntaxhighlight lang="shell">
mw.b ${loadaddr} 0xff 0x200000
setexpr fsbl1addr ${loadaddr} + 0x0
setexpr fsbl2addr ${loadaddr} + 0x40000
setexpr ssbl1addr ${loadaddr} + 0x80000
</syntaxhighlight>

Load <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> from SD card:
<syntaxhighlight lang="shell">
load mmc 0:4 ${fsbl1addr} u-boot-spl.stm32
load mmc 0:4 ${fsbl2addr} u-boot-spl.stm32
load mmc 0:4 ${ssbl1addr} u-boot.itb
</syntaxhighlight>

Load <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> from tftp server:
<syntaxhighlight lang="shell">
setenv serverip 10.20.30.1
setenv ipaddr 10.20.30.100
setenv netmask 255.255.255.0
tftp ${fsbl1addr} ${serverip}:u-boot-spl.stm32
tftp ${fsbl2addr} ${serverip}:u-boot-spl.stm32
tftp ${ssbl1addr} ${serverip}:u-boot.itb
</syntaxhighlight>

Check for magic numbers of expected image headers and conditionally program the SPI-NOR flash:
<syntaxhighlight lang="shell">
if itest *${fsbl1addr} == 0x324d5453 && itest *${fsbl2addr} == 0x324d5453 && itest *${ssbl1addr} == 0xedfe0dd0; then
sf probe && sf update ${loadaddr} 0 0x200000
fi
</syntaxhighlight>

===== Write U-Boot SPL and U-Boot to an SD card =====

<div style="color:red">TODO:</div>


===== Write U-Boot SPL and U-Boot to the eMMC =====

<div style="color:red">TODO:</div>


==== Enroll, test and enforce BootROM image authentication ====

To enroll, test and enforce image authentication by the BootROM you need to program the PKH into the OTP of the STM32MP15 SoC.
The <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> file that you created in the [[#Generate key pair with STM32MP_KeyGen_CLI|Generate key pair with STM32MP_KeyGen_CLI]] step contains the PKH in binary format for use with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> U-Boot command.
If the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command does fail or is not available on the target U-Boot, you can also write the PKH manually with the more generic <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command into the OTP.

===== Program public key hash to eFuses =====

The following '''commands for the U-Boot Shell''' load the file <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> into memory and program the contained PKH to the OTP of the STM32MP15 SoC.
The used command <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> writes and locks the words of the OTP automatically without knowing anything about the OTP layout/addresses.
If this fails or the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command is not available, you can also write and lock the OTP with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command

====== Program <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> into OTP with <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command ======

Load <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> by SD card:
<syntaxhighlight lang="shell">
load mmc 0:4 ${loadaddr} publicKeyhash.bin
</syntaxhighlight>

Or load <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> by TFTP:
<syntaxhighlight lang="shell">
setenv serverip 10.20.30.1
setenv ipaddr 10.20.30.100
setenv netmask 255.255.255.0
tftp ${loadaddr} ${serverip}:publicKeyhash.bin
</syntaxhighlight>

Show the contents of <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight>:
<syntaxhighlight lang="shell">
stm32key read ${loadaddr}
</syntaxhighlight>
<syntaxhighlight lang="console">
Read KEY at 0xc2000000
OTP value 24: 4e31bbcd
OTP value 25: 51e827dd
OTP value 26: 3511f521
OTP value 27: fd9c11a2
OTP value 28: 5b997b82
OTP value 29: 8150adc5
OTP value 30: a9c68fa9
OTP value 31: 72a3ba74
</syntaxhighlight>

Write the contents of <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> to OTP with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command:
<syntaxhighlight lang="shell">
stm32key fuse ${loadaddr}
</syntaxhighlight>
<syntaxhighlight lang="console">
TODO: Add output
</syntaxhighlight>

====== Program PKH manually into OTP with <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command ======

Generate fuse command with hexdump from file <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> on linux host:
<div style="color:red">Warning: Do not use the example output! Only use your unique values for programming the PKH in the OTP!</div>
<syntaxhighlight lang="shell">
echo fuse prog -y 0 0x18 $(hexdump -e '/4 "0x"' -e '/1 "%x"' -e '" "' /path/to/publicKeyhash.bin)
</syntaxhighlight>
<syntaxhighlight lang="console">
fuse prog -y 0 0x18 0x4e31bbcd 0x51e827dd 0x3511f521 0xfd9c11a2 0x5b997b82 0x8150adc5 0xa9c68fa9 0x72a3ba74
</syntaxhighlight>

Write the PKH into OTP manually with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<div style="color:red">Warning: Do not use the example command! Only use your unique values for programming the PKH in the OTP!</div>
<syntaxhighlight lang="shell">
fuse prog -y 0 0x18 0x4e31bbcd 0x51e827dd 0x3511f521 0xfd9c11a2 0x5b997b82 0x8150adc5 0xa9c68fa9 0x72a3ba74
</syntaxhighlight>

Lock the related OTP words manually with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<syntaxhighlight lang="shell">
fuse prog -y 0 0x10000018 1 1 1 1 1 1 1 1
</syntaxhighlight>

===== Test BootROM image authentication =====

To verify the image authentication by the BootROM with the programmed PKH and the programmed signed images, you must reboot your device.

On the third line of the U-Boot SPL output, check the BootROM authentication status.
The status output should look like this: <syntaxhighlight lang="console" inline>Bootrom authentication: succeeded</syntaxhighlight>.
Note the <syntaxhighlight lang="console" inline>succeeded</syntaxhighlight> status for successful authentication of the U-Boot SPL image by the BootROM.

The following output shows successful authentication of the U-Boot-SPL image in line 3, as well as successful authentication of the used configuration in line 7 and the U-Boot and Device Tree subimages in lines 8 and 9 of the U-Boot-FIT image.
<syntaxhighlight lang="console" line highlight="3,7-9">
U-Boot SPL 2022.01-00012-g6c5892c90c28 (Feb 16 2022 - 11:11:16 +0100)
Model: STMicroelectronics STM32MP15xx DHCOM Premium Developer Kit (2)
Bootrom authentication: succeeded
Code: SoM:rev=1,ddr3=3 Board:rev=0
RAM: DDR3L 32bits 2x4Gb 533MHz
Trying to boot from SPI
## Checking hash(es) for config config-2 ... sha256,rsa4096:fsbl-cfg-2022-02-16+ OK
## Checking hash(es) for Image uboot ... sha256,rsa4096:fsbl-img-2022-02-16+ sha256+ OK
## Checking hash(es) for Image fdt-1 ... sha256,rsa4096:fsbl-img-2022-02-16+ sha256+ OK
</syntaxhighlight>

===== Enforce BootROM image authentication =====

Without any further changes, the BootROM is able to perform authentication of the FSBL image, but unauthenticated images can still be used and executed.
The device is still open, let's see this as a kind of test mode to check if the PKH is set correctly.

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

The 6th bit in the 1st word of the OTP is responsible that the BootROM only accepts signed images.
Burning this bit enforces authentication of images by the BootROM and unsigned binaries are no longer supported on the target device.

To program this bit, the U-Boot Shell can be used with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command or with the more general <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command.

With usage of the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command:
<div style="color:red">Warning: After running the following command, your device will only be able to boot signed images!</div>
<syntaxhighlight lang="shell">
stm32key close
</syntaxhighlight>

Or with usage of the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<div style="color:red">Warning: After running the following command, your device will only be able to boot signed images!</div>
<syntaxhighlight lang="shell">
fuse prog 0 0x0 0x40
</syntaxhighlight>

== Secure Boot in Trusted Boot with BootROM authentication, TF-A and OP-TEE ==

<div style="color:red">TODO:</div>
# Add support for STM32MP15 DHCOM in <ref name="TF-A" />
# Add support for STM32MP15 DHCOM in <ref name="OP-TEE/optee_os" />
# Create stm32mp15_dhcom_trusted_defconfig???
# Integrate STM32MP15 DHCOM into <ref name="OP-TEE/build" />

== References ==

<references>
<ref name="UEFI specification">[http://www.uefi.org/specifications http://www.uefi.org/specifications]</ref>
<ref name="Basic Boot">[https://source.denx.de/u-boot/u-boot/-/blob/master/configs/stm32mp15_basic_defconfig U-Boot Source stm32mp15_basic_defconfig]</ref>
<ref name="Trusted Boot">[https://source.denx.de/u-boot/u-boot/-/blob/master/configs/stm32mp15_trusted_defconfig U-Boot Source stm32mp15_trusted_defconfig]</ref>
<ref name="BSI TR-02102">[https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.pdf BSI - Technische Richtlinie, "Kryptographische Algorithmen und Schlüssellängen", BSI TR-02102-1]</ref>
<ref name="STM32 image header">[https://wiki.st.com/stm32mpu/wiki/STM32_header_for_binary_files STM32 header for binary files]</ref>
<ref name="KeyGen_tool">[https://wiki.st.com/stm32mpu/wiki/KeyGen_tool STM32MP KeyGen tool]</ref>
<ref name="Signing_tool">[https://wiki.st.com/stm32mpu/wiki/Signing_tool STM32MP Signing tool]</ref>
<ref name="TF-A">[https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/ Trusted Firmware-A (TF-A)]</ref>
<ref name="OP-TEE/optee_os">[https://github.com/OP-TEE/optee_os OP-TEE Trusted OS]</ref>
<ref name="OP-TEE/build">[https://github.com/OP-TEE/build Makefiles to use OP-TEE on various platforms]</ref>
</references>

DHCOM STM32MP15 Secure Boot

2022-03-22T09:29:14Z

Dkierner: Improve wording of /* What is meant by Verified Boot? */ including title

<div class="toclimit-3">__TOC__</div>

== Introduction ==

=== Abbreviations ===

{| class="wikitable sortable"
|-
! Abbreviation !! Description
|-
| BSI || Bundesamt für Sicherheit in der Informationstechnik
|-
| CoM || Computer on module
|-
| FIT || Flattened Image Tree
|-
| FSBL || Fist Stage Bootloader (TF-A or U-Boot SPL)
|-
| OTP || One Time Programmable (eFuses)
|-
| OP-TEE || Open Portable Trusted Execution Environment
|-
| PKH || Public Key Hash
|-
| ROM || Read-Only Memory
|-
| RSA || Rivest, Shamir und Adleman (asynchronous encryption)
|-
| SHA || Secure Hash Algorithm
|-
| SoC || System on chip
|-
| SoM || System on module
|-
| SSBL || Second Stage Bootloader (U-Boot)
|-
| TF-A || Trusted Firmware A
|}

=== What does Secure Boot mean? ===

The term Secure Boot originally comes from the UEFI specification<ref name="UEFI specification" /> and describes a secure boot process in which only signed software is loaded and executed during the boot process.

Secure Boot is a necessary cornerstone for enforcing security mechanisms in a trusted computing environment.
Enforcing the execution of signed software only during the boot process, as long as the chain of trust is secure, can guarantee that said software is free from tampering, as any manipulation will invalidate the software's signature and prevent the software from being executed.

[[File:Secure Boot Generic en.png|600px|Secure Boot Generic]]

The figure [[Media:Secure Boot Generic en.png|Secure Boot Generic]] shows an example of a secure boot process that leads to a reset in the event of an error in the signature check. Each stage uses the certificate and signature to check the origin and integrity of the next stage. On success, the next stage is executed, and in the event of an error, this always leads to a defined error state. In the simplest case, the certificates are integrated into the binary image of the previous stage.

Program code and certificate need to be trustworthy and therefore protected against tampering in each stage, otherwise the secure boot chain can be compromised. Except for the first stage, all binary images are protected against third-party tampering by the signature. As this is practically impossible for the first stage, manipulation protection has to be enforced by hardware measures to make said stage immutable, with the first stage's program code and the verification certificate for the second stage being stored in read-only memory (ROM).

=== Basic and trusted boot in the context of Secure Boot ===

When booting Linux on the STM32MP1 SoC with U-Boot SPL and U-Boot only, STM speaks of "Basic Boot"<ref name="Basic Boot" />.
However, if Linux is booted with a combination of TF-A, U-Boot and OP-TEE, STM refers to this as "Trusted Boot"<ref name="Trusted Boot" />.

{| class="wikitable"
|-
! Boot chain !! Description
|-
| Basic boot || BootROM -> U-Boot SPL -> U-Boot -> Linux
|-
| Trusted boot || BootROM -> TF-A -> U-Boot + OP-TEE -> Linux
|}

== Secure Boot in Basic Boot with BootROM authentication and Verified Boot ==

This Secure Boot implementation does use the the BootROM integrated image authentication to authenticate the U-Boot SPL as FSBL.
Authentication of U-Boot as SSBL by the U-Boot SPL and authentication of the Linux kernel, Device Tree and ramdisk by U-Boot is done using the open source implementation [[#What is meant by Verified Boot?|Verified Boot]].

This also means that everything from U-Boot SPL onwards is platform independent, as we do not rely on hardware specific implementations.

=== Verified Boot ===

Developers of Google's Chromium project worked out a concept for the Verified Boot called Secure Boot mechanism on the basis of the boot loader "Das U-Boot".
They use the existing infrastructure of the FIT images and for the system configuration at runtime via a Device Tree.
The description language for the FIT images was extended by an additional signature node and the Device Tree of the platform was used to store the certificate(s) for the authentication of the images.
The signature node can be used to sign individual subimages as well as combinations of individual subimages in the FIT image.
The tool <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight> takes care the signature creation for the FIT images and the addition of the certificate in a Device Tree.

With Verified Boot, the Device Tree with included public key is integrated into the program image of the stage, which accomplishes the authentication and is thus very similar to the general procedure shown in figure [[Media:Secure Boot Generic en.png|Secure Boot Generic]].
The number of public keys that can be integrated is theoretically unlimited, but they must be distinguishable by name.

==== Technical details of Verified Boot ====

{| class="wikitable"
|-
| '''Name'''
| Verified Boot
|-
| '''Implementierung'''
| Software (Open Source)
|-
| '''Hash algorithms'''
|
* SHA1 (deprecated)<ref name="BSI TR-02102" />
* SHA256
* SHA384
* SHA512
|-
| '''Crypto algorithms
|
* RSA2048 (deprecated as of 2024)<ref name="BSI TR-02102" />
* RSA4096

* ECDSA256 (currently limited to U-Boot SPL)
|-
| '''Number of key pairs'''
| unlimited
|-
|}

==== In-depth references for Verified Boot ====


===== Flatten Image Tree =====
* [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT U-Boot Documentation: doc/uImage.FIT]
* [https://source.denx.de/u-boot/u-boot/-/commit/d5934ad7 U-Boot Commit d5934ad7: "new uImage: Add dual format uImage support framework"]
* ...
* [https://source.denx.de/u-boot/u-boot/-/commit/3310c549 U-Boot Commit d5934ad7: "new uImage: Add new uImage format documentation and examples"]

===== Verified Boot =====

* [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT/signature.txt U-Boot Documentation: doc/uImage.FIT/signature.txt]
* [https://source.denx.de/u-boot/u-boot/-/commit/3e569a6b U-Boot Commit 3e569a6b: "image: Add signing infrastructure"]
* [https://source.denx.de/u-boot/u-boot/-/commit/56518e71 U-Boot Commit 56518e71: "image: Support signing of images"]
* [https://source.denx.de/u-boot/u-boot/-/commit/4d098529 U-Boot Commit 4d098529: "image: Add support for signing of FIT configurations"]

===== ECDSA signature verification =====

<div style="color:red">TODO: Mention ECDSA limitations</div>
Note: This has currently some limitations!


* [https://source.denx.de/u-boot/u-boot/-/commit/928a8be7 U-Boot Commit 928a8be7: "lib: ecdsa: Implement UCLASS_ECDSA verification on target"]
* [https://source.denx.de/u-boot/u-boot/-/commit/ee870859 U-Boot Commit ee870859: "arm: stm32mp1: Implement ECDSA signature verification"]

=== Tutorial: Secure boot from BootROM to Linux with basic boot ===

==== System requirements and needed tools ====

The following table lists all requirements to create the key pairs and build the signed images with embedded public keys.

{| class="wikitable"
|-
! Category !! Description
|-
| '''Host operating system''' ||
* Linux (Debian 9, Ubuntu 18.04 or higher prefered)
|-
| '''Debian packages''' ||
* bison
* device-tree-compiler
* flex
* gcc-arm-linux-gnueabihf (>= gcc 6)
* git
* make
* openssl
|-
| '''STM32 Tools''' ||
* [https://www.st.com/en/development-tools/stm32cubeprog.html STM32CubeProgrammer]
** STM32MP_KeyGen_CLI
** STM32MP_SigningTool_CLI
|}

<div style="color:red">TODO: Should we give host setup instructions?</div>


==== Intended use of the four generated key pairs ====

We've decided to create and use as few certificates as reasonable to ensure a high level of security.
Therefore, we chose a separate key pair for each boot stage and also a separate key pair for image and configuration nodes.
If you're confused about the difference between image and configuration nodes, head over to [[#Flatten Image Tree|Flatten Image Tree]] to refresh your knowledge.
The exact purpose of the four key pairs generated for Verified Boot is described in the following table.

{| class="wikitable"
|-
! File name !! Intended use
|-
| '''fsbl-img''' || Authenticate image nodes of FIT images loaded by U-Boot SPL (U-Boot, Device Tree, firmware)
|-
| '''fsbl-cfg''' || Authenticate config nodes of FIT images loaded by U-Boot SPL (U-Boot + Device Tree + firmware)
|-
| '''ssbl-img''' || Authenticate image nodes of FIT images loaded by U-Boot (Kernel, Device Tree, InitRamFS)
|-
| '''ssbl-cfg''' || Authenticate config nodes of FIT images loaded by U-Boot (Kernel + Device Tree + InitRamFS)
|-
|}

==== Created/Modified files in the U-Boot source for Verified Boot ====

The created or modified files to build U-Boot with Verified Boot on STM32MP15 are described in the following table.

{| class="wikitable"
|-
! File
! Description
|-
| build_signed_uboot.sh
| Shell script that automates the creation of key pairs, the modification of FIT source files and Device Tree's and building of U-Boot SPL and U-Boot.
|-
| board/dhelectronics/dh_stm32mp1/u-boot-dhco?.its
| FIT source files with defined U-Boot image and Device Tree's for DHSOM platforms.
|-
| board/dhelectronics/dh_stm32mp1/linux-dhcom.its
| Dummy FIT source file with defined dummy kernel image and dummy Device Tree for DHSOM platforms.<br>To avoid relying on a built kernel image on a fixed path, we created this dummy, since adding the public keys with <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight> requires a valid FIT source file.
|-
| configs/stm32mp15_dhco?_secure_defconfig
| Example U-Boot defconfig's with enabled <syntaxhighlight lang="shell" inline>CONFIG_FIT_SIGNATURE</syntaxhighlight> and <syntaxhighlight lang="shell" inline>CONFIG_SPL_FIT_SIGNATURE</syntaxhighlight>.
|}

==== Build Verified Boot enabled U-Boot SPL and U-Boot ====

To build the U-Boot SPL and U-Boot images, you need to check out the source code and run a build script that automates everything from key generation to image creation and signing.

===== Checkout source code for Verified Boot =====

<div style="color:red">TODO: Replace my personal GitLab by a public available repository</div>
Checkout the branch <syntaxhighlight lang="shell" inline>v2022.01_dhcom_secure_boot</syntaxhighlight> of my personal GitLab repository with:

<syntaxhighlight lang="shell">
git clone git@dhplgl01:jneuhauser/u-boot.git -b v2022.01_dhcom_secure_boot
</syntaxhighlight>

If you already have a cloned U-Boot source code, you can also fetch it into your existing repository with:

<syntaxhighlight lang="shell">
cd /path/to/u-boot
git remote add jneuhauser git@dhplgl01:jneuhauser/u-boot.git
git fetch jneuhauser
git checkout v2022.01_dhcom_secure_boot
</syntaxhighlight>

===== Run the build script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> =====

The shell script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> included in the U-Boot source performs the following steps.
# Prebuild U-Boat SPL and U-Boat to build the required tools and Device Tree's
# Generate the [[#Intended use of the four generated key pairs|four key pairs]] if not already created
# Generate/Modify FIT image source files for Linux (dummy) and U-Boot
# Add public keys to the built Device Tree's used by U-Boot SPL and U-Boot
# Rebuild U-Boot SPL and U-Boot with new Device Tree's containing the public keys

The script supports the following environment variables to configure the target architecture, the cross compiler, the defconfig, the key algorithm, the key directory, and a key postfix.
{| class="wikitable sortable"
|-
! Name !! Description !! Default
|-
| ARCH || Target architecture for the U-Boot build || arm
|-
| CROSS_COMPILE || Used cross compiler to build U-Boot || arm-linux-gnueabihf-
|-
| DEFCONFIG || Used defconfig for the U-Boot build || stm32mp15_dhcom_secure_defconfig
|-
| KEY_ALGO || Signature algorithm used for Verified Boot || rsa
|-
| KEY_DIR || Directory where the key pairs are stored || ../keys
|-
| KEY_POSTFIX || Postfix which is appended to the key names || -$(date +%F)
|}

To perform the steps mentioned above, you just need to run the shell script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> like below.
In this example, we override the default value for <syntaxhighlight lang="shell" inline>KEY_POSTFIX</syntaxhighlight> with <syntaxhighlight lang="shell" inline>-testing</syntaxhighlight> to append this string to the [[#Intended use of the four generated key pairs|four key file names]].
The script has debug output enabled by default, which should output all the statements in the script itself and the output of the commands used in the script.
If you have any problems with the script, feel free to get in touch with the script author [mailto:jneuhauser@dh-electronics.com Johann Neuhauser] and attach a logfile.

<syntaxhighlight lang="shell">
cd /path/to/u-boot
KEY_POSTFIX="-testing" ./build_signed_uboot.sh | tee build_signed_uboot.log
</syntaxhighlight>

If this process completes without error, there are two boot loader images in the root directory of the U-Boot source.
{| class="wikitable sortable"
|-
! File name !! Stage !! Description
|-
| u-boot-spl.stm32 || FSBL || U-Boot SPL binary with appended Device Tree and prepended STM32 image header<ref name="STM32 image header" />.
|-
| u-boot.itb || SSBL || U-Boot and Device Tree's contained in a signed FIT image.
|}

==== Generate key pair and sign U-Boot SPL for BootROM authentication ====

To sign the U-Boot SPL as SSBL image for authentication with the BootROM we have to use the STM32 tools <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight> and <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight>.

===== Generate key pair with <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight> =====

All STM32MP15 SoC's only support one key pair for authenticating images through the BootROM.
To generate ECDSA key pairs for the STM32MP Secure Boot we are using the tool <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight><ref name="KeyGen_tool" /> to generate a single key pair.
<syntaxhighlight lang="shell">
STM32MP_KeyGen_CLI --absolute-path "$(pwd)" --password 12345678
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Key Generator v2.9.0
-------------------------------------------------------------------

Prime256v1 curve is selected.
AES_256_cbc algorithm is selected for private key encryption
Generating Prime256v1 keys...
Private key PEM file created
Public key PEM file created
public key hash file created
Keys generated successfully.
+ public key: publicKey.pem
+ private key: privateKey.pem
+ public hash key: publicKeyhash.bin
</syntaxhighlight>

===== Sign U-Boot SPL with <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight> =====

To add the public key and the image signature to our built U-Boot SPL binary with STM32 image header, we are using the tool <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight><ref name="Signing_tool" /> to update the existing STM32 image header of <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> with the required details.
<syntaxhighlight lang="shell">
STM32MP_SigningTool_CLI --binary-image /path/to/u-boot/u-boot-spl.stm32 --public-key publicKey.pem --private-key privateKey.pem --password 12345678 --output /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Signing Tool v2.9.0
-------------------------------------------------------------------

Prime256v1 curve is selected.
Header version 1 preparation ...
Reading Private Key File...
ECDSA signature generated.
Signature verification: SUCCESS
The Signed image file generated successfully: /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>

You can check the STM32 image header details with:
<syntaxhighlight lang="shell">
STM32MP_SigningTool_CLI --dump-header /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Signing Tool v2.9.0
-------------------------------------------------------------------

Header description:

Magic: 0x53544d32
Signature: c8 30 a0 62 2d 6d 4e 1b b9 f7 fe 38 27 65 e0 44 f0 f5 9d e6 8a a6 02 cb 74 52 26 9c 1e e9 07 17
1a c7 da 8e 96 fa 82 d3 b1 dc d5 3a 05 0e 87 83 94 4d 47 ad 17 07 88 0d b5 ae 2e 38 1d 90 22 ad
Checksum: 0xa8ca85
Header version: 0x10000
Size: 0x22dec
Load address: 0x2ffc2500
Entry point: 0x2ffc2500
Image version: 0x0
Option flags: 0x0
ECDSA Algo: 0x1
ECDSA pub key: 3b 71 8e 59 f1 ee 4c a8 4b 72 5f 4a 1c 63 8b 6e b8 01 ec 1a 3f 8c 98 2f d2 1d 77 f9 09 10 8f 04
30 da 5c 3a 24 53 0d 71 93 f0 a5 d9 c9 a7 27 b4 5f a5 c4 4d 55 8b 7a 25 e3 03 ef ca 87 ff 04 25
Binary type: 0x0
</syntaxhighlight>
The difference to an unsigned STM32 image header is that the values for "Signature" and "ECDSA pub key" are not all zeros and that "Option flags" is 0x0 for enabled signature verification instead of 0x1 for disabled signature verification.

==== Write U-Boot SPL and U-Boot to your boot media ====

The first step to verify that the built U-Boot SPL and U-Boot works as expected is to program both images to your boot media.
Depending on the boot configuration, your DHSOM will boot from the module's SPI-NOR flash, from the module's or baseboard's eMMC or from an SD card.
The boot configuration is always defined by the boot pins by default, because the boot pins have no alternative function on the STM32MP15 SoC's.

<div style="color:red">TODO: How can a user determine the used boot media?</div>
<div style="color:red">TODO: How to enforce boot media on Secure Boot enabled devices?</div>

===== Write U-Boot SPL and U-Boot to the SPI-NOR flash of the SoM =====

The following '''commands for the U-Boot Shell''' calculate some addresses based on the image offsets expected by the BootROM, load the required images from SD card or via TFTP into memory and finally write the prepared memory into the SPI-NOR flash on the SoM.

Prepare for loading <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> into memory:
<syntaxhighlight lang="shell">
mw.b ${loadaddr} 0xff 0x200000
setexpr fsbl1addr ${loadaddr} + 0x0
setexpr fsbl2addr ${loadaddr} + 0x40000
setexpr ssbl1addr ${loadaddr} + 0x80000
</syntaxhighlight>

Load <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> from SD card:
<syntaxhighlight lang="shell">
load mmc 0:4 ${fsbl1addr} u-boot-spl.stm32
load mmc 0:4 ${fsbl2addr} u-boot-spl.stm32
load mmc 0:4 ${ssbl1addr} u-boot.itb
</syntaxhighlight>

Load <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> from tftp server:
<syntaxhighlight lang="shell">
setenv serverip 10.20.30.1
setenv ipaddr 10.20.30.100
setenv netmask 255.255.255.0
tftp ${fsbl1addr} ${serverip}:u-boot-spl.stm32
tftp ${fsbl2addr} ${serverip}:u-boot-spl.stm32
tftp ${ssbl1addr} ${serverip}:u-boot.itb
</syntaxhighlight>

Check for magic numbers of expected image headers and conditionally program the SPI-NOR flash:
<syntaxhighlight lang="shell">
if itest *${fsbl1addr} == 0x324d5453 && itest *${fsbl2addr} == 0x324d5453 && itest *${ssbl1addr} == 0xedfe0dd0; then
sf probe && sf update ${loadaddr} 0 0x200000
fi
</syntaxhighlight>

===== Write U-Boot SPL and U-Boot to an SD card =====

<div style="color:red">TODO:</div>


===== Write U-Boot SPL and U-Boot to the eMMC =====

<div style="color:red">TODO:</div>


==== Enroll, test and enforce BootROM image authentication ====

To enroll, test and enforce image authentication by the BootROM you need to program the PKH into the OTP of the STM32MP15 SoC.
The <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> file that you created in the [[#Generate key pair with STM32MP_KeyGen_CLI|Generate key pair with STM32MP_KeyGen_CLI]] step contains the PKH in binary format for use with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> U-Boot command.
If the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command does fail or is not available on the target U-Boot, you can also write the PKH manually with the more generic <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command into the OTP.

===== Program public key hash to eFuses =====

The following '''commands for the U-Boot Shell''' load the file <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> into memory and program the contained PKH to the OTP of the STM32MP15 SoC.
The used command <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> writes and locks the words of the OTP automatically without knowing anything about the OTP layout/addresses.
If this fails or the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command is not available, you can also write and lock the OTP with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command

====== Program <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> into OTP with <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command ======

Load <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> by SD card:
<syntaxhighlight lang="shell">
load mmc 0:4 ${loadaddr} publicKeyhash.bin
</syntaxhighlight>

Or load <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> by TFTP:
<syntaxhighlight lang="shell">
setenv serverip 10.20.30.1
setenv ipaddr 10.20.30.100
setenv netmask 255.255.255.0
tftp ${loadaddr} ${serverip}:publicKeyhash.bin
</syntaxhighlight>

Show the contents of <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight>:
<syntaxhighlight lang="shell">
stm32key read ${loadaddr}
</syntaxhighlight>
<syntaxhighlight lang="console">
Read KEY at 0xc2000000
OTP value 24: 4e31bbcd
OTP value 25: 51e827dd
OTP value 26: 3511f521
OTP value 27: fd9c11a2
OTP value 28: 5b997b82
OTP value 29: 8150adc5
OTP value 30: a9c68fa9
OTP value 31: 72a3ba74
</syntaxhighlight>

Write the contents of <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> to OTP with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command:
<syntaxhighlight lang="shell">
stm32key fuse ${loadaddr}
</syntaxhighlight>
<syntaxhighlight lang="console">
TODO: Add output
</syntaxhighlight>

====== Program PKH manually into OTP with <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command ======

Generate fuse command with hexdump from file <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> on linux host:
<div style="color:red">Warning: Do not use the example output! Only use your unique values for programming the PKH in the OTP!</div>
<syntaxhighlight lang="shell">
echo fuse prog -y 0 0x18 $(hexdump -e '/4 "0x"' -e '/1 "%x"' -e '" "' /path/to/publicKeyhash.bin)
</syntaxhighlight>
<syntaxhighlight lang="console">
fuse prog -y 0 0x18 0x4e31bbcd 0x51e827dd 0x3511f521 0xfd9c11a2 0x5b997b82 0x8150adc5 0xa9c68fa9 0x72a3ba74
</syntaxhighlight>

Write the PKH into OTP manually with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<div style="color:red">Warning: Do not use the example command! Only use your unique values for programming the PKH in the OTP!</div>
<syntaxhighlight lang="shell">
fuse prog -y 0 0x18 0x4e31bbcd 0x51e827dd 0x3511f521 0xfd9c11a2 0x5b997b82 0x8150adc5 0xa9c68fa9 0x72a3ba74
</syntaxhighlight>

Lock the related OTP words manually with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<syntaxhighlight lang="shell">
fuse prog -y 0 0x10000018 1 1 1 1 1 1 1 1
</syntaxhighlight>

===== Test BootROM image authentication =====

To verify the image authentication by the BootROM with the programmed PKH and the programmed signed images, you must reboot your device.

On the third line of the U-Boot SPL output, check the BootROM authentication status.
The status output should look like this: <syntaxhighlight lang="console" inline>Bootrom authentication: succeeded</syntaxhighlight>.
Note the <syntaxhighlight lang="console" inline>succeeded</syntaxhighlight> status for successful authentication of the U-Boot SPL image by the BootROM.

The following output shows successful authentication of the U-Boot-SPL image in line 3, as well as successful authentication of the used configuration in line 7 and the U-Boot and Device Tree subimages in lines 8 and 9 of the U-Boot-FIT image.
<syntaxhighlight lang="console" line highlight="3,7-9">
U-Boot SPL 2022.01-00012-g6c5892c90c28 (Feb 16 2022 - 11:11:16 +0100)
Model: STMicroelectronics STM32MP15xx DHCOM Premium Developer Kit (2)
Bootrom authentication: succeeded
Code: SoM:rev=1,ddr3=3 Board:rev=0
RAM: DDR3L 32bits 2x4Gb 533MHz
Trying to boot from SPI
## Checking hash(es) for config config-2 ... sha256,rsa4096:fsbl-cfg-2022-02-16+ OK
## Checking hash(es) for Image uboot ... sha256,rsa4096:fsbl-img-2022-02-16+ sha256+ OK
## Checking hash(es) for Image fdt-1 ... sha256,rsa4096:fsbl-img-2022-02-16+ sha256+ OK
</syntaxhighlight>

===== Enforce BootROM image authentication =====

Without any further changes, the BootROM is able to perform authentication of the FSBL image, but unauthenticated images can still be used and executed.
The device is still open, let's see this as a kind of test mode to check if the PKH is set correctly.

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

The 6th bit in the 1st word of the OTP is responsible that the BootROM only accepts signed images.
Burning this bit enforces authentication of images by the BootROM and unsigned binaries are no longer supported on the target device.

To program this bit, the U-Boot Shell can be used with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command or with the more general <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command.

With usage of the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command:
<div style="color:red">Warning: After running the following command, your device will only be able to boot signed images!</div>
<syntaxhighlight lang="shell">
stm32key close
</syntaxhighlight>

Or with usage of the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<div style="color:red">Warning: After running the following command, your device will only be able to boot signed images!</div>
<syntaxhighlight lang="shell">
fuse prog 0 0x0 0x40
</syntaxhighlight>

== Secure Boot in Trusted Boot with BootROM authentication, TF-A and OP-TEE ==

<div style="color:red">TODO:</div>
# Add support for STM32MP15 DHCOM in <ref name="TF-A" />
# Add support for STM32MP15 DHCOM in <ref name="OP-TEE/optee_os" />
# Create stm32mp15_dhcom_trusted_defconfig???
# Integrate STM32MP15 DHCOM into <ref name="OP-TEE/build" />

== References ==

<references>
<ref name="UEFI specification">[http://www.uefi.org/specifications http://www.uefi.org/specifications]</ref>
<ref name="Basic Boot">[https://source.denx.de/u-boot/u-boot/-/blob/master/configs/stm32mp15_basic_defconfig U-Boot Source stm32mp15_basic_defconfig]</ref>
<ref name="Trusted Boot">[https://source.denx.de/u-boot/u-boot/-/blob/master/configs/stm32mp15_trusted_defconfig U-Boot Source stm32mp15_trusted_defconfig]</ref>
<ref name="BSI TR-02102">[https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.pdf BSI - Technische Richtlinie, "Kryptographische Algorithmen und Schlüssellängen", BSI TR-02102-1]</ref>
<ref name="STM32 image header">[https://wiki.st.com/stm32mpu/wiki/STM32_header_for_binary_files STM32 header for binary files]</ref>
<ref name="KeyGen_tool">[https://wiki.st.com/stm32mpu/wiki/KeyGen_tool STM32MP KeyGen tool]</ref>
<ref name="Signing_tool">[https://wiki.st.com/stm32mpu/wiki/Signing_tool STM32MP Signing tool]</ref>
<ref name="TF-A">[https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/ Trusted Firmware-A (TF-A)]</ref>
<ref name="OP-TEE/optee_os">[https://github.com/OP-TEE/optee_os OP-TEE Trusted OS]</ref>
<ref name="OP-TEE/build">[https://github.com/OP-TEE/build Makefiles to use OP-TEE on various platforms]</ref>
</references>

DHCOM STM32MP15 Secure Boot

2022-03-22T09:08:52Z

Dkierner: Add TF-A and OP-TEE to section /* Abbreviations */

<div class="toclimit-3">__TOC__</div>

== Introduction ==

=== Abbreviations ===

{| class="wikitable sortable"
|-
! Abbreviation !! Description
|-
| BSI || Bundesamt für Sicherheit in der Informationstechnik
|-
| CoM || Computer on module
|-
| FIT || Flattened Image Tree
|-
| FSBL || Fist Stage Bootloader (TF-A or U-Boot SPL)
|-
| OTP || One Time Programmable (eFuses)
|-
| OP-TEE || Open Portable Trusted Execution Environment
|-
| PKH || Public Key Hash
|-
| ROM || Read-Only Memory
|-
| RSA || Rivest, Shamir und Adleman (asynchronous encryption)
|-
| SHA || Secure Hash Algorithm
|-
| SoC || System on chip
|-
| SoM || System on module
|-
| SSBL || Second Stage Bootloader (U-Boot)
|-
| TF-A || Trusted Firmware A
|}

=== What does Secure Boot mean? ===

The term Secure Boot originally comes from the UEFI specification<ref name="UEFI specification" /> and describes a secure boot process in which only signed software is loaded and executed during the boot process.

Secure Boot is a necessary cornerstone for enforcing security mechanisms in a trusted computing environment.
Enforcing the execution of signed software only during the boot process, as long as the chain of trust is secure, can guarantee that said software is free from tampering, as any manipulation will invalidate the software's signature and prevent the software from being executed.

[[File:Secure Boot Generic en.png|600px|Secure Boot Generic]]

The figure [[Media:Secure Boot Generic en.png|Secure Boot Generic]] shows an example of a secure boot process that leads to a reset in the event of an error in the signature check. Each stage uses the certificate and signature to check the origin and integrity of the next stage. On success, the next stage is executed, and in the event of an error, this always leads to a defined error state. In the simplest case, the certificates are integrated into the binary image of the previous stage.

Program code and certificate need to be trustworthy and therefore protected against tampering in each stage, otherwise the secure boot chain can be compromised. Except for the first stage, all binary images are protected against third-party tampering by the signature. As this is practically impossible for the first stage, manipulation protection has to be enforced by hardware measures to make said stage immutable, with the first stage's program code and the verification certificate for the second stage being stored in read-only memory (ROM).

=== Basic and trusted boot in the context of Secure Boot ===

When booting Linux on the STM32MP1 SoC with U-Boot SPL and U-Boot only, STM speaks of "Basic Boot"<ref name="Basic Boot" />.
However, if Linux is booted with a combination of TF-A, U-Boot and OP-TEE, STM refers to this as "Trusted Boot"<ref name="Trusted Boot" />.

{| class="wikitable"
|-
! Boot chain !! Description
|-
| Basic boot || BootROM -> U-Boot SPL -> U-Boot -> Linux
|-
| Trusted boot || BootROM -> TF-A -> U-Boot + OP-TEE -> Linux
|}

== Secure Boot in Basic Boot with BootROM authentication and Verified Boot ==

This Secure Boot implementation does use the the BootROM integrated image authentication to authenticate the U-Boot SPL as FSBL.
Authentication of U-Boot as SSBL by the U-Boot SPL and authentication of the Linux kernel, Device Tree and ramdisk by U-Boot is done using the open source implementation [[#What is meant by Verified Boot?|Verified Boot]].

This also means that everything from U-Boot SPL onwards is platform independent, as we do not rely on hardware specific implementations.

=== What is meant by Verified Boot? ===

Developers of Google's Chromium project worked out a concept for the Verified Boot called Secure Boot mechanism on the basis of the boot loader "Das U-Boot".
They use the existing infrastructure of the FIT images and for the system configuration at runtime via a Device Tree.
The description language for the FIT images was extended by an additional signature node and the Device Tree of the platform was used to store the certificate(s) for the authentication of the images.
The signature node can be used to sign individual subimages as well as combinations of individual subimages in the FIT image.
The tool <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight> takes over the creation of the signatures in the FIT images and the addition of the certificate in a Device Tree.

With Verified Boot, the Device Tree with the included public key is integrated into the program image of the stage, which accomplishes the authentication and is thus very similar to the general procedure shown in figure [[Media:Secure Boot Generic en.png|Secure Boot Generic]].
The number of public keys that can be integrated is theoretically unlimited, but they must be distinguishable by name.

==== Technical details of Verified Boot ====

{| class="wikitable"
|-
| '''Name'''
| Verified Boot
|-
| '''Implementierung'''
| Software (Open Source)
|-
| '''Hash algorithms'''
|
* SHA1 (deprecated)<ref name="BSI TR-02102" />
* SHA256
* SHA384
* SHA512
|-
| '''Crypto algorithms
|
* RSA2048 (deprecated as of 2024)<ref name="BSI TR-02102" />
* RSA4096

* ECDSA256 (currently limited to U-Boot SPL)
|-
| '''Number of key pairs'''
| unlimited
|-
|}

==== In-depth references for Verified Boot ====


===== Flatten Image Tree =====
* [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT U-Boot Documentation: doc/uImage.FIT]
* [https://source.denx.de/u-boot/u-boot/-/commit/d5934ad7 U-Boot Commit d5934ad7: "new uImage: Add dual format uImage support framework"]
* ...
* [https://source.denx.de/u-boot/u-boot/-/commit/3310c549 U-Boot Commit d5934ad7: "new uImage: Add new uImage format documentation and examples"]

===== Verified Boot =====

* [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT/signature.txt U-Boot Documentation: doc/uImage.FIT/signature.txt]
* [https://source.denx.de/u-boot/u-boot/-/commit/3e569a6b U-Boot Commit 3e569a6b: "image: Add signing infrastructure"]
* [https://source.denx.de/u-boot/u-boot/-/commit/56518e71 U-Boot Commit 56518e71: "image: Support signing of images"]
* [https://source.denx.de/u-boot/u-boot/-/commit/4d098529 U-Boot Commit 4d098529: "image: Add support for signing of FIT configurations"]

===== ECDSA signature verification =====

<div style="color:red">TODO: Mention ECDSA limitations</div>
Note: This has currently some limitations!


* [https://source.denx.de/u-boot/u-boot/-/commit/928a8be7 U-Boot Commit 928a8be7: "lib: ecdsa: Implement UCLASS_ECDSA verification on target"]
* [https://source.denx.de/u-boot/u-boot/-/commit/ee870859 U-Boot Commit ee870859: "arm: stm32mp1: Implement ECDSA signature verification"]

=== Tutorial: Secure boot from BootROM to Linux with basic boot ===

==== System requirements and needed tools ====

The following table lists all requirements to create the key pairs and build the signed images with embedded public keys.

{| class="wikitable"
|-
! Category !! Description
|-
| '''Host operating system''' ||
* Linux (Debian 9, Ubuntu 18.04 or higher prefered)
|-
| '''Debian packages''' ||
* bison
* device-tree-compiler
* flex
* gcc-arm-linux-gnueabihf (>= gcc 6)
* git
* make
* openssl
|-
| '''STM32 Tools''' ||
* [https://www.st.com/en/development-tools/stm32cubeprog.html STM32CubeProgrammer]
** STM32MP_KeyGen_CLI
** STM32MP_SigningTool_CLI
|}

<div style="color:red">TODO: Should we give host setup instructions?</div>


==== Intended use of the four generated key pairs ====

We've decided to create and use as few certificates as reasonable to ensure a high level of security.
Therefore, we chose a separate key pair for each boot stage and also a separate key pair for image and configuration nodes.
If you're confused about the difference between image and configuration nodes, head over to [[#Flatten Image Tree|Flatten Image Tree]] to refresh your knowledge.
The exact purpose of the four key pairs generated for Verified Boot is described in the following table.

{| class="wikitable"
|-
! File name !! Intended use
|-
| '''fsbl-img''' || Authenticate image nodes of FIT images loaded by U-Boot SPL (U-Boot, Device Tree, firmware)
|-
| '''fsbl-cfg''' || Authenticate config nodes of FIT images loaded by U-Boot SPL (U-Boot + Device Tree + firmware)
|-
| '''ssbl-img''' || Authenticate image nodes of FIT images loaded by U-Boot (Kernel, Device Tree, InitRamFS)
|-
| '''ssbl-cfg''' || Authenticate config nodes of FIT images loaded by U-Boot (Kernel + Device Tree + InitRamFS)
|-
|}

==== Created/Modified files in the U-Boot source for Verified Boot ====

The created or modified files to build U-Boot with Verified Boot on STM32MP15 are described in the following table.

{| class="wikitable"
|-
! File
! Description
|-
| build_signed_uboot.sh
| Shell script that automates the creation of key pairs, the modification of FIT source files and Device Tree's and building of U-Boot SPL and U-Boot.
|-
| board/dhelectronics/dh_stm32mp1/u-boot-dhco?.its
| FIT source files with defined U-Boot image and Device Tree's for DHSOM platforms.
|-
| board/dhelectronics/dh_stm32mp1/linux-dhcom.its
| Dummy FIT source file with defined dummy kernel image and dummy Device Tree for DHSOM platforms.<br>To avoid relying on a built kernel image on a fixed path, we created this dummy, since adding the public keys with <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight> requires a valid FIT source file.
|-
| configs/stm32mp15_dhco?_secure_defconfig
| Example U-Boot defconfig's with enabled <syntaxhighlight lang="shell" inline>CONFIG_FIT_SIGNATURE</syntaxhighlight> and <syntaxhighlight lang="shell" inline>CONFIG_SPL_FIT_SIGNATURE</syntaxhighlight>.
|}

==== Build Verified Boot enabled U-Boot SPL and U-Boot ====

To build the U-Boot SPL and U-Boot images, you need to check out the source code and run a build script that automates everything from key generation to image creation and signing.

===== Checkout source code for Verified Boot =====

<div style="color:red">TODO: Replace my personal GitLab by a public available repository</div>
Checkout the branch <syntaxhighlight lang="shell" inline>v2022.01_dhcom_secure_boot</syntaxhighlight> of my personal GitLab repository with:

<syntaxhighlight lang="shell">
git clone git@dhplgl01:jneuhauser/u-boot.git -b v2022.01_dhcom_secure_boot
</syntaxhighlight>

If you already have a cloned U-Boot source code, you can also fetch it into your existing repository with:

<syntaxhighlight lang="shell">
cd /path/to/u-boot
git remote add jneuhauser git@dhplgl01:jneuhauser/u-boot.git
git fetch jneuhauser
git checkout v2022.01_dhcom_secure_boot
</syntaxhighlight>

===== Run the build script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> =====

The shell script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> included in the U-Boot source performs the following steps.
# Prebuild U-Boat SPL and U-Boat to build the required tools and Device Tree's
# Generate the [[#Intended use of the four generated key pairs|four key pairs]] if not already created
# Generate/Modify FIT image source files for Linux (dummy) and U-Boot
# Add public keys to the built Device Tree's used by U-Boot SPL and U-Boot
# Rebuild U-Boot SPL and U-Boot with new Device Tree's containing the public keys

The script supports the following environment variables to configure the target architecture, the cross compiler, the defconfig, the key algorithm, the key directory, and a key postfix.
{| class="wikitable sortable"
|-
! Name !! Description !! Default
|-
| ARCH || Target architecture for the U-Boot build || arm
|-
| CROSS_COMPILE || Used cross compiler to build U-Boot || arm-linux-gnueabihf-
|-
| DEFCONFIG || Used defconfig for the U-Boot build || stm32mp15_dhcom_secure_defconfig
|-
| KEY_ALGO || Signature algorithm used for Verified Boot || rsa
|-
| KEY_DIR || Directory where the key pairs are stored || ../keys
|-
| KEY_POSTFIX || Postfix which is appended to the key names || -$(date +%F)
|}

To perform the steps mentioned above, you just need to run the shell script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> like below.
In this example, we override the default value for <syntaxhighlight lang="shell" inline>KEY_POSTFIX</syntaxhighlight> with <syntaxhighlight lang="shell" inline>-testing</syntaxhighlight> to append this string to the [[#Intended use of the four generated key pairs|four key file names]].
The script has debug output enabled by default, which should output all the statements in the script itself and the output of the commands used in the script.
If you have any problems with the script, feel free to get in touch with the script author [mailto:jneuhauser@dh-electronics.com Johann Neuhauser] and attach a logfile.

<syntaxhighlight lang="shell">
cd /path/to/u-boot
KEY_POSTFIX="-testing" ./build_signed_uboot.sh | tee build_signed_uboot.log
</syntaxhighlight>

If this process completes without error, there are two boot loader images in the root directory of the U-Boot source.
{| class="wikitable sortable"
|-
! File name !! Stage !! Description
|-
| u-boot-spl.stm32 || FSBL || U-Boot SPL binary with appended Device Tree and prepended STM32 image header<ref name="STM32 image header" />.
|-
| u-boot.itb || SSBL || U-Boot and Device Tree's contained in a signed FIT image.
|}

==== Generate key pair and sign U-Boot SPL for BootROM authentication ====

To sign the U-Boot SPL as SSBL image for authentication with the BootROM we have to use the STM32 tools <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight> and <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight>.

===== Generate key pair with <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight> =====

All STM32MP15 SoC's only support one key pair for authenticating images through the BootROM.
To generate ECDSA key pairs for the STM32MP Secure Boot we are using the tool <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight><ref name="KeyGen_tool" /> to generate a single key pair.
<syntaxhighlight lang="shell">
STM32MP_KeyGen_CLI --absolute-path "$(pwd)" --password 12345678
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Key Generator v2.9.0
-------------------------------------------------------------------

Prime256v1 curve is selected.
AES_256_cbc algorithm is selected for private key encryption
Generating Prime256v1 keys...
Private key PEM file created
Public key PEM file created
public key hash file created
Keys generated successfully.
+ public key: publicKey.pem
+ private key: privateKey.pem
+ public hash key: publicKeyhash.bin
</syntaxhighlight>

===== Sign U-Boot SPL with <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight> =====

To add the public key and the image signature to our built U-Boot SPL binary with STM32 image header, we are using the tool <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight><ref name="Signing_tool" /> to update the existing STM32 image header of <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> with the required details.
<syntaxhighlight lang="shell">
STM32MP_SigningTool_CLI --binary-image /path/to/u-boot/u-boot-spl.stm32 --public-key publicKey.pem --private-key privateKey.pem --password 12345678 --output /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Signing Tool v2.9.0
-------------------------------------------------------------------

Prime256v1 curve is selected.
Header version 1 preparation ...
Reading Private Key File...
ECDSA signature generated.
Signature verification: SUCCESS
The Signed image file generated successfully: /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>

You can check the STM32 image header details with:
<syntaxhighlight lang="shell">
STM32MP_SigningTool_CLI --dump-header /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Signing Tool v2.9.0
-------------------------------------------------------------------

Header description:

Magic: 0x53544d32
Signature: c8 30 a0 62 2d 6d 4e 1b b9 f7 fe 38 27 65 e0 44 f0 f5 9d e6 8a a6 02 cb 74 52 26 9c 1e e9 07 17
1a c7 da 8e 96 fa 82 d3 b1 dc d5 3a 05 0e 87 83 94 4d 47 ad 17 07 88 0d b5 ae 2e 38 1d 90 22 ad
Checksum: 0xa8ca85
Header version: 0x10000
Size: 0x22dec
Load address: 0x2ffc2500
Entry point: 0x2ffc2500
Image version: 0x0
Option flags: 0x0
ECDSA Algo: 0x1
ECDSA pub key: 3b 71 8e 59 f1 ee 4c a8 4b 72 5f 4a 1c 63 8b 6e b8 01 ec 1a 3f 8c 98 2f d2 1d 77 f9 09 10 8f 04
30 da 5c 3a 24 53 0d 71 93 f0 a5 d9 c9 a7 27 b4 5f a5 c4 4d 55 8b 7a 25 e3 03 ef ca 87 ff 04 25
Binary type: 0x0
</syntaxhighlight>
The difference to an unsigned STM32 image header is that the values for "Signature" and "ECDSA pub key" are not all zeros and that "Option flags" is 0x0 for enabled signature verification instead of 0x1 for disabled signature verification.

==== Write U-Boot SPL and U-Boot to your boot media ====

The first step to verify that the built U-Boot SPL and U-Boot works as expected is to program both images to your boot media.
Depending on the boot configuration, your DHSOM will boot from the module's SPI-NOR flash, from the module's or baseboard's eMMC or from an SD card.
The boot configuration is always defined by the boot pins by default, because the boot pins have no alternative function on the STM32MP15 SoC's.

<div style="color:red">TODO: How can a user determine the used boot media?</div>
<div style="color:red">TODO: How to enforce boot media on Secure Boot enabled devices?</div>

===== Write U-Boot SPL and U-Boot to the SPI-NOR flash of the SoM =====

The following '''commands for the U-Boot Shell''' calculate some addresses based on the image offsets expected by the BootROM, load the required images from SD card or via TFTP into memory and finally write the prepared memory into the SPI-NOR flash on the SoM.

Prepare for loading <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> into memory:
<syntaxhighlight lang="shell">
mw.b ${loadaddr} 0xff 0x200000
setexpr fsbl1addr ${loadaddr} + 0x0
setexpr fsbl2addr ${loadaddr} + 0x40000
setexpr ssbl1addr ${loadaddr} + 0x80000
</syntaxhighlight>

Load <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> from SD card:
<syntaxhighlight lang="shell">
load mmc 0:4 ${fsbl1addr} u-boot-spl.stm32
load mmc 0:4 ${fsbl2addr} u-boot-spl.stm32
load mmc 0:4 ${ssbl1addr} u-boot.itb
</syntaxhighlight>

Load <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> from tftp server:
<syntaxhighlight lang="shell">
setenv serverip 10.20.30.1
setenv ipaddr 10.20.30.100
setenv netmask 255.255.255.0
tftp ${fsbl1addr} ${serverip}:u-boot-spl.stm32
tftp ${fsbl2addr} ${serverip}:u-boot-spl.stm32
tftp ${ssbl1addr} ${serverip}:u-boot.itb
</syntaxhighlight>

Check for magic numbers of expected image headers and conditionally program the SPI-NOR flash:
<syntaxhighlight lang="shell">
if itest *${fsbl1addr} == 0x324d5453 && itest *${fsbl2addr} == 0x324d5453 && itest *${ssbl1addr} == 0xedfe0dd0; then
sf probe && sf update ${loadaddr} 0 0x200000
fi
</syntaxhighlight>

===== Write U-Boot SPL and U-Boot to an SD card =====

<div style="color:red">TODO:</div>


===== Write U-Boot SPL and U-Boot to the eMMC =====

<div style="color:red">TODO:</div>


==== Enroll, test and enforce BootROM image authentication ====

To enroll, test and enforce image authentication by the BootROM you need to program the PKH into the OTP of the STM32MP15 SoC.
The <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> file that you created in the [[#Generate key pair with STM32MP_KeyGen_CLI|Generate key pair with STM32MP_KeyGen_CLI]] step contains the PKH in binary format for use with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> U-Boot command.
If the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command does fail or is not available on the target U-Boot, you can also write the PKH manually with the more generic <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command into the OTP.

===== Program public key hash to eFuses =====

The following '''commands for the U-Boot Shell''' load the file <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> into memory and program the contained PKH to the OTP of the STM32MP15 SoC.
The used command <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> writes and locks the words of the OTP automatically without knowing anything about the OTP layout/addresses.
If this fails or the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command is not available, you can also write and lock the OTP with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command

====== Program <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> into OTP with <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command ======

Load <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> by SD card:
<syntaxhighlight lang="shell">
load mmc 0:4 ${loadaddr} publicKeyhash.bin
</syntaxhighlight>

Or load <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> by TFTP:
<syntaxhighlight lang="shell">
setenv serverip 10.20.30.1
setenv ipaddr 10.20.30.100
setenv netmask 255.255.255.0
tftp ${loadaddr} ${serverip}:publicKeyhash.bin
</syntaxhighlight>

Show the contents of <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight>:
<syntaxhighlight lang="shell">
stm32key read ${loadaddr}
</syntaxhighlight>
<syntaxhighlight lang="console">
Read KEY at 0xc2000000
OTP value 24: 4e31bbcd
OTP value 25: 51e827dd
OTP value 26: 3511f521
OTP value 27: fd9c11a2
OTP value 28: 5b997b82
OTP value 29: 8150adc5
OTP value 30: a9c68fa9
OTP value 31: 72a3ba74
</syntaxhighlight>

Write the contents of <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> to OTP with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command:
<syntaxhighlight lang="shell">
stm32key fuse ${loadaddr}
</syntaxhighlight>
<syntaxhighlight lang="console">
TODO: Add output
</syntaxhighlight>

====== Program PKH manually into OTP with <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command ======

Generate fuse command with hexdump from file <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> on linux host:
<div style="color:red">Warning: Do not use the example output! Only use your unique values for programming the PKH in the OTP!</div>
<syntaxhighlight lang="shell">
echo fuse prog -y 0 0x18 $(hexdump -e '/4 "0x"' -e '/1 "%x"' -e '" "' /path/to/publicKeyhash.bin)
</syntaxhighlight>
<syntaxhighlight lang="console">
fuse prog -y 0 0x18 0x4e31bbcd 0x51e827dd 0x3511f521 0xfd9c11a2 0x5b997b82 0x8150adc5 0xa9c68fa9 0x72a3ba74
</syntaxhighlight>

Write the PKH into OTP manually with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<div style="color:red">Warning: Do not use the example command! Only use your unique values for programming the PKH in the OTP!</div>
<syntaxhighlight lang="shell">
fuse prog -y 0 0x18 0x4e31bbcd 0x51e827dd 0x3511f521 0xfd9c11a2 0x5b997b82 0x8150adc5 0xa9c68fa9 0x72a3ba74
</syntaxhighlight>

Lock the related OTP words manually with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<syntaxhighlight lang="shell">
fuse prog -y 0 0x10000018 1 1 1 1 1 1 1 1
</syntaxhighlight>

===== Test BootROM image authentication =====

To verify the image authentication by the BootROM with the programmed PKH and the programmed signed images, you must reboot your device.

On the third line of the U-Boot SPL output, check the BootROM authentication status.
The status output should look like this: <syntaxhighlight lang="console" inline>Bootrom authentication: succeeded</syntaxhighlight>.
Note the <syntaxhighlight lang="console" inline>succeeded</syntaxhighlight> status for successful authentication of the U-Boot SPL image by the BootROM.

The following output shows successful authentication of the U-Boot-SPL image in line 3, as well as successful authentication of the used configuration in line 7 and the U-Boot and Device Tree subimages in lines 8 and 9 of the U-Boot-FIT image.
<syntaxhighlight lang="console" line highlight="3,7-9">
U-Boot SPL 2022.01-00012-g6c5892c90c28 (Feb 16 2022 - 11:11:16 +0100)
Model: STMicroelectronics STM32MP15xx DHCOM Premium Developer Kit (2)
Bootrom authentication: succeeded
Code: SoM:rev=1,ddr3=3 Board:rev=0
RAM: DDR3L 32bits 2x4Gb 533MHz
Trying to boot from SPI
## Checking hash(es) for config config-2 ... sha256,rsa4096:fsbl-cfg-2022-02-16+ OK
## Checking hash(es) for Image uboot ... sha256,rsa4096:fsbl-img-2022-02-16+ sha256+ OK
## Checking hash(es) for Image fdt-1 ... sha256,rsa4096:fsbl-img-2022-02-16+ sha256+ OK
</syntaxhighlight>

===== Enforce BootROM image authentication =====

Without any further changes, the BootROM is able to perform authentication of the FSBL image, but unauthenticated images can still be used and executed.
The device is still open, let's see this as a kind of test mode to check if the PKH is set correctly.

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

The 6th bit in the 1st word of the OTP is responsible that the BootROM only accepts signed images.
Burning this bit enforces authentication of images by the BootROM and unsigned binaries are no longer supported on the target device.

To program this bit, the U-Boot Shell can be used with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command or with the more general <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command.

With usage of the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command:
<div style="color:red">Warning: After running the following command, your device will only be able to boot signed images!</div>
<syntaxhighlight lang="shell">
stm32key close
</syntaxhighlight>

Or with usage of the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<div style="color:red">Warning: After running the following command, your device will only be able to boot signed images!</div>
<syntaxhighlight lang="shell">
fuse prog 0 0x0 0x40
</syntaxhighlight>

== Secure Boot in Trusted Boot with BootROM authentication, TF-A and OP-TEE ==

<div style="color:red">TODO:</div>
# Add support for STM32MP15 DHCOM in <ref name="TF-A" />
# Add support for STM32MP15 DHCOM in <ref name="OP-TEE/optee_os" />
# Create stm32mp15_dhcom_trusted_defconfig???
# Integrate STM32MP15 DHCOM into <ref name="OP-TEE/build" />

== References ==

<references>
<ref name="UEFI specification">[http://www.uefi.org/specifications http://www.uefi.org/specifications]</ref>
<ref name="Basic Boot">[https://source.denx.de/u-boot/u-boot/-/blob/master/configs/stm32mp15_basic_defconfig U-Boot Source stm32mp15_basic_defconfig]</ref>
<ref name="Trusted Boot">[https://source.denx.de/u-boot/u-boot/-/blob/master/configs/stm32mp15_trusted_defconfig U-Boot Source stm32mp15_trusted_defconfig]</ref>
<ref name="BSI TR-02102">[https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.pdf BSI - Technische Richtlinie, "Kryptographische Algorithmen und Schlüssellängen", BSI TR-02102-1]</ref>
<ref name="STM32 image header">[https://wiki.st.com/stm32mpu/wiki/STM32_header_for_binary_files STM32 header for binary files]</ref>
<ref name="KeyGen_tool">[https://wiki.st.com/stm32mpu/wiki/KeyGen_tool STM32MP KeyGen tool]</ref>
<ref name="Signing_tool">[https://wiki.st.com/stm32mpu/wiki/Signing_tool STM32MP Signing tool]</ref>
<ref name="TF-A">[https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/ Trusted Firmware-A (TF-A)]</ref>
<ref name="OP-TEE/optee_os">[https://github.com/OP-TEE/optee_os OP-TEE Trusted OS]</ref>
<ref name="OP-TEE/build">[https://github.com/OP-TEE/build Makefiles to use OP-TEE on various platforms]</ref>
</references>

DHCOM STM32MP15 Secure Boot

2022-03-22T09:06:33Z

Dkierner: Improve wording and correct grammar issue in section /* What is meant by Secure Boot with basic/trusted boot? */ including headline

<div class="toclimit-3">__TOC__</div>

== Introduction ==

=== Abbreviations ===

{| class="wikitable sortable"
|-
! Abbreviation !! Description
|-
| BSI || Bundesamt für Sicherheit in der Informationstechnik
|-
| CoM || Computer on module
|-
| FIT || Flattened Image Tree
|-
| FSBL || Fist Stage Bootloader (TF-A or U-Boot SPL)
|-
| OTP || One Time Programmable (eFuses)
|-
| PKH || Public Key Hash
|-
| ROM || Read-Only Memory
|-
| RSA || Rivest, Shamir und Adleman (asynchronous encryption)
|-
| SHA || Secure Hash Algorithm
|-
| SoC || System on chip
|-
| SoM || System on module
|-
| SSBL || Second Stage Bootloader (U-Boot)
|}

=== What does Secure Boot mean? ===

The term Secure Boot originally comes from the UEFI specification<ref name="UEFI specification" /> and describes a secure boot process in which only signed software is loaded and executed during the boot process.

Secure Boot is a necessary cornerstone for enforcing security mechanisms in a trusted computing environment.
Enforcing the execution of signed software only during the boot process, as long as the chain of trust is secure, can guarantee that said software is free from tampering, as any manipulation will invalidate the software's signature and prevent the software from being executed.

[[File:Secure Boot Generic en.png|600px|Secure Boot Generic]]

The figure [[Media:Secure Boot Generic en.png|Secure Boot Generic]] shows an example of a secure boot process that leads to a reset in the event of an error in the signature check. Each stage uses the certificate and signature to check the origin and integrity of the next stage. On success, the next stage is executed, and in the event of an error, this always leads to a defined error state. In the simplest case, the certificates are integrated into the binary image of the previous stage.

Program code and certificate need to be trustworthy and therefore protected against tampering in each stage, otherwise the secure boot chain can be compromised. Except for the first stage, all binary images are protected against third-party tampering by the signature. As this is practically impossible for the first stage, manipulation protection has to be enforced by hardware measures to make said stage immutable, with the first stage's program code and the verification certificate for the second stage being stored in read-only memory (ROM).

=== Basic and trusted boot in the context of Secure Boot ===

When booting Linux on the STM32MP1 SoC with U-Boot SPL and U-Boot only, STM speaks of "Basic Boot"<ref name="Basic Boot" />.
However, if Linux is booted with a combination of TF-A, U-Boot and OP-TEE, STM refers to this as "Trusted Boot"<ref name="Trusted Boot" />.

{| class="wikitable"
|-
! Boot chain !! Description
|-
| Basic boot || BootROM -> U-Boot SPL -> U-Boot -> Linux
|-
| Trusted boot || BootROM -> TF-A -> U-Boot + OP-TEE -> Linux
|}

== Secure Boot in Basic Boot with BootROM authentication and Verified Boot ==

This Secure Boot implementation does use the the BootROM integrated image authentication to authenticate the U-Boot SPL as FSBL.
Authentication of U-Boot as SSBL by the U-Boot SPL and authentication of the Linux kernel, Device Tree and ramdisk by U-Boot is done using the open source implementation [[#What is meant by Verified Boot?|Verified Boot]].

This also means that everything from U-Boot SPL onwards is platform independent, as we do not rely on hardware specific implementations.

=== What is meant by Verified Boot? ===

Developers of Google's Chromium project worked out a concept for the Verified Boot called Secure Boot mechanism on the basis of the boot loader "Das U-Boot".
They use the existing infrastructure of the FIT images and for the system configuration at runtime via a Device Tree.
The description language for the FIT images was extended by an additional signature node and the Device Tree of the platform was used to store the certificate(s) for the authentication of the images.
The signature node can be used to sign individual subimages as well as combinations of individual subimages in the FIT image.
The tool <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight> takes over the creation of the signatures in the FIT images and the addition of the certificate in a Device Tree.

With Verified Boot, the Device Tree with the included public key is integrated into the program image of the stage, which accomplishes the authentication and is thus very similar to the general procedure shown in figure [[Media:Secure Boot Generic en.png|Secure Boot Generic]].
The number of public keys that can be integrated is theoretically unlimited, but they must be distinguishable by name.

==== Technical details of Verified Boot ====

{| class="wikitable"
|-
| '''Name'''
| Verified Boot
|-
| '''Implementierung'''
| Software (Open Source)
|-
| '''Hash algorithms'''
|
* SHA1 (deprecated)<ref name="BSI TR-02102" />
* SHA256
* SHA384
* SHA512
|-
| '''Crypto algorithms
|
* RSA2048 (deprecated as of 2024)<ref name="BSI TR-02102" />
* RSA4096

* ECDSA256 (currently limited to U-Boot SPL)
|-
| '''Number of key pairs'''
| unlimited
|-
|}

==== In-depth references for Verified Boot ====


===== Flatten Image Tree =====
* [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT U-Boot Documentation: doc/uImage.FIT]
* [https://source.denx.de/u-boot/u-boot/-/commit/d5934ad7 U-Boot Commit d5934ad7: "new uImage: Add dual format uImage support framework"]
* ...
* [https://source.denx.de/u-boot/u-boot/-/commit/3310c549 U-Boot Commit d5934ad7: "new uImage: Add new uImage format documentation and examples"]

===== Verified Boot =====

* [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT/signature.txt U-Boot Documentation: doc/uImage.FIT/signature.txt]
* [https://source.denx.de/u-boot/u-boot/-/commit/3e569a6b U-Boot Commit 3e569a6b: "image: Add signing infrastructure"]
* [https://source.denx.de/u-boot/u-boot/-/commit/56518e71 U-Boot Commit 56518e71: "image: Support signing of images"]
* [https://source.denx.de/u-boot/u-boot/-/commit/4d098529 U-Boot Commit 4d098529: "image: Add support for signing of FIT configurations"]

===== ECDSA signature verification =====

<div style="color:red">TODO: Mention ECDSA limitations</div>
Note: This has currently some limitations!


* [https://source.denx.de/u-boot/u-boot/-/commit/928a8be7 U-Boot Commit 928a8be7: "lib: ecdsa: Implement UCLASS_ECDSA verification on target"]
* [https://source.denx.de/u-boot/u-boot/-/commit/ee870859 U-Boot Commit ee870859: "arm: stm32mp1: Implement ECDSA signature verification"]

=== Tutorial: Secure boot from BootROM to Linux with basic boot ===

==== System requirements and needed tools ====

The following table lists all requirements to create the key pairs and build the signed images with embedded public keys.

{| class="wikitable"
|-
! Category !! Description
|-
| '''Host operating system''' ||
* Linux (Debian 9, Ubuntu 18.04 or higher prefered)
|-
| '''Debian packages''' ||
* bison
* device-tree-compiler
* flex
* gcc-arm-linux-gnueabihf (>= gcc 6)
* git
* make
* openssl
|-
| '''STM32 Tools''' ||
* [https://www.st.com/en/development-tools/stm32cubeprog.html STM32CubeProgrammer]
** STM32MP_KeyGen_CLI
** STM32MP_SigningTool_CLI
|}

<div style="color:red">TODO: Should we give host setup instructions?</div>


==== Intended use of the four generated key pairs ====

We've decided to create and use as few certificates as reasonable to ensure a high level of security.
Therefore, we chose a separate key pair for each boot stage and also a separate key pair for image and configuration nodes.
If you're confused about the difference between image and configuration nodes, head over to [[#Flatten Image Tree|Flatten Image Tree]] to refresh your knowledge.
The exact purpose of the four key pairs generated for Verified Boot is described in the following table.

{| class="wikitable"
|-
! File name !! Intended use
|-
| '''fsbl-img''' || Authenticate image nodes of FIT images loaded by U-Boot SPL (U-Boot, Device Tree, firmware)
|-
| '''fsbl-cfg''' || Authenticate config nodes of FIT images loaded by U-Boot SPL (U-Boot + Device Tree + firmware)
|-
| '''ssbl-img''' || Authenticate image nodes of FIT images loaded by U-Boot (Kernel, Device Tree, InitRamFS)
|-
| '''ssbl-cfg''' || Authenticate config nodes of FIT images loaded by U-Boot (Kernel + Device Tree + InitRamFS)
|-
|}

==== Created/Modified files in the U-Boot source for Verified Boot ====

The created or modified files to build U-Boot with Verified Boot on STM32MP15 are described in the following table.

{| class="wikitable"
|-
! File
! Description
|-
| build_signed_uboot.sh
| Shell script that automates the creation of key pairs, the modification of FIT source files and Device Tree's and building of U-Boot SPL and U-Boot.
|-
| board/dhelectronics/dh_stm32mp1/u-boot-dhco?.its
| FIT source files with defined U-Boot image and Device Tree's for DHSOM platforms.
|-
| board/dhelectronics/dh_stm32mp1/linux-dhcom.its
| Dummy FIT source file with defined dummy kernel image and dummy Device Tree for DHSOM platforms.<br>To avoid relying on a built kernel image on a fixed path, we created this dummy, since adding the public keys with <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight> requires a valid FIT source file.
|-
| configs/stm32mp15_dhco?_secure_defconfig
| Example U-Boot defconfig's with enabled <syntaxhighlight lang="shell" inline>CONFIG_FIT_SIGNATURE</syntaxhighlight> and <syntaxhighlight lang="shell" inline>CONFIG_SPL_FIT_SIGNATURE</syntaxhighlight>.
|}

==== Build Verified Boot enabled U-Boot SPL and U-Boot ====

To build the U-Boot SPL and U-Boot images, you need to check out the source code and run a build script that automates everything from key generation to image creation and signing.

===== Checkout source code for Verified Boot =====

<div style="color:red">TODO: Replace my personal GitLab by a public available repository</div>
Checkout the branch <syntaxhighlight lang="shell" inline>v2022.01_dhcom_secure_boot</syntaxhighlight> of my personal GitLab repository with:

<syntaxhighlight lang="shell">
git clone git@dhplgl01:jneuhauser/u-boot.git -b v2022.01_dhcom_secure_boot
</syntaxhighlight>

If you already have a cloned U-Boot source code, you can also fetch it into your existing repository with:

<syntaxhighlight lang="shell">
cd /path/to/u-boot
git remote add jneuhauser git@dhplgl01:jneuhauser/u-boot.git
git fetch jneuhauser
git checkout v2022.01_dhcom_secure_boot
</syntaxhighlight>

===== Run the build script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> =====

The shell script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> included in the U-Boot source performs the following steps.
# Prebuild U-Boat SPL and U-Boat to build the required tools and Device Tree's
# Generate the [[#Intended use of the four generated key pairs|four key pairs]] if not already created
# Generate/Modify FIT image source files for Linux (dummy) and U-Boot
# Add public keys to the built Device Tree's used by U-Boot SPL and U-Boot
# Rebuild U-Boot SPL and U-Boot with new Device Tree's containing the public keys

The script supports the following environment variables to configure the target architecture, the cross compiler, the defconfig, the key algorithm, the key directory, and a key postfix.
{| class="wikitable sortable"
|-
! Name !! Description !! Default
|-
| ARCH || Target architecture for the U-Boot build || arm
|-
| CROSS_COMPILE || Used cross compiler to build U-Boot || arm-linux-gnueabihf-
|-
| DEFCONFIG || Used defconfig for the U-Boot build || stm32mp15_dhcom_secure_defconfig
|-
| KEY_ALGO || Signature algorithm used for Verified Boot || rsa
|-
| KEY_DIR || Directory where the key pairs are stored || ../keys
|-
| KEY_POSTFIX || Postfix which is appended to the key names || -$(date +%F)
|}

To perform the steps mentioned above, you just need to run the shell script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> like below.
In this example, we override the default value for <syntaxhighlight lang="shell" inline>KEY_POSTFIX</syntaxhighlight> with <syntaxhighlight lang="shell" inline>-testing</syntaxhighlight> to append this string to the [[#Intended use of the four generated key pairs|four key file names]].
The script has debug output enabled by default, which should output all the statements in the script itself and the output of the commands used in the script.
If you have any problems with the script, feel free to get in touch with the script author [mailto:jneuhauser@dh-electronics.com Johann Neuhauser] and attach a logfile.

<syntaxhighlight lang="shell">
cd /path/to/u-boot
KEY_POSTFIX="-testing" ./build_signed_uboot.sh | tee build_signed_uboot.log
</syntaxhighlight>

If this process completes without error, there are two boot loader images in the root directory of the U-Boot source.
{| class="wikitable sortable"
|-
! File name !! Stage !! Description
|-
| u-boot-spl.stm32 || FSBL || U-Boot SPL binary with appended Device Tree and prepended STM32 image header<ref name="STM32 image header" />.
|-
| u-boot.itb || SSBL || U-Boot and Device Tree's contained in a signed FIT image.
|}

==== Generate key pair and sign U-Boot SPL for BootROM authentication ====

To sign the U-Boot SPL as SSBL image for authentication with the BootROM we have to use the STM32 tools <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight> and <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight>.

===== Generate key pair with <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight> =====

All STM32MP15 SoC's only support one key pair for authenticating images through the BootROM.
To generate ECDSA key pairs for the STM32MP Secure Boot we are using the tool <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight><ref name="KeyGen_tool" /> to generate a single key pair.
<syntaxhighlight lang="shell">
STM32MP_KeyGen_CLI --absolute-path "$(pwd)" --password 12345678
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Key Generator v2.9.0
-------------------------------------------------------------------

Prime256v1 curve is selected.
AES_256_cbc algorithm is selected for private key encryption
Generating Prime256v1 keys...
Private key PEM file created
Public key PEM file created
public key hash file created
Keys generated successfully.
+ public key: publicKey.pem
+ private key: privateKey.pem
+ public hash key: publicKeyhash.bin
</syntaxhighlight>

===== Sign U-Boot SPL with <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight> =====

To add the public key and the image signature to our built U-Boot SPL binary with STM32 image header, we are using the tool <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight><ref name="Signing_tool" /> to update the existing STM32 image header of <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> with the required details.
<syntaxhighlight lang="shell">
STM32MP_SigningTool_CLI --binary-image /path/to/u-boot/u-boot-spl.stm32 --public-key publicKey.pem --private-key privateKey.pem --password 12345678 --output /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Signing Tool v2.9.0
-------------------------------------------------------------------

Prime256v1 curve is selected.
Header version 1 preparation ...
Reading Private Key File...
ECDSA signature generated.
Signature verification: SUCCESS
The Signed image file generated successfully: /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>

You can check the STM32 image header details with:
<syntaxhighlight lang="shell">
STM32MP_SigningTool_CLI --dump-header /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Signing Tool v2.9.0
-------------------------------------------------------------------

Header description:

Magic: 0x53544d32
Signature: c8 30 a0 62 2d 6d 4e 1b b9 f7 fe 38 27 65 e0 44 f0 f5 9d e6 8a a6 02 cb 74 52 26 9c 1e e9 07 17
1a c7 da 8e 96 fa 82 d3 b1 dc d5 3a 05 0e 87 83 94 4d 47 ad 17 07 88 0d b5 ae 2e 38 1d 90 22 ad
Checksum: 0xa8ca85
Header version: 0x10000
Size: 0x22dec
Load address: 0x2ffc2500
Entry point: 0x2ffc2500
Image version: 0x0
Option flags: 0x0
ECDSA Algo: 0x1
ECDSA pub key: 3b 71 8e 59 f1 ee 4c a8 4b 72 5f 4a 1c 63 8b 6e b8 01 ec 1a 3f 8c 98 2f d2 1d 77 f9 09 10 8f 04
30 da 5c 3a 24 53 0d 71 93 f0 a5 d9 c9 a7 27 b4 5f a5 c4 4d 55 8b 7a 25 e3 03 ef ca 87 ff 04 25
Binary type: 0x0
</syntaxhighlight>
The difference to an unsigned STM32 image header is that the values for "Signature" and "ECDSA pub key" are not all zeros and that "Option flags" is 0x0 for enabled signature verification instead of 0x1 for disabled signature verification.

==== Write U-Boot SPL and U-Boot to your boot media ====

The first step to verify that the built U-Boot SPL and U-Boot works as expected is to program both images to your boot media.
Depending on the boot configuration, your DHSOM will boot from the module's SPI-NOR flash, from the module's or baseboard's eMMC or from an SD card.
The boot configuration is always defined by the boot pins by default, because the boot pins have no alternative function on the STM32MP15 SoC's.

<div style="color:red">TODO: How can a user determine the used boot media?</div>
<div style="color:red">TODO: How to enforce boot media on Secure Boot enabled devices?</div>

===== Write U-Boot SPL and U-Boot to the SPI-NOR flash of the SoM =====

The following '''commands for the U-Boot Shell''' calculate some addresses based on the image offsets expected by the BootROM, load the required images from SD card or via TFTP into memory and finally write the prepared memory into the SPI-NOR flash on the SoM.

Prepare for loading <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> into memory:
<syntaxhighlight lang="shell">
mw.b ${loadaddr} 0xff 0x200000
setexpr fsbl1addr ${loadaddr} + 0x0
setexpr fsbl2addr ${loadaddr} + 0x40000
setexpr ssbl1addr ${loadaddr} + 0x80000
</syntaxhighlight>

Load <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> from SD card:
<syntaxhighlight lang="shell">
load mmc 0:4 ${fsbl1addr} u-boot-spl.stm32
load mmc 0:4 ${fsbl2addr} u-boot-spl.stm32
load mmc 0:4 ${ssbl1addr} u-boot.itb
</syntaxhighlight>

Load <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> from tftp server:
<syntaxhighlight lang="shell">
setenv serverip 10.20.30.1
setenv ipaddr 10.20.30.100
setenv netmask 255.255.255.0
tftp ${fsbl1addr} ${serverip}:u-boot-spl.stm32
tftp ${fsbl2addr} ${serverip}:u-boot-spl.stm32
tftp ${ssbl1addr} ${serverip}:u-boot.itb
</syntaxhighlight>

Check for magic numbers of expected image headers and conditionally program the SPI-NOR flash:
<syntaxhighlight lang="shell">
if itest *${fsbl1addr} == 0x324d5453 && itest *${fsbl2addr} == 0x324d5453 && itest *${ssbl1addr} == 0xedfe0dd0; then
sf probe && sf update ${loadaddr} 0 0x200000
fi
</syntaxhighlight>

===== Write U-Boot SPL and U-Boot to an SD card =====

<div style="color:red">TODO:</div>


===== Write U-Boot SPL and U-Boot to the eMMC =====

<div style="color:red">TODO:</div>


==== Enroll, test and enforce BootROM image authentication ====

To enroll, test and enforce image authentication by the BootROM you need to program the PKH into the OTP of the STM32MP15 SoC.
The <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> file that you created in the [[#Generate key pair with STM32MP_KeyGen_CLI|Generate key pair with STM32MP_KeyGen_CLI]] step contains the PKH in binary format for use with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> U-Boot command.
If the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command does fail or is not available on the target U-Boot, you can also write the PKH manually with the more generic <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command into the OTP.

===== Program public key hash to eFuses =====

The following '''commands for the U-Boot Shell''' load the file <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> into memory and program the contained PKH to the OTP of the STM32MP15 SoC.
The used command <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> writes and locks the words of the OTP automatically without knowing anything about the OTP layout/addresses.
If this fails or the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command is not available, you can also write and lock the OTP with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command

====== Program <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> into OTP with <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command ======

Load <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> by SD card:
<syntaxhighlight lang="shell">
load mmc 0:4 ${loadaddr} publicKeyhash.bin
</syntaxhighlight>

Or load <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> by TFTP:
<syntaxhighlight lang="shell">
setenv serverip 10.20.30.1
setenv ipaddr 10.20.30.100
setenv netmask 255.255.255.0
tftp ${loadaddr} ${serverip}:publicKeyhash.bin
</syntaxhighlight>

Show the contents of <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight>:
<syntaxhighlight lang="shell">
stm32key read ${loadaddr}
</syntaxhighlight>
<syntaxhighlight lang="console">
Read KEY at 0xc2000000
OTP value 24: 4e31bbcd
OTP value 25: 51e827dd
OTP value 26: 3511f521
OTP value 27: fd9c11a2
OTP value 28: 5b997b82
OTP value 29: 8150adc5
OTP value 30: a9c68fa9
OTP value 31: 72a3ba74
</syntaxhighlight>

Write the contents of <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> to OTP with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command:
<syntaxhighlight lang="shell">
stm32key fuse ${loadaddr}
</syntaxhighlight>
<syntaxhighlight lang="console">
TODO: Add output
</syntaxhighlight>

====== Program PKH manually into OTP with <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command ======

Generate fuse command with hexdump from file <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> on linux host:
<div style="color:red">Warning: Do not use the example output! Only use your unique values for programming the PKH in the OTP!</div>
<syntaxhighlight lang="shell">
echo fuse prog -y 0 0x18 $(hexdump -e '/4 "0x"' -e '/1 "%x"' -e '" "' /path/to/publicKeyhash.bin)
</syntaxhighlight>
<syntaxhighlight lang="console">
fuse prog -y 0 0x18 0x4e31bbcd 0x51e827dd 0x3511f521 0xfd9c11a2 0x5b997b82 0x8150adc5 0xa9c68fa9 0x72a3ba74
</syntaxhighlight>

Write the PKH into OTP manually with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<div style="color:red">Warning: Do not use the example command! Only use your unique values for programming the PKH in the OTP!</div>
<syntaxhighlight lang="shell">
fuse prog -y 0 0x18 0x4e31bbcd 0x51e827dd 0x3511f521 0xfd9c11a2 0x5b997b82 0x8150adc5 0xa9c68fa9 0x72a3ba74
</syntaxhighlight>

Lock the related OTP words manually with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<syntaxhighlight lang="shell">
fuse prog -y 0 0x10000018 1 1 1 1 1 1 1 1
</syntaxhighlight>

===== Test BootROM image authentication =====

To verify the image authentication by the BootROM with the programmed PKH and the programmed signed images, you must reboot your device.

On the third line of the U-Boot SPL output, check the BootROM authentication status.
The status output should look like this: <syntaxhighlight lang="console" inline>Bootrom authentication: succeeded</syntaxhighlight>.
Note the <syntaxhighlight lang="console" inline>succeeded</syntaxhighlight> status for successful authentication of the U-Boot SPL image by the BootROM.

The following output shows successful authentication of the U-Boot-SPL image in line 3, as well as successful authentication of the used configuration in line 7 and the U-Boot and Device Tree subimages in lines 8 and 9 of the U-Boot-FIT image.
<syntaxhighlight lang="console" line highlight="3,7-9">
U-Boot SPL 2022.01-00012-g6c5892c90c28 (Feb 16 2022 - 11:11:16 +0100)
Model: STMicroelectronics STM32MP15xx DHCOM Premium Developer Kit (2)
Bootrom authentication: succeeded
Code: SoM:rev=1,ddr3=3 Board:rev=0
RAM: DDR3L 32bits 2x4Gb 533MHz
Trying to boot from SPI
## Checking hash(es) for config config-2 ... sha256,rsa4096:fsbl-cfg-2022-02-16+ OK
## Checking hash(es) for Image uboot ... sha256,rsa4096:fsbl-img-2022-02-16+ sha256+ OK
## Checking hash(es) for Image fdt-1 ... sha256,rsa4096:fsbl-img-2022-02-16+ sha256+ OK
</syntaxhighlight>

===== Enforce BootROM image authentication =====

Without any further changes, the BootROM is able to perform authentication of the FSBL image, but unauthenticated images can still be used and executed.
The device is still open, let's see this as a kind of test mode to check if the PKH is set correctly.

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

The 6th bit in the 1st word of the OTP is responsible that the BootROM only accepts signed images.
Burning this bit enforces authentication of images by the BootROM and unsigned binaries are no longer supported on the target device.

To program this bit, the U-Boot Shell can be used with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command or with the more general <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command.

With usage of the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command:
<div style="color:red">Warning: After running the following command, your device will only be able to boot signed images!</div>
<syntaxhighlight lang="shell">
stm32key close
</syntaxhighlight>

Or with usage of the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<div style="color:red">Warning: After running the following command, your device will only be able to boot signed images!</div>
<syntaxhighlight lang="shell">
fuse prog 0 0x0 0x40
</syntaxhighlight>

== Secure Boot in Trusted Boot with BootROM authentication, TF-A and OP-TEE ==

<div style="color:red">TODO:</div>
# Add support for STM32MP15 DHCOM in <ref name="TF-A" />
# Add support for STM32MP15 DHCOM in <ref name="OP-TEE/optee_os" />
# Create stm32mp15_dhcom_trusted_defconfig???
# Integrate STM32MP15 DHCOM into <ref name="OP-TEE/build" />

== References ==

<references>
<ref name="UEFI specification">[http://www.uefi.org/specifications http://www.uefi.org/specifications]</ref>
<ref name="Basic Boot">[https://source.denx.de/u-boot/u-boot/-/blob/master/configs/stm32mp15_basic_defconfig U-Boot Source stm32mp15_basic_defconfig]</ref>
<ref name="Trusted Boot">[https://source.denx.de/u-boot/u-boot/-/blob/master/configs/stm32mp15_trusted_defconfig U-Boot Source stm32mp15_trusted_defconfig]</ref>
<ref name="BSI TR-02102">[https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.pdf BSI - Technische Richtlinie, "Kryptographische Algorithmen und Schlüssellängen", BSI TR-02102-1]</ref>
<ref name="STM32 image header">[https://wiki.st.com/stm32mpu/wiki/STM32_header_for_binary_files STM32 header for binary files]</ref>
<ref name="KeyGen_tool">[https://wiki.st.com/stm32mpu/wiki/KeyGen_tool STM32MP KeyGen tool]</ref>
<ref name="Signing_tool">[https://wiki.st.com/stm32mpu/wiki/Signing_tool STM32MP Signing tool]</ref>
<ref name="TF-A">[https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/ Trusted Firmware-A (TF-A)]</ref>
<ref name="OP-TEE/optee_os">[https://github.com/OP-TEE/optee_os OP-TEE Trusted OS]</ref>
<ref name="OP-TEE/build">[https://github.com/OP-TEE/build Makefiles to use OP-TEE on various platforms]</ref>
</references>

DHCOM STM32MP15 Secure Boot

2022-03-22T09:00:50Z

Dkierner: Improve wording of section "What is meant by Secure Boot?" including headline

<div class="toclimit-3">__TOC__</div>

== Introduction ==

=== Abbreviations ===

{| class="wikitable sortable"
|-
! Abbreviation !! Description
|-
| BSI || Bundesamt für Sicherheit in der Informationstechnik
|-
| CoM || Computer on module
|-
| FIT || Flattened Image Tree
|-
| FSBL || Fist Stage Bootloader (TF-A or U-Boot SPL)
|-
| OTP || One Time Programmable (eFuses)
|-
| PKH || Public Key Hash
|-
| ROM || Read-Only Memory
|-
| RSA || Rivest, Shamir und Adleman (asynchronous encryption)
|-
| SHA || Secure Hash Algorithm
|-
| SoC || System on chip
|-
| SoM || System on module
|-
| SSBL || Second Stage Bootloader (U-Boot)
|}

=== What does Secure Boot mean? ===

The term Secure Boot originally comes from the UEFI specification<ref name="UEFI specification" /> and describes a secure boot process in which only signed software is loaded and executed during the boot process.

Secure Boot is a necessary cornerstone for enforcing security mechanisms in a trusted computing environment.
Enforcing the execution of signed software only during the boot process, as long as the chain of trust is secure, can guarantee that said software is free from tampering, as any manipulation will invalidate the software's signature and prevent the software from being executed.

[[File:Secure Boot Generic en.png|600px|Secure Boot Generic]]

The figure [[Media:Secure Boot Generic en.png|Secure Boot Generic]] shows an example of a secure boot process that leads to a reset in the event of an error in the signature check. Each stage uses the certificate and signature to check the origin and integrity of the next stage. On success, the next stage is executed, and in the event of an error, this always leads to a defined error state. In the simplest case, the certificates are integrated into the binary image of the previous stage.

Program code and certificate need to be trustworthy and therefore protected against tampering in each stage, otherwise the secure boot chain can be compromised. Except for the first stage, all binary images are protected against third-party tampering by the signature. As this is practically impossible for the first stage, manipulation protection has to be enforced by hardware measures to make said stage immutable, with the first stage's program code and the verification certificate for the second stage being stored in read-only memory (ROM).

=== What is meant by Secure Boot with basic/trusted boot? ===

When booting Linux on the STM32MP1 SoC's with U-Boot SPL and U-Boot only, STM speaks of "Basic Boot"<ref name="Basic Boot" />.
However, if Linux is booted with a combination of TF-A, U-Boot and OP-TEE, STM refers to this as "Trusted Boot"<ref name="Trusted Boot" />.

{| class="wikitable"
|-
! Boot chain !! Description
|-
| Basic boot || BootROM -> U-Boot SPL -> U-Boot -> Linux
|-
| Trusted boot || BootROM -> TF-A -> U-Boot + OP-TEE -> Linux
|}

== Secure Boot in Basic Boot with BootROM authentication and Verified Boot ==

This Secure Boot implementation does use the the BootROM integrated image authentication to authenticate the U-Boot SPL as FSBL.
Authentication of U-Boot as SSBL by the U-Boot SPL and authentication of the Linux kernel, Device Tree and ramdisk by U-Boot is done using the open source implementation [[#What is meant by Verified Boot?|Verified Boot]].

This also means that everything from U-Boot SPL onwards is platform independent, as we do not rely on hardware specific implementations.

=== What is meant by Verified Boot? ===

Developers of Google's Chromium project worked out a concept for the Verified Boot called Secure Boot mechanism on the basis of the boot loader "Das U-Boot".
They use the existing infrastructure of the FIT images and for the system configuration at runtime via a Device Tree.
The description language for the FIT images was extended by an additional signature node and the Device Tree of the platform was used to store the certificate(s) for the authentication of the images.
The signature node can be used to sign individual subimages as well as combinations of individual subimages in the FIT image.
The tool <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight> takes over the creation of the signatures in the FIT images and the addition of the certificate in a Device Tree.

With Verified Boot, the Device Tree with the included public key is integrated into the program image of the stage, which accomplishes the authentication and is thus very similar to the general procedure shown in figure [[Media:Secure Boot Generic en.png|Secure Boot Generic]].
The number of public keys that can be integrated is theoretically unlimited, but they must be distinguishable by name.

==== Technical details of Verified Boot ====

{| class="wikitable"
|-
| '''Name'''
| Verified Boot
|-
| '''Implementierung'''
| Software (Open Source)
|-
| '''Hash algorithms'''
|
* SHA1 (deprecated)<ref name="BSI TR-02102" />
* SHA256
* SHA384
* SHA512
|-
| '''Crypto algorithms
|
* RSA2048 (deprecated as of 2024)<ref name="BSI TR-02102" />
* RSA4096

* ECDSA256 (currently limited to U-Boot SPL)
|-
| '''Number of key pairs'''
| unlimited
|-
|}

==== In-depth references for Verified Boot ====


===== Flatten Image Tree =====
* [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT U-Boot Documentation: doc/uImage.FIT]
* [https://source.denx.de/u-boot/u-boot/-/commit/d5934ad7 U-Boot Commit d5934ad7: "new uImage: Add dual format uImage support framework"]
* ...
* [https://source.denx.de/u-boot/u-boot/-/commit/3310c549 U-Boot Commit d5934ad7: "new uImage: Add new uImage format documentation and examples"]

===== Verified Boot =====

* [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT/signature.txt U-Boot Documentation: doc/uImage.FIT/signature.txt]
* [https://source.denx.de/u-boot/u-boot/-/commit/3e569a6b U-Boot Commit 3e569a6b: "image: Add signing infrastructure"]
* [https://source.denx.de/u-boot/u-boot/-/commit/56518e71 U-Boot Commit 56518e71: "image: Support signing of images"]
* [https://source.denx.de/u-boot/u-boot/-/commit/4d098529 U-Boot Commit 4d098529: "image: Add support for signing of FIT configurations"]

===== ECDSA signature verification =====

<div style="color:red">TODO: Mention ECDSA limitations</div>
Note: This has currently some limitations!


* [https://source.denx.de/u-boot/u-boot/-/commit/928a8be7 U-Boot Commit 928a8be7: "lib: ecdsa: Implement UCLASS_ECDSA verification on target"]
* [https://source.denx.de/u-boot/u-boot/-/commit/ee870859 U-Boot Commit ee870859: "arm: stm32mp1: Implement ECDSA signature verification"]

=== Tutorial: Secure boot from BootROM to Linux with basic boot ===

==== System requirements and needed tools ====

The following table lists all requirements to create the key pairs and build the signed images with embedded public keys.

{| class="wikitable"
|-
! Category !! Description
|-
| '''Host operating system''' ||
* Linux (Debian 9, Ubuntu 18.04 or higher prefered)
|-
| '''Debian packages''' ||
* bison
* device-tree-compiler
* flex
* gcc-arm-linux-gnueabihf (>= gcc 6)
* git
* make
* openssl
|-
| '''STM32 Tools''' ||
* [https://www.st.com/en/development-tools/stm32cubeprog.html STM32CubeProgrammer]
** STM32MP_KeyGen_CLI
** STM32MP_SigningTool_CLI
|}

<div style="color:red">TODO: Should we give host setup instructions?</div>


==== Intended use of the four generated key pairs ====

We've decided to create and use as few certificates as reasonable to ensure a high level of security.
Therefore, we chose a separate key pair for each boot stage and also a separate key pair for image and configuration nodes.
If you're confused about the difference between image and configuration nodes, head over to [[#Flatten Image Tree|Flatten Image Tree]] to refresh your knowledge.
The exact purpose of the four key pairs generated for Verified Boot is described in the following table.

{| class="wikitable"
|-
! File name !! Intended use
|-
| '''fsbl-img''' || Authenticate image nodes of FIT images loaded by U-Boot SPL (U-Boot, Device Tree, firmware)
|-
| '''fsbl-cfg''' || Authenticate config nodes of FIT images loaded by U-Boot SPL (U-Boot + Device Tree + firmware)
|-
| '''ssbl-img''' || Authenticate image nodes of FIT images loaded by U-Boot (Kernel, Device Tree, InitRamFS)
|-
| '''ssbl-cfg''' || Authenticate config nodes of FIT images loaded by U-Boot (Kernel + Device Tree + InitRamFS)
|-
|}

==== Created/Modified files in the U-Boot source for Verified Boot ====

The created or modified files to build U-Boot with Verified Boot on STM32MP15 are described in the following table.

{| class="wikitable"
|-
! File
! Description
|-
| build_signed_uboot.sh
| Shell script that automates the creation of key pairs, the modification of FIT source files and Device Tree's and building of U-Boot SPL and U-Boot.
|-
| board/dhelectronics/dh_stm32mp1/u-boot-dhco?.its
| FIT source files with defined U-Boot image and Device Tree's for DHSOM platforms.
|-
| board/dhelectronics/dh_stm32mp1/linux-dhcom.its
| Dummy FIT source file with defined dummy kernel image and dummy Device Tree for DHSOM platforms.<br>To avoid relying on a built kernel image on a fixed path, we created this dummy, since adding the public keys with <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight> requires a valid FIT source file.
|-
| configs/stm32mp15_dhco?_secure_defconfig
| Example U-Boot defconfig's with enabled <syntaxhighlight lang="shell" inline>CONFIG_FIT_SIGNATURE</syntaxhighlight> and <syntaxhighlight lang="shell" inline>CONFIG_SPL_FIT_SIGNATURE</syntaxhighlight>.
|}

==== Build Verified Boot enabled U-Boot SPL and U-Boot ====

To build the U-Boot SPL and U-Boot images, you need to check out the source code and run a build script that automates everything from key generation to image creation and signing.

===== Checkout source code for Verified Boot =====

<div style="color:red">TODO: Replace my personal GitLab by a public available repository</div>
Checkout the branch <syntaxhighlight lang="shell" inline>v2022.01_dhcom_secure_boot</syntaxhighlight> of my personal GitLab repository with:

<syntaxhighlight lang="shell">
git clone git@dhplgl01:jneuhauser/u-boot.git -b v2022.01_dhcom_secure_boot
</syntaxhighlight>

If you already have a cloned U-Boot source code, you can also fetch it into your existing repository with:

<syntaxhighlight lang="shell">
cd /path/to/u-boot
git remote add jneuhauser git@dhplgl01:jneuhauser/u-boot.git
git fetch jneuhauser
git checkout v2022.01_dhcom_secure_boot
</syntaxhighlight>

===== Run the build script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> =====

The shell script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> included in the U-Boot source performs the following steps.
# Prebuild U-Boat SPL and U-Boat to build the required tools and Device Tree's
# Generate the [[#Intended use of the four generated key pairs|four key pairs]] if not already created
# Generate/Modify FIT image source files for Linux (dummy) and U-Boot
# Add public keys to the built Device Tree's used by U-Boot SPL and U-Boot
# Rebuild U-Boot SPL and U-Boot with new Device Tree's containing the public keys

The script supports the following environment variables to configure the target architecture, the cross compiler, the defconfig, the key algorithm, the key directory, and a key postfix.
{| class="wikitable sortable"
|-
! Name !! Description !! Default
|-
| ARCH || Target architecture for the U-Boot build || arm
|-
| CROSS_COMPILE || Used cross compiler to build U-Boot || arm-linux-gnueabihf-
|-
| DEFCONFIG || Used defconfig for the U-Boot build || stm32mp15_dhcom_secure_defconfig
|-
| KEY_ALGO || Signature algorithm used for Verified Boot || rsa
|-
| KEY_DIR || Directory where the key pairs are stored || ../keys
|-
| KEY_POSTFIX || Postfix which is appended to the key names || -$(date +%F)
|}

To perform the steps mentioned above, you just need to run the shell script <syntaxhighlight lang="shell" inline>build_signed_uboot.sh</syntaxhighlight> like below.
In this example, we override the default value for <syntaxhighlight lang="shell" inline>KEY_POSTFIX</syntaxhighlight> with <syntaxhighlight lang="shell" inline>-testing</syntaxhighlight> to append this string to the [[#Intended use of the four generated key pairs|four key file names]].
The script has debug output enabled by default, which should output all the statements in the script itself and the output of the commands used in the script.
If you have any problems with the script, feel free to get in touch with the script author [mailto:jneuhauser@dh-electronics.com Johann Neuhauser] and attach a logfile.

<syntaxhighlight lang="shell">
cd /path/to/u-boot
KEY_POSTFIX="-testing" ./build_signed_uboot.sh | tee build_signed_uboot.log
</syntaxhighlight>

If this process completes without error, there are two boot loader images in the root directory of the U-Boot source.
{| class="wikitable sortable"
|-
! File name !! Stage !! Description
|-
| u-boot-spl.stm32 || FSBL || U-Boot SPL binary with appended Device Tree and prepended STM32 image header<ref name="STM32 image header" />.
|-
| u-boot.itb || SSBL || U-Boot and Device Tree's contained in a signed FIT image.
|}

==== Generate key pair and sign U-Boot SPL for BootROM authentication ====

To sign the U-Boot SPL as SSBL image for authentication with the BootROM we have to use the STM32 tools <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight> and <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight>.

===== Generate key pair with <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight> =====

All STM32MP15 SoC's only support one key pair for authenticating images through the BootROM.
To generate ECDSA key pairs for the STM32MP Secure Boot we are using the tool <syntaxhighlight lang="shell" inline>STM32MP_KeyGen_CLI</syntaxhighlight><ref name="KeyGen_tool" /> to generate a single key pair.
<syntaxhighlight lang="shell">
STM32MP_KeyGen_CLI --absolute-path "$(pwd)" --password 12345678
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Key Generator v2.9.0
-------------------------------------------------------------------

Prime256v1 curve is selected.
AES_256_cbc algorithm is selected for private key encryption
Generating Prime256v1 keys...
Private key PEM file created
Public key PEM file created
public key hash file created
Keys generated successfully.
+ public key: publicKey.pem
+ private key: privateKey.pem
+ public hash key: publicKeyhash.bin
</syntaxhighlight>

===== Sign U-Boot SPL with <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight> =====

To add the public key and the image signature to our built U-Boot SPL binary with STM32 image header, we are using the tool <syntaxhighlight lang="shell" inline>STM32MP_SigningTool_CLI</syntaxhighlight><ref name="Signing_tool" /> to update the existing STM32 image header of <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> with the required details.
<syntaxhighlight lang="shell">
STM32MP_SigningTool_CLI --binary-image /path/to/u-boot/u-boot-spl.stm32 --public-key publicKey.pem --private-key privateKey.pem --password 12345678 --output /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Signing Tool v2.9.0
-------------------------------------------------------------------

Prime256v1 curve is selected.
Header version 1 preparation ...
Reading Private Key File...
ECDSA signature generated.
Signature verification: SUCCESS
The Signed image file generated successfully: /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>

You can check the STM32 image header details with:
<syntaxhighlight lang="shell">
STM32MP_SigningTool_CLI --dump-header /path/to/u-boot/u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-------------------------------------------------------------------
STM32MP Signing Tool v2.9.0
-------------------------------------------------------------------

Header description:

Magic: 0x53544d32
Signature: c8 30 a0 62 2d 6d 4e 1b b9 f7 fe 38 27 65 e0 44 f0 f5 9d e6 8a a6 02 cb 74 52 26 9c 1e e9 07 17
1a c7 da 8e 96 fa 82 d3 b1 dc d5 3a 05 0e 87 83 94 4d 47 ad 17 07 88 0d b5 ae 2e 38 1d 90 22 ad
Checksum: 0xa8ca85
Header version: 0x10000
Size: 0x22dec
Load address: 0x2ffc2500
Entry point: 0x2ffc2500
Image version: 0x0
Option flags: 0x0
ECDSA Algo: 0x1
ECDSA pub key: 3b 71 8e 59 f1 ee 4c a8 4b 72 5f 4a 1c 63 8b 6e b8 01 ec 1a 3f 8c 98 2f d2 1d 77 f9 09 10 8f 04
30 da 5c 3a 24 53 0d 71 93 f0 a5 d9 c9 a7 27 b4 5f a5 c4 4d 55 8b 7a 25 e3 03 ef ca 87 ff 04 25
Binary type: 0x0
</syntaxhighlight>
The difference to an unsigned STM32 image header is that the values for "Signature" and "ECDSA pub key" are not all zeros and that "Option flags" is 0x0 for enabled signature verification instead of 0x1 for disabled signature verification.

==== Write U-Boot SPL and U-Boot to your boot media ====

The first step to verify that the built U-Boot SPL and U-Boot works as expected is to program both images to your boot media.
Depending on the boot configuration, your DHSOM will boot from the module's SPI-NOR flash, from the module's or baseboard's eMMC or from an SD card.
The boot configuration is always defined by the boot pins by default, because the boot pins have no alternative function on the STM32MP15 SoC's.

<div style="color:red">TODO: How can a user determine the used boot media?</div>
<div style="color:red">TODO: How to enforce boot media on Secure Boot enabled devices?</div>

===== Write U-Boot SPL and U-Boot to the SPI-NOR flash of the SoM =====

The following '''commands for the U-Boot Shell''' calculate some addresses based on the image offsets expected by the BootROM, load the required images from SD card or via TFTP into memory and finally write the prepared memory into the SPI-NOR flash on the SoM.

Prepare for loading <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> into memory:
<syntaxhighlight lang="shell">
mw.b ${loadaddr} 0xff 0x200000
setexpr fsbl1addr ${loadaddr} + 0x0
setexpr fsbl2addr ${loadaddr} + 0x40000
setexpr ssbl1addr ${loadaddr} + 0x80000
</syntaxhighlight>

Load <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> from SD card:
<syntaxhighlight lang="shell">
load mmc 0:4 ${fsbl1addr} u-boot-spl.stm32
load mmc 0:4 ${fsbl2addr} u-boot-spl.stm32
load mmc 0:4 ${ssbl1addr} u-boot.itb
</syntaxhighlight>

Load <syntaxhighlight lang="shell" inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot.itb</syntaxhighlight> from tftp server:
<syntaxhighlight lang="shell">
setenv serverip 10.20.30.1
setenv ipaddr 10.20.30.100
setenv netmask 255.255.255.0
tftp ${fsbl1addr} ${serverip}:u-boot-spl.stm32
tftp ${fsbl2addr} ${serverip}:u-boot-spl.stm32
tftp ${ssbl1addr} ${serverip}:u-boot.itb
</syntaxhighlight>

Check for magic numbers of expected image headers and conditionally program the SPI-NOR flash:
<syntaxhighlight lang="shell">
if itest *${fsbl1addr} == 0x324d5453 && itest *${fsbl2addr} == 0x324d5453 && itest *${ssbl1addr} == 0xedfe0dd0; then
sf probe && sf update ${loadaddr} 0 0x200000
fi
</syntaxhighlight>

===== Write U-Boot SPL and U-Boot to an SD card =====

<div style="color:red">TODO:</div>


===== Write U-Boot SPL and U-Boot to the eMMC =====

<div style="color:red">TODO:</div>


==== Enroll, test and enforce BootROM image authentication ====

To enroll, test and enforce image authentication by the BootROM you need to program the PKH into the OTP of the STM32MP15 SoC.
The <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> file that you created in the [[#Generate key pair with STM32MP_KeyGen_CLI|Generate key pair with STM32MP_KeyGen_CLI]] step contains the PKH in binary format for use with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> U-Boot command.
If the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command does fail or is not available on the target U-Boot, you can also write the PKH manually with the more generic <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command into the OTP.

===== Program public key hash to eFuses =====

The following '''commands for the U-Boot Shell''' load the file <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> into memory and program the contained PKH to the OTP of the STM32MP15 SoC.
The used command <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> writes and locks the words of the OTP automatically without knowing anything about the OTP layout/addresses.
If this fails or the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command is not available, you can also write and lock the OTP with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command

====== Program <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> into OTP with <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command ======

Load <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> by SD card:
<syntaxhighlight lang="shell">
load mmc 0:4 ${loadaddr} publicKeyhash.bin
</syntaxhighlight>

Or load <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> by TFTP:
<syntaxhighlight lang="shell">
setenv serverip 10.20.30.1
setenv ipaddr 10.20.30.100
setenv netmask 255.255.255.0
tftp ${loadaddr} ${serverip}:publicKeyhash.bin
</syntaxhighlight>

Show the contents of <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight>:
<syntaxhighlight lang="shell">
stm32key read ${loadaddr}
</syntaxhighlight>
<syntaxhighlight lang="console">
Read KEY at 0xc2000000
OTP value 24: 4e31bbcd
OTP value 25: 51e827dd
OTP value 26: 3511f521
OTP value 27: fd9c11a2
OTP value 28: 5b997b82
OTP value 29: 8150adc5
OTP value 30: a9c68fa9
OTP value 31: 72a3ba74
</syntaxhighlight>

Write the contents of <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> to OTP with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command:
<syntaxhighlight lang="shell">
stm32key fuse ${loadaddr}
</syntaxhighlight>
<syntaxhighlight lang="console">
TODO: Add output
</syntaxhighlight>

====== Program PKH manually into OTP with <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command ======

Generate fuse command with hexdump from file <syntaxhighlight lang="shell" inline>publicKeyhash.bin</syntaxhighlight> on linux host:
<div style="color:red">Warning: Do not use the example output! Only use your unique values for programming the PKH in the OTP!</div>
<syntaxhighlight lang="shell">
echo fuse prog -y 0 0x18 $(hexdump -e '/4 "0x"' -e '/1 "%x"' -e '" "' /path/to/publicKeyhash.bin)
</syntaxhighlight>
<syntaxhighlight lang="console">
fuse prog -y 0 0x18 0x4e31bbcd 0x51e827dd 0x3511f521 0xfd9c11a2 0x5b997b82 0x8150adc5 0xa9c68fa9 0x72a3ba74
</syntaxhighlight>

Write the PKH into OTP manually with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<div style="color:red">Warning: Do not use the example command! Only use your unique values for programming the PKH in the OTP!</div>
<syntaxhighlight lang="shell">
fuse prog -y 0 0x18 0x4e31bbcd 0x51e827dd 0x3511f521 0xfd9c11a2 0x5b997b82 0x8150adc5 0xa9c68fa9 0x72a3ba74
</syntaxhighlight>

Lock the related OTP words manually with the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<syntaxhighlight lang="shell">
fuse prog -y 0 0x10000018 1 1 1 1 1 1 1 1
</syntaxhighlight>

===== Test BootROM image authentication =====

To verify the image authentication by the BootROM with the programmed PKH and the programmed signed images, you must reboot your device.

On the third line of the U-Boot SPL output, check the BootROM authentication status.
The status output should look like this: <syntaxhighlight lang="console" inline>Bootrom authentication: succeeded</syntaxhighlight>.
Note the <syntaxhighlight lang="console" inline>succeeded</syntaxhighlight> status for successful authentication of the U-Boot SPL image by the BootROM.

The following output shows successful authentication of the U-Boot-SPL image in line 3, as well as successful authentication of the used configuration in line 7 and the U-Boot and Device Tree subimages in lines 8 and 9 of the U-Boot-FIT image.
<syntaxhighlight lang="console" line highlight="3,7-9">
U-Boot SPL 2022.01-00012-g6c5892c90c28 (Feb 16 2022 - 11:11:16 +0100)
Model: STMicroelectronics STM32MP15xx DHCOM Premium Developer Kit (2)
Bootrom authentication: succeeded
Code: SoM:rev=1,ddr3=3 Board:rev=0
RAM: DDR3L 32bits 2x4Gb 533MHz
Trying to boot from SPI
## Checking hash(es) for config config-2 ... sha256,rsa4096:fsbl-cfg-2022-02-16+ OK
## Checking hash(es) for Image uboot ... sha256,rsa4096:fsbl-img-2022-02-16+ sha256+ OK
## Checking hash(es) for Image fdt-1 ... sha256,rsa4096:fsbl-img-2022-02-16+ sha256+ OK
</syntaxhighlight>

===== Enforce BootROM image authentication =====

Without any further changes, the BootROM is able to perform authentication of the FSBL image, but unauthenticated images can still be used and executed.
The device is still open, let's see this as a kind of test mode to check if the PKH is set correctly.

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

The 6th bit in the 1st word of the OTP is responsible that the BootROM only accepts signed images.
Burning this bit enforces authentication of images by the BootROM and unsigned binaries are no longer supported on the target device.

To program this bit, the U-Boot Shell can be used with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command or with the more general <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command.

With usage of the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command:
<div style="color:red">Warning: After running the following command, your device will only be able to boot signed images!</div>
<syntaxhighlight lang="shell">
stm32key close
</syntaxhighlight>

Or with usage of the <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command:
<div style="color:red">Warning: After running the following command, your device will only be able to boot signed images!</div>
<syntaxhighlight lang="shell">
fuse prog 0 0x0 0x40
</syntaxhighlight>

== Secure Boot in Trusted Boot with BootROM authentication, TF-A and OP-TEE ==

<div style="color:red">TODO:</div>
# Add support for STM32MP15 DHCOM in <ref name="TF-A" />
# Add support for STM32MP15 DHCOM in <ref name="OP-TEE/optee_os" />
# Create stm32mp15_dhcom_trusted_defconfig???
# Integrate STM32MP15 DHCOM into <ref name="OP-TEE/build" />

== References ==

<references>
<ref name="UEFI specification">[http://www.uefi.org/specifications http://www.uefi.org/specifications]</ref>
<ref name="Basic Boot">[https://source.denx.de/u-boot/u-boot/-/blob/master/configs/stm32mp15_basic_defconfig U-Boot Source stm32mp15_basic_defconfig]</ref>
<ref name="Trusted Boot">[https://source.denx.de/u-boot/u-boot/-/blob/master/configs/stm32mp15_trusted_defconfig U-Boot Source stm32mp15_trusted_defconfig]</ref>
<ref name="BSI TR-02102">[https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.pdf BSI - Technische Richtlinie, "Kryptographische Algorithmen und Schlüssellängen", BSI TR-02102-1]</ref>
<ref name="STM32 image header">[https://wiki.st.com/stm32mpu/wiki/STM32_header_for_binary_files STM32 header for binary files]</ref>
<ref name="KeyGen_tool">[https://wiki.st.com/stm32mpu/wiki/KeyGen_tool STM32MP KeyGen tool]</ref>
<ref name="Signing_tool">[https://wiki.st.com/stm32mpu/wiki/Signing_tool STM32MP Signing tool]</ref>
<ref name="TF-A">[https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/ Trusted Firmware-A (TF-A)]</ref>
<ref name="OP-TEE/optee_os">[https://github.com/OP-TEE/optee_os OP-TEE Trusted OS]</ref>
<ref name="OP-TEE/build">[https://github.com/OP-TEE/build Makefiles to use OP-TEE on various platforms]</ref>
</references>