STiRoT STM32H5 How to intro

Revision as of 16:27, 5 May 2023 by Registered User
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 background needed to understand and execute the related How_to_start_with_ST-iROT_on_STM32H573 hands-on
This step by step is based on the ST provided STM32CubeFW example (STM32Cube_FW_H5_Vx.x.x\Projects\STM32H573I-DK\Applications\ROT\STiROT_Appli).
Another STiROT how to start using STM32CubeMx with a secure and non-secure user applications is available in the article How_to_start_with_STM32CubeMX_STiROT_Boot_path_on_STM32H57.


This introduction article reviews some technical notions needed to understand the STM32CubeFW example.
More detailed explanations about STiROT are available in the two following articles:


Reminder

  • STiROT states for ST Immutable Root of Trust and is an implementation of Secure Boot and Secure Firmware Update security features.
  • The STiROT is embedded in all STM32H57x devices.
  • Since the STiROT is requiring hardware cryptographic accelerator, it is not supported on STM32H6x and STM32H503 products.


1. STiROT services

The two provided STiROT services will be used in the How_to_start_with_ST-iROT_on_STM32H573.

1) The Secure Boot:
Verification of the Integrity and Authenticity of the application code before every execution.
2) The Secure Firmware Update:
Detection if a new firmware image is available, checks its authenticity and verifies the integrity of the code before installing it after decryption.

2. STiROT use case for the how to example

There are two possible use cases explained in the STiROT_for_STM32H5 (one or two boot stages)
The how to example is using the case 1: the full secure user application is executed after the STiROT (1 boot stage)

The figure below shows the related boot path.


File:BootPath STiROT how to.png
Figure 1. STiROT how to example, Bootpath

As shown in the figure, two option bytes need to be programmed to define the wanted bootpath.

  • The Trust Zone needs to be enabled
  • The UBE (Unique Boot Entry) needs to be set to select the STiROT.

The programming of these Option Bytes is done automatically using the provided provisioning script.
The next sections will explain what is required and the steps to configure the bootpath before launching the script.


As shown in the figure below, with this chosen boot path the STiROT is the first application executed after any reset.
STiROT application is executed in temporal isolation 1 (HDPL1) (refer to Introduction to Silicon device life cycle article)

  • This figure shows also the download areas for the encrypted and signed user application firmware and/or data image(s) to be installed.
  • When installed the user application firmware is located in the execution area .
  • When installed (if applicable) the data are stored (reencrypted) in a secure storage area dedicated to the related isolation level (HDPL2 OB Keys for the how to example).
  • The user application needs to have secure part (at least the vector table and the reset handler) or can be full secure as for the "how to" hands-on.


File:STiROT1.png
Figure 2. User application is executed after STiROT (one boot stage)

The Firmware/Data image installations and update is adressed in the next sections.
When the installation is done, at each power-on or reset of the device, the STiROT is executed first.

  • When the STiROT is executed, the debugger is deactivated and there is no possibility of access from user.
  • After a successful verification of the user application (integrity and authenticity), the STiROT executes the user application in temporal isolation level 2 (HDPL2 for this example) and in secure mode.
  • In case there is a verification failure of the user application code, the STiROT will execute the embedded Bootloader (refer to AN2606) to download a new user app code and/or data.
  • As mentioned, the How_to_start_with_ST-iROT_on_STM32H573 hands-on uses a full secure 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 hands-on.
  • The definition that the user application is full secure is done during the STiROT configuration.
  • The activation or not of the data image is also done during the STiROT configuration.
  • The data can for instances be used to store keys or any other secret information needed by the user. But for this "how to" example, it is just data without meaning 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 for the "how to".
Read STiROT_for_STM32H5 article for more details.

  • Two configuration xml files are provided in the STM32CubeFW with default value.
  • The STM32TrustedPackageCreator (TPC) is used to graphically update to the chosen configuration.
  • TPC will save the modification in the configuration xml file.
  • Two OB Key files are generated with TPC. These two encrypted files are used during the provisioning of the device.

A script (Provisioning.bat) provided in the STM32Cube_FW, is guiding the user during the configuration definition and device programming.

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

