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.

How to start with OEMiRoT on STM32H7S

Literature

OEMiRoT STM32H7S How to Introduction
How to start with DA access and FW update on STM32H7S
UM2237 STM32CubeProgrammer software description
UM2238 STM32 trusted package creator (TPC) tool software description
AN5054 Secure programming using STM32CubeProgrammer

Target description

The purpose of this article is to explain step by step how to use the STM32CubeFW example provided by ST, for OEMiRoT, using the STM32H7S 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.

Based on this STM32CubeFW example, additional exercises are proposed

To generate a certificate chain.
To reopen the debugger in CLOSED product states
To attach an IDE
To perform a firmware upgrade using the bootloader

Introduction

Start by reading the zzzzzz article.
For more details and to get an overview on OEMiRoT, read the zzzzzzzz articles.

One example of OEMiRoT is provided in the STM32Cube_FW that is used in this "getting started".

Through this practical example you will learn:

What OEMiRoT is and how to use the STM32CubeFW example which is provided.
How to configure the OEMiRoT and the debug authentication for this example.
What is the iLoader and its role.
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.
How to perform a debug authentication and reopen the debugger.
How to read the installed user application firmware using the STM32CubeProgrammer
How to attach an IDE on a running target and execute step by step, the secure user application
How to perform a regression to retrieve an empty board
The principle of certificate chain.

Prerequisites

Hardware
- STM32H7S discovery board: the STM32H7S devices have all the available security features, including the HW crypto accelerator (the HW cryptographic acceleration is not support for STM327R devices).
- Discovery MB1736- STM32H7S (need USBC cable)

Required tools
- STM32Cube_FW_H7RS_V1.0.0RC2 or later
- STM32CubeProgrammer_rev0.0.5-H7RS-B01 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 STM32Cube_FW_H7RS Cube firmware (advise is to place it close form the C: in order to avoid long windows paths)
- A directory STM32H7S78-DK is included in "STM32Cube_FW_H7RS\Projects"

Open the env.bat file

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

2- Update the COM port to be aligned with your COM port number.

Use the Windows device manager to find out your COM port number, as shown in figure below

3- Check that the OEMiRoT_Appli path is OK

1. Example with PASSWORD configuration

This chapter explains how to start with the provisioning script.
It is used to configure the OEMiRoT and the debug authentication.

1.1. Preliminary stage

The different steps to configure and use the OEMiRoT are based on a script provided in the STM32CubeFW:

Projects\STM32H7S78-DK\ROT_Provisioning\OEMiROT\provisioning.bat

The following documentation is a guide through all the steps of this script, and explains how to perform each of them.

The figure below shows where the script is located in the STM32CubeFW.

