How to deploy SSP: a step-by-step approach

This message will disappear after all relevant tasks have been resolved.

Semantic MediaWiki

There are 1 incomplete or pending task to finish installation of Semantic MediaWiki. An administrator or user with sufficient rights can complete it. This should be done before adding new data to avoid inconsistencies.

Applicable for

STM32MP13x lines, STM32MP15x lines

1 Article purpose[edit source]

This article aims to explain, step by step, how to run the SSP process from the OEM secret generation till the chip provisioning. The SSP overview is explained here.

This example will use the STM32CubeProgrammer and its associated tools to manage the complete SSP.

2 OEM secret management[edit source]

The aim of SSP is to protect OEM secrets. It includes multiple secrets:

Secrets that will be provisioned in OTP,
OEM authentication keys for Secure Boot,
OEM secrets encryption key.

2.1 Key generation[edit source]

2.1.1 Authentication keys[edit source]

The initial keys to generate for STM32 MPU is the authentication keys. This is the root of trust of the STM32 MPU secure boot. The PKHTH (on STM32MP13xC/F lines ) or PKH (on STM32MP15xC/F lines ) will be automatically installed during the SSP process in the dedicated OTP.

To generate the keys, you can use the KeyGen_tool:

On STM32MP13xC/F lines :

Example to generate 8 ECC key pair (Prime256v1) using AES_256_cbc encryption:

 STM32MP_KeyGen_CLI -abs /home/user/KeyFolder/ -pwd testkey1 testkey2 testkey3 testkey4 testkey5 testkey6 testkey7 testkey8 -n 8

On STM32MP15xC/F lines :

Example to generate 1 ECC key pair (Prime256v1) using AES_256_cbc encryption:

 STM32MP_KeyGen_CLI -abs /home/user/KeyFolder/ -pwd testkey

2.1.2 Encryption key[edit source]

The SSP process uses a symmetric encryption to hide OEM secrets exchanged with the chip. This encryption/decryption uses a AES encryption scheme using:

a 128 bit symmetric key
a 128 bit nonce value

Both values will first be stored in the HSM and sent to the chip using a unique chip encrypted flow.
The two values can be directly generated with the STM32 Trusted Package Creator available in STM32CubeProgrammer , that will also manage the secret file encryption with the given key:

File:Contributors:SSP secret UI.png

Another solution is to prepare both key using the KeyGen_tool (till version 2.12.0) with the command:

 STM32MP_KeyGen_CLI -rand 16 enc_key.bin
 STM32MP_KeyGen_CLI -rand 16 nonce.bin

2.2 Secret file[edit source]

2.2.1 Secret file creation[edit source]

Warning

There is actually no tool to generate the file so the secret file must be generated manually. Hexadecimal tool must be used to generate the file.
ssp-secrets/ssp_secret_template.bin is an empty file with the correct size for STM32MP1 series.

The secret file, that must be generated by OEM, must represent the OTP 59 to 95 on STM32MP1 series, named Free for user.

On STM32MP1 series:

the words 57 and 58 are reserved for mac_address.
the final file size must be (96 - 59) * 4 bytes = 148 bytes.

Information

On STM32 boards, the word 59 is already fused to store the ST Board ID. For SSP testing purpose on STM32MP board, the content of the word 59 must be skipped by using the 0x00000000 value in the secret file.

2.2.2 Secret file encryption[edit source]

The STM32 Trusted Package Creator is used to encrypt and prepare the final secret file used for provisioning.
This encrypted final file will contains:

the PKH or PKHTH,
the RMA ^[1] password,
the OEM secrets.

All the previous generated keys must be properly selected in the STM32 Trusted Package Creator interface to generate the final encrypted file (.ssp). The chip and RMA password must be registered in the interface.

File:Contributors:SSP secret UI.png

2.3 HSM provisioning[edit source]

The HSMv2^[2] must be provisioned with the OEM associated SSP file.

The STM32 Trusted Package Creator has a dedicated SSP HSM provisioning interface to select:

the encryption key used to encrypt SSP secret file,
the nonce used to encrypt SSP secret file,
the personalization data file (used to identify the chip):
- STM32MP1 for STM32MP1 series
  - 5010100D file for STM32MP13xC/F lines
  - 5000200A file for STM32MP15xC/F lines

the maximum of images to program (which depends also on the HSMv2 used).

File:Contributors:HSM UI.png

3 SSP Firmware management[edit source]

On STM32MP1 series, a specific firmware is used to:

exchange SSP communication with the host,
burn the OTP in fuses.

This part is managed using a specific TF-A BL2 that is delivered with each ecosystem version and must be updated regarding the customer board.
It only includes a limited part of the TF-A BL2 scope:

only serial boot support,
dedicated SSP feature set.

Warning

An important requirement is the VDDCORE regulator. The interaction between the ROM code and TF-A BL2 requires to maintain the VDDCORE during reset transition. This is done by the TF-A BL2 SSP default firmware when using a PMIC. It must be taking in account for a power discret board that must not stop the VDDCORE during a software system reset.

3.1 TF-A customization[edit source]

The main TF-A firmware is ready for all targets except the board device tree. It must be customized in the same way it is made for TF-A BL2.

3.2 Build TF-A BL2 SSP[edit source]

Because it uses the same firmware, the way of building and configuring the firmware is described in the How_to_configure_TF-A_BL2 page.

The specific part is the following one:

dedicated flag to enable the SSP part: STM32MP_SSP
no TRUSTED_BOARD_BOOT enabled to limit the BL2 binary size.

Example:

Command line for UART mode on STM32MP13xC/F lines using STM32MP135x-DK Discovery kit :

 make ARM_ARCH_MAJOR=7 ARCH=aarch32 PLAT=stm32mp1 STM32MP_UART_PROGRAMMER=1 \
      STM32MP13=1 STM32MP_SSP=1 DTB_FILE_NAME=stm32mp135f-dk.dtb

Command line for USB mode on STM32MP15xC/F lines using unknown board type identifier :

 make ARM_ARCH_MAJOR=7 ARCH=aarch32 PLAT=stm32mp1 STM32MP_USB_PROGRAMMER=1 \
      STM32MP15=1 STM32MP_SSP=1 DTB_FILE_NAME=stm32mp157c-ev1.dtb

3.3 Signing TF-A BL2 SSP[edit source]

This TF-A BL2 SSP firmware MUST be signed with the OEM authentication key generated at step 1. The authentication will be made by the ROM code using the OEM public key given by the HSM during the process.

This is made in the same way as TF-A BL2 using the Signing_tool:
Example :

  STM32MP_SigningTool_CLI -bin tfa-ssp.stm32 -pubk OEMpublicKey.pem –prvk OEMprivateKey.pem –pwd testkey

4 Production processing[edit source]

At that stage, the following parts are available:

SSP encrypted secret file,
provisioned HSM ,
TF-A BL2 SSP signed firmware,

All that material must be given to the untrusted production to start the SSP process.

4.1 Test case using STM32CubeProgrammer_Cli[edit source]

For an evaluation purpose, STM32CubeProgrammer can be used to test the SSP processing chain.

On the host, the STM32CubeProgrammer must be installed. HSM is plugged into the host smartcard reader. The board is connected, chip is virgin. Serial boot mode is selected and power is ON.

The following command can be used for a USB SSP provisioning:

   STM32_Programmer_CLI -c port=usb1 -ssp <ssp_file_path> <tf-a-bl2-ssp-path> hsm=1

5 SSP : Final state[edit source]

At that stage, the device is provisioned with all the OEM secrets:

OEM PKH or PKHTH,
OTP secrets.

The chip is now in secure close state, the secure boot is mandatory.
Enabling secure boot is the final step to use the chip. Maybe adding the link to secure boot page or TF-A build command to enable secure boot could be useful and it will highlight the information.

The SSP process can not be restarted anymore.

6 References[edit source]

[1] STM32_MPU_resources#AN5827

[2] ttps://www.st.com/en/development-tools/stm32hsm-v2.html

[1]

[2]