This page explains how to enable the the secure boot for your board.
1. Purpose[edit source]
In this article, the stm32key U-Boot command is used to illustrate and experiment the steps needed to activate the secure boot features: authentication and encryption.
For real secured product, the associated OTPs must be updated directly by customer application or with Secure Secret Provisioning (SSP).
The needed keys file is generated using STM32 KeyGen tool.
The file are signed with STM32 Signing tool.
2. U-Boot command stm32key[edit source]
U-Boot in OpenSTLinux embeds a stm32key command that can be called from U-Boot command line interface to manage the keys in OTPs.
stm32key help
stm32key - Manage key on STM32 Usage: stm32key list : list the supported key with description stm32key select [<key>] : Select the key identified by <key> or display the key used for read/fuse command stm32key read [<addr> | -a ] : Read the curent key at <addr> or current / all (-a) key in OTP stm32key fuse [-y] <addr> : Fuse the current key at addr in OTP stm32key close [-y] : Close the device, force use of PKH stored in OTP
The optional option -y is used to skip the confirmation message.
The name of the used <key> is
- for STM32MP13x lines
: PKHTH for authentication and EDMK for encryption
stm32key list PKHTH : Hash of the 8 ECC Public Keys Hashes Table (ECDSA is the authentication algorithm) OTP24..32 EDMK : Encryption/Decryption Master Key" OTP92..95
- for STM32MP15x lines : PKH for authentication
stm32key list PKH : Hash of the ECC Public Key (ECDSA is the authentication algorithm) OTP24..32
3. Authentication steps with U-Boot[edit source]
The steps described in authentication for STM32MP13x and for STM32MP15x are executed with the same sequence of U-Boot stm32keycommands:
- U-Boot Key registration with U-Boot: update and lock OTPs (
stm32key fuse) - Check Authentication with registered keys
- Close the device with U-Boot, only signed binary will be accepted (
stm32key close)
3.1. Prerequisite: Key generation[edit source]
First step is to generate with STM32 KeyGen tool
- the ECC pairs of keys (private and public); they will be used to sign the images.
- the OTP data used by the ROM code on the target to verify the public key in the signed STM32 image header.
- 8 pairs (publicKey0x{0..7}.pem and privateKey0x{0..7}.pem) and PKHTH file publicKeysHashHashes.bin for STM32MP13x lines
- 8 pairs (publicKey0x{0..7}.pem and privateKey0x{0..7}.pem) and PKHTH file publicKeysHashHashes.bin for STM32MP13x lines
{PC$}} STM32MP_KeyGen_CLI -abs . -n 8 -pwd PASS1 PASS2 PASS3 PASS4 PASS5 PASS6 PASS7 PASS8
- 1 pair (publicKey.pem & privateKey.pem) and PKH file publicKeyhash.bin for STM32MP15x lines
- 1 pair (publicKey.pem & privateKey.pem) and PKH file publicKeyhash.bin for STM32MP15x lines
{PC$}} STM32MP_KeyGen_CLI -abs . -pwd PASSWORD
3.2. Keys registration with U-Boot[edit source]
The first step to enable the authentication is to burn the keys in OTPs with the output file from STM32 KeyGen.
- Select keys with U-Boot: with the command
sm32key select <key>
with <key>=
- PKHTH for STM32MP13x lines
- PKHTH for STM32MP13x lines
sm32key select PKHTH PKHTH selected
- PKH for STM32MP15x lines
- PKH for STM32MP15x lines
sm32key select PKH PKH selected
- Load keys file in DDR
The keys file, the output file from STM32 KeyGen, must be available in DDR before proceeding the stm32key command;
this file is loaded at 0xc0000000 in the next examples.
For example loaded from a filesystem partition on a storage device by using the load.
with a file Keys.bin in bootfs (partition 4) on SD card (mmc0):
load mmc 0:4 0xc0000000 Keys.bin 32 bytes read in 50 ms (0 Bytes/s)
- Verify keys file in DDR
Then you can verify the content of keys files loaded in DDR with the command:
stm32key read 0xc0000000
Example for STM32MP13x lines with PKHTH
stm32key read 0xC0000000 Read PKHTH at 0xc0000000 PKHTH OTP 24: [c0000000] 27051956 PKHTH OTP 25: [c0000004] b56aef2d PKHTH OTP 26: [c0000008] 6215263c PKHTH OTP 27: [c000000c] 00000439 PKHTH OTP 28: [c0000010] 00000000 PKHTH OTP 29: [c0000014] 00000000 PKHTH OTP 30: [c0000018] 72429173 PKHTH OTP 31: [c000001c] 05020600
Example for STM32MP15x lines with PKH
stm32key read 0xC0000000 Read PKH at 0xc0000000 PKH OTP 24: [c0000000] 27051956EDMK PKH OTP 25: [c0000004] b56aef2d PKH OTP 26: [c0000008] 6215263c PKH OTP 27: [c000000c] 00000439 PKH OTP 28: [c0000010] 00000000 PKH OTP 29: [c0000014] 00000000 PKH OTP 30: [c0000018] 72429173 PKH OTP 31: [c000001c] 05020600
- Register keys
To write and lock the keys in OTP, you use the command:
stm32key fuse 0xc0000000
- Verify keys in OTPs
After the previous command, the device contains the keys to authenticate images and it can be verified with the command:
stm32key read
Result for STM32MP13x lines with PKHTH
stm32key read PKHTH OTP 24: 27051956 lock : 50000000 PKHTH OTP 25: b56aef2d lock : 50000000 PKHTH OTP 26: 6215263c lock : 50000000 PKHTH OTP 27: 00000439 lock : 50000000 PKHTH OTP 28: 00000000 lock : 50000000 PKHTH OTP 29: 00000000 lock : 50000000 PKHTH OTP 30: 72429173 lock : 50000000 PKHTH OTP 31: 05020600 lock : 50000000
Result for STM32MP15x lines with PKH
stm32key read PKH OTP 24: 27051956 lock : 50000000 PKH OTP 25: b56aef2d lock : 50000000 PKH OTP 26: 6215263c lock : 50000000 PKH OTP 27: 00000439 lock : 50000000 PKH OTP 28: 00000000 lock : 50000000 PKH OTP 29: 00000000 lock : 50000000 PKH OTP 30: 72429173 lock : 50000000 PKH OTP 31: 05020600 lock : 50000000
3.3. Check authentication[edit source]
Without any other modification, the device is able to perform image authentication but the non-authenticated images can still be used and executed: the device is still opened, let's see this as a kind of test mode to check that the keys is properly set.
To check authentication, the FSBL binary must be signed with the STM32 Signing tool.
For example, you can sign the result of the TF-A compilation with STM32 image header: tf-a.stm32.
- For STM32MP13: request authentication with the bit 0 of option flags: -of
STM32MP_SigningTool_CLI -bin tf-a.stm32 \ -pubk <KEY_PATH>/publicKey*.pem \ -prvk <KEY_PATH>/privateKey00.pem \ -pwd PASS1 \ -of 0x00000001 \ -o tf-a-signed.stm32
- For STM32MP15:
STM32MP_SigningTool_CLI -bin tf-a.stm32 \ -pubk <KEY_PATH>/publicKey.pem \ -prvk <KEY_PATH>/privateKey.pem \ -pwd PASSWORD -o tf-a-signed.stm32
See STM32 Signing tool for other options.
Once the image is signed, tf-a-signed.stm32, it can be programmed into the flash on the target board with STM32CubeProgrammer.
Using this signed binary, the ROM code compares the keys carried in the STM32 header with the one that was provisioned in OTP and starts the FSBL = TF-A.
The Authentication result to transmit to TF-A and, at boot time on board, you must see the following line in TF-A trace:
NOTICE: Bootrom authentication succeeded
Example:
NOTICE: CPU: STM32MP157CAA Rev.? NOTICE: Model: STMicroelectronics STM32MP157C eval daughter on eval mother NOTICE: Board: MB1263 Var1.0 Rev.C-01 NOTICE: Bootrom authentication succeeded INFO: Reset reason (0x15): INFO: Power-on Reset (rst_por) INFO: PMIC version = 0x10
3.4. Closing the device with U-Boot[edit source]
As soon as the authentication process is confirmed, the device can be closed and the user is forced to use signed images.
Non-signed binaries will not be supported anymore on the target.
This operation is perform with the U-Boot command:
stm32key close
4. Encryption/Decryption steps with U-Boot[edit source]
Encryption/Decryption is supported on STM32MP13x lines
4.1. Encrypte/Decrypt Keys registration with U-Boot[edit source]
The first step to enable the authentication is to burn the keys in OTPs with the output file from STM32 KeyGen.
- Select keys with U-Boot: with the command
sm32key select <key>
with <key>=
- PKHTH for STM32MP13x lines
- PKHTH for STM32MP13x lines
sm32key select PKHTH PKHTH selected
- Load keys file in DDR
The keys file, the output file from STM32 KeyGen, must be available in DDR before proceeding the stm32key command;
this file is loaded at 0xc0000000 in the next examples.
For example loaded from a filesystem partition on a storage device by using the load.
with a file Keys.bin in bootfs (partition 4) on SD card (mmc0):
load mmc 0:4 0xc0000000 Keys.bin 32 bytes read in 50 ms (0 Bytes/s)
- Verify keys file in DDR
Then you can verify the content of keys files loaded in DDR with the command:
stm32key read 0xc0000000
Example for STM32MP13x lines with EDMK
stm32key read 0xC0000000 Read EDMK at 0xc0000000 EDMK OTP 92: [c0000000] 27051956 EDMK OTP 93: [c0000004] b56aef2d EDMK OTP 94: [c0000008] 6215263c EDMK OTP 95: [c000000c] 00000439
- Register keys
To write and lock the keys in OTP, you use the command:
-encdc0x25205f0e \ -prvk <KEY_PATH>/encryption_key.bin \ stm32key fuse 0xc0000000
- Verify keys in OTPs
After the previous command, the device contains the keys to decrypt the images and it can be verified with the command:
stm32key read
Result for STM32MP13x lines with EDMK
stm32key read EDMK OTP 92: 00000000 lock : 50000000 EDMK OTP 93: 00000000 lock : 50000000 EDMK OTP 94: 00000000 lock : 50000000 EDMK OTP 95: 00000000 lock : 50000000
Warning the content of the key can't be read, it is masked, but the lock proprety can be verified.
4.2. Check decryption[edit source]
Without any other modification, the device is able to use only encrypted images.
- For STM32MP13: request authentication with the bit 1 of option flags: -of
{PC$}} STM32MP_SigningTool_CLI -bin tf-a.stm32 \
-encdc0x25205f0e \
-prvk <KEY_PATH>/encryption_key.bin \
-of 0x00000002 \
-o tf-a-signed.stm32
This decryption can be combined with authentication with bit0 and bit1 of option flags: -of
{PC$}} STM32MP_SigningTool_CLI -bin tf-a.stm32 \
-encdc0x25205f0e \
-prvk <KEY_PATH>/encryption_key.bin \
-pubk <KEY_PATH>/publicKey*.pem \
-prvk <KEY_PATH>/privateKey00.pem \
-pwd PASS1 \
-of 0x00000003 \
-o tf-a-signed.stm32
5. References[edit source]