Wiki-DB - User contributions [en]

Main Page

2024-06-12T09:49:02Z

Jneuhauser: This wiki is no more "new" for a long time

__NOTOC__
{| style="width: 100%; color: #000000; border-spacing: 2px; border: 1px solid darkgray;" valign="top" |
| style="width: 25%; text-align: center;" |
| style="width: 50%; text-align: center;" |
| style="width: 25%; text-align: center;" |
|-
| style="text-align: center;" | [[Image:Welcome.jpg|200px|Welcome to DH electronics MediaWiki]]
| style="text-align: center;" | [[Image:LOGO_DH_electronics-SMALL.jpg|200px|Welcome to DH electronics MediaWiki]]
| style="text-align: center;" | [[Image:Mediawiki.jpg|183px|Welcome to DH electronics MediaWiki]]
|}

''Welcome to DH electronics MediaWiki. This Wiki has the aim to provide our customers technical support for DH electronics products.''

{| style="width: 100%; color: #000000; border-collapse:collapse; border: darkgray; border-style: solid; border-width: 1px 0 1px 0"
|
|style="padding:10px;"|
=== [[DHSOM|DHSOM]] ===

A '''System On Module''' (SOM) is a powerful embedded computer on a compact circuit board.

Our DHCOM modules offer high performance coupled with extensive features and interfaces, low power consumption
as well as compact size.Possible applications for our modules are in visualization, multimedia, automation and communication devices

Click '''[[DHSOM|here]]''' to get support information for our '''[[DHSOM|DHSOM]]''' products.
| style="text-align: right;" |[[Image:IM6Modul.png|center|300px|COM iMX6-D2|link=DHSOM]]
|-
|style="border: darkgray; border-style: solid; border-width: 1px 0 0 0;"|
|style="padding:10px; border: darkgray; border-style: solid; border-width: 1px 0 0 0;"|

=== [[Image:XLON Logo in Schwarz von SD Kopie.jpg|120px|DH electronics XLON|link=XLON]] ===

'''XLON''' products are network interfaces and infrastructure components for LonWorks technology.

Click '''[[XLON|here]]''' to get support information for our '''[[XLON]]''' products.
| style="text-align: right; border: darkgray; border-style: solid; border-width: 1px 0 0 0;" |[[Image:XLON U10.png|center|275px|XLON U10|link=XLON]]

|-
|style="border: darkgray; border-style: solid; border-width: 1px 0 0 0;"|
|style="padding:10px; border: darkgray; border-style: solid; border-width: 1px 0 0 0;"|

=== [[Avenger96]] ===

The AVENGER Board is a 96Boards compliant consumer edition board based on the STM32MP15 series of SoCs.

Click '''[[Avenger96|here]]''' to get support information for our '''[[Avenger96]]''' products.
| style="text-align: right; border: darkgray; border-style: solid; border-width: 1px 0 0 0;" |[[Image:Avenger96_Pers.png|center|350px|Avenger96|link=Avenger96]]

|-
|style="border: darkgray; border-style: solid; border-width: 1px 0 0 0;"|
|style="padding:10px; border: darkgray; border-style: solid; border-width: 1px 0 0 0;"|
=== [[DHMI]] ===

DHMI is our HMI systems (Human-Machine Interface) product range. The standard series are equipped with resistive or capacitive touch displays and our SOM.

Click '''[[DHMI|here]]''' to get support information for our '''[[DHMI]]''' products.
| style="text-align: right; border: darkgray; border-style: solid; border-width: 1px 0 0 0;" |[[Image:HMI_7_mit_Rahmen_Display_medres_wiki.png|center|350px|DHMI|link=DHMI]]

|-
|style="border: darkgray; border-style: solid; border-width: 1px 0 0 0;"|
|style="padding:10px; border: darkgray; border-style: solid; border-width: 1px 0 0 0;"|
=== [[DHCON]] ===

Our DHCON products are optimized for smart home & building as well as Industry 4.0 and IoT applications.

Click '''[[DHCON|here]]''' to get support information for our '''[[DHCON]]''' products.
| style="text-align: right; border: darkgray; border-style: solid; border-width: 1px 0 0 0;" |[[Image:IN-RAIL.png|center|350px|DHCON|link=DHCON]]

|}

COM iMX8 Hardware

2024-06-11T06:58:42Z

Jneuhauser: /* Link to product page instead of the "broken", direct links to the files */

== User Manual / Datasheet ==
[https://www.dh-electronics.com/embedded-produkte/dhsom/detail/dhcom-imx8m-plus DH electronics Product page]

== Downloads ==
:* [[media:DHCOM_schematic_symbol_R03.zip|Download schematic symbols for DHCOM SODIMM-200 connector]]
:* [[media:CAD_DHCOM-iMX8MPlus-3D-Model-2022-03-23.zip|DHCOM i.MX8M Plus 3D model]]

== Available Documents and Links from ST ==

[https://www.nxp.com/products/processors-and-microcontrollers/arm-processors/i-mx-applications-processors/i-mx-8-applications-processors/i-mx-8m-plus-arm-cortex-a53-machine-learning-vision-multimedia-and-industrial-iot:IMX8MPLUS NXP product page and documentation]

DHCOM STM32MP1 Hardware

2024-06-11T06:57:50Z

Jneuhauser: /* Update linkt to product page */

== User Manual / Datasheet ==
[https://www.dh-electronics.com/embedded-produkte/dhsom/detail/dhcom-stm32mp15 DH electronics Product page]

== Downloads ==
:* [[media:DHCOM_schematic_symbol_R03.zip|Download schematic symbols for DHCOM SODIMM-200 and display adaptor connector]]

== Available Documents and Links from ST ==

[https://wiki.st.com/stm32mpu/index.php/STM32MP15_resources STM32MP15 resources]

[https://wiki.st.com/stm32mpu STM32MP1 wiki]

U-Boot recovery for i.MX6 Q/D/DL/S/ULL via JTAG v2

2023-10-11T13:56:49Z

Jneuhauser:

This guide details the process of flashing U-Boot onto our i.MX6 based DHCOM using OpenOCD.
The hardware configuration, software installation, and step-by-step programming procedures are provided.

== Required Hardware ==
* Baseboard as power source for DHCOM
* JTAG Debugger: [https://www.olimex.com/Products/ARM/JTAG/ARM-USB-TINY-H/ Olimex Arm-USB-OCD-Tiny-H]
:All tests and documents were made with this one, but technically all JTAG adapters listed by OpenOCD should work.
* DHCOM JTAG adapter for FFC connection: Article number FD00037
:[[File:JTAG-Adapter.jpeg|300px]]
* Wuerth FFC cable: [https://www.we-online.com/de/components/products/FFC_0_50_TYPE_1_6876XXXXX002 687610050002]
:Note: One cable is included with the DHCOM JTAG adapter.

== Installation ==
This installation was made on the [[Virtual Machine for Application Development]].
All console expressions refer to this Debian system, but any other debian based system should also work.

<div style="color:red">To support all our i.MX6 based DHCOM, it is necessary to have OpenOCD v0.11.0 or higher.</div>

=== OpenOCD from master branch (before Debian 11 alias Bullseye) ===
# Install needed libraries and tools <br><code>sudo apt-get install git build-essential pkg-config autoconf automake libtool libusb-dev libusb-1.0-0-dev libhidapi-dev libftdi-dev</code>
# Clone git repository to local directory and checkout v0.12.0 tag <br><code>git clone -b v0.12.0 https://repo.or.cz/openocd.git</code>
# Change working directory to the extracted one <br><code>cd openocd</code>
# Prepare source directory and submodules (when building from the git repository) <br><code>./bootstrap</code>
# Generate the Makefiles to build OpenOCD <br><code>./configure</code>
# Build OpenOCD from source <br><code>make -j4</code>
# Install OpenOCD to /usr/local <br><code>sudo make install</code>
# (optional) Remove openocd source directory <br><code>cd .. && rm -rf openocd</code>

=== OpenOCD from Debian repositories (since Debian 11 alias Bullseye) ===
# Install OpenOCD from Debian repositories <br><code>sudo apt-get install openocd</code>

=== Non root access to tty devices ===
# Add your user to the dialout group: <br><code>sudo usermod -a -G dialout ${USER}</code>
# Add your user to the plugdev group: <br><code>sudo usermod -a -G plugdev ${USER}</code>
# Logout and login to apply new group rights

== U-Boot Programming ==
There are two ways for doing this.
The easy way is an automatic shell script, which handles all the commands needed for the programming process.
The other one is to type in the required commands.
In a few cases the shell script fails then you need to go the other way and program the U-Boot manually.
The steps [[#Preparation|Preparation]] and [[#Start up OpenOCD|Start up OpenOCD]] are required for both automatic and manual flash programming.

=== Preparation ===
==== Get the needed recovery files ====
# Download and extract the needed files [[media:2023-08-28_imx6_U-Boot_recovery.tar.xz|| tar xJ</code>
# Change working directory to the extracted one <br><code>cd 2023-08-28_imx6_U-Boot_recovery</code>
==== Connect JTAG adapter ====
# Connect the JTAG adapter with your PC and the Debian VM (Player - Removeable Devices) through USB
# Connect the JTAG interface via the DHCOM JTAG adapter to the i.MX6 module (If you don't have a JTAG adapter, please ask DH electronics)
#:[[File:JTAG-connection.jpeg|1000px]]]
# Put the SODIMM-200 module (DHCOM) into the SODIMM-200 slot on your basebord
# Connect to the serial console (serial port) of the board like here [[COM_iMX6_Bootloader_U-Boot#Enter_Bootloader_Console|Enter_Bootloader_Console]]

=== Start up OpenOCD ===
# Ensure you have everything properly connected like in [[#Connect JTAG adapter|Connect JTAG adapter]]
# Power up the i.MX6 board and have a look at the serial output (serial port).
#:* '''i.MX6 Q/D/DL/S'''<br>It is okay if a U-Boot is starting up, because the device will be reset later.
#:* '''i.MX6 ULL'''<br>There must be no output of U-Boot, otherwise go to [[#Troubleshooting|Troubleshooting]].
# Open a new terminal window (local shell console)
# Ensure you are in the directory with the recovery files <br><code>cd /path/to/2023-08-28_imx6_U-Boot_recovery</code>
# Start OpenOCD depending on your hardware
#:* '''i.MX6 Q/D/DL/S'''<br><code>openocd -f interface/ftdi/olimex-arm-usb-tiny-h.cfg -f target/imx6.cfg -f dhcom-manual-loaded-code.cfg</code>
#:* '''i.MX6 ULL'''<br><code>openocd -f interface/ftdi/olimex-arm-usb-tiny-h.cfg -f imx6ull.cfg -f target/imx6ul.cfg -f dhcom-manual-loaded-code.cfg</code>
'''The output should look like:'''
<nowiki>
Open On-Chip Debugger 0.12.0
Licensed under GNU GPL v2
For bug reports, read
http://openocd.org/doc/doxygen/bugs.html
Info : auto-selecting first available session transport "jtag". To override use 'transport select <transport>'.
Warn : imx6.sdma: nonstandard IR value
boot_from_sd
Info : Listening on port 6666 for tcl connections
Info : Listening on port 4444 for telnet connections
Info : clock speed 1000 kHz
Info : JTAG tap: imx6.cpu tap/device found: 0x4ba00477 (mfg: 0x23b (ARM Ltd), part: 0xba00, ver: 0x4)
Info : TAP imx6.sdma does not have valid IDCODE (idcode=0x4323803a)
Info : JTAG tap: imx6.sjc tap/device found: 0x2191c01d (mfg: 0x00e (Freescale (Motorola)), part: 0x191c, ver: 0x2)
Info : imx6.cpu.0: hardware has 6 breakpoints, 4 watchpoints
Info : starting gdb server for imx6.cpu.0 on 3333
Info : Listening on port 3333 for gdb connections</nowiki>

=== Automated Programming ===
# Ensure OpenOCD is running like in [[#Start up OpenOCD|Start up OpenOCD]]
# Open a second terminal window (local shell console)
# Ensure you are in the directory with the recovery files <br><code>cd /path/to/2023-08-28_imx6_U-Boot_recovery</code>
# Execute the automated bash script with arguments depending on your hardware and desired U-Boot
#:* Default DH U-Boot
#:** '''i.MX6 Q/D/DL/S'''<br><code>sh prog_bl.sh imx6qdl</code>
#:** '''i.MX6 ULL'''<br><code>sh prog_bl.sh imx6ull</code>
#:* Custom U-Boot
#:** '''i.MX6 Q/D/DL/S'''<br><code>sh prog_bl.sh imx6qdl /path/to/u-boot-with-spl.imx</code>
#:** '''i.MX6 ULL'''<br><code>sh prog_bl.sh imx6ull /path/to/u-boot-with-spl.imx</code>
'''On success the output of the script should look like:'''
<nowiki>
Programming: u-boot-with-spl-imx6qdl.imx to imx6qdl
Trying ::1...
Connection failed: Connection refused
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
Open On-Chip Debugger
> boot_from_sd
imx6.cpu.0: MPIDR level2 0, cluster 0, core 0, multi core, no SMT
target halted in Thumb state due to debug-request, current mode: Supervisor
cpsr: 0xa00001f3 pc: 0x8ff7a982
MMU: enabled, D-Cache: enabled, I-Cache: enabled
Invalid ACK (0) in DAP response
Could not read DSCR register
Error waiting for cortex_a_exec_opcode
Invalid ACK (0) in DAP response
Could not read DSCR register
Invalid ACK (0) in DAP response
JTAG-DP STICKY ERROR
Could not read DSCR register
Error waiting for dpm prepare

Invalid ACK (7) in DAP response
Polling target imx6.cpu.0 failed, trying to reexamine
Debug regions are unpowered, an unexpected reset might have happened
JTAG-DP STICKY ERROR
Could not initialize the APB-AP
Examination failed, GDB will be halted. Polling again in 100ms
JTAG-DP STICKY ERROR
Polling target imx6.cpu.0 failed, trying to reexamine
imx6.cpu.0: hardware has 6 breakpoints, 4 watchpoints
> prepare_code_load
target halted in Thumb state due to debug-request, current mode: Supervisor
cpsr: 0x800001f3 pc: 0x8ff7a982
MMU: disabled, D-Cache: disabled, I-Cache: disabled
> load_image u-boot-spl-prog-imx6qdl.bin 0x908000
32768 bytes written at address 0x00908000
downloaded 32768 bytes in 1.152152s (27.774 KiB/s)

> resume
> halt
target halted in Thumb state due to debug-request, current mode: Supervisor
cpsr: 0x800001f3 pc: 0x0090ba5e
MMU: disabled, D-Cache: disabled, I-Cache: enabled
> load_image u-boot-with-spl-imx6qdl.imx 0x12000000
567752 bytes written at address 0x12000000
downloaded 567752 bytes in 18.675529s (29.688 KiB/s)

> resume
> Connection closed by foreign host.</nowiki>
'''On success the output of serial console (serial port) should look like:'''
<nowiki>
U-Boot SPL 2018.05-23076-g8686cf2574 (Mar 10 2020 - 10:26:00 +0100)
SPL: Unsupported Boot Device!
SPL: failed to boot from all boot devices
### ERROR ### Please RESET the board ###
Searching for IVT header at DDR address 0x12000000
....
Found IVT header
Determinded image length: 0x8a9c8

### Recovery ### Trying to program SPI flash ###
Probing SPI flash... ok
Erasing SPI flash... ok
Programming SPI flash... ok

### Recovery ### Finished ###</nowiki>
'''Note:''' If some error occures you can try the [[#Manual Programming|Manual Programming]] method below

=== Manual Programming ===
# Ensure OpenOCD is running like in [[#Start up OpenOCD|Start up OpenOCD]]
# Open a second terminal window (local shell console)
# Ensure you are in the directory with the recovery files <br><code>cd /path/to/2023-08-28_imx6_U-Boot_recovery</code>
# Open a telnet session to OpenOCD <br><code>telnet localhost 4444</code>
## Ensure device boot fails by booting from invalid media
##:* '''i.MX6 Q/D/DL/S'''<br><code>boot_from_sd</code>
##:* '''i.MX6 ULL'''<br>Follow [[#Troubleshooting|Troubleshooting]] to ensure no U-Boot starts.
## Prepare for running manual loaded code<br><code>prepare_code_load</code>
## Load modified U-Boot SPL as flash programmer in SRAM (device dependent)
##:* '''i.MX6 Q/D/DL/S'''<br><code>load_image u-boot-spl-prog-imx6qdl.bin 0x908000</code>
##:* '''i.MX6 ULL'''<br><code>load_image u-boot-spl-prog-imx6ull.bin 0x908000</code>
## Resume code execution at entry point of loaded U-Boot SPL <br><code>resume 0x00908000</code>
## Halt code execution if you see '''Searching for IVT header at DDR address 0xX2000000''' in serial console <br><code>halt</code>
## Load desired U-Boot image into RAM (device and customer dependent)
##:* '''i.MX6 Q/D/DL/S'''<br><code>load_image u-boot-with-spl-imx6qdl.imx 0x12000000</code>
##:* '''i.MX6 ULL'''<br><code>load_image u-boot-with-spl-imx6ull.imx 0x82000000</code>
## Resume code execution after U-Boot image is in RAM<br><code>resume</code>
## Wait until the serial output (serial port) looks like in [[#Automated Programming|Automated Programming]]
## Exit telnet with <code>exit</code> and close OpenOCD with STRG+C

== Troubleshooting ==
If there is a U-Boot starting, the OpenOCD procedure may not work properly.
There are two solutions to prevent the start of U-Boot from the SPI-NOR-Flash.

=== SDP Boot (only i.MX6 ULL) ===
# Boot in Serial Download Mode to prevent booting the broken U-Boot from SPI-NOR-Flash
## Hold the button for sdp boot mode on the SODIMM-200 module (DHCOM) next to the BGA module (DHCOR)
##:[[File:DHCOR_i.MX6ULL_SDP-Boot.jpg|400px]]
## Reset the device. To reset the device, press the reset button on the baseboard or unplug and plug in the power plug.
## Release the button for sdp boot mode
# If no new output is printed on the serial console (serial port), continue with the flashing procedure

=== SD Boot (only i.MX6 Q/D/DL/S) ===
# Ensure OpenOCD is running like in [[#Start up OpenOCD|Start up OpenOCD]]
# Open a telnet session to OpenOCD <br><code>telnet localhost 4444</code>
# Use the following command to trigger a boot from an invalid source by setting the boot source to an invalid media for the next boot and then reset the device. <br><code>boot_from_sd</code>
# If no new output is printed on the serial console (serial port), continue with the flashing procedure

U-Boot recovery for i.MX6 Q/D/DL/S/ULL via JTAG v2

2023-10-11T13:56:29Z

Jneuhauser:

This guide details the process of flashing U-Boot onto our i.MX6 based DHCOM using OpenOCD.
The hardware configuration, software installation, and step-by-step programming procedures are provided.

== Required Hardware ==
* Baseboard as power source for DHCOM
* JTAG Debugger: [https://www.olimex.com/Products/ARM/JTAG/ARM-USB-TINY-H/ Olimex Arm-USB-OCD-Tiny-H]
:All tests and documents were made with this one, but technically all JTAG adapters listed by OpenOCD should work.
* DHCOM JTAG adapter for FFC connection: Article number FD00037
:[[File:JTAG-Adapter.jpeg|300px]]
* Wuerth FFC cable: [https://www.we-online.com/de/components/products/FFC_0_50_TYPE_1_6876XXXXX002 687610050002]
:Note: One cable is included with the DHCOM JTAG adapter.

== Installation ==
This installation was made on the [[Virtual Machine for Application Development]].
All console expressions refer to this Debian system, but any other debian based system should also work.

<div style="color:red">To support all our i.MX6 based DHCOM, it is necessary to have OpenOCD v0.11.0 or higher.</div>

=== OpenOCD from master branch (before Debian 11 alias Bullseye) ===
# Install needed libraries and tools <br><code>sudo apt-get install git build-essential pkg-config autoconf automake libtool libusb-dev libusb-1.0-0-dev libhidapi-dev libftdi-dev</code>
# Clone git repository to local directory and checkout v0.12.0 tag <br><code>git clone -b v0.12.0 https://repo.or.cz/openocd.git</code>
# Change working directory to the extracted one <br><code>cd openocd</code>
# Prepare source directory and submodules (when building from the git repository) <br><code>./bootstrap</code>
# Generate the Makefiles to build OpenOCD <br><code>./configure</code>
# Build OpenOCD from source <br><code>make -j4</code>
# Install OpenOCD to /usr/local <br><code>sudo make install</code>
# (optional) Remove openocd source directory <br><code>cd .. && rm -rf openocd</code>

=== OpenOCD from Debian repositories (since Debian 11 alias Bullseye) ===
# Install OpenOCD from Debian repositories <br><code>sudo apt-get install openocd</code>

=== Non root access to tty devices ===
# Add your user to the dialout group: <br><code>sudo usermod -a -G dialout ${USER}</code>
# Add your user to the plugdev group: <br><code>sudo usermod -a -G plugdev ${USER}</code>
# Logout and login to apply new group rights

== U-Boot Programming ==
There are two ways for doing this.
The easy way is an automatic shell script, which handles all the commands needed for the programming process.
The other one is to type in the required commands.
In a few cases the shell script fails then you need to go the other way and program the U-Boot manually.
The steps [[#Preparation|Preparation]] and [[#Start up OpenOCD|Start up OpenOCD]] are required for both automatic and manual flash programming.

=== Preparation ===
==== Get the needed recovery files ====
# Download and extract the needed files [[media:2023-08-28_imx6_U-Boot_recovery.tar.xz|| tar xJ</code>
# Change working directory to the extracted one <br><code>cd 2023-08-28_imx6_U-Boot_recovery</code>
==== Connect JTAG adapter ====
# Connect the JTAG adapter with your PC and the Debian VM (Player - Removeable Devices) through USB
# Connect the JTAG interface via the DHCOM JTAG adapter to the i.MX6 module (If you don't have a JTAG adapter, please ask DH electronics)
#:[[File:JTAG-connection.jpeg|1000px]]]
# Put the SODIMM-200 module (DHCOM) into the SODIMM-200 slot on your basebord
# Connect to the serial console (serial port) of the board like here [[COM_iMX6_Bootloader_U-Boot#Enter_Bootloader_Console|Enter_Bootloader_Console]]

=== Start up OpenOCD ===
# Ensure you have everything properly connected like in [[#Connect JTAG adapter|Connect JTAG adapter]]
# Power up the i.MX6 board and have a look at the serial output (serial port).
#:* '''i.MX6 Q/D/DL/S'''<br>It is okay if a U-Boot is starting up, because the device will be reset later.
#:* '''i.MX6 ULL'''<br>There must be no output of U-Boot, otherwise go to [[#Troubleshooting|Troubleshooting]].
# Open a new terminal window (local shell console)
# Ensure you are in the directory with the recovery files <br><code>cd /path/to/2023-08-28_imx6_U-Boot_recovery</code>
# Start OpenOCD depending on your hardware
#:* '''i.MX6 Q/D/DL/S'''<br><code>openocd -f interface/ftdi/olimex-arm-usb-tiny-h.cfg -f target/imx6.cfg -f dhcom-manual-loaded-code.cfg</code>
#:* '''i.MX6 ULL'''<br><code>openocd -f interface/ftdi/olimex-arm-usb-tiny-h.cfg -f imx6ull.cfg -f target/imx6ul.cfg -f dhcom-manual-loaded-code.cfg</code>
'''The output should look like:'''
<nowiki>
Open On-Chip Debugger 0.12.0
Licensed under GNU GPL v2
For bug reports, read
http://openocd.org/doc/doxygen/bugs.html
Info : auto-selecting first available session transport "jtag". To override use 'transport select <transport>'.
Warn : imx6.sdma: nonstandard IR value
boot_from_sd
Info : Listening on port 6666 for tcl connections
Info : Listening on port 4444 for telnet connections
Info : clock speed 1000 kHz
Info : JTAG tap: imx6.cpu tap/device found: 0x4ba00477 (mfg: 0x23b (ARM Ltd), part: 0xba00, ver: 0x4)
Info : TAP imx6.sdma does not have valid IDCODE (idcode=0x4323803a)
Info : JTAG tap: imx6.sjc tap/device found: 0x2191c01d (mfg: 0x00e (Freescale (Motorola)), part: 0x191c, ver: 0x2)
Info : imx6.cpu.0: hardware has 6 breakpoints, 4 watchpoints
Info : starting gdb server for imx6.cpu.0 on 3333
Info : Listening on port 3333 for gdb connections</nowiki>

=== Automated Programming ===
# Ensure OpenOCD is running like in [[#Start up OpenOCD|Start up OpenOCD]]
# Open a second terminal window (local shell console)
# Ensure you are in the directory with the recovery files <br><code>cd /path/to/2023-08-28_imx6_U-Boot_recovery</code>
# Execute the automated bash script with arguments depending on your hardware and desired U-Boot
#:* Default DH U-Boot
#:** '''i.MX6 Q/D/DL/S'''<br><code>sh prog_bl.sh imx6qdl</code>
#:** '''i.MX6 ULL'''<br><code>sh prog_bl.sh imx6ull</code>
#:* Custom U-Boot
#:** '''i.MX6 Q/D/DL/S'''<br><code>sh prog_bl.sh imx6qdl /path/to/u-boot-with-spl.imx</code>
#:** '''i.MX6 ULL'''<br><code>sh prog_bl.sh imx6ull /path/to/u-boot-with-spl.imx</code>
'''On success the output of the script should look like:'''
<nowiki>
Programming: u-boot-with-spl-imx6qdl.imx to imx6qdl
Trying ::1...
Connection failed: Connection refused
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
Open On-Chip Debugger
> boot_from_sd
imx6.cpu.0: MPIDR level2 0, cluster 0, core 0, multi core, no SMT
target halted in Thumb state due to debug-request, current mode: Supervisor
cpsr: 0xa00001f3 pc: 0x8ff7a982
MMU: enabled, D-Cache: enabled, I-Cache: enabled
Invalid ACK (0) in DAP response
Could not read DSCR register
Error waiting for cortex_a_exec_opcode
Invalid ACK (0) in DAP response
Could not read DSCR register
Invalid ACK (0) in DAP response
JTAG-DP STICKY ERROR
Could not read DSCR register
Error waiting for dpm prepare

Invalid ACK (7) in DAP response
Polling target imx6.cpu.0 failed, trying to reexamine
Debug regions are unpowered, an unexpected reset might have happened
JTAG-DP STICKY ERROR
Could not initialize the APB-AP
Examination failed, GDB will be halted. Polling again in 100ms
JTAG-DP STICKY ERROR
Polling target imx6.cpu.0 failed, trying to reexamine
imx6.cpu.0: hardware has 6 breakpoints, 4 watchpoints
> prepare_code_load
target halted in Thumb state due to debug-request, current mode: Supervisor
cpsr: 0x800001f3 pc: 0x8ff7a982
MMU: disabled, D-Cache: disabled, I-Cache: disabled
> load_image u-boot-spl-prog-imx6qdl.bin 0x908000
32768 bytes written at address 0x00908000
downloaded 32768 bytes in 1.152152s (27.774 KiB/s)

> resume
> halt
target halted in Thumb state due to debug-request, current mode: Supervisor
cpsr: 0x800001f3 pc: 0x0090ba5e
MMU: disabled, D-Cache: disabled, I-Cache: enabled
> load_image u-boot-with-spl-imx6qdl.imx 0x12000000
567752 bytes written at address 0x12000000
downloaded 567752 bytes in 18.675529s (29.688 KiB/s)

> resume
> Connection closed by foreign host.</nowiki>
'''On success the output of serial console (serial port) should look like:'''
<nowiki>
U-Boot SPL 2018.05-23076-g8686cf2574 (Mar 10 2020 - 10:26:00 +0100)
SPL: Unsupported Boot Device!
SPL: failed to boot from all boot devices
### ERROR ### Please RESET the board ###
Searching for IVT header at DDR address 0x12000000
....
Found IVT header
Determinded image length: 0x8a9c8

### Recovery ### Trying to program SPI flash ###
Probing SPI flash... ok
Erasing SPI flash... ok
Programming SPI flash... ok

### Recovery ### Finished ###</nowiki>
'''Note:''' If some error occures you can try the [[#Manual Programming|Manual Programming]] method below

=== Manual Programming ===
# Ensure OpenOCD is running like in [[#Start up OpenOCD|Start up OpenOCD]]
# Open a second terminal window (local shell console)
# Ensure you are in the directory with the recovery files <br><code>cd /path/to/2023-08-28_imx6_U-Boot_recovery</code>
# Open a telnet session to OpenOCD <br><code>telnet localhost 4444</code>
## Ensure device boot fails by booting from invalid media
##:* '''i.MX6 Q/D/DL/S'''<br><code>boot_from_sd</code>
##:* '''i.MX6 ULL'''<br>Follow [[#Troubleshooting|Troubleshooting]] to ensure no U-Boot starts.
## Prepare for running manual loaded code<br><code>prepare_code_load</code>
## Load modified U-Boot SPL as flash programmer in SRAM (device dependent)
##:* '''i.MX6 Q/D/DL/S'''<br><code>load_image u-boot-spl-prog-imx6qdl.bin 0x908000</code>
##:* '''i.MX6 ULL'''<br><code>load_image u-boot-spl-prog-imx6ull.bin 0x908000</code>
## Resume code execution at entry point of loaded U-Boot SPL <br><code>resume 0x00908000</code>
## Halt code execution if you see '''Searching for IVT header at DDR address 0xX2000000''' in serial console <br><code>halt</code>
## Load desired U-Boot image into RAM (device and customer dependent)
##:* '''i.MX6 Q/D/DL/S'''<br><code>load_image u-boot-with-spl-imx6qdl.imx 0x12000000</code>
##:* '''i.MX6 ULL'''<br><code>load_image u-boot-with-spl-imx6ull.imx 0x82000000</code>
## Resume code execution after U-Boot image is in RAM<br><code>resume</code>
## Wait until the serial output (serial port) looks like in [[#Automated Programming|Automated Programming]]
## Exit telnet with <code>exit</code> and close OpenOCD with STRG+C

== Troubleshooting ==
If there is a U-Boot starting, the OpenOCD procedure may not work properly.
There are two solutions to prevent the start of U-Boot from the SPI-NOR-Flash.

=== SDP Boot (only i.MX6 ULL) ===
# Boot in Serial Download Mode to prevent booting the broken U-Boot from SPI-NOR-Flash
## Hold the button for sdp boot mode on the SODIMM-200 module (DHCOM) next to the BGA module (DHCOR)
##:[[File:DHCOR_i.MX6ULL_SDP-Boot.jpg|400px]]
## Reset the device. To reset the device, press the reset button on the baseboard or unplug and plug in the power plug.
## Release the button for sdp boot mode
# If no new output is printed on the serial console (serial port), continue with the flashing procedure

=== SDP Boot (only i.MX6 Q/D/DL/S) ===
# Ensure OpenOCD is running like in [[#Start up OpenOCD|Start up OpenOCD]]
# Open a telnet session to OpenOCD <br><code>telnet localhost 4444</code>
# Use the following command to trigger a boot from an invalid source by setting the boot source to an invalid media for the next boot and then reset the device. <br><code>boot_from_sd</code>
# If no new output is printed on the serial console (serial port), continue with the flashing procedure

U-Boot recovery for i.MX6 Q/D/DL/S/ULL via JTAG v2

2023-10-11T13:54:27Z

Jneuhauser:

This guide details the process of flashing U-Boot onto our i.MX6 based DHCOM using OpenOCD.
The hardware configuration, software installation, and step-by-step programming procedures are provided.

== Required Hardware ==
* Baseboard as power source for DHCOM
* JTAG Debugger: [https://www.olimex.com/Products/ARM/JTAG/ARM-USB-TINY-H/ Olimex Arm-USB-OCD-Tiny-H]
:All tests and documents were made with this one, but technically all JTAG adapters listed by OpenOCD should work.
* DHCOM JTAG adapter for FFC connection: Article number FD00037
:[[File:JTAG-Adapter.jpeg|300px]]
* Wuerth FFC cable: [https://www.we-online.com/de/components/products/FFC_0_50_TYPE_1_6876XXXXX002 687610050002]
:Note: One cable is included with the DHCOM JTAG adapter.

== Installation ==
This installation was made on the [[Virtual Machine for Application Development]].
All console expressions refer to this Debian system, but any other debian based system should also work.

<div style="color:red">To support all our i.MX6 based DHCOM, it is necessary to have OpenOCD v0.11.0 or higher.</div>

=== OpenOCD from master branch (before Debian 11 alias Bullseye) ===
# Install needed libraries and tools <br><code>sudo apt-get install git build-essential pkg-config autoconf automake libtool libusb-dev libusb-1.0-0-dev libhidapi-dev libftdi-dev</code>
# Clone git repository to local directory and checkout v0.12.0 tag <br><code>git clone -b v0.12.0 https://repo.or.cz/openocd.git</code>
# Change working directory to the extracted one <br><code>cd openocd</code>
# Prepare source directory and submodules (when building from the git repository) <br><code>./bootstrap</code>
# Generate the Makefiles to build OpenOCD <br><code>./configure</code>
# Build OpenOCD from source <br><code>make -j4</code>
# Install OpenOCD to /usr/local <br><code>sudo make install</code>
# (optional) Remove openocd source directory <br><code>cd .. && rm -rf openocd</code>

=== OpenOCD from Debian repositories (since Debian 11 alias Bullseye) ===
# Install OpenOCD from Debian repositories <br><code>sudo apt-get install openocd</code>

=== Non root access to tty devices ===
# Add your user to the dialout group: <br><code>sudo usermod -a -G dialout ${USER}</code>
# Add your user to the plugdev group: <br><code>sudo usermod -a -G plugdev ${USER}</code>
# Logout and login to apply new group rights

== U-Boot Programming ==
There are two ways for doing this.
The easy way is an automatic shell script, which handles all the commands needed for the programming process.
The other one is to type in the required commands.
In a few cases the shell script fails then you need to go the other way and program the U-Boot manually.
The steps [[#Preparation|Preparation]] and [[#Start up OpenOCD|Start up OpenOCD]] are required for both automatic and manual flash programming.

=== Preparation ===
==== Get the needed recovery files ====
# Download and extract the needed files [[media:2023-08-28_imx6_U-Boot_recovery.tar.xz|| tar xJ</code>
# Change working directory to the extracted one <br><code>cd 2023-08-28_imx6_U-Boot_recovery</code>
==== Connect JTAG adapter ====
# Connect the JTAG adapter with your PC and the Debian VM (Player - Removeable Devices) through USB
# Connect the JTAG interface via the DHCOM JTAG adapter to the i.MX6 module (If you don't have a JTAG adapter, please ask DH electronics)
#:[[File:JTAG-connection.jpeg|1000px]]]
# Put the SODIMM-200 module (DHCOM) into the SODIMM-200 slot on your basebord
# Connect to the serial console (serial port) of the board like here [[COM_iMX6_Bootloader_U-Boot#Enter_Bootloader_Console|Enter_Bootloader_Console]]

=== Start up OpenOCD ===
# Ensure you have everything properly connected like in [[#Connect JTAG adapter|Connect JTAG adapter]]
# Power up the i.MX6 board and have a look at the serial output (serial port).
#:* '''i.MX6 Q/D/DL/S'''<br>It is okay if a U-Boot is starting up, because the device will be reset later.
#:* '''i.MX6 ULL'''<br>There must be no output of U-Boot, otherwise go to [[#Troubleshooting|Troubleshooting]].
# Open a new terminal window (local shell console)
# Ensure you are in the directory with the recovery files <br><code>cd /path/to/2023-08-28_imx6_U-Boot_recovery</code>
# Start OpenOCD depending on your hardware
#:* '''i.MX6 Q/D/DL/S'''<br><code>openocd -f interface/ftdi/olimex-arm-usb-tiny-h.cfg -f target/imx6.cfg -f dhcom-manual-loaded-code.cfg</code>
#:* '''i.MX6 ULL'''<br><code>openocd -f interface/ftdi/olimex-arm-usb-tiny-h.cfg -f imx6ull.cfg -f target/imx6ul.cfg -f dhcom-manual-loaded-code.cfg</code>
'''The output should look like:'''
<nowiki>
Open On-Chip Debugger 0.12.0
Licensed under GNU GPL v2
For bug reports, read
http://openocd.org/doc/doxygen/bugs.html
Info : auto-selecting first available session transport "jtag". To override use 'transport select <transport>'.
Warn : imx6.sdma: nonstandard IR value
boot_from_sd
Info : Listening on port 6666 for tcl connections
Info : Listening on port 4444 for telnet connections
Info : clock speed 1000 kHz
Info : JTAG tap: imx6.cpu tap/device found: 0x4ba00477 (mfg: 0x23b (ARM Ltd), part: 0xba00, ver: 0x4)
Info : TAP imx6.sdma does not have valid IDCODE (idcode=0x4323803a)
Info : JTAG tap: imx6.sjc tap/device found: 0x2191c01d (mfg: 0x00e (Freescale (Motorola)), part: 0x191c, ver: 0x2)
Info : imx6.cpu.0: hardware has 6 breakpoints, 4 watchpoints
Info : starting gdb server for imx6.cpu.0 on 3333
Info : Listening on port 3333 for gdb connections</nowiki>

=== Automated Programming ===
# Ensure OpenOCD is running like in [[#Start up OpenOCD|Start up OpenOCD]]
# Open a second terminal window (local shell console)
# Ensure you are in the directory with the recovery files <br><code>cd /path/to/2023-08-28_imx6_U-Boot_recovery</code>
# Execute the automated bash script with arguments depending on your hardware and desired U-Boot
#:* Default DH U-Boot
#:** '''i.MX6 Q/D/DL/S'''<br><code>sh prog_bl.sh imx6qdl</code>
#:** '''i.MX6 ULL'''<br><code>sh prog_bl.sh imx6ull</code>
#:* Custom U-Boot
#:** '''i.MX6 Q/D/DL/S'''<br><code>sh prog_bl.sh imx6qdl /path/to/u-boot-with-spl.imx</code>
#:** '''i.MX6 ULL'''<br><code>sh prog_bl.sh imx6ull /path/to/u-boot-with-spl.imx</code>
'''On success the output of the script should look like:'''
<nowiki>
Programming: u-boot-with-spl-imx6qdl.imx to imx6qdl
Trying ::1...
Connection failed: Connection refused
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
Open On-Chip Debugger
> boot_from_sd
imx6.cpu.0: MPIDR level2 0, cluster 0, core 0, multi core, no SMT
target halted in Thumb state due to debug-request, current mode: Supervisor
cpsr: 0xa00001f3 pc: 0x8ff7a982
MMU: enabled, D-Cache: enabled, I-Cache: enabled
Invalid ACK (0) in DAP response
Could not read DSCR register
Error waiting for cortex_a_exec_opcode
Invalid ACK (0) in DAP response
Could not read DSCR register
Invalid ACK (0) in DAP response
JTAG-DP STICKY ERROR
Could not read DSCR register
Error waiting for dpm prepare

Invalid ACK (7) in DAP response
Polling target imx6.cpu.0 failed, trying to reexamine
Debug regions are unpowered, an unexpected reset might have happened
JTAG-DP STICKY ERROR
Could not initialize the APB-AP
Examination failed, GDB will be halted. Polling again in 100ms
JTAG-DP STICKY ERROR
Polling target imx6.cpu.0 failed, trying to reexamine
imx6.cpu.0: hardware has 6 breakpoints, 4 watchpoints
> prepare_code_load
target halted in Thumb state due to debug-request, current mode: Supervisor
cpsr: 0x800001f3 pc: 0x8ff7a982
MMU: disabled, D-Cache: disabled, I-Cache: disabled
> load_image u-boot-spl-prog-imx6qdl.bin 0x908000
32768 bytes written at address 0x00908000
downloaded 32768 bytes in 1.152152s (27.774 KiB/s)

> resume
> halt
target halted in Thumb state due to debug-request, current mode: Supervisor
cpsr: 0x800001f3 pc: 0x0090ba5e
MMU: disabled, D-Cache: disabled, I-Cache: enabled
> load_image u-boot-with-spl-imx6qdl.imx 0x12000000
567752 bytes written at address 0x12000000
downloaded 567752 bytes in 18.675529s (29.688 KiB/s)

> resume
> Connection closed by foreign host.</nowiki>
'''On success the output of serial console (serial port) should look like:'''
<nowiki>
U-Boot SPL 2018.05-23076-g8686cf2574 (Mar 10 2020 - 10:26:00 +0100)
SPL: Unsupported Boot Device!
SPL: failed to boot from all boot devices
### ERROR ### Please RESET the board ###
Searching for IVT header at DDR address 0x12000000
....
Found IVT header
Determinded image length: 0x8a9c8

### Recovery ### Trying to program SPI flash ###
Probing SPI flash... ok
Erasing SPI flash... ok
Programming SPI flash... ok

### Recovery ### Finished ###</nowiki>
'''Note:''' If some error occures you can try the [[#Manual Programming|Manual Programming]] method below

=== Manual Programming ===
# Ensure OpenOCD is running like in [[#Start up OpenOCD|Start up OpenOCD]]
# Open a second terminal window (local shell console)
# Ensure you are in the directory with the recovery files <br><code>cd /path/to/2023-08-28_imx6_U-Boot_recovery</code>
# Open a telnet session to OpenOCD <br><code>telnet localhost 4444</code>
## Ensure device boot fails by booting from invalid media
##:* '''i.MX6 Q/D/DL/S'''<br><code>boot_from_sd</code>
##:* '''i.MX6 ULL'''<br>Follow [[#Troubleshooting|Troubleshooting]] to ensure no U-Boot starts.
## Prepare for running manual loaded code<br><code>prepare_code_load</code>
## Load modified U-Boot SPL as flash programmer in SRAM (device dependent)
##:* '''i.MX6 Q/D/DL/S'''<br><code>load_image u-boot-spl-prog-imx6qdl.bin 0x908000</code>
##:* '''i.MX6 ULL'''<br><code>load_image u-boot-spl-prog-imx6ull.bin 0x908000</code>
## Resume code execution at entry point of loaded U-Boot SPL <br><code>resume 0x00908000</code>
## Halt code execution if you see '''Searching for IVT header at DDR address 0xX2000000''' in serial console <br><code>halt</code>
## Load desired U-Boot image into RAM (device and customer dependent)
##:* '''i.MX6 Q/D/DL/S'''<br><code>load_image u-boot-with-spl-imx6qdl.imx 0x12000000</code>
##:* '''i.MX6 ULL'''<br><code>load_image u-boot-with-spl-imx6ull.imx 0x82000000</code>
## Resume code execution after U-Boot image is in RAM<br><code>resume</code>
## Wait until the serial output (serial port) looks like in [[#Automated Programming|Automated Programming]]
## Exit telnet with <code>exit</code> and close OpenOCD with STRG+C

== Troubleshooting ==
If there is a U-Boot starting, the OpenOCD procedure may not work properly.
There are two solutions to prevent the start of U-Boot from the SPI-NOR-Flash.

=== SDP Boot (only i.MX6 ULL) ===
# Boot in Serial Download Mode to prevent booting the broken U-Boot from SPI-NOR-Flash
## Hold the button for sdp boot mode on the SODIMM-200 module (DHCOM) next to the BGA module (DHCOR)
##:[[File:DHCOR_i.MX6ULL_SDP-Boot.jpg|400px]]
## Reset the device. To reset the device, press the reset button on the baseboard or unplug and plug in the power plug.
## Release the button for sdp boot mode
# If no new output is printed on the serial console (serial port), continue with the flashing procedure

=== SDP Boot (only i.MX6 Q/D/DL/S) ===
# Ensure OpenOCD is running like in [[#Start up OpenOCD|Start up OpenOCD]]
# Open a telnet session to OpenOCD <br><code>telnet localhost 4444</code>
# Use the following command to trigger a boot from an invalid source by overwriting the boot source to an invalid media for the next boot and then reset the device. <br><code>boot_from_sd</code>
# If no new output is printed on the serial console (serial port), continue with the flashing procedure

U-Boot recovery for i.MX6 Q/D/DL/S/ULL via JTAG v2

2023-10-11T13:42:15Z

Jneuhauser:

U-Boot recovery for i.MX6 Q/D/DL/S/ULL via JTAG v2

2023-08-28T12:56:06Z

Jneuhauser: Initial v2 with untested i.MX6ULL

This guide details the process of flashing U-Boot onto our i.MX6 based DHCOM using OpenOCD.
The hardware configuration, software installation, and step-by-step programming procedures are provided.

== Required Hardware ==
* Baseboard as power source for DHCOM
* JTAG Debugger: [https://www.olimex.com/Products/ARM/JTAG/ARM-USB-TINY-H/ Olimex Arm-USB-OCD-Tiny-H]
:All tests and documents were made with this one, but technically all JTAG adapters listed by OpenOCD should work.
* DHCOM JTAG adapter for FFC connection: Article number FD00037
:[[File:JTAG-Adapter.jpeg|300px]]
* Wuerth FFC cable: [https://www.we-online.com/de/components/products/FFC_0_50_TYPE_1_6876XXXXX002 687610050002]
:Note: One cable is included with the DHCOM JTAG adapter.

== Installation ==
This installation was made on the [[Virtual Machine for Application Development]].
All console expressions refer to this Debian system, but any other debian based system should also work.

<div style="color:red">To support all our i.MX6 based DHCOM, it is necessary to have OpenOCD v0.11.0 or higher.</div>

=== OpenOCD from master branch (before Debian 11 alias Bullseye) ===
# Install needed libraries and tools <br><code>sudo apt-get install git build-essential pkg-config autoconf automake libtool libusb-dev libusb-1.0-0-dev libhidapi-dev libftdi-dev</code>
# Clone git repository to local directory and checkout v0.12.0 tag <br><code>git clone -b v0.12.0 https://repo.or.cz/openocd.git</code>
# Change working directory to the extracted one <br><code>cd openocd</code>
# Prepare source directory and submodules (when building from the git repository) <br><code>./bootstrap</code>
# Generate the Makefiles to build OpenOCD <br><code>./configure</code>
# Build OpenOCD from source <br><code>make -j4</code>
# Install OpenOCD to /usr/local <br><code>sudo make install</code>
# (optional) Remove openocd source directory <br><code>cd .. && rm -rf openocd</code>

=== OpenOCD from Debian repositories (since Debian 11 alias Bullseye) ===
# Install OpenOCD from Debian repositories <br><code>sudo apt-get install openocd</code>

=== Non root access to tty devices ===
# Add your user to the dialout group: <br><code>sudo usermod -a -G dialout ${USER}</code>
# Add your user to the plugdev group: <br><code>sudo usermod -a -G plugdev ${USER}</code>
# Logout and login to apply new group rights

== U-Boot Programming ==
There are two ways for doing this.
The easy way is an automatic shell script, which handles all the commands needed for the programming process.
The other one is to type in the required commands.
In a few cases the shell script fails then you need to go the other way and program the U-Boot manually.
The steps [[#Preparation|Preparation]] and [[#Start up OpenOCD|Start up OpenOCD]] are required for both automatic and manual flash programming.

=== Preparation ===
==== Get the needed recovery files ====
# Download and extract the needed files [[media:2023-08-28_imx6_U-Boot_recovery.tar.xz|| tar xJ</code>
# Change working directory to the extracted one <br><code>cd 2023-08-28_imx6_U-Boot_recovery</code>
==== Connect JTAG adapter ====
# Connect the JTAG adapter with your PC and the Debian VM (Player - Removeable Devices) through USB
# Connect the JTAG interface via the DHCOM JTAG adapter to the i.MX6 module (If you don't have a JTAG adapter, please ask DH electronics)
#:[[File:JTAG-connection.jpeg|1000px]]]
# Put the SODIMM-200 module (DHCOM) into the SODIMM-200 slot on your basebord
# Connect to the serial console (serial port) of the board like here [[COM_iMX6_Bootloader_U-Boot#Enter_Bootloader_Console|Enter_Bootloader_Console]]

=== Start up OpenOCD ===
# Ensure you have everything properly connected like in [[#Connect JTAG adapter|Connect JTAG adapter]]
# Power up the i.MX6 board and have a look at the serial output (serial port). There must be no output (no U-Boot starting) else go to [[#Troubleshooting|Troubleshooting]]
# Open a new terminal window (local shell console)
# Ensure you are in the directory with the recovery files <br><code>cd /path/to/2020-03-10_imx6_U-Boot_recovery</code>
# Start OpenOCD depending on your hardware
#:* '''i.MX6 Q/D/DL/S'''<br><code>openocd -f interface/ftdi/olimex-arm-usb-tiny-h.cfg -f target/imx6.cfg -f dhcom-manual-loaded-code.cfg</code>
#:* '''i.MX6 ULL'''<br><code>openocd -f interface/ftdi/olimex-arm-usb-tiny-h.cfg -f imx6ull.cfg -f target/imx6ul.cfg -f dhcom-manual-loaded-code.cfg</code>
'''The output should look like:'''
<nowiki>
Open On-Chip Debugger 0.12.0
Licensed under GNU GPL v2
For bug reports, read
http://openocd.org/doc/doxygen/bugs.html
Info : auto-selecting first available session transport "jtag". To override use 'transport select <transport>'.
Warn : imx6.sdma: nonstandard IR value
boot_from_sd
Info : Listening on port 6666 for tcl connections
Info : Listening on port 4444 for telnet connections
Info : clock speed 1000 kHz
Info : JTAG tap: imx6.cpu tap/device found: 0x4ba00477 (mfg: 0x23b (ARM Ltd), part: 0xba00, ver: 0x4)
Info : TAP imx6.sdma does not have valid IDCODE (idcode=0x4323803a)
Info : JTAG tap: imx6.sjc tap/device found: 0x2191c01d (mfg: 0x00e (Freescale (Motorola)), part: 0x191c, ver: 0x2)
Info : imx6.cpu.0: hardware has 6 breakpoints, 4 watchpoints
Info : starting gdb server for imx6.cpu.0 on 3333
Info : Listening on port 3333 for gdb connections</nowiki>

=== Automated Programming ===
# Ensure OpenOCD is running like in [[#Start up OpenOCD|Start up OpenOCD]]
# Open a second terminal window (local shell console)
# Ensure you are in the directory with the recovery files <br><code>cd /path/to/2023-08-28_imx6_U-Boot_recovery</code>
# Execute the automated bash script with arguments depending on your hardware and desired U-Boot
#:* Default DH U-Boot
#:** '''i.MX6 Q/D/DL/S'''<br><code>sh prog_bl.sh imx6qdl</code>
#:** '''i.MX6 ULL'''<br><code>sh prog_bl.sh imx6ull</code>
#:* Custom U-Boot
#:** '''i.MX6 Q/D/DL/S'''<br><code>sh prog_bl.sh imx6qdl /path/to/u-boot-with-spl.imx</code>
#:** '''i.MX6 ULL'''<br><code>sh prog_bl.sh imx6ull /path/to/u-boot-with-spl.imx</code>
'''On success the output of the script should look like:'''
<nowiki>
Programming: u-boot-with-spl-imx6qdl.imx to imx6qdl
Trying ::1...
Connection failed: Connection refused
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
Open On-Chip Debugger
> boot_from_sd
imx6.cpu.0: MPIDR level2 0, cluster 0, core 0, multi core, no SMT
target halted in Thumb state due to debug-request, current mode: Supervisor
cpsr: 0xa00001f3 pc: 0x8ff7a982
MMU: enabled, D-Cache: enabled, I-Cache: enabled
Invalid ACK (0) in DAP response
Could not read DSCR register
Error waiting for cortex_a_exec_opcode
Invalid ACK (0) in DAP response
Could not read DSCR register
Invalid ACK (0) in DAP response
JTAG-DP STICKY ERROR
Could not read DSCR register
Error waiting for dpm prepare

Invalid ACK (7) in DAP response
Polling target imx6.cpu.0 failed, trying to reexamine
Debug regions are unpowered, an unexpected reset might have happened
JTAG-DP STICKY ERROR
Could not initialize the APB-AP
Examination failed, GDB will be halted. Polling again in 100ms
JTAG-DP STICKY ERROR
Polling target imx6.cpu.0 failed, trying to reexamine
imx6.cpu.0: hardware has 6 breakpoints, 4 watchpoints
> prepare_code_load
target halted in Thumb state due to debug-request, current mode: Supervisor
cpsr: 0x800001f3 pc: 0x8ff7a982
MMU: disabled, D-Cache: disabled, I-Cache: disabled
> load_image u-boot-spl-prog-imx6qdl.bin 0x908000
32768 bytes written at address 0x00908000
downloaded 32768 bytes in 1.152152s (27.774 KiB/s)

> resume
> halt
target halted in Thumb state due to debug-request, current mode: Supervisor
cpsr: 0x800001f3 pc: 0x0090ba5e
MMU: disabled, D-Cache: disabled, I-Cache: enabled
> load_image u-boot-with-spl-imx6qdl.imx 0x12000000
567752 bytes written at address 0x12000000
downloaded 567752 bytes in 18.675529s (29.688 KiB/s)

> resume
> Connection closed by foreign host.</nowiki>
'''On success the output of serial console (serial port) should look like:'''
<nowiki>
U-Boot SPL 2018.05-23076-g8686cf2574 (Mar 10 2020 - 10:26:00 +0100)
SPL: Unsupported Boot Device!
SPL: failed to boot from all boot devices
### ERROR ### Please RESET the board ###
Searching for IVT header at DDR address 0x12000000
....
Found IVT header
Determinded image length: 0x8a9c8

### Recovery ### Trying to program SPI flash ###
Probing SPI flash... ok
Erasing SPI flash... ok
Programming SPI flash... ok

### Recovery ### Finished ###</nowiki>
'''Note:''' If some error occures you can try the [[#Manual Programming|Manual Programming]] method below

=== Manual Programming ===
# Ensure OpenOCD is running like in [[#Start up OpenOCD|Start up OpenOCD]]
# Open a second terminal window (local shell console)
# Ensure you are in the directory with the recovery files <br><code>cd /path/to/2023-08-28_imx6_U-Boot_recovery</code>
# Open a telnet session to OpenOCD <br><code>telnet localhost 4444</code>
## Ensure device boot fails by booting from invalid media<br><code>boot_from_sd</code>
## Prepare for running manual loaded code<br><code>prepare_code_load</code>
## Load modified U-Boot SPL as flash programmer in SRAM (device dependent)
##:* '''i.MX6 Q/D/DL/S'''<br><code>load_image u-boot-spl-prog-imx6qdl.bin 0x908000</code>
##:* '''i.MX6 ULL'''<br><code>load_image u-boot-spl-prog-imx6ull.bin 0x908000</code>
## Resume code execution at entry point of loaded U-Boot SPL <br><code>resume 0x00908000</code>
## Halt code execution if you see '''Searching for IVT header at DDR address 0xX2000000''' in serial console <br><code>halt</code>
## Load desired U-Boot image into RAM (device and customer dependent)
##:* '''i.MX6 Q/D/DL/S'''<br><code>load_image u-boot-with-spl-imx6qdl.imx 0x12000000</code>
##:* '''i.MX6 ULL'''<br><code>load_image u-boot-with-spl-imx6ull.imx 0x82000000</code>
## Resume code execution after U-Boot image is in RAM<br><code>resume</code>
## Wait until the serial output (serial port) looks like in [[#Automated Programming|Automated Programming]]
## Exit telnet with <code>exit</code> and close OpenOCD with STRG+C

== Troubleshooting ==
If there is a U-Boot starting, the OpenOCD procedure may not work properly.
There are two solutions to prevent the start of U-Boot from the SPI-NOR-Flash.

=== SDP Boot (only i.MX6 ULL) ===
# Boot in Serial Download Mode to prevent booting the broken U-Boot from SPI-NOR-Flash
## Hold the button for sdp boot mode on the SODIMM-200 module (DHCOM) next to the BGA module (DHCOR)
##:[[File:DHCOR_i.MX6ULL_SDP-Boot.jpg|400px]]
## Reset the device. To reset the device, press the reset button on the baseboard or unplug and plug in the power plug.
## Release the button for sdp boot mode
# If no new output is printed on the serial console (serial port), continue with the flashing procedure

U-Boot recovery for i.MX6 Q/D/DL/S/ULL via JTAG

2023-08-22T13:59:41Z

Jneuhauser: Fix recovery file path

This guide details the process of flashing U-Boot onto our i.MX6 based DHCOM using OpenOCD.
The hardware configuration, software installation, and step-by-step programming procedures are provided.

== Required Hardware ==
* Baseboard as power source for DHCOM
* JTAG Debugger: [https://www.olimex.com/Products/ARM/JTAG/ARM-USB-TINY-H/ Olimex Arm-USB-OCD-Tiny-H]
:All tests and documents were made with this one, but technically all JTAG adapters listed by OpenOCD should work.
* DHCOM JTAG adapter for FFC connection: Article number FD00037
:[[File:JTAG-Adapter.jpeg|300px]]
* Wuerth FFC cable: [https://www.we-online.com/de/components/products/FFC_0_50_TYPE_1_6876XXXXX002 687610050002]
:Note: One cable is included with the DHCOM JTAG adapter.

== Installation ==
This installation was made on the [[Virtual Machine for Application Development]].
All console expressions refer to this Debian system, but any other debian based system should also work.

<div style="color:red">To support all our i.MX6 based DHCOM, it is necessary to have OpenOCD v0.11.0 or higher.</div>

=== OpenOCD from master branch (before Debian 11 alias Bullseye) ===
# Install needed libraries and tools <br><code>sudo apt-get install git build-essential pkg-config autoconf automake libtool libusb-dev libusb-1.0-0-dev libhidapi-dev libftdi-dev</code>
# Clone git repository to local directory and checkout v0.12.0 tag <br><code>git clone -b v0.12.0 https://repo.or.cz/openocd.git</code>
# Change working directory to the extracted one <br><code>cd openocd</code>
# Prepare source directory and submodules (when building from the git repository) <br><code>./bootstrap</code>
# Generate the Makefiles to build OpenOCD <br><code>./configure</code>
# Build OpenOCD from source <br><code>make -j4</code>
# Install OpenOCD to /usr/local <br><code>sudo make install</code>
# (optional) Remove openocd source directory <br><code>cd .. && rm -rf openocd</code>

=== OpenOCD from Debian repositories (since Debian 11 alias Bullseye) ===
# Install OpenOCD from Debian repositories <br><code>sudo apt-get install openocd</code>

=== Non root access to tty devices ===
# Add your user to the dialout group: <br><code>sudo usermod -a -G dialout ${USER}</code>
# Add your user to the plugdev group: <br><code>sudo usermod -a -G plugdev ${USER}</code>
# Logout and login to apply new group rights

== U-Boot Programming ==
There are two ways for doing this.
The easy way is an automatic bash script, which handles all the commands needed for the programming process.
The other one is to type in the required commands.
In a few cases the bash script fails then you need to go the other way and program the U-Boot manually.
The steps [[#Preparation|Preparation]] and [[#Start up OpenOCD|Start up OpenOCD]] are required for both automatic and manual flash programming.

=== Preparation ===
==== Get the needed recovery files ====
# Download and extract the needed files [[media:2020-03-10_imx6_U-Boot_recovery.tar.gz|| tar xz</code>
# Change working directory to the extracted one <br><code>cd 2020-03-10_imx6_U-Boot_recovery</code>
==== Connect JTAG adapter ====
# Connect the JTAG adapter with your PC and the Debian VM (Player - Removeable Devices) through USB
# Connect the JTAG interface via the DHCOM JTAG adapter to the i.MX6 module (If you don't have a JTAG adapter, please ask DH electronics)
#:[[File:JTAG-connection.jpeg|1000px]]]
# Put the SODIMM-200 module (DHCOM) into the SODIMM-200 slot on your basebord
# Connect to the serial console (serial port) of the board like here [[COM_iMX6_Bootloader_U-Boot#Enter_Bootloader_Console|Enter_Bootloader_Console]]

=== Start up OpenOCD ===
# Ensure you have everything properly connected like in [[#Connect JTAG adapter|Connect JTAG adapter]]
# Power up the i.MX6 board and have a look at the serial output (serial port). There must be no output (no U-Boot starting) else go to [[#Troubleshooting|Troubleshooting]]
# Open a new terminal window (local shell console)
# Ensure you are in the directory with the recovery files <br><code>cd /path/to/2020-03-10_imx6_U-Boot_recovery</code>
# Start OpenOCD depending on your hardware
#:* '''i.MX6 Q/D/DL/S'''<br><code>openocd -f interface/ftdi/olimex-arm-usb-tiny-h.cfg -f target/imx6.cfg -f dhcom-manual-loaded-code.cfg</code>
#:* '''i.MX6 ULL'''<br><code>openocd -f interface/ftdi/olimex-arm-usb-tiny-h.cfg -f imx6ull.cfg -f target/imx6ul.cfg -f dhcom-manual-loaded-code.cfg</code>
'''The output should look like:'''
<nowiki>
Open On-Chip Debugger 0.10.0+dev-00935-g31100927 (2019-10-01-12:14)
Licensed under GNU GPL v2
For bug reports, read
http://openocd.org/doc/doxygen/bugs.html
0x088c101d
Info : auto-selecting first available session transport "jtag". To override use 'transport select <transport>'.
Warn : imx6ull.sdma: nonstandard IR value
2182283264
imx6_dummy_init
Info : Listening on port 6666 for tcl connections
Info : Listening on port 4444 for telnet connections
Info : clock speed 1000 kHz
Info : JTAG tap: imx6ull.cpu tap/device found: 0x5ba00477 (mfg: 0x23b (ARM Ltd.), part: 0xba00, ver: 0x5)
Info : TAP imx6ull.sdma does not have IDCODE
Info : JTAG tap: imx6ull.sjc tap/device found: 0x088c101d (mfg: 0x00e (Freescale (Motorola)), part: 0x88c1, ver: 0x0)
Info : imx6ull.cpu: hardware has 6 breakpoints, 4 watchpoints
Info : Listening on port 3333 for gdb connections</nowiki>

=== Automated Programming ===
# Ensure OpenOCD is running like in [[#Start up OpenOCD|Start up OpenOCD]]
# Open a second terminal window (local shell console)
# Ensure you are in the directory with the recovery files <br><code>cd /path/to/2019-10-08_imx6_U-Boot_recovery</code>
# Execute the automated bash script with arguments depending on your hardware and desired U-Boot
#:* Default DH U-Boot
#:** '''i.MX6 Q/D/DL/S'''<br><code>./prog_bl.sh imx6qdl</code>
#:** '''i.MX6 ULL'''<br><code>./prog_bl.sh imx6ull</code>
#:* Custom U-Boot
#:** '''i.MX6 Q/D/DL/S'''<br><code>./prog_bl.sh imx6qdl /path/to/u-boot-with-spl.imx</code>
#:** '''i.MX6 ULL'''<br><code>./prog_bl.sh imx6ull /path/to/u-boot-with-spl.imx</code>
'''On success the output of the script should look like:'''
<nowiki>
Programming: u-boot-with-spl-imx6ull.imx to imx6ull
Trying ::1...
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
Open On-Chip Debugger
> reset
JTAG tap: imx6ull.cpu tap/device found: 0x5ba00477 (mfg: 0x23b (ARM Ltd.), part: 0xba00, ver: 0x5)
TAP imx6ull.sdma does not have IDCODE
JTAG tap: imx6ull.sjc tap/device found: 0x088c101d (mfg: 0x00e (Freescale (Motorola)), part: 0x88c1, ver: 0x0)
imx6ull.cpu rev 5, partnum c07, arch f, variant 0, implementor 41
imx6ull.cpu: MPIDR level2 0, cluster 0, core 0, multi core, no SMT
target halted in Thumb state due to debug-request, current mode: Supervisor
cpsr: 0x400001f3 pc: 0x00002f76
MMU: disabled, D-Cache: disabled, I-Cache: enabled
imx6ull.cpu rev 5, partnum c07, arch f, variant 0, implementor 41
target halted in Thumb state due to debug-request, current mode: Supervisor
cpsr: 0x400001f3 pc: 0x00002f74
MMU: disabled, D-Cache: disabled, I-Cache: enabled
> load_image u-boot-spl-prog-imx6ull.bin 0x908000
45056 bytes written at address 0x00908000
downloaded 45056 bytes in 1.610037s (27.329 KiB/s)

> resume 0x00908000
> halt
imx6ull.cpu rev 5, partnum c07, arch f, variant 0, implementor 41
target halted in Thumb state due to debug-request, current mode: Supervisor
cpsr: 0x800001f3 pc: 0x00908934
MMU: disabled, D-Cache: disabled, I-Cache: enabled
> load_image u-boot-with-spl-imx6ull.imx 0x82000000
451456 bytes written at address 0x82000000
downloaded 451456 bytes in 15.305990s (28.804 KiB/s)

> resume
> Connection closed by foreign host.</nowiki>
'''On success the output of serial console (serial port) should look like:'''
<nowiki>
U-Boot SPL 2018.05-DH_v0.19_emmc-00102-gc8e3c3df13 (Oct 01 2019 - 16:12:44 +0200)
DRAM: Auto calibration...successful
SPL: Unsupported Boot Device!
SPL: failed to boot from all boot devices
### ERROR ### Please RESET the board ###
Searching for IVT header at DDR address 0x82000000
.....
Found IVT header
Probing SPI flash... ok
Erasing... ok
Programming... ok
</nowiki>
'''Note:''' If some error occures you can try the [[#Manual Programming|Manual Programming]] method below

=== Manual Programming ===
# Ensure OpenOCD is running like in [[#Start up OpenOCD|Start up OpenOCD]]
# Open a second terminal window (local shell console)
# Ensure you are in the directory with the recovery files <br><code>cd /path/to/2019-10-08_imx6_U-Boot_recovery</code>
# Open a telnet session to OpenOCD <br><code>telnet localhost 4444</code>
## Reset and halt the device <br><code>reset</code>
## Load modified U-Boot SPL as flash programmer in SRAM (device dependent)
##:* '''i.MX6 Q/D/DL/S'''<br><code>load_image u-boot-spl-prog-imx6qdl.bin 0x908000</code>
##:* '''i.MX6 ULL'''<br><code>load_image u-boot-spl-prog-imx6ull.bin 0x908000</code>
## Resume code execution at entry point of loaded U-Boot SPL <br><code>resume 0x00908000</code>
## Halt code execution if you see '''Searching for IVT header at DDR address 0xX2000000''' in serial console <br><code>halt</code>
## Load desired U-Boot image into RAM (device and customer dependent)
##:* '''i.MX6 Q/D/DL/S'''<br><code>load_image u-boot-with-spl-imx6qdl.imx 0x12000000</code>
##:* '''i.MX6 ULL'''<br><code>load_image u-boot-with-spl-imx6ull.imx 0x82000000</code>
## Resume code execution after U-Boot image is in RAM<br><code>resume</code>
## Wait until the serial output (serial port) looks like in [[#Automated Programming|Automated Programming]]

== Troubleshooting ==
If there is a U-Boot starting, the OpenOCD procedure may not work properly.
There are two solutions to prevent the start of U-Boot from the SPI-NOR-Flash.

=== SDP Boot (only i.MX6 ULL) ===
# Boot in Serial Download Mode to prevent booting the broken U-Boot from SPI-NOR-Flash
## Hold the button for sdp boot mode on the SODIMM-200 module (DHCOM) next to the BGA module (DHCOR)
##:[[File:DHCOR_i.MX6ULL_SDP-Boot.jpg|400px]]
## Reset the device. To reset the device, press the reset button on the baseboard or unplug and plug in the power plug.
## Release the button for sdp boot mode
# If no new output is printed on the serial console (serial port), continue with the flashing procedure

=== Delete U-Boot ===
# <code>sf probe</code>
# <code>sf erase 0x0 0xf0000</code>
# Restart the board
# If no new output is printed on the serial console (serial port), continue with the flashing procedure

U-Boot recovery for i.MX6 Q/D/DL/S/ULL via JTAG

2023-08-22T13:48:38Z

Jneuhauser: Update descriptions and fix broken links

This guide details the process of flashing U-Boot onto our i.MX6 based DHCOM using OpenOCD.
The hardware configuration, software installation, and step-by-step programming procedures are provided.

== Required Hardware ==
* Baseboard as power source for DHCOM
* JTAG Debugger: [https://www.olimex.com/Products/ARM/JTAG/ARM-USB-TINY-H/ Olimex Arm-USB-OCD-Tiny-H]
:All tests and documents were made with this one, but technically all JTAG adapters listed by OpenOCD should work.
* DHCOM JTAG adapter for FFC connection: Article number FD00037
:[[File:JTAG-Adapter.jpeg|300px]]
* Wuerth FFC cable: [https://www.we-online.com/de/components/products/FFC_0_50_TYPE_1_6876XXXXX002 687610050002]
:Note: One cable is included with the DHCOM JTAG adapter.

== Installation ==
This installation was made on the [[Virtual Machine for Application Development]].
All console expressions refer to this Debian system, but any other debian based system should also work.

<div style="color:red">To support all our i.MX6 based DHCOM, it is necessary to have OpenOCD v0.11.0 or higher.</div>

=== OpenOCD from master branch (before Debian 11 alias Bullseye) ===
# Install needed libraries and tools <br><code>sudo apt-get install git build-essential pkg-config autoconf automake libtool libusb-dev libusb-1.0-0-dev libhidapi-dev libftdi-dev</code>
# Clone git repository to local directory and checkout v0.12.0 tag <br><code>git clone -b v0.12.0 https://repo.or.cz/openocd.git</code>
# Change working directory to the extracted one <br><code>cd openocd</code>
# Prepare source directory and submodules (when building from the git repository) <br><code>./bootstrap</code>
# Generate the Makefiles to build OpenOCD <br><code>./configure</code>
# Build OpenOCD from source <br><code>make -j4</code>
# Install OpenOCD to /usr/local <br><code>sudo make install</code>
# (optional) Remove openocd source directory <br><code>cd .. && rm -rf openocd</code>

=== OpenOCD from Debian repositories (since Debian 11 alias Bullseye) ===
# Install OpenOCD from Debian repositories <br><code>sudo apt-get install openocd</code>

=== Non root access to tty devices ===
# Add your user to the dialout group: <br><code>sudo usermod -a -G dialout ${USER}</code>
# Add your user to the plugdev group: <br><code>sudo usermod -a -G plugdev ${USER}</code>
# Logout and login to apply new group rights

== U-Boot Programming ==
There are two ways for doing this.
The easy way is an automatic bash script, which handles all the commands needed for the programming process.
The other one is to type in the required commands.
In a few cases the bash script fails then you need to go the other way and program the U-Boot manually.
The steps [[#Preparation|Preparation]] and [[#Start up OpenOCD|Start up OpenOCD]] are required for both automatic and manual flash programming.

=== Preparation ===
==== Get the needed recovery files ====
# Download and extract the needed files [[media:2020-03-10_imx6_U-Boot_recovery.tar.gz|| tar xz</code>
# Change working directory to the extracted one <br><code>cd 2020-03-10_imx6_U-Boot_recovery</code>
==== Connect JTAG adapter ====
# Connect the JTAG adapter with your PC and the Debian VM (Player - Removeable Devices) through USB
# Connect the JTAG interface via the DHCOM JTAG adapter to the i.MX6 module (If you don't have a JTAG adapter, please ask DH electronics)
#:[[File:JTAG-connection.jpeg|1000px]]]
# Put the SODIMM-200 module (DHCOM) into the SODIMM-200 slot on your basebord
# Connect to the serial console (serial port) of the board like here [[COM_iMX6_Bootloader_U-Boot#Enter_Bootloader_Console|Enter_Bootloader_Console]]

=== Start up OpenOCD ===
# Ensure you have everything properly connected like in [[#Connect JTAG adapter|Connect JTAG adapter]]
# Power up the i.MX6 board and have a look at the serial output (serial port). There must be no output (no U-Boot starting) else go to [[#Troubleshooting|Troubleshooting]]
# Open a new terminal window (local shell console)
# Ensure you are in the directory with the recovery files <br><code>cd /path/to/2019-10-08_imx6_U-Boot_recovery</code>
# Start OpenOCD depending on your hardware
#:* '''i.MX6 Q/D/DL/S'''<br><code>openocd -f interface/ftdi/olimex-arm-usb-tiny-h.cfg -f target/imx6.cfg -f dhcom-manual-loaded-code.cfg</code>
#:* '''i.MX6 ULL'''<br><code>openocd -f interface/ftdi/olimex-arm-usb-tiny-h.cfg -f imx6ull.cfg -f target/imx6ul.cfg -f dhcom-manual-loaded-code.cfg</code>
'''The output should look like:'''
<nowiki>
Open On-Chip Debugger 0.10.0+dev-00935-g31100927 (2019-10-01-12:14)
Licensed under GNU GPL v2
For bug reports, read
http://openocd.org/doc/doxygen/bugs.html
0x088c101d
Info : auto-selecting first available session transport "jtag". To override use 'transport select <transport>'.
Warn : imx6ull.sdma: nonstandard IR value
2182283264
imx6_dummy_init
Info : Listening on port 6666 for tcl connections
Info : Listening on port 4444 for telnet connections
Info : clock speed 1000 kHz
Info : JTAG tap: imx6ull.cpu tap/device found: 0x5ba00477 (mfg: 0x23b (ARM Ltd.), part: 0xba00, ver: 0x5)
Info : TAP imx6ull.sdma does not have IDCODE
Info : JTAG tap: imx6ull.sjc tap/device found: 0x088c101d (mfg: 0x00e (Freescale (Motorola)), part: 0x88c1, ver: 0x0)
Info : imx6ull.cpu: hardware has 6 breakpoints, 4 watchpoints
Info : Listening on port 3333 for gdb connections</nowiki>

=== Automated Programming ===
# Ensure OpenOCD is running like in [[#Start up OpenOCD|Start up OpenOCD]]
# Open a second terminal window (local shell console)
# Ensure you are in the directory with the recovery files <br><code>cd /path/to/2019-10-08_imx6_U-Boot_recovery</code>
# Execute the automated bash script with arguments depending on your hardware and desired U-Boot
#:* Default DH U-Boot
#:** '''i.MX6 Q/D/DL/S'''<br><code>./prog_bl.sh imx6qdl</code>
#:** '''i.MX6 ULL'''<br><code>./prog_bl.sh imx6ull</code>
#:* Custom U-Boot
#:** '''i.MX6 Q/D/DL/S'''<br><code>./prog_bl.sh imx6qdl /path/to/u-boot-with-spl.imx</code>
#:** '''i.MX6 ULL'''<br><code>./prog_bl.sh imx6ull /path/to/u-boot-with-spl.imx</code>
'''On success the output of the script should look like:'''
<nowiki>
Programming: u-boot-with-spl-imx6ull.imx to imx6ull
Trying ::1...
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
Open On-Chip Debugger
> reset
JTAG tap: imx6ull.cpu tap/device found: 0x5ba00477 (mfg: 0x23b (ARM Ltd.), part: 0xba00, ver: 0x5)
TAP imx6ull.sdma does not have IDCODE
JTAG tap: imx6ull.sjc tap/device found: 0x088c101d (mfg: 0x00e (Freescale (Motorola)), part: 0x88c1, ver: 0x0)
imx6ull.cpu rev 5, partnum c07, arch f, variant 0, implementor 41
imx6ull.cpu: MPIDR level2 0, cluster 0, core 0, multi core, no SMT
target halted in Thumb state due to debug-request, current mode: Supervisor
cpsr: 0x400001f3 pc: 0x00002f76
MMU: disabled, D-Cache: disabled, I-Cache: enabled
imx6ull.cpu rev 5, partnum c07, arch f, variant 0, implementor 41
target halted in Thumb state due to debug-request, current mode: Supervisor
cpsr: 0x400001f3 pc: 0x00002f74
MMU: disabled, D-Cache: disabled, I-Cache: enabled
> load_image u-boot-spl-prog-imx6ull.bin 0x908000
45056 bytes written at address 0x00908000
downloaded 45056 bytes in 1.610037s (27.329 KiB/s)

> resume 0x00908000
> halt
imx6ull.cpu rev 5, partnum c07, arch f, variant 0, implementor 41
target halted in Thumb state due to debug-request, current mode: Supervisor
cpsr: 0x800001f3 pc: 0x00908934
MMU: disabled, D-Cache: disabled, I-Cache: enabled
> load_image u-boot-with-spl-imx6ull.imx 0x82000000
451456 bytes written at address 0x82000000
downloaded 451456 bytes in 15.305990s (28.804 KiB/s)

> resume
> Connection closed by foreign host.</nowiki>
'''On success the output of serial console (serial port) should look like:'''
<nowiki>
U-Boot SPL 2018.05-DH_v0.19_emmc-00102-gc8e3c3df13 (Oct 01 2019 - 16:12:44 +0200)
DRAM: Auto calibration...successful
SPL: Unsupported Boot Device!
SPL: failed to boot from all boot devices
### ERROR ### Please RESET the board ###
Searching for IVT header at DDR address 0x82000000
.....
Found IVT header
Probing SPI flash... ok
Erasing... ok
Programming... ok
</nowiki>
'''Note:''' If some error occures you can try the [[#Manual Programming|Manual Programming]] method below

=== Manual Programming ===
# Ensure OpenOCD is running like in [[#Start up OpenOCD|Start up OpenOCD]]
# Open a second terminal window (local shell console)
# Ensure you are in the directory with the recovery files <br><code>cd /path/to/2019-10-08_imx6_U-Boot_recovery</code>
# Open a telnet session to OpenOCD <br><code>telnet localhost 4444</code>
## Reset and halt the device <br><code>reset</code>
## Load modified U-Boot SPL as flash programmer in SRAM (device dependent)
##:* '''i.MX6 Q/D/DL/S'''<br><code>load_image u-boot-spl-prog-imx6qdl.bin 0x908000</code>
##:* '''i.MX6 ULL'''<br><code>load_image u-boot-spl-prog-imx6ull.bin 0x908000</code>
## Resume code execution at entry point of loaded U-Boot SPL <br><code>resume 0x00908000</code>
## Halt code execution if you see '''Searching for IVT header at DDR address 0xX2000000''' in serial console <br><code>halt</code>
## Load desired U-Boot image into RAM (device and customer dependent)
##:* '''i.MX6 Q/D/DL/S'''<br><code>load_image u-boot-with-spl-imx6qdl.imx 0x12000000</code>
##:* '''i.MX6 ULL'''<br><code>load_image u-boot-with-spl-imx6ull.imx 0x82000000</code>
## Resume code execution after U-Boot image is in RAM<br><code>resume</code>
## Wait until the serial output (serial port) looks like in [[#Automated Programming|Automated Programming]]

== Troubleshooting ==
If there is a U-Boot starting, the OpenOCD procedure may not work properly.
There are two solutions to prevent the start of U-Boot from the SPI-NOR-Flash.

=== SDP Boot (only i.MX6 ULL) ===
# Boot in Serial Download Mode to prevent booting the broken U-Boot from SPI-NOR-Flash
## Hold the button for sdp boot mode on the SODIMM-200 module (DHCOM) next to the BGA module (DHCOR)
##:[[File:DHCOR_i.MX6ULL_SDP-Boot.jpg|400px]]
## Reset the device. To reset the device, press the reset button on the baseboard or unplug and plug in the power plug.
## Release the button for sdp boot mode
# If no new output is printed on the serial console (serial port), continue with the flashing procedure

=== Delete U-Boot ===
# <code>sf probe</code>
# <code>sf erase 0x0 0xf0000</code>
# Restart the board
# If no new output is printed on the serial console (serial port), continue with the flashing procedure

Yocto build guide with docker

2022-11-24T14:54:46Z

Jneuhauser: Update to /path/to/kas-dhsom #2

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

= Requirements =

To build Yocto images you need a powerfull build machine and a lot of time.

== Hardware ==

* CPU: four cores or more
* RAM: 16 GB or more
* HDD/SSD: from 25 GB to 100 GB free space (depends on included features)

== Software ==

* Linux OS
* Docker

= Start your build environment =

The following two examples show how to create yocto images using the <syntaxhighlight lang="shell" inline>kas</syntaxhighlight> container or the <syntaxhighlight lang="shell" inline>kas-container</syntaxhighlight> script.

In the following examples, we use the meta-dhsom-stm32-bsp layer as the top layer for creating images for the STM32MP15 DHSOM family with our baseboards.
If you have your own layer on top because you have a custom DHSOM baseboard, then you must replace meta-dhsom-stm32-bsp with your own layer in all commands.

See the documentation for how to use the <syntaxhighlight lang="shell" inline>kas</syntaxhighlight> tool:
* https://kas.readthedocs.io/en/latest/userguide.html
* https://kas.readthedocs.io/en/latest/command-line.html

== Docker container based bash shell ==

Preparation:
<syntaxhighlight lang="shell">
export KAS_WORK_DIR=/mnt/work/yocto
export KAS_BUILD_DIR=/mnt/build/yocto

sudo mkdir -p "${KAS_WORK_DIR}" "${KAS_BUILD_DIR}"
sudo chown $(id –u):$(id –g) "${KAS_WORK_DIR}" "${KAS_BUILD_DIR}"

cd /path/to/kas-dhsom

docker run --rm --interactive --tty --init \
--env TERM="xterm-256color" \
--env USER_ID="$(id -u)" --env GROUP_ID="$(id -g)" \
--volume "${KAS_BUILD_DIR}":"${KAS_BUILD_DIR}":rw \
--env KAS_BUILD_DIR="${KAS_BUILD_DIR}" \
--volume "${KAS_WORK_DIR}":"${KAS_WORK_DIR}":rw \
--env KAS_WORK_DIR="${KAS_WORK_DIR}" \
--volume "${PWD}":"${PWD}":rw \
--workdir="${PWD}" \
ghcr.io/siemens/kas/kas:latest-release \
/bin/bash
</syntaxhighlight>

Usage:
<syntaxhighlight lang="shell">
cd /path/to/kas-dhsom
kas menu
kas build
</syntaxhighlight>

== Docker container based kas tool ==

Preparation:
<syntaxhighlight lang="shell">
wget -O kas-container https://github.com/siemens/kas/raw/master/kas-container
chmod +x kas-container
</syntaxhighlight>

Usage:
<syntaxhighlight lang="shell">
cd /path/to/kas-dhsom
/path/to/kas-container menu
/path/to/kas-container build
</syntaxhighlight>

Yocto build guide with docker

2022-11-24T14:54:12Z

Jneuhauser: Update to /path/to/kas-dhsom

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

= Requirements =

To build Yocto images you need a powerfull build machine and a lot of time.

== Hardware ==

* CPU: four cores or more
* RAM: 16 GB or more
* HDD/SSD: from 25 GB to 100 GB free space (depends on included features)

== Software ==

* Linux OS
* Docker

= Start your build environment =

The following two examples show how to create yocto images using the <syntaxhighlight lang="shell" inline>kas</syntaxhighlight> container or the <syntaxhighlight lang="shell" inline>kas-container</syntaxhighlight> script.

In the following examples, we use the meta-dhsom-stm32-bsp layer as the top layer for creating images for the STM32MP15 DHSOM family with our baseboards.
If you have your own layer on top because you have a custom DHSOM baseboard, then you must replace meta-dhsom-stm32-bsp with your own layer in all commands.

See the documentation for how to use the <syntaxhighlight lang="shell" inline>kas</syntaxhighlight> tool:
* https://kas.readthedocs.io/en/latest/userguide.html
* https://kas.readthedocs.io/en/latest/command-line.html

== Docker container based bash shell ==

Preparation:
<syntaxhighlight lang="shell">
export KAS_WORK_DIR=/mnt/work/yocto
export KAS_BUILD_DIR=/mnt/build/yocto

sudo mkdir -p "${KAS_WORK_DIR}" "${KAS_BUILD_DIR}"
sudo chown $(id –u):$(id –g) "${KAS_WORK_DIR}" "${KAS_BUILD_DIR}"

cd /path/to/kas-dhsom

docker run --rm --interactive --tty --init \
--env TERM="xterm-256color" \
--env USER_ID="$(id -u)" --env GROUP_ID="$(id -g)" \
--volume "${KAS_BUILD_DIR}":"${KAS_BUILD_DIR}":rw \
--env KAS_BUILD_DIR="${KAS_BUILD_DIR}" \
--volume "${KAS_WORK_DIR}":"${KAS_WORK_DIR}":rw \
--env KAS_WORK_DIR="${KAS_WORK_DIR}" \
--volume "${PWD}":"${PWD}":rw \
--workdir="${PWD}" \
ghcr.io/siemens/kas/kas:latest-release \
/bin/bash
</syntaxhighlight>

Usage:
<syntaxhighlight lang="shell">
cd /path/to/meta-dhsom-stm32-bsp/kas
kas menu
kas build
</syntaxhighlight>

== Docker container based kas tool ==

Preparation:
<syntaxhighlight lang="shell">
wget -O kas-container https://github.com/siemens/kas/raw/master/kas-container
chmod +x kas-container
</syntaxhighlight>

Usage:
<syntaxhighlight lang="shell">
cd /path/to/kas-dhsom
/path/to/kas-container menu
/path/to/kas-container build
</syntaxhighlight>

Yocto build guide with docker

2022-11-24T14:42:07Z

Jneuhauser: /* Docker container based bash shell */ Update dir creation for KAS_WORK_DIR and KAS_BUILD_DIR

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

= Requirements =

To build Yocto images you need a powerfull build machine and a lot of time.

== Hardware ==

* CPU: four cores or more
* RAM: 16 GB or more
* HDD/SSD: from 25 GB to 100 GB free space (depends on included features)

== Software ==

* Linux OS
* Docker

= Start your build environment =

The following two examples show how to create yocto images using the <syntaxhighlight lang="shell" inline>kas</syntaxhighlight> container or the <syntaxhighlight lang="shell" inline>kas-container</syntaxhighlight> script.

In the following examples, we use the meta-dhsom-stm32-bsp layer as the top layer for creating images for the STM32MP15 DHSOM family with our baseboards.
If you have your own layer on top because you have a custom DHSOM baseboard, then you must replace meta-dhsom-stm32-bsp with your own layer in all commands.

See the documentation for how to use the <syntaxhighlight lang="shell" inline>kas</syntaxhighlight> tool:
* https://kas.readthedocs.io/en/latest/userguide.html
* https://kas.readthedocs.io/en/latest/command-line.html

== Docker container based bash shell ==

Preparation:
<syntaxhighlight lang="shell">
export KAS_WORK_DIR=/mnt/work/yocto
export KAS_BUILD_DIR=/mnt/build/yocto

sudo mkdir -p "${KAS_WORK_DIR}" "${KAS_BUILD_DIR}"
sudo chown $(id –u):$(id –g) "${KAS_WORK_DIR}" "${KAS_BUILD_DIR}"

cd /path/to/meta-dhsom-stm32-bsp

docker run --rm --interactive --tty --init \
--env TERM="xterm-256color" \
--env USER_ID="$(id -u)" --env GROUP_ID="$(id -g)" \
--volume "${KAS_BUILD_DIR}":"${KAS_BUILD_DIR}":rw \
--env KAS_BUILD_DIR="${KAS_BUILD_DIR}" \
--volume "${KAS_WORK_DIR}":"${KAS_WORK_DIR}":rw \
--env KAS_WORK_DIR="${KAS_WORK_DIR}" \
--volume "${PWD}":"${PWD}":rw \
--workdir="${PWD}" \
ghcr.io/siemens/kas/kas:latest-release \
/bin/bash
</syntaxhighlight>

Usage:
<syntaxhighlight lang="shell">
cd /path/to/meta-dhsom-stm32-bsp/kas
kas menu
kas build
</syntaxhighlight>

== Docker container based kas tool ==

Preparation:
<syntaxhighlight lang="shell">
wget -O kas-container https://github.com/siemens/kas/raw/master/kas-container
chmod +x kas-container
</syntaxhighlight>

Usage:
<syntaxhighlight lang="shell">
cd /path/to/meta-dhsom-stm32-bsp/kas
/path/to/kas-container menu
/path/to/kas-container build
</syntaxhighlight>

DHCOM STM32MP15 Secure Boot

2022-11-23T10:15:59Z

Jneuhauser: /* Secure Boot in Trusted Boot with BootROM authentication, TF-A and OP-TEE */ Update upstreaming status

<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 (U-Boot)
|-
| FSBL || Fist Stage Bootloader (TF-A or U-Boot SPL)
|-
| ITS || Image Tree Source (U-Boot)
|-
| 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 ====

Checkout the branch <syntaxhighlight lang="shell" inline>v2022.01_dhcom_secure_boot</syntaxhighlight> from DH electronics GitHub repository with:

<syntaxhighlight lang="shell">
git clone https://github.com/dh-electronics/u-boot-stm32mp1.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 u-boot-stm32mp1 https://github.com/dh-electronics/u-boot-stm32mp1.git
git fetch u-boot-stm32mp1
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-spl-signed.stm32 || FSBL || Same as above but as signed STM32 image. Is created in [[#Sign U-Boot SPL with STM32MP_SigningTool_CLI|Sign U-Boot SPL with STM32MP_SigningTool_CLI]].
|-
| u-boot.itb || SSBL || U-Boot and Device Tree's contained in a FIT image.
|-
| u-boot-signed.itb || SSBL || Same as above but with signed configs and images.
|}

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

Load <syntaxhighlight lang="shell" inline>u-boot-spl-signed.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot-signed.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-signed.stm32
tftp ${fsbl2addr} ${serverip}:u-boot-spl-signed.stm32
tftp ${ssbl1addr} ${serverip}:u-boot-signed.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 =====

<div style="color:blue">Note: If you have any problems with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command use the manual procedure with the generic <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command in the next section.</div>

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

<div style="color:blue">Note: Use this manual procedure only if you have problems with the simpler <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command from the previous section.</div>

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: A Yocto example project would be the best!</div>

== Support of STM32MP1 DHSOM in TF-A, OP-TEE OS and OP-TEE Developer Setup ==

The following table shows the Support status of our STM32MP1-based DHSOMs in the TF-A, OP-TEE OS and OP-TEE Developer Setup projects.
This table is also a good starting point for what is required to support custom boards based on the STM32MP1 DHSOM in these projects.

{| class="wikitable" style="margin:auto"
|+ Support of STM32MP1 DHSOM in TF-A, OP-TEE OS and OP-TEE Developer Setup
|-
! DHSOM
! TF-A<ref name="TF-A" />
! OP-TEE OS<ref name="OP-TEE/optee_os" />
! OP-TEE developer setup<ref name="OP-TEE/build" />
! OP-TEE developer setup Linux<ref name="linaro-swg/linux" />
! OP-TEE developer setup manifest<ref name="OP-TEE/manifest" />
|-
! STM32MP157C DHCOM PDK2
| upstreamed in [https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/commit/?id=eef485abb13b6df9a94137edd82904aab0ecf02d commit eef485ab]
| upstreamed in [https://github.com/OP-TEE/optee_os/commit/6e9896c08ac4d8e81bb95ba1afa46cf6028fd4df commit 6e9896c0]
| upstreamed in [https://github.com/OP-TEE/build/commit/5914639cb690f57a3ce8ba0277ddc6eea2fc3985 commit 5914639c]
| upstreamed in [https://github.com/linaro-swg/linux/commit/2e9ae24784dd51d0a8325871b400795b88f04e2a commit 2e9ae247]
| upstreamed in [https://github.com/OP-TEE/manifest/commit/ef96a36f1821dad69a3fec14c9b75160cdcad351 commit ef96a36f] and [https://github.com/OP-TEE/manifest/commit/2ebdc19d56b2dec9e57dcd2b8024a8023a8665b9 commit 2ebdc19d]
|-
! STM32MP157A DHCOR Avenger96
| upstreamed in [https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/commit/?id=51e223058fe70b311542178f1865514745fa7874 commit 51e22305]
| upstreamed in [https://github.com/OP-TEE/optee_os/commit/5c932a03de3f1126c4710b3b6b296eb720746182 commit 5c932a03]
| upstreamed in [https://github.com/OP-TEE/build/commit/e43efa5b691a5f594db982134d4116ad1e625412 commit e43efa5b]
| upstreamed in [https://github.com/linaro-swg/linux/commit/29aee39cfa576029922eee42542571f730850877 commit 29aee39c]
| upstreamed in [https://github.com/OP-TEE/manifest/commit/ef96a36f1821dad69a3fec14c9b75160cdcad351 commit ef96a36f] and [https://github.com/OP-TEE/manifest/commit/2ebdc19d56b2dec9e57dcd2b8024a8023a8665b9 commit 2ebdc19d]
|}

= Examples for Flatten Image Tree Source files =

This example shows how to define an ITS file with your own content and how to use it from the U-Boot shell.

To build the FIT binary, there is the <syntaxhighlight lang="shell" inline>build_signed_fit_image.sh</syntaxhighlight> script included in the repository mentioned in [[#Checkout_source_code_for_Verified_Boot|Checkout Source Code for Verified Boot]].
<div style="color:blue">Note that you have to change <syntaxhighlight lang="shell" inline>KEY_ALGO</syntaxhighlight>, <syntaxhighlight lang="shell" inline>KEY_NAME_SSBL_IMG</syntaxhighlight> and <syntaxhighlight lang="shell" inline>KEY_NAME_SSBL_CFG</syntaxhighlight> to valid values if you build your image manually with <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight>.</div>
See [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT U-Boot Documentation: doc/uImage.FIT] for more examples and explanations of the possible properties.

== Signed FIT with Linux, ramdisk and device trees ==

Example of an ITS file with Linux, ramdisk and two device trees as images and a configuration for each valid image combination:
<syntaxhighlight lang="c">
/dts-v1/;

/ {
description = "Linux, ramdisk and FDT for DHCOM STM32MP1";
#address-cells = <1>;

images {
linux {
description = "Linux STM32MP15 DHSOM";
data = /incbin/("/mnt/work/linux/arch/arm/boot/Image.gz");
type = "kernel";
os = "linux";
arch = "arm";
/* Image compressed with gzip and decrompressed by U-Boot */
compression = "gzip";
load = <0xc0008000>;
entry = <0xc0008000>;
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

ramdisk {
description = "RootFS ramdisk DHSOM ARMv7";
data = /incbin/("/mnt/work/rootfs/ramdisk.cpio.gz");
type = "ramdisk";
arch = "arm";
os = "linux";
/* ramdisk.cpio.gz compressed with gzip and decrompressed by Linux instead of by U-Boot */
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

fdt-stm32mp157c-dhcom-pdk2 {
description = "FDT STM32MP157C DHCOM Premium Developer Kit (2)";
data = /incbin/("/mnt/work/linux/arch/arm/boot/dts/stm32mp157c-dhcom-pdk2.dtb");
type = "flat_dt";
arch = "arm";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

fdt-stm32mp157c-dhcom-picoitx {
description = "FDT STM32MP157C DHCOM PicoITX";
data = /incbin/("/mnt/work/linux/arch/arm/boot/dts/stm32mp157c-dhcom-picoitx.dtb");
type = "flat_dt";
arch = "arm";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};
};

configurations {
default = "stm32mp157c-dhcom-pdk2";

stm32mp157c-dhcom-pdk2 {
description = "STM32MP157C DHCOM Premium Developer Kit (2)";
kernel = "linux";
ramdisk = "ramdisk";
fdt = "fdt-stm32mp157c-dhcom-pdk2";
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_CFG";
sign-images = "kernel", "ramdisk", "fdt";
};
};

stm32mp157c-dhcom-picoitx {
description = "STM32MP157C DHCOM PicoITX";
kernel = "linux";
ramdisk = "ramdisk";
fdt = "fdt-stm32mp157c-dhcom-picoitx";
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_CFG";
sign-images = "kernel", "ramdisk", "fdt";
};
};
};
};
</syntaxhighlight>

Example U-Boot shell commands to load the FIT file '''linux-signed.itb''' and boot the configuration '''stm32mp157c-dhcom-pdk2''':
<syntaxhighlight lang="shell">
load mmc 0:4 ${loadaddr} /boot/linux-signed.itb
bootm ${loadaddr}#stm32mp157c-dhcom-pdk2
</syntaxhighlight>

== Signed FIT with U-Boot scripts ==

Example of an ITS file with images '''boot''' and '''recovery''' of type script:
<syntaxhighlight lang="c">
/dts-v1/;

/ {
description = "Various signed scripts";
#address-cells = <1>;

images {
boot {
description = "Signed boot script";
data = /incbin/("/mnt/work/u-boot_scripts/boot.scr");
type = "script";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

recovery {
description = "Signed recovery script";
data = /incbin/("/mnt/work/u-boot_scripts/recovery.scr");
type = "script";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};
};

configurations { /* Mandatory node */ };
};
</syntaxhighlight>

Example U-Boot shell commands to load FIT file '''scripts-signed.itb''' and run the image '''boot''' with type script:
<syntaxhighlight lang="shell">
load mmc 0:4 ${scriptaddr} /boot/scripts-signed.itb
source ${scriptaddr}:boot
</syntaxhighlight>

= 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 OP-TEE developer setup]</ref>
<ref name="OP-TEE/manifest">[https://github.com/OP-TEE/build OP-TEE developer setup manifest]</ref>
<ref name="linaro-swg/linux">[https://github.com/linaro-swg/linux Linux for OP-TEE developer setup]</ref>

</references>

Toolchain Container Images

2022-10-27T10:03:23Z

Jneuhauser: /* Images with native Debian GCC toolchain */ Drop duplicate

DH electronics provides Docker images with preinstalled toolchains.
__TOC__

== Introduction ==

For cross developing of applications we provide Docker container images with preinstalled toolchains.
You need to have Docker installed ([https://docs.docker.com/engine/install/ How to install Docker]), in our [[Virtual Machine for Application Development|VM for Application Development]] starting with Stretch Vxx Docker is preinstalled and preconfigured.
The container images are available [https://hub.docker.com/ Docker Hub].

You can check which commands are executed for each layer in an image, and thus the installed packages, by clicking a specific tag in the Tag tab of an image on [https://hub.docker.com/ Docker Hub].
Here is an example for the image [https://hub.docker.com/layers/dhelectronics/debian-build-essential/stretch-amd64/images/sha256-12438156065c6cda9e5edcc8e25e553d78a9f14c2eaaadc7e7069e2515b93911?context=repo dhelectronics/debian-build-essential:stretch-amd64].

'''Note''': For userspace application development, we recommend using the ELBE/Yocto-SDK which came with your root filesystem.
This is because the SDKs comes with all needed development headers and libraries for its respective root filesystem.

== Available Toolchains ==

=== Images with native Debian GCC toolchain ===

At the Docker repository <tt>[https://hub.docker.com/r/dhelectronics/debian-build-essential dhelectronics/debian-build-essential]</tt> images with the standard native GCC toolchain of Debian are located.

The images are based on the Debian (slim-varaiant) image with <tt>cmake</tt>, <tt>ccache</tt>, <tt>curl</tt>, <tt>bc</tt>, <tt>lzop</tt>, <tt>xz-utils</tt>, <tt>jq</tt> and other tools additionally installed.
The Debian GCC toolchain is installed via the package <tt>debian-build-essential</tt>.

Tags consists of a combination of the used version of Debian and the architecture of the image (e.g. <tt>buster-amd64</tt>).
Currently there is any combination of the Debian versions <tt>jessie</tt>, <tt>stretch</tt> and <tt>buster</tt> with the architectures <tt>amd64</tt>, <tt>arm32v5</tt> and <tt>arm32v7</tt> is possible.
Note that Docker uses another names for distinguishing the different architectures of ARM processors: <tt>arm32v5</tt> corresponds to Debian's <tt>armel</tt> while <tt>arm32v7</tt> corresponds to Debian's <tt>armhf</tt> architecture.

You can use QEMU's user mode emulation for running the ARM-containers on an amd64-machine, the resulting software of a build still runs on the respective ARM architecture.
To use this you have to install the packages <tt>binfmt-support</tt> and <tt>qemu-user-static</tt> on the host.
To activate this for the container:
* If your host is on Debian '''stretch or earlier''', you have to include the usermode emulator into the container at the start of your container. This can be done with a bind mount. Add the option <tt>--mount type=bind,src=/usr/bin/qemu-arm-static,dst=/usr/bin/qemu-arm-static</tt> to the run command of the container.
* If your host is on Debian '''buster or later''', this works automaticly. You don't have to alter the run command of the container.
Note that running a conatiner on emulated hardware affects the performance of the compiler.
Tests have indicated that building the Linux kernel with one thread on the native armhf compiler running on an amd64 machine with emulation is about 9 times slower than building the same kernel with one thread on the same machine via a crossbuild compiler.

For easing the use with the [[Toolchain_Container_Images#Use_the_symlink_wrapper|symlink-wrapper]] script, aliases for <tt>make</tt> and <tt>cmake</tt> are created: <tt>make-container</tt> and <tt>cmake-container</tt>. These can be used at the symlink-script as additional symlinks which won't collide with the host system's <tt>make</tt> and <tt>cmake</tt> so that the complete build can run inside one container.

=== Images with Debian crossbuild GCC toolchain ===

At the Docker repository <tt>[https://hub.docker.com/r/dhelectronics/debian-cross-build-essential dhelectronics/debian-cross-build-essential]</tt> images with the Debian GCC toolchain for crosscompiling are located.

All images are based on the debian images (slim varaiant) and run on an amd64 host. The standard Debian crossbuild toolchain is used. This toolchain is installed via the package <tt>crossbuild-essentail-armhf</tt>.
The packages <tt>bc</tt>, <tt>bison</tt>, <tt>build-essential</tt>, <tt>ca-certificates</tt>, <tt>ccache</tt>, <tt>cmake</tt>, <tt>curl</tt>, <tt>flex</tt>, <tt>git</tt>, <tt>jq</tt>, <tt>ketchup</tt>, <tt>libssl-dev</tt>, <tt>lzop</tt> and <tt>xz-utils</tt> additionally installed, so that the images are suited to build the Linux kernel.

The tags have the schema '''<tt>DIST</tt>-<tt>ARCH</tt>''':

* '''<tt>DIST</tt>''': Determines which debian version the container image is based on.
* '''<tt>ARCH</tt>''': Determines which the architecture for which the cross toolchain builds. Note that the architecture names of Docker are used as an example Debian's <tt>armhf</tt> corresponds to <tt>arm32v7</tt>.

For easing the use with the [[Toolchain_Container_Images#Use_the_symlink_wrapper|symlink-wrapper]] script, aliases for <tt>make</tt> and <tt>cmake</tt> are created: <tt>make-cross</tt> and <tt>cmake-cross</tt>. These can be used at the symlink-script as additional symlinks which won't collide with the host system's <tt>make</tt> and <tt>cmake</tt> so that the complete build can run inside one container.

=== Images with Linaro/ARM toolchain ===

At the Docker repository <tt>[https://hub.docker.com/r/dhelectronics/linaro-cross-build dhelectronics/linaro-cross-build]</tt> images with the Linaro/ARM GCC toolchain for crosscompiling are located.

These images use the toolchain of Linaro (up to GCC 7) or ARM (beginning with GCC 8) and uses the debian-slim image as a basis for this image.
The toolchain is installed inside <tt>/opt</tt> and the <tt>PATH</tt>-variable is extened to include the directory with the binaries of the toolchain.
The packages <tt>bc</tt>, <tt>bison</tt>, <tt>build-essential</tt>, <tt>ca-certificates</tt>, <tt>ccache</tt>, <tt>cmake</tt>, <tt>curl</tt>, <tt>flex</tt>, <tt>git</tt>, <tt>jq</tt>, <tt>ketchup</tt>, <tt>libssl-dev</tt>, <tt>lzop</tt> and <tt>xz-utils</tt> additionally installed, so that the images are suited to build the Linux kernel.

The tags have the schema '''<tt>DIST</tt>-<tt>ARCH</tt>-<tt>VERSION</tt>''':

* '''<tt>DIST</tt>''': Determines which debian version the container image is based on.
* '''<tt>ARCH</tt>''': Determines which the architecture for which the cross toolchain builds. Note that the architecture names of Docker are used as an example Debian's `armhf` corresponds to <tt>arm32v7</tt>.
* '''<tt>VERSION</tt>''': Determines which version of the toolchain is used. There are two kinds of versions: '''<tt>X.Y\[.Z\]-yyyy.mm</tt>''' does explictly point to a specific version of the toolchain. '''<tt>X</tt>''' points to the latest version of the major version of the toolchain, of which a image is existing. It is possible that some versions of the toolchain are skipped.

For easing the use with the [[Toolchain_Container_Images#Use_the_symlink_wrapper|symlink-wrapper]] script, aliases for <tt>make</tt> and <tt>cmake</tt> are created: <tt>make-cross</tt> and <tt>cmake-cross</tt>. These can be used at the symlink-script as additional symlinks which won't collide with the host system's <tt>make</tt> and <tt>cmake</tt> so that the complete build can run inside one container.

== Using the containers ==

=== Open console inside the container ===

You can start the container with the current work directory mounted into the container:

<tt>$ docker run -it --rm --mount type=bind,src=$(pwd)/,dst=$(pwd) --workdir $(pwd) --user $(id -u):$(id -g) dhelectronics/linaro-cross-build:buster-arm32v7-8.3-2019.03</tt>

After the container has started a console is open, now you can run any command to build the application (e.g. <tt>make all</tt>).
When the build is finished, you can quit the console with <tt>CTRL+D</tt>.

=== Call the buildsystem at container start ===

Alternativly you can call the build command directly at the run command of the container:

<tt>$ docker run -it --rm --mount type=bind,src=$(pwd)/,dst=$(pwd) --workdir $(pwd) --user $(id -u):$(id -g) dhelectronics/linaro-cross-build:stretch-arm32v7-6.3.1-2017.05 make all</tt>

=== Use the symlink wrapper ===

We created a python script called <tt>[[Docker Symlink Wrapper|docker-symlink-wrapper.py]]</tt> (Not yet downloadable).
This script can create symlinks which point to a container.
Technicly, these symlinks point to the script.
If the script called over a symlink, it looks up which container should be called.
This container is then started with the name of the symlink as command to execute.
All arguments are passed to the container, If something is piped into STDIN, it is passed into the container, too.
It is possible to set the tag of the container image which should be started.

This example uses the <tt>linaro-cross-build</tt>-toolchain, what the commands are doing exactly, [[Docker_Symlink_Wrapper#Available_Commands|look at the documentation of the symlink wrapper]].

To create the symlinks, you need a JSON file which defines the needed things about the container images:

<nowiki>{
"symlinks":[
"arm-linux-gnueabihf-as",
"arm-linux-gnueabihf-ld",
"arm-linux-gnueabihf-gcc",
"arm-linux-gnueabihf-g++",
"arm-linux-gnueabihf-ar",
"arm-linux-gnueabihf-nm",
"arm-linux-gnueabihf-strip",
"arm-linux-gnueabihf-objcopy",
"arm-linux-gnueabihf-objdump",
"make-cross",
"cmake-cross"
],
"registry":"",
"image":"dhelectronics/linaro-cross-build",
"tag":"buster-arm32v7-8",
"installpath":"/usr/local/bin"
}</nowiki>

Then you can call the symlink script with superuser privileges to create the symlinks:

<nowiki>sudo docker-symlink-wrapper.py install cross-build install.json</nowiki>

Now the symlinks are installed and every call to <tt>arm-linux-gnueabihf-gcc</tt> and the other symlinks will go into the container.
Note that when calling a symlink only the current working directory is mounted into the container!
If you want to compile a file, you have to be inside the directory of the file or one of its parent directories.

To get the list of available versions of the toolchain you can use the following command:

<nowiki>docker-symlink-wrapper.py list-versions cross-build</nowiki>

To set the tag (= version of the toolchain) of the container, there is a command. As an example if you want to use version 6.3.1-2017.05 of the Linaro toolchain (based on Debian stretch):

<nowiki>sudo docker-symlink-wrapper.py set-version cross-build stretch-arm32v7-6.3.1-2017.05</nowiki>

=== Remove images which aren't needed anymore ===

If you want to delete a container image which you do not need anymore you can enter:

<tt>docker image rm <imagename+tag></tt>

If you download a newer version of an image, the old version won't be automaticly removed, the old image won't be accessible by its name and tag. This kind of image is called "dangling image". To remove all dangling images (so they won't take any space on disk) you can enter

<tt>docker image prune</tt>

== Extend the container with libraries ==

'''Note''': If you only need libraries which came on your root filesystem, we recommend using the ELBE/Yocto-SDK which came with this root filesystem.
In the SDK the corresponding headers and libraries are already preinstalled.

=== Create a modified container image ===

You can a new container image which includes the needed library.
For this you need to create a new Dockerfile inside an empty container.
Here is an example <tt>Dockerfile</tt> to include the C/C++ libraries of mosquitto (MQTT-broker/client) into the <tt>debian-build-essential</tt> image:

<nowiki>FROM dhelectronics/debian-build-essential:buster-arm32v7
RUN apt-get update && apt-get install -y --no-install-recommends libmosquitto-dev libmosquittopp-dev </nowiki>

Now you can create the new container image with:

<nowiki>docker build -t your-custom-image:latest .</nowiki>

After that the container can be started like any other container.
If you want to use the symlink script, you have to create your own JSON file to create the symlinks.
The symlinks of the normal <tt>debian-build-essential</tt> container images have to be removed because they would collide with each other (unless you install the symlinks into another directory but then the symlink which comes first inside the <tt>PATH</tt> enviornmental variable will be prefered over the other which can cause unwanted behavior).

=== Install libraries at runtime ===

When you run a console inside the container, you can run apt to install addional libraries. Note that when the container is removed, any changes to the container are lost.

=== Include libraries and headers into your project folder ===

You can include needed libraries and headers into a sub directory of your project directory which is mounted into the container. So you do not need to modify the image or the container at runtime.

Toolchain Container Images

2022-10-27T10:02:59Z

Jneuhauser: Remove "This is made for our VM" as it works on any docker enabled linux

DH electronics provides Docker images with preinstalled toolchains.
__TOC__

== Introduction ==

For cross developing of applications we provide Docker container images with preinstalled toolchains.
You need to have Docker installed ([https://docs.docker.com/engine/install/ How to install Docker]), in our [[Virtual Machine for Application Development|VM for Application Development]] starting with Stretch Vxx Docker is preinstalled and preconfigured.
The container images are available [https://hub.docker.com/ Docker Hub].

You can check which commands are executed for each layer in an image, and thus the installed packages, by clicking a specific tag in the Tag tab of an image on [https://hub.docker.com/ Docker Hub].
Here is an example for the image [https://hub.docker.com/layers/dhelectronics/debian-build-essential/stretch-amd64/images/sha256-12438156065c6cda9e5edcc8e25e553d78a9f14c2eaaadc7e7069e2515b93911?context=repo dhelectronics/debian-build-essential:stretch-amd64].

'''Note''': For userspace application development, we recommend using the ELBE/Yocto-SDK which came with your root filesystem.
This is because the SDKs comes with all needed development headers and libraries for its respective root filesystem.

== Available Toolchains ==

=== Images with native Debian GCC toolchain ===

At the Docker repository <tt>[https://hub.docker.com/r/dhelectronics/debian-build-essential dhelectronics/debian-build-essential]</tt> images with the standard native GCC toolchain of Debian are located.

The images are based on the Debian (slim-varaiant) image with <tt>cmake</tt>, <tt>ccache</tt>, <tt>curl</tt>, <tt>bc</tt>, <tt>lzop</tt>, <tt>xz-utils</tt>, <tt>jq</tt> and other tools additionally installed.
The Debian GCC toolchain is installed via the package <tt>debian-build-essential</tt>.

You can checkout which commands are executed for each layer, and therefore also the installed packages, if you click on a specific tag in the tag tab.
For example for image [https://hub.docker.com/layers/dhelectronics/debian-build-essential/stretch-amd64/images/sha256-12438156065c6cda9e5edcc8e25e553d78a9f14c2eaaadc7e7069e2515b93911?context=repo dhelectronics/debian-build-essential:stretch-amd64].

Tags consists of a combination of the used version of Debian and the architecture of the image (e.g. <tt>buster-amd64</tt>).
Currently there is any combination of the Debian versions <tt>jessie</tt>, <tt>stretch</tt> and <tt>buster</tt> with the architectures <tt>amd64</tt>, <tt>arm32v5</tt> and <tt>arm32v7</tt> is possible.
Note that Docker uses another names for distinguishing the different architectures of ARM processors: <tt>arm32v5</tt> corresponds to Debian's <tt>armel</tt> while <tt>arm32v7</tt> corresponds to Debian's <tt>armhf</tt> architecture.

You can use QEMU's user mode emulation for running the ARM-containers on an amd64-machine, the resulting software of a build still runs on the respective ARM architecture.
To use this you have to install the packages <tt>binfmt-support</tt> and <tt>qemu-user-static</tt> on the host.
To activate this for the container:
* If your host is on Debian '''stretch or earlier''', you have to include the usermode emulator into the container at the start of your container. This can be done with a bind mount. Add the option <tt>--mount type=bind,src=/usr/bin/qemu-arm-static,dst=/usr/bin/qemu-arm-static</tt> to the run command of the container.
* If your host is on Debian '''buster or later''', this works automaticly. You don't have to alter the run command of the container.
Note that running a conatiner on emulated hardware affects the performance of the compiler.
Tests have indicated that building the Linux kernel with one thread on the native armhf compiler running on an amd64 machine with emulation is about 9 times slower than building the same kernel with one thread on the same machine via a crossbuild compiler.

For easing the use with the [[Toolchain_Container_Images#Use_the_symlink_wrapper|symlink-wrapper]] script, aliases for <tt>make</tt> and <tt>cmake</tt> are created: <tt>make-container</tt> and <tt>cmake-container</tt>. These can be used at the symlink-script as additional symlinks which won't collide with the host system's <tt>make</tt> and <tt>cmake</tt> so that the complete build can run inside one container.

=== Images with Debian crossbuild GCC toolchain ===

At the Docker repository <tt>[https://hub.docker.com/r/dhelectronics/debian-cross-build-essential dhelectronics/debian-cross-build-essential]</tt> images with the Debian GCC toolchain for crosscompiling are located.

All images are based on the debian images (slim varaiant) and run on an amd64 host. The standard Debian crossbuild toolchain is used. This toolchain is installed via the package <tt>crossbuild-essentail-armhf</tt>.
The packages <tt>bc</tt>, <tt>bison</tt>, <tt>build-essential</tt>, <tt>ca-certificates</tt>, <tt>ccache</tt>, <tt>cmake</tt>, <tt>curl</tt>, <tt>flex</tt>, <tt>git</tt>, <tt>jq</tt>, <tt>ketchup</tt>, <tt>libssl-dev</tt>, <tt>lzop</tt> and <tt>xz-utils</tt> additionally installed, so that the images are suited to build the Linux kernel.

The tags have the schema '''<tt>DIST</tt>-<tt>ARCH</tt>''':

* '''<tt>DIST</tt>''': Determines which debian version the container image is based on.
* '''<tt>ARCH</tt>''': Determines which the architecture for which the cross toolchain builds. Note that the architecture names of Docker are used as an example Debian's <tt>armhf</tt> corresponds to <tt>arm32v7</tt>.

For easing the use with the [[Toolchain_Container_Images#Use_the_symlink_wrapper|symlink-wrapper]] script, aliases for <tt>make</tt> and <tt>cmake</tt> are created: <tt>make-cross</tt> and <tt>cmake-cross</tt>. These can be used at the symlink-script as additional symlinks which won't collide with the host system's <tt>make</tt> and <tt>cmake</tt> so that the complete build can run inside one container.

=== Images with Linaro/ARM toolchain ===

At the Docker repository <tt>[https://hub.docker.com/r/dhelectronics/linaro-cross-build dhelectronics/linaro-cross-build]</tt> images with the Linaro/ARM GCC toolchain for crosscompiling are located.

These images use the toolchain of Linaro (up to GCC 7) or ARM (beginning with GCC 8) and uses the debian-slim image as a basis for this image.
The toolchain is installed inside <tt>/opt</tt> and the <tt>PATH</tt>-variable is extened to include the directory with the binaries of the toolchain.
The packages <tt>bc</tt>, <tt>bison</tt>, <tt>build-essential</tt>, <tt>ca-certificates</tt>, <tt>ccache</tt>, <tt>cmake</tt>, <tt>curl</tt>, <tt>flex</tt>, <tt>git</tt>, <tt>jq</tt>, <tt>ketchup</tt>, <tt>libssl-dev</tt>, <tt>lzop</tt> and <tt>xz-utils</tt> additionally installed, so that the images are suited to build the Linux kernel.

The tags have the schema '''<tt>DIST</tt>-<tt>ARCH</tt>-<tt>VERSION</tt>''':

* '''<tt>DIST</tt>''': Determines which debian version the container image is based on.
* '''<tt>ARCH</tt>''': Determines which the architecture for which the cross toolchain builds. Note that the architecture names of Docker are used as an example Debian's `armhf` corresponds to <tt>arm32v7</tt>.
* '''<tt>VERSION</tt>''': Determines which version of the toolchain is used. There are two kinds of versions: '''<tt>X.Y\[.Z\]-yyyy.mm</tt>''' does explictly point to a specific version of the toolchain. '''<tt>X</tt>''' points to the latest version of the major version of the toolchain, of which a image is existing. It is possible that some versions of the toolchain are skipped.

For easing the use with the [[Toolchain_Container_Images#Use_the_symlink_wrapper|symlink-wrapper]] script, aliases for <tt>make</tt> and <tt>cmake</tt> are created: <tt>make-cross</tt> and <tt>cmake-cross</tt>. These can be used at the symlink-script as additional symlinks which won't collide with the host system's <tt>make</tt> and <tt>cmake</tt> so that the complete build can run inside one container.

== Using the containers ==

=== Open console inside the container ===

You can start the container with the current work directory mounted into the container:

<tt>$ docker run -it --rm --mount type=bind,src=$(pwd)/,dst=$(pwd) --workdir $(pwd) --user $(id -u):$(id -g) dhelectronics/linaro-cross-build:buster-arm32v7-8.3-2019.03</tt>

After the container has started a console is open, now you can run any command to build the application (e.g. <tt>make all</tt>).
When the build is finished, you can quit the console with <tt>CTRL+D</tt>.

=== Call the buildsystem at container start ===

Alternativly you can call the build command directly at the run command of the container:

<tt>$ docker run -it --rm --mount type=bind,src=$(pwd)/,dst=$(pwd) --workdir $(pwd) --user $(id -u):$(id -g) dhelectronics/linaro-cross-build:stretch-arm32v7-6.3.1-2017.05 make all</tt>

=== Use the symlink wrapper ===

We created a python script called <tt>[[Docker Symlink Wrapper|docker-symlink-wrapper.py]]</tt> (Not yet downloadable).
This script can create symlinks which point to a container.
Technicly, these symlinks point to the script.
If the script called over a symlink, it looks up which container should be called.
This container is then started with the name of the symlink as command to execute.
All arguments are passed to the container, If something is piped into STDIN, it is passed into the container, too.
It is possible to set the tag of the container image which should be started.

This example uses the <tt>linaro-cross-build</tt>-toolchain, what the commands are doing exactly, [[Docker_Symlink_Wrapper#Available_Commands|look at the documentation of the symlink wrapper]].

To create the symlinks, you need a JSON file which defines the needed things about the container images:

<nowiki>{
"symlinks":[
"arm-linux-gnueabihf-as",
"arm-linux-gnueabihf-ld",
"arm-linux-gnueabihf-gcc",
"arm-linux-gnueabihf-g++",
"arm-linux-gnueabihf-ar",
"arm-linux-gnueabihf-nm",
"arm-linux-gnueabihf-strip",
"arm-linux-gnueabihf-objcopy",
"arm-linux-gnueabihf-objdump",
"make-cross",
"cmake-cross"
],
"registry":"",
"image":"dhelectronics/linaro-cross-build",
"tag":"buster-arm32v7-8",
"installpath":"/usr/local/bin"
}</nowiki>

Then you can call the symlink script with superuser privileges to create the symlinks:

<nowiki>sudo docker-symlink-wrapper.py install cross-build install.json</nowiki>

Now the symlinks are installed and every call to <tt>arm-linux-gnueabihf-gcc</tt> and the other symlinks will go into the container.
Note that when calling a symlink only the current working directory is mounted into the container!
If you want to compile a file, you have to be inside the directory of the file or one of its parent directories.

To get the list of available versions of the toolchain you can use the following command:

<nowiki>docker-symlink-wrapper.py list-versions cross-build</nowiki>

To set the tag (= version of the toolchain) of the container, there is a command. As an example if you want to use version 6.3.1-2017.05 of the Linaro toolchain (based on Debian stretch):

<nowiki>sudo docker-symlink-wrapper.py set-version cross-build stretch-arm32v7-6.3.1-2017.05</nowiki>

=== Remove images which aren't needed anymore ===

If you want to delete a container image which you do not need anymore you can enter:

<tt>docker image rm <imagename+tag></tt>

If you download a newer version of an image, the old version won't be automaticly removed, the old image won't be accessible by its name and tag. This kind of image is called "dangling image". To remove all dangling images (so they won't take any space on disk) you can enter

<tt>docker image prune</tt>

== Extend the container with libraries ==

'''Note''': If you only need libraries which came on your root filesystem, we recommend using the ELBE/Yocto-SDK which came with this root filesystem.
In the SDK the corresponding headers and libraries are already preinstalled.

=== Create a modified container image ===

You can a new container image which includes the needed library.
For this you need to create a new Dockerfile inside an empty container.
Here is an example <tt>Dockerfile</tt> to include the C/C++ libraries of mosquitto (MQTT-broker/client) into the <tt>debian-build-essential</tt> image:

<nowiki>FROM dhelectronics/debian-build-essential:buster-arm32v7
RUN apt-get update && apt-get install -y --no-install-recommends libmosquitto-dev libmosquittopp-dev </nowiki>

Now you can create the new container image with:

<nowiki>docker build -t your-custom-image:latest .</nowiki>

After that the container can be started like any other container.
If you want to use the symlink script, you have to create your own JSON file to create the symlinks.
The symlinks of the normal <tt>debian-build-essential</tt> container images have to be removed because they would collide with each other (unless you install the symlinks into another directory but then the symlink which comes first inside the <tt>PATH</tt> enviornmental variable will be prefered over the other which can cause unwanted behavior).

=== Install libraries at runtime ===

When you run a console inside the container, you can run apt to install addional libraries. Note that when the container is removed, any changes to the container are lost.

=== Include libraries and headers into your project folder ===

You can include needed libraries and headers into a sub directory of your project directory which is mounted into the container. So you do not need to modify the image or the container at runtime.

DHCOM STM32MP15 Secure Boot

2022-09-16T08:18:23Z

Jneuhauser: /* Secure Boot in Trusted Boot with BootROM authentication, TF-A and OP-TEE */ Update upstreaming status

<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 (U-Boot)
|-
| FSBL || Fist Stage Bootloader (TF-A or U-Boot SPL)
|-
| ITS || Image Tree Source (U-Boot)
|-
| 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 ====

Checkout the branch <syntaxhighlight lang="shell" inline>v2022.01_dhcom_secure_boot</syntaxhighlight> from DH electronics GitHub repository with:

<syntaxhighlight lang="shell">
git clone https://github.com/dh-electronics/u-boot-stm32mp1.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 u-boot-stm32mp1 https://github.com/dh-electronics/u-boot-stm32mp1.git
git fetch u-boot-stm32mp1
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-spl-signed.stm32 || FSBL || Same as above but as signed STM32 image. Is created in [[#Sign U-Boot SPL with STM32MP_SigningTool_CLI|Sign U-Boot SPL with STM32MP_SigningTool_CLI]].
|-
| u-boot.itb || SSBL || U-Boot and Device Tree's contained in a FIT image.
|-
| u-boot-signed.itb || SSBL || Same as above but with signed configs and images.
|}

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

Load <syntaxhighlight lang="shell" inline>u-boot-spl-signed.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot-signed.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-signed.stm32
tftp ${fsbl2addr} ${serverip}:u-boot-spl-signed.stm32
tftp ${ssbl1addr} ${serverip}:u-boot-signed.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 =====

<div style="color:blue">Note: If you have any problems with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command use the manual procedure with the generic <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command in the next section.</div>

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

<div style="color:blue">Note: Use this manual procedure only if you have problems with the simpler <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command from the previous section.</div>

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: A Yocto example project would be the best!</div>

== Support of STM32MP1 DHSOM in TF-A, OP-TEE OS and OP-TEE Developer Setup ==

The following table shows the Support status of our STM32MP1-based DHSOMs in the TF-A, OP-TEE OS and OP-TEE Developer Setup projects.
This table is also a good starting point for what is required to support custom boards based on the STM32MP1 DHSOM in these projects.

{| class="wikitable" style="margin:auto"
|+ Support of STM32MP1 DHSOM in TF-A, OP-TEE OS and OP-TEE Developer Setup
|-
! DHSOM
! TF-A<ref name="TF-A" />
! OP-TEE OS<ref name="OP-TEE/optee_os" />
! OP-TEE developer setup<ref name="OP-TEE/build" />
! OP-TEE developer setup Linux<ref name="linaro-swg/linux" />
! OP-TEE developer setup manifest<ref name="OP-TEE/manifest" />
|-
! STM32MP157C DHCOM PDK2
| upstreamed in [https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/commit/?id=eef485abb13b6df9a94137edd82904aab0ecf02d commit eef485ab]
| upstreamed in [https://github.com/OP-TEE/optee_os/commit/6e9896c08ac4d8e81bb95ba1afa46cf6028fd4df commit 6e9896c0]
| upstreamed in [https://github.com/OP-TEE/build/commit/5914639cb690f57a3ce8ba0277ddc6eea2fc3985 commit 5914639c]
| upstreamed in [https://github.com/linaro-swg/linux/commit/2e9ae24784dd51d0a8325871b400795b88f04e2a commit 2e9ae247]
| preview in [https://github.com/jneuhauser/optee_manifest/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
|-
! STM32MP157A DHCOR Avenger96
| upstreamed in [https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/commit/?id=51e223058fe70b311542178f1865514745fa7874 commit 51e22305]
| upstreamed in [https://github.com/OP-TEE/optee_os/commit/5c932a03de3f1126c4710b3b6b296eb720746182 commit 5c932a03]
| upstreamed in [https://github.com/OP-TEE/build/commit/e43efa5b691a5f594db982134d4116ad1e625412 commit e43efa5b]
| upstreamed in [https://github.com/linaro-swg/linux/commit/29aee39cfa576029922eee42542571f730850877 commit 29aee39c]
| preview in [https://github.com/jneuhauser/optee_manifest/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
|}

= Examples for Flatten Image Tree Source files =

This example shows how to define an ITS file with your own content and how to use it from the U-Boot shell.

To build the FIT binary, there is the <syntaxhighlight lang="shell" inline>build_signed_fit_image.sh</syntaxhighlight> script included in the repository mentioned in [[#Checkout_source_code_for_Verified_Boot|Checkout Source Code for Verified Boot]].
<div style="color:blue">Note that you have to change <syntaxhighlight lang="shell" inline>KEY_ALGO</syntaxhighlight>, <syntaxhighlight lang="shell" inline>KEY_NAME_SSBL_IMG</syntaxhighlight> and <syntaxhighlight lang="shell" inline>KEY_NAME_SSBL_CFG</syntaxhighlight> to valid values if you build your image manually with <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight>.</div>
See [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT U-Boot Documentation: doc/uImage.FIT] for more examples and explanations of the possible properties.

== Signed FIT with Linux, ramdisk and device trees ==

Example of an ITS file with Linux, ramdisk and two device trees as images and a configuration for each valid image combination:
<syntaxhighlight lang="c">
/dts-v1/;

/ {
description = "Linux, ramdisk and FDT for DHCOM STM32MP1";
#address-cells = <1>;

images {
linux {
description = "Linux STM32MP15 DHSOM";
data = /incbin/("/mnt/work/linux/arch/arm/boot/Image.gz");
type = "kernel";
os = "linux";
arch = "arm";
/* Image compressed with gzip and decrompressed by U-Boot */
compression = "gzip";
load = <0xc0008000>;
entry = <0xc0008000>;
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

ramdisk {
description = "RootFS ramdisk DHSOM ARMv7";
data = /incbin/("/mnt/work/rootfs/ramdisk.cpio.gz");
type = "ramdisk";
arch = "arm";
os = "linux";
/* ramdisk.cpio.gz compressed with gzip and decrompressed by Linux instead of by U-Boot */
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

fdt-stm32mp157c-dhcom-pdk2 {
description = "FDT STM32MP157C DHCOM Premium Developer Kit (2)";
data = /incbin/("/mnt/work/linux/arch/arm/boot/dts/stm32mp157c-dhcom-pdk2.dtb");
type = "flat_dt";
arch = "arm";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

fdt-stm32mp157c-dhcom-picoitx {
description = "FDT STM32MP157C DHCOM PicoITX";
data = /incbin/("/mnt/work/linux/arch/arm/boot/dts/stm32mp157c-dhcom-picoitx.dtb");
type = "flat_dt";
arch = "arm";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};
};

configurations {
default = "stm32mp157c-dhcom-pdk2";

stm32mp157c-dhcom-pdk2 {
description = "STM32MP157C DHCOM Premium Developer Kit (2)";
kernel = "linux";
ramdisk = "ramdisk";
fdt = "fdt-stm32mp157c-dhcom-pdk2";
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_CFG";
sign-images = "kernel", "ramdisk", "fdt";
};
};

stm32mp157c-dhcom-picoitx {
description = "STM32MP157C DHCOM PicoITX";
kernel = "linux";
ramdisk = "ramdisk";
fdt = "fdt-stm32mp157c-dhcom-picoitx";
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_CFG";
sign-images = "kernel", "ramdisk", "fdt";
};
};
};
};
</syntaxhighlight>

Example U-Boot shell commands to load the FIT file '''linux-signed.itb''' and boot the configuration '''stm32mp157c-dhcom-pdk2''':
<syntaxhighlight lang="shell">
load mmc 0:4 ${loadaddr} /boot/linux-signed.itb
bootm ${loadaddr}#stm32mp157c-dhcom-pdk2
</syntaxhighlight>

== Signed FIT with U-Boot scripts ==

Example of an ITS file with images '''boot''' and '''recovery''' of type script:
<syntaxhighlight lang="c">
/dts-v1/;

/ {
description = "Various signed scripts";
#address-cells = <1>;

images {
boot {
description = "Signed boot script";
data = /incbin/("/mnt/work/u-boot_scripts/boot.scr");
type = "script";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

recovery {
description = "Signed recovery script";
data = /incbin/("/mnt/work/u-boot_scripts/recovery.scr");
type = "script";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};
};

configurations { /* Mandatory node */ };
};
</syntaxhighlight>

Example U-Boot shell commands to load FIT file '''scripts-signed.itb''' and run the image '''boot''' with type script:
<syntaxhighlight lang="shell">
load mmc 0:4 ${scriptaddr} /boot/scripts-signed.itb
source ${scriptaddr}:boot
</syntaxhighlight>

= 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 OP-TEE developer setup]</ref>
<ref name="OP-TEE/manifest">[https://github.com/OP-TEE/build OP-TEE developer setup manifest]</ref>
<ref name="linaro-swg/linux">[https://github.com/linaro-swg/linux Linux for OP-TEE developer setup]</ref>

</references>

DHCOM STM32MP15 Secure Boot

2022-09-12T12:09:48Z

Jneuhauser: /* Examples for Flatten Image Tree Source files */ Fix link to git repo source

<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 (U-Boot)
|-
| FSBL || Fist Stage Bootloader (TF-A or U-Boot SPL)
|-
| ITS || Image Tree Source (U-Boot)
|-
| 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 ====

Checkout the branch <syntaxhighlight lang="shell" inline>v2022.01_dhcom_secure_boot</syntaxhighlight> from DH electronics GitHub repository with:

<syntaxhighlight lang="shell">
git clone https://github.com/dh-electronics/u-boot-stm32mp1.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 u-boot-stm32mp1 https://github.com/dh-electronics/u-boot-stm32mp1.git
git fetch u-boot-stm32mp1
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-spl-signed.stm32 || FSBL || Same as above but as signed STM32 image. Is created in [[#Sign U-Boot SPL with STM32MP_SigningTool_CLI|Sign U-Boot SPL with STM32MP_SigningTool_CLI]].
|-
| u-boot.itb || SSBL || U-Boot and Device Tree's contained in a FIT image.
|-
| u-boot-signed.itb || SSBL || Same as above but with signed configs and images.
|}

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

Load <syntaxhighlight lang="shell" inline>u-boot-spl-signed.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot-signed.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-signed.stm32
tftp ${fsbl2addr} ${serverip}:u-boot-spl-signed.stm32
tftp ${ssbl1addr} ${serverip}:u-boot-signed.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 =====

<div style="color:blue">Note: If you have any problems with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command use the manual procedure with the generic <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command in the next section.</div>

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

<div style="color:blue">Note: Use this manual procedure only if you have problems with the simpler <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command from the previous section.</div>

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: A Yocto example project would be the best!</div>

== Support of STM32MP1 DHSOM in TF-A, OP-TEE OS and OP-TEE Developer Setup ==

The following table shows the Support status of our STM32MP1-based DHSOMs in the TF-A, OP-TEE OS and OP-TEE Developer Setup projects.
This table is also a good starting point for what is required to support custom boards based on the STM32MP1 DHSOM in these projects.

{| class="wikitable" style="margin:auto"
|+ Support of STM32MP1 DHSOM in TF-A, OP-TEE OS and OP-TEE Developer Setup
|-
! DHSOM
! TF-A<ref name="TF-A" />
! OP-TEE OS<ref name="OP-TEE/optee_os" />
! OP-TEE developer setup<ref name="OP-TEE/build" />
! OP-TEE developer setup Linux<ref name="linaro-swg/linux" />
! OP-TEE developer setup manifest<ref name="OP-TEE/manifest" />
|-
! STM32MP157C DHCOM PDK2
| upstreamed in [https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/commit/?id=eef485abb13b6df9a94137edd82904aab0ecf02d commit eef485ab]
| upstreamed in [https://github.com/OP-TEE/optee_os/commit/6e9896c08ac4d8e81bb95ba1afa46cf6028fd4df commit 6e9896c0]
| upstreamed in [https://github.com/OP-TEE/build/commit/5914639cb690f57a3ce8ba0277ddc6eea2fc3985 commit 5914639c]
| under review in [https://github.com/linaro-swg/linux/pull/105 pull request 105]
| preview in [https://github.com/jneuhauser/optee_manifest/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
|-
! STM32MP157A DHCOR Avenger96
| upstreamed in [https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/commit/?id=51e223058fe70b311542178f1865514745fa7874 commit 51e22305]
| upstreamed in [https://github.com/OP-TEE/optee_os/commit/5c932a03de3f1126c4710b3b6b296eb720746182 commit 5c932a03]
| upstreamed in [https://github.com/OP-TEE/build/commit/e43efa5b691a5f594db982134d4116ad1e625412 commit e43efa5b]
| under review in [https://github.com/linaro-swg/linux/pull/105 pull request 105]
| preview in [https://github.com/jneuhauser/optee_manifest/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
|}

= Examples for Flatten Image Tree Source files =

This example shows how to define an ITS file with your own content and how to use it from the U-Boot shell.

To build the FIT binary, there is the <syntaxhighlight lang="shell" inline>build_signed_fit_image.sh</syntaxhighlight> script included in the repository mentioned in [[#Checkout_source_code_for_Verified_Boot|Checkout Source Code for Verified Boot]].
<div style="color:blue">Note that you have to change <syntaxhighlight lang="shell" inline>KEY_ALGO</syntaxhighlight>, <syntaxhighlight lang="shell" inline>KEY_NAME_SSBL_IMG</syntaxhighlight> and <syntaxhighlight lang="shell" inline>KEY_NAME_SSBL_CFG</syntaxhighlight> to valid values if you build your image manually with <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight>.</div>
See [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT U-Boot Documentation: doc/uImage.FIT] for more examples and explanations of the possible properties.

== Signed FIT with Linux, ramdisk and device trees ==

Example of an ITS file with Linux, ramdisk and two device trees as images and a configuration for each valid image combination:
<syntaxhighlight lang="c">
/dts-v1/;

/ {
description = "Linux, ramdisk and FDT for DHCOM STM32MP1";
#address-cells = <1>;

images {
linux {
description = "Linux STM32MP15 DHSOM";
data = /incbin/("/mnt/work/linux/arch/arm/boot/Image.gz");
type = "kernel";
os = "linux";
arch = "arm";
/* Image compressed with gzip and decrompressed by U-Boot */
compression = "gzip";
load = <0xc0008000>;
entry = <0xc0008000>;
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

ramdisk {
description = "RootFS ramdisk DHSOM ARMv7";
data = /incbin/("/mnt/work/rootfs/ramdisk.cpio.gz");
type = "ramdisk";
arch = "arm";
os = "linux";
/* ramdisk.cpio.gz compressed with gzip and decrompressed by Linux instead of by U-Boot */
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

fdt-stm32mp157c-dhcom-pdk2 {
description = "FDT STM32MP157C DHCOM Premium Developer Kit (2)";
data = /incbin/("/mnt/work/linux/arch/arm/boot/dts/stm32mp157c-dhcom-pdk2.dtb");
type = "flat_dt";
arch = "arm";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

fdt-stm32mp157c-dhcom-picoitx {
description = "FDT STM32MP157C DHCOM PicoITX";
data = /incbin/("/mnt/work/linux/arch/arm/boot/dts/stm32mp157c-dhcom-picoitx.dtb");
type = "flat_dt";
arch = "arm";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};
};

configurations {
default = "stm32mp157c-dhcom-pdk2";

stm32mp157c-dhcom-pdk2 {
description = "STM32MP157C DHCOM Premium Developer Kit (2)";
kernel = "linux";
ramdisk = "ramdisk";
fdt = "fdt-stm32mp157c-dhcom-pdk2";
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_CFG";
sign-images = "kernel", "ramdisk", "fdt";
};
};

stm32mp157c-dhcom-picoitx {
description = "STM32MP157C DHCOM PicoITX";
kernel = "linux";
ramdisk = "ramdisk";
fdt = "fdt-stm32mp157c-dhcom-picoitx";
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_CFG";
sign-images = "kernel", "ramdisk", "fdt";
};
};
};
};
</syntaxhighlight>

Example U-Boot shell commands to load the FIT file '''linux-signed.itb''' and boot the configuration '''stm32mp157c-dhcom-pdk2''':
<syntaxhighlight lang="shell">
load mmc 0:4 ${loadaddr} /boot/linux-signed.itb
bootm ${loadaddr}#stm32mp157c-dhcom-pdk2
</syntaxhighlight>

== Signed FIT with U-Boot scripts ==

Example of an ITS file with images '''boot''' and '''recovery''' of type script:
<syntaxhighlight lang="c">
/dts-v1/;

/ {
description = "Various signed scripts";
#address-cells = <1>;

images {
boot {
description = "Signed boot script";
data = /incbin/("/mnt/work/u-boot_scripts/boot.scr");
type = "script";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

recovery {
description = "Signed recovery script";
data = /incbin/("/mnt/work/u-boot_scripts/recovery.scr");
type = "script";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};
};

configurations { /* Mandatory node */ };
};
</syntaxhighlight>

Example U-Boot shell commands to load FIT file '''scripts-signed.itb''' and run the image '''boot''' with type script:
<syntaxhighlight lang="shell">
load mmc 0:4 ${scriptaddr} /boot/scripts-signed.itb
source ${scriptaddr}:boot
</syntaxhighlight>

= 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 OP-TEE developer setup]</ref>
<ref name="OP-TEE/manifest">[https://github.com/OP-TEE/build OP-TEE developer setup manifest]</ref>
<ref name="linaro-swg/linux">[https://github.com/linaro-swg/linux Linux for OP-TEE developer setup]</ref>

</references>

DHCOM STM32MP15 Secure Boot

2022-09-12T07:12:57Z

Jneuhauser: /* Support of STM32MP1 DHSOM in TF-A, OP-TEE OS and OP-TEE Developer Setup */ Update upstreaming status

<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 (U-Boot)
|-
| FSBL || Fist Stage Bootloader (TF-A or U-Boot SPL)
|-
| ITS || Image Tree Source (U-Boot)
|-
| 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 ====

Checkout the branch <syntaxhighlight lang="shell" inline>v2022.01_dhcom_secure_boot</syntaxhighlight> from DH electronics GitHub repository with:

<syntaxhighlight lang="shell">
git clone https://github.com/dh-electronics/u-boot-stm32mp1.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 u-boot-stm32mp1 https://github.com/dh-electronics/u-boot-stm32mp1.git
git fetch u-boot-stm32mp1
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-spl-signed.stm32 || FSBL || Same as above but as signed STM32 image. Is created in [[#Sign U-Boot SPL with STM32MP_SigningTool_CLI|Sign U-Boot SPL with STM32MP_SigningTool_CLI]].
|-
| u-boot.itb || SSBL || U-Boot and Device Tree's contained in a FIT image.
|-
| u-boot-signed.itb || SSBL || Same as above but with signed configs and images.
|}

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

Load <syntaxhighlight lang="shell" inline>u-boot-spl-signed.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot-signed.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-signed.stm32
tftp ${fsbl2addr} ${serverip}:u-boot-spl-signed.stm32
tftp ${ssbl1addr} ${serverip}:u-boot-signed.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 =====

<div style="color:blue">Note: If you have any problems with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command use the manual procedure with the generic <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command in the next section.</div>

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

<div style="color:blue">Note: Use this manual procedure only if you have problems with the simpler <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command from the previous section.</div>

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: A Yocto example project would be the best!</div>

== Support of STM32MP1 DHSOM in TF-A, OP-TEE OS and OP-TEE Developer Setup ==

The following table shows the Support status of our STM32MP1-based DHSOMs in the TF-A, OP-TEE OS and OP-TEE Developer Setup projects.
This table is also a good starting point for what is required to support custom boards based on the STM32MP1 DHSOM in these projects.

{| class="wikitable" style="margin:auto"
|+ Support of STM32MP1 DHSOM in TF-A, OP-TEE OS and OP-TEE Developer Setup
|-
! DHSOM
! TF-A<ref name="TF-A" />
! OP-TEE OS<ref name="OP-TEE/optee_os" />
! OP-TEE developer setup<ref name="OP-TEE/build" />
! OP-TEE developer setup Linux<ref name="linaro-swg/linux" />
! OP-TEE developer setup manifest<ref name="OP-TEE/manifest" />
|-
! STM32MP157C DHCOM PDK2
| upstreamed in [https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/commit/?id=eef485abb13b6df9a94137edd82904aab0ecf02d commit eef485ab]
| upstreamed in [https://github.com/OP-TEE/optee_os/commit/6e9896c08ac4d8e81bb95ba1afa46cf6028fd4df commit 6e9896c0]
| upstreamed in [https://github.com/OP-TEE/build/commit/5914639cb690f57a3ce8ba0277ddc6eea2fc3985 commit 5914639c]
| under review in [https://github.com/linaro-swg/linux/pull/105 pull request 105]
| preview in [https://github.com/jneuhauser/optee_manifest/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
|-
! STM32MP157A DHCOR Avenger96
| upstreamed in [https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/commit/?id=51e223058fe70b311542178f1865514745fa7874 commit 51e22305]
| upstreamed in [https://github.com/OP-TEE/optee_os/commit/5c932a03de3f1126c4710b3b6b296eb720746182 commit 5c932a03]
| upstreamed in [https://github.com/OP-TEE/build/commit/e43efa5b691a5f594db982134d4116ad1e625412 commit e43efa5b]
| under review in [https://github.com/linaro-swg/linux/pull/105 pull request 105]
| preview in [https://github.com/jneuhauser/optee_manifest/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
|}

= Examples for Flatten Image Tree Source files =

This example shows how to define an ITS file with your own content and how to use it from the U-Boot shell.

To build the FIT binary, there is the <syntaxhighlight lang="shell" inline>build_signed_fit_image.sh</syntaxhighlight> script included in the repository mentioned in [[#Checkout Source Code for Verified Boot|Checkout Source Code for Verified Boot]].
<div style="color:blue">Note that you have to change <syntaxhighlight lang="shell" inline>KEY_ALGO</syntaxhighlight>, <syntaxhighlight lang="shell" inline>KEY_NAME_SSBL_IMG</syntaxhighlight> and <syntaxhighlight lang="shell" inline>KEY_NAME_SSBL_CFG</syntaxhighlight> to valid values if you build your image manually with <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight>.</div>
See [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT U-Boot Documentation: doc/uImage.FIT] for more examples and explanations of the possible properties.

== Signed FIT with Linux, ramdisk and device trees ==

Example of an ITS file with Linux, ramdisk and two device trees as images and a configuration for each valid image combination:
<syntaxhighlight lang="c">
/dts-v1/;

/ {
description = "Linux, ramdisk and FDT for DHCOM STM32MP1";
#address-cells = <1>;

images {
linux {
description = "Linux STM32MP15 DHSOM";
data = /incbin/("/mnt/work/linux/arch/arm/boot/Image.gz");
type = "kernel";
os = "linux";
arch = "arm";
/* Image compressed with gzip and decrompressed by U-Boot */
compression = "gzip";
load = <0xc0008000>;
entry = <0xc0008000>;
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

ramdisk {
description = "RootFS ramdisk DHSOM ARMv7";
data = /incbin/("/mnt/work/rootfs/ramdisk.cpio.gz");
type = "ramdisk";
arch = "arm";
os = "linux";
/* ramdisk.cpio.gz compressed with gzip and decrompressed by Linux instead of by U-Boot */
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

fdt-stm32mp157c-dhcom-pdk2 {
description = "FDT STM32MP157C DHCOM Premium Developer Kit (2)";
data = /incbin/("/mnt/work/linux/arch/arm/boot/dts/stm32mp157c-dhcom-pdk2.dtb");
type = "flat_dt";
arch = "arm";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

fdt-stm32mp157c-dhcom-picoitx {
description = "FDT STM32MP157C DHCOM PicoITX";
data = /incbin/("/mnt/work/linux/arch/arm/boot/dts/stm32mp157c-dhcom-picoitx.dtb");
type = "flat_dt";
arch = "arm";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};
};

configurations {
default = "stm32mp157c-dhcom-pdk2";

stm32mp157c-dhcom-pdk2 {
description = "STM32MP157C DHCOM Premium Developer Kit (2)";
kernel = "linux";
ramdisk = "ramdisk";
fdt = "fdt-stm32mp157c-dhcom-pdk2";
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_CFG";
sign-images = "kernel", "ramdisk", "fdt";
};
};

stm32mp157c-dhcom-picoitx {
description = "STM32MP157C DHCOM PicoITX";
kernel = "linux";
ramdisk = "ramdisk";
fdt = "fdt-stm32mp157c-dhcom-picoitx";
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_CFG";
sign-images = "kernel", "ramdisk", "fdt";
};
};
};
};
</syntaxhighlight>

Example U-Boot shell commands to load the FIT file '''linux-signed.itb''' and boot the configuration '''stm32mp157c-dhcom-pdk2''':
<syntaxhighlight lang="shell">
load mmc 0:4 ${loadaddr} /boot/linux-signed.itb
bootm ${loadaddr}#stm32mp157c-dhcom-pdk2
</syntaxhighlight>

== Signed FIT with U-Boot scripts ==

Example of an ITS file with images '''boot''' and '''recovery''' of type script:
<syntaxhighlight lang="c">
/dts-v1/;

/ {
description = "Various signed scripts";
#address-cells = <1>;

images {
boot {
description = "Signed boot script";
data = /incbin/("/mnt/work/u-boot_scripts/boot.scr");
type = "script";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

recovery {
description = "Signed recovery script";
data = /incbin/("/mnt/work/u-boot_scripts/recovery.scr");
type = "script";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};
};

configurations { /* Mandatory node */ };
};
</syntaxhighlight>

Example U-Boot shell commands to load FIT file '''scripts-signed.itb''' and run the image '''boot''' with type script:
<syntaxhighlight lang="shell">
load mmc 0:4 ${scriptaddr} /boot/scripts-signed.itb
source ${scriptaddr}:boot
</syntaxhighlight>

= 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 OP-TEE developer setup]</ref>
<ref name="OP-TEE/manifest">[https://github.com/OP-TEE/build OP-TEE developer setup manifest]</ref>
<ref name="linaro-swg/linux">[https://github.com/linaro-swg/linux Linux for OP-TEE developer setup]</ref>

</references>

DHCOM STM32MP15 Secure Boot

2022-09-09T11:38:03Z

Jneuhauser: Extend "Examples for Flatten Image Tree Source files"

<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 (U-Boot)
|-
| FSBL || Fist Stage Bootloader (TF-A or U-Boot SPL)
|-
| ITS || Image Tree Source (U-Boot)
|-
| 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 ====

Checkout the branch <syntaxhighlight lang="shell" inline>v2022.01_dhcom_secure_boot</syntaxhighlight> from DH electronics GitHub repository with:

<syntaxhighlight lang="shell">
git clone https://github.com/dh-electronics/u-boot-stm32mp1.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 u-boot-stm32mp1 https://github.com/dh-electronics/u-boot-stm32mp1.git
git fetch u-boot-stm32mp1
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-spl-signed.stm32 || FSBL || Same as above but as signed STM32 image. Is created in [[#Sign U-Boot SPL with STM32MP_SigningTool_CLI|Sign U-Boot SPL with STM32MP_SigningTool_CLI]].
|-
| u-boot.itb || SSBL || U-Boot and Device Tree's contained in a FIT image.
|-
| u-boot-signed.itb || SSBL || Same as above but with signed configs and images.
|}

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

Load <syntaxhighlight lang="shell" inline>u-boot-spl-signed.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot-signed.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-signed.stm32
tftp ${fsbl2addr} ${serverip}:u-boot-spl-signed.stm32
tftp ${ssbl1addr} ${serverip}:u-boot-signed.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 =====

<div style="color:blue">Note: If you have any problems with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command use the manual procedure with the generic <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command in the next section.</div>

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

<div style="color:blue">Note: Use this manual procedure only if you have problems with the simpler <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command from the previous section.</div>

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: A Yocto example project would be the best!</div>

== Support of STM32MP1 DHSOM in TF-A, OP-TEE OS and OP-TEE Developer Setup ==

The following table shows the Support status of our STM32MP1-based DHSOMs in the TF-A, OP-TEE OS and OP-TEE Developer Setup projects.
This table is also a good starting point for what is required to support custom boards based on the STM32MP1 DHSOM in these projects.

{| class="wikitable" style="margin:auto"
|+ Support of STM32MP1 DHSOM in TF-A, OP-TEE OS and OP-TEE Developer Setup
|-
! DHSOM
! TF-A<ref name="TF-A" />
! OP-TEE OS<ref name="OP-TEE/optee_os" />
! OP-TEE developer setup<ref name="OP-TEE/build" />
! OP-TEE developer setup Linux<ref name="linaro-swg/linux" />
! OP-TEE developer setup manifest<ref name="OP-TEE/manifest" />
|-
! STM32MP157C DHCOM PDK2
| upstreamed in [https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/commit/?id=eef485abb13b6df9a94137edd82904aab0ecf02d commit eef485ab]
| upstreamed in [https://github.com/OP-TEE/optee_os/commit/6e9896c08ac4d8e81bb95ba1afa46cf6028fd4df commit 6e9896c0]
| under review in [https://github.com/OP-TEE/build/pull/586 pull request 586]
| under review in [https://github.com/linaro-swg/linux/pull/105 pull request 105]
| preview in [https://github.com/jneuhauser/optee_manifest/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
|-
! STM32MP157A DHCOR Avenger96
| upstreamed in [https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/commit/?id=51e223058fe70b311542178f1865514745fa7874 commit 51e22305]
| upstreamed in [https://github.com/OP-TEE/optee_os/commit/5c932a03de3f1126c4710b3b6b296eb720746182 commit 5c932a03]
| under review in [https://github.com/OP-TEE/build/pull/586 pull request 586]
| under review in [https://github.com/linaro-swg/linux/pull/105 pull request 105]
| preview in [https://github.com/jneuhauser/optee_manifest/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
|}

= Examples for Flatten Image Tree Source files =

This example shows how to define an ITS file with your own content and how to use it from the U-Boot shell.

To build the FIT binary, there is the <syntaxhighlight lang="shell" inline>build_signed_fit_image.sh</syntaxhighlight> script included in the repository mentioned in [[#Checkout Source Code for Verified Boot|Checkout Source Code for Verified Boot]].
<div style="color:blue">Note that you have to change <syntaxhighlight lang="shell" inline>KEY_ALGO</syntaxhighlight>, <syntaxhighlight lang="shell" inline>KEY_NAME_SSBL_IMG</syntaxhighlight> and <syntaxhighlight lang="shell" inline>KEY_NAME_SSBL_CFG</syntaxhighlight> to valid values if you build your image manually with <syntaxhighlight lang="shell" inline>mkimage</syntaxhighlight>.</div>
See [https://source.denx.de/u-boot/u-boot/tree/master/doc/uImage.FIT U-Boot Documentation: doc/uImage.FIT] for more examples and explanations of the possible properties.

== Signed FIT with Linux, ramdisk and device trees ==

Example of an ITS file with Linux, ramdisk and two device trees as images and a configuration for each valid image combination:
<syntaxhighlight lang="c">
/dts-v1/;

/ {
description = "Linux, ramdisk and FDT for DHCOM STM32MP1";
#address-cells = <1>;

images {
linux {
description = "Linux STM32MP15 DHSOM";
data = /incbin/("/mnt/work/linux/arch/arm/boot/Image.gz");
type = "kernel";
os = "linux";
arch = "arm";
/* Image compressed with gzip and decrompressed by U-Boot */
compression = "gzip";
load = <0xc0008000>;
entry = <0xc0008000>;
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

ramdisk {
description = "RootFS ramdisk DHSOM ARMv7";
data = /incbin/("/mnt/work/rootfs/ramdisk.cpio.gz");
type = "ramdisk";
arch = "arm";
os = "linux";
/* ramdisk.cpio.gz compressed with gzip and decrompressed by Linux instead of by U-Boot */
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

fdt-stm32mp157c-dhcom-pdk2 {
description = "FDT STM32MP157C DHCOM Premium Developer Kit (2)";
data = /incbin/("/mnt/work/linux/arch/arm/boot/dts/stm32mp157c-dhcom-pdk2.dtb");
type = "flat_dt";
arch = "arm";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

fdt-stm32mp157c-dhcom-picoitx {
description = "FDT STM32MP157C DHCOM PicoITX";
data = /incbin/("/mnt/work/linux/arch/arm/boot/dts/stm32mp157c-dhcom-picoitx.dtb");
type = "flat_dt";
arch = "arm";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};
};

configurations {
default = "stm32mp157c-dhcom-pdk2";

stm32mp157c-dhcom-pdk2 {
description = "STM32MP157C DHCOM Premium Developer Kit (2)";
kernel = "linux";
ramdisk = "ramdisk";
fdt = "fdt-stm32mp157c-dhcom-pdk2";
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_CFG";
sign-images = "kernel", "ramdisk", "fdt";
};
};

stm32mp157c-dhcom-picoitx {
description = "STM32MP157C DHCOM PicoITX";
kernel = "linux";
ramdisk = "ramdisk";
fdt = "fdt-stm32mp157c-dhcom-picoitx";
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_CFG";
sign-images = "kernel", "ramdisk", "fdt";
};
};
};
};
</syntaxhighlight>

Example U-Boot shell commands to load the FIT file '''linux-signed.itb''' and boot the configuration '''stm32mp157c-dhcom-pdk2''':
<syntaxhighlight lang="shell">
load mmc 0:4 ${loadaddr} /boot/linux-signed.itb
bootm ${loadaddr}#stm32mp157c-dhcom-pdk2
</syntaxhighlight>

== Signed FIT with U-Boot scripts ==

Example of an ITS file with images '''boot''' and '''recovery''' of type script:
<syntaxhighlight lang="c">
/dts-v1/;

/ {
description = "Various signed scripts";
#address-cells = <1>;

images {
boot {
description = "Signed boot script";
data = /incbin/("/mnt/work/u-boot_scripts/boot.scr");
type = "script";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

recovery {
description = "Signed recovery script";
data = /incbin/("/mnt/work/u-boot_scripts/recovery.scr");
type = "script";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};
};

configurations { /* Mandatory node */ };
};
</syntaxhighlight>

Example U-Boot shell commands to load FIT file '''scripts-signed.itb''' and run the image '''boot''' with type script:
<syntaxhighlight lang="shell">
load mmc 0:4 ${scriptaddr} /boot/scripts-signed.itb
source ${scriptaddr}:boot
</syntaxhighlight>

= 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 OP-TEE developer setup]</ref>
<ref name="OP-TEE/manifest">[https://github.com/OP-TEE/build OP-TEE developer setup manifest]</ref>
<ref name="linaro-swg/linux">[https://github.com/linaro-swg/linux Linux for OP-TEE developer setup]</ref>

</references>

U-Boot recovery for STM32MP1 DHSOM via DFU

2022-09-09T07:42:36Z

Jneuhauser: /* U-Boot booting via DFU */ Add kernel log check also for USB download gadget

To recover a corrupted U-Boot on a STM32MP1-based DHCOM, we can use the default fallback boot source DFU via serial link or USB to temporarily boot U-Boot SPL and U-Boot.
From this U-Boot shell we can write both bootloader images from the SD card to the boot flash.

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

== Requirements ==
=== Software ===
* Linux host computer ([[Virtual Machine for Application Development]] is used in this guide)
* [https://source.denx.de/u-boot/u-boot/-/tree/v2022.04 U-Boot 2022.04] for your board (download and build instructions below)
* [https://packages.debian.org/stable/dfu-util dfu-util] (for DFU boot mode)

=== Hardware ===
* STM32MP1 based DHCOM
* DHCOM Premium Developer Kit Baseboard (or Baseboards with OTG ports)
* USB cable for OTG port (Mini USB for PDK2, USB-C for PDK3) (for DFU boot mode)
* SD card (for SD card boot mode)

== Preparation ==
This installation was made on the [[Virtual Machine for Application Development]].
All console expressions refer to this Debian system, but any other debian based system should also work.

=== Install dfu-util (debian) ===
<syntaxhighlight lang="shell">
apt-get install dfu-util
</syntaxhighlight>
<syntaxhighlight lang="console">
</syntaxhighlight>

=== Download/Build U-Boot SPL and U-Boot binaries ===

There are two ways to get the required U-Boot binaries.
These can either be downloaded or built from the sources by yourself.
Follow one of the two steps below.

==== Download prebuilt binaries ====

[[media:AACQ30W-7l-Zi_Zutu0Zv-Zua|Dropbox: U-Boot_recovery_for_STM32MP1_DHSOM_via_DFU]] ([https://source.denx.de/u-boot/u-boot/-/tree/v2022.04 source])

<syntaxhighlight lang="shell">
curl -LsS https://www.dropbox.com/sh/os9so01tivajkxs/AACQ30W-7l-Zi_Zutu0Zv-Zua > recovery_binaryies.zip
unzip recovery_binaryies.zip
</syntaxhighlight>
<syntaxhighlight lang="console">
Archive: recovery_binaryies.zip
warning: stripped absolute path spec from /
mapname: conversion of failed
creating: U-Boot_v2022.04_mainline/
creating: U-Boot_v2022.04_mainline/av96/
creating: U-Boot_v2022.04_mainline/pdk2/
creating: U-Boot_v2022.04_mainline/drc02/
creating: U-Boot_v2022.04_mainline/picoitx/
extracting: U-Boot_v2022.04_mainline/av96/u-boot.itb
extracting: U-Boot_v2022.04_mainline/pdk2/u-boot.itb
extracting: U-Boot_v2022.04_mainline/drc02/u-boot.itb
extracting: U-Boot_v2022.04_mainline/picoitx/u-boot.itb
extracting: U-Boot_v2022.04_mainline/av96/u-boot-spl.stm32
extracting: U-Boot_v2022.04_mainline/pdk2/u-boot-spl.stm32
extracting: U-Boot_v2022.04_mainline/drc02/u-boot-spl.stm32
extracting: U-Boot_v2022.04_mainline/picoitx/u-boot-spl.stm32
</syntaxhighlight>

==== Build binaries from source ====

Clone U-Boot mainline source code for release v2022.04:
<syntaxhighlight lang="shell">
UBOOT_SRC=/work/dev/u-boot_v2022.04
mkdir -p $UBOOT_SRC
git clone --branch v2022.04 --depth 1 https://source.denx.de/u-boot/u-boot.git $UBOOT_SRC
cd $UBOOT_SRC
</syntaxhighlight>

Available U-Boot defconfigs for STM32MP1 based DHSOM devices with default device tree in bold:
* '''stm32mp15_dhcom_basic_defconfig''' ('''pdk2''', picoitx, drc02)
* '''stm32mp15_dhcor_basic_defconfig''' ('''avenger96''')
<syntaxhighlight lang="shell">
mkdir -p /work/dev/u-boot
git clone https://source.denx.de/u-boot/u-boot.git -b v2022.04 /work/dev/u-boot
cd /work/dev/u-boot
ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- make stm32mp15_dhcom_basic_defconfig
</syntaxhighlight>

Change default device tree (Example for: stm32mp15xx-dhcom-picoitx):
<syntaxhighlight lang="shell">
sed -iE 's/(stm32mp15xx-dhcom-pdk2|stm32mp157a-dhcor-avenger96)/stm32mp15xx-dhcom-picoitx/' .config
</syntaxhighlight>

Build linux binaries with all available cores:
<syntaxhighlight lang="shell">
ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- make -j$(nproc)
</syntaxhighlight>
<syntaxhighlight lang="console">
...
SHIPPED dts/dt.dtb
CAT u-boot-dtb.bin
MKIMAGE u-boot.img
COPY u-boot.dtb
MKIMAGE u-boot-dtb.img
MKIMAGE u-boot.itb
...
LD spl/u-boot-spl
OBJCOPY spl/u-boot-spl-nodtb.bin
SYM spl/u-boot-spl.sym
CAT spl/u-boot-spl-dtb.bin
COPY spl/u-boot-spl.bin
BINMAN all
</syntaxhighlight>

Check that the required binaries have been created and are of the appropriate size:
<syntaxhighlight lang="shell">
ls -l u-boot.itb u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-rw-r--r-- 1 devel devel 819720 Apr 11 17:03 u-boot.itb
-rw-r--r-- 1 devel devel 124288 Apr 11 17:03 u-boot-spl.stm32
</syntaxhighlight>

== U-Boot booting via DFU ==

To boot U-Boot SPL and U-Boot via DFU boot mode, you must first check if you have a DFU device connected, then load U-Boot SPL into the SRAM of your STM32MP1 and wait until the DRAM is initialized.
Then load U-Boot in the DRAM of your STM32MP1 and continue the boot process using the shown key combination.

=== Download of U-Boot SPL with <code>dfu-util</code> ===

(Re-)Connect the USB cable with your host computer and the OTG port of your baseboard and check the kernel log for a available '''DFU''' device:
<syntaxhighlight lang="shell">
sudo dmesg
</syntaxhighlight>
<syntaxhighlight lang="console" highlight="4">
...
usb 2-2: New USB device found, idVendor=0483, idProduct=df11, bcdDevice= 2.00
usb 2-2: New USB device strings: Mfr=1, Product=2, SerialNumber=3
usb 2-2: Product: DFU in HS Mode @Device ID /0x500, @Revision ID /0x0000
usb 2-2: Manufacturer: STMicroelectronics
usb 2-2: SerialNumber: 0040001D3130510439373430
</syntaxhighlight>

Download of U-Boot SPL with dfu-util to connected device:
<syntaxhighlight lang="shell">
dfu-util -a 1 -D u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
dfu-util 0.9

Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
Copyright 2010-2016 Tormod Volden and Stefan Schmidt
This program is Free Software and has ABSOLUTELY NO WARRANTY
Please report bugs to http://sourceforge.net/p/dfu-util/tickets/

dfu-util: Invalid DFU suffix signature
dfu-util: A valid DFU suffix will be required in a future dfu-util release!!!
Opening DFU capable USB device...
ID 0483:df11
Run-time device DFU version 0110
Claiming USB DFU Interface...
Setting Alternate Setting #1 ...
Determining device status: state = dfuIDLE, status = 0
dfuIDLE, continuing
DFU mode device DFU version 0110
Device returned transfer size 1024
Copying data from PC to DFU device
Download [=========================] 100% 160911 bytes
Download done.
state(7) = dfuMANIFEST, status(0) = No error condition is present
state(2) = dfuIDLE, status(0) = No error condition is present
Done!
</syntaxhighlight>

Output of the serial console:
<syntaxhighlight lang="console">
U-Boot SPL 2022.04 (Apr 05 2022 - 08:27:30 +0200)
Model: STMicroelectronics STM32MP15xx DHCOM Premium Developer Kit (2)
Code: SoM:rev=1,ddr3=3 Board:rev=0
RAM: DDR3L 32bits 2x4Gb 533MHz
Trying to boot from DFU
</syntaxhighlight>

=== Download of U-Boot with <code>dfu-util</code> ===

(Re-)Connect the USB cable with your host computer and the OTG port of your baseboard and check the kernel log for a available '''USB download gadget''' device:
<syntaxhighlight lang="shell">
sudo dmesg
</syntaxhighlight>
<syntaxhighlight lang="console" highlight="5">
...
usb 3-2: new high-speed USB device number 8 using xhci_hcd
usb 3-2: New USB device found, idVendor=0483, idProduct=df11, bcdDevice= 2.27
usb 3-2: New USB device strings: Mfr=1, Product=2, SerialNumber=0
usb 3-2: Product: USB download gadget
usb 3-2: Manufacturer: dh
</syntaxhighlight>

Download of U-Boot with dfu-util to connected device:
<syntaxhighlight lang="shell">
dfu-util -a 0 -D u-boot.itb
</syntaxhighlight>
<syntaxhighlight lang="console">
dfu-util 0.9

Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
Copyright 2010-2016 Tormod Volden and Stefan Schmidt
This program is Free Software and has ABSOLUTELY NO WARRANTY
Please report bugs to http://sourceforge.net/p/dfu-util/tickets/

dfu-util: Invalid DFU suffix signature
dfu-util: A valid DFU suffix will be required in a future dfu-util release!!!
Opening DFU capable USB device...
ID 0483:df11
Run-time device DFU version 0110
Claiming USB DFU Interface...
Setting Alternate Setting #0 ...
Determining device status: state = dfuIDLE, status = 0
dfuIDLE, continuing
DFU mode device DFU version 0110
Device returned transfer size 4096
Copying data from PC to DFU device
Download [=========================] 100% 819232 bytes
Download done.
state(7) = dfuMANIFEST, status(0) = No error condition is present
state(2) = dfuIDLE, status(0) = No error condition is present
Done!
</syntaxhighlight>

Output of the serial console:
<syntaxhighlight lang="console">
#DOWNLOAD ... OK
Ctrl+C to exit ...
</syntaxhighlight>

Output of the serial console after pressing '''Ctrl+C''':
<syntaxhighlight lang="console">
U-Boot 2022.04 (Apr 05 2022 - 08:27:30 +0200)

CPU: STM32MP157CAA Rev.Z
Model: STMicroelectronics STM32MP15xx DHCOM Premium Developer Kit (2)
Board: stm32mp1 in basic mode (dh,stm32mp15xx-dhcom-pdk2)
DRAM: 1 GiB
Clocks:
- MPU : 650 MHz
- MCU : 208.878 MHz
- AXI : 266.500 MHz
- PER : 24 MHz
- DDR : 533 MHz
Core: 255 devices, 31 uclasses, devicetree: separate
MMC: STM32 SD/MMC: 2, STM32 SD/MMC: 0, STM32 SD/MMC: 1
Loading Environment from SPIFlash... SF: Detected w25q16cl with page size 256 Bytes, erase size 4 KiB, total 2 MiB
OK
In: serial
Out: serial
Err: serial
Net: eth0: ethernet@5800a000, eth1: ks8851mll@64000000
Hit any key to stop autoboot: 0
</syntaxhighlight>

== U-Boot booting via SD card ==

Set the disk:
<syntaxhighlight lang="shell">
STM32_DISK=/dev/sdc
</syntaxhighlight>

=== Partition a SD card ===

Create partition table and partitions:
<syntaxhighlight lang="shell">
parted --script -- ${STM32_DISK} \
mktable gpt \
mkpart fsbl1 1MiB 1.25MiB \
mkpart fsbl2 2MiB 2.25MiB \
mkpart ssbl 3MiB 5MiB \
mkpart rootfs ext4 5MiB 100% \
set 4 legacy_boot on \
unit MiB \
print
</syntaxhighlight>
<syntaxhighlight lang="console">
Model: Generic STORAGE DEVICE (scsi)
Disk /dev/sdc: 954MiB
Sector size (logical/physical): 512B/512B
Partition Table: gpt
Disk Flags:

Number Start End Size File system Name Flags
1 1.00MiB 1.25MiB 0.25MiB fsbl1
2 2.00MiB 2.25MiB 0.25MiB fsbl2
3 3.00MiB 5.00MiB 2.00MiB ssbl
4 5.00MiB 953MiB 948MiB ext4 rootfs legacy_boot
</syntaxhighlight>

Redetect partitions:
<syntaxhighlight lang="shell">
partprobe ${STM32_DISK}
</syntaxhighlight>

=== Create file system on partition 4 ===

Create filesystem on partition 4:
<syntaxhighlight lang="shell">
mkfs.ext4 -m 0 -L rootfs ${STM32_DISK}4
</syntaxhighlight>
<syntaxhighlight lang="console">
mke2fs 1.46.2 (28-Feb-2021)
Creating filesystem with 242688 4k blocks and 60672 inodes
Filesystem UUID: bda8eff7-aa5a-4ed8-aa53-f22e3a1e3203
Superblock backups stored on blocks:
32768, 98304, 163840, 229376

Allocating group tables: done
Writing inode tables: done
Creating journal (4096 blocks): done
Writing superblocks and filesystem accounting information: done
</syntaxhighlight>

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

Write u-boot spl and u-boot to boot partitions 1, 2 and 3:
<syntaxhighlight lang="shell">
dd if=u-boot-spl.stm32 of=${STM32_DISK}1
dd if=u-boot-spl.stm32 of=${STM32_DISK}2
dd if=u-boot.itb of=${STM32_DISK}3
</syntaxhighlight>
<syntaxhighlight lang="console">
314+1 records in
314+1 records out
160911 bytes (161 kB, 157 KiB) copied, 0.274919 s, 585 kB/s
314+1 records in
314+1 records out
160911 bytes (161 kB, 157 KiB) copied, 0.280309 s, 574 kB/s
1600+1 records in
1600+1 records out
819232 bytes (819 kB, 800 KiB) copied, 0.862246 s, 950 kB/s
</syntaxhighlight>

Copy u-boot spl and u-boot to directory <code>boot</code> on rootfs partition 4:
<syntaxhighlight lang="shell">
mkdir -p rootfs
mount ${STM32_DISK}4 rootfs
mkdir -p rootfs/boot
cp u-boot-spl.stm32 u-boot.itb rootfs/boot/
umount rootfs && rmdir rootfs
</syntaxhighlight>

=== Boot from SD card ===

# Hold the button for SD card boot mode on the SODIMM-200 module (DHCOM) below the eMMC chip.
#:[[File:STM32MP1-Button.jpg|400px]]
# Reset the device. To reset the device, press the reset button on the baseboard or unplug and plug in the power plug.
# Release the button for SD card boot mode

== U-Boot flashing via SD card ==

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

Follow the instructions in [[#U-Boot booting via SD card|U-Boot booting via SD card]] to prepare an SD card with a file system on partition 4 that contains the required <code>u-boot-spl.stm32</code> and <code>u-boot.itb</code> binaries.

=== Write U-Boot SPL and U-Boot to SPI-NOR-Flash ===

# Start U-Boot by [[#U-Boot booting via DFU|U-Boot booting via DFU]] or by [[#Boot from SD card|Boot from SD card]]
# Attach prepared SD card to the on module SD card slot
# Program U-Boot SPL and U-Boot by the script <code>update_sf</code> stored in the U-Boot environment.
#:<syntaxhighlight lang="shell">
STM32MP> run update_sf
</syntaxhighlight>
#:<syntaxhighlight lang="console">
160911 bytes read in 80 ms (1.9 MiB/s)
819232 bytes read in 115 ms (6.8 MiB/s)
SF: Detected w25q16cl with page size 256 Bytes, erase size 4 KiB, total 2 MiB
SF: 2097152 bytes @ 0x0 Erased: OK
device 0 offset 0x0, size 0x2748f
160911 bytes written, 0 bytes skipped in 1.664s, speed 98903 B/s
device 0 offset 0x40000, size 0x2748f
160911 bytes written, 0 bytes skipped in 1.626s, speed 101211 B/s
device 0 offset 0x80000, size 0xc8020
815136 bytes written, 4096 bytes skipped in 8.379s, speed 100094 B/s
</syntaxhighlight>

U-Boot recovery for STM32MP1 DHSOM via DFU

2022-09-09T06:16:30Z

Jneuhauser: Fix translation

To recover a corrupted U-Boot on a STM32MP1-based DHCOM, we can use the default fallback boot source DFU via serial link or USB to temporarily boot U-Boot SPL and U-Boot.
From this U-Boot shell we can write both bootloader images from the SD card to the boot flash.

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

== Requirements ==
=== Software ===
* Linux host computer ([[Virtual Machine for Application Development]] is used in this guide)
* [https://source.denx.de/u-boot/u-boot/-/tree/v2022.04 U-Boot 2022.04] for your board (download and build instructions below)
* [https://packages.debian.org/stable/dfu-util dfu-util] (for DFU boot mode)

=== Hardware ===
* STM32MP1 based DHCOM
* DHCOM Premium Developer Kit Baseboard (or Baseboards with OTG ports)
* USB cable for OTG port (Mini USB for PDK2, USB-C for PDK3) (for DFU boot mode)
* SD card (for SD card boot mode)

== Preparation ==
This installation was made on the [[Virtual Machine for Application Development]].
All console expressions refer to this Debian system, but any other debian based system should also work.

=== Install dfu-util (debian) ===
<syntaxhighlight lang="shell">
apt-get install dfu-util
</syntaxhighlight>
<syntaxhighlight lang="console">
</syntaxhighlight>

=== Download/Build U-Boot SPL and U-Boot binaries ===

There are two ways to get the required U-Boot binaries.
These can either be downloaded or built from the sources by yourself.
Follow one of the two steps below.

==== Download prebuilt binaries ====

[[media:AACQ30W-7l-Zi_Zutu0Zv-Zua|Dropbox: U-Boot_recovery_for_STM32MP1_DHSOM_via_DFU]] ([https://source.denx.de/u-boot/u-boot/-/tree/v2022.04 source])

<syntaxhighlight lang="shell">
curl -LsS https://www.dropbox.com/sh/os9so01tivajkxs/AACQ30W-7l-Zi_Zutu0Zv-Zua > recovery_binaryies.zip
unzip recovery_binaryies.zip
</syntaxhighlight>
<syntaxhighlight lang="console">
Archive: recovery_binaryies.zip
warning: stripped absolute path spec from /
mapname: conversion of failed
creating: U-Boot_v2022.04_mainline/
creating: U-Boot_v2022.04_mainline/av96/
creating: U-Boot_v2022.04_mainline/pdk2/
creating: U-Boot_v2022.04_mainline/drc02/
creating: U-Boot_v2022.04_mainline/picoitx/
extracting: U-Boot_v2022.04_mainline/av96/u-boot.itb
extracting: U-Boot_v2022.04_mainline/pdk2/u-boot.itb
extracting: U-Boot_v2022.04_mainline/drc02/u-boot.itb
extracting: U-Boot_v2022.04_mainline/picoitx/u-boot.itb
extracting: U-Boot_v2022.04_mainline/av96/u-boot-spl.stm32
extracting: U-Boot_v2022.04_mainline/pdk2/u-boot-spl.stm32
extracting: U-Boot_v2022.04_mainline/drc02/u-boot-spl.stm32
extracting: U-Boot_v2022.04_mainline/picoitx/u-boot-spl.stm32
</syntaxhighlight>

==== Build binaries from source ====

Clone U-Boot mainline source code for release v2022.04:
<syntaxhighlight lang="shell">
UBOOT_SRC=/work/dev/u-boot_v2022.04
mkdir -p $UBOOT_SRC
git clone --branch v2022.04 --depth 1 https://source.denx.de/u-boot/u-boot.git $UBOOT_SRC
cd $UBOOT_SRC
</syntaxhighlight>

Available U-Boot defconfigs for STM32MP1 based DHSOM devices with default device tree in bold:
* '''stm32mp15_dhcom_basic_defconfig''' ('''pdk2''', picoitx, drc02)
* '''stm32mp15_dhcor_basic_defconfig''' ('''avenger96''')
<syntaxhighlight lang="shell">
mkdir -p /work/dev/u-boot
git clone https://source.denx.de/u-boot/u-boot.git -b v2022.04 /work/dev/u-boot
cd /work/dev/u-boot
ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- make stm32mp15_dhcom_basic_defconfig
</syntaxhighlight>

Change default device tree (Example for: stm32mp15xx-dhcom-picoitx):
<syntaxhighlight lang="shell">
sed -iE 's/(stm32mp15xx-dhcom-pdk2|stm32mp157a-dhcor-avenger96)/stm32mp15xx-dhcom-picoitx/' .config
</syntaxhighlight>

Build linux binaries with all available cores:
<syntaxhighlight lang="shell">
ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- make -j$(nproc)
</syntaxhighlight>
<syntaxhighlight lang="console">
...
SHIPPED dts/dt.dtb
CAT u-boot-dtb.bin
MKIMAGE u-boot.img
COPY u-boot.dtb
MKIMAGE u-boot-dtb.img
MKIMAGE u-boot.itb
...
LD spl/u-boot-spl
OBJCOPY spl/u-boot-spl-nodtb.bin
SYM spl/u-boot-spl.sym
CAT spl/u-boot-spl-dtb.bin
COPY spl/u-boot-spl.bin
BINMAN all
</syntaxhighlight>

Check that the required binaries have been created and are of the appropriate size:
<syntaxhighlight lang="shell">
ls -l u-boot.itb u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-rw-r--r-- 1 devel devel 819720 Apr 11 17:03 u-boot.itb
-rw-r--r-- 1 devel devel 124288 Apr 11 17:03 u-boot-spl.stm32
</syntaxhighlight>

== U-Boot booting via DFU ==

To boot U-Boot SPL and U-Boot via DFU boot mode, you must first check if you have a DFU device connected, then load U-Boot SPL into the SRAM of your STM32MP1 and wait until the DRAM is initialized.
Then load U-Boot in the DRAM of your STM32MP1 and continue the boot process using the shown key combination.

=== Check for available DFU device ===

(Re-)Connect the USB cable with your host computer and the OTG port of your baseboard and check the kernel log for a available DFU device:
<syntaxhighlight lang="shell">
sudo dmesg
</syntaxhighlight>
<syntaxhighlight lang="console" highlight="4">
...
usb 2-2: New USB device found, idVendor=0483, idProduct=df11, bcdDevice= 2.00
usb 2-2: New USB device strings: Mfr=1, Product=2, SerialNumber=3
usb 2-2: Product: DFU in HS Mode @Device ID /0x500, @Revision ID /0x0000
usb 2-2: Manufacturer: STMicroelectronics
usb 2-2: SerialNumber: 0040001D3130510439373430
</syntaxhighlight>

=== Download of U-Boot SPL with <code>dfu-util</code> ===

Download of U-Boot SPL with dfu-util to connected device:
<syntaxhighlight lang="shell">
dfu-util -a 1 -D u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
dfu-util 0.9

Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
Copyright 2010-2016 Tormod Volden and Stefan Schmidt
This program is Free Software and has ABSOLUTELY NO WARRANTY
Please report bugs to http://sourceforge.net/p/dfu-util/tickets/

dfu-util: Invalid DFU suffix signature
dfu-util: A valid DFU suffix will be required in a future dfu-util release!!!
Opening DFU capable USB device...
ID 0483:df11
Run-time device DFU version 0110
Claiming USB DFU Interface...
Setting Alternate Setting #1 ...
Determining device status: state = dfuIDLE, status = 0
dfuIDLE, continuing
DFU mode device DFU version 0110
Device returned transfer size 1024
Copying data from PC to DFU device
Download [=========================] 100% 160911 bytes
Download done.
state(7) = dfuMANIFEST, status(0) = No error condition is present
state(2) = dfuIDLE, status(0) = No error condition is present
Done!
</syntaxhighlight>

Output of the serial console:
<syntaxhighlight lang="console">
U-Boot SPL 2022.04 (Apr 05 2022 - 08:27:30 +0200)
Model: STMicroelectronics STM32MP15xx DHCOM Premium Developer Kit (2)
Code: SoM:rev=1,ddr3=3 Board:rev=0
RAM: DDR3L 32bits 2x4Gb 533MHz
Trying to boot from DFU
</syntaxhighlight>

=== Download of U-Boot with <code>dfu-util</code> ===

Download of U-Boot with dfu-util to connected device:
<syntaxhighlight lang="shell">
dfu-util -a 0 -D u-boot.itb
</syntaxhighlight>
<syntaxhighlight lang="console">
dfu-util 0.9

Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
Copyright 2010-2016 Tormod Volden and Stefan Schmidt
This program is Free Software and has ABSOLUTELY NO WARRANTY
Please report bugs to http://sourceforge.net/p/dfu-util/tickets/

dfu-util: Invalid DFU suffix signature
dfu-util: A valid DFU suffix will be required in a future dfu-util release!!!
Opening DFU capable USB device...
ID 0483:df11
Run-time device DFU version 0110
Claiming USB DFU Interface...
Setting Alternate Setting #0 ...
Determining device status: state = dfuIDLE, status = 0
dfuIDLE, continuing
DFU mode device DFU version 0110
Device returned transfer size 4096
Copying data from PC to DFU device
Download [=========================] 100% 819232 bytes
Download done.
state(7) = dfuMANIFEST, status(0) = No error condition is present
state(2) = dfuIDLE, status(0) = No error condition is present
Done!
</syntaxhighlight>

Output of the serial console:
<syntaxhighlight lang="console">
#DOWNLOAD ... OK
Ctrl+C to exit ...
</syntaxhighlight>

Output of the serial console after pressing '''Ctrl+C''':
<syntaxhighlight lang="console">
U-Boot 2022.04 (Apr 05 2022 - 08:27:30 +0200)

CPU: STM32MP157CAA Rev.Z
Model: STMicroelectronics STM32MP15xx DHCOM Premium Developer Kit (2)
Board: stm32mp1 in basic mode (dh,stm32mp15xx-dhcom-pdk2)
DRAM: 1 GiB
Clocks:
- MPU : 650 MHz
- MCU : 208.878 MHz
- AXI : 266.500 MHz
- PER : 24 MHz
- DDR : 533 MHz
Core: 255 devices, 31 uclasses, devicetree: separate
MMC: STM32 SD/MMC: 2, STM32 SD/MMC: 0, STM32 SD/MMC: 1
Loading Environment from SPIFlash... SF: Detected w25q16cl with page size 256 Bytes, erase size 4 KiB, total 2 MiB
OK
In: serial
Out: serial
Err: serial
Net: eth0: ethernet@5800a000, eth1: ks8851mll@64000000
Hit any key to stop autoboot: 0
</syntaxhighlight>

== U-Boot booting via SD card ==

Set the disk:
<syntaxhighlight lang="shell">
STM32_DISK=/dev/sdc
</syntaxhighlight>

=== Partition a SD card ===

Create partition table and partitions:
<syntaxhighlight lang="shell">
parted --script -- ${STM32_DISK} \
mktable gpt \
mkpart fsbl1 1MiB 1.25MiB \
mkpart fsbl2 2MiB 2.25MiB \
mkpart ssbl 3MiB 5MiB \
mkpart rootfs ext4 5MiB 100% \
set 4 legacy_boot on \
unit MiB \
print
</syntaxhighlight>
<syntaxhighlight lang="console">
Model: Generic STORAGE DEVICE (scsi)
Disk /dev/sdc: 954MiB
Sector size (logical/physical): 512B/512B
Partition Table: gpt
Disk Flags:

Number Start End Size File system Name Flags
1 1.00MiB 1.25MiB 0.25MiB fsbl1
2 2.00MiB 2.25MiB 0.25MiB fsbl2
3 3.00MiB 5.00MiB 2.00MiB ssbl
4 5.00MiB 953MiB 948MiB ext4 rootfs legacy_boot
</syntaxhighlight>

Redetect partitions:
<syntaxhighlight lang="shell">
partprobe ${STM32_DISK}
</syntaxhighlight>

=== Create file system on partition 4 ===

Create filesystem on partition 4:
<syntaxhighlight lang="shell">
mkfs.ext4 -m 0 -L rootfs ${STM32_DISK}4
</syntaxhighlight>
<syntaxhighlight lang="console">
mke2fs 1.46.2 (28-Feb-2021)
Creating filesystem with 242688 4k blocks and 60672 inodes
Filesystem UUID: bda8eff7-aa5a-4ed8-aa53-f22e3a1e3203
Superblock backups stored on blocks:
32768, 98304, 163840, 229376

Allocating group tables: done
Writing inode tables: done
Creating journal (4096 blocks): done
Writing superblocks and filesystem accounting information: done
</syntaxhighlight>

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

Write u-boot spl and u-boot to boot partitions 1, 2 and 3:
<syntaxhighlight lang="shell">
dd if=u-boot-spl.stm32 of=${STM32_DISK}1
dd if=u-boot-spl.stm32 of=${STM32_DISK}2
dd if=u-boot.itb of=${STM32_DISK}3
</syntaxhighlight>
<syntaxhighlight lang="console">
314+1 records in
314+1 records out
160911 bytes (161 kB, 157 KiB) copied, 0.274919 s, 585 kB/s
314+1 records in
314+1 records out
160911 bytes (161 kB, 157 KiB) copied, 0.280309 s, 574 kB/s
1600+1 records in
1600+1 records out
819232 bytes (819 kB, 800 KiB) copied, 0.862246 s, 950 kB/s
</syntaxhighlight>

Copy u-boot spl and u-boot to directory <code>boot</code> on rootfs partition 4:
<syntaxhighlight lang="shell">
mkdir -p rootfs
mount ${STM32_DISK}4 rootfs
mkdir -p rootfs/boot
cp u-boot-spl.stm32 u-boot.itb rootfs/boot/
umount rootfs && rmdir rootfs
</syntaxhighlight>

=== Boot from SD card ===

# Hold the button for SD card boot mode on the SODIMM-200 module (DHCOM) below the eMMC chip.
#:[[File:STM32MP1-Button.jpg|400px]]
# Reset the device. To reset the device, press the reset button on the baseboard or unplug and plug in the power plug.
# Release the button for SD card boot mode

== U-Boot flashing via SD card ==

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

Follow the instructions in [[#U-Boot booting via SD card|U-Boot booting via SD card]] to prepare an SD card with a file system on partition 4 that contains the required <code>u-boot-spl.stm32</code> and <code>u-boot.itb</code> binaries.

=== Write U-Boot SPL and U-Boot to SPI-NOR-Flash ===

# Start U-Boot by [[#U-Boot booting via DFU|U-Boot booting via DFU]] or by [[#Boot from SD card|Boot from SD card]]
# Attach prepared SD card to the on module SD card slot
# Program U-Boot SPL and U-Boot by the script <code>update_sf</code> stored in the U-Boot environment.
#:<syntaxhighlight lang="shell">
STM32MP> run update_sf
</syntaxhighlight>
#:<syntaxhighlight lang="console">
160911 bytes read in 80 ms (1.9 MiB/s)
819232 bytes read in 115 ms (6.8 MiB/s)
SF: Detected w25q16cl with page size 256 Bytes, erase size 4 KiB, total 2 MiB
SF: 2097152 bytes @ 0x0 Erased: OK
device 0 offset 0x0, size 0x2748f
160911 bytes written, 0 bytes skipped in 1.664s, speed 98903 B/s
device 0 offset 0x40000, size 0x2748f
160911 bytes written, 0 bytes skipped in 1.626s, speed 101211 B/s
device 0 offset 0x80000, size 0xc8020
815136 bytes written, 4096 bytes skipped in 8.379s, speed 100094 B/s
</syntaxhighlight>

U-Boot recovery for STM32MP1 DHSOM via DFU

2022-09-09T06:15:52Z

Jneuhauser: Add text to section

To recover a corrupted U-Boot on a STM32MP1-based DHCOM, we can use the default fallback boot source DFU via serial link or USB to temporarily boot U-Boot SPL and U-Boot.
From this U-Boot shell we can write both bootloader images from the SD card to the boot flash.

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

== Requirements ==
=== Software ===
* Linux host computer ([[Virtual Machine for Application Development]] is used in this guide)
* [https://source.denx.de/u-boot/u-boot/-/tree/v2022.04 U-Boot 2022.04] for your board (download and build instructions below)
* [https://packages.debian.org/stable/dfu-util dfu-util] (for DFU boot mode)

=== Hardware ===
* STM32MP1 based DHCOM
* DHCOM Premium Developer Kit Baseboard (or Baseboards with OTG ports)
* USB cable for OTG port (Mini USB for PDK2, USB-C for PDK3) (for DFU boot mode)
* SD card (for SD card boot mode)

== Preparation ==
This installation was made on the [[Virtual Machine for Application Development]].
All console expressions refer to this Debian system, but any other debian based system should also work.

=== Install dfu-util (debian) ===
<syntaxhighlight lang="shell">
apt-get install dfu-util
</syntaxhighlight>
<syntaxhighlight lang="console">
</syntaxhighlight>

=== Download/Build U-Boot SPL and U-Boot binaries ===

There are two ways to get the required submarine binaries.
These can either be downloaded or built from the sources by yourself.
Follow one of the two steps below.

==== Download prebuilt binaries ====

[[media:AACQ30W-7l-Zi_Zutu0Zv-Zua|Dropbox: U-Boot_recovery_for_STM32MP1_DHSOM_via_DFU]] ([https://source.denx.de/u-boot/u-boot/-/tree/v2022.04 source])

<syntaxhighlight lang="shell">
curl -LsS https://www.dropbox.com/sh/os9so01tivajkxs/AACQ30W-7l-Zi_Zutu0Zv-Zua > recovery_binaryies.zip
unzip recovery_binaryies.zip
</syntaxhighlight>
<syntaxhighlight lang="console">
Archive: recovery_binaryies.zip
warning: stripped absolute path spec from /
mapname: conversion of failed
creating: U-Boot_v2022.04_mainline/
creating: U-Boot_v2022.04_mainline/av96/
creating: U-Boot_v2022.04_mainline/pdk2/
creating: U-Boot_v2022.04_mainline/drc02/
creating: U-Boot_v2022.04_mainline/picoitx/
extracting: U-Boot_v2022.04_mainline/av96/u-boot.itb
extracting: U-Boot_v2022.04_mainline/pdk2/u-boot.itb
extracting: U-Boot_v2022.04_mainline/drc02/u-boot.itb
extracting: U-Boot_v2022.04_mainline/picoitx/u-boot.itb
extracting: U-Boot_v2022.04_mainline/av96/u-boot-spl.stm32
extracting: U-Boot_v2022.04_mainline/pdk2/u-boot-spl.stm32
extracting: U-Boot_v2022.04_mainline/drc02/u-boot-spl.stm32
extracting: U-Boot_v2022.04_mainline/picoitx/u-boot-spl.stm32
</syntaxhighlight>

==== Build binaries from source ====

Clone U-Boot mainline source code for release v2022.04:
<syntaxhighlight lang="shell">
UBOOT_SRC=/work/dev/u-boot_v2022.04
mkdir -p $UBOOT_SRC
git clone --branch v2022.04 --depth 1 https://source.denx.de/u-boot/u-boot.git $UBOOT_SRC
cd $UBOOT_SRC
</syntaxhighlight>

Available U-Boot defconfigs for STM32MP1 based DHSOM devices with default device tree in bold:
* '''stm32mp15_dhcom_basic_defconfig''' ('''pdk2''', picoitx, drc02)
* '''stm32mp15_dhcor_basic_defconfig''' ('''avenger96''')
<syntaxhighlight lang="shell">
mkdir -p /work/dev/u-boot
git clone https://source.denx.de/u-boot/u-boot.git -b v2022.04 /work/dev/u-boot
cd /work/dev/u-boot
ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- make stm32mp15_dhcom_basic_defconfig
</syntaxhighlight>

Change default device tree (Example for: stm32mp15xx-dhcom-picoitx):
<syntaxhighlight lang="shell">
sed -iE 's/(stm32mp15xx-dhcom-pdk2|stm32mp157a-dhcor-avenger96)/stm32mp15xx-dhcom-picoitx/' .config
</syntaxhighlight>

Build linux binaries with all available cores:
<syntaxhighlight lang="shell">
ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- make -j$(nproc)
</syntaxhighlight>
<syntaxhighlight lang="console">
...
SHIPPED dts/dt.dtb
CAT u-boot-dtb.bin
MKIMAGE u-boot.img
COPY u-boot.dtb
MKIMAGE u-boot-dtb.img
MKIMAGE u-boot.itb
...
LD spl/u-boot-spl
OBJCOPY spl/u-boot-spl-nodtb.bin
SYM spl/u-boot-spl.sym
CAT spl/u-boot-spl-dtb.bin
COPY spl/u-boot-spl.bin
BINMAN all
</syntaxhighlight>

Check that the required binaries have been created and are of the appropriate size:
<syntaxhighlight lang="shell">
ls -l u-boot.itb u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-rw-r--r-- 1 devel devel 819720 Apr 11 17:03 u-boot.itb
-rw-r--r-- 1 devel devel 124288 Apr 11 17:03 u-boot-spl.stm32
</syntaxhighlight>

== U-Boot booting via DFU ==

To boot U-Boot SPL and U-Boot via DFU boot mode, you must first check if you have a DFU device connected, then load U-Boot SPL into the SRAM of your STM32MP1 and wait until the DRAM is initialized.
Then load U-Boot in the DRAM of your STM32MP1 and continue the boot process using the shown key combination.

=== Check for available DFU device ===

(Re-)Connect the USB cable with your host computer and the OTG port of your baseboard and check the kernel log for a available DFU device:
<syntaxhighlight lang="shell">
sudo dmesg
</syntaxhighlight>
<syntaxhighlight lang="console" highlight="4">
...
usb 2-2: New USB device found, idVendor=0483, idProduct=df11, bcdDevice= 2.00
usb 2-2: New USB device strings: Mfr=1, Product=2, SerialNumber=3
usb 2-2: Product: DFU in HS Mode @Device ID /0x500, @Revision ID /0x0000
usb 2-2: Manufacturer: STMicroelectronics
usb 2-2: SerialNumber: 0040001D3130510439373430
</syntaxhighlight>

=== Download of U-Boot SPL with <code>dfu-util</code> ===

Download of U-Boot SPL with dfu-util to connected device:
<syntaxhighlight lang="shell">
dfu-util -a 1 -D u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
dfu-util 0.9

Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
Copyright 2010-2016 Tormod Volden and Stefan Schmidt
This program is Free Software and has ABSOLUTELY NO WARRANTY
Please report bugs to http://sourceforge.net/p/dfu-util/tickets/

dfu-util: Invalid DFU suffix signature
dfu-util: A valid DFU suffix will be required in a future dfu-util release!!!
Opening DFU capable USB device...
ID 0483:df11
Run-time device DFU version 0110
Claiming USB DFU Interface...
Setting Alternate Setting #1 ...
Determining device status: state = dfuIDLE, status = 0
dfuIDLE, continuing
DFU mode device DFU version 0110
Device returned transfer size 1024
Copying data from PC to DFU device
Download [=========================] 100% 160911 bytes
Download done.
state(7) = dfuMANIFEST, status(0) = No error condition is present
state(2) = dfuIDLE, status(0) = No error condition is present
Done!
</syntaxhighlight>

Output of the serial console:
<syntaxhighlight lang="console">
U-Boot SPL 2022.04 (Apr 05 2022 - 08:27:30 +0200)
Model: STMicroelectronics STM32MP15xx DHCOM Premium Developer Kit (2)
Code: SoM:rev=1,ddr3=3 Board:rev=0
RAM: DDR3L 32bits 2x4Gb 533MHz
Trying to boot from DFU
</syntaxhighlight>

=== Download of U-Boot with <code>dfu-util</code> ===

Download of U-Boot with dfu-util to connected device:
<syntaxhighlight lang="shell">
dfu-util -a 0 -D u-boot.itb
</syntaxhighlight>
<syntaxhighlight lang="console">
dfu-util 0.9

Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
Copyright 2010-2016 Tormod Volden and Stefan Schmidt
This program is Free Software and has ABSOLUTELY NO WARRANTY
Please report bugs to http://sourceforge.net/p/dfu-util/tickets/

dfu-util: Invalid DFU suffix signature
dfu-util: A valid DFU suffix will be required in a future dfu-util release!!!
Opening DFU capable USB device...
ID 0483:df11
Run-time device DFU version 0110
Claiming USB DFU Interface...
Setting Alternate Setting #0 ...
Determining device status: state = dfuIDLE, status = 0
dfuIDLE, continuing
DFU mode device DFU version 0110
Device returned transfer size 4096
Copying data from PC to DFU device
Download [=========================] 100% 819232 bytes
Download done.
state(7) = dfuMANIFEST, status(0) = No error condition is present
state(2) = dfuIDLE, status(0) = No error condition is present
Done!
</syntaxhighlight>

Output of the serial console:
<syntaxhighlight lang="console">
#DOWNLOAD ... OK
Ctrl+C to exit ...
</syntaxhighlight>

Output of the serial console after pressing '''Ctrl+C''':
<syntaxhighlight lang="console">
U-Boot 2022.04 (Apr 05 2022 - 08:27:30 +0200)

CPU: STM32MP157CAA Rev.Z
Model: STMicroelectronics STM32MP15xx DHCOM Premium Developer Kit (2)
Board: stm32mp1 in basic mode (dh,stm32mp15xx-dhcom-pdk2)
DRAM: 1 GiB
Clocks:
- MPU : 650 MHz
- MCU : 208.878 MHz
- AXI : 266.500 MHz
- PER : 24 MHz
- DDR : 533 MHz
Core: 255 devices, 31 uclasses, devicetree: separate
MMC: STM32 SD/MMC: 2, STM32 SD/MMC: 0, STM32 SD/MMC: 1
Loading Environment from SPIFlash... SF: Detected w25q16cl with page size 256 Bytes, erase size 4 KiB, total 2 MiB
OK
In: serial
Out: serial
Err: serial
Net: eth0: ethernet@5800a000, eth1: ks8851mll@64000000
Hit any key to stop autoboot: 0
</syntaxhighlight>

== U-Boot booting via SD card ==

Set the disk:
<syntaxhighlight lang="shell">
STM32_DISK=/dev/sdc
</syntaxhighlight>

=== Partition a SD card ===

Create partition table and partitions:
<syntaxhighlight lang="shell">
parted --script -- ${STM32_DISK} \
mktable gpt \
mkpart fsbl1 1MiB 1.25MiB \
mkpart fsbl2 2MiB 2.25MiB \
mkpart ssbl 3MiB 5MiB \
mkpart rootfs ext4 5MiB 100% \
set 4 legacy_boot on \
unit MiB \
print
</syntaxhighlight>
<syntaxhighlight lang="console">
Model: Generic STORAGE DEVICE (scsi)
Disk /dev/sdc: 954MiB
Sector size (logical/physical): 512B/512B
Partition Table: gpt
Disk Flags:

Number Start End Size File system Name Flags
1 1.00MiB 1.25MiB 0.25MiB fsbl1
2 2.00MiB 2.25MiB 0.25MiB fsbl2
3 3.00MiB 5.00MiB 2.00MiB ssbl
4 5.00MiB 953MiB 948MiB ext4 rootfs legacy_boot
</syntaxhighlight>

Redetect partitions:
<syntaxhighlight lang="shell">
partprobe ${STM32_DISK}
</syntaxhighlight>

=== Create file system on partition 4 ===

Create filesystem on partition 4:
<syntaxhighlight lang="shell">
mkfs.ext4 -m 0 -L rootfs ${STM32_DISK}4
</syntaxhighlight>
<syntaxhighlight lang="console">
mke2fs 1.46.2 (28-Feb-2021)
Creating filesystem with 242688 4k blocks and 60672 inodes
Filesystem UUID: bda8eff7-aa5a-4ed8-aa53-f22e3a1e3203
Superblock backups stored on blocks:
32768, 98304, 163840, 229376

Allocating group tables: done
Writing inode tables: done
Creating journal (4096 blocks): done
Writing superblocks and filesystem accounting information: done
</syntaxhighlight>

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

Write u-boot spl and u-boot to boot partitions 1, 2 and 3:
<syntaxhighlight lang="shell">
dd if=u-boot-spl.stm32 of=${STM32_DISK}1
dd if=u-boot-spl.stm32 of=${STM32_DISK}2
dd if=u-boot.itb of=${STM32_DISK}3
</syntaxhighlight>
<syntaxhighlight lang="console">
314+1 records in
314+1 records out
160911 bytes (161 kB, 157 KiB) copied, 0.274919 s, 585 kB/s
314+1 records in
314+1 records out
160911 bytes (161 kB, 157 KiB) copied, 0.280309 s, 574 kB/s
1600+1 records in
1600+1 records out
819232 bytes (819 kB, 800 KiB) copied, 0.862246 s, 950 kB/s
</syntaxhighlight>

Copy u-boot spl and u-boot to directory <code>boot</code> on rootfs partition 4:
<syntaxhighlight lang="shell">
mkdir -p rootfs
mount ${STM32_DISK}4 rootfs
mkdir -p rootfs/boot
cp u-boot-spl.stm32 u-boot.itb rootfs/boot/
umount rootfs && rmdir rootfs
</syntaxhighlight>

=== Boot from SD card ===

# Hold the button for SD card boot mode on the SODIMM-200 module (DHCOM) below the eMMC chip.
#:[[File:STM32MP1-Button.jpg|400px]]
# Reset the device. To reset the device, press the reset button on the baseboard or unplug and plug in the power plug.
# Release the button for SD card boot mode

== U-Boot flashing via SD card ==

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

Follow the instructions in [[#U-Boot booting via SD card|U-Boot booting via SD card]] to prepare an SD card with a file system on partition 4 that contains the required <code>u-boot-spl.stm32</code> and <code>u-boot.itb</code> binaries.

=== Write U-Boot SPL and U-Boot to SPI-NOR-Flash ===

# Start U-Boot by [[#U-Boot booting via DFU|U-Boot booting via DFU]] or by [[#Boot from SD card|Boot from SD card]]
# Attach prepared SD card to the on module SD card slot
# Program U-Boot SPL and U-Boot by the script <code>update_sf</code> stored in the U-Boot environment.
#:<syntaxhighlight lang="shell">
STM32MP> run update_sf
</syntaxhighlight>
#:<syntaxhighlight lang="console">
160911 bytes read in 80 ms (1.9 MiB/s)
819232 bytes read in 115 ms (6.8 MiB/s)
SF: Detected w25q16cl with page size 256 Bytes, erase size 4 KiB, total 2 MiB
SF: 2097152 bytes @ 0x0 Erased: OK
device 0 offset 0x0, size 0x2748f
160911 bytes written, 0 bytes skipped in 1.664s, speed 98903 B/s
device 0 offset 0x40000, size 0x2748f
160911 bytes written, 0 bytes skipped in 1.626s, speed 101211 B/s
device 0 offset 0x80000, size 0xc8020
815136 bytes written, 4096 bytes skipped in 8.379s, speed 100094 B/s
</syntaxhighlight>

DHCOM STM32MP15 Secure Boot

2022-09-09T06:10:49Z

Jneuhauser:

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

Checkout the branch <syntaxhighlight lang="shell" inline>v2022.01_dhcom_secure_boot</syntaxhighlight> from DH electronics GitHub repository with:

<syntaxhighlight lang="shell">
git clone https://github.com/dh-electronics/u-boot-stm32mp1.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 u-boot-stm32mp1 https://github.com/dh-electronics/u-boot-stm32mp1.git
git fetch u-boot-stm32mp1
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-spl-signed.stm32 || FSBL || Same as above but as signed STM32 image. Is created in [[#Sign U-Boot SPL with STM32MP_SigningTool_CLI|Sign U-Boot SPL with STM32MP_SigningTool_CLI]].
|-
| u-boot.itb || SSBL || U-Boot and Device Tree's contained in a FIT image.
|-
| u-boot-signed.itb || SSBL || Same as above but with signed configs and images.
|}

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

Load <syntaxhighlight lang="shell" inline>u-boot-spl-signed.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot-signed.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-signed.stm32
tftp ${fsbl2addr} ${serverip}:u-boot-spl-signed.stm32
tftp ${ssbl1addr} ${serverip}:u-boot-signed.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 =====

<div style="color:blue">Note: If you have any problems with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command use the manual procedure with the generic <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command in the next section.</div>

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

<div style="color:blue">Note: Use this manual procedure only if you have problems with the simpler <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command from the previous section.</div>

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: A Yocto example project would be the best!</div>

== Support of STM32MP1 DHSOM in TF-A, OP-TEE OS and OP-TEE Developer Setup ==

The following table shows the Support status of our STM32MP1-based DHSOMs in the TF-A, OP-TEE OS and OP-TEE Developer Setup projects.
This table is also a good starting point for what is required to support custom boards based on the STM32MP1 DHSOM in these projects.

{| class="wikitable" style="margin:auto"
|+ Support of STM32MP1 DHSOM in TF-A, OP-TEE OS and OP-TEE Developer Setup
|-
! DHSOM
! TF-A<ref name="TF-A" />
! OP-TEE OS<ref name="OP-TEE/optee_os" />
! OP-TEE developer setup<ref name="OP-TEE/build" />
! OP-TEE developer setup Linux<ref name="linaro-swg/linux" />
! OP-TEE developer setup manifest<ref name="OP-TEE/manifest" />
|-
! STM32MP157C DHCOM PDK2
| upstreamed in [https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/commit/?id=eef485abb13b6df9a94137edd82904aab0ecf02d commit eef485ab]
| upstreamed in [https://github.com/OP-TEE/optee_os/commit/6e9896c08ac4d8e81bb95ba1afa46cf6028fd4df commit 6e9896c0]
| under review in [https://github.com/OP-TEE/build/pull/586 pull request 586]
| under review in [https://github.com/linaro-swg/linux/pull/105 pull request 105]
| preview in [https://github.com/jneuhauser/optee_manifest/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
|-
! STM32MP157A DHCOR Avenger96
| upstreamed in [https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/commit/?id=51e223058fe70b311542178f1865514745fa7874 commit 51e22305]
| upstreamed in [https://github.com/OP-TEE/optee_os/commit/5c932a03de3f1126c4710b3b6b296eb720746182 commit 5c932a03]
| under review in [https://github.com/OP-TEE/build/pull/586 pull request 586]
| under review in [https://github.com/linaro-swg/linux/pull/105 pull request 105]
| preview in [https://github.com/jneuhauser/optee_manifest/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
|}

= Examples for Flatten Image Tree Source files =

Example for a FIT-Source file with signed Linux, ramdisk and two device trees / configurations:
<syntaxhighlight lang="c">
/dts-v1/;

/ {
description = "Linux, Ramdisk and FDT for STM32MP1 DHSOM";
#address-cells = <1>;

images {
linux {
description = "Linux STM32MP1 DHSOM";
data = /incbin/("/work/dev/linux/dev-5.10.y_dhsom/arch/arm/boot/Image.gz");
type = "kernel";
os = "linux";
arch = "arm";
/* Image compressed with gzip and decrompressed by U-Boot */
compression = "gzip";
load = <0xc0008000>;
entry = <0xc0008000>;
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

ramdisk {
description = "RootFS Ramdisk DHSOM";
data = /incbin/("/work/dev/rootfs/ramdisk.cpio.gz");
type = "ramdisk";
arch = "arm";
os = "linux";
/* ramdisk.cpio compressed with gzip and decrompressed by Linux instead of by U-Boot */
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

fdt-stm32mp157c-dhcom-pdk2 {
description = "FDT STM32MP157C DHCOM Premium Developer Kit (2)";
data = /incbin/("/work/dev/linux/dev-5.10.y_dhsom/arch/arm/boot/dts/stm32mp157c-dhcom-pdk2.dtb");
type = "flat_dt";
arch = "arm";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

fdt-stm32mp157c-dhcom-picoitx {
description = "FDT STM32MP157C DHCOM PicoITX";
data = /incbin/("/work/dev/linux/dev-5.10.y_dhsom/arch/arm/boot/dts/stm32mp157c-dhcom-picoitx.dtb");
type = "flat_dt";
arch = "arm";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};
};

configurations {
default = "config-stm32mp157c-dhcom-pdk2";

config-stm32mp157c-dhcom-pdk2 {
description = "STM32MP157C DHCOM Premium Developer Kit (2)";
kernel = "linux";
ramdisk = "ramdisk";
fdt = "fdt-stm32mp157c-dhcom-pdk2";
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_CFG";
sign-images = "kernel", "ramdisk", "fdt";
};
};

config-stm32mp157c-dhcom-picoitx {
description = "STM32MP157C DHCOM PicoITX";
kernel = "linux";
ramdisk = "ramdisk";
fdt = "fdt-stm32mp157c-dhcom-picoitx";
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_CFG";
sign-images = "kernel", "ramdisk", "fdt";
};
};
};
};
</syntaxhighlight>

= 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 OP-TEE developer setup]</ref>
<ref name="OP-TEE/manifest">[https://github.com/OP-TEE/build OP-TEE developer setup manifest]</ref>
<ref name="linaro-swg/linux">[https://github.com/linaro-swg/linux Linux for OP-TEE developer setup]</ref>

</references>

DHCOM STM32MP15 Secure Boot

2022-09-08T15:45:39Z

Jneuhauser: Fix layout/reference issues and add TODO

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

Checkout the branch <syntaxhighlight lang="shell" inline>v2022.01_dhcom_secure_boot</syntaxhighlight> from DH electronics GitHub repository with:

<syntaxhighlight lang="shell">
git clone https://github.com/dh-electronics/u-boot-stm32mp1.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 u-boot-stm32mp1 https://github.com/dh-electronics/u-boot-stm32mp1.git
git fetch u-boot-stm32mp1
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-spl-signed.stm32 || FSBL || Same as above but as signed STM32 image. Is created in [[#Sign U-Boot SPL with STM32MP_SigningTool_CLI|Sign U-Boot SPL with STM32MP_SigningTool_CLI]].
|-
| u-boot.itb || SSBL || U-Boot and Device Tree's contained in a FIT image.
|-
| u-boot-signed.itb || SSBL || Same as above but with signed configs and images.
|}

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

Load <syntaxhighlight lang="shell" inline>u-boot-spl-signed.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot-signed.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-signed.stm32
tftp ${fsbl2addr} ${serverip}:u-boot-spl-signed.stm32
tftp ${ssbl1addr} ${serverip}:u-boot-signed.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 =====

<div style="color:blue">Note: If you have any problems with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command use the manual procedure with the generic <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command in the next section.</div>

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

<div style="color:blue">Note: Use this manual procedure only if you have problems with the simpler <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command from the previous section.</div>

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: A Yocto example project would be the best!</div>

== Support of STM32MP1 DHSOM in TF-A, OP-TEE OS and OP-TEE Developer Setup ==

The following table shows the Suuport status of our STM32MP1-based DHSOMs in the TF-A, OP-TEE OS and OP-TEE Developer Setup projects.
This table is also a good starting point for what is required to support custom boards based on the STM32MP1 DHSOM in these projects.

{| class="wikitable" style="margin:auto"
|+ Support of STM32MP1 DHSOM in TF-A, OP-TEE OS and OP-TEE Developer Setup
|-
! DHSOM
! TF-A<ref name="TF-A" />
! OP-TEE OS<ref name="OP-TEE/optee_os" />
! OP-TEE developer setup<ref name="OP-TEE/build" />
! OP-TEE developer setup Linux<ref name="linaro-swg/linux" />
! OP-TEE developer setup manifest<ref name="OP-TEE/manifest" />
|-
! STM32MP157C DHCOM PDK2
| upstreamed in [https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/commit/?id=eef485abb13b6df9a94137edd82904aab0ecf02d commit eef485ab]
| upstreamed in [https://github.com/OP-TEE/optee_os/commit/6e9896c08ac4d8e81bb95ba1afa46cf6028fd4df commit 6e9896c0]
| under review in [https://github.com/OP-TEE/build/pull/586 pull request 586]
| under review in [https://github.com/linaro-swg/linux/pull/105 pull request 105]
| preview in [https://github.com/jneuhauser/optee_manifest/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
|-
! STM32MP157A DHCOR Avenger96
| upstreamed in [https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/commit/?id=51e223058fe70b311542178f1865514745fa7874 commit 51e22305]
| upstreamed in [https://github.com/OP-TEE/optee_os/commit/5c932a03de3f1126c4710b3b6b296eb720746182 commit 5c932a03]
| under review in [https://github.com/OP-TEE/build/pull/586 pull request 586]
| under review in [https://github.com/linaro-swg/linux/pull/105 pull request 105]
| preview in [https://github.com/jneuhauser/optee_manifest/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
|}

= Examples for Flatten Image Tree Source files =

Example for a FIT-Source file with signed Linux, ramdisk and two device trees / configurations:
<syntaxhighlight lang="c">
/dts-v1/;

/ {
description = "Linux, Ramdisk and FDT for STM32MP1 DHSOM";
#address-cells = <1>;

images {
linux {
description = "Linux STM32MP1 DHSOM";
data = /incbin/("/work/dev/linux/dev-5.10.y_dhsom/arch/arm/boot/Image.gz");
type = "kernel";
os = "linux";
arch = "arm";
/* Image compressed with gzip and decrompressed by U-Boot */
compression = "gzip";
load = <0xc0008000>;
entry = <0xc0008000>;
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

ramdisk {
description = "RootFS Ramdisk DHSOM";
data = /incbin/("/work/dev/rootfs/ramdisk.cpio.gz");
type = "ramdisk";
arch = "arm";
os = "linux";
/* ramdisk.cpio compressed with gzip and decrompressed by Linux instead of by U-Boot */
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

fdt-stm32mp157c-dhcom-pdk2 {
description = "FDT STM32MP157C DHCOM Premium Developer Kit (2)";
data = /incbin/("/work/dev/linux/dev-5.10.y_dhsom/arch/arm/boot/dts/stm32mp157c-dhcom-pdk2.dtb");
type = "flat_dt";
arch = "arm";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

fdt-stm32mp157c-dhcom-picoitx {
description = "FDT STM32MP157C DHCOM PicoITX";
data = /incbin/("/work/dev/linux/dev-5.10.y_dhsom/arch/arm/boot/dts/stm32mp157c-dhcom-picoitx.dtb");
type = "flat_dt";
arch = "arm";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};
};

configurations {
default = "config-stm32mp157c-dhcom-pdk2";

config-stm32mp157c-dhcom-pdk2 {
description = "STM32MP157C DHCOM Premium Developer Kit (2)";
kernel = "linux";
ramdisk = "ramdisk";
fdt = "fdt-stm32mp157c-dhcom-pdk2";
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_CFG";
sign-images = "kernel", "ramdisk", "fdt";
};
};

config-stm32mp157c-dhcom-picoitx {
description = "STM32MP157C DHCOM PicoITX";
kernel = "linux";
ramdisk = "ramdisk";
fdt = "fdt-stm32mp157c-dhcom-picoitx";
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_CFG";
sign-images = "kernel", "ramdisk", "fdt";
};
};
};
};
</syntaxhighlight>

= 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 OP-TEE developer setup]</ref>
<ref name="OP-TEE/manifest">[https://github.com/OP-TEE/build OP-TEE developer setup manifest]</ref>
<ref name="linaro-swg/linux">[https://github.com/linaro-swg/linux Linux for OP-TEE developer setup]</ref>

</references>

DHCOM STM32MP15 Secure Boot

2022-09-08T15:39:32Z

Jneuhauser: /* Secure Boot in Trusted Boot with BootROM authentication, TF-A and OP-TEE */

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

Checkout the branch <syntaxhighlight lang="shell" inline>v2022.01_dhcom_secure_boot</syntaxhighlight> from DH electronics GitHub repository with:

<syntaxhighlight lang="shell">
git clone https://github.com/dh-electronics/u-boot-stm32mp1.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 u-boot-stm32mp1 https://github.com/dh-electronics/u-boot-stm32mp1.git
git fetch u-boot-stm32mp1
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-spl-signed.stm32 || FSBL || Same as above but as signed STM32 image. Is created in [[#Sign U-Boot SPL with STM32MP_SigningTool_CLI|Sign U-Boot SPL with STM32MP_SigningTool_CLI]].
|-
| u-boot.itb || SSBL || U-Boot and Device Tree's contained in a FIT image.
|-
| u-boot-signed.itb || SSBL || Same as above but with signed configs and images.
|}

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

Load <syntaxhighlight lang="shell" inline>u-boot-spl-signed.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot-signed.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-signed.stm32
tftp ${fsbl2addr} ${serverip}:u-boot-spl-signed.stm32
tftp ${ssbl1addr} ${serverip}:u-boot-signed.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 =====

<div style="color:blue">Note: If you have any problems with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command use the manual procedure with the generic <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command in the next section.</div>

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

<div style="color:blue">Note: Use this manual procedure only if you have problems with the simpler <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command from the previous section.</div>

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 =

== Support of STM32MP1 DHSOM in TF-A, OP-TEE OS and OP-TEE Developer Setup ==

The following table shows the Suuport status of our STM32MP1-based DHSOMs in the TF-A, OP-TEE OS and OP-TEE Developer Setup projects.
This table is also a good starting point for what is required to support custom boards based on the STM32MP1 DHSOM in these projects.

{| class="wikitable" style="margin:auto" align="left"
|+ Support of STM32MP1 DHSOM in TF-A, OP-TEE OS and OP-TEE Developer Setup
|-
! DHSOM
! TF-A
! OP-TEE OS
! OP-TEE developer setup
! OP-TEE developer setup Linux
! OP-TEE developer setup manifest
|-
! STM32MP157C DHCOM PDK2
| upstreamed in [https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/commit/?id=eef485abb13b6df9a94137edd82904aab0ecf02d commit eef485ab]
| upstreamed in [https://github.com/OP-TEE/optee_os/commit/6e9896c08ac4d8e81bb95ba1afa46cf6028fd4df commit 6e9896c0]
| under review in [https://github.com/OP-TEE/build/pull/586 pull request 586]
| under review in [https://github.com/linaro-swg/linux/pull/105 pull request 105]
| preview in [https://github.com/jneuhauser/optee_manifest/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
|-
! STM32MP157A DHCOR Avenger96
| upstreamed in [https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/commit/?id=51e223058fe70b311542178f1865514745fa7874 commit 51e22305]
| upstreamed in [https://github.com/OP-TEE/optee_os/commit/5c932a03de3f1126c4710b3b6b296eb720746182 commit 5c932a03]
| under review in [https://github.com/OP-TEE/build/pull/586 pull request 586]
| under review in [https://github.com/linaro-swg/linux/pull/105 pull request 105]
| preview in [https://github.com/jneuhauser/optee_manifest/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
|}

= Examples for Flatten Image Tree Source files =

Example for a FIT-Source file with signed Linux, ramdisk and two device trees / configurations:
<syntaxhighlight lang="c">
/dts-v1/;

/ {
description = "Linux, Ramdisk and FDT for STM32MP1 DHSOM";
#address-cells = <1>;

images {
linux {
description = "Linux STM32MP1 DHSOM";
data = /incbin/("/work/dev/linux/dev-5.10.y_dhsom/arch/arm/boot/Image.gz");
type = "kernel";
os = "linux";
arch = "arm";
/* Image compressed with gzip and decrompressed by U-Boot */
compression = "gzip";
load = <0xc0008000>;
entry = <0xc0008000>;
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

ramdisk {
description = "RootFS Ramdisk DHSOM";
data = /incbin/("/work/dev/rootfs/ramdisk.cpio.gz");
type = "ramdisk";
arch = "arm";
os = "linux";
/* ramdisk.cpio compressed with gzip and decrompressed by Linux instead of by U-Boot */
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

fdt-stm32mp157c-dhcom-pdk2 {
description = "FDT STM32MP157C DHCOM Premium Developer Kit (2)";
data = /incbin/("/work/dev/linux/dev-5.10.y_dhsom/arch/arm/boot/dts/stm32mp157c-dhcom-pdk2.dtb");
type = "flat_dt";
arch = "arm";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

fdt-stm32mp157c-dhcom-picoitx {
description = "FDT STM32MP157C DHCOM PicoITX";
data = /incbin/("/work/dev/linux/dev-5.10.y_dhsom/arch/arm/boot/dts/stm32mp157c-dhcom-picoitx.dtb");
type = "flat_dt";
arch = "arm";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};
};

configurations {
default = "config-stm32mp157c-dhcom-pdk2";

config-stm32mp157c-dhcom-pdk2 {
description = "STM32MP157C DHCOM Premium Developer Kit (2)";
kernel = "linux";
ramdisk = "ramdisk";
fdt = "fdt-stm32mp157c-dhcom-pdk2";
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_CFG";
sign-images = "kernel", "ramdisk", "fdt";
};
};

config-stm32mp157c-dhcom-picoitx {
description = "STM32MP157C DHCOM PicoITX";
kernel = "linux";
ramdisk = "ramdisk";
fdt = "fdt-stm32mp157c-dhcom-picoitx";
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_CFG";
sign-images = "kernel", "ramdisk", "fdt";
};
};
};
};
</syntaxhighlight>

= 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 OP-TEE developer setup]</ref>
<ref name="OP-TEE/manifest">[https://github.com/OP-TEE/build OP-TEE developer setup manifest]</ref>
<ref name="linaro-swg/linux">[https://github.com/linaro-swg/linux Linux for OP-TEE developer setup]</ref>

</references>

DHCOM STM32MP15 Secure Boot

2022-09-08T14:34:23Z

Jneuhauser: /* References */

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

Checkout the branch <syntaxhighlight lang="shell" inline>v2022.01_dhcom_secure_boot</syntaxhighlight> from DH electronics GitHub repository with:

<syntaxhighlight lang="shell">
git clone https://github.com/dh-electronics/u-boot-stm32mp1.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 u-boot-stm32mp1 https://github.com/dh-electronics/u-boot-stm32mp1.git
git fetch u-boot-stm32mp1
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-spl-signed.stm32 || FSBL || Same as above but as signed STM32 image. Is created in [[#Sign U-Boot SPL with STM32MP_SigningTool_CLI|Sign U-Boot SPL with STM32MP_SigningTool_CLI]].
|-
| u-boot.itb || SSBL || U-Boot and Device Tree's contained in a FIT image.
|-
| u-boot-signed.itb || SSBL || Same as above but with signed configs and images.
|}

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

Load <syntaxhighlight lang="shell" inline>u-boot-spl-signed.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot-signed.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-signed.stm32
tftp ${fsbl2addr} ${serverip}:u-boot-spl-signed.stm32
tftp ${ssbl1addr} ${serverip}:u-boot-signed.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 =====

<div style="color:blue">Note: If you have any problems with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command use the manual procedure with the generic <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command in the next section.</div>

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

<div style="color:blue">Note: Use this manual procedure only if you have problems with the simpler <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command from the previous section.</div>

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 TF-A<ref name="TF-A" />
## STM32MP157C DHCOM on PDK2 baseboard: upstreamed in [https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/commit/fdts/stm32mp157c-dhcom-pdk2.dts?id=eef485abb13b6df9a94137edd82904aab0ecf02d commit eef485ab]
## STM32MP157A DHCOR SoM on Avenger96 baseboard: upstreamed in [https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/commit/?id=51e223058fe70b311542178f1865514745fa7874 commit 51e22305]
# Add support for STM32MP15 DHCOM in OP-TEE OS <ref name="OP-TEE/optee_os" />
## STM32MP157C DHCOM on PDK2 baseboard: upstreamed in [https://github.com/OP-TEE/optee_os/commit/6e9896c08ac4d8e81bb95ba1afa46cf6028fd4df commit 6e9896c0]
## STM32MP157A DHCOR SoM on Avenger96 baseboard: upstreamed in [https://github.com/OP-TEE/optee_os/commit/5c932a03de3f1126c4710b3b6b296eb720746182 commit 5c932a03]
# Integrate STM32MP15 DHCOM into OP-TEE developer setup <ref name="OP-TEE/build" />
## STM32MP157C DHCOM on PDK2 baseboard: under review in [https://github.com/OP-TEE/build/pull/586 pull request 586] (preview available in [https://github.com/jneuhauser/optee_build/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
## STM32MP157A DHCOR SoM on Avenger96 baseboard: under review in [https://github.com/OP-TEE/build/pull/586 pull request 586] (preview available in [https://github.com/jneuhauser/optee_build/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
# Define Linux OP-TEE ressources for STM32MP15 DHSOM <ref name="linaro-swg/linux" />
## STM32MP157C DHCOM on PDK2 baseboard: under review in [https://github.com/linaro-swg/linux/pull/105 pull request 105] (preview available in [https://github.com/jneuhauser/linux/tree/optee-stm32mp1-dhsom branch optee-stm32mp1-dhsom])
## STM32MP157A DHCOR SoM on Avenger96 baseboard: under review in [https://github.com/linaro-swg/linux/pull/105 pull request 105] (preview available in [https://github.com/jneuhauser/linux/tree/optee-stm32mp1-dhsom branch optee-stm32mp1-dhsom])
# Update required components in OP-TEE developer setup manifest <ref name="OP-TEE/manifest" />
## STM32MP157C DHCOM on PDK2 baseboard: waiting for next TF-A release (preview available in [https://github.com/jneuhauser/optee_manifest/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
## STM32MP157A DHCOR SoM on Avenger96 baseboard: waiting for next TF-A release (preview available in [https://github.com/jneuhauser/optee_manifest/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])

= Examples for Flatten Image Tree Source files =

Example for a FIT-Source file with signed Linux, ramdisk and two device trees / configurations:
<syntaxhighlight lang="c">
/dts-v1/;

/ {
description = "Linux, Ramdisk and FDT for STM32MP1 DHSOM";
#address-cells = <1>;

images {
linux {
description = "Linux STM32MP1 DHSOM";
data = /incbin/("/work/dev/linux/dev-5.10.y_dhsom/arch/arm/boot/Image.gz");
type = "kernel";
os = "linux";
arch = "arm";
/* Image compressed with gzip and decrompressed by U-Boot */
compression = "gzip";
load = <0xc0008000>;
entry = <0xc0008000>;
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

ramdisk {
description = "RootFS Ramdisk DHSOM";
data = /incbin/("/work/dev/rootfs/ramdisk.cpio.gz");
type = "ramdisk";
arch = "arm";
os = "linux";
/* ramdisk.cpio compressed with gzip and decrompressed by Linux instead of by U-Boot */
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

fdt-stm32mp157c-dhcom-pdk2 {
description = "FDT STM32MP157C DHCOM Premium Developer Kit (2)";
data = /incbin/("/work/dev/linux/dev-5.10.y_dhsom/arch/arm/boot/dts/stm32mp157c-dhcom-pdk2.dtb");
type = "flat_dt";
arch = "arm";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

fdt-stm32mp157c-dhcom-picoitx {
description = "FDT STM32MP157C DHCOM PicoITX";
data = /incbin/("/work/dev/linux/dev-5.10.y_dhsom/arch/arm/boot/dts/stm32mp157c-dhcom-picoitx.dtb");
type = "flat_dt";
arch = "arm";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};
};

configurations {
default = "config-stm32mp157c-dhcom-pdk2";

config-stm32mp157c-dhcom-pdk2 {
description = "STM32MP157C DHCOM Premium Developer Kit (2)";
kernel = "linux";
ramdisk = "ramdisk";
fdt = "fdt-stm32mp157c-dhcom-pdk2";
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_CFG";
sign-images = "kernel", "ramdisk", "fdt";
};
};

config-stm32mp157c-dhcom-picoitx {
description = "STM32MP157C DHCOM PicoITX";
kernel = "linux";
ramdisk = "ramdisk";
fdt = "fdt-stm32mp157c-dhcom-picoitx";
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_CFG";
sign-images = "kernel", "ramdisk", "fdt";
};
};
};
};
</syntaxhighlight>

= 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 OP-TEE developer setup]</ref>
<ref name="OP-TEE/manifest">[https://github.com/OP-TEE/build OP-TEE developer setup manifest]</ref>
<ref name="linaro-swg/linux">[https://github.com/linaro-swg/linux Linux for OP-TEE developer setup]</ref>

</references>

DHCOM STM32MP15 Secure Boot

2022-09-08T14:32:46Z

Jneuhauser: Update status of OP-TEE upstreaming

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

Checkout the branch <syntaxhighlight lang="shell" inline>v2022.01_dhcom_secure_boot</syntaxhighlight> from DH electronics GitHub repository with:

<syntaxhighlight lang="shell">
git clone https://github.com/dh-electronics/u-boot-stm32mp1.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 u-boot-stm32mp1 https://github.com/dh-electronics/u-boot-stm32mp1.git
git fetch u-boot-stm32mp1
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-spl-signed.stm32 || FSBL || Same as above but as signed STM32 image. Is created in [[#Sign U-Boot SPL with STM32MP_SigningTool_CLI|Sign U-Boot SPL with STM32MP_SigningTool_CLI]].
|-
| u-boot.itb || SSBL || U-Boot and Device Tree's contained in a FIT image.
|-
| u-boot-signed.itb || SSBL || Same as above but with signed configs and images.
|}

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

Load <syntaxhighlight lang="shell" inline>u-boot-spl-signed.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot-signed.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-signed.stm32
tftp ${fsbl2addr} ${serverip}:u-boot-spl-signed.stm32
tftp ${ssbl1addr} ${serverip}:u-boot-signed.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 =====

<div style="color:blue">Note: If you have any problems with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command use the manual procedure with the generic <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command in the next section.</div>

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

<div style="color:blue">Note: Use this manual procedure only if you have problems with the simpler <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command from the previous section.</div>

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 TF-A<ref name="TF-A" />
## STM32MP157C DHCOM on PDK2 baseboard: upstreamed in [https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/commit/fdts/stm32mp157c-dhcom-pdk2.dts?id=eef485abb13b6df9a94137edd82904aab0ecf02d commit eef485ab]
## STM32MP157A DHCOR SoM on Avenger96 baseboard: upstreamed in [https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/commit/?id=51e223058fe70b311542178f1865514745fa7874 commit 51e22305]
# Add support for STM32MP15 DHCOM in OP-TEE OS <ref name="OP-TEE/optee_os" />
## STM32MP157C DHCOM on PDK2 baseboard: upstreamed in [https://github.com/OP-TEE/optee_os/commit/6e9896c08ac4d8e81bb95ba1afa46cf6028fd4df commit 6e9896c0]
## STM32MP157A DHCOR SoM on Avenger96 baseboard: upstreamed in [https://github.com/OP-TEE/optee_os/commit/5c932a03de3f1126c4710b3b6b296eb720746182 commit 5c932a03]
# Integrate STM32MP15 DHCOM into OP-TEE developer setup <ref name="OP-TEE/build" />
## STM32MP157C DHCOM on PDK2 baseboard: under review in [https://github.com/OP-TEE/build/pull/586 pull request 586] (preview available in [https://github.com/jneuhauser/optee_build/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
## STM32MP157A DHCOR SoM on Avenger96 baseboard: under review in [https://github.com/OP-TEE/build/pull/586 pull request 586] (preview available in [https://github.com/jneuhauser/optee_build/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
# Define Linux OP-TEE ressources for STM32MP15 DHSOM <ref name="linaro-swg/linux" />
## STM32MP157C DHCOM on PDK2 baseboard: under review in [https://github.com/linaro-swg/linux/pull/105 pull request 105] (preview available in [https://github.com/jneuhauser/linux/tree/optee-stm32mp1-dhsom branch optee-stm32mp1-dhsom])
## STM32MP157A DHCOR SoM on Avenger96 baseboard: under review in [https://github.com/linaro-swg/linux/pull/105 pull request 105] (preview available in [https://github.com/jneuhauser/linux/tree/optee-stm32mp1-dhsom branch optee-stm32mp1-dhsom])
# Update required components in OP-TEE developer setup manifest <ref name="OP-TEE/manifest" />
## STM32MP157C DHCOM on PDK2 baseboard: waiting for next TF-A release (preview available in [https://github.com/jneuhauser/optee_manifest/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
## STM32MP157A DHCOR SoM on Avenger96 baseboard: waiting for next TF-A release (preview available in [https://github.com/jneuhauser/optee_manifest/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])

= Examples for Flatten Image Tree Source files =

Example for a FIT-Source file with signed Linux, ramdisk and two device trees / configurations:
<syntaxhighlight lang="c">
/dts-v1/;

/ {
description = "Linux, Ramdisk and FDT for STM32MP1 DHSOM";
#address-cells = <1>;

images {
linux {
description = "Linux STM32MP1 DHSOM";
data = /incbin/("/work/dev/linux/dev-5.10.y_dhsom/arch/arm/boot/Image.gz");
type = "kernel";
os = "linux";
arch = "arm";
/* Image compressed with gzip and decrompressed by U-Boot */
compression = "gzip";
load = <0xc0008000>;
entry = <0xc0008000>;
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

ramdisk {
description = "RootFS Ramdisk DHSOM";
data = /incbin/("/work/dev/rootfs/ramdisk.cpio.gz");
type = "ramdisk";
arch = "arm";
os = "linux";
/* ramdisk.cpio compressed with gzip and decrompressed by Linux instead of by U-Boot */
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

fdt-stm32mp157c-dhcom-pdk2 {
description = "FDT STM32MP157C DHCOM Premium Developer Kit (2)";
data = /incbin/("/work/dev/linux/dev-5.10.y_dhsom/arch/arm/boot/dts/stm32mp157c-dhcom-pdk2.dtb");
type = "flat_dt";
arch = "arm";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

fdt-stm32mp157c-dhcom-picoitx {
description = "FDT STM32MP157C DHCOM PicoITX";
data = /incbin/("/work/dev/linux/dev-5.10.y_dhsom/arch/arm/boot/dts/stm32mp157c-dhcom-picoitx.dtb");
type = "flat_dt";
arch = "arm";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};
};

configurations {
default = "config-stm32mp157c-dhcom-pdk2";

config-stm32mp157c-dhcom-pdk2 {
description = "STM32MP157C DHCOM Premium Developer Kit (2)";
kernel = "linux";
ramdisk = "ramdisk";
fdt = "fdt-stm32mp157c-dhcom-pdk2";
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_CFG";
sign-images = "kernel", "ramdisk", "fdt";
};
};

config-stm32mp157c-dhcom-picoitx {
description = "STM32MP157C DHCOM PicoITX";
kernel = "linux";
ramdisk = "ramdisk";
fdt = "fdt-stm32mp157c-dhcom-picoitx";
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_CFG";
sign-images = "kernel", "ramdisk", "fdt";
};
};
};
};
</syntaxhighlight>

= 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 OP-TEE developer setup]</ref>
</references>

DHCOM STM32MP15 Secure Boot

2022-09-06T06:04:44Z

Jneuhauser: Update status of TF-A upstreaming

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

Checkout the branch <syntaxhighlight lang="shell" inline>v2022.01_dhcom_secure_boot</syntaxhighlight> from DH electronics GitHub repository with:

<syntaxhighlight lang="shell">
git clone https://github.com/dh-electronics/u-boot-stm32mp1.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 u-boot-stm32mp1 https://github.com/dh-electronics/u-boot-stm32mp1.git
git fetch u-boot-stm32mp1
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-spl-signed.stm32 || FSBL || Same as above but as signed STM32 image. Is created in [[#Sign U-Boot SPL with STM32MP_SigningTool_CLI|Sign U-Boot SPL with STM32MP_SigningTool_CLI]].
|-
| u-boot.itb || SSBL || U-Boot and Device Tree's contained in a FIT image.
|-
| u-boot-signed.itb || SSBL || Same as above but with signed configs and images.
|}

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

Load <syntaxhighlight lang="shell" inline>u-boot-spl-signed.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot-signed.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-signed.stm32
tftp ${fsbl2addr} ${serverip}:u-boot-spl-signed.stm32
tftp ${ssbl1addr} ${serverip}:u-boot-signed.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 =====

<div style="color:blue">Note: If you have any problems with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command use the manual procedure with the generic <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command in the next section.</div>

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

<div style="color:blue">Note: Use this manual procedure only if you have problems with the simpler <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command from the previous section.</div>

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 TF-A<ref name="TF-A" />
## STM32MP157C DHCOM on PDK2 baseboard: upstreamed in [https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/commit/fdts/stm32mp157c-dhcom-pdk2.dts?id=eef485abb13b6df9a94137edd82904aab0ecf02d commit eef485ab]
## STM32MP157A DHCOR SoM on Avenger96 baseboard: upstreamed in [https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/commit/?id=51e223058fe70b311542178f1865514745fa7874 commit 51e22305]
# Add support for STM32MP15 DHCOM in OP-TEE OS <ref name="OP-TEE/optee_os" />
## STM32MP157C DHCOM on PDK2 baseboard: under review in [https://github.com/OP-TEE/optee_os/pull/5479 pull request 5479] (preview available in [https://github.com/jneuhauser/optee_os/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
## STM32MP157A DHCOR SoM on Avenger96 baseboard: under review in [https://github.com/OP-TEE/optee_os/pull/5479 pull request 5479] (preview available in [https://github.com/jneuhauser/optee_os/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
# Integrate STM32MP15 DHCOM into OP-TEE developer setup <ref name="OP-TEE/build" />
## STM32MP157C DHCOM on PDK2 baseboard: work in progress (preview available in [https://github.com/jneuhauser/optee_build/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
## STM32MP157A DHCOR SoM on Avenger96 baseboard: work in progress (preview available in [https://github.com/jneuhauser/optee_build/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
# OP-TEE OP-TEE developer setup manifest <ref name="OP-TEE/build" />
## STM32MP157C DHCOM on PDK2 baseboard: work in progress (preview available in [https://github.com/jneuhauser/optee_manifest/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
## STM32MP157A DHCOR SoM on Avenger96 baseboard: work in progress (preview available in [https://github.com/jneuhauser/optee_manifest/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])

= Examples for Flatten Image Tree Source files =

Example for a FIT-Source file with signed Linux, ramdisk and two device trees / configurations:
<syntaxhighlight lang="c">
/dts-v1/;

/ {
description = "Linux, Ramdisk and FDT for STM32MP1 DHSOM";
#address-cells = <1>;

images {
linux {
description = "Linux STM32MP1 DHSOM";
data = /incbin/("/work/dev/linux/dev-5.10.y_dhsom/arch/arm/boot/Image.gz");
type = "kernel";
os = "linux";
arch = "arm";
/* Image compressed with gzip and decrompressed by U-Boot */
compression = "gzip";
load = <0xc0008000>;
entry = <0xc0008000>;
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

ramdisk {
description = "RootFS Ramdisk DHSOM";
data = /incbin/("/work/dev/rootfs/ramdisk.cpio.gz");
type = "ramdisk";
arch = "arm";
os = "linux";
/* ramdisk.cpio compressed with gzip and decrompressed by Linux instead of by U-Boot */
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

fdt-stm32mp157c-dhcom-pdk2 {
description = "FDT STM32MP157C DHCOM Premium Developer Kit (2)";
data = /incbin/("/work/dev/linux/dev-5.10.y_dhsom/arch/arm/boot/dts/stm32mp157c-dhcom-pdk2.dtb");
type = "flat_dt";
arch = "arm";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

fdt-stm32mp157c-dhcom-picoitx {
description = "FDT STM32MP157C DHCOM PicoITX";
data = /incbin/("/work/dev/linux/dev-5.10.y_dhsom/arch/arm/boot/dts/stm32mp157c-dhcom-picoitx.dtb");
type = "flat_dt";
arch = "arm";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};
};

configurations {
default = "config-stm32mp157c-dhcom-pdk2";

config-stm32mp157c-dhcom-pdk2 {
description = "STM32MP157C DHCOM Premium Developer Kit (2)";
kernel = "linux";
ramdisk = "ramdisk";
fdt = "fdt-stm32mp157c-dhcom-pdk2";
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_CFG";
sign-images = "kernel", "ramdisk", "fdt";
};
};

config-stm32mp157c-dhcom-picoitx {
description = "STM32MP157C DHCOM PicoITX";
kernel = "linux";
ramdisk = "ramdisk";
fdt = "fdt-stm32mp157c-dhcom-picoitx";
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_CFG";
sign-images = "kernel", "ramdisk", "fdt";
};
};
};
};
</syntaxhighlight>

= 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 OP-TEE developer setup]</ref>
</references>

DHCOM STM32MP15 Secure Boot

2022-08-09T12:29:15Z

Jneuhauser: Update state of OP-TEE mainiling

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

Checkout the branch <syntaxhighlight lang="shell" inline>v2022.01_dhcom_secure_boot</syntaxhighlight> from DH electronics GitHub repository with:

<syntaxhighlight lang="shell">
git clone https://github.com/dh-electronics/u-boot-stm32mp1.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 u-boot-stm32mp1 https://github.com/dh-electronics/u-boot-stm32mp1.git
git fetch u-boot-stm32mp1
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-spl-signed.stm32 || FSBL || Same as above but as signed STM32 image. Is created in [[#Sign U-Boot SPL with STM32MP_SigningTool_CLI|Sign U-Boot SPL with STM32MP_SigningTool_CLI]].
|-
| u-boot.itb || SSBL || U-Boot and Device Tree's contained in a FIT image.
|-
| u-boot-signed.itb || SSBL || Same as above but with signed configs and images.
|}

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

Load <syntaxhighlight lang="shell" inline>u-boot-spl-signed.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot-signed.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-signed.stm32
tftp ${fsbl2addr} ${serverip}:u-boot-spl-signed.stm32
tftp ${ssbl1addr} ${serverip}:u-boot-signed.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 =====

<div style="color:blue">Note: If you have any problems with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command use the manual procedure with the generic <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command in the next section.</div>

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

<div style="color:blue">Note: Use this manual procedure only if you have problems with the simpler <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command from the previous section.</div>

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 TF-A<ref name="TF-A" />
## STM32MP157C DHCOM on PDK2 baseboard: upstreamed in [https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/commit/fdts/stm32mp157c-dhcom-pdk2.dts?id=eef485abb13b6df9a94137edd82904aab0ecf02d commit eef485ab]
## STM32MP157A DHCOR SoM on Avenger96 baseboard: under review in [https://review.trustedfirmware.org/c/TF-A/trusted-firmware-a/+/15939 change 15939]
# Add support for STM32MP15 DHCOM in OP-TEE OS <ref name="OP-TEE/optee_os" />
## STM32MP157C DHCOM on PDK2 baseboard: under review in [https://github.com/OP-TEE/optee_os/pull/5479 pull request 5479] (preview available in [https://github.com/jneuhauser/optee_os/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
## STM32MP157A DHCOR SoM on Avenger96 baseboard: under review in [https://github.com/OP-TEE/optee_os/pull/5479 pull request 5479] (preview available in [https://github.com/jneuhauser/optee_os/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
# Integrate STM32MP15 DHCOM into OP-TEE developer setup <ref name="OP-TEE/build" />
## STM32MP157C DHCOM on PDK2 baseboard: work in progress (preview available in [https://github.com/jneuhauser/optee_build/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
## STM32MP157A DHCOR SoM on Avenger96 baseboard: work in progress (preview available in [https://github.com/jneuhauser/optee_build/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
# OP-TEE OP-TEE developer setup manifest <ref name="OP-TEE/build" />
## STM32MP157C DHCOM on PDK2 baseboard: work in progress (preview available in [https://github.com/jneuhauser/optee_manifest/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
## STM32MP157A DHCOR SoM on Avenger96 baseboard: work in progress (preview available in [https://github.com/jneuhauser/optee_manifest/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])

= Examples for Flatten Image Tree Source files =

Example for a FIT-Source file with signed Linux, ramdisk and two device trees / configurations:
<syntaxhighlight lang="c">
/dts-v1/;

/ {
description = "Linux, Ramdisk and FDT for STM32MP1 DHSOM";
#address-cells = <1>;

images {
linux {
description = "Linux STM32MP1 DHSOM";
data = /incbin/("/work/dev/linux/dev-5.10.y_dhsom/arch/arm/boot/Image.gz");
type = "kernel";
os = "linux";
arch = "arm";
/* Image compressed with gzip and decrompressed by U-Boot */
compression = "gzip";
load = <0xc0008000>;
entry = <0xc0008000>;
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

ramdisk {
description = "RootFS Ramdisk DHSOM";
data = /incbin/("/work/dev/rootfs/ramdisk.cpio.gz");
type = "ramdisk";
arch = "arm";
os = "linux";
/* ramdisk.cpio compressed with gzip and decrompressed by Linux instead of by U-Boot */
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

fdt-stm32mp157c-dhcom-pdk2 {
description = "FDT STM32MP157C DHCOM Premium Developer Kit (2)";
data = /incbin/("/work/dev/linux/dev-5.10.y_dhsom/arch/arm/boot/dts/stm32mp157c-dhcom-pdk2.dtb");
type = "flat_dt";
arch = "arm";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

fdt-stm32mp157c-dhcom-picoitx {
description = "FDT STM32MP157C DHCOM PicoITX";
data = /incbin/("/work/dev/linux/dev-5.10.y_dhsom/arch/arm/boot/dts/stm32mp157c-dhcom-picoitx.dtb");
type = "flat_dt";
arch = "arm";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};
};

configurations {
default = "config-stm32mp157c-dhcom-pdk2";

config-stm32mp157c-dhcom-pdk2 {
description = "STM32MP157C DHCOM Premium Developer Kit (2)";
kernel = "linux";
ramdisk = "ramdisk";
fdt = "fdt-stm32mp157c-dhcom-pdk2";
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_CFG";
sign-images = "kernel", "ramdisk", "fdt";
};
};

config-stm32mp157c-dhcom-picoitx {
description = "STM32MP157C DHCOM PicoITX";
kernel = "linux";
ramdisk = "ramdisk";
fdt = "fdt-stm32mp157c-dhcom-picoitx";
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_CFG";
sign-images = "kernel", "ramdisk", "fdt";
};
};
};
};
</syntaxhighlight>

= 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 OP-TEE developer setup]</ref>
</references>

Yocto build guide with docker

2022-07-22T11:02:41Z

Jneuhauser: Initial minimal version

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

= Requirements =

To build Yocto images you need a powerfull build machine and a lot of time.

== Hardware ==

* CPU: four cores or more
* RAM: 16 GB or more
* HDD/SSD: from 25 GB to 100 GB free space (depends on included features)

== Software ==

* Linux OS
* Docker

= Start your build environment =

The following two examples show how to create yocto images using the <syntaxhighlight lang="shell" inline>kas</syntaxhighlight> container or the <syntaxhighlight lang="shell" inline>kas-container</syntaxhighlight> script.

In the following examples, we use the meta-dhsom-stm32-bsp layer as the top layer for creating images for the STM32MP15 DHSOM family with our baseboards.
If you have your own layer on top because you have a custom DHSOM baseboard, then you must replace meta-dhsom-stm32-bsp with your own layer in all commands.

See the documentation for how to use the <syntaxhighlight lang="shell" inline>kas</syntaxhighlight> tool:
* https://kas.readthedocs.io/en/latest/userguide.html
* https://kas.readthedocs.io/en/latest/command-line.html

== Docker container based bash shell ==

Preparation:
<syntaxhighlight lang="shell">
export KAS_WORK_DIR=/mnt/work/yocto
export KAS_BUILD_DIR=/mnt/build/yocto

mkdir -p "${KAS_WORK_DIR}" "${KAS_BUILD_DIR}"

cd /path/to/meta-dhsom-stm32-bsp

docker run --rm --interactive --tty --init \
--env TERM="xterm-256color" \
--env USER_ID="$(id -u)" --env GROUP_ID="$(id -g)" \
--volume "${KAS_BUILD_DIR}":"${KAS_BUILD_DIR}":rw \
--env KAS_BUILD_DIR="${KAS_BUILD_DIR}" \
--volume "${KAS_WORK_DIR}":"${KAS_WORK_DIR}":rw \
--env KAS_WORK_DIR="${KAS_WORK_DIR}" \
--volume "${PWD}":"${PWD}":rw \
--workdir="${PWD}" \
ghcr.io/siemens/kas/kas:latest-release \
/bin/bash
</syntaxhighlight>

Usage:
<syntaxhighlight lang="shell">
cd /path/to/meta-dhsom-stm32-bsp/kas
kas menu
kas build
</syntaxhighlight>

== Docker container based kas tool ==

Preparation:
<syntaxhighlight lang="shell">
wget -O kas-container https://github.com/siemens/kas/raw/master/kas-container
chmod +x kas-container
</syntaxhighlight>

Usage:
<syntaxhighlight lang="shell">
cd /path/to/meta-dhsom-stm32-bsp/kas
/path/to/kas-container menu
/path/to/kas-container build
</syntaxhighlight>

DHCOM STM32MP15 Secure Boot

2022-07-18T13:31:02Z

Jneuhauser: Remove one useless subsection

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

Checkout the branch <syntaxhighlight lang="shell" inline>v2022.01_dhcom_secure_boot</syntaxhighlight> from DH electronics GitHub repository with:

<syntaxhighlight lang="shell">
git clone https://github.com/dh-electronics/u-boot-stm32mp1.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 u-boot-stm32mp1 https://github.com/dh-electronics/u-boot-stm32mp1.git
git fetch u-boot-stm32mp1
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-spl-signed.stm32 || FSBL || Same as above but as signed STM32 image. Is created in [[#Sign U-Boot SPL with STM32MP_SigningTool_CLI|Sign U-Boot SPL with STM32MP_SigningTool_CLI]].
|-
| u-boot.itb || SSBL || U-Boot and Device Tree's contained in a FIT image.
|-
| u-boot-signed.itb || SSBL || Same as above but with signed configs and images.
|}

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

Load <syntaxhighlight lang="shell" inline>u-boot-spl-signed.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot-signed.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-signed.stm32
tftp ${fsbl2addr} ${serverip}:u-boot-spl-signed.stm32
tftp ${ssbl1addr} ${serverip}:u-boot-signed.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 =====

<div style="color:blue">Note: If you have any problems with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command use the manual procedure with the generic <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command in the next section.</div>

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

<div style="color:blue">Note: Use this manual procedure only if you have problems with the simpler <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command from the previous section.</div>

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 TF-A<ref name="TF-A" />
## STM32MP157C DHCOM on PDK2 baseboard: upstreamed in [https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/commit/fdts/stm32mp157c-dhcom-pdk2.dts?id=eef485abb13b6df9a94137edd82904aab0ecf02d commit eef485ab]
## STM32MP157A DHCOR SoM on Avenger96 baseboard: under review in [https://review.trustedfirmware.org/c/TF-A/trusted-firmware-a/+/15939 change 15939]
# Add support for STM32MP15 DHCOM in OP-TEE OS <ref name="OP-TEE/optee_os" />
## STM32MP157C DHCOM on PDK2 baseboard: work in progress (preview available in [https://github.com/jneuhauser/optee_os/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
## STM32MP157A DHCOR SoM on Avenger96 baseboard: work in progress (preview available in [https://github.com/jneuhauser/optee_os/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
# Integrate STM32MP15 DHCOM into OP-TEE developer setup <ref name="OP-TEE/build" />
## STM32MP157C DHCOM on PDK2 baseboard: work in progress (preview available in [https://github.com/jneuhauser/optee_build/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
## STM32MP157A DHCOR SoM on Avenger96 baseboard: work in progress (preview available in [https://github.com/jneuhauser/optee_build/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
# OP-TEE OP-TEE developer setup manifest <ref name="OP-TEE/build" />
## STM32MP157C DHCOM on PDK2 baseboard: work in progress (preview available in [https://github.com/jneuhauser/optee_manifest/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
## STM32MP157A DHCOR SoM on Avenger96 baseboard: work in progress (preview available in [https://github.com/jneuhauser/optee_manifest/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])

= Examples for Flatten Image Tree Source files =

Example for a FIT-Source file with signed Linux, ramdisk and two device trees / configurations:
<syntaxhighlight lang="c">
/dts-v1/;

/ {
description = "Linux, Ramdisk and FDT for STM32MP1 DHSOM";
#address-cells = <1>;

images {
linux {
description = "Linux STM32MP1 DHSOM";
data = /incbin/("/work/dev/linux/dev-5.10.y_dhsom/arch/arm/boot/Image.gz");
type = "kernel";
os = "linux";
arch = "arm";
/* Image compressed with gzip and decrompressed by U-Boot */
compression = "gzip";
load = <0xc0008000>;
entry = <0xc0008000>;
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

ramdisk {
description = "RootFS Ramdisk DHSOM";
data = /incbin/("/work/dev/rootfs/ramdisk.cpio.gz");
type = "ramdisk";
arch = "arm";
os = "linux";
/* ramdisk.cpio compressed with gzip and decrompressed by Linux instead of by U-Boot */
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

fdt-stm32mp157c-dhcom-pdk2 {
description = "FDT STM32MP157C DHCOM Premium Developer Kit (2)";
data = /incbin/("/work/dev/linux/dev-5.10.y_dhsom/arch/arm/boot/dts/stm32mp157c-dhcom-pdk2.dtb");
type = "flat_dt";
arch = "arm";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

fdt-stm32mp157c-dhcom-picoitx {
description = "FDT STM32MP157C DHCOM PicoITX";
data = /incbin/("/work/dev/linux/dev-5.10.y_dhsom/arch/arm/boot/dts/stm32mp157c-dhcom-picoitx.dtb");
type = "flat_dt";
arch = "arm";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};
};

configurations {
default = "config-stm32mp157c-dhcom-pdk2";

config-stm32mp157c-dhcom-pdk2 {
description = "STM32MP157C DHCOM Premium Developer Kit (2)";
kernel = "linux";
ramdisk = "ramdisk";
fdt = "fdt-stm32mp157c-dhcom-pdk2";
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_CFG";
sign-images = "kernel", "ramdisk", "fdt";
};
};

config-stm32mp157c-dhcom-picoitx {
description = "STM32MP157C DHCOM PicoITX";
kernel = "linux";
ramdisk = "ramdisk";
fdt = "fdt-stm32mp157c-dhcom-picoitx";
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_CFG";
sign-images = "kernel", "ramdisk", "fdt";
};
};
};
};
</syntaxhighlight>

= 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 OP-TEE developer setup]</ref>
</references>

DHCOM STM32MP15 Secure Boot

2022-07-18T13:25:34Z

Jneuhauser: /* References */ Update OP-TEE developer setup

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

Checkout the branch <syntaxhighlight lang="shell" inline>v2022.01_dhcom_secure_boot</syntaxhighlight> from DH electronics GitHub repository with:

<syntaxhighlight lang="shell">
git clone https://github.com/dh-electronics/u-boot-stm32mp1.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 u-boot-stm32mp1 https://github.com/dh-electronics/u-boot-stm32mp1.git
git fetch u-boot-stm32mp1
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-spl-signed.stm32 || FSBL || Same as above but as signed STM32 image. Is created in [[#Sign U-Boot SPL with STM32MP_SigningTool_CLI|Sign U-Boot SPL with STM32MP_SigningTool_CLI]].
|-
| u-boot.itb || SSBL || U-Boot and Device Tree's contained in a FIT image.
|-
| u-boot-signed.itb || SSBL || Same as above but with signed configs and images.
|}

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

Load <syntaxhighlight lang="shell" inline>u-boot-spl-signed.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot-signed.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-signed.stm32
tftp ${fsbl2addr} ${serverip}:u-boot-spl-signed.stm32
tftp ${ssbl1addr} ${serverip}:u-boot-signed.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 ======

<div style="color:blue">Note: If you have any problems with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command use the manual procedure with the generic <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command in the next section.</div>

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

<div style="color:blue">Note: Use this manual procedure only if you have problems with the simpler <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command from the previous section.</div>

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 TF-A<ref name="TF-A" />
## STM32MP157C DHCOM on PDK2 baseboard: upstreamed in [https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/commit/fdts/stm32mp157c-dhcom-pdk2.dts?id=eef485abb13b6df9a94137edd82904aab0ecf02d commit eef485ab]
## STM32MP157A DHCOR SoM on Avenger96 baseboard: under review in [https://review.trustedfirmware.org/c/TF-A/trusted-firmware-a/+/15939 change 15939]
# Add support for STM32MP15 DHCOM in OP-TEE OS <ref name="OP-TEE/optee_os" />
## STM32MP157C DHCOM on PDK2 baseboard: work in progress (preview available in [https://github.com/jneuhauser/optee_os/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
## STM32MP157A DHCOR SoM on Avenger96 baseboard: work in progress (preview available in [https://github.com/jneuhauser/optee_os/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
# Integrate STM32MP15 DHCOM into OP-TEE developer setup <ref name="OP-TEE/build" />
## STM32MP157C DHCOM on PDK2 baseboard: work in progress (preview available in [https://github.com/jneuhauser/optee_build/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
## STM32MP157A DHCOR SoM on Avenger96 baseboard: work in progress (preview available in [https://github.com/jneuhauser/optee_build/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
# OP-TEE OP-TEE developer setup manifest <ref name="OP-TEE/build" />
## STM32MP157C DHCOM on PDK2 baseboard: work in progress (preview available in [https://github.com/jneuhauser/optee_manifest/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
## STM32MP157A DHCOR SoM on Avenger96 baseboard: work in progress (preview available in [https://github.com/jneuhauser/optee_manifest/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])

== Examples for Flatten Image Tree Source files ==

Example for a FIT-Source file with signed Linux, ramdisk and two device trees / configurations:
<syntaxhighlight lang="c">
/dts-v1/;

/ {
description = "Linux, Ramdisk and FDT for STM32MP1 DHSOM";
#address-cells = <1>;

images {
linux {
description = "Linux STM32MP1 DHSOM";
data = /incbin/("/work/dev/linux/dev-5.10.y_dhsom/arch/arm/boot/Image.gz");
type = "kernel";
os = "linux";
arch = "arm";
/* Image compressed with gzip and decrompressed by U-Boot */
compression = "gzip";
load = <0xc0008000>;
entry = <0xc0008000>;
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

ramdisk {
description = "RootFS Ramdisk DHSOM";
data = /incbin/("/work/dev/rootfs/ramdisk.cpio.gz");
type = "ramdisk";
arch = "arm";
os = "linux";
/* ramdisk.cpio compressed with gzip and decrompressed by Linux instead of by U-Boot */
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

fdt-stm32mp157c-dhcom-pdk2 {
description = "FDT STM32MP157C DHCOM Premium Developer Kit (2)";
data = /incbin/("/work/dev/linux/dev-5.10.y_dhsom/arch/arm/boot/dts/stm32mp157c-dhcom-pdk2.dtb");
type = "flat_dt";
arch = "arm";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

fdt-stm32mp157c-dhcom-picoitx {
description = "FDT STM32MP157C DHCOM PicoITX";
data = /incbin/("/work/dev/linux/dev-5.10.y_dhsom/arch/arm/boot/dts/stm32mp157c-dhcom-picoitx.dtb");
type = "flat_dt";
arch = "arm";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};
};

configurations {
default = "config-stm32mp157c-dhcom-pdk2";

config-stm32mp157c-dhcom-pdk2 {
description = "STM32MP157C DHCOM Premium Developer Kit (2)";
kernel = "linux";
ramdisk = "ramdisk";
fdt = "fdt-stm32mp157c-dhcom-pdk2";
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_CFG";
sign-images = "kernel", "ramdisk", "fdt";
};
};

config-stm32mp157c-dhcom-picoitx {
description = "STM32MP157C DHCOM PicoITX";
kernel = "linux";
ramdisk = "ramdisk";
fdt = "fdt-stm32mp157c-dhcom-picoitx";
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_CFG";
sign-images = "kernel", "ramdisk", "fdt";
};
};
};
};
</syntaxhighlight>

== 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 OP-TEE developer setup]</ref>
</references>

DHCOM STM32MP15 Secure Boot

2022-07-18T13:21:17Z

Jneuhauser: /* Secure Boot in Trusted Boot with BootROM authentication, TF-A and OP-TEE */ Update TF-A and OP-TEE progress

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

Checkout the branch <syntaxhighlight lang="shell" inline>v2022.01_dhcom_secure_boot</syntaxhighlight> from DH electronics GitHub repository with:

<syntaxhighlight lang="shell">
git clone https://github.com/dh-electronics/u-boot-stm32mp1.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 u-boot-stm32mp1 https://github.com/dh-electronics/u-boot-stm32mp1.git
git fetch u-boot-stm32mp1
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-spl-signed.stm32 || FSBL || Same as above but as signed STM32 image. Is created in [[#Sign U-Boot SPL with STM32MP_SigningTool_CLI|Sign U-Boot SPL with STM32MP_SigningTool_CLI]].
|-
| u-boot.itb || SSBL || U-Boot and Device Tree's contained in a FIT image.
|-
| u-boot-signed.itb || SSBL || Same as above but with signed configs and images.
|}

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

Load <syntaxhighlight lang="shell" inline>u-boot-spl-signed.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot-signed.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-signed.stm32
tftp ${fsbl2addr} ${serverip}:u-boot-spl-signed.stm32
tftp ${ssbl1addr} ${serverip}:u-boot-signed.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 ======

<div style="color:blue">Note: If you have any problems with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command use the manual procedure with the generic <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command in the next section.</div>

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

<div style="color:blue">Note: Use this manual procedure only if you have problems with the simpler <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command from the previous section.</div>

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 TF-A<ref name="TF-A" />
## STM32MP157C DHCOM on PDK2 baseboard: upstreamed in [https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/commit/fdts/stm32mp157c-dhcom-pdk2.dts?id=eef485abb13b6df9a94137edd82904aab0ecf02d commit eef485ab]
## STM32MP157A DHCOR SoM on Avenger96 baseboard: under review in [https://review.trustedfirmware.org/c/TF-A/trusted-firmware-a/+/15939 change 15939]
# Add support for STM32MP15 DHCOM in OP-TEE OS <ref name="OP-TEE/optee_os" />
## STM32MP157C DHCOM on PDK2 baseboard: work in progress (preview available in [https://github.com/jneuhauser/optee_os/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
## STM32MP157A DHCOR SoM on Avenger96 baseboard: work in progress (preview available in [https://github.com/jneuhauser/optee_os/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
# Integrate STM32MP15 DHCOM into OP-TEE developer setup <ref name="OP-TEE/build" />
## STM32MP157C DHCOM on PDK2 baseboard: work in progress (preview available in [https://github.com/jneuhauser/optee_build/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
## STM32MP157A DHCOR SoM on Avenger96 baseboard: work in progress (preview available in [https://github.com/jneuhauser/optee_build/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
# OP-TEE OP-TEE developer setup manifest <ref name="OP-TEE/build" />
## STM32MP157C DHCOM on PDK2 baseboard: work in progress (preview available in [https://github.com/jneuhauser/optee_manifest/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])
## STM32MP157A DHCOR SoM on Avenger96 baseboard: work in progress (preview available in [https://github.com/jneuhauser/optee_manifest/tree/dev/stm32mp1-dhsom branch dev/stm32mp1-dhsom])

== Examples for Flatten Image Tree Source files ==

Example for a FIT-Source file with signed Linux, ramdisk and two device trees / configurations:
<syntaxhighlight lang="c">
/dts-v1/;

/ {
description = "Linux, Ramdisk and FDT for STM32MP1 DHSOM";
#address-cells = <1>;

images {
linux {
description = "Linux STM32MP1 DHSOM";
data = /incbin/("/work/dev/linux/dev-5.10.y_dhsom/arch/arm/boot/Image.gz");
type = "kernel";
os = "linux";
arch = "arm";
/* Image compressed with gzip and decrompressed by U-Boot */
compression = "gzip";
load = <0xc0008000>;
entry = <0xc0008000>;
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

ramdisk {
description = "RootFS Ramdisk DHSOM";
data = /incbin/("/work/dev/rootfs/ramdisk.cpio.gz");
type = "ramdisk";
arch = "arm";
os = "linux";
/* ramdisk.cpio compressed with gzip and decrompressed by Linux instead of by U-Boot */
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

fdt-stm32mp157c-dhcom-pdk2 {
description = "FDT STM32MP157C DHCOM Premium Developer Kit (2)";
data = /incbin/("/work/dev/linux/dev-5.10.y_dhsom/arch/arm/boot/dts/stm32mp157c-dhcom-pdk2.dtb");
type = "flat_dt";
arch = "arm";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

fdt-stm32mp157c-dhcom-picoitx {
description = "FDT STM32MP157C DHCOM PicoITX";
data = /incbin/("/work/dev/linux/dev-5.10.y_dhsom/arch/arm/boot/dts/stm32mp157c-dhcom-picoitx.dtb");
type = "flat_dt";
arch = "arm";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};
};

configurations {
default = "config-stm32mp157c-dhcom-pdk2";

config-stm32mp157c-dhcom-pdk2 {
description = "STM32MP157C DHCOM Premium Developer Kit (2)";
kernel = "linux";
ramdisk = "ramdisk";
fdt = "fdt-stm32mp157c-dhcom-pdk2";
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_CFG";
sign-images = "kernel", "ramdisk", "fdt";
};
};

config-stm32mp157c-dhcom-picoitx {
description = "STM32MP157C DHCOM PicoITX";
kernel = "linux";
ramdisk = "ramdisk";
fdt = "fdt-stm32mp157c-dhcom-picoitx";
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_CFG";
sign-images = "kernel", "ramdisk", "fdt";
};
};
};
};
</syntaxhighlight>

== 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-06-27T09:57:57Z

Jneuhauser: Program public key hash to eFuses: Add note about command preference

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

Checkout the branch <syntaxhighlight lang="shell" inline>v2022.01_dhcom_secure_boot</syntaxhighlight> from DH electronics GitHub repository with:

<syntaxhighlight lang="shell">
git clone https://github.com/dh-electronics/u-boot-stm32mp1.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 u-boot-stm32mp1 https://github.com/dh-electronics/u-boot-stm32mp1.git
git fetch u-boot-stm32mp1
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-spl-signed.stm32 || FSBL || Same as above but as signed STM32 image. Is created in [[#Sign U-Boot SPL with STM32MP_SigningTool_CLI|Sign U-Boot SPL with STM32MP_SigningTool_CLI]].
|-
| u-boot.itb || SSBL || U-Boot and Device Tree's contained in a FIT image.
|-
| u-boot-signed.itb || SSBL || Same as above but with signed configs and images.
|}

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

Load <syntaxhighlight lang="shell" inline>u-boot-spl-signed.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot-signed.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-signed.stm32
tftp ${fsbl2addr} ${serverip}:u-boot-spl-signed.stm32
tftp ${ssbl1addr} ${serverip}:u-boot-signed.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 ======

<div style="color:blue">Note: If you have any problems with the <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command use the manual procedure with the generic <syntaxhighlight lang="shell" inline>fuse</syntaxhighlight> command in the next section.</div>

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

<div style="color:blue">Note: Use this manual procedure only if you have problems with the simpler <syntaxhighlight lang="shell" inline>stm32key</syntaxhighlight> command from the previous section.</div>

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

== Examples for Flatten Image Tree Source files ==

Example for a FIT-Source file with signed Linux, ramdisk and two device trees / configurations:
<syntaxhighlight lang="c">
/dts-v1/;

/ {
description = "Linux, Ramdisk and FDT for STM32MP1 DHSOM";
#address-cells = <1>;

images {
linux {
description = "Linux STM32MP1 DHSOM";
data = /incbin/("/work/dev/linux/dev-5.10.y_dhsom/arch/arm/boot/Image.gz");
type = "kernel";
os = "linux";
arch = "arm";
/* Image compressed with gzip and decrompressed by U-Boot */
compression = "gzip";
load = <0xc0008000>;
entry = <0xc0008000>;
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

ramdisk {
description = "RootFS Ramdisk DHSOM";
data = /incbin/("/work/dev/rootfs/ramdisk.cpio.gz");
type = "ramdisk";
arch = "arm";
os = "linux";
/* ramdisk.cpio compressed with gzip and decrompressed by Linux instead of by U-Boot */
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

fdt-stm32mp157c-dhcom-pdk2 {
description = "FDT STM32MP157C DHCOM Premium Developer Kit (2)";
data = /incbin/("/work/dev/linux/dev-5.10.y_dhsom/arch/arm/boot/dts/stm32mp157c-dhcom-pdk2.dtb");
type = "flat_dt";
arch = "arm";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

fdt-stm32mp157c-dhcom-picoitx {
description = "FDT STM32MP157C DHCOM PicoITX";
data = /incbin/("/work/dev/linux/dev-5.10.y_dhsom/arch/arm/boot/dts/stm32mp157c-dhcom-picoitx.dtb");
type = "flat_dt";
arch = "arm";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};
};

configurations {
default = "config-stm32mp157c-dhcom-pdk2";

config-stm32mp157c-dhcom-pdk2 {
description = "STM32MP157C DHCOM Premium Developer Kit (2)";
kernel = "linux";
ramdisk = "ramdisk";
fdt = "fdt-stm32mp157c-dhcom-pdk2";
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_CFG";
sign-images = "kernel", "ramdisk", "fdt";
};
};

config-stm32mp157c-dhcom-picoitx {
description = "STM32MP157C DHCOM PicoITX";
kernel = "linux";
ramdisk = "ramdisk";
fdt = "fdt-stm32mp157c-dhcom-picoitx";
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_CFG";
sign-images = "kernel", "ramdisk", "fdt";
};
};
};
};
</syntaxhighlight>

== 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-06-27T09:08:10Z

Jneuhauser: Add FIT-Source examples section with a single example

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

Checkout the branch <syntaxhighlight lang="shell" inline>v2022.01_dhcom_secure_boot</syntaxhighlight> from DH electronics GitHub repository with:

<syntaxhighlight lang="shell">
git clone https://github.com/dh-electronics/u-boot-stm32mp1.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 u-boot-stm32mp1 https://github.com/dh-electronics/u-boot-stm32mp1.git
git fetch u-boot-stm32mp1
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-spl-signed.stm32 || FSBL || Same as above but as signed STM32 image. Is created in [[#Sign U-Boot SPL with STM32MP_SigningTool_CLI|Sign U-Boot SPL with STM32MP_SigningTool_CLI]].
|-
| u-boot.itb || SSBL || U-Boot and Device Tree's contained in a FIT image.
|-
| u-boot-signed.itb || SSBL || Same as above but with signed configs and images.
|}

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

Load <syntaxhighlight lang="shell" inline>u-boot-spl-signed.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot-signed.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-signed.stm32
tftp ${fsbl2addr} ${serverip}:u-boot-spl-signed.stm32
tftp ${ssbl1addr} ${serverip}:u-boot-signed.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" />

== Examples for Flatten Image Tree Source files ==

Example for a FIT-Source file with signed Linux, ramdisk and two device trees / configurations:
<syntaxhighlight lang="c">
/dts-v1/;

/ {
description = "Linux, Ramdisk and FDT for STM32MP1 DHSOM";
#address-cells = <1>;

images {
linux {
description = "Linux STM32MP1 DHSOM";
data = /incbin/("/work/dev/linux/dev-5.10.y_dhsom/arch/arm/boot/Image.gz");
type = "kernel";
os = "linux";
arch = "arm";
/* Image compressed with gzip and decrompressed by U-Boot */
compression = "gzip";
load = <0xc0008000>;
entry = <0xc0008000>;
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

ramdisk {
description = "RootFS Ramdisk DHSOM";
data = /incbin/("/work/dev/rootfs/ramdisk.cpio.gz");
type = "ramdisk";
arch = "arm";
os = "linux";
/* ramdisk.cpio compressed with gzip and decrompressed by Linux instead of by U-Boot */
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

fdt-stm32mp157c-dhcom-pdk2 {
description = "FDT STM32MP157C DHCOM Premium Developer Kit (2)";
data = /incbin/("/work/dev/linux/dev-5.10.y_dhsom/arch/arm/boot/dts/stm32mp157c-dhcom-pdk2.dtb");
type = "flat_dt";
arch = "arm";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};

fdt-stm32mp157c-dhcom-picoitx {
description = "FDT STM32MP157C DHCOM PicoITX";
data = /incbin/("/work/dev/linux/dev-5.10.y_dhsom/arch/arm/boot/dts/stm32mp157c-dhcom-picoitx.dtb");
type = "flat_dt";
arch = "arm";
compression = "none";
hash-1 {
algo = "sha256";
};
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_IMG";
};
};
};

configurations {
default = "config-stm32mp157c-dhcom-pdk2";

config-stm32mp157c-dhcom-pdk2 {
description = "STM32MP157C DHCOM Premium Developer Kit (2)";
kernel = "linux";
ramdisk = "ramdisk";
fdt = "fdt-stm32mp157c-dhcom-pdk2";
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_CFG";
sign-images = "kernel", "ramdisk", "fdt";
};
};

config-stm32mp157c-dhcom-picoitx {
description = "STM32MP157C DHCOM PicoITX";
kernel = "linux";
ramdisk = "ramdisk";
fdt = "fdt-stm32mp157c-dhcom-picoitx";
signature-1 {
algo = "sha256,KEY_ALGO";
key-name-hint = "KEY_NAME_SSBL_CFG";
sign-images = "kernel", "ramdisk", "fdt";
};
};
};
};
</syntaxhighlight>

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

U-Boot recovery for STM32MP1 DHSOM

2022-04-14T09:51:53Z

Jneuhauser: Created page with "To recover a corrupted U-Boot on a STM32MP1-based DHCOM, we can use the default fallback boot source DFU via serial link or USB or the SD card boot mode to temporarily boot U-..."

To recover a corrupted U-Boot on a STM32MP1-based DHCOM, we can use the default fallback boot source DFU via serial link or USB or the SD card boot mode to temporarily boot U-Boot SPL and U-Boot.
From this U-Boot shell we can write both bootloader images from the SD card to the boot flash.

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

== Requirements ==
=== Software ===
* Linux host computer ([[Virtual Machine for Application Development]] is used in this guide)
* [https://source.denx.de/u-boot/u-boot/-/tree/v2022.04 U-Boot 2022.04] for your board (download and build instructions below)
* [https://packages.debian.org/stable/dfu-util dfu-util] (for DFU boot mode)

=== Hardware ===
* STM32MP1 based DHCOM
* DHCOM Premium Developer Kit Baseboard (or Baseboards with OTG ports)
* USB cable for OTG port (Mini USB for PDK2, USB-C for PDK3) (for DFU boot mode)
* SD card (for SD card boot mode)

== Preparation ==
This installation was made on the [[Virtual Machine for Application Development]].
All console expressions refer to this Debian system, but any other debian based system should also work.

=== Install dfu-util (debian) ===
<syntaxhighlight lang="shell">
apt-get install dfu-util
</syntaxhighlight>
<syntaxhighlight lang="console">
</syntaxhighlight>

=== Download/Build U-Boot SPL and U-Boot binaries ===

==== Download prebuilt binaries ====

[[media:AACQ30W-7l-Zi_Zutu0Zv-Zua|Dropbox: U-Boot_recovery_for_STM32MP1_DHSOM_via_DFU]] ([https://source.denx.de/u-boot/u-boot/-/tree/v2022.04 source])

<syntaxhighlight lang="shell">
curl -LsS https://www.dropbox.com/sh/os9so01tivajkxs/AACQ30W-7l-Zi_Zutu0Zv-Zua > recovery_binaryies.zip
unzip recovery_binaryies.zip
</syntaxhighlight>
<syntaxhighlight lang="console">
Archive: recovery_binaryies.zip
warning: stripped absolute path spec from /
mapname: conversion of failed
creating: U-Boot_v2022.04_mainline/
creating: U-Boot_v2022.04_mainline/av96/
creating: U-Boot_v2022.04_mainline/pdk2/
creating: U-Boot_v2022.04_mainline/drc02/
creating: U-Boot_v2022.04_mainline/picoitx/
extracting: U-Boot_v2022.04_mainline/av96/u-boot.itb
extracting: U-Boot_v2022.04_mainline/pdk2/u-boot.itb
extracting: U-Boot_v2022.04_mainline/drc02/u-boot.itb
extracting: U-Boot_v2022.04_mainline/picoitx/u-boot.itb
extracting: U-Boot_v2022.04_mainline/av96/u-boot-spl.stm32
extracting: U-Boot_v2022.04_mainline/pdk2/u-boot-spl.stm32
extracting: U-Boot_v2022.04_mainline/drc02/u-boot-spl.stm32
extracting: U-Boot_v2022.04_mainline/picoitx/u-boot-spl.stm32
</syntaxhighlight>

==== Build binaries from source ====

Clone U-Boot mainline source code for release v2022.04:
<syntaxhighlight lang="shell">
UBOOT_SRC=/work/dev/u-boot_v2022.04
mkdir -p $UBOOT_SRC
git clone --branch v2022.04 --depth 1 https://source.denx.de/u-boot/u-boot.git $UBOOT_SRC
cd $UBOOT_SRC
</syntaxhighlight>

Available U-Boot defconfigs for STM32MP1 based DHSOM devices with default device tree in bold:
* '''stm32mp15_dhcom_basic_defconfig''' ('''pdk2''', picoitx, drc02)
* '''stm32mp15_dhcor_basic_defconfig''' ('''avenger96''')
<syntaxhighlight lang="shell">
mkdir -p /work/dev/u-boot
git clone https://source.denx.de/u-boot/u-boot.git -b v2022.04 /work/dev/u-boot
cd /work/dev/u-boot
ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- make stm32mp15_dhcom_basic_defconfig
</syntaxhighlight>

Change default device tree (Example for: stm32mp15xx-dhcom-picoitx):
<syntaxhighlight lang="shell">
sed -iE 's/(stm32mp15xx-dhcom-pdk2|stm32mp157a-dhcor-avenger96)/stm32mp15xx-dhcom-picoitx/' .config
</syntaxhighlight>

Build linux binaries with all available cores:
<syntaxhighlight lang="shell">
ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- make -j$(nproc)
</syntaxhighlight>
<syntaxhighlight lang="console">
...
SHIPPED dts/dt.dtb
CAT u-boot-dtb.bin
MKIMAGE u-boot.img
COPY u-boot.dtb
MKIMAGE u-boot-dtb.img
MKIMAGE u-boot.itb
...
LD spl/u-boot-spl
OBJCOPY spl/u-boot-spl-nodtb.bin
SYM spl/u-boot-spl.sym
CAT spl/u-boot-spl-dtb.bin
COPY spl/u-boot-spl.bin
BINMAN all
</syntaxhighlight>

Check that the required binaries have been created and are of the appropriate size:
<syntaxhighlight lang="shell">
ls -l u-boot.itb u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-rw-r--r-- 1 devel devel 819720 Apr 11 17:03 u-boot.itb
-rw-r--r-- 1 devel devel 124288 Apr 11 17:03 u-boot-spl.stm32
</syntaxhighlight>

== U-Boot booting via DFU ==

To boot U-Boot SPL and U-Boot via DFU boot mode, you must first check if you have a DFU device connected, then load U-Boot SPL into the SRAM of your STM32MP1 and wait until the DRAM is initialized.
Then load U-Boot in the DRAM of your STM32MP1 and continue the boot process using the shown key combination.

=== Check for available DFU device ===

(Re-)Connect the USB cable with your host computer and the OTG port of your baseboard and check the kernel log for a available DFU device:
<syntaxhighlight lang="shell">
sudo dmesg
</syntaxhighlight>
<syntaxhighlight lang="console" highlight="4">
...
usb 2-2: New USB device found, idVendor=0483, idProduct=df11, bcdDevice= 2.00
usb 2-2: New USB device strings: Mfr=1, Product=2, SerialNumber=3
usb 2-2: Product: DFU in HS Mode @Device ID /0x500, @Revision ID /0x0000
usb 2-2: Manufacturer: STMicroelectronics
usb 2-2: SerialNumber: 0040001D3130510439373430
</syntaxhighlight>

=== Download of U-Boot SPL with <code>dfu-util</code> ===

Download of U-Boot SPL with dfu-util to connected device:
<syntaxhighlight lang="shell">
dfu-util -a 1 -D u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
dfu-util 0.9

Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
Copyright 2010-2016 Tormod Volden and Stefan Schmidt
This program is Free Software and has ABSOLUTELY NO WARRANTY
Please report bugs to http://sourceforge.net/p/dfu-util/tickets/

dfu-util: Invalid DFU suffix signature
dfu-util: A valid DFU suffix will be required in a future dfu-util release!!!
Opening DFU capable USB device...
ID 0483:df11
Run-time device DFU version 0110
Claiming USB DFU Interface...
Setting Alternate Setting #1 ...
Determining device status: state = dfuIDLE, status = 0
dfuIDLE, continuing
DFU mode device DFU version 0110
Device returned transfer size 1024
Copying data from PC to DFU device
Download [=========================] 100% 160911 bytes
Download done.
state(7) = dfuMANIFEST, status(0) = No error condition is present
state(2) = dfuIDLE, status(0) = No error condition is present
Done!
</syntaxhighlight>

Output of the serial console:
<syntaxhighlight lang="console">
U-Boot SPL 2022.04 (Apr 05 2022 - 08:27:30 +0200)
Model: STMicroelectronics STM32MP15xx DHCOM Premium Developer Kit (2)
Code: SoM:rev=1,ddr3=3 Board:rev=0
RAM: DDR3L 32bits 2x4Gb 533MHz
Trying to boot from DFU
</syntaxhighlight>

=== Download of U-Boot with <code>dfu-util</code> ===

Download of U-Boot with dfu-util to connected device:
<syntaxhighlight lang="shell">
dfu-util -a 0 -D u-boot.itb
</syntaxhighlight>
<syntaxhighlight lang="console">
dfu-util 0.9

Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
Copyright 2010-2016 Tormod Volden and Stefan Schmidt
This program is Free Software and has ABSOLUTELY NO WARRANTY
Please report bugs to http://sourceforge.net/p/dfu-util/tickets/

dfu-util: Invalid DFU suffix signature
dfu-util: A valid DFU suffix will be required in a future dfu-util release!!!
Opening DFU capable USB device...
ID 0483:df11
Run-time device DFU version 0110
Claiming USB DFU Interface...
Setting Alternate Setting #0 ...
Determining device status: state = dfuIDLE, status = 0
dfuIDLE, continuing
DFU mode device DFU version 0110
Device returned transfer size 4096
Copying data from PC to DFU device
Download [=========================] 100% 819232 bytes
Download done.
state(7) = dfuMANIFEST, status(0) = No error condition is present
state(2) = dfuIDLE, status(0) = No error condition is present
Done!
</syntaxhighlight>

Output of the serial console:
<syntaxhighlight lang="console">
#DOWNLOAD ... OK
Ctrl+C to exit ...
</syntaxhighlight>

Output of the serial console after pressing '''Ctrl+C''':
<syntaxhighlight lang="console">
U-Boot 2022.04 (Apr 05 2022 - 08:27:30 +0200)

CPU: STM32MP157CAA Rev.Z
Model: STMicroelectronics STM32MP15xx DHCOM Premium Developer Kit (2)
Board: stm32mp1 in basic mode (dh,stm32mp15xx-dhcom-pdk2)
DRAM: 1 GiB
Clocks:
- MPU : 650 MHz
- MCU : 208.878 MHz
- AXI : 266.500 MHz
- PER : 24 MHz
- DDR : 533 MHz
Core: 255 devices, 31 uclasses, devicetree: separate
MMC: STM32 SD/MMC: 2, STM32 SD/MMC: 0, STM32 SD/MMC: 1
Loading Environment from SPIFlash... SF: Detected w25q16cl with page size 256 Bytes, erase size 4 KiB, total 2 MiB
OK
In: serial
Out: serial
Err: serial
Net: eth0: ethernet@5800a000, eth1: ks8851mll@64000000
Hit any key to stop autoboot: 0
</syntaxhighlight>

== U-Boot booting via SD card ==

Set the disk:
<syntaxhighlight lang="shell">
STM32_DISK=/dev/sdc
</syntaxhighlight>

=== Partition a SD card ===

Create partition table and partitions:
<syntaxhighlight lang="shell">
parted --script -- ${STM32_DISK} \
mktable gpt \
mkpart fsbl1 1MiB 1.25MiB \
mkpart fsbl2 2MiB 2.25MiB \
mkpart ssbl 3MiB 5MiB \
mkpart rootfs ext4 5MiB 100% \
set 4 legacy_boot on \
unit MiB \
print
</syntaxhighlight>
<syntaxhighlight lang="console">
Model: Generic STORAGE DEVICE (scsi)
Disk /dev/sdc: 954MiB
Sector size (logical/physical): 512B/512B
Partition Table: gpt
Disk Flags:

Number Start End Size File system Name Flags
1 1.00MiB 1.25MiB 0.25MiB fsbl1
2 2.00MiB 2.25MiB 0.25MiB fsbl2
3 3.00MiB 5.00MiB 2.00MiB ssbl
4 5.00MiB 953MiB 948MiB ext4 rootfs legacy_boot
</syntaxhighlight>

Redetect partitions:
<syntaxhighlight lang="shell">
partprobe ${STM32_DISK}
</syntaxhighlight>

=== Create file system on partition 4 ===

Create filesystem on partition 4:
<syntaxhighlight lang="shell">
mkfs.ext4 -m 0 -L rootfs ${STM32_DISK}4
</syntaxhighlight>
<syntaxhighlight lang="console">
mke2fs 1.46.2 (28-Feb-2021)
Creating filesystem with 242688 4k blocks and 60672 inodes
Filesystem UUID: bda8eff7-aa5a-4ed8-aa53-f22e3a1e3203
Superblock backups stored on blocks:
32768, 98304, 163840, 229376

Allocating group tables: done
Writing inode tables: done
Creating journal (4096 blocks): done
Writing superblocks and filesystem accounting information: done
</syntaxhighlight>

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

Write u-boot spl and u-boot to boot partitions 1, 2 and 3:
<syntaxhighlight lang="shell">
dd if=u-boot-spl.stm32 of=${STM32_DISK}1
dd if=u-boot-spl.stm32 of=${STM32_DISK}2
dd if=u-boot.itb of=${STM32_DISK}3
</syntaxhighlight>
<syntaxhighlight lang="console">
314+1 records in
314+1 records out
160911 bytes (161 kB, 157 KiB) copied, 0.274919 s, 585 kB/s
314+1 records in
314+1 records out
160911 bytes (161 kB, 157 KiB) copied, 0.280309 s, 574 kB/s
1600+1 records in
1600+1 records out
819232 bytes (819 kB, 800 KiB) copied, 0.862246 s, 950 kB/s
</syntaxhighlight>

Copy u-boot spl and u-boot to directory <code>boot</code> on rootfs partition 4:
<syntaxhighlight lang="shell">
mkdir -p rootfs
mount ${STM32_DISK}4 rootfs
mkdir -p rootfs/boot
cp u-boot-spl.stm32 u-boot.itb rootfs/boot/
umount rootfs && rmdir rootfs
</syntaxhighlight>

=== Boot from SD card ===

# Hold the button for SD card boot mode on the SODIMM-200 module (DHCOM) below the eMMC chip.
#:[[File:DHCOR_i.MX6ULL_SDP-Boot.jpg|400px]]
# Reset the device. To reset the device, press the reset button on the baseboard or unplug and plug in the power plug.
# Release the button for SD card boot mode

== U-Boot flashing via SD card ==

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

Follow the instructions in [[#U-Boot booting via SD card|U-Boot booting via SD card]] to prepare an SD card with a file system on partition 4 that contains the required <code>u-boot-spl.stm32</code> and <code>u-boot.itb</code> binaries.

=== Write U-Boot SPL and U-Boot to SPI-NOR-Flash ===

# Start U-Boot by [[#U-Boot booting via DFU|U-Boot booting via DFU]] or by [[#Boot from SD card|Boot from SD card]]
# Attach prepared SD card to the on module SD card slot
# Program U-Boot SPL and U-Boot by the script <code>update_sf</code> stored in the U-Boot environment.
#:<syntaxhighlight lang="shell">
STM32MP> run update_sf
</syntaxhighlight>
#:<syntaxhighlight lang="console">
160911 bytes read in 80 ms (1.9 MiB/s)
819232 bytes read in 115 ms (6.8 MiB/s)
SF: Detected w25q16cl with page size 256 Bytes, erase size 4 KiB, total 2 MiB
SF: 2097152 bytes @ 0x0 Erased: OK
device 0 offset 0x0, size 0x2748f
160911 bytes written, 0 bytes skipped in 1.664s, speed 98903 B/s
device 0 offset 0x40000, size 0x2748f
160911 bytes written, 0 bytes skipped in 1.626s, speed 101211 B/s
device 0 offset 0x80000, size 0xc8020
815136 bytes written, 4096 bytes skipped in 8.379s, speed 100094 B/s
</syntaxhighlight>

U-Boot recovery for STM32MP1 DHSOM via DFU

2022-04-14T09:50:37Z

Jneuhauser: /* Write U-Boot SPL and U-Boot to the SD card */

To recover a corrupted U-Boot on a STM32MP1-based DHCOM, we can use the default fallback boot source DFU via serial link or USB to temporarily boot U-Boot SPL and U-Boot.
From this U-Boot shell we can write both bootloader images from the SD card to the boot flash.

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

== Requirements ==
=== Software ===
* Linux host computer ([[Virtual Machine for Application Development]] is used in this guide)
* [https://source.denx.de/u-boot/u-boot/-/tree/v2022.04 U-Boot 2022.04] for your board (download and build instructions below)
* [https://packages.debian.org/stable/dfu-util dfu-util] (for DFU boot mode)

=== Hardware ===
* STM32MP1 based DHCOM
* DHCOM Premium Developer Kit Baseboard (or Baseboards with OTG ports)
* USB cable for OTG port (Mini USB for PDK2, USB-C for PDK3) (for DFU boot mode)
* SD card (for SD card boot mode)

== Preparation ==
This installation was made on the [[Virtual Machine for Application Development]].
All console expressions refer to this Debian system, but any other debian based system should also work.

=== Install dfu-util (debian) ===
<syntaxhighlight lang="shell">
apt-get install dfu-util
</syntaxhighlight>
<syntaxhighlight lang="console">
</syntaxhighlight>

=== Download/Build U-Boot SPL and U-Boot binaries ===

==== Download prebuilt binaries ====

[[media:AACQ30W-7l-Zi_Zutu0Zv-Zua|Dropbox: U-Boot_recovery_for_STM32MP1_DHSOM_via_DFU]] ([https://source.denx.de/u-boot/u-boot/-/tree/v2022.04 source])

<syntaxhighlight lang="shell">
curl -LsS https://www.dropbox.com/sh/os9so01tivajkxs/AACQ30W-7l-Zi_Zutu0Zv-Zua > recovery_binaryies.zip
unzip recovery_binaryies.zip
</syntaxhighlight>
<syntaxhighlight lang="console">
Archive: recovery_binaryies.zip
warning: stripped absolute path spec from /
mapname: conversion of failed
creating: U-Boot_v2022.04_mainline/
creating: U-Boot_v2022.04_mainline/av96/
creating: U-Boot_v2022.04_mainline/pdk2/
creating: U-Boot_v2022.04_mainline/drc02/
creating: U-Boot_v2022.04_mainline/picoitx/
extracting: U-Boot_v2022.04_mainline/av96/u-boot.itb
extracting: U-Boot_v2022.04_mainline/pdk2/u-boot.itb
extracting: U-Boot_v2022.04_mainline/drc02/u-boot.itb
extracting: U-Boot_v2022.04_mainline/picoitx/u-boot.itb
extracting: U-Boot_v2022.04_mainline/av96/u-boot-spl.stm32
extracting: U-Boot_v2022.04_mainline/pdk2/u-boot-spl.stm32
extracting: U-Boot_v2022.04_mainline/drc02/u-boot-spl.stm32
extracting: U-Boot_v2022.04_mainline/picoitx/u-boot-spl.stm32
</syntaxhighlight>

==== Build binaries from source ====

Clone U-Boot mainline source code for release v2022.04:
<syntaxhighlight lang="shell">
UBOOT_SRC=/work/dev/u-boot_v2022.04
mkdir -p $UBOOT_SRC
git clone --branch v2022.04 --depth 1 https://source.denx.de/u-boot/u-boot.git $UBOOT_SRC
cd $UBOOT_SRC
</syntaxhighlight>

Available U-Boot defconfigs for STM32MP1 based DHSOM devices with default device tree in bold:
* '''stm32mp15_dhcom_basic_defconfig''' ('''pdk2''', picoitx, drc02)
* '''stm32mp15_dhcor_basic_defconfig''' ('''avenger96''')
<syntaxhighlight lang="shell">
mkdir -p /work/dev/u-boot
git clone https://source.denx.de/u-boot/u-boot.git -b v2022.04 /work/dev/u-boot
cd /work/dev/u-boot
ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- make stm32mp15_dhcom_basic_defconfig
</syntaxhighlight>

Change default device tree (Example for: stm32mp15xx-dhcom-picoitx):
<syntaxhighlight lang="shell">
sed -iE 's/(stm32mp15xx-dhcom-pdk2|stm32mp157a-dhcor-avenger96)/stm32mp15xx-dhcom-picoitx/' .config
</syntaxhighlight>

Build linux binaries with all available cores:
<syntaxhighlight lang="shell">
ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- make -j$(nproc)
</syntaxhighlight>
<syntaxhighlight lang="console">
...
SHIPPED dts/dt.dtb
CAT u-boot-dtb.bin
MKIMAGE u-boot.img
COPY u-boot.dtb
MKIMAGE u-boot-dtb.img
MKIMAGE u-boot.itb
...
LD spl/u-boot-spl
OBJCOPY spl/u-boot-spl-nodtb.bin
SYM spl/u-boot-spl.sym
CAT spl/u-boot-spl-dtb.bin
COPY spl/u-boot-spl.bin
BINMAN all
</syntaxhighlight>

Check that the required binaries have been created and are of the appropriate size:
<syntaxhighlight lang="shell">
ls -l u-boot.itb u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-rw-r--r-- 1 devel devel 819720 Apr 11 17:03 u-boot.itb
-rw-r--r-- 1 devel devel 124288 Apr 11 17:03 u-boot-spl.stm32
</syntaxhighlight>

== U-Boot booting via DFU ==

To boot U-Boot SPL and U-Boot via DFU boot mode, you must first check if you have a DFU device connected, then load U-Boot SPL into the SRAM of your STM32MP1 and wait until the DRAM is initialized.
Then load U-Boot in the DRAM of your STM32MP1 and continue the boot process using the shown key combination.

=== Check for available DFU device ===

(Re-)Connect the USB cable with your host computer and the OTG port of your baseboard and check the kernel log for a available DFU device:
<syntaxhighlight lang="shell">
sudo dmesg
</syntaxhighlight>
<syntaxhighlight lang="console" highlight="4">
...
usb 2-2: New USB device found, idVendor=0483, idProduct=df11, bcdDevice= 2.00
usb 2-2: New USB device strings: Mfr=1, Product=2, SerialNumber=3
usb 2-2: Product: DFU in HS Mode @Device ID /0x500, @Revision ID /0x0000
usb 2-2: Manufacturer: STMicroelectronics
usb 2-2: SerialNumber: 0040001D3130510439373430
</syntaxhighlight>

=== Download of U-Boot SPL with <code>dfu-util</code> ===

Download of U-Boot SPL with dfu-util to connected device:
<syntaxhighlight lang="shell">
dfu-util -a 1 -D u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
dfu-util 0.9

Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
Copyright 2010-2016 Tormod Volden and Stefan Schmidt
This program is Free Software and has ABSOLUTELY NO WARRANTY
Please report bugs to http://sourceforge.net/p/dfu-util/tickets/

dfu-util: Invalid DFU suffix signature
dfu-util: A valid DFU suffix will be required in a future dfu-util release!!!
Opening DFU capable USB device...
ID 0483:df11
Run-time device DFU version 0110
Claiming USB DFU Interface...
Setting Alternate Setting #1 ...
Determining device status: state = dfuIDLE, status = 0
dfuIDLE, continuing
DFU mode device DFU version 0110
Device returned transfer size 1024
Copying data from PC to DFU device
Download [=========================] 100% 160911 bytes
Download done.
state(7) = dfuMANIFEST, status(0) = No error condition is present
state(2) = dfuIDLE, status(0) = No error condition is present
Done!
</syntaxhighlight>

Output of the serial console:
<syntaxhighlight lang="console">
U-Boot SPL 2022.04 (Apr 05 2022 - 08:27:30 +0200)
Model: STMicroelectronics STM32MP15xx DHCOM Premium Developer Kit (2)
Code: SoM:rev=1,ddr3=3 Board:rev=0
RAM: DDR3L 32bits 2x4Gb 533MHz
Trying to boot from DFU
</syntaxhighlight>

=== Download of U-Boot with <code>dfu-util</code> ===

Download of U-Boot with dfu-util to connected device:
<syntaxhighlight lang="shell">
dfu-util -a 0 -D u-boot.itb
</syntaxhighlight>
<syntaxhighlight lang="console">
dfu-util 0.9

Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
Copyright 2010-2016 Tormod Volden and Stefan Schmidt
This program is Free Software and has ABSOLUTELY NO WARRANTY
Please report bugs to http://sourceforge.net/p/dfu-util/tickets/

dfu-util: Invalid DFU suffix signature
dfu-util: A valid DFU suffix will be required in a future dfu-util release!!!
Opening DFU capable USB device...
ID 0483:df11
Run-time device DFU version 0110
Claiming USB DFU Interface...
Setting Alternate Setting #0 ...
Determining device status: state = dfuIDLE, status = 0
dfuIDLE, continuing
DFU mode device DFU version 0110
Device returned transfer size 4096
Copying data from PC to DFU device
Download [=========================] 100% 819232 bytes
Download done.
state(7) = dfuMANIFEST, status(0) = No error condition is present
state(2) = dfuIDLE, status(0) = No error condition is present
Done!
</syntaxhighlight>

Output of the serial console:
<syntaxhighlight lang="console">
#DOWNLOAD ... OK
Ctrl+C to exit ...
</syntaxhighlight>

Output of the serial console after pressing '''Ctrl+C''':
<syntaxhighlight lang="console">
U-Boot 2022.04 (Apr 05 2022 - 08:27:30 +0200)

CPU: STM32MP157CAA Rev.Z
Model: STMicroelectronics STM32MP15xx DHCOM Premium Developer Kit (2)
Board: stm32mp1 in basic mode (dh,stm32mp15xx-dhcom-pdk2)
DRAM: 1 GiB
Clocks:
- MPU : 650 MHz
- MCU : 208.878 MHz
- AXI : 266.500 MHz
- PER : 24 MHz
- DDR : 533 MHz
Core: 255 devices, 31 uclasses, devicetree: separate
MMC: STM32 SD/MMC: 2, STM32 SD/MMC: 0, STM32 SD/MMC: 1
Loading Environment from SPIFlash... SF: Detected w25q16cl with page size 256 Bytes, erase size 4 KiB, total 2 MiB
OK
In: serial
Out: serial
Err: serial
Net: eth0: ethernet@5800a000, eth1: ks8851mll@64000000
Hit any key to stop autoboot: 0
</syntaxhighlight>

== U-Boot booting via SD card ==

Set the disk:
<syntaxhighlight lang="shell">
STM32_DISK=/dev/sdc
</syntaxhighlight>

=== Partition a SD card ===

Create partition table and partitions:
<syntaxhighlight lang="shell">
parted --script -- ${STM32_DISK} \
mktable gpt \
mkpart fsbl1 1MiB 1.25MiB \
mkpart fsbl2 2MiB 2.25MiB \
mkpart ssbl 3MiB 5MiB \
mkpart rootfs ext4 5MiB 100% \
set 4 legacy_boot on \
unit MiB \
print
</syntaxhighlight>
<syntaxhighlight lang="console">
Model: Generic STORAGE DEVICE (scsi)
Disk /dev/sdc: 954MiB
Sector size (logical/physical): 512B/512B
Partition Table: gpt
Disk Flags:

Number Start End Size File system Name Flags
1 1.00MiB 1.25MiB 0.25MiB fsbl1
2 2.00MiB 2.25MiB 0.25MiB fsbl2
3 3.00MiB 5.00MiB 2.00MiB ssbl
4 5.00MiB 953MiB 948MiB ext4 rootfs legacy_boot
</syntaxhighlight>

Redetect partitions:
<syntaxhighlight lang="shell">
partprobe ${STM32_DISK}
</syntaxhighlight>

=== Create file system on partition 4 ===

Create filesystem on partition 4:
<syntaxhighlight lang="shell">
mkfs.ext4 -m 0 -L rootfs ${STM32_DISK}4
</syntaxhighlight>
<syntaxhighlight lang="console">
mke2fs 1.46.2 (28-Feb-2021)
Creating filesystem with 242688 4k blocks and 60672 inodes
Filesystem UUID: bda8eff7-aa5a-4ed8-aa53-f22e3a1e3203
Superblock backups stored on blocks:
32768, 98304, 163840, 229376

Allocating group tables: done
Writing inode tables: done
Creating journal (4096 blocks): done
Writing superblocks and filesystem accounting information: done
</syntaxhighlight>

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

Write u-boot spl and u-boot to boot partitions 1, 2 and 3:
<syntaxhighlight lang="shell">
dd if=u-boot-spl.stm32 of=${STM32_DISK}1
dd if=u-boot-spl.stm32 of=${STM32_DISK}2
dd if=u-boot.itb of=${STM32_DISK}3
</syntaxhighlight>
<syntaxhighlight lang="console">
314+1 records in
314+1 records out
160911 bytes (161 kB, 157 KiB) copied, 0.274919 s, 585 kB/s
314+1 records in
314+1 records out
160911 bytes (161 kB, 157 KiB) copied, 0.280309 s, 574 kB/s
1600+1 records in
1600+1 records out
819232 bytes (819 kB, 800 KiB) copied, 0.862246 s, 950 kB/s
</syntaxhighlight>

Copy u-boot spl and u-boot to directory <code>boot</code> on rootfs partition 4:
<syntaxhighlight lang="shell">
mkdir -p rootfs
mount ${STM32_DISK}4 rootfs
mkdir -p rootfs/boot
cp u-boot-spl.stm32 u-boot.itb rootfs/boot/
umount rootfs && rmdir rootfs
</syntaxhighlight>

=== Boot from SD card ===

# Hold the button for SD card boot mode on the SODIMM-200 module (DHCOM) below the eMMC chip.
#:[[File:DHCOR_i.MX6ULL_SDP-Boot.jpg|400px]]
# Reset the device. To reset the device, press the reset button on the baseboard or unplug and plug in the power plug.
# Release the button for SD card boot mode

== U-Boot flashing via SD card ==

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

Follow the instructions in [[#U-Boot booting via SD card|U-Boot booting via SD card]] to prepare an SD card with a file system on partition 4 that contains the required <code>u-boot-spl.stm32</code> and <code>u-boot.itb</code> binaries.

=== Write U-Boot SPL and U-Boot to SPI-NOR-Flash ===

# Start U-Boot by [[#U-Boot booting via DFU|U-Boot booting via DFU]] or by [[#Boot from SD card|Boot from SD card]]
# Attach prepared SD card to the on module SD card slot
# Program U-Boot SPL and U-Boot by the script <code>update_sf</code> stored in the U-Boot environment.
#:<syntaxhighlight lang="shell">
STM32MP> run update_sf
</syntaxhighlight>
#:<syntaxhighlight lang="console">
160911 bytes read in 80 ms (1.9 MiB/s)
819232 bytes read in 115 ms (6.8 MiB/s)
SF: Detected w25q16cl with page size 256 Bytes, erase size 4 KiB, total 2 MiB
SF: 2097152 bytes @ 0x0 Erased: OK
device 0 offset 0x0, size 0x2748f
160911 bytes written, 0 bytes skipped in 1.664s, speed 98903 B/s
device 0 offset 0x40000, size 0x2748f
160911 bytes written, 0 bytes skipped in 1.626s, speed 101211 B/s
device 0 offset 0x80000, size 0xc8020
815136 bytes written, 4096 bytes skipped in 8.379s, speed 100094 B/s
</syntaxhighlight>

U-Boot recovery for STM32MP1 DHSOM via DFU

2022-04-14T09:49:17Z

Jneuhauser:

To recover a corrupted U-Boot on a STM32MP1-based DHCOM, we can use the default fallback boot source DFU via serial link or USB to temporarily boot U-Boot SPL and U-Boot.
From this U-Boot shell we can write both bootloader images from the SD card to the boot flash.

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

== Requirements ==
=== Software ===
* Linux host computer ([[Virtual Machine for Application Development]] is used in this guide)
* [https://source.denx.de/u-boot/u-boot/-/tree/v2022.04 U-Boot 2022.04] for your board (download and build instructions below)
* [https://packages.debian.org/stable/dfu-util dfu-util] (for DFU boot mode)

=== Hardware ===
* STM32MP1 based DHCOM
* DHCOM Premium Developer Kit Baseboard (or Baseboards with OTG ports)
* USB cable for OTG port (Mini USB for PDK2, USB-C for PDK3) (for DFU boot mode)
* SD card (for SD card boot mode)

== Preparation ==
This installation was made on the [[Virtual Machine for Application Development]].
All console expressions refer to this Debian system, but any other debian based system should also work.

=== Install dfu-util (debian) ===
<syntaxhighlight lang="shell">
apt-get install dfu-util
</syntaxhighlight>
<syntaxhighlight lang="console">
</syntaxhighlight>

=== Download/Build U-Boot SPL and U-Boot binaries ===

==== Download prebuilt binaries ====

[[media:AACQ30W-7l-Zi_Zutu0Zv-Zua|Dropbox: U-Boot_recovery_for_STM32MP1_DHSOM_via_DFU]] ([https://source.denx.de/u-boot/u-boot/-/tree/v2022.04 source])

<syntaxhighlight lang="shell">
curl -LsS https://www.dropbox.com/sh/os9so01tivajkxs/AACQ30W-7l-Zi_Zutu0Zv-Zua > recovery_binaryies.zip
unzip recovery_binaryies.zip
</syntaxhighlight>
<syntaxhighlight lang="console">
Archive: recovery_binaryies.zip
warning: stripped absolute path spec from /
mapname: conversion of failed
creating: U-Boot_v2022.04_mainline/
creating: U-Boot_v2022.04_mainline/av96/
creating: U-Boot_v2022.04_mainline/pdk2/
creating: U-Boot_v2022.04_mainline/drc02/
creating: U-Boot_v2022.04_mainline/picoitx/
extracting: U-Boot_v2022.04_mainline/av96/u-boot.itb
extracting: U-Boot_v2022.04_mainline/pdk2/u-boot.itb
extracting: U-Boot_v2022.04_mainline/drc02/u-boot.itb
extracting: U-Boot_v2022.04_mainline/picoitx/u-boot.itb
extracting: U-Boot_v2022.04_mainline/av96/u-boot-spl.stm32
extracting: U-Boot_v2022.04_mainline/pdk2/u-boot-spl.stm32
extracting: U-Boot_v2022.04_mainline/drc02/u-boot-spl.stm32
extracting: U-Boot_v2022.04_mainline/picoitx/u-boot-spl.stm32
</syntaxhighlight>

==== Build binaries from source ====

Clone U-Boot mainline source code for release v2022.04:
<syntaxhighlight lang="shell">
UBOOT_SRC=/work/dev/u-boot_v2022.04
mkdir -p $UBOOT_SRC
git clone --branch v2022.04 --depth 1 https://source.denx.de/u-boot/u-boot.git $UBOOT_SRC
cd $UBOOT_SRC
</syntaxhighlight>

Available U-Boot defconfigs for STM32MP1 based DHSOM devices with default device tree in bold:
* '''stm32mp15_dhcom_basic_defconfig''' ('''pdk2''', picoitx, drc02)
* '''stm32mp15_dhcor_basic_defconfig''' ('''avenger96''')
<syntaxhighlight lang="shell">
mkdir -p /work/dev/u-boot
git clone https://source.denx.de/u-boot/u-boot.git -b v2022.04 /work/dev/u-boot
cd /work/dev/u-boot
ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- make stm32mp15_dhcom_basic_defconfig
</syntaxhighlight>

Change default device tree (Example for: stm32mp15xx-dhcom-picoitx):
<syntaxhighlight lang="shell">
sed -iE 's/(stm32mp15xx-dhcom-pdk2|stm32mp157a-dhcor-avenger96)/stm32mp15xx-dhcom-picoitx/' .config
</syntaxhighlight>

Build linux binaries with all available cores:
<syntaxhighlight lang="shell">
ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- make -j$(nproc)
</syntaxhighlight>
<syntaxhighlight lang="console">
...
SHIPPED dts/dt.dtb
CAT u-boot-dtb.bin
MKIMAGE u-boot.img
COPY u-boot.dtb
MKIMAGE u-boot-dtb.img
MKIMAGE u-boot.itb
...
LD spl/u-boot-spl
OBJCOPY spl/u-boot-spl-nodtb.bin
SYM spl/u-boot-spl.sym
CAT spl/u-boot-spl-dtb.bin
COPY spl/u-boot-spl.bin
BINMAN all
</syntaxhighlight>

Check that the required binaries have been created and are of the appropriate size:
<syntaxhighlight lang="shell">
ls -l u-boot.itb u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-rw-r--r-- 1 devel devel 819720 Apr 11 17:03 u-boot.itb
-rw-r--r-- 1 devel devel 124288 Apr 11 17:03 u-boot-spl.stm32
</syntaxhighlight>

== U-Boot booting via DFU ==

To boot U-Boot SPL and U-Boot via DFU boot mode, you must first check if you have a DFU device connected, then load U-Boot SPL into the SRAM of your STM32MP1 and wait until the DRAM is initialized.
Then load U-Boot in the DRAM of your STM32MP1 and continue the boot process using the shown key combination.

=== Check for available DFU device ===

(Re-)Connect the USB cable with your host computer and the OTG port of your baseboard and check the kernel log for a available DFU device:
<syntaxhighlight lang="shell">
sudo dmesg
</syntaxhighlight>
<syntaxhighlight lang="console" highlight="4">
...
usb 2-2: New USB device found, idVendor=0483, idProduct=df11, bcdDevice= 2.00
usb 2-2: New USB device strings: Mfr=1, Product=2, SerialNumber=3
usb 2-2: Product: DFU in HS Mode @Device ID /0x500, @Revision ID /0x0000
usb 2-2: Manufacturer: STMicroelectronics
usb 2-2: SerialNumber: 0040001D3130510439373430
</syntaxhighlight>

=== Download of U-Boot SPL with <code>dfu-util</code> ===

Download of U-Boot SPL with dfu-util to connected device:
<syntaxhighlight lang="shell">
dfu-util -a 1 -D u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
dfu-util 0.9

Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
Copyright 2010-2016 Tormod Volden and Stefan Schmidt
This program is Free Software and has ABSOLUTELY NO WARRANTY
Please report bugs to http://sourceforge.net/p/dfu-util/tickets/

dfu-util: Invalid DFU suffix signature
dfu-util: A valid DFU suffix will be required in a future dfu-util release!!!
Opening DFU capable USB device...
ID 0483:df11
Run-time device DFU version 0110
Claiming USB DFU Interface...
Setting Alternate Setting #1 ...
Determining device status: state = dfuIDLE, status = 0
dfuIDLE, continuing
DFU mode device DFU version 0110
Device returned transfer size 1024
Copying data from PC to DFU device
Download [=========================] 100% 160911 bytes
Download done.
state(7) = dfuMANIFEST, status(0) = No error condition is present
state(2) = dfuIDLE, status(0) = No error condition is present
Done!
</syntaxhighlight>

Output of the serial console:
<syntaxhighlight lang="console">
U-Boot SPL 2022.04 (Apr 05 2022 - 08:27:30 +0200)
Model: STMicroelectronics STM32MP15xx DHCOM Premium Developer Kit (2)
Code: SoM:rev=1,ddr3=3 Board:rev=0
RAM: DDR3L 32bits 2x4Gb 533MHz
Trying to boot from DFU
</syntaxhighlight>

=== Download of U-Boot with <code>dfu-util</code> ===

Download of U-Boot with dfu-util to connected device:
<syntaxhighlight lang="shell">
dfu-util -a 0 -D u-boot.itb
</syntaxhighlight>
<syntaxhighlight lang="console">
dfu-util 0.9

Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
Copyright 2010-2016 Tormod Volden and Stefan Schmidt
This program is Free Software and has ABSOLUTELY NO WARRANTY
Please report bugs to http://sourceforge.net/p/dfu-util/tickets/

dfu-util: Invalid DFU suffix signature
dfu-util: A valid DFU suffix will be required in a future dfu-util release!!!
Opening DFU capable USB device...
ID 0483:df11
Run-time device DFU version 0110
Claiming USB DFU Interface...
Setting Alternate Setting #0 ...
Determining device status: state = dfuIDLE, status = 0
dfuIDLE, continuing
DFU mode device DFU version 0110
Device returned transfer size 4096
Copying data from PC to DFU device
Download [=========================] 100% 819232 bytes
Download done.
state(7) = dfuMANIFEST, status(0) = No error condition is present
state(2) = dfuIDLE, status(0) = No error condition is present
Done!
</syntaxhighlight>

Output of the serial console:
<syntaxhighlight lang="console">
#DOWNLOAD ... OK
Ctrl+C to exit ...
</syntaxhighlight>

Output of the serial console after pressing '''Ctrl+C''':
<syntaxhighlight lang="console">
U-Boot 2022.04 (Apr 05 2022 - 08:27:30 +0200)

CPU: STM32MP157CAA Rev.Z
Model: STMicroelectronics STM32MP15xx DHCOM Premium Developer Kit (2)
Board: stm32mp1 in basic mode (dh,stm32mp15xx-dhcom-pdk2)
DRAM: 1 GiB
Clocks:
- MPU : 650 MHz
- MCU : 208.878 MHz
- AXI : 266.500 MHz
- PER : 24 MHz
- DDR : 533 MHz
Core: 255 devices, 31 uclasses, devicetree: separate
MMC: STM32 SD/MMC: 2, STM32 SD/MMC: 0, STM32 SD/MMC: 1
Loading Environment from SPIFlash... SF: Detected w25q16cl with page size 256 Bytes, erase size 4 KiB, total 2 MiB
OK
In: serial
Out: serial
Err: serial
Net: eth0: ethernet@5800a000, eth1: ks8851mll@64000000
Hit any key to stop autoboot: 0
</syntaxhighlight>

== U-Boot booting via SD card ==

Set the disk:
<syntaxhighlight lang="shell">
STM32_DISK=/dev/sdc
</syntaxhighlight>

=== Partition a SD card ===

Create partition table and partitions:
<syntaxhighlight lang="shell">
parted --script -- ${STM32_DISK} \
mktable gpt \
mkpart fsbl1 1MiB 1.25MiB \
mkpart fsbl2 2MiB 2.25MiB \
mkpart ssbl 3MiB 5MiB \
mkpart rootfs ext4 5MiB 100% \
set 4 legacy_boot on \
unit MiB \
print
</syntaxhighlight>
<syntaxhighlight lang="console">
Model: Generic STORAGE DEVICE (scsi)
Disk /dev/sdc: 954MiB
Sector size (logical/physical): 512B/512B
Partition Table: gpt
Disk Flags:

Number Start End Size File system Name Flags
1 1.00MiB 1.25MiB 0.25MiB fsbl1
2 2.00MiB 2.25MiB 0.25MiB fsbl2
3 3.00MiB 5.00MiB 2.00MiB ssbl
4 5.00MiB 953MiB 948MiB ext4 rootfs legacy_boot
</syntaxhighlight>

Redetect partitions:
<syntaxhighlight lang="shell">
partprobe ${STM32_DISK}
</syntaxhighlight>

=== Create file system on partition 4 ===

Create filesystem on partition 4:
<syntaxhighlight lang="shell">
mkfs.ext4 -m 0 -L rootfs ${STM32_DISK}4
</syntaxhighlight>
<syntaxhighlight lang="console">
mke2fs 1.46.2 (28-Feb-2021)
Creating filesystem with 242688 4k blocks and 60672 inodes
Filesystem UUID: bda8eff7-aa5a-4ed8-aa53-f22e3a1e3203
Superblock backups stored on blocks:
32768, 98304, 163840, 229376

Allocating group tables: done
Writing inode tables: done
Creating journal (4096 blocks): done
Writing superblocks and filesystem accounting information: done
</syntaxhighlight>

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

Write u-boot spl and u-boot to boot partitions 1, 2 and 3:
<syntaxhighlight lang="shell">
dd if=u-boot-spl.stm32 of=${STM32_DISK}1
dd if=u-boot-spl.stm32 of=${STM32_DISK}2
dd if=u-boot.itb of=${STM32_DISK}3
</syntaxhighlight>
<syntaxhighlight lang="console">
314+1 records in
314+1 records out
160911 bytes (161 kB, 157 KiB) copied, 0.274919 s, 585 kB/s
314+1 records in
314+1 records out
160911 bytes (161 kB, 157 KiB) copied, 0.280309 s, 574 kB/s
1600+1 records in
1600+1 records out
819232 bytes (819 kB, 800 KiB) copied, 0.862246 s, 950 kB/s
</syntaxhighlight>

Copy u-boot spl and u-boot to directory <code>boot</code> on rootfs partition 4:
<syntaxhighlight lang="shell">
mkdir -p rootfs
mount ${STM32_DISK}4 rootfs
mkdir -p rootfs/boot
cp u-boot-spl.stm32 u-boot.itb rootfs/boot/
umount rootfs && rmdir rootfs
</syntaxhighlight>

=== Boot from SD card ===

# Hold the button for SD card boot mode on the SODIMM-200 module (DHCOM) below the eMMC chip.
#:[[File:DHCOR_i.MX6ULL_SDP-Boot.jpg|400px]]
# Reset the device. To reset the device, press the reset button on the baseboard or unplug and plug in the power plug.
# Release the button for SD card boot mode

== U-Boot flashing via SD card ==

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

Follow the instruction in [[#U-Boot booting via SD card|U-Boot booting via SD card]] to prepare a SD card with a file system on partition 4, which contains the required binaries <code>u-boot-spl.stm32</code> and <code>u-boot.itb</code>.

=== Write U-Boot SPL and U-Boot to SPI-NOR-Flash ===

# Start U-Boot by [[#U-Boot booting via DFU|U-Boot booting via DFU]] or by [[#Boot from SD card|Boot from SD card]]
# Attach prepared SD card to the on module SD card slot
# Program U-Boot SPL and U-Boot by the script <code>update_sf</code> stored in the U-Boot environment.
#:<syntaxhighlight lang="shell">
STM32MP> run update_sf
</syntaxhighlight>
#:<syntaxhighlight lang="console">
160911 bytes read in 80 ms (1.9 MiB/s)
819232 bytes read in 115 ms (6.8 MiB/s)
SF: Detected w25q16cl with page size 256 Bytes, erase size 4 KiB, total 2 MiB
SF: 2097152 bytes @ 0x0 Erased: OK
device 0 offset 0x0, size 0x2748f
160911 bytes written, 0 bytes skipped in 1.664s, speed 98903 B/s
device 0 offset 0x40000, size 0x2748f
160911 bytes written, 0 bytes skipped in 1.626s, speed 101211 B/s
device 0 offset 0x80000, size 0xc8020
815136 bytes written, 4096 bytes skipped in 8.379s, speed 100094 B/s
</syntaxhighlight>

U-Boot recovery for STM32MP1 DHSOM via DFU

2022-04-14T09:12:32Z

Jneuhauser: /* Check for available DFU device */

To recover a corrupted U-Boot on a STM32MP1-based DHCOM, we can use the default fallback boot source DFU via serial link or USB to temporarily boot U-Boot SPL and U-Boot.
From this U-Boot shell we can write both bootloader images from the SD card to the boot flash.

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

== Requirements ==
=== Software ===
* Linux host computer ([[Virtual Machine for Application Development]] is used in this guide)
* [https://packages.debian.org/stable/dfu-util dfu-util]
* [https://source.denx.de/u-boot/u-boot/-/tree/v2022.04 U-Boot 2022.04] for your board (download and build instructions below)

=== Hardware ===
* STM32MP1 based DHCOM
* DHCOM Premium Developer Kit Baseboard (or Baseboards with OTG ports)
* USB cable for OTG port (Mini USB for PDK2, USB-C for PDK3)

== Preparation ==
This installation was made on the [[Virtual Machine for Application Development]].
All console expressions refer to this Debian system, but any other debian based system should also work.

=== Install dfu-util (debian) ===
<syntaxhighlight lang="shell">
apt-get install dfu-util
</syntaxhighlight>
<syntaxhighlight lang="console">
</syntaxhighlight>

=== Download/Build U-Boot SPL and U-Boot binaries ===

==== Download prebuilt binaries ====

[[media:AACQ30W-7l-Zi_Zutu0Zv-Zua|Dropbox: U-Boot_recovery_for_STM32MP1_DHSOM_via_DFU]] ([https://source.denx.de/u-boot/u-boot/-/tree/v2022.04 source])

<syntaxhighlight lang="shell">
curl -LsS https://www.dropbox.com/sh/os9so01tivajkxs/AACQ30W-7l-Zi_Zutu0Zv-Zua > recovery_binaryies.zip
unzip recovery_binaryies.zip
</syntaxhighlight>
<syntaxhighlight lang="console">
Archive: recovery_binaryies.zip
warning: stripped absolute path spec from /
mapname: conversion of failed
creating: U-Boot_v2022.04_mainline/
creating: U-Boot_v2022.04_mainline/av96/
creating: U-Boot_v2022.04_mainline/pdk2/
creating: U-Boot_v2022.04_mainline/drc02/
creating: U-Boot_v2022.04_mainline/picoitx/
extracting: U-Boot_v2022.04_mainline/av96/u-boot.itb
extracting: U-Boot_v2022.04_mainline/pdk2/u-boot.itb
extracting: U-Boot_v2022.04_mainline/drc02/u-boot.itb
extracting: U-Boot_v2022.04_mainline/picoitx/u-boot.itb
extracting: U-Boot_v2022.04_mainline/av96/u-boot-spl.stm32
extracting: U-Boot_v2022.04_mainline/pdk2/u-boot-spl.stm32
extracting: U-Boot_v2022.04_mainline/drc02/u-boot-spl.stm32
extracting: U-Boot_v2022.04_mainline/picoitx/u-boot-spl.stm32
</syntaxhighlight>

==== Build binaries from source ====

Clone U-Boot mainline source code for release v2022.04:
<syntaxhighlight lang="shell">
UBOOT_SRC=/work/dev/u-boot_v2022.04
mkdir -p $UBOOT_SRC
git clone --branch v2022.04 --depth 1 https://source.denx.de/u-boot/u-boot.git $UBOOT_SRC
cd $UBOOT_SRC
</syntaxhighlight>

Available U-Boot defconfigs for STM32MP1 based DHSOM devices with default device tree in bold:
* '''stm32mp15_dhcom_basic_defconfig''' ('''pdk2''', picoitx, drc02)
* '''stm32mp15_dhcor_basic_defconfig''' ('''avenger96''')
<syntaxhighlight lang="shell">
mkdir -p /work/dev/u-boot
git clone https://source.denx.de/u-boot/u-boot.git -b v2022.04 /work/dev/u-boot
cd /work/dev/u-boot
ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- make stm32mp15_dhcom_basic_defconfig
</syntaxhighlight>

Change default device tree (Example for: stm32mp15xx-dhcom-picoitx):
<syntaxhighlight lang="shell">
sed -iE 's/(stm32mp15xx-dhcom-pdk2|stm32mp157a-dhcor-avenger96)/stm32mp15xx-dhcom-picoitx/' .config
</syntaxhighlight>

Build linux binaries with all available cores:
<syntaxhighlight lang="shell">
ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- make -j$(nproc)
</syntaxhighlight>
<syntaxhighlight lang="console">
...
SHIPPED dts/dt.dtb
CAT u-boot-dtb.bin
MKIMAGE u-boot.img
COPY u-boot.dtb
MKIMAGE u-boot-dtb.img
MKIMAGE u-boot.itb
...
LD spl/u-boot-spl
OBJCOPY spl/u-boot-spl-nodtb.bin
SYM spl/u-boot-spl.sym
CAT spl/u-boot-spl-dtb.bin
COPY spl/u-boot-spl.bin
BINMAN all
</syntaxhighlight>

Check that the required binaries have been created and are of the appropriate size:
<syntaxhighlight lang="shell">
ls -l u-boot.itb u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-rw-r--r-- 1 devel devel 819720 Apr 11 17:03 u-boot.itb
-rw-r--r-- 1 devel devel 124288 Apr 11 17:03 u-boot-spl.stm32
</syntaxhighlight>

== U-Boot booting via DFU ==

To boot U-Boot SPL and U-Boot via DFU boot mode, you must first check if you have a DFU device connected, then load U-Boot SPL into the SRAM of your STM32MP1 and wait until the DRAM is initialized.
Then load U-Boot in the DRAM of your STM32MP1 and continue the boot process using the shown key combination.

=== Check for available DFU device ===

(Re-)Connect the USB cable with your host computer and the OTG port of your baseboard and check the kernel log for a available DFU device:
<syntaxhighlight lang="shell">
sudo dmesg
</syntaxhighlight>
<syntaxhighlight lang="console" highlight="4">
...
usb 2-2: New USB device found, idVendor=0483, idProduct=df11, bcdDevice= 2.00
usb 2-2: New USB device strings: Mfr=1, Product=2, SerialNumber=3
usb 2-2: Product: DFU in HS Mode @Device ID /0x500, @Revision ID /0x0000
usb 2-2: Manufacturer: STMicroelectronics
usb 2-2: SerialNumber: 0040001D3130510439373430
</syntaxhighlight>

=== Download of U-Boot SPL with <code>dfu-util</code> ===

Download of U-Boot SPL with dfu-util to connected device:
<syntaxhighlight lang="shell">
dfu-util -a 1 -D u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
dfu-util 0.9

Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
Copyright 2010-2016 Tormod Volden and Stefan Schmidt
This program is Free Software and has ABSOLUTELY NO WARRANTY
Please report bugs to http://sourceforge.net/p/dfu-util/tickets/

dfu-util: Invalid DFU suffix signature
dfu-util: A valid DFU suffix will be required in a future dfu-util release!!!
Opening DFU capable USB device...
ID 0483:df11
Run-time device DFU version 0110
Claiming USB DFU Interface...
Setting Alternate Setting #1 ...
Determining device status: state = dfuIDLE, status = 0
dfuIDLE, continuing
DFU mode device DFU version 0110
Device returned transfer size 1024
Copying data from PC to DFU device
Download [=========================] 100% 160911 bytes
Download done.
state(7) = dfuMANIFEST, status(0) = No error condition is present
state(2) = dfuIDLE, status(0) = No error condition is present
Done!
</syntaxhighlight>

Output of the serial console:
<syntaxhighlight lang="console">
U-Boot SPL 2022.04 (Apr 05 2022 - 08:27:30 +0200)
Model: STMicroelectronics STM32MP15xx DHCOM Premium Developer Kit (2)
Code: SoM:rev=1,ddr3=3 Board:rev=0
RAM: DDR3L 32bits 2x4Gb 533MHz
Trying to boot from DFU
</syntaxhighlight>

=== Download of U-Boot with <code>dfu-util</code> ===

Download of U-Boot with dfu-util to connected device:
<syntaxhighlight lang="shell">
dfu-util -a 0 -D u-boot.itb
</syntaxhighlight>
<syntaxhighlight lang="console">
dfu-util 0.9

Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
Copyright 2010-2016 Tormod Volden and Stefan Schmidt
This program is Free Software and has ABSOLUTELY NO WARRANTY
Please report bugs to http://sourceforge.net/p/dfu-util/tickets/

dfu-util: Invalid DFU suffix signature
dfu-util: A valid DFU suffix will be required in a future dfu-util release!!!
Opening DFU capable USB device...
ID 0483:df11
Run-time device DFU version 0110
Claiming USB DFU Interface...
Setting Alternate Setting #0 ...
Determining device status: state = dfuIDLE, status = 0
dfuIDLE, continuing
DFU mode device DFU version 0110
Device returned transfer size 4096
Copying data from PC to DFU device
Download [=========================] 100% 819232 bytes
Download done.
state(7) = dfuMANIFEST, status(0) = No error condition is present
state(2) = dfuIDLE, status(0) = No error condition is present
Done!
</syntaxhighlight>

Output of the serial console:
<syntaxhighlight lang="console">
#DOWNLOAD ... OK
Ctrl+C to exit ...
</syntaxhighlight>

Output of the serial console after pressing '''Ctrl+C''':
<syntaxhighlight lang="console">
U-Boot 2022.04 (Apr 05 2022 - 08:27:30 +0200)

CPU: STM32MP157CAA Rev.Z
Model: STMicroelectronics STM32MP15xx DHCOM Premium Developer Kit (2)
Board: stm32mp1 in basic mode (dh,stm32mp15xx-dhcom-pdk2)
DRAM: 1 GiB
Clocks:
- MPU : 650 MHz
- MCU : 208.878 MHz
- AXI : 266.500 MHz
- PER : 24 MHz
- DDR : 533 MHz
Core: 255 devices, 31 uclasses, devicetree: separate
MMC: STM32 SD/MMC: 2, STM32 SD/MMC: 0, STM32 SD/MMC: 1
Loading Environment from SPIFlash... SF: Detected w25q16cl with page size 256 Bytes, erase size 4 KiB, total 2 MiB
OK
In: serial
Out: serial
Err: serial
Net: eth0: ethernet@5800a000, eth1: ks8851mll@64000000
Hit any key to stop autoboot: 0
</syntaxhighlight>

== Troubleshooting ==
If there is a U-Boot starting, the DFU procedure may not work properly.
There are two solutions to prevent the start of U-Boot from the SPI-NOR-Flash.

=== SD card boot mode (only HS00014) ===
# Boot in SD card boot mode to prevent booting the broken U-Boot from SPI-NOR-Flash
## Hold the button for SD card boot mode on the SODIMM-200 module (DHCOM) below the eMMC chip.
##:[[File:DHCOR_i.MX6ULL_SDP-Boot.jpg|400px]]
## Reset the device. To reset the device, press the reset button on the baseboard or unplug and plug in the power plug.
## Release the button for SD card boot mode
# If no new output is printed on the serial console (serial port), continue with the DFU booting procedure

=== Delete U-Boot ===
# <code>sf probe</code>
# <code>sf erase 0x0 0xf0000</code>
# Restart the board
# If no new output is printed on the serial console (serial port), continue with the DFU booting procedure

U-Boot recovery for STM32MP1 DHSOM via DFU

2022-04-14T08:50:06Z

Jneuhauser: Created page with " To recover a corrupted U-Boot on a STM32MP1-based DHCOM, we can use the de..."

To recover a corrupted U-Boot on a STM32MP1-based DHCOM, we can use the default fallback boot source DFU via serial link or USB to temporarily boot U-Boot SPL and U-Boot.
From this U-Boot shell we can write both bootloader images from the SD card to the boot flash.

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

== Requirements ==
=== Software ===
* Linux host computer ([[Virtual Machine for Application Development]] is used in this guide)
* [https://packages.debian.org/stable/dfu-util dfu-util]
* [https://source.denx.de/u-boot/u-boot/-/tree/v2022.04 U-Boot 2022.04] for your board (download and build instructions below)

=== Hardware ===
* STM32MP1 based DHCOM
* DHCOM Premium Developer Kit Baseboard (or Baseboards with OTG ports)
* USB cable for OTG port (Mini USB for PDK2, USB-C for PDK3)

== Preparation ==
This installation was made on the [[Virtual Machine for Application Development]].
All console expressions refer to this Debian system, but any other debian based system should also work.

=== Install dfu-util (debian) ===
<syntaxhighlight lang="shell">
apt-get install dfu-util
</syntaxhighlight>
<syntaxhighlight lang="console">
</syntaxhighlight>

=== Download/Build U-Boot SPL and U-Boot binaries ===

==== Download prebuilt binaries ====

[[media:AACQ30W-7l-Zi_Zutu0Zv-Zua|Dropbox: U-Boot_recovery_for_STM32MP1_DHSOM_via_DFU]] ([https://source.denx.de/u-boot/u-boot/-/tree/v2022.04 source])

<syntaxhighlight lang="shell">
curl -LsS https://www.dropbox.com/sh/os9so01tivajkxs/AACQ30W-7l-Zi_Zutu0Zv-Zua > recovery_binaryies.zip
unzip recovery_binaryies.zip
</syntaxhighlight>
<syntaxhighlight lang="console">
Archive: recovery_binaryies.zip
warning: stripped absolute path spec from /
mapname: conversion of failed
creating: U-Boot_v2022.04_mainline/
creating: U-Boot_v2022.04_mainline/av96/
creating: U-Boot_v2022.04_mainline/pdk2/
creating: U-Boot_v2022.04_mainline/drc02/
creating: U-Boot_v2022.04_mainline/picoitx/
extracting: U-Boot_v2022.04_mainline/av96/u-boot.itb
extracting: U-Boot_v2022.04_mainline/pdk2/u-boot.itb
extracting: U-Boot_v2022.04_mainline/drc02/u-boot.itb
extracting: U-Boot_v2022.04_mainline/picoitx/u-boot.itb
extracting: U-Boot_v2022.04_mainline/av96/u-boot-spl.stm32
extracting: U-Boot_v2022.04_mainline/pdk2/u-boot-spl.stm32
extracting: U-Boot_v2022.04_mainline/drc02/u-boot-spl.stm32
extracting: U-Boot_v2022.04_mainline/picoitx/u-boot-spl.stm32
</syntaxhighlight>

==== Build binaries from source ====

Clone U-Boot mainline source code for release v2022.04:
<syntaxhighlight lang="shell">
UBOOT_SRC=/work/dev/u-boot_v2022.04
mkdir -p $UBOOT_SRC
git clone --branch v2022.04 --depth 1 https://source.denx.de/u-boot/u-boot.git $UBOOT_SRC
cd $UBOOT_SRC
</syntaxhighlight>

Available U-Boot defconfigs for STM32MP1 based DHSOM devices with default device tree in bold:
* '''stm32mp15_dhcom_basic_defconfig''' ('''pdk2''', picoitx, drc02)
* '''stm32mp15_dhcor_basic_defconfig''' ('''avenger96''')
<syntaxhighlight lang="shell">
mkdir -p /work/dev/u-boot
git clone https://source.denx.de/u-boot/u-boot.git -b v2022.04 /work/dev/u-boot
cd /work/dev/u-boot
ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- make stm32mp15_dhcom_basic_defconfig
</syntaxhighlight>

Change default device tree (Example for: stm32mp15xx-dhcom-picoitx):
<syntaxhighlight lang="shell">
sed -iE 's/(stm32mp15xx-dhcom-pdk2|stm32mp157a-dhcor-avenger96)/stm32mp15xx-dhcom-picoitx/' .config
</syntaxhighlight>

Build linux binaries with all available cores:
<syntaxhighlight lang="shell">
ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- make -j$(nproc)
</syntaxhighlight>
<syntaxhighlight lang="console">
...
SHIPPED dts/dt.dtb
CAT u-boot-dtb.bin
MKIMAGE u-boot.img
COPY u-boot.dtb
MKIMAGE u-boot-dtb.img
MKIMAGE u-boot.itb
...
LD spl/u-boot-spl
OBJCOPY spl/u-boot-spl-nodtb.bin
SYM spl/u-boot-spl.sym
CAT spl/u-boot-spl-dtb.bin
COPY spl/u-boot-spl.bin
BINMAN all
</syntaxhighlight>

Check that the required binaries have been created and are of the appropriate size:
<syntaxhighlight lang="shell">
ls -l u-boot.itb u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
-rw-r--r-- 1 devel devel 819720 Apr 11 17:03 u-boot.itb
-rw-r--r-- 1 devel devel 124288 Apr 11 17:03 u-boot-spl.stm32
</syntaxhighlight>

== U-Boot booting via DFU ==

To boot U-Boot SPL and U-Boot via DFU boot mode, you must first check if you have a DFU device connected, then load U-Boot SPL into the SRAM of your STM32MP1 and wait until the DRAM is initialized.
Then load U-Boot in the DRAM of your STM32MP1 and continue the boot process using the shown key combination.

=== Check for available DFU device ===

(Re-)Connect the USB cable with your host computer and the OTG port of your baseboard.
In the kernel log you should see something like:
<syntaxhighlight lang="shell">
sudo dmesg
</syntaxhighlight>
<syntaxhighlight lang="console" highlight="4">
...
usb 2-2: New USB device found, idVendor=0483, idProduct=df11, bcdDevice= 2.00
usb 2-2: New USB device strings: Mfr=1, Product=2, SerialNumber=3
usb 2-2: Product: DFU in HS Mode @Device ID /0x500, @Revision ID /0x0000
usb 2-2: Manufacturer: STMicroelectronics
usb 2-2: SerialNumber: 0040001D3130510439373430
</syntaxhighlight>

=== Download of U-Boot SPL with <code>dfu-util</code> ===

Download of U-Boot SPL with dfu-util to connected device:
<syntaxhighlight lang="shell">
dfu-util -a 1 -D u-boot-spl.stm32
</syntaxhighlight>
<syntaxhighlight lang="console">
dfu-util 0.9

Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
Copyright 2010-2016 Tormod Volden and Stefan Schmidt
This program is Free Software and has ABSOLUTELY NO WARRANTY
Please report bugs to http://sourceforge.net/p/dfu-util/tickets/

dfu-util: Invalid DFU suffix signature
dfu-util: A valid DFU suffix will be required in a future dfu-util release!!!
Opening DFU capable USB device...
ID 0483:df11
Run-time device DFU version 0110
Claiming USB DFU Interface...
Setting Alternate Setting #1 ...
Determining device status: state = dfuIDLE, status = 0
dfuIDLE, continuing
DFU mode device DFU version 0110
Device returned transfer size 1024
Copying data from PC to DFU device
Download [=========================] 100% 160911 bytes
Download done.
state(7) = dfuMANIFEST, status(0) = No error condition is present
state(2) = dfuIDLE, status(0) = No error condition is present
Done!
</syntaxhighlight>

Output of the serial console:
<syntaxhighlight lang="console">
U-Boot SPL 2022.04 (Apr 05 2022 - 08:27:30 +0200)
Model: STMicroelectronics STM32MP15xx DHCOM Premium Developer Kit (2)
Code: SoM:rev=1,ddr3=3 Board:rev=0
RAM: DDR3L 32bits 2x4Gb 533MHz
Trying to boot from DFU
</syntaxhighlight>

=== Download of U-Boot with <code>dfu-util</code> ===

Download of U-Boot with dfu-util to connected device:
<syntaxhighlight lang="shell">
dfu-util -a 0 -D u-boot.itb
</syntaxhighlight>
<syntaxhighlight lang="console">
dfu-util 0.9

Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
Copyright 2010-2016 Tormod Volden and Stefan Schmidt
This program is Free Software and has ABSOLUTELY NO WARRANTY
Please report bugs to http://sourceforge.net/p/dfu-util/tickets/

dfu-util: Invalid DFU suffix signature
dfu-util: A valid DFU suffix will be required in a future dfu-util release!!!
Opening DFU capable USB device...
ID 0483:df11
Run-time device DFU version 0110
Claiming USB DFU Interface...
Setting Alternate Setting #0 ...
Determining device status: state = dfuIDLE, status = 0
dfuIDLE, continuing
DFU mode device DFU version 0110
Device returned transfer size 4096
Copying data from PC to DFU device
Download [=========================] 100% 819232 bytes
Download done.
state(7) = dfuMANIFEST, status(0) = No error condition is present
state(2) = dfuIDLE, status(0) = No error condition is present
Done!
</syntaxhighlight>

Output of the serial console:
<syntaxhighlight lang="console">
#DOWNLOAD ... OK
Ctrl+C to exit ...
</syntaxhighlight>

Output of the serial console after pressing '''Ctrl+C''':
<syntaxhighlight lang="console">
U-Boot 2022.04 (Apr 05 2022 - 08:27:30 +0200)

CPU: STM32MP157CAA Rev.Z
Model: STMicroelectronics STM32MP15xx DHCOM Premium Developer Kit (2)
Board: stm32mp1 in basic mode (dh,stm32mp15xx-dhcom-pdk2)
DRAM: 1 GiB
Clocks:
- MPU : 650 MHz
- MCU : 208.878 MHz
- AXI : 266.500 MHz
- PER : 24 MHz
- DDR : 533 MHz
Core: 255 devices, 31 uclasses, devicetree: separate
MMC: STM32 SD/MMC: 2, STM32 SD/MMC: 0, STM32 SD/MMC: 1
Loading Environment from SPIFlash... SF: Detected w25q16cl with page size 256 Bytes, erase size 4 KiB, total 2 MiB
OK
In: serial
Out: serial
Err: serial
Net: eth0: ethernet@5800a000, eth1: ks8851mll@64000000
Hit any key to stop autoboot: 0
</syntaxhighlight>

== Troubleshooting ==
If there is a U-Boot starting, the DFU procedure may not work properly.
There are two solutions to prevent the start of U-Boot from the SPI-NOR-Flash.

=== SD card boot mode (only HS00014) ===
# Boot in SD card boot mode to prevent booting the broken U-Boot from SPI-NOR-Flash
## Hold the button for SD card boot mode on the SODIMM-200 module (DHCOM) below the eMMC chip.
##:[[File:DHCOR_i.MX6ULL_SDP-Boot.jpg|400px]]
## Reset the device. To reset the device, press the reset button on the baseboard or unplug and plug in the power plug.
## Release the button for SD card boot mode
# If no new output is printed on the serial console (serial port), continue with the DFU booting procedure

=== Delete U-Boot ===
# <code>sf probe</code>
# <code>sf erase 0x0 0xf0000</code>
# Restart the board
# If no new output is printed on the serial console (serial port), continue with the DFU booting procedure

DHCOM STM32MP15 Secure Boot

2022-03-23T08:18:18Z

Jneuhauser: Update U-Boot repository URL

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

Checkout the branch <syntaxhighlight lang="shell" inline>v2022.01_dhcom_secure_boot</syntaxhighlight> from DH electronics GitHub repository with:

<syntaxhighlight lang="shell">
git clone https://github.com/dh-electronics/u-boot-stm32mp1.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 u-boot-stm32mp1 https://github.com/dh-electronics/u-boot-stm32mp1.git
git fetch u-boot-stm32mp1
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-spl-signed.stm32 || FSBL || Same as above but as signed STM32 image. Is created in [[#Sign U-Boot SPL with STM32MP_SigningTool_CLI|Sign U-Boot SPL with STM32MP_SigningTool_CLI]].
|-
| u-boot.itb || SSBL || U-Boot and Device Tree's contained in a FIT image.
|-
| u-boot-signed.itb || SSBL || Same as above but with signed configs and images.
|}

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

Load <syntaxhighlight lang="shell" inline>u-boot-spl-signed.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot-signed.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-signed.stm32
tftp ${fsbl2addr} ${serverip}:u-boot-spl-signed.stm32
tftp ${ssbl1addr} ${serverip}:u-boot-signed.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-22T13:55:16Z

Jneuhauser: Use image files with "-signed" postfix for all commands after signing of u-boot-spl.stm32

<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-spl-signed.stm32 || FSBL || Same as above but as signed STM32 image. Is created in [[#Sign U-Boot SPL with STM32MP_SigningTool_CLI|Sign U-Boot SPL with STM32MP_SigningTool_CLI]].
|-
| u-boot.itb || SSBL || U-Boot and Device Tree's contained in a FIT image.
|-
| u-boot-signed.itb || SSBL || Same as above but with signed configs and images.
|}

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

Load <syntaxhighlight lang="shell" inline>u-boot-spl-signed.stm32</syntaxhighlight> and <syntaxhighlight lang="shell" inline>u-boot-signed.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-signed.stm32
tftp ${fsbl2addr} ${serverip}:u-boot-spl-signed.stm32
tftp ${ssbl1addr} ${serverip}:u-boot-signed.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-22T13:51:27Z

Jneuhauser: Update commands and outputs in "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-spl-signed.stm32 || FSBL || Same as above but as signed STM32 image. Is created in [[#Sign U-Boot SPL with STM32MP_SigningTool_CLI|Sign U-Boot SPL with STM32MP_SigningTool_CLI]].
|-
| u-boot.itb || SSBL || U-Boot and Device Tree's contained in a FIT image.
|-
| u-boot-signed.itb || SSBL || Same as above but with signed configs and images.
|}

==== 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-signed.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-signed.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-signed.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-22T13:49:52Z

Jneuhauser: Extend table of U-Boot binaries with signed variants and output signed STM32 image with signed postfix

<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-spl-signed.stm32 || FSBL || Same as above but as signed STM32 image. Is created in [[#Sign U-Boot SPL with STM32MP_SigningTool_CLI|Sign U-Boot SPL with STM32MP_SigningTool_CLI]].
|-
| u-boot.itb || SSBL || U-Boot and Device Tree's contained in a FIT image.
|-
| u-boot-signed.itb || SSBL || Same as above but with signed configs and images.
|}

==== 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-signed.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-21T14:58:54Z

Jneuhauser: Add property lang="shell" to empty syntaxhighlight blocks

<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 is meant by 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 in the boot process.

Secure Boot is the necessary cornerstone for enforcing security mechanisms in the overall system.
If only signed software is executed at system startup, it can also be assumed that the software is free from tampering, comes from a trusted source and the application of security policies always takes place during the boot process.

[[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. If successful, 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.

The program code and the certificate must be trusted and protected against tampering in each stage, otherwise the boot chain can be compromised. Except for the first stage, all binary images are protected against third-party tampering by the signature. Since it is practically impossible to verify the first stage, but this must still be protected against manipulation, the program code for the first stage and the certificate for the verification of the second stage are stored in a ROM, for example.

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

DHCOM STM32MP15 Secure Boot

2022-03-21T14:56:57Z

Jneuhauser: Undo revision 3636 by Jneuhauser (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)
|-
| 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 is meant by 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 in the boot process.

Secure Boot is the necessary cornerstone for enforcing security mechanisms in the overall system.
If only signed software is executed at system startup, it can also be assumed that the software is free from tampering, comes from a trusted source and the application of security policies always takes place during the boot process.

[[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. If successful, 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.

The program code and the certificate must be trusted and protected against tampering in each stage, otherwise the boot chain can be compromised. Except for the first stage, all binary images are protected against third-party tampering by the signature. Since it is practically impossible to verify the first stage, but this must still be protected against manipulation, the program code for the first stage and the certificate for the verification of the second stage are stored in a ROM, for example.

=== 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 inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight 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 inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight 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 inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight 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-21T14:54:33Z

Jneuhauser: Add property lang="bash" to empty syntaxhighlight blocks

<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 is meant by 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 in the boot process.

Secure Boot is the necessary cornerstone for enforcing security mechanisms in the overall system.
If only signed software is executed at system startup, it can also be assumed that the software is free from tampering, comes from a trusted source and the application of security policies always takes place during the boot process.

[[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. If successful, 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.

The program code and the certificate must be trusted and protected against tampering in each stage, otherwise the boot chain can be compromised. Except for the first stage, all binary images are protected against third-party tampering by the signature. Since it is practically impossible to verify the first stage, but this must still be protected against manipulation, the program code for the first stage and the certificate for the verification of the second stage are stored in a ROM, for example.

=== 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
| bash 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 bash 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 bash 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 bash''' 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 bash''' 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 bash 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-21T12:16:23Z

Jneuhauser: Initial page

<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 is meant by 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 in the boot process.

Secure Boot is the necessary cornerstone for enforcing security mechanisms in the overall system.
If only signed software is executed at system startup, it can also be assumed that the software is free from tampering, comes from a trusted source and the application of security policies always takes place during the boot process.

[[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. If successful, 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.

The program code and the certificate must be trusted and protected against tampering in each stage, otherwise the boot chain can be compromised. Except for the first stage, all binary images are protected against third-party tampering by the signature. Since it is practically impossible to verify the first stage, but this must still be protected against manipulation, the program code for the first stage and the certificate for the verification of the second stage are stored in a ROM, for example.

=== 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 inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight 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 inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight 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 inline>u-boot-spl.stm32</syntaxhighlight> and <syntaxhighlight 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>

User:Jneuhauser/vector.css

2022-03-16T08:55:34Z

Jneuhauser: Add required css for TOC limit

/* https://www.mediawiki.org/wiki/Template:TOC */
.toclimit-2 .toclevel-1 ul,
.toclimit-3 .toclevel-2 ul,
.toclimit-4 .toclevel-3 ul,
.toclimit-5 .toclevel-4 ul,
.toclimit-6 .toclevel-5 ul,
.toclimit-7 .toclevel-6 ul {
display: none;
}