How to start with ST-uRoT on STM32H573

How to start with ST-uRoT on STM32H57385min

Target description

The purpose of this article is to explain step by step how to use the STM32CubeFW example STiROT_OEMuRoT provided by ST, using the STM32H573 discovery board.

• How to use the script provided by ST and perform all the required steps.
• How to install and run the user application example which is provided.
• How to perform a regression to retrieve an empty board with initial settings.

Introduction

• Start by reading the STiROT STM32H5 How to intro article.
• For more details and to get an overview on STiROT, read the STiROT for STM32H5 and STiROT articles.

Through this practical example you will learn:

• What STiROT is and how to use the STM32CubeFW example which is provided.
• How to configure the STiROT and OEMuRoT for this example.
• How to generate an encrypted and signed image for the user application firmware and user data.
• What the device provisioning is and how to perform the setup of the device.
• How the user application and user data are installed.

Prerequisites

• Hardware
  • STM32H573 discovery board: the STM32H573 devices have all the available security features, including the HW crypto accelerator. (Note that for the STM32H56x devices, the HW crypto is not available)
    
  • Discovery MB1677- STM32H573 (need USBC cable)

Figure 1 STM32H573 DK MB1677.png

• Required tools
  • STM32Cube_FW_H5_V1.0.0 or later
  • STM32CubeProgrammer_rev2.13.0 or more recent (with trusted package creator (TPC) selected at installation).
  • IAR Embedded Workbench^® rev 9.20.1 or later.
  • Tera Term / Putty or equivalent terminal emulator.

Information

The TPC installed together with CubeProgrammer in the bin folder located in default STM32CubeProgrammer path : C:\Program Files\STMicroelectronics\STM32Cube\STM32CubeProgrammer\bin You can pin this tool to the taskbar to simplify the "STiROT Getting started" process :

• STM32Cube Firmware
  • Download the STM32CubeFW_H5 Cube firmware (Place it as close as possible to the C: root, to avoid long windows path)
  • A directory STM32H573I-DK is included in the “Projects” directory
  • If the STM32CubeProgrammer has not been installed in the default folder:C:\Program Files\STMicroelectronics\STM32Cube\STM32CubeProgrammer, the customized installation path needs to be updated in the environment variable: env.bat
  • Check that the selected application path is correct: for the following tutorial the STiROT fully secured example is described => The STiROT_Appli must be active.

Figure 2: STM32Cube_FW_H5

• Check that the selected application path is correct, as shown in the figure below: for the following tutorial, the STiROT fully secured example is described => The STiROT_Appli must be active.

Figure 3 STM32H573 env.bat

Literature

• Wiki pages:
  • STiROT STM32H5 How to intro article.
  • STiROT for STM32H5 article.
  • STiROT article.
  • Debug Authentication STM32H5 How to Introduction article.
• UM2237 STM32CubeProgrammer software description
• UM2238 STM32 trusted package creator (TPC) tool software description
• AN5054 Secure programming using STM32CubeProgrammer

Step by step instructions

• The different stages to configure and use the STiROT_OEMuRoT are based on a script provided in the STM32CubeFW (provisioning.bat)
• The following documentation is a guide through all the steps of this script, and explains how to perform each of them.

1. STiROT, debug authentication and OEMuRoT configuration

This chapter explains how to start with the provisioning script.
It is used to first configure the STiROT, the debug authentication and the OEMuRoT.
The figure below shows where the script is located in the STM32CubeFW.

• Launch the provisioning.bat (double click) and keep it running during all the following steps

1.1. STiROT configuration

As indicated by the script, the first step is to define the appropriate STiROT configuration and to generate the related STiROT_Config.obk file. This file will be used in a later step to configure the MCU and to set the related option bytes.

The STiROT configuration is based on the STiROT_Config.xml file.
A default file is provided in the STM32Cube_FW.

The STiROT_Config.xml file can be opened and updated using the STM32 trusted package creator but this file can be modified using a text editor.

The following parameters can be defined in the STiROT_Config.xml

• The number of images managed (code image only, or code and data images)
• Mapping information (offset and size of each execution and download slots)
• Size of the secure area when the firmware is not fully secured.
• Product state minimum allowed
• ECDSA-256 encryption key
• ECDSA-256 authentication key
• High speed boot (240Mhz vs 64Mhz) capability
• SRAM2 erasing in case of reset activation
• SRAM2 ECC management activation

