How to use U-Boot stm32key command

Applicable for STM32MP13x lines, STM32MP15x lines

1 Purpose[edit]

In this article, the stm32key U-Boot command is used to illustrate and experiment the steps to provision the keys in the correct OTP needed to activate secure boot features: authentication and encryption.

It also allows setting the device directly to the CLOSED state.

1.1 Prerequisite[edit]

All the required keys must be generated to provision the OTP.

The OTP write support must be activated in OP-TEE STM32MP BSEC PTA with CFG_STM32_BSEC_WRITE.

In ecosystem release ≤ v4.1.0 More info.png , this configuration is activated only on OP-TEE debug release with:

CFG_STM32_BSEC_WRITE ?= $(CFG_TEE_CORE_DEBUG)

The command stm32key is not functional by default with the release version of OP-TEE.

Warning white.png Warning
Make sure that a device with secure boot enabled is used: this is mentioned in the chip part number, for STM32MP13 and STM32MP15. Otherwise, the device becomes permanently unusable.

2 stm32key command[edit]

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 Warning.png: 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 More info.png: PKH for authentication
  stm32key list
 PKH: Hash of the ECC Public Key (ECDSA is the authentication algorithm)
 	OTP24..32

3 Authentication keys provisioning[edit]

The key provisioning is the first step to enable the authentication: burn the keys in OTPs with the key hash output file from STM32 KeyGen.

3.1 Select keys[edit]

Key is selected with the command sm32key select <key>, with <key>=

  • PKHTH for STM32MP13x lines Warning.png
  sm32key select PKHTH
 PKHTH selected
  • PKH for STM32MP15x lines More info.png
  sm32key select PKH
 PKH selected

3.2 Load keys file in DDR[edit]

The keys hash file, output file from STM32 KeyGen, must be available in DDR before proceeding with the stm32key command;
this file is loaded at 0xc0000000 in the next examples.

The file publicKeysHash.bin can be loaded from a filesystem partition on a storage device by using the load command. For example, the file publicKeysHash.bin is in the bootfs (partition 7) on SD™ card (mmc0):

  load mmc 0:7 0xc0000000 publicKeysHash.bin
 32 bytes read in 50 ms (0 Bytes/s)

3.3 Verify keys file in DDR[edit]

Once the publicKeysHash.bin file is loaded in DDR, you can verify the content of the file with the command:

  stm32key read 0xc0000000 

Example for STM32MP13x lines Warning.png 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 More info.png with PKH

 stm32key read 0xC0000000
 Read PKH at 0xc0000000
 PKH OTP 24: [c0000000] 27051956
 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

3.4 Key provisioning[edit]

To write and lock the keys in OTP, you use the command:

  stm32key fuse 0xc0000000 
Warning white.png Warning
Verify the keys before to confirm the operation; It is an irreversible operation!

3.5 Verify keys file in OTP[edit]

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 Warning.png 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 More info.png 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

4 Encryption Decryption Master Key provisioning[edit]

The EDMK key provisioning is the first step to enable the image decryption.

It is only available on STM32MP13x lines Warning.png.

4.1 Select EDMK[edit]

Key is selected with the command sm32key select <key>, with <key>=

  • EDMK for STM32MP13x lines Warning.png
  stm32key select EDMK
 EDMK selected

4.2 Load EDMK file in DDR[edit]

The keys file must be available in DDR before proceeding the stm32key command;
this file is loaded at 0xc0000000 in the next examples.

The file edmk.bin can be loaded from a filesystem partition on a storage device by using the load command. For example, the file edmk.bin is in the bootfs (partition 7) on SD™ card (mmc0):

  load mmc 0:7 0xc0000000 edmk.bin
 32 bytes read in 50 ms (0 Bytes/s)

4.3 Verify EDMK in DDR[edit]

Then you can verify the content of keys files loaded in DDR with the command: sm32key read <addr>

Result for STM32MP13x lines Warning.png with EDMK and <addr>=0xc0000000

  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

4.4 EDMK provisioning[edit]

To write and lock the EDMK in OTP, you use the command with the same address:

  stm32key fuse 0xc0000000
Warning white.png Warning
Verify keys before to confirm the operation, it is a irreversible operation !

4.5 Verify EDMK in OTP[edit]

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 Warning.png 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 cannot be read. It is masked, but the lock property can be verified to ensure that the key has been written.

5 Closing the device[edit]

Once the authentication process is confirmed in ROM code and in TF-A, the device can be closed to ensure that only signed images can be used.

This operation is performed with the U-Boot command:

  stm32key close
Warning white.png Warning
This must not be done on STM32MP13x or STM32MP15x devices without secure boot enabled; Otherwise, the device becomes bricked and cannot be used anymore