STiRoT STM32H5 How to intro

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.

Target description

The purpose of this article is to provide the necessary background to understand and execute the related How to start with STiRoT on STM32H573 development.
This step by step guide is based on the STM32CubeFW example provided by ST (STM32Cube_FW_H5_Vx.x.x\Projects\STM32H573I-DK\Applications\ROT\STiROT_Appli).
Another STiRoT article on how to start using STM32CubeMx with a secure and non secure user applications is available: How to start with STM32CubeMX STiRoT Boot path on STM32H57.


This introductory article lists the necessary technical concepts that are needed to understand the STM32CubeFW example.
More detailed information about the STiRoT is available in the two following articles:


Reminder

  • STiRoT stands for "ST Immutable Root of Trust" and is an implementation of both Secure Boot (SB) and Secure Firmware Update (SFU) security features.
  • The STiRoT is embedded in all the STM32H57x devices.
  • Since the STiRoT requires a hardware cryptographic accelerator, it is not supported by STM32H6x and STM32H503 products.


1 STiRoT services

The two STiRoT services that are provided are used in the How to start with STiRoT on STM32H573.

1) The Secure Boot:
Verification of the integrity, and authenticity of the application code before any execution.
2) The Secure Firmware Update:
If a new firmware image is available on detection, the SFU checks its authenticity. Once the firmware is decrypted, the SFU checks and confirms the integrity of the code before installing it.

2 STiRoT use case for the "how to" example

There are two possible use cases explained in the STiRoT for STM32H5 which correspond to:

  • One boot stage
  • Two boot stages.

The "how to" example is using case 1: the fully secured user application is executed after the STiRoT (1 boot stage)

The figure below shows the related boot path.


Figure 1. STiRoT "how to" example, Bootpath

As shown in the figure below, two option bytes must be programmed to define the appropriate bootpath.

  • TrustZone® must be enabled
  • The Unique Boot Entry (UBE) must be set to select the STiRoT.

The programming of these option bytes (OB) is done automatically using the provisioning script provided in the package.
The next sections explain what is required and the steps to configure the bootpath before launching the script.

As shown in the figure below, based on the chosen bootpath, the STiRoT is the first application executed after each reset.
The STiRoT application is executed in temporal isolation 1 (HDPL1) (refer to Introduction to Silicon device life cycle article)

  • This figure shows the download areas for the encrypted and signed user application firmware, and the data image(s) to be installed.
  • When installed, the user application firmware is placed in the execution area .
  • When installed (and if applicable), the data are stored (re-encrypted) in a secure storage area dedicated to the related isolation level (HDPL2 OB keys for the "how to" example).
  • The user application must have a secure sector containing at least the vector table and the reset handler. It can also be fully secured as in the "how to" sample.


Figure 2. User application is executed after STiRoT (one boot stage)

The firmware/data image installations and update are described in the next sections.
Once the installation is complete, the STiRoT is executed first at each power-on or reset of the device.

  • When the STiRoT is executed, the debugger is deactivated and the user has no further access to it.
  • After a successful verification of the user application which includes integrity and authenticity, the STiRoT executes the user application in temporal isolation level 2 (HDPL2 for this example) and in secure mode.
  • In case of a verification failure of the user application code, the STiRoT executes the embedded bootloader (refer to AN2606) to download a new user app code and/or data.
  • As mentioned, the How to start with STiRoT on STM32H573 article demonstrates the implementation of a fully secured user application. An example with secure and non secure user application is described in the How to start with STM32CubeMX STiRoT Boot path on STM32H57 article.
  • The securing of the user application is done during the STiRoT configuration.
  • The activation of the data image is also done during the STiRoT configuration.
  • The data can, for instance, be used to store keys or any other secret information needed by the user. But for this "how to" example, it is just random data to show the principle and to be read back through the user application.


3 STiRoT and debug authentication configuration

This chapter describes the STiRoT and debug authentication configuration used in the "how to" example.
Read the STiRoT for STM32H5 article for more details.

  • Two configuration xml files are provided in the STM32CubeFW with default values.
  • The STM32TrustedPackageCreator (TPC) is used to graphically update the configuration.
  • The TPC saves the modifications to the configuration xml file.
  • Two OB key files are generated with the TPC. These two encrypted files are used during the provisioning of the device.

