Difference between revisions of "How to use U-Boot stm32key command"

[unchecked revision] [quality revision]
m
m
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 to directly set the device to CLOSED state.

1.1 Prerequisite[edit]

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

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 will become 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.

 
STM32MP> 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
 
STM32MP> 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
 
STM32MP> 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
 
STM32MP> sm32key select PKHTH
 PKHTH selected
  • PKH for STM32MP15x lines More info.png
 
STM32MP> 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 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):

 
STM32MP> 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:

 
STM32MP> stm32key read 0xc0000000 

Example for STM32MP13x lines Warning.png with PKHTH

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

STM32MP> 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:

 
STM32MP> stm32key fuse 0xc0000000 

Warning white.png Warning
Verify keys before to confirm the operation, it is a 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:

 
STM32MP> stm32key read

Result for STM32MP13x lines Warning.png with PKHTH

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

STM32MP> 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
 
STM32MP> 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):

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

 
STM32MP> 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:

 
STM32MP> 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:

 
STM32MP> stm32key read

Result for STM32MP13x lines Warning.png with EDMK

STM32MP> 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 property can be verified to ensure the key as 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 perform with the U-Boot command:

 
STM32MP> stm32key close
Warning white.png Warning
This must not be done on STM32MP13 or STM32MP15 part numbers without Secure boot enabled, otherwise the chip will be bricked and could not be used anymore
{{ApplicableFor
|MPUs list=STM32MP13x, STM32MP15x
|MPUs checklist=STM32MP13x, STM32MP15x
}}
__TOC__
== Purpose ==
In this article, the <code>stm32key</code> U-Boot command is used to '''illustrate''' and '''experiment''' the steps to provision the [[How_to_secure_STM32_MPU#STM32MPU_keys|keys]] in the correct OTP needed to activate [[How_to_secure_STM32_MPU#Secure_Boot|secure boot]] features: authentication and encryption.

It also allows to directly set the device to [[How_to_secure_STM32_MPU#Device_life_cycle|'''CLOSED''']] state.

=== Prerequisite ===

All the required [[How_to_secure_STM32_MPU#STM32MPU_keys|keys]] have to be generated to provision the OTP.

{{Warning| Make sure that a device with Secure boot enabled is used: this is mentioned in the chip part number, for [[STM32MP13_microprocessor#Part_number_codification|STM32MP13]] and [[STM32MP15_microprocessor#Part_number_codification|STM32MP15]], otherwise the device will become permanently unusable.}}

== stm32key command ==

U-Boot in OpenSTLinux embeds a <code>stm32key</code> command that can be called from [[U-Boot_overview#U-Boot command line interface (CLI)|U-Boot command line interface]] to manage the keys in OTPs.

  {{U-Boot$}} stm32key help
  stm32key - Manage key on STM32

  Usage:
  stm32key list : list the supported key with description
  stm32key select [{{HighlightParam|<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 <code>-y</code> is used to skip the confirmation message.

The name of the used {{HighlightParam|<key>}} is 
* for {{MicroprocessorDevice | device=13}}: {{Highlight|PKHTH}} for authentication and {{Highlight|EDMK}} for encryption
  {{U-Boot$}} stm32key list
  {{Highlight|PKHTH}} : Hash of the 8 ECC Public Keys Hashes Table (ECDSA is the authentication algorithm)
  	OTP24..32
  {{Highlight|EDMK}} : Encryption/Decryption Master Key"
  	OTP92..95
* for {{MicroprocessorDevice | device=15}}: {{Highlight|PKH}} for authentication
  {{U-Boot$}} stm32key list
  {{Highlight|PKH}} : Hash of the ECC Public Key (ECDSA is the authentication algorithm)
  	OTP24..32

==Authentication keys provisioning==

The [[How_to_secure_STM32_MPU#Provisioning|key provisioning]] is the first step to enable the authentication: burn the keys in OTPs with the key hash output file from [[KeyGen_tool|STM32 KeyGen]].

===Select keys===
Key is selected with the command <code>sm32key select {{HighlightParam|<key>}}</code>, with {{HighlightParam|<key>}}=

:* {{Highlight|PKHTH}} for {{MicroprocessorDevice | device=13}}
  {{U-Boot$}} sm32key select {{Highlight|PKHTH}}
  PKHTH selected

:* {{Highlight|PKH}} for {{MicroprocessorDevice | device=15}}
  {{U-Boot$}} sm32key select {{Highlight|PKH}}
  PKH selected

===Load keys file in DDR===

The keys hash file, output file from [[KeyGen_tool|STM32 KeyGen]], must be available in DDR before proceeding the <code>stm32key</code> command;<br/>this file is loaded at {{HighlightParam|0xc0000000}} in the next examples.
<div class="mw-collapsible  mw-collapsed">

The file {{Highlight|publicKeysHash.bin}} can be loaded from a filesystem partition on a storage device by using the <code>load</code> command.
For example, the file {{Highlight|publicKeysHash.bin}} is in the  bootfs (partition {{HighlightParam|7}}) on SD card ({{HighlightParam|mmc0}}):

  {{U-Boot$}} load {{HighlightParam|mmc}} {{HighlightParam|0}}:{{HighlightParam|7}} {{HighlightParam|0xc0000000}} {{Highlight|publicKeysHash.bin}}
  32 bytes read in 50 ms (0 Bytes/s)</div></div>


===Verify keys file in DDR===

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

  {{U-Boot$}} stm32key read {{HighlightParam|0xc0000000}} 

Example for {{MicroprocessorDevice | device=13}} with {{Highlight|PKHTH}}
 {{U-Boot$}} 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 {{MicroprocessorDevice | device=15}} with {{Highlight|PKH}}

 {{U-Boot$}} 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

===Key provisioning===

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

  {{U-Boot$}} stm32key fuse {{HighlightParam|0xc0000000}} 

{{Warning| Verify keys before to confirm the operation, it is a irreversible operation !}}

===Verify keys file in OTP===

After the previous command, the device contains the keys to authenticate images and it can be verified with the command:

  {{U-Boot$}} stm32key read

Result for {{MicroprocessorDevice | device=13}} with {{Highlight|PKHTH}}

 {{U-Boot$}} 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 {{MicroprocessorDevice | device=15}} with {{Highlight|PKH}}

 {{U-Boot$}} 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

==Encryption Decryption Master Key provisioning==

The [[How_to_secure_STM32_MPU#Provisioning|EDMK key provisioning]] is the first step to enable the image decryption.

It is only available on {{MicroprocessorDevice | device=13}}.

===Select EDMK===
Key is selected with the command <code>sm32key select {{HighlightParam|<key>}}</code>, with {{HighlightParam|<key>}}=

:* {{Highlight|EDMK}} for {{MicroprocessorDevice | device=13}}
  {{U-Boot$}} stm32key select {{Highlight|EDMK}}
  EDMK selected

===Load EDMK file in DDR===

The keys file must be available in DDR before proceeding the <code>stm32key</code> command;<br/>this file is loaded at {{HighlightParam|0xc0000000}} in the next examples.
<div class="mw-collapsible  mw-collapsed">

The file {{Highlight|edmk.bin}} can be loaded from a filesystem partition on a storage device by using the <code>load</code> command.
For example, the file {{Highlight|edmk.bin}} is in the bootfs (partition {{HighlightParam|7}}) on SD card ({{HighlightParam|mmc0}}):

  {{U-Boot$}} load {{HighlightParam|mmc}} {{HighlightParam|0}}:{{HighlightParam|7}} {{HighlightParam|0xc0000000}} {{Highlight|edmk.bin}}
  32 bytes read in 50 ms (0 Bytes/s)</div></div>


===Verify EDMK in DDR===

Then you can verify the content of keys files loaded in DDR with the command: <code>sm32key read {{HighlightParam|<addr>}}</code>


Result for {{MicroprocessorDevice | device=13}} with {{Highlight|EDMK}} and <addr>=0xc0000000
  {{U-Boot$}} stm32key read {{HighlightParam|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

===EDMK provisioning===

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

  {{U-Boot$}} stm32key fuse {{HighlightParam|0xc0000000}}

{{Warning| Verify keys before to confirm the operation, it is a irreversible operation !}}

===Verify EDMK in OTP===

After the previous command, the device contains the keys to decrypt the images and it can be verified with the command:

  {{U-Boot$}} stm32key read

Result for {{MicroprocessorDevice | device=13}} with {{Highlight|EDMK}}
 {{U-Boot$}} stm32key read
  EDMK OTP 92: 00000000 lock : {{HighlightParam|50000000}}
  EDMK OTP 93: 00000000 lock : {{HighlightParam|50000000}}
  EDMK OTP 94: 00000000 lock : {{HighlightParam|50000000}}
  EDMK OTP 95: 00000000 lock : {{HighlightParam|50000000}}

Warning the content of the key can't be read, it is masked, but the lock property can be verified to ensure the key as been written.

==Closing the device==

Once the authentication process is confirmed in [[How_to_secure_STM32_MPU#ROM_code_secure_boot_validation|ROM code]] and in TF-A, the device can be [[How_to_secure_STM32_MPU#Device_life_cycle|closed]] to ensure that {{Highlight|only signed images}} can be used.

[[How_to_secure_STM32_MPU#Close_the_device|This operation]] is perform with the U-Boot command:

  {{U-Boot$}} stm32key close

{{Warning| This must not be done on [[STM32MP13_microprocessor#Security_and_Cortex-A7_frequency|STM32MP13]] or [[STM32MP15_microprocessor#Security_and_Cortex-A7_frequency|STM32MP15]] part numbers without '''Secure boot enabled''', otherwise the chip will be bricked and could not be used anymore}}
<noinclude>

[[Category:How to populate boards]]
[[Category:U-Boot|U-Boot - 9]]</noinclude>
Line 211: Line 211:
 
<noinclude>
 
<noinclude>
 
[[Category:How to populate boards]]
 
[[Category:How to populate boards]]
[[Category:U-Boot]]
+
[[Category:U-Boot|U-Boot - 9]]
 
</noinclude>
 
</noinclude>