Difference between revisions of "How to perform Secure Boot from Distribution package"

[quality revision] [pending revision]
m
m (Sign first-stage bootloader binaries)
 
Applicable for STM32MP13x lines, STM32MP15x lines

1 Article purpose[edit]

The purpose of this article is to explain how to perform a secure boot on a STM32MP device with the Distribution package.
To perform this use-case you need to:

These steps are not reversible You must proceed step-by-step (you cannot reproduce in reverseroll back).

Warning white.png Warning
Please take care to Make sure you save the generated signature key generate which are that is put on the STM32MP device. One time Once the signature are is saved and the closed device it's not possible to change it device is "closed", no change is possible

2 Creating signature key[edit]

For To perform the Secure Boot, you need to have binaries signed which with a specific signature key.

If this signature key is already present on the STM32MP device, go directly to Distribution package with signed FIP.

For creating To create the signature key, we need to you must use the STM32MP KeyGen CLI Tool.

See KeyGen tool page for installation and command-line options.
The minimal command to use is:

 STM32MP_KeyGen_CLI -abs <output directory> -pwd <password> -n <number of key>

With:

  • <output directory> = patch to the generated private and public key files (privateKey.pem and publicKey*.pem)
  • <password> = Password of the private key. The password must contain 4 characters at least.
  • <number of key> = number of key pairs, 1 for STM32MP15 or 8 for stm32MP13
Warning white.png Warning
Please save Save the password associated to the signature key and the files generated (publicKey*.pem and privateKey.pem),

they will be are asked for when you need to sign a binary.

2.1 Creating signature key for STM32MP15x lines More info.png[edit]

STM32MP15x lines More info.png device support supports only one couple of Signature signature key pair (Public key / Private Key)
Example:

 STM32MP_KeyGen_CLI -abs stm32mp15-key/ -pwd azerty -n 1
        -------------------------------------------------------------------
                        STM32MP Key Generator v1.0.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 packet 0 generated successfully.
  + public key:       /tmp/key/publicKey00.pem
  + private key:      /tmp/key/privateKey00.pem
  + public hash key:  /tmp/key/publicKeyHash00.bin
  ------------------------------------------------------------
  Hash of table of Hash of {algorithm + public Key} file generated successfully.
  + Hash Hash:  /tmp/key/publicKeysHashHashes.bin

2.2 Creating signature key for STM32MP13x lines Warning.png[edit]

STM32MP13x lines Warning.png device support 8 couples of Signature key supports up to 8 signature key pairs (Public key / Private Key)
Example:

 STM32MP_KeyGen_CLI -abs stm32mp13-key/ -pwd azerty -n 8
       -------------------------------------------------------------------
                       STM32MP Key Generator v1.0.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 packet 0 generated successfully.
 + public key:       /tmp/key/publicKey00.pem
 + private key:      /tmp/key/privateKey00.pem
 + public hash key:  /tmp/key/publicKeyHash00.bin
 ------------------------------------------------------------
 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 packet 1 generated successfully.
 + public key:       /tmp/key/publicKey01.pem
 + private key:      /tmp/key/privateKey01.pem
 + public hash key:  /tmp/key/publicKeyHash01.bin
 ------------------------------------------------------------
 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 packet 2 generated successfully.
 + public key:       /tmp/key/publicKey02.pem
 + private key:      /tmp/key/privateKey02.pem
 + public hash key:  /tmp/key/publicKeyHash02.bin
 ------------------------------------------------------------
 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 must be signed with 
 Keys packet 3 generated successfully.
 + public key:       /tmp/key/publicKey03.pem
 + private key:      /tmp/key/privateKey03.pem
 + public hash key:  /tmp/key/publicKeyHash03.bin
 ------------------------------------------------------------
 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 packet 4 generated successfully.
 + public key:       /tmp/key/publicKey04.pem
 + private key:      /tmp/key/privateKey04.pem
 + public hash key:  /tmp/key/publicKeyHash04.bin
 ------------------------------------------------------------
 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 packet 5 generated successfully.
 + public key:       /tmp/key/publicKey05.pem
 + private key:      /tmp/key/privateKey05.pem
 + public hash key:  /tmp/key/publicKeyHash05.bin
 ------------------------------------------------------------
 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 packet 6 generated successfully.
 + public key:       /tmp/key/publicKey06.pemsoc
 + private key:      /tmp/key/privateKey06.pem
 + public hash key:  /tmp/key/publicKeyHash06.bin
 ------------------------------------------------------------
 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 packet 7 generated successfully.
 + public key:       /tmp/key/publicKey07.pem
 + private key:      /tmp/key/privateKey07.pem
 + public hash key:  /tmp/key/publicKeyHash07.bin
 ------------------------------------------------------------
 Hash of table of Hash of {algorithm + public Key} file generated successfully.
 + Hash Hash:  /tmp/key/publicKeysHashHashes.bin

3 Creating encryption key[edit]

3.1 Creating encryption key for STM32MP13x lines Warning.png[edit]

To perform Secure Boot with encrypted binaries, you must have binaries encrypted with a specific encryption key.

If this signature key is already present on the STM32MP device, go directly to Distribution package with signed FIP.

To create an encryption key, you must generate a random key of 16 bytes'.
On Linux PC:

 dd if=/dev/random of=stm32mp13_encryption_key.bin bs=1 count=16

On Linux with STM32MP_KeyGen_CLI:

 STM32MP_KeyGen_CLI.exe -rand 16 stm32mp13_encryption_key.bin

On Windows with STM32MP_KeyGen_CLI:

 STM32MP_KeyGen_CLI.exe -rand 16 stm32mp13_encryption_key.bin

4 Put signature key on STM32MP[edit]

Info white.png Information
For Demonstration demonstration and TEST purposetest purposes, the signature key can be put on the STM32MP device with a simple U-Boot command on the development board.

For product purposeproduction purposes, it must be set on in the production step, as described in the AN5510: Overview of the secure secret provisioning Secure_Secret_Provisioning_(SSP) on STM32MP1 Series.

34.1 Put the hash key on the device for STM32MP15x lines More info.png[edit]

To manually put the public key hash (PKH) on the STM32MP device with a U-Boot stm32key command, you need to:

  • Put the hash key Public Key Hash' file (publicKeyhash.bin), generated on in the previous section, on bootfs partition
  • Boot the board and stop it on th U-Boot console
  • Load hash the public key hash in DDR
    for example, the hash key file is located on 8th partition of sdcardthe SD card:
 load mmc 0:8 0xc0000000 publicKeyhash.bin
  • Register hash public key hash
 stm32key fuse 0xc0000000

For more information, see How to use U-Boot stm32key command.

34.2 Put hash key on device for STM32MP13x lines Warning.png[edit]

To manually put the public key hash (PKH) on STM32MP device with U-Boot stm32key command, you need to:

  • Put the hash key 'Public Key Hash file (publicKeysHashHashes.bin), generated on previous section, on bootfs partition
  • Boot the board and stop on U-Boot console
  • Load hash public key hash in DDR
    for example, the hash key file is located on 8th partition of sdcard:
 load mmc 0:8 0xc0000000 publicKeysHashHashes.bin
  • Register public key hash
 stm32key fuse 0xc0000000

For more information, see How to use U-Boot stm32key command.

5 Put encryption key on STM32MP[edit]

Info white.png Information
For demonstration and test purposes, the encryption key can be put on the STM32MP device with a simple U-Boot command on the development board.

For production purposes, it must be set in the production step.

5.1 Put an encryption key on the device for STM32MP13x lines Warning.png[edit]

To manually put the key on the STM32MP device with a U-Boot stm32key command, you need to:

  • Put the encryption key file (stm32mp13_encryption_key.bin), generated in the previous section, on the bootfs partition
  • Boot the board and stop it on the U-Boot console
  • Load a hash public key in DDR
    for example, the hash key file is located on 8th partition of the SD card:
 load mmc 0:8 0xc0000000 stm32mp13_encryption_key.bin

 stm32key select EDMK

  • Register encryption key
 stm32key fuse 0xc0000000
  • Verify that the key is registered
 stm32key read

For more information, see How to use U-Boot stm32key command.

4 6 Distribution package with signed FIP[edit]

46.1 Pre-requisiterequisites[edit]

46.2 Generate Distribution package with signed binaries[edit]

Info white.png Information
With this step only FIP binaries are signed
  • source Source the environment of the Distribution package
 source layers/meta-st/scripts/envsetup.sh

Select your DISTRO and your machine

  • Indicate where to found find your Signature key

(in this example we are put the signature key on meta-st-stm32mp layer on key directory)
Add the following lines on your local.conf (on build directory)

For ST32MP15:

 echo 'FIP_SIGN_KEY = "key/stm32mp15/privateKey.pem" ' >> conf/local.conf
 echo 'FIP_SIGN_KEY_stm32mp15 = "key/stm32mp15/privateKey.pem" ' >> conf/local.conf 
 echo 'FIP_SIGN_KEY_EXTERNAL = "1" ' >> conf/local.conf 
 echo 'FIP_SIGN_KEY_PASS = "<password of signature key>" ' >> conf/local.conf
 echo 'TF_A_SIGN_ENABLE = "1" ' >> conf/local.conf 

For ST32MP13:

 echo 'FIP_SIGN_KEY = "key/stm32mp13/privateKey00.pem" ' >> conf/local.conf
 echo 'FIP_SIGN_KEY_stm32mp13 = "key/stm32mp13/privateKey00.pem" ' >> conf/local.conf 
 echo 'FIP_SIGN_KEY_EXTERNAL = "1" ' >> conf/local.conf 
 echo 'FIP_SIGN_KEY_PASS = "<password of signature key>" ' >> conf/local.conf
 echo 'TF_A_SIGN_ENABLE = "1" ' >> conf/local.conf 

Request to sign the FIP file generated:

 echo 'FIP_SIGN_ENABLE = "1" ' >> conf/local.conf 
  • Compile your binaries

bitbake st-image-weston

On tmp-glibc/deploy/images/<machine name>/fip/ you will found the FIP file signed ready to be programmed on board.

5 Sign first

6.3 Generate a Distribution package with encrypted partition binaries for STM32MP13x lines Warning.png[edit]

To enable secure boot with encryption support, you must add DECRYPTION_SUPPORT=aes_gcm with the ENCRYPT_BLx to specify the encrypted binary.

Request encryption support on BL2 TF-A binaries:

 echo 'TF_A_ENCRYPTED_ENABLE = "1" ' >> conf/local.conf

7 Sign first-stage bootloader binaries[edit]

The first stage bootloader binaries = TF-A BL2 are generated unsigned; we need to sign it them manually with the STM32MP_SigningTool_CLI.