Launch the script: provisioning.bat (double click) and keep it running during all the following steps.
- Type the product state: CLOSED (don't use LOCKED for this tutorial, this state is used only to set a final product state)
- Type the chosen Debug Authentication: PASSWORD (for explanation about certificate and password refer to intro article)

1.2. OEMiRoT configuration

The next step indicated by the script is to open the OEMiROT_Config.xml file, update to the wanted configuration and to generate the OBk file.

Open STM32TrustedPackageCreator.

Select the shield
Select OBkey tab
Select the OEMiRoT_Config.xml configuration file. All the default settings for this hands-on are already filled-in and it is not needed to regenerate the encryption and authentication keys. In case these keys are regenerated, the firmware image needs to be regenerated (in case this image is already available)
Generate OBkey
The confirmation window is displayed

According to the path specified in the OEMiROT_Config.xml, an OEMiROT_Config.obk file is generated in Projects\STM32H7S78-DK\ROT_Provisioning\OEMiROT\Binary folder. This file will be used by the script during the provisioning step.

1.3. Debug Authentication configuration

The Debug Authentication (DA) configuration is the next step of the script.

Using STM32TrustedPackageCreator

Select the shield
Select OBkey tab
Select the DA_Config.xml configuration file. All the default settings for this hands-on are already filled-in .
Generate OBkey
A success message is displayed for the password file password.bin generation
The confirmation window is displayed

Warning: for a commercial product, it is important to define your own key. But for trials it is advised to use the default provided, to avoid blocked regression due to lost password.

According to the path specified in the DA_Config.xml, a DA_Config.obk file is generated in Projects\STM32H7S78-DK\ROT_Provisioning\DA\Binary folder. This file will be used by the script during the provisioning step.

1.4. Image generation

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

Two code examples for IAR Embedded Workbench™ are provided:

OEMiROT_Boot corresponds to the Secure Boot.

It performs authenticity and integrity checks of the project firmware and data images.

OEMiROT_Appli is an example of application managed by OEMiROT

OEMiROT_Boot project configuration
The step 3 of the scripte is the generation of the OEMiROT_Boot and OEMiROT_Appli applications firmware images.

Open the Project.eww located in the EWARM directory: Projects\STM32H7S78-DK\Applications\ROT\OEMiROT_Boot\EWARM

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

This example is configured by default for one application image and no data image. You can check these default parameters in 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.

OEMiROT_Boot project compilation

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\STM32H7S78-DK\Applications\ROT\OEMiROT_Boot\Binary\OEMiROT_Boot.bin

OEMiROT_Appli project compilation

Open the Project.eww located in the EWARM directory:

Projects\STM32H7S78-DK\Applications\ROT\OEMiROT_Appli\EWARM

Open Project -> Option -> General Options

The device and CPU core should be automatically recognized.

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

The following image is created: Projects\STM32H7S78-DK\Applications\ROT\OEMiROT_Appli\Binary\rot_app_enc_sign.hex Don’t close the EWARM project.

1.5. Board programming

In the next steps the script will automatically perform

The provisioning of the Option Byte
Flash the previously generated image in the downloads area
Perform the needed reset to install the code
Set the final state of the product

If all the steps have been executed successfully, a confirmation is displayed as shown in the figure above.

1.6. OEMiRoT application execution

Close the script
Launch the Teraterm (or equivalent)
File => New connection
The COM port number should be the same as indicated by your Windows device manager and also written in the env.bat file (see Prerequisites chapter)
Setup => Serial port -> update to 115200 (and see the figure below for other configurations) -> New Setting

Press the reset button (black button of the discovery board)
The OEMiRoT application is executed (figure below)

1.7. Full regression

There are two ways to perform a regression
- Using the graphic interface of the STM32CubeProgrammer.
- Using the regression script provided in the STM32CubeFW

1.7.1. Full regression using the script provided in the STM32CubeFW

Launch the script as shown in the figure below

You need to specify if the Debug Authentication provisioning as been done with Certificate or Password.
Type "Password" for this example
The script is executed and indicate that the regression has been performed successfully.

1.7.2. Full regression using the graphic interface of the STM32CubeProgrammer

Click in STM32CubeProgrammer
Select Debug Authentication.
Click “Discover”
The information window will be filled:

Enter the file password.bin path and click Regression

2. Example with CERTIFICATE configuration

2.1. OEMiRoT and debug authentication configuration

This chapter explains how to start with the provisioning script. It is used to configure the OEMiRoT and the debug authentication (in this case a configuration using a certificate)

2.2. Preliminary stage

The same provisioning script is used as for the example for a Debug Authentication configuration with Password.
- Script located at: STM32CubeFW: STM32H7S78-DK\ROT_Provisioning\STiROT\provisioning.bat
The following documentation is a guide through all the steps of this script, and explains how to perform each of them.

Launch the script: provisioning.bat (double click) and keep it running during all the following steps.
Type the product state: CLOSED (don't use LOCKED for this tutorial, this state is used only to set a final product state)
Type the chosen Debug Authentication: CERTIFICATE (for explanation about certificate and password refer to intro article)

2.3. OEMiRoT configuration

The next step indicated by the script is to open the OEMiROT_Config.xml file, update to the wanted configuration and to generate the OBk file.

Open STM32TrustedPackageCreator.

Select the shield
Select OBkey tab
Select the OEMiRoT_Config.xml configuration file. All the default settings for this hands-on are already filled-in and it is not needed to regenerate the encryption and authentication keys. In case these keys are regenerated, the firmware image needs to be regenerated (in case this image is already available)
Generate OBkey
The confirmation window is displayed

According to the path specified in the OEMiROT_Config.xml, an OEMiROT_Config.obk file is generated in Projects\STM32H7S78-DK\ROT_Provisioning\OEMiROT\Binary folder. This file will be used by the script during the provisioning step.

2.4. Debug Authentication configuration

The Debug Authentication (DA) configuration is the next step of the script.

Using STM32TrustedPackageCreator

Select the shield
Select OBkey tab
Select the DA_Config.xml configuration file (file for the DA configuration with Certificate). All the default settings for this hands-on are already filled-in and a default Debug Authentication root key is provided.
Generate OBkey
The confirmation window is displayed

Warning: for a commercial product, it is important to regenerate your own Debug Authentication root key. But for trials it is advised to use the default provided, to avoid blocked regression due to lost key.

According to the path specified in the DA_Config.xml, a DA_Config.obk file is generated as shown in the figure below.

This file will be used by the script during the provisioning step.

2.5. Image generation

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

Two code examples for IAR Embedded Workbench™ are provided:

OEMiROT_Boot corresponds to the Secure Boot.

It performs authenticity and integrity checks of the project firmware and data images.

OEMiROT_Appli is an example of application managed by OEMiROT

OEMiROT_Boot project configuration
The step 3 of the scripte is the generation of the OEMiROT_Boot and OEMiROT_Appli applications firmware images.

Open the Project.eww located in the EWARM directory: Projects\STM32H7S78-DK\Applications\ROT\OEMiROT_Boot\EWARM

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

This example is configured by default for one application image and no data image. You can check these default parameters in 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.

OEMiROT_Boot project compilation

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\STM32H7S78-DK\Applications\ROT\OEMiROT_Boot\Binary\OEMiROT_Boot.bin

OEMiROT_Appli project compilation

Open the Project.eww located in the EWARM directory:

Projects\STM32H7S78-DK\Applications\ROT\OEMiROT_Appli\EWARM

Open Project -> Option -> General Options

The device and CPU core should be automatically recognized.

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

The following image is created: Projects\STM32H7S78-DK\Applications\ROT\OEMiROT_Appli\Binary\rot_app_enc_sign.hex Don’t close the EWARM project.

2.6. Board programming

In the next steps the script will automatically perform

The provisioning of the Option Byte
Flash the previously generated image in the downloads area
Perform the needed reset to install the code
Set the final state of the product

If all the steps have been executed successfully, a confirmation is displayed as shown in the figure above.

2.7. OEMiRoT application execution

Close the script
Launch the Teraterm (or equivalent)
File => New connection
The COM port number should be the same as indicated by your Windows device manager and also written in the env.bat file (see Prerequisites chapter)
Setup => Serial port -> update to 115200 (and see the figure below for other configurations) -> New Setting

Press the reset button (black button of the discovery board)
The OEMiRoT application is executed (figure below)

2.8. Full regression

There are two ways to perform a regression
- Using the graphic interface of the STM32CubeProgrammer.
- Using the regression script provided in the STM32CubeFW

2.8.1. Full regression using the script provided in the STM32CubeFW

Launch the script as shown in the figure below

You need to specify if the Debug Authentication provisioning as been done with Certificate or Password.
Type "Password" for this example
The script is executed and indicate that the regression has been performed successfully.

2.8.2. Full regression using the graphic interface of the STM32CubeProgrammer

Click in STM32CubeProgrammer
Select Debug Authentication.
Click “Discover”
The information window will be filled:

Enter the paths for the key and the certificate (example with a certificate chain will be shown later, in this example only a single certificate is used (ROOT)):

Select Full regression

Click Execute, and the following success Message is displayed: