How to start with STiRoT_OEMuRoT on STM32H573

How to start with STiRoT_OEMuRoT 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.
Based on the following description, it is straightforward to use the STiROT_OEMuROT example provided in the STM32CubeFW for the Nucleo-H533.

• 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.
  

Description of the bootpath in this usecase :

Refer to the following link for more details about this second boot stage updatable by the user: STiRoT for STM32H5 : Two boot stages

This practical example explains:

• 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 (USBC cable required)

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 is installed together with CubeProgrammer in the bin folder located in the 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 a long file 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.
• Note: For Linux and Mac operating systems, the end users may have to change manually the attribute of .sh scripts to executable.

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 is 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

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, follow the steps below:

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). There is a second boot stage, OEMuRoT, so code and data configured here concern OEMuRoT.
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).

• For a commercial product, it is mandatory to regenerate the encryption and authentication keys.

When the STiROT_Config.obk file generation is complete, 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 your 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 is configured and the related (DA_Config.obk) is generated.
The DA_Config.obk is used to configure the conditions to reopen a protected device and the debugger. This file is 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 (this type of file is used in 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, follow the steps below:

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 the 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 required only 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. A warning message is displayed, confirm that you want to overwrite the existing certificate.
• Click "Generate Certificate".

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

1.3. OEMuRoT configuration

OEMuRoT is the updatable root of trust. It can be updated on a production device.

Press any key in the provisioning script window. The next step is OEMuRoT configuration and the following section describes how to complete this step.

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, follow the steps below:

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.

• For a commercial product, it is mandatory to regenerate the authentication and encryption keys.

After this step, the provisioning script is automatically created in a second step the file OEMuRoT_Config.obk.

2. Images generation

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

2.1. Boot firmware image generation

2.1.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.

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 use

• 1 secure code image
• 1 nonsecure code image
• 1 secure data image
• 1 nonsecure data image

Please update the file flash_layout.h as shown in the 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.

2.1.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 are automatically recognized and you should see the window below.

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.

• 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

2.2. 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

The command line which creates an image of the code with STM32TrustedPackageCreator is:

• 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 –Nonsecure Project

• Select the Nonsecure Project:

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

This Postbuild command creates an image of the compiled nonsecure code using the 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

2.3. Data image generation

During this step, two image files are 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:

• 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 is 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.

3. Provisioning

Step 3 of the provisioning script program the OB and flash the images previously generated.

• Connect your board on your laptop.
• Connect STM32CubeProgrammer and check that the device is in open state.
  

If the device is not in open state, refer to Regression paragraph, which explains the regression. If the flash memory is not erased, the provisioning script erases it anyway.

• Disconnect from STM32CubeProgrammer.

• Go back to the provisioning script window and press a key.
  

The script program the OB and flash the images previously generated.
The product state can be chosen (OPEN or PROVISIONED or TZ-CLOSED or CLOSED or LOCKED).

Warning

Reminder: LOCKED is a definitive product step that cannot be changed.

Make a first trial by setting the product in CLOSED state and complete the tutorial until the end.

4. Execute the installed firmware

• Open PUTTY (or another terminal emulator).
• Select “Serial" and the COMxx port*.
• Set speed to 115200.
• Data 8 bits / Parity None / Stop 1 bit
• Click Open.

• Reset the board using the SW reset button on the board:

The code installed during the previous steps is executed.

The menu of the installed code has two options:

• The menu 1 launchs the standard bootloader located in the system flash.
• The menu 2 displays the first 8 bytes and the last 8 bytes of the ns_data.bin