Note:
In order to mitigate the risk of attacks, some major information are duplicated between option bytes and Obkeys configuration such as sram2_ecc, sram2_rst, secure watermark, product_state.
The STiROT does not start (reset generated) if an error is detected during the control of these information. In this case, a regression must be done before restarting the provisioning process with a correct configuration.
This does not happen if the product is used according to specifications and if the product is not subject to an attack.
To understand what happens during the boot sequence, the status provided through the discovery command of the debug authentication needs to be analyzed.
The debug authentication and discovery command launched with the STM32CubeProgrammer are explained later in this article.
The discovery command can be launched through an STM32CubeProgrammer CLI command (.\STM32_Programmer_CLI.exe -c port=swd debugauth=2)

1.1.1. STiROT configuration file generation (STiROT_Config.obk)

To generate a customized configuration file, you must follow these steps:

1. Open the trusted package creator (TPC) and select H5 (TPC installed together with CubeProgrammer)
2. Open the Obkey tab
3. Select the STiROT_Config.xml file
4. Update the parameters (this example is for a fully secured code and data)
5. The default encryption and authentication keys can be regenerated
6. Generate the file by clicking "Generate OBkey".

The STiROT_Config.obk file is generated, and the modified parameters are saved in STiROT_Config.xml file
(Click on the picture to view it in full screen)

When the STiROT_Config.obk file generation is completed, a "Success OBKey File Generation" window is displayed.

1.2. Debug authentication configuration

• A default working configuration enabling all the DA capabilities (regression, debug opening) is provided in the STM32CubeFW. This configuration can be used for this tutorial.
• Warning: for your own application, it is mandatory to define you own custom DA configuration. For a commercial product, it is important to regenerate the debug authentication root key (key_1_root.pem, as explained in next section)
• The following sections explain how to define a custom configuration.
• Press any key in the provisioning script window. The next step is indicated: debug authentication configuration. The following section describes how to complete this step.

At this step, the debug authentication will be configured and the related (DA_Config.obk) will be generated.
The DA_Config.obk is used to configure the conditions to reopen a protected device and the debugger. This file will be used in a later step to configure the MCU and to set the related option bytes.

The debug authentication configuration is based on the DA_Config.xml file used as input for the trusted package creator. A default file is provided in the STM32Cube_FW.

Figure 9 STM32H573 STiROT DA config xml

Two files are included in the “DA\Config” directory:

• DA_Config.xml : a configuration based on certificates for the H5 crypto parts (such file is used for this tutorial)
• DA_ConfigWithPassword.xml : is not used for STiROT (only for use cases with TrustZone^® not activated)

1.2.1. DA configuration file generation (DA_Config.obk)

To generate a customized configuration file the following steps need to be followed:

1. Open the trusted package creator and select H5 (installed through the "CubeProgrammer Installation")
2. Open the Obkey tab
3. Select the DA_Config.xml file
4. Update the parameters
5. Generate the file by clicking "Generate OBkey".

The DA_Config.obk file is generated, and the modified parameters are saved in DA_Config.xml file
(Click on the picture to view it in full screen)

• Note:: The level 1 (HDPL1) is reserved for the STiROT, a debug opening in level 1 is not allowed (even when selected in the permission mask). (see wiki article dedicated to lifecycle).
• Warning: For a commercial product, it is important to regenerate the debug authentication root key (key_1_root.pem), as the key provided in the STM32CubeFW is public. You must store it in a safe place.

1.2.2. Short explanation about the permission masks

For more information on the debug authentication and the related permission masks, refer to the: Debug Authentication for STM32H5 article.
During the previous step, the permissions to reconnect a debugger and to make a regression were chosen.
This permission mask is called the "SOC_MASK".
The SOC permissions are included in the DA_Config.obk generated file and used for the configuration stored into the device. The owner of the root key (key_1_root.pem) and the related certificate (cert_root.b64) can request these defined permissions.
It is possible to define different permissions for different users, for instance for different OEMs or final customers. Refer to debug authentication and certificate chain chapter.

• Note: If the root key is regenerated (see the "regenerate" button in the figure above), you must regenerate the root certificate (cert_root.b64) using the STM32 Trusted Package Creator, as shown in next section.

1.2.3. Regenerate the root certificate in case the root key is regenerated

• The following steps are only required if the root key (key_1_root.pem) has been regenerated.
• In the STM32 trusted package creator (TPC), select the DA CertifGen.
• Open the link to the private and public root key located in the CubeFW DA/Keys folder, as shown in the figure below.
• Select the certificate file in the CubeFW DA/Certificates folder, as shown in the figure below. A warning message is displayed, confirm you wish to overwrite the existing certificate.
• Click "Generate Certificate"

(Click on the picture to view it in full screen)

1.3. OEMuRoT configuration

The OEMuRoT configuration is based on the OEMuRoT_Config_Keys.xml file.
A default file is provided in the STM32Cube_FW.