For installation and command-line options, see Signing tool.

Info white.png Information
if you need to populate the FSBL binary via STM32CubeProgrammer, you also need to also sign the serial boot TF-A BL2 loaded on in memory

This These tools is are used to sign a binary with STM32 header, with the minimal options to sign the FSBL binary is:

 STM32MP_SigningTool_CLI -pubk <public key> -prvk  <private key> -pwd <password> -t fsbl -of <Option_Flags> -bin FSBL binary not signed>.stm32 -o <FSBL binary signed>.stm32

with:

  • <public key>= the path of the Private Public key files file generated by KeyGen: publicKey*privateKey.pem, 1 for STM32MP15 and 8 for STM32MP13
  • <private key> = the path of the Public Private key file files generated by KeyGen: privateKeypublicKey*.pem, 1 for STM32MP15 and 8 for STM32MP13
  • <password> = pasword used by KeyGen to protect the key files
  • <Option_Flags> = the -of option is required only for STM32MP13, with 0x00000001 value

57.1 Signing first-stage bootloader binaries for STM32MP15x lines More info.png[edit]

For SDCARD:

 STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp15/publicKey.pem -prvk  <path to meta-st-stm32mp>key/stm32mp15/privateKey.pem -pwd <password> -t ssblfsbl -bin arm-trusted-firmware/tf-a-<board name>-sdcard.stm32 -o arm-trusted-firmware/tf-a-<board name>-sdcard_Signed.stm32

For EMMC:

 STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp15/publicKey.pem -prvk  <path to meta-st-stm32mp>key/stm32mp15/privateKey.pem -pwd <password> -t ssblfsbl -bin arm-trusted-firmware/tf-a-<board name>-emmc.stm32 -o arm-trusted-firmware/tf-a-<board name>-emmc_Signed.stm32

For NAND:

 STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp15/publicKey.pem -prvk  <path to meta-st-stm32mp>key/stm32mp15/privateKey.pem -pwd <password> -t ssblfsbl -bin arm-trusted-firmware/tf-a-<board name>-nand.stm32 -o arm-trusted-firmware/tf-a-<board name>-nand_Signed.stm32

For NOR:

 STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp15/publicKey.pem -prvk  <path to meta-st-stm32mp>key/stm32mp15/privateKey.pem -pwd <password> -t ssblfsbl -bin arm-trusted-firmware/tf-a-<board name>-nor.stm32 -o arm-trusted-firmware/tf-a-<board name>-nor_Signed.stm32

For USB (used with STM32CubeProgrammer):

 STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp15/publicKey.pem -prvk  <path to meta-st-stm32mp>key/stm32mp15/privateKey.pem -pwd <password> -t ssblfsbl -bin arm-trusted-firmware/tf-a-<board name>-usb.stm32 -o arm-trusted-firmware/tf-a-<board name>-usb_Signed.stm32

For UART (used with STM32CubeProgrammer):

 STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp15/publicKey.pem -prvk  <path to meta-st-stm32mp>key/stm32mp15/privateKey.pem -pwd <password> -t ssblfsbl -bin arm-trusted-firmware/tf-a-<board name>-uart.stm32 -o arm-trusted-firmware/tf-a-<board name>-uart_Signed.stm32

57.2 Signing first stage bootloader binaries for STM32MP13x lines Warning.png[edit]

For SDCARD:

 STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp13/publicKey*.pem -prvk  <path to meta-st-stm32mp>key/stm32mp15/privateKey00.pem -pwd <password> -t ssblfsbl -of 0x00000001 -bin arm-trusted-firmware/tf-a-<board name>-sdcard.stm32 -o arm-trusted-firmware/tf-a-<board name>-sdcard_Signed.stm32

For EMMC:

 STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp13/publicKey*.pem -prvk  <path to meta-st-stm32mp>key/stm32mp13/privateKey00.pem -pwd <password> -t ssblfsbl -of 0x00000001 -bin arm-trusted-firmware/tf-a-<board name>-emmc.stm32 -o arm-trusted-firmware/tf-a-<board name>-emmc_Signed.stm32

For NAND:

 STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp13/publicKey*.pem -prvk  <path to meta-st-stm32mp>key/stm32mp13/privateKey00.pem -pwd <password> -t ssblfsbl -of 0x00000001 -bin arm-trusted-firmware/tf-a-<board name>-nand.stm32 -o arm-trusted-firmware/tf-a-<board name>-nand_Signed.stm32

For NOR:

 STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp13/publicKey*.pem -prvk  <path to meta-st-stm32mp>key/stm32mp13/privateKey00.pem -pwd <password> -t ssblfsbl -of 0x00000001 -bin arm-trusted-firmware/tf-a-<board name>-nor.stm32 -o arm-trusted-firmware/tf-a-<board name>-nor_Signed.stm32

For USB (used with STM32CubeProgrammer):

 STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp13/publicKey*.pem -prvk  <path to meta-st-stm32mp>key/stm32mp13/privateKey00.pem -pwd <password> -t ssblfsbl -of 0x00000001 -bin arm-trusted-firmware/tf-a-<board name>-usb.stm32 -o arm-trusted-firmware/tf-a-<board name>-usb_Signed.stm32

For UART (used with STM32CubeProgrammer):

 STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp13/publicKey*.pem -prvk  <path to meta-st-stm32mp>key/stm32mp13/privateKey00.pem -pwd <password> -t ssblfsbl -of 0x00000001 -bin arm-trusted-firmware/tf-a-<board name>-uart.stm32 -o arm-trusted-firmware/tf-a-<board name>-uart_Signed.stm32
6

7.3 Encrypt first stage bootloader binaries for STM32MP13x lines Warning.png[edit]

For SDCARD:

 STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp13/publicKey*.pem -prvk  <path to meta-st-stm32mp>key/stm32mp15/privateKey00.pem -pwd <password>  --enc-key  <path to meta-st-stm32mp>key/stm32mp13/stm32mp13_encryption_key.bin -t fsbl   --enc-dc 0x0E5F2025 --image-version 0 -of 0x80000003 -bin arm-trusted-firmware/tf-a-<board name>-sdcard.stm32 -o arm-trusted-firmware/tf-a-<board name>-sdcard_Encrypted.stm32

For EMMC:

 STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp13/publicKey*.pem -prvk  <path to meta-st-stm32mp>key/stm32mp15/privateKey00.pem -pwd <password>  --enc-key  <path to meta-st-stm32mp>key/stm32mp13/stm32mp13_encryption_key.bin -t fsbl   --enc-dc 0x0E5F2025 --image-version 0 -of 0x80000003 -bin arm-trusted-firmware/tf-a-<board name>-emmc.stm32 -o arm-trusted-firmware/tf-a-<board name>-emmc_Encrypted.stm32

For NAND:

 STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp13/publicKey*.pem -prvk  <path to meta-st-stm32mp>key/stm32mp15/privateKey00.pem -pwd <password>  --enc-key  <path to meta-st-stm32mp>key/stm32mp13/stm32mp13_encryption_key.bin -t fsbl   --enc-dc 0x0E5F2025 --image-version 0 -of 0x80000003 -bin arm-trusted-firmware/tf-a-<board name>-nand.stm32 -o arm-trusted-firmware/tf-a-<board name>-nand_Encrypted.stm32

For NOR:

 STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp13/publicKey*.pem -prvk  <path to meta-st-stm32mp>key/stm32mp15/privateKey00.pem -pwd <password>  --enc-key  <path to meta-st-stm32mp>key/stm32mp13/stm32mp13_encryption_key.bin -t fsbl   --enc-dc 0x0E5F2025 --image-version 0 -of 0x80000003 -bin arm-trusted-firmware/tf-a-<board name>-nor.stm32 -o arm-trusted-firmware/tf-a-<board name>-nor_Encrypted.stm32

8 Create FlashLayout for signed binaries[edit]

To populate the correct binaries on the board, you need to create a FlashLayout file with the signed binaries:

  • FSBL = tf-a-*_Signed.stm32
  • FIP = fip-*.bin

Example for FlashLayout_sdcard_stm32mp157f-dk2-optee.tsv:

#Opt	Id	Name	Type	IP	Offset	Binary
- 	0x01	fsbl-boot	Binary	none	0x0	arm-trusted-firmware/tf-a-stm32mp157f-dk2-usb.stm32
-	0x03	fip-boot	FIP	none	0x0	fip/fip-stm32mp157f-dk2-optee.bin
P	0x04	fsbl1	Binary	mmc0	0x00004400	arm-trusted-firmware/tf-a-stm32mp157f-dk2-sdcard.stm32
P	0x05	fsbl2	Binary	mmc0	0x00044400	arm-trusted-firmware/tf-a-stm32mp157f-dk2-sdcard.stm32
P	0x06	metadata1	Binary	mmc0	0x00084400	arm-trusted-firmware/metadata.bin
P	0x07	metadata2	Binary	mmc0	0x000C4400	arm-trusted-firmware/metadata.bin 
P	0x08	fip-a	FIP	mmc0	0x00104400	fip/fip-stm32mp157f-dk2-optee.bin
PED	0x09	fip-b	FIP	mmc0	0x00504400	none
PED	0x0A	u-boot-env	Binary	mmc0	0x00904400	none
P	0x10	bootfs	System	mmc0	0x00984400	st-image-bootfs-openstlinux-weston-stm32mp1.ext4
P	0x11	vendorfs	FileSystem	mmc0	0x04984400	st-image-vendorfs-openstlinux-weston-stm32mp1.ext4
P	0x12	rootfs	FileSystem	mmc0	0x05984400	st-image-weston-openstlinux-weston-stm32mp1.ext4
P	0x13	userfs	FileSystem	mmc0	0x33984400	st-image-userfs-openstlinux-weston-stm32mp1.ext4

You need to update the fsbl1-boot, fip-boot, fsbl1, fsbl2 and fip partitions.
Result:

#Opt	Id	Name	Type	IP	Offset	Binary
- 	0x01	fsbl-boot	Binary	none	0x0	arm-trusted-firmware/tf-a-stm32mp157f-dk2-usb_Signed.stm32
-	0x03	fip-boot	FIP	none	0x0	fip/fip-stm32mp157f-dk2-optee_Signed.bin
P	0x04	fsbl1	Binary	mmc0	0x00004400	arm-trusted-firmware/tf-a-stm32mp157f-dk2- sdcard_Signed.stm32
P	0x05	fsbl2	Binary	mmc0	0x00044400	arm-trusted-firmware/tf-a-stm32mp157f-dk2- sdcard_Signed.stm32
P	0x06	metadata1	Binary	mmc0	0x00084400	arm-trusted-firmware/metadata.bin
P	0x07	metadata2	Binary	mmc0	0x000C4400	arm-trusted-firmware/metadata.bin 
P	0x08	fip-a	FIP	mmc0	0x00104400	fip/fip-stm32mp157f-dk2-optee_Signed.bin
PED	0x09	fip-b	FIP	mmc0	0x00504400	none
PED	0x0A	u-boot-env	Binary	mmc0	0x00904400	none
P	0x10	bootfs	System	mmc0	0x00984400	st-image-bootfs-openstlinux-weston-stm32mp1.ext4
P	0x11	vendorfs	FileSystem	mmc0	0x04984400	st-image-vendorfs-openstlinux-weston-stm32mp1.ext4
P	0x12	rootfs	FileSystem	mmc0	0x05984400	st-image-weston-openstlinux-weston-stm32mp1.ext4
P	0x13	userfs	FileSystem	mmc0	0x33984400	st-image-userfs-openstlinux-weston-stm32mp1.ext4

7 9 Program and test[edit]

To populate the correct binaries on the board with STM32CubeProgrammer, you need to must use the previous FlashLayout file with the signed binaries.

At board boot time on board, you must check the two level of the secure boot: the ROM code secure boot validation, and the TF-A BL2 trusted board boot validation.

8 10 Close the device[edit]

Info white.png Information
For Demonstration demonstration and TEST purposetest purposes, the STM32MP device can be closed with a simple U-Boot command on the development board. For product purposeproduction purposes, it must be set on in production step as described in the AN5510: Overview of the secure secret provisioning (SSP) on STM32MP1 Series.

For more information, see How to secure STM32 MPU.

Warning white.png Warning
Please take care to Make sure you only close the device only if the previous authentication test succeedsucceeded, otherwise the chip will be is bricked and could not be used anymore , and is now unusable.

In U-Boot console:

 
 stm32key close

For more information, see the How to use U-Boot stm32key command.

As soon as the device is closed, and it the operation is irreversible operation, ; the user is forced to only use only signed images.

Warning white.png Warning
This must not be done on STM32MP13 or STM32MP15 part numbers without Secure boot enabled, otherwise the chip will be is bricked and could not be used anymore
9
, and is now unusable.

11 References[edit]


<noinclude>{{ApplicableFor
|MPUs list=STM32MP13x, STM32MP15x
|MPUs checklist=STM32MP13x, STM32MP15x
}}</noinclude>

==Article purpose==
The purpose of this article is to explain how to perform a [[How_to_secure_STM32_MPU|secure boot on a STM32MP device]] with the Distribution package.<br>