The configuration management is the step1 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 open and edited with STM32TrustedPackageCreator:

  • STM32Cube_FW_H5_Vx.x.x\Projects\STM32H573I-DK\ROT_Provisioning\STiROT\Config\STiRoT_Config.xml.
  • This default file contains already the configuration listed below.

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

  • Two images: one user application code image & one user application data images
  • User application full secure.
  • Flash location for user application (defined as offset from the beginning of the user flash, aligned with a sector start address; for this example: 0x00000000).
  • Flash location for the user application download (defined as offset from the beginning of the user flash, aligned with a sector start address; for this example: 0x001E0000).
  • Firmware area size (for download and execution), aligned on sector size (for this example: 0x00020000),
  • Flash location for the data download (defined as offset from the beginning of the user flash, aligned with a sector start address; for this example: 0x001DE000).
  • Encryption and authentication key location (only ECDSA256 supported)
  • Minimal product state: OPEN, this means that the STiROT will allow the user firmware execution for all the possible product states.
  • Two keys are provisioned: a key for the authentication and a key for the file encryption. Default keys are provided in the STM32Cube_FW but can be regenerated using STM32TrustedPackageCreator. (see How to start with ST-iROT 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 DHUK (Derived Hardware Unique Key, not accessible by a user) and stored encrypted in the secure storage area (for this example: HDPL2 secure storage and DHUK is used) (see STiROT_for_STM32H5 article).

When the STiROT configuration is ready in TPC, clicking "Generate OBkey" button in 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 into 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 different state than OPEN, a debug authentication is needed to ensure that only the authorized person can access or modify the content of the device.
Without a correct DA provisioning it is not possible to reopen the debugger for these product states different than OPEN.
As shown in figure1, for this example TrustZone is activated. In this case the Debug Authentication is done through a root key and a root certificate (for TZ=0 it's done through a password but only a 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

This file can be edited using STM32TrustedPackageCreator.
The root key can be regenerated for a custom protection of the device (important for a commercial product).
But for this example or for trials it is advised to use the default provided key, because if the new generated key is lost you can't reopen the device or perform a regression.
The permission mask edited graphically in TPC, is used to define the authorization that the owner of the root key and certificate will have.
These permissions are stored in what is called the SOC_MASK and is programmed into de device during the provisioning step.

Details about the Debug Authentication are available in the Debug_Authentication_for_STM32H5_MCUs article.

When the DA configuration is ready in TPC, clicking "Generate OBkey" button in TPC generates 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 into the device.

4. Firmware code and data images generation

The step 2 of the script (Provisioning.bat in STM32CubeFW) is the user application firmware image generation.

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

  • User application firmware image
  • The user data image

To be compatible with STiROT there are some specific format for these two files. For the STM32CubeFW examples you don't need to take care of these formats. But in case of own development, you will need to understand it, at least to define the correct size of your user application code and data. (refer to the STiROT_for_STM32H5 article)


4.1. User application code image generation

The described example is for a full secure user application.
So for the STiROT configuration with STM32TrustedPackageCreator (TPC) you need to tick the "Is the firmware full secure".
And in TPC the "Size of the secure area inside the firmware execution area" is grayed automatically and can't be filled-out.
But even in case of a secure and non-secure user applications, 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, TPC can be used to generate the image.

How to proceed for both ways is explained in the How_to_start_with_ST-iROT_on_STM32H573 article


4.2. User data image generation

The described example is using a data file.
These data are just used to be written back during user application execution and have no other meaning.
So for the STiROT configuration with STM32TrustedPackageCreator (TPC), you need to select "firmware and data images".

For the data image generation, you need to use TPC as described in the How_to_start_with_ST-iROT_on_STM32H573 article

5. Provisioning

The step 3 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 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. It will guide you step by step.

6. Regression

For product state different than OPEN, you need to perform a full regression to retrieve an empty board.

A full regression erases the user stored contents and secrets.

  • Erase the obkeys.
  • 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 in open state.

There are two way 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 in a transparent way for 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_ST-iROT_on_STM32H573 Full_regression)
    • Using the "Discover" button will indicate the product state even if a debugger can't be connected (except in LOCKED state)
    • For the regression the path above to the root key and certificate needs to be selected
Retrieved from "https://wiki.st.com/stm32mcu/index.php?title=Security:STiRoT_STM32H5_How_to_intro&oldid=33768"