The OEMuRoT_Config_Keys.xml file can be opened and updated using the STM32 trusted package creator but this file can be modified using a text editor.

• ECDSA-256 encryption key
• ECDSA-256 authentication key

1.3.1. OEMuRoT configuration file generation (OEMuRoT_Config_intermediate.bin)

To generate a customized configuration file, you must follow these steps:

1. Open the trusted package creator (TPC) and select H5 (TPC installed together with CubeProgrammer)
2. Open the Obkey tab
3. Select the OEMuRoT_Config_Keys.xml file
4. The default encryption and authentication keys can be regenerated
5. Generate the file by clicking "Generate OBkey".

The OEMuRoT_Config_intermediate.bin file is generated

1.4. Images generation

Step 2 of the provisioning corresponds to the generation of the images.

1.4.1. OEMiROT_Boot project configuration

Check that the STM32H5 IAR™ provided patch is correctly installed and check that your IAR Embedded Workbench™ version is recent enough.

OEMiROT_Boot corresponds to the Secure Boot. It performs authenticity and integrity checks of the project firmware and data images.

Number of code images and Data images is defined in flash_layout.h file in the
./Projects\STM32H573I-DK\Applications\ROT\OEMiROT_Boot\Inc folder.

In this example we want to use

• 1 secure code image
• 1 non-secure code image
• 1 secure Data image
• 1 non-secure Data image

Please update the file flash_layout.h as shown in figure below  :

Information

During the OEMiROT_Boot execution, if the number of images is wrong, Bootloader is launched to load new code and/or data images.

1.4.2. OEMiROT_Boot firmware image generation

• Open the Project.eww located in the EWARM directory: Projects\STM32H573I-DK\Applications\ROT\OEMiROT_Boot\EWARM
• Open Project -> Option -> General Options: The device and CPU core should be automatically recognized and you should see the following windows:

If the device is not recognized, check that the STM32H5 IAR™ provided patch is correctly installed, and check that your IAR Embedded Workbench™ version is recent enough.

• Perform: Project -> Rebuild all (don’t upload the code, only perform a compilation)

The following binary is created: Projects\STM32H573I-DK\Applications\ROT\OEMiROT_Boot\EWARM\STM32H573I_DK\Exe\Project.bin

1.4.3. Code firmware image generation

OEMiROT_Appli_TrustZone project compilation –Secure Project

• Open the Project.eww located in the EWARM directory:

Projects\STM32H573I-DK\Applications\ROT\OEMiROT_Appli_TrustZone\EWARM

• Select the Secure Project:

• Open Project -> Option -> General Options

The device and CPU core should be automatically recognized.

• Open Project -> Option -> Build Actions

Here is the command line which will create an image of the code with STM32TrustedPackageCreator:

• Perform: Project -> Rebuild all (don’t upload the code, only perform a compilation)

The following image is created: Projects\STM32H573I-DK\Applications\ROT\OEMiROT_Appli_TrustZone\Binary\rot_tz_s_app_enc_sign.hex Don’t close the EWARM project.

OEMiROT_Appli_TrustZone project compilation –Non-Secure Project

• Select the Nonsecure Project:

• Open Project -> Option -> Build Actions and check the correct paths for the command line

This Postbuild command will create an image of the compiled non secure code thanks to STM32TrustedPackageCreator.

• Perform: Project -> Rebuild all (don’t upload the code, only perform a compilation)

The following image is created: Projects\STM32H573I-DK\Applications\ROT\OEMiROT_Appli_TrustZone\Binary\rot_tz_ns_app_enc_sign.hex

1.4.4. Data image generation

During this step, two image files will be created from secure and nonsecure data files.

The provided data files s_data.bin and ns_data.bin are just example files for this tutorial but have no meaning and are not used for the code execution.

This tutorial shows an example for a two-code, two-data-images installation, but other configurations are also possible.

To generate images of secure and nonsecure data you must:

• Open STM32TrustedPackageCreator and select H5.
• Open the ImageGen tab.
• Select the template for the relevant image: OEMuROT_S_Data_Image.xml (in ROT_Provisioning\STiROT_OEMuROT\Images directory)
• Update the default configuration if required:
  • Update the version number.
  • Enable the dependency with the other data image when simultaneous installation is required for compatibility reasons.
  • Select the binary file to be used as an input file.
  • Select the output file to be filled with the signed and encrypted binary (HEX format).
• Launch the generation.
• An encrypted signed file will be created: s_data_enc_sign.hex

Resume these steps by selecting the OEMuROT_NS_Data_Image.xml template in order to generate an ns_data_enc_sign.hex image.