To perform this use-case you need to:
* [[#Create#Creating signature key|Create signature key]] with [[KeyGen tool]] (if is not already done) 
* [[#Put signature key on STM32MP|Put signature key on STM32MP]] (if is not already done)
* Compile a [[#Distribution package with signed FIP|Distribution package with signed FIP]]
* [[#Sign first stage bootloader binaries|Sign first stage bootloader binaries]] with [[Signing tool]]
* [[#Create FlashLayout for signed binaries|Create FlashLayout for signed binaries]]
* [[#Program and test|Program and test]]
* [[#Close the device|Close the device]] (if is not already done)
These steps are not reversible (you cannot reproduce in reverse).

{{Warning | Please take care to save the signature key generate which are put on STM32MP device. One time the signature are saved and the '''closed''' device it's not possible to change it}}

==Creating signature key==
For perform You must proceed step-by-step (you cannot roll back).

{{Warning | Make sure you save the generated signature key that is put on the STM32MP device. Once the signature is saved and the device is "closed", no change is possible}}

==Creating signature key==
To perform the Secure Boot, you need to have  binaries signed whichwith a specific signature key. 

If this signature key is already present on the STM32MP device, go directly to  [[#Distribution package with signed FIP|Distribution package with signed FIP]].
For creating signature key, we need to use To create the signature key, you must use  the '''STM32MP KeyGen CLI Tool'''.

See [[KeyGen tool]] page for installation and command -line options.<br>

The minimal command to use is:


 {{PC$}} STM32MP_KeyGen_CLI {{Highlight|-abs}} {{HighlightParam|<output directory>}} {{Highlight|-pwd}} {{HighlightParam|<password>}} {{Highlight|-n}} {{HighlightParam|<number of key>}}
With:
* {{HighlightParam|<output directory>}} = patch to the generated private and public key files (privateKey.pem and publicKey*.pem)
* {{HighlightParam|<password>}} = Password of the private key. The password must contain 4 characters at least. 
* {{HighlightParam|<number of key>}} = number of key pairs, 1 for STM32MP15 or 8 for stm32MP13

{{warning| Please save Save the <u>password</u> associated to the signature key and the <u>files generated</u> (publicKey*.pem and privateKey.pem),<br/>

they will be are asked for when you need to sign a binary.}}

===Creating signature key for {{MicroprocessorDevice | device=15}}===
{{MicroprocessorDevice | device=15}} device supportsupports only one couple of Signature key signature key pair (Public key / Private Key)<br/>

Example:
 {{PC$}} STM32MP_KeyGen_CLI -abs stm32mp15-key/ -pwd azerty -n 1
         -------------------------------------------------------------------
                         STM32MP Key Generator v1.0.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 packet 0 generated successfully.
   + public key:       /tmp/key/publicKey00.pem
   + private key:      /tmp/key/privateKey00.pem
   + public hash key:  /tmp/key/publicKeyHash00.bin
   ------------------------------------------------------------
   Hash of table of Hash of {algorithm + public Key} file generated successfully.
   + Hash Hash:  /tmp/key/publicKeysHashHashes.bin

===Creating signature key for {{MicroprocessorDevice | device=13}}===
{{MicroprocessorDevice | device=13}} device support 8 couples of Signature key supports up to 8 signature key pairs (Public key / Private Key)<br/>

Example:
 {{PC$}} STM32MP_KeyGen_CLI -abs stm32mp13-key/ -pwd azerty -n 8<pre>

       -------------------------------------------------------------------
                       STM32MP Key Generator v1.0.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 packet 0 generated successfully.
 + public key:       /tmp/key/publicKey00.pem
 + private key:      /tmp/key/privateKey00.pem
 + public hash key:  /tmp/key/publicKeyHash00.bin
 ------------------------------------------------------------
 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 packet 1 generated successfully.
 + public key:       /tmp/key/publicKey01.pem
 + private key:      /tmp/key/privateKey01.pem
 + public hash key:  /tmp/key/publicKeyHash01.bin
 ------------------------------------------------------------
 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 packet 2 generated successfully.
 + public key:       /tmp/key/publicKey02.pem
 + private key:      /tmp/key/privateKey02.pem
 + public hash key:  /tmp/key/publicKeyHash02.bin
 ------------------------------------------------------------
 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 must be signed with 
 Keys packet 3 generated successfully.
 + public key:       /tmp/key/publicKey03.pem
 + private key:      /tmp/key/privateKey03.pem
 + public hash key:  /tmp/key/publicKeyHash03.bin
 ------------------------------------------------------------
 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 packet 4 generated successfully.
 + public key:       /tmp/key/publicKey04.pem
 + private key:      /tmp/key/privateKey04.pem
 + public hash key:  /tmp/key/publicKeyHash04.bin
 ------------------------------------------------------------
 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 packet 5 generated successfully.
 + public key:       /tmp/key/publicKey05.pem
 + private key:      /tmp/key/privateKey05.pem
 + public hash key:  /tmp/key/publicKeyHash05.bin
 ------------------------------------------------------------
 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 packet 6 generated successfully.
 + public key:       /tmp/key/publicKey06.pemsoc
 + private key:      /tmp/key/privateKey06.pem
 + public hash key:  /tmp/key/publicKeyHash06.bin
 ------------------------------------------------------------
 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 packet 7 generated successfully.
 + public key:       /tmp/key/publicKey07.pem
 + private key:      /tmp/key/privateKey07.pem
 + public hash key:  /tmp/key/publicKeyHash07.bin
 ------------------------------------------------------------
 Hash of table of Hash of {algorithm + public Key} file generated successfully.
 + Hash Hash:  /tmp/key/publicKeysHashHashes.bin
</pre>


==Creating encryption key==

===Creating encryption key for {{MicroprocessorDevice | device=13}}===

To perform Secure Boot with encrypted binaries, you must have binaries encrypted with a specific encryption key. 

If this signature key is already present on the STM32MP device, go directly to  [[#Distribution package with signed FIP|Distribution package with signed FIP]].

To create an encryption key, you must generate a random key of 16 bytes'.<br/>

On Linux PC: 
 {{PC$}} dd if=/dev/random of=stm32mp13_encryption_key.bin bs=1 count=16

On Linux with STM32MP_KeyGen_CLI:
 {{PC$}} STM32MP_KeyGen_CLI.exe -rand 16 stm32mp13_encryption_key.bin

On Windows with STM32MP_KeyGen_CLI:
 {{PC$}} STM32MP_KeyGen_CLI.exe -rand 16 stm32mp13_encryption_key.bin

==Put signature key on STM32MP ==
{{info| For Demonstrationdemonstration and TEST purposetest purposes, the signature key can be put on the STM32MP device with a simple U-Boot command on the  development board.<br/>

For product purposeproduction purposes, it must be set on in the production step, as described in the [[STM32MP15 resources#AN5510|AN5510: Overview of the secure secret provisioning (SSP) on STM32MP1 Series]].}} 
[[Secure_Secret_Provisioning_(SSP)]].}} 

===Put the hash key on the device for {{MicroprocessorDevice | device=15}}===
To manually put the public key hash (PKH) on the STM32MP device with a U-Boot stm32key command, you need to:
* Put the ''Public Key Hash''' file (publicKeyhash.bin), generated in the previous section, on bootfs partition 
* Boot the board and stop it on th U-Boot console
* Load the public key hash in DDR<br/>for example, the hash key file is located on 8th partition of the SD card: 
 {{U-Boot$}} load mmc 0:8 0xc0000000 publicKeyhash.bin
* Register public key hash
 {{U-Boot$}} stm32key fuse 0xc0000000

For more information, see  [[How to use U-Boot stm32key command]].
===Put hash key on device for {{MicroprocessorDevice | device=1513}}===
To manually put the public key hash (PKH) on STM32MP device with U-Boot stm32key command, you need to:
* Put the '''hash key''' file (publicKeyhashPublic Key Hash'' file (publicKeysHashHashes.bin), generated on previous section, on bootfs partition 
* Boot the board and stop on U-Boot console
* Load hash public key hash in DDR<br/>for example, the hash key file is located on 8th partition of sdcard: {{U-Boot$}} load mmc 0:8 0xc0000000 publicKeyhashpublicKeysHashHashes.bin
* Register hash public key  hash{{U-Boot$}} stm32key fuse 0xc0000000

For more information, see  [[How to use U-Boot stm32key command]].

===Put hash key on Put encryption key on STM32MP==

{{info| For demonstration and test purposes, the encryption key can be put on the STM32MP device with a simple U-Boot command on the development board.<br/>

For production purposes, it must be set in the production step.}} 

===Put an encryption key on the device for {{MicroprocessorDevice | device=13}}===
To manually put the key on the STM32MP device with a U-Boot stm32key command, you need to:
* Put the '''hashencryption key''' file (publicKeysHashHashes.bin), generated on previous section, on ''stm32mp13_encryption_key.bin''), generated in the previous section, on the bootfs partition 
* Boot the board and stop it on the U-Boot console
* Load a hash public key in DDR<br/>for example, the hash key file is located on 8th partition of sdcardthe SD card:
 {{U-Boot$}} load mmc 0:8 0xc0000000 publicKeysHashHashesstm32mp13_encryption_key.bin
* Register hash publicSelect the EDMK key  {{U-Boot$}} stm32key fuse 0xc0000000
([[How_to_use_U-Boot_stm32key_command#Encryption_Decryption_Master_Key_provisioning|How to use U-Boot stm32key command|]])
 {{U-Boot$}} stm32key select EDMK
* Register encryption key
 {{U-Boot$}} stm32key fuse 0xc0000000
* Verify that the key is registered
 {{U-Boot$}} stm32key readFor more information, see  [[How to use U-Boot stm32key command]].

==Distribution package with signed FIP==

===Pre-requisiterequisites===
* Having the Signature Key (Public Key(s), Private Key(s), Hash key file, password)
* Having getobtained the [[STM32MP1_Distribution_Package|STM32MP1 Distribution Package]]

===Generate Distribution package with signed binaries===
{{info|With this step only FIP binaries are signed}}

* sourceSource the environment of the Distribution package 
 {{PC$}} source layers/meta-st/scripts/envsetup.sh
Select your DISTRO and your machine
* Indicate where to foundfind your Signature key
(in this example we are put the signature key on meta-st-stm32mp layer on key directory)<br/>

Add the following lines on your local.conf (on build directory)

For ST32MP15:
 {{PC$}} echo 'FIP_SIGN_KEY = "key/stm32mp15/privateKey.pem" ' >> conf/local.conf {{PC$}} echo 'FIP_SIGN_KEY_stm32mp15 = "key/stm32mp15/privateKey.pem" ' >> conf/local.conf {{PC$}} echo 'FIP_SIGN_KEY_EXTERNAL = "1" ' >> conf/local.conf 
 {{PC$}} echo 'FIP_SIGN_KEY_PASS = "<password of signature key>" ' >> conf/local.conf
 {{PC$}} echo 'TF_A_SIGN_ENABLE = "1" ' >> conf/local.conf 

For ST32MP13:
 {{PC$}} echo 'FIP_SIGN_KEY = "key/stm32mp13/privateKey00.pem" ' >> conf/local.conf {{PC$}} echo 'FIP_SIGN_KEY_stm32mp13 = "key/stm32mp13/privateKey00.pem" ' >> conf/local.conf {{PC$}} echo 'FIP_SIGN_KEY_EXTERNAL = "1" ' >> conf/local.conf 
 {{PC$}} echo 'FIP_SIGN_KEY_PASS = "<password of signature key>" ' >> conf/local.conf
 {{PC$}} echo 'TF_A_SIGN_ENABLE = "1" ' >> conf/local.conf 

Request to sign the FIP file generated:
 {{PC$}} echo 'FIP_SIGN_ENABLE = "1" ' >> conf/local.conf 

* Compile your binaries
{{PC$}} bitbake st-image-weston

On '''tmp-glibc/deploy/images/<machine name>/fip/''' you will found the FIP file signed ready to be programmed on board.

==Sign first stage bootloader binaries===Generate a Distribution package with encrypted partition binaries for {{MicroprocessorDevice | device=13}}===
To enable secure boot with encryption support, you must add '''DECRYPTION_SUPPORT=aes_gcm''' with the '''ENCRYPT_BLx''' to specify the encrypted binary.<br/>


Request encryption support on BL2 TF-A binaries:
 {{PC$}} echo 'TF_A_ENCRYPTED_ENABLE = "1" ' >> conf/local.conf

==Sign first-stage bootloader binaries==
{{ReviewsComments | [[User:Lionel Vitte|Lionel Vitte]] ([[User talk:Lionel Vitte|talk]]) 10:31, 6 December 2022 (CET) - Is it 'first-stage' of 'first stage'?}}The first stage bootloader binaries = TF-A BL2 are generated unsigned; we need to sign itthem manually with the '''STM32MP_SigningTool_CLI'''.

For installation and command -line options, see [[Signing tool]].

{{info| if you need to populate the FSBL binary via STM32CubeProgrammer, you also need to also sign the serial boot TF-A BL2 loaded onin memory}}
ThisThese tools isare used to sign a binary with [[STM32 header for binary files|STM32 header]], with the minimal options to sign the FSBL binary is:
 {{PC$}} STM32MP_SigningTool_CLI {{Highlight|-pubk}} {{HighlightParam|<public key>}} {{Highlight|-prvk}}  {{HighlightParam|<private key>}} {{Highlight|-pwd}} {{HighlightParam|<password>}} {{Highlight|-t}} {{HighlightParam|fsbl}} {{Highlight|-of}} {{HighlightParam|<Option_Flags>}} {{Highlight|-bin}} {{HighlightParam|FSBL binary not signed>.stm32}} {{Highlight|-o}} {{HighlightParam|<FSBL binary signed>.stm32}}

with:
* {{HighlightParam|<public key>}}= the path of the PrivatePublic key filesfile generated by KeyGen: publicKey*privateKey.pem, 1 for STM32MP15 and 8 for STM32MP13
* {{HighlightParam|<private key>}} = 

{{ReviewsComments | [[User:Lionel Vitte|Lionel Vitte]] ([[User talk:Lionel Vitte|talk]]) 10:31, 6 December 2022 (CET) - Really privateKey.pem with the parameter <public key>?}}
* {{HighlightParam|<private key>}} =  the path of the PublicPrivate key filefiles generated by KeyGen: privateKeypublicKey*.pem
, 1 for STM32MP15 and 8 for STM32MP13
{{ReviewsComments | [[User:Lionel Vitte|Lionel Vitte]] ([[User talk:Lionel Vitte|talk]]) 10:31, 6 December 2022 (CET) - Really publicy.pem with the parameter <private key>?}}* {{HighlightParam|<password>}} = pasword used by KeyGen to protect the key files
* {{HighlightParam|<Option_Flags>}} = the {{Highlight|-of}} option is required only for STM32MP13, with 0x00000001 value

===Signing first -stage bootloader binaries for {{MicroprocessorDevice | device=15}}===
For SDCARD:
 {{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp15/publicKey.pem -prvk  <path to meta-st-stm32mp>key/stm32mp15/privateKey.pem -pwd <password> -t ssblfsbl -bin arm-trusted-firmware/tf-a-<board name>-sdcard.stm32 -o arm-trusted-firmware/tf-a-<board name>-sdcard_Signed.stm32
For EMMC:
 {{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp15/publicKey.pem -prvk  <path to meta-st-stm32mp>key/stm32mp15/privateKey.pem -pwd <password> -t ssblfsbl -bin arm-trusted-firmware/tf-a-<board name>-emmc.stm32 -o arm-trusted-firmware/tf-a-<board name>-emmc_Signed.stm32
For NAND:
 {{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp15/publicKey.pem -prvk  <path to meta-st-stm32mp>key/stm32mp15/privateKey.pem -pwd <password> -t ssblfsbl -bin arm-trusted-firmware/tf-a-<board name>-nand.stm32 -o arm-trusted-firmware/tf-a-<board name>-nand_Signed.stm32
For NOR:
 {{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp15/publicKey.pem -prvk  <path to meta-st-stm32mp>key/stm32mp15/privateKey.pem -pwd <password> -t ssblfsbl -bin arm-trusted-firmware/tf-a-<board name>-nor.stm32 -o arm-trusted-firmware/tf-a-<board name>-nor_Signed.stm32
For USB (used with STM32CubeProgrammer):
 {{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp15/publicKey.pem -prvk  <path to meta-st-stm32mp>key/stm32mp15/privateKey.pem -pwd <password> -t ssblfsbl -bin arm-trusted-firmware/tf-a-<board name>-usb.stm32 -o arm-trusted-firmware/tf-a-<board name>-usb_Signed.stm32
For UART (used with STM32CubeProgrammer):
 {{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp15/publicKey.pem -prvk  <path to meta-st-stm32mp>key/stm32mp15/privateKey.pem -pwd <password> -t ssblfsbl -bin arm-trusted-firmware/tf-a-<board name>-uart.stm32 -o arm-trusted-firmware/tf-a-<board name>-uart_Signed.stm32

===Signing first stage bootloader binaries for {{MicroprocessorDevice | device=13}}===
For SDCARD:
 {{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp13/publicKey*.pem -prvk  <path to meta-st-stm32mp>key/stm32mp15/privateKey00.pem -pwd <password> -t ssblfsbl '''-of 0x00000001''' -bin arm-trusted-firmware/tf-a-<board name>-sdcard.stm32 -o arm-trusted-firmware/tf-a-<board name>-sdcard_Signed.stm32
For EMMC:
 {{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp13/publicKey*.pem -prvk  <path to meta-st-stm32mp>key/stm32mp13/privateKey00.pem -pwd <password> -t ssblfsbl '''-of 0x00000001''' -bin arm-trusted-firmware/tf-a-<board name>-emmc.stm32 -o arm-trusted-firmware/tf-a-<board name>-emmc_Signed.stm32
For NAND:
 {{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp13/publicKey*.pem -prvk  <path to meta-st-stm32mp>key/stm32mp13/privateKey00.pem -pwd <password> -t ssblfsbl '''-of 0x00000001''' -bin arm-trusted-firmware/tf-a-<board name>-nand.stm32 -o arm-trusted-firmware/tf-a-<board name>-nand_Signed.stm32
For NOR:
 {{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp13/publicKey*.pem -prvk  <path to meta-st-stm32mp>key/stm32mp13/privateKey00.pem -pwd <password> -t ssblfsbl '''-of 0x00000001''' -bin arm-trusted-firmware/tf-a-<board name>-nor.stm32 -o arm-trusted-firmware/tf-a-<board name>-nor_Signed.stm32
For USB (used with STM32CubeProgrammer):
 {{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp13/publicKey*.pem -prvk  <path to meta-st-stm32mp>key/stm32mp13/privateKey00.pem -pwd <password> -t ssblfsbl '''-of 0x00000001''' -bin arm-trusted-firmware/tf-a-<board name>-usb.stm32 -o arm-trusted-firmware/tf-a-<board name>-usb_Signed.stm32
For UART (used with STM32CubeProgrammer):
 {{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp13/publicKey*.pem -prvk  <path to meta-st-stm32mp>key/stm32mp13/privateKey00.pem -pwd <password> -t ssblfsbl '''-of 0x00000001''' -bin arm-trusted-firmware/tf-a-<board name>-uart.stm32 -o arm-trusted-firmware/tf-a-<board name>-uart_Signed.stm32

===Encrypt first stage bootloader binaries for {{MicroprocessorDevice | device=13}}===
For SDCARD:
 {{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp13/publicKey*.pem -prvk  <path to meta-st-stm32mp>key/stm32mp15/privateKey00.pem -pwd <password>  --enc-key  <path to meta-st-stm32mp>key/stm32mp13/stm32mp13_encryption_key.bin -t fsbl  ''' --enc-dc 0x0E5F2025 --image-version 0 -of 0x80000003''' -bin arm-trusted-firmware/tf-a-<board name>-sdcard.stm32 -o arm-trusted-firmware/tf-a-<board name>-sdcard_Encrypted.stm32

For EMMC:
 {{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp13/publicKey*.pem -prvk  <path to meta-st-stm32mp>key/stm32mp15/privateKey00.pem -pwd <password>  --enc-key  <path to meta-st-stm32mp>key/stm32mp13/stm32mp13_encryption_key.bin -t fsbl  ''' --enc-dc 0x0E5F2025 --image-version 0 -of 0x80000003''' -bin arm-trusted-firmware/tf-a-<board name>-emmc.stm32 -o arm-trusted-firmware/tf-a-<board name>-emmc_Encrypted.stm32

For NAND:
 {{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp13/publicKey*.pem -prvk  <path to meta-st-stm32mp>key/stm32mp15/privateKey00.pem -pwd <password>  --enc-key  <path to meta-st-stm32mp>key/stm32mp13/stm32mp13_encryption_key.bin -t fsbl  ''' --enc-dc 0x0E5F2025 --image-version 0 -of 0x80000003''' -bin arm-trusted-firmware/tf-a-<board name>-nand.stm32 -o arm-trusted-firmware/tf-a-<board name>-nand_Encrypted.stm32

For NOR:
 {{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp13/publicKey*.pem -prvk  <path to meta-st-stm32mp>key/stm32mp15/privateKey00.pem -pwd <password>  --enc-key  <path to meta-st-stm32mp>key/stm32mp13/stm32mp13_encryption_key.bin -t fsbl  ''' --enc-dc 0x0E5F2025 --image-version 0 -of 0x80000003''' -bin arm-trusted-firmware/tf-a-<board name>-nor.stm32 -o arm-trusted-firmware/tf-a-<board name>-nor_Encrypted.stm32

==Create FlashLayout for signed binaries==
To populate the correct binaries on the board, you need to create a FlashLayout file with the signed binaries:
* FSBL = tf-a-*_Signed.stm32
* FIP = fip-*.bin

Example for FlashLayout_sdcard_stm32mp157f-dk2-optee.tsv:
 #Opt	Id	Name	Type	IP	Offset	Binary
 - 	0x01	fsbl-boot	Binary	none	0x0	arm-trusted-firmware/tf-a-stm32mp157f-dk2-usb.stm32
 -	0x03	fip-boot	FIP	none	0x0	fip/fip-stm32mp157f-dk2-optee.bin
 P	0x04	fsbl1	Binary	mmc0	0x00004400	arm-trusted-firmware/tf-a-stm32mp157f-dk2-sdcard.stm32
 P	0x05	fsbl2	Binary	mmc0	0x00044400	arm-trusted-firmware/tf-a-stm32mp157f-dk2-sdcard.stm32
 P	0x06	metadata1	Binary	mmc0	0x00084400	arm-trusted-firmware/metadata.bin
 P	0x07	metadata2	Binary	mmc0	0x000C4400	arm-trusted-firmware/metadata.bin 
 P	0x08	fip-a	FIP	mmc0	0x00104400	fip/fip-stm32mp157f-dk2-optee.bin
 PED	0x09	fip-b	FIP	mmc0	0x00504400	none
 PED	0x0A	u-boot-env	Binary	mmc0	0x00904400	none
 P	0x10	bootfs	System	mmc0	0x00984400	st-image-bootfs-openstlinux-weston-stm32mp1.ext4
 P	0x11	vendorfs	FileSystem	mmc0	0x04984400	st-image-vendorfs-openstlinux-weston-stm32mp1.ext4
 P	0x12	rootfs	FileSystem	mmc0	0x05984400	st-image-weston-openstlinux-weston-stm32mp1.ext4
 P	0x13	userfs	FileSystem	mmc0	0x33984400	st-image-userfs-openstlinux-weston-stm32mp1.ext4

You need to update the '''fsbl1-boot''', '''fip-boot''', '''fsbl1''', '''fsbl2''' and '''fip''' partitions.<br/>

Result:
 #Opt	Id	Name	Type	IP	Offset	Binary
 - 	0x01	fsbl-boot	Binary	none	0x0	'''arm-trusted-firmware/tf-a-stm32mp157f-dk2-usb_Signed.stm32'''
 -	0x03	fip-boot	FIP	none	0x0	'''fip/fip-stm32mp157f-dk2-optee_Signed.bin'''
 P	0x04	fsbl1	Binary	mmc0	0x00004400	'''arm-trusted-firmware/tf-a-stm32mp157f-dk2- sdcard_Signed.stm32'''
 P	0x05	fsbl2	Binary	mmc0	0x00044400	'''arm-trusted-firmware/tf-a-stm32mp157f-dk2- sdcard_Signed.stm32'''
 P	0x06	metadata1	Binary	mmc0	0x00084400	arm-trusted-firmware/metadata.bin
 P	0x07	metadata2	Binary	mmc0	0x000C4400	arm-trusted-firmware/metadata.bin 
 P	0x08	fip-a	FIP	mmc0	0x00104400	'''fip/fip-stm32mp157f-dk2-optee_Signed.bin'''
 PED	0x09	fip-b	FIP	mmc0	0x00504400	none
 PED	0x0A	u-boot-env	Binary	mmc0	0x00904400	none
 P	0x10	bootfs	System	mmc0	0x00984400	st-image-bootfs-openstlinux-weston-stm32mp1.ext4
 P	0x11	vendorfs	FileSystem	mmc0	0x04984400	st-image-vendorfs-openstlinux-weston-stm32mp1.ext4
 P	0x12	rootfs	FileSystem	mmc0	0x05984400	st-image-weston-openstlinux-weston-stm32mp1.ext4
 P	0x13	userfs	FileSystem	mmc0	0x33984400	st-image-userfs-openstlinux-weston-stm32mp1.ext4

==Program and test==
To populate the correct binaries on the board with STM32CubeProgrammer, you need to must use the previous FlashLayout file with the signed binaries.

At board boot time on board, you must check [[How_to_secure_STM32_MPU#Firmware_secure_boot|the two level of the secure boot]]: the ROM code secure boot validation, and the TF-A BL2 trusted board boot validation.

==Close the device==

{{info| For Demonstrationdemonstration and TEST purposetest purposes, the STM32MP device can be closed with a simple U-Boot command on the development board. For product purposeproduction purposes, it must be set onin production step as described in the [[STM32MP15 resources#AN5510|AN5510: Overview of the secure secret provisioning (SSP) on STM32MP1 Series]].}} 

For more information, see  [[How_to_secure_STM32_MPU#Close_the_device|How to secure STM32 MPU]].

{{Warning | Please take care toMake sure you only close the device only if the previous authentication test succeedsucceeded, otherwise the chip will be is bricked, and could not be used anymoreis now unusable.}}

In U-Boot console:
  {{U-Boot$}} stm32key close

For more information, see the [[How to use U-Boot stm32key command]].

As soon as the device is closed, and itthe operation is irreversible operation, ; the user is forced to only use only signed images.

{{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 is bricked, and could not be used anymoreis now unusable.}}

== References==<references />
<noinclude>

[[Category:How_to_customize_software]]
{{PublicationRequestId | 24642 | 2022-09-26| ticket entered by the review has been cancelled to launch a new Experts review. Reuse this number to start a new TW review when needed}}</noinclude>
(36 intermediate revisions by 8 users not shown)
Line 3: Line 3:
 
|MPUs checklist=STM32MP13x, STM32MP15x
 
|MPUs checklist=STM32MP13x, STM32MP15x
 
}}</noinclude>
 
}}</noinclude>
  +
 
==Article purpose==
 
==Article purpose==
The purpose of this article is to explain how to perform a [[How_to_secure_STM32_MPU|secure boot on a STM32MP device]] with Distribution package.
+
The purpose of this article is to explain how to perform a [[How_to_secure_STM32_MPU|secure boot on a STM32MP device]] with the Distribution package.
 
<br>
 
<br>
 
To perform this use-case you need to:
 
To perform this use-case you need to:
* [[#Create signature key|Create signature key]] with [[KeyGen tool]] (if is not already done)  
+
* [[#Creating signature key|Create signature key]] with [[KeyGen tool]] (if not already done)  
* [[#Put signature key on STM32MP|Put signature key on STM32MP]] (if is not already done)
+
* [[#Put signature key on STM32MP|Put signature key on STM32MP]] (if not already done)
 
* Compile a [[#Distribution package with signed FIP|Distribution package with signed FIP]]
 
* Compile a [[#Distribution package with signed FIP|Distribution package with signed FIP]]
 
* [[#Sign first stage bootloader binaries|Sign first stage bootloader binaries]] with [[Signing tool]]
 
* [[#Sign first stage bootloader binaries|Sign first stage bootloader binaries]] with [[Signing tool]]
 
* [[#Create FlashLayout for signed binaries|Create FlashLayout for signed binaries]]
 
* [[#Create FlashLayout for signed binaries|Create FlashLayout for signed binaries]]
 
* [[#Program and test|Program and test]]
 
* [[#Program and test|Program and test]]
* [[#Close the device|Close the device]] (if is not already done)
+
* [[#Close the device|Close the device]] (if not already done)
   
These steps are not reversible (you cannot reproduce in reverse).
+
You must proceed step-by-step (you cannot roll back).
   
{{Warning | Please take care to save the signature key generate which are put on STM32MP device. One time the signature are saved and the '''closed''' device it's not possible to change it}}
+
{{Warning | Make sure you save the generated signature key that is put on the STM32MP device. Once the signature is saved and the device is "closed", no change is possible}}
   
 
==Creating signature key==
 
==Creating signature key==
For perform Secure Boot, you need to have binaries signed which a specific signature key.  
+
To perform the Secure Boot, you need to have binaries signed with a specific signature key.  
   
If this signature key is already present STM32MP device, go directly to  [[#Distribution package with signed FIP|Distribution package with signed FIP]].
+
If this signature key is already present on the STM32MP device, go directly to  [[#Distribution package with signed FIP|Distribution package with signed FIP]].
   
For creating signature key, we need to use '''STM32MP KeyGen CLI Tool'''.
+
To create the signature key, you must use the '''STM32MP KeyGen CLI Tool'''.
   
See [[KeyGen tool]] page for installation and command line options.<br>
+
See [[KeyGen tool]] page for installation and command-line options.<br>
The minimal command to use is
+
The minimal command to use is:
   
 
  {{PC$}} STM32MP_KeyGen_CLI {{Highlight|-abs}} {{HighlightParam|<output directory>}} {{Highlight|-pwd}} {{HighlightParam|<password>}} {{Highlight|-n}} {{HighlightParam|<number of key>}}
 
  {{PC$}} STM32MP_KeyGen_CLI {{Highlight|-abs}} {{HighlightParam|<output directory>}} {{Highlight|-pwd}} {{HighlightParam|<password>}} {{Highlight|-n}} {{HighlightParam|<number of key>}}
Line 35: Line 36:
 
* {{HighlightParam|<number of key>}} = number of key pairs, 1 for STM32MP15 or 8 for stm32MP13
 
* {{HighlightParam|<number of key>}} = number of key pairs, 1 for STM32MP15 or 8 for stm32MP13
   
{{warning| Please save the <u>password</u> associated to signature key and the <u>files generated</u> (publicKey*.pem and privateKey.pem),<br/>
+
{{warning| Save the <u>password</u> associated to the signature key and the <u>files generated</u> (publicKey*.pem and privateKey.pem),<br/>
they will be asked when you need to sign a binary.}}
+
they are asked for when you need to sign a binary.}}
   
 
===Creating signature key for {{MicroprocessorDevice | device=15}}===
 
===Creating signature key for {{MicroprocessorDevice | device=15}}===
{{MicroprocessorDevice | device=15}} device support only one couple of Signature key (Public key / Private Key)<br/>
+
{{MicroprocessorDevice | device=15}} device supports only one signature key pair (Public key / Private Key)<br/>
 
Example:
 
Example:
 
  {{PC$}} STM32MP_KeyGen_CLI -abs stm32mp15-key/ -pwd azerty -n 1
 
  {{PC$}} STM32MP_KeyGen_CLI -abs stm32mp15-key/ -pwd azerty -n 1
Line 61: Line 62:
   
 
===Creating signature key for {{MicroprocessorDevice | device=13}}===
 
===Creating signature key for {{MicroprocessorDevice | device=13}}===
{{MicroprocessorDevice | device=13}} device support 8 couples of Signature key (Public key / Private Key)<br/>
+
{{MicroprocessorDevice | device=13}} device supports up to 8 signature key pairs (Public key / Private Key)<br/>
 
Example:
 
Example:
 
  {{PC$}} STM32MP_KeyGen_CLI -abs stm32mp13-key/ -pwd azerty -n 8
 
  {{PC$}} STM32MP_KeyGen_CLI -abs stm32mp13-key/ -pwd azerty -n 8
Line 154: Line 155:
   
 
</pre>
 
</pre>
  +
  +
==Creating encryption key==
  +
  +
===Creating encryption key for {{MicroprocessorDevice | device=13}}===
  +
  +
To perform Secure Boot with encrypted binaries, you must have binaries encrypted with a specific encryption key.
  +
  +
If this signature key is already present on the STM32MP device, go directly to  [[#Distribution package with signed FIP|Distribution package with signed FIP]].
  +
  +
To create an encryption key, you must generate a random key of 16 bytes'.<br/>
  +
On Linux PC:
  +
{{PC$}} dd if=/dev/random of=stm32mp13_encryption_key.bin bs=1 count=16
  +
  +
On Linux with STM32MP_KeyGen_CLI:
  +
{{PC$}} STM32MP_KeyGen_CLI.exe -rand 16 stm32mp13_encryption_key.bin
  +
  +
On Windows with STM32MP_KeyGen_CLI:
  +
{{PC$}} STM32MP_KeyGen_CLI.exe -rand 16 stm32mp13_encryption_key.bin
   
 
==Put signature key on STM32MP ==
 
==Put signature key on STM32MP ==
{{info| For Demonstration and TEST purpose, the signature key can be put on STM32MP device with a simple U-Boot command on development board.<br/>
+
{{info| For demonstration and test purposes, the signature key can be put on the STM32MP device with a simple U-Boot command on the  development board.<br/>
For product purpose, it must be set on production step as described in the [[STM32MP15 resources#AN5510|AN5510: Overview of the secure secret provisioning (SSP) on STM32MP1 Series]].}}  
+
For production purposes, it must be set in the production step, as described in [[Secure_Secret_Provisioning_(SSP)]].}}  
   
===Put hash key on device for {{MicroprocessorDevice | device=15}}===
+
===Put the hash key on the device for {{MicroprocessorDevice | device=15}}===
To manually put the key on STM32MP device with U-Boot stm32key command, you need to:
+
To manually put the public key hash (PKH) on the STM32MP device with a U-Boot stm32key command, you need to:
* Put the '''hash key''' file (publicKeyhash.bin), generated on previous section, on bootfs partition  
+
* Put the ''Public Key Hash''' file (publicKeyhash.bin), generated in the previous section, on bootfs partition  
* Boot the board and stop on U-Boot console
+
* Boot the board and stop it on th U-Boot console
* Load hash public key in DDR<br/>for example, the hash key file is located on 8th partition of sdcard:  
+
* Load the public key hash in DDR<br/>for example, the hash key file is located on 8th partition of the SD card:  
 
  {{U-Boot$}} load mmc 0:8 0xc0000000 publicKeyhash.bin
 
  {{U-Boot$}} load mmc 0:8 0xc0000000 publicKeyhash.bin
* Register hash public key
+
* Register public key hash
 
  {{U-Boot$}} stm32key fuse 0xc0000000
 
  {{U-Boot$}} stm32key fuse 0xc0000000
   
Line 171: Line 190:
   
 
===Put hash key on device for {{MicroprocessorDevice | device=13}}===
 
===Put hash key on device for {{MicroprocessorDevice | device=13}}===
To manually put the key on STM32MP device with U-Boot stm32key command, you need to:
+
To manually put the public key hash (PKH) on STM32MP device with U-Boot stm32key command, you need to:
* Put the '''hash key''' file (publicKeysHashHashes.bin), generated on previous section, on bootfs partition  
+
* Put the '''Public Key Hash'' file (publicKeysHashHashes.bin), generated on previous section, on bootfs partition  
 
* Boot the board and stop on U-Boot console
 
* Boot the board and stop on U-Boot console
* Load hash public key in DDR<br/>for example, the hash key file is located on 8th partition of sdcard:
+
* Load public key hash in DDR<br/>for example, the hash key file is located on 8th partition of sdcard:
 
  {{U-Boot$}} load mmc 0:8 0xc0000000 publicKeysHashHashes.bin
 
  {{U-Boot$}} load mmc 0:8 0xc0000000 publicKeysHashHashes.bin
* Register hash public key
+
* Register public key hash
 
  {{U-Boot$}} stm32key fuse 0xc0000000
 
  {{U-Boot$}} stm32key fuse 0xc0000000
   
  +
For more information, see  [[How to use U-Boot stm32key command]].
  +
  +
==Put encryption key on STM32MP==
  +
  +
{{info| For demonstration and test purposes, the encryption key can be put on the STM32MP device with a simple U-Boot command on the development board.<br/>
  +
For production purposes, it must be set in the production step.}}
  +
  +
===Put an encryption key on the device for {{MicroprocessorDevice | device=13}}===
  +
To manually put the key on the STM32MP device with a U-Boot stm32key command, you need to:
  +
* Put the '''encryption key''' file (''stm32mp13_encryption_key.bin''), generated in the previous section, on the bootfs partition
  +
* Boot the board and stop it on the U-Boot console
  +
* Load a hash public key in DDR<br/>for example, the hash key file is located on 8th partition of the SD card:
  +
{{U-Boot$}} load mmc 0:8 0xc0000000 stm32mp13_encryption_key.bin
  +
* Select the EDMK key ([[How_to_use_U-Boot_stm32key_command#Encryption_Decryption_Master_Key_provisioning|How to use U-Boot stm32key command|]])
  +
{{U-Boot$}} stm32key select EDMK
  +
* Register encryption key
  +
{{U-Boot$}} stm32key fuse 0xc0000000
  +
* Verify that the key is registered
  +
{{U-Boot$}} stm32key read
 
For more information, see  [[How to use U-Boot stm32key command]].
 
For more information, see  [[How to use U-Boot stm32key command]].
   
 
==Distribution package with signed FIP==
 
==Distribution package with signed FIP==
   
===Pre-requisite===
+
===Pre-requisites===
* Having Signature Key (Public Key(s), Private Key(s), Hash key file, password)
+
* Having the Signature Key (Public Key(s), Private Key(s), Hash key file, password)
* Having get the [[STM32MP1_Distribution_Package|STM32MP1 Distribution Package]]
+
* Having obtained the [[STM32MP1_Distribution_Package|STM32MP1 Distribution Package]]
   
 
===Generate Distribution package with signed binaries===
 
===Generate Distribution package with signed binaries===
 
{{info|With this step only FIP binaries are signed}}
 
{{info|With this step only FIP binaries are signed}}
   
* source the environment of Distribution package  
+
* Source the environment of the Distribution package  
 
  {{PC$}} source layers/meta-st/scripts/envsetup.sh
 
  {{PC$}} source layers/meta-st/scripts/envsetup.sh
 
Select your DISTRO and your machine
 
Select your DISTRO and your machine
* Indicate where to found your Signature key
+
* Indicate where to find your Signature key
(in this example we are put the signature key on meta-st-stm32mp layer on key directory)<br/>
+
(in this example we put the signature key on meta-st-stm32mp layer on key directory)<br/>
 
Add the following lines on your local.conf (on build directory)
 
Add the following lines on your local.conf (on build directory)
   
 
For ST32MP15:
 
For ST32MP15:
  {{PC$}} echo 'FIP_SIGN_KEY = "key/stm32mp15/privateKey.pem" ' >> conf/local.conf  
+
  {{PC$}} echo 'FIP_SIGN_KEY = "key/stm32mp15/privateKey.pem" ' >> conf/local.conf
  +
{{PC$}} echo 'FIP_SIGN_KEY_stm32mp15 = "key/stm32mp15/privateKey.pem" ' >> conf/local.conf  
 
  {{PC$}} echo 'FIP_SIGN_KEY_EXTERNAL = "1" ' >> conf/local.conf  
 
  {{PC$}} echo 'FIP_SIGN_KEY_EXTERNAL = "1" ' >> conf/local.conf  
 
  {{PC$}} echo 'FIP_SIGN_KEY_PASS = "<password of signature key>" ' >> conf/local.conf
 
  {{PC$}} echo 'FIP_SIGN_KEY_PASS = "<password of signature key>" ' >> conf/local.conf
Line 204: Line 243:
   
 
For ST32MP13:
 
For ST32MP13:
  {{PC$}} echo 'FIP_SIGN_KEY = "key/stm32mp13/privateKey00.pem" ' >> conf/local.conf  
+
  {{PC$}} echo 'FIP_SIGN_KEY = "key/stm32mp13/privateKey00.pem" ' >> conf/local.conf
  +
{{PC$}} echo 'FIP_SIGN_KEY_stm32mp13 = "key/stm32mp13/privateKey00.pem" ' >> conf/local.conf  
 
  {{PC$}} echo 'FIP_SIGN_KEY_EXTERNAL = "1" ' >> conf/local.conf  
 
  {{PC$}} echo 'FIP_SIGN_KEY_EXTERNAL = "1" ' >> conf/local.conf  
 
  {{PC$}} echo 'FIP_SIGN_KEY_PASS = "<password of signature key>" ' >> conf/local.conf
 
  {{PC$}} echo 'FIP_SIGN_KEY_PASS = "<password of signature key>" ' >> conf/local.conf
Line 217: Line 257:
 
On '''tmp-glibc/deploy/images/<machine name>/fip/''' you will found the FIP file signed ready to be programmed on board.
 
On '''tmp-glibc/deploy/images/<machine name>/fip/''' you will found the FIP file signed ready to be programmed on board.
   
==Sign first stage bootloader binaries==
+
===Generate a Distribution package with encrypted partition binaries for {{MicroprocessorDevice | device=13}}===
The first stage bootloader binaries = TF-A BL2 are generated unsigned; we need to sign it manually with '''STM32MP_SigningTool_CLI'''.
+
To enable secure boot with encryption support, you must add '''DECRYPTION_SUPPORT=aes_gcm''' with the '''ENCRYPT_BLx''' to specify the encrypted binary.<br/>
  +
 
  +
Request encryption support on BL2 TF-A binaries:
  +
{{PC$}} echo 'TF_A_ENCRYPTED_ENABLE = "1" ' >> conf/local.conf
  +
 
  +
==Sign first-stage bootloader binaries==
  +
{{ReviewsComments | [[User:Lionel Vitte|Lionel Vitte]] ([[User talk:Lionel Vitte|talk]]) 10:31, 6 December 2022 (CET) - Is it 'first-stage' of 'first stage'?}}
  +
The first stage bootloader binaries = TF-A BL2 are generated unsigned; we need to sign them manually with the '''STM32MP_SigningTool_CLI'''.
   
For installation and command line options see [[Signing tool]].
+
For installation and command-line options, see [[Signing tool]].
   
{{info| if you need to populate the FSBL binary via STM32CubeProgrammer, you need to also sign the serial boot TF-A BL2 loaded on memory}}
+
{{info| if you need to populate the FSBL binary via STM32CubeProgrammer, you also need to sign the serial boot TF-A BL2 loaded in memory}}
   
This tools is used to sign a binary with [[STM32 header for binary files|STM32 header]], with the minimal options to sign the FSBL binary is:
+
These tools are used to sign a binary with [[STM32 header for binary files|STM32 header]], with the minimal options to sign the FSBL binary:
 
  {{PC$}} STM32MP_SigningTool_CLI {{Highlight|-pubk}} {{HighlightParam|<public key>}} {{Highlight|-prvk}}  {{HighlightParam|<private key>}} {{Highlight|-pwd}} {{HighlightParam|<password>}} {{Highlight|-t}} {{HighlightParam|fsbl}} {{Highlight|-of}} {{HighlightParam|<Option_Flags>}} {{Highlight|-bin}} {{HighlightParam|FSBL binary not signed>.stm32}} {{Highlight|-o}} {{HighlightParam|<FSBL binary signed>.stm32}}
 
  {{PC$}} STM32MP_SigningTool_CLI {{Highlight|-pubk}} {{HighlightParam|<public key>}} {{Highlight|-prvk}}  {{HighlightParam|<private key>}} {{Highlight|-pwd}} {{HighlightParam|<password>}} {{Highlight|-t}} {{HighlightParam|fsbl}} {{Highlight|-of}} {{HighlightParam|<Option_Flags>}} {{Highlight|-bin}} {{HighlightParam|FSBL binary not signed>.stm32}} {{Highlight|-o}} {{HighlightParam|<FSBL binary signed>.stm32}}
   
 
with:
 
with:
* {{HighlightParam|<public key>}}= the path of the Private key files generated by KeyGen: publicKey*.pem, 1 for STM32MP15 and 8 for STM32MP13
+
* {{HighlightParam|<public key>}}= the path of the Public key file generated by KeyGen: privateKey.pem
* {{HighlightParam|<private key>}} = the path of the Public key file generated by KeyGen: privateKey.pem
+
{{ReviewsComments | [[User:Lionel Vitte|Lionel Vitte]] ([[User talk:Lionel Vitte|talk]]) 10:31, 6 December 2022 (CET) - Really privateKey.pem with the parameter <public key>?}}
  +
* {{HighlightParam|<private key>}} = the path of the Private key files generated by KeyGen: publicKey*.pem, 1 for STM32MP15 and 8 for STM32MP13
  +
{{ReviewsComments | [[User:Lionel Vitte|Lionel Vitte]] ([[User talk:Lionel Vitte|talk]]) 10:31, 6 December 2022 (CET) - Really publicy.pem with the parameter <private key>?}}
 
* {{HighlightParam|<password>}} = pasword used by KeyGen to protect the key files
 
* {{HighlightParam|<password>}} = pasword used by KeyGen to protect the key files
 
* {{HighlightParam|<Option_Flags>}} = the {{Highlight|-of}} option is required only for STM32MP13, with 0x00000001 value
 
* {{HighlightParam|<Option_Flags>}} = the {{Highlight|-of}} option is required only for STM32MP13, with 0x00000001 value
   
===Signing first stage bootloader binaries for {{MicroprocessorDevice | device=15}}===
+
===Signing first-stage bootloader binaries for {{MicroprocessorDevice | device=15}}===
 
For SDCARD:
 
For SDCARD:
  {{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp15/publicKey.pem -prvk  <path to meta-st-stm32mp>key/stm32mp15/privateKey.pem -pwd <password> -t ssbl -bin arm-trusted-firmware/tf-a-<board name>-sdcard.stm32 -o arm-trusted-firmware/tf-a-<board name>-sdcard_Signed.stm32
+
  {{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp15/publicKey.pem -prvk  <path to meta-st-stm32mp>key/stm32mp15/privateKey.pem -pwd <password> -t fsbl -bin arm-trusted-firmware/tf-a-<board name>-sdcard.stm32 -o arm-trusted-firmware/tf-a-<board name>-sdcard_Signed.stm32
 
For EMMC:
 
For EMMC:
  {{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp15/publicKey.pem -prvk  <path to meta-st-stm32mp>key/stm32mp15/privateKey.pem -pwd <password> -t ssbl -bin arm-trusted-firmware/tf-a-<board name>-emmc.stm32 -o arm-trusted-firmware/tf-a-<board name>-emmc_Signed.stm32
+
  {{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp15/publicKey.pem -prvk  <path to meta-st-stm32mp>key/stm32mp15/privateKey.pem -pwd <password> -t fsbl -bin arm-trusted-firmware/tf-a-<board name>-emmc.stm32 -o arm-trusted-firmware/tf-a-<board name>-emmc_Signed.stm32
 
For NAND:
 
For NAND:
  {{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp15/publicKey.pem -prvk  <path to meta-st-stm32mp>key/stm32mp15/privateKey.pem -pwd <password> -t ssbl -bin arm-trusted-firmware/tf-a-<board name>-nand.stm32 -o arm-trusted-firmware/tf-a-<board name>-nand_Signed.stm32
+
  {{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp15/publicKey.pem -prvk  <path to meta-st-stm32mp>key/stm32mp15/privateKey.pem -pwd <password> -t fsbl -bin arm-trusted-firmware/tf-a-<board name>-nand.stm32 -o arm-trusted-firmware/tf-a-<board name>-nand_Signed.stm32
 
For NOR:
 
For NOR:
  {{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp15/publicKey.pem -prvk  <path to meta-st-stm32mp>key/stm32mp15/privateKey.pem -pwd <password> -t ssbl -bin arm-trusted-firmware/tf-a-<board name>-nor.stm32 -o arm-trusted-firmware/tf-a-<board name>-nor_Signed.stm32
+
  {{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp15/publicKey.pem -prvk  <path to meta-st-stm32mp>key/stm32mp15/privateKey.pem -pwd <password> -t fsbl -bin arm-trusted-firmware/tf-a-<board name>-nor.stm32 -o arm-trusted-firmware/tf-a-<board name>-nor_Signed.stm32
 
For USB (used with STM32CubeProgrammer):
 
For USB (used with STM32CubeProgrammer):
  {{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp15/publicKey.pem -prvk  <path to meta-st-stm32mp>key/stm32mp15/privateKey.pem -pwd <password> -t ssbl -bin arm-trusted-firmware/tf-a-<board name>-usb.stm32 -o arm-trusted-firmware/tf-a-<board name>-usb_Signed.stm32
+
  {{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp15/publicKey.pem -prvk  <path to meta-st-stm32mp>key/stm32mp15/privateKey.pem -pwd <password> -t fsbl -bin arm-trusted-firmware/tf-a-<board name>-usb.stm32 -o arm-trusted-firmware/tf-a-<board name>-usb_Signed.stm32
 
For UART (used with STM32CubeProgrammer):
 
For UART (used with STM32CubeProgrammer):
  {{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp15/publicKey.pem -prvk  <path to meta-st-stm32mp>key/stm32mp15/privateKey.pem -pwd <password> -t ssbl -bin arm-trusted-firmware/tf-a-<board name>-uart.stm32 -o arm-trusted-firmware/tf-a-<board name>-uart_Signed.stm32
+
  {{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp15/publicKey.pem -prvk  <path to meta-st-stm32mp>key/stm32mp15/privateKey.pem -pwd <password> -t fsbl -bin arm-trusted-firmware/tf-a-<board name>-uart.stm32 -o arm-trusted-firmware/tf-a-<board name>-uart_Signed.stm32
   
 
===Signing first stage bootloader binaries for {{MicroprocessorDevice | device=13}}===
 
===Signing first stage bootloader binaries for {{MicroprocessorDevice | device=13}}===
 
For SDCARD:
 
For SDCARD:
  {{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp13/publicKey*.pem -prvk  <path to meta-st-stm32mp>key/stm32mp15/privateKey00.pem -pwd <password> -t ssbl '''-of 0x00000001''' -bin arm-trusted-firmware/tf-a-<board name>-sdcard.stm32 -o arm-trusted-firmware/tf-a-<board name>-sdcard_Signed.stm32
+
  {{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp13/publicKey*.pem -prvk  <path to meta-st-stm32mp>key/stm32mp15/privateKey00.pem -pwd <password> -t fsbl '''-of 0x00000001''' -bin arm-trusted-firmware/tf-a-<board name>-sdcard.stm32 -o arm-trusted-firmware/tf-a-<board name>-sdcard_Signed.stm32
 
For EMMC:
 
For EMMC:
  {{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp13/publicKey*.pem -prvk  <path to meta-st-stm32mp>key/stm32mp13/privateKey00.pem -pwd <password> -t ssbl '''-of 0x00000001''' -bin arm-trusted-firmware/tf-a-<board name>-emmc.stm32 -o arm-trusted-firmware/tf-a-<board name>-emmc_Signed.stm32
+
  {{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp13/publicKey*.pem -prvk  <path to meta-st-stm32mp>key/stm32mp13/privateKey00.pem -pwd <password> -t fsbl '''-of 0x00000001''' -bin arm-trusted-firmware/tf-a-<board name>-emmc.stm32 -o arm-trusted-firmware/tf-a-<board name>-emmc_Signed.stm32
 
For NAND:
 
For NAND:
  {{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp13/publicKey*.pem -prvk  <path to meta-st-stm32mp>key/stm32mp13/privateKey00.pem -pwd <password> -t ssbl '''-of 0x00000001''' -bin arm-trusted-firmware/tf-a-<board name>-nand.stm32 -o arm-trusted-firmware/tf-a-<board name>-nand_Signed.stm32
+
  {{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp13/publicKey*.pem -prvk  <path to meta-st-stm32mp>key/stm32mp13/privateKey00.pem -pwd <password> -t fsbl '''-of 0x00000001''' -bin arm-trusted-firmware/tf-a-<board name>-nand.stm32 -o arm-trusted-firmware/tf-a-<board name>-nand_Signed.stm32
 
For NOR:
 
For NOR:
  {{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp13/publicKey*.pem -prvk  <path to meta-st-stm32mp>key/stm32mp13/privateKey00.pem -pwd <password> -t ssbl '''-of 0x00000001''' -bin arm-trusted-firmware/tf-a-<board name>-nor.stm32 -o arm-trusted-firmware/tf-a-<board name>-nor_Signed.stm32
+
  {{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp13/publicKey*.pem -prvk  <path to meta-st-stm32mp>key/stm32mp13/privateKey00.pem -pwd <password> -t fsbl '''-of 0x00000001''' -bin arm-trusted-firmware/tf-a-<board name>-nor.stm32 -o arm-trusted-firmware/tf-a-<board name>-nor_Signed.stm32
 
For USB (used with STM32CubeProgrammer):
 
For USB (used with STM32CubeProgrammer):
  {{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp13/publicKey*.pem -prvk  <path to meta-st-stm32mp>key/stm32mp13/privateKey00.pem -pwd <password> -t ssbl '''-of 0x00000001''' -bin arm-trusted-firmware/tf-a-<board name>-usb.stm32 -o arm-trusted-firmware/tf-a-<board name>-usb_Signed.stm32
+
  {{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp13/publicKey*.pem -prvk  <path to meta-st-stm32mp>key/stm32mp13/privateKey00.pem -pwd <password> -t fsbl '''-of 0x00000001''' -bin arm-trusted-firmware/tf-a-<board name>-usb.stm32 -o arm-trusted-firmware/tf-a-<board name>-usb_Signed.stm32
 
For UART (used with STM32CubeProgrammer):
 
For UART (used with STM32CubeProgrammer):
  {{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp13/publicKey*.pem -prvk  <path to meta-st-stm32mp>key/stm32mp13/privateKey00.pem -pwd <password> -t ssbl '''-of 0x00000001''' -bin arm-trusted-firmware/tf-a-<board name>-uart.stm32 -o arm-trusted-firmware/tf-a-<board name>-uart_Signed.stm32
+
  {{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp13/publicKey*.pem -prvk  <path to meta-st-stm32mp>key/stm32mp13/privateKey00.pem -pwd <password> -t fsbl '''-of 0x00000001''' -bin arm-trusted-firmware/tf-a-<board name>-uart.stm32 -o arm-trusted-firmware/tf-a-<board name>-uart_Signed.stm32
  +
 
  +
===Encrypt first stage bootloader binaries for {{MicroprocessorDevice | device=13}}===
  +
For SDCARD:
  +
{{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp13/publicKey*.pem -prvk  <path to meta-st-stm32mp>key/stm32mp15/privateKey00.pem -pwd <password>  --enc-key  <path to meta-st-stm32mp>key/stm32mp13/stm32mp13_encryption_key.bin -t fsbl  ''' --enc-dc 0x0E5F2025 --image-version 0 -of 0x80000003''' -bin arm-trusted-firmware/tf-a-<board name>-sdcard.stm32 -o arm-trusted-firmware/tf-a-<board name>-sdcard_Encrypted.stm32
  +
 
  +
For EMMC:
  +
{{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp13/publicKey*.pem -prvk  <path to meta-st-stm32mp>key/stm32mp15/privateKey00.pem -pwd <password>  --enc-key  <path to meta-st-stm32mp>key/stm32mp13/stm32mp13_encryption_key.bin -t fsbl  ''' --enc-dc 0x0E5F2025 --image-version 0 -of 0x80000003''' -bin arm-trusted-firmware/tf-a-<board name>-emmc.stm32 -o arm-trusted-firmware/tf-a-<board name>-emmc_Encrypted.stm32
  +
 
  +
For NAND:
  +
{{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp13/publicKey*.pem -prvk  <path to meta-st-stm32mp>key/stm32mp15/privateKey00.pem -pwd <password>  --enc-key  <path to meta-st-stm32mp>key/stm32mp13/stm32mp13_encryption_key.bin -t fsbl  ''' --enc-dc 0x0E5F2025 --image-version 0 -of 0x80000003''' -bin arm-trusted-firmware/tf-a-<board name>-nand.stm32 -o arm-trusted-firmware/tf-a-<board name>-nand_Encrypted.stm32
  +
 
  +
For NOR:
  +
{{PC$}} STM32MP_SigningTool_CLI  -pubk <path to meta-st-stm32mp>key/stm32mp13/publicKey*.pem -prvk  <path to meta-st-stm32mp>key/stm32mp15/privateKey00.pem -pwd <password>  --enc-key  <path to meta-st-stm32mp>key/stm32mp13/stm32mp13_encryption_key.bin -t fsbl  ''' --enc-dc 0x0E5F2025 --image-version 0 -of 0x80000003''' -bin arm-trusted-firmware/tf-a-<board name>-nor.stm32 -o arm-trusted-firmware/tf-a-<board name>-nor_Encrypted.stm32
   
 
==Create FlashLayout for signed binaries==
 
==Create FlashLayout for signed binaries==
Line 300: Line 362:
   
 
==Program and test==
 
==Program and test==
To populate the correct binaries on the board with STM32CubeProgrammer, you need to use the previous FlashLayout file with the signed binaries.
+
To populate the correct binaries on the board with STM32CubeProgrammer, you must use the previous FlashLayout file with the signed binaries.
   
At boot time on board, you must check [[How_to_secure_STM32_MPU#Firmware_secure_boot|the two level of the secure boot]]: the ROM code secure boot validation and the TF-A BL2 trusted board boot validation.
+
At board boot time, you must check [[How_to_secure_STM32_MPU#Firmware_secure_boot|the two level of the secure boot]]: the ROM code secure boot validation, and the TF-A BL2 trusted board boot validation.
   
 
==Close the device==
 
==Close the device==
   
{{info| For Demonstration and TEST purpose, the STM32MP device can be closed with a simple U-Boot command on development board. For product purpose, it must be set on production step as described in the [[STM32MP15 resources#AN5510|AN5510: Overview of the secure secret provisioning (SSP) on STM32MP1 Series]].}}  
+
{{info| For demonstration and test purposes, the STM32MP device can be closed with a simple U-Boot command on the development board. For production purposes, it must be set in production step as described in [[STM32MP15 resources#AN5510|AN5510: Overview of the secure secret provisioning (SSP) on STM32MP1 Series]].}}  
   
 
For more information, see  [[How_to_secure_STM32_MPU#Close_the_device|How to secure STM32 MPU]].
 
For more information, see  [[How_to_secure_STM32_MPU#Close_the_device|How to secure STM32 MPU]].
   
{{Warning | Please take care to close the device only if the previous authentication test succeed, otherwise the chip will be bricked and could not be used anymore}}
+
{{Warning | Make sure you only close the device if the previous authentication test succeeded, otherwise the chip is bricked, and is now unusable.}}
   
 
In U-Boot console:
 
In U-Boot console:
 
   {{U-Boot$}} stm32key close
 
   {{U-Boot$}} stm32key close
   
For more information, see [[How to use U-Boot stm32key command]].
+
For more information, see the [[How to use U-Boot stm32key command]].
   
As soon as the device is closed, and it is irreversible operation, the user is forced to use only signed images.
+
As soon as the device is closed, the operation is irreversible; the user is forced to only use signed images.
   
{{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}}
+
{{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 is bricked, and is now unusable.}}
   
 
== References==
 
== References==
 
<references />
 
<references />
 
<noinclude>
 
<noinclude>
 
+
[[Category:How_to_customize_software]]
  +
{{PublicationRequestId | 24642 | 2022-09-26| ticket entered by the review has been cancelled to launch a new Experts review. Reuse this number to start a new TW review when needed}}
 
</noinclude>
 
</noinclude>