A script (Provisioning.bat) provided in the STM32Cube_FW, guides the user through the configuration definition and device programming.

  • STM32Cube_FW_H5_Vx.x.x\Projects\STM32H573I-DK\ROT_Provisioning\STiROT\provisioning.bat.

The configuration management is the first step of the script execution.

3.1 STiRoT configuration for the proposed "How to"

All possible configuration options are described in the appendix table of the STiRoT for STM32H5 article.

For the STiRoT configuration, the following xml file is opened and edited with the STM32TrustedPackageCreator:

  • STM32Cube_FW_H5_Vx.x.x\Projects\STM32H573I-DK\ROT_Provisioning\STiROT\Config\STiRoT_Config.xml.

This default file already contains the configurations listed below.

The STiRoT configuration listed below is used for the proposed "how to" example:

  • Two images are available: one user application code image and one user application data image.
  • A fully secured user application.
  • The flash location for the user application. It is defined as an offset from the beginning of the user flash, and is aligned with a sector start address range. In this example, it is: 0x00000000.
  • The flash location for the user application download. It is defined as an offset from the beginning of the user flash, and is aligned with a sector start address range. In this example, it is: 0x001E0000.
  • The firmware area size for download and execution is aligned on a sector size. In this example, it is: 0x00020000.
  • The flash location for the data download is defined as an offset from the beginning of the user flash, and is aligned with a sector start address. In this example, it is: 0x001DE000.
  • Encryption and authentication key location (only ECDSA256 supported)
  • Minimal product state: open means that the STiRoT allows the user firmware execution for all the possible product states.
  • Two keys are provisioned: one key for the authentication and one key for the file encryption. The default keys are provided in the STM32Cube_FW but they can be regenerated using STM32TrustedPackageCreator. (see How to start with STiRoT article).

Note::
There is no execution area defined for the data. Once the data image is decrypted by the STiRoT, it is encrypted using a derived hardware unique key (DHUK), which is not accessible to a user and stored in encrypted form in the secure storage area (in this example, the HDPL2 secure storage and DHUK is used) (see STiRoT for STM32H5 article).

When the STiRoT configuration is ready in the TPC, clicking "Generate OBkey" button in the TPC generates the related encrypted file:

  • STM32Cube_FW_H5_Vx.x.x\Projects\STM32H573I-DK\ROT_Provisioning\STiROT\Binary\STiRoT_Config.obk

This file is used by the provisioning script to set the STiRoT configuration in the device.

3.2 Debug authentication configuration for the proposed "How to"

Detail explanations about the debug authentication (DA) are available in the Introduction to Debug Authentication for STM32H5 MCUs article.

If the product is set to a state other than open, a debug authentication is needed to ensure that only the authorized user can access or modify the content of the device.
Without a correct DA provisioning it is not possible to reopen the debugger of the product in any state other than open.
As shown in figure1, the TrustZone® is activated. In this case, the debug authentication is done through a root key and a root certificate. For TZ=0, it is done through a password authentication and only full regression is possible. (refer to: Debug Authentication STM32H5 How to Introduction for more details)

A default configuration file is provided in the STM32CubeFW: STM32Cube_FW_H5_V1.x.x\Projects\STM32H573I-DK\ROT_Provisioning\DA\Config\DA_Config.xml.

  • The debug authentication is configured using this DA_Config.xml file. (STM32Cube_FW_H5_Vx.x.x\Projects\STM32H573I-DK\ROT_Provisioning\DA\Config)
  • This xml file can be directly edited or graphically edited using STM32TrustedPackageCreator.
  • A default root key is provided in the STM32Cube_FW. This key is recommended for trials, because if the root key is lost, the device can not be reopened and regression can not be performed.
  • A new key can be generated using STM32TrustedPackageCreator.
  • The permission mask for the debug opening is set using STM32TrustedPackageCreator. These permissions are stored in the SOC_MASK which is programmed in the device during the provisioning step.
  • The DA_Config.obk file is generated using STM32TrustedPackageCreator. This file is used during the device provisioning.
Note: For a commercial product, the debug authentication root key (key_1_root.pem) must regenerated, as the key provided in the STM32CubeFW is public.

When the DA configuration is ready in the TPC, click on the "Generate OBkey" button to generate the related encrypted file:

  • STM32Cube_FW_H5_Vx.x.x\Projects\STM32H573I-DK\ROT_Provisioning\DA\Binary\DA_Config.obk

This file is used by the provisioning script to set the DA configuration in the device.

4 Firmware code and data images generation

The second step of the script (Provisioning.bat in STM32CubeFW) is used to generate the user application firmware image.

For this proposed "how to", there are two signed and encrypted images to be generated:

  • The user application firmware image
  • The user data image

To be compatible with STiRoT, specific formats are requested for the two files. For the STM32CubeFW examples, it is not compulsory to take these formats into account. But in case of a user specific development, the user must define the correct user application code and data sizes. (refer to the STiRoT for STM32H5 article)


4.1 User application code image generation

This example is for a fully secured user application.
For the STiRoT configuration with the STM32TrustedPackageCreator (TPC), "Is the firmware full secure" must be ticked.
In the TPC, the "Size of the secure area inside the firmware execution area" is grayed automatically and can not be edited.
Even when secure and non secure user applications are needed, only one firmware image is generated containing both.

There are two ways to generate an encrypted and signed user application firmware image:

  • Generate the binary and image using an IDE. The image is generated through a postbuild command, the TPC is launched automatically by the IDE at the end of the firmware compilation.
  • If the user firmware binary is available, the TPC can be used to generate the image.

How to proceed using either method is explained in the How to start with STiRoT on STM32H573 article.


4.2 User data image generation

This example uses a data file.
These data is just used to be written back during user application execution and has no other meaning.
For the STiRoT configuration with the STM32TrustedPackageCreator (TPC), the "firmware and data images" must be selected.

For the data image generation, use the TPC as described in the How to start with STiRoT on STM32H573 article.

5 Provisioning

The third step of the script (Provisioning.bat in STM32CubeFW) is the provisioning of the device.
During the provisioning:

  • The option bytes are programmed according to the defined STiRoT configuration.
  • The user application firmware image and data image are uploaded in the user flash at a location defined during the STiRoT configuration.
  • The user application firmware is decrypted and copied in the user flash execution area according to the STiRoT configuration (see figure 2).
  • The data image is decrypted and stored re-encrypted in the secure storage area (see figure 2)
  • The final product state is set.

The provisioning is straightforward if the provisioning script is used. This is a step by step guide.

6 Regression

For a product state other than open, perform a full regression to retrieve an empty board.

A full regression erases the user stored content and secrets.

  • Erase the OB keys
  • Erase the complete user flash content
  • Erase the data of the secure storage (HDPL1 to HDPL3)
  • Reset the secure option bytes to their default value
  • Set the product to the open state.

There are two ways to proceed:

  • Executing the regression script provided in the STM32CubeFW
    • STM32Cube_FW_H5_Vx.x.x\Projects\STM32H573I-DK\ROT_Provisioning\DA\regression.bat
    • This script is using implicitly, with no consequence to the user, the root key and the root certificate
      • Root key: STM32Cube_FW_H5_Vx.x.x\Projects\STM32H573I-DK\ROT_Provisioning\DA\Keys\key_1_root.pem
      • Root certificate: STM32Cube_FW_H5_Vx.x.x\Projects\STM32H573I-DK\ROT_Provisioning\DA\Certificates\cert_root.b64
  • Using STM32CubeProgrammer, (see How to start with STiRoT on STM32H573 Full regression)
    • Click on the "Discover" button to indicate the product state, even if a debugger cannot be connected (except in locked state).
    • For the regression, select the path to the root key and certificate.


Retrieved from "https://wiki.st.com/stm32mcu/index.php?title=Security:STiRoT_STM32H5_How_to_intro&oldid=52664"