How to start with OEMiRoT on STM32H7S

How to start with OEMiRoT on STM32H7S


Literature


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.
Info white.png Information
How to start with DA access on STM32H7RS wiki article can also guide you to practice with debug opening, and download a new image from a closed device in download slot, that will generate a firmware update at next reset.

Introduction

Start by reading the OEMiRoT STM32H7S How to Introduction article.

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.
  • How to generate an encrypted and signed image for the user application firmware.
  • What the device provisioning is and how to perform the setup of the device.
  • How the user application is installed.
  • How to perform a regression to retrieve an empty board.

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)
STM32H7S DK.png
  • Required tools
    • STM32Cube_FW_H7RS_V1.0.0 or later
    • STM32CubeProgrammer v2.16.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
Info white.png 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 :
Security PinToTask.png


  • 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" .
STM32Cube FW H7RS.png
  • 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:

Security COM Port.png
  • 3- Check that the OEMiRoT_Appli path is OK. The picture below shows the configuration path for the STM32CubeFW example but it is possible to select an other application that respects OEMiRoT template.
SECURITY H7S OEMiRoT env bat 3.png


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.
SECURITY H7S OEMiRoT Provisioning script.png
  • Before running the provisioning script be careful to disconnect the UART from any terminal tool otherwise the provisioning might fail.
  • 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).
SECURITY H7S OEMiRoT Provisioning password STEP 1.png

1.2. OEMiRoT configuration

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

SECURITY H7S OEMiRoT Provisioning STEP 2 OEMIROT CONFIG 2.png
  • Open STM32TrustedPackageCreator
  1. Select the shield Security DA ICON STM32CubeProgrammer.png
  2. Select OBkey tab
  3. 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)
  4. Generate OBkey
  5. The confirmation window is displayed
SECURITY H7S OEMiRoT Provisioning STEP 2 OEMIROT CONFIG TPC.png


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.

SECURITY H7S DA configuration with password script.png


  • Using STM32TrustedPackageCreator
  1. Select the shield Security DA ICON STM32CubeProgrammer.png
  2. Select OBkey tab
  3. Select the DA_ConfigWithPassword.xml configuration file. All the default settings for this hands-on are already filled-in
  4. Generate OBkey
  5. A success message is displayed for the password file password.bin generation
  6. The confirmation window is displayed
SECURITY H7S DA CONFIG PASSWORD TPC 2.png


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

SECURITY H7S OEMiRoT Applications.png
  • 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 script is the generation of the OEMiROT_Boot and OEMiROT_Appli applications firmware images.

SECURITY H7S OEMiRoT Provisioning STEP 3 script.png
  • 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  :

SECURITY H7S OEMiRoT appli boot images number.png
Info white.png 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:
SECURITY H7S-Options for node Project IAR .png

If the device is not recognized, check that the STM32H7 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

SECURITY H7S OEMiRoT Provisioning STEP 3 script Appli.png
  • 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
SECURITY H7S OEMiRoT Provisioning Success 2.png
  • 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
teraterm config.png
  • Press the reset button (black button of the discovery board)
  • The OEMiRoT application is executed (figure below)
SECURITY H7S OEMiRoT Appli Teraterm.png

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
Security Regression Script.png
  • 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
Security Full Regression Password.png


1.7.2. Full regression using the graphic interface of the STM32CubeProgrammer

  • Click Security DA ICON STM32CubeProgrammer.png in STM32CubeProgrammer
  • Select Debug Authentication.
  • Click “Discover”
  • The information window will be filled:
SECURITY H7S DISCOVERY CMD CB PASSWORD CLOSED STATE 3.png
  • Enter the file password.bin path and click Regression
SECURITY H7S CB FULL REGRESSION PASSWORD CP 2.png

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.
SECURITY H7S OEMiRoT Provisioning script.png
  • Before running the provisioning script be careful to disconnect the UART from any terminal tool otherwise the provisioning might fail.
  • 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)
SECURITY H7S OEMiRoT Provisioning STEP 1.png

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.

SECURITY H7S OEMiRoT Provisioning STEP 2 OEMIROT CONFIG.png
  • Open STM32TrustedPackageCreator.
  1. Select the shield Security DA ICON STM32CubeProgrammer.png
  2. Select OBkey tab
  3. 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)
  4. Generate OBkey
  5. The confirmation window is displayed
SECURITY H7S OEMiRoT Provisioning STEP 2 OEMIROT CONFIG TPC.png


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.

Security H7S DA configuration script.png
  • Using STM32TrustedPackageCreator
  1. Select the shield Security DA ICON STM32CubeProgrammer.png
  2. Select OBkey tab
  3. 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.
  4. Generate OBkey
  5. The confirmation window is displayed
SECURITY H7S DA CONFIG CERTIFICATE TPC 2.png
  • 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.

Security DA config obk generation.png

2.5. Image generation

Check that the STM32H7 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:

SECURITY H7S OEMiRoT Applications.png
  • 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.

SECURITY H7S OEMiRoT Provisioning STEP 3 script.png
  • 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  :

SECURITY H7S OEMiRoT appli boot images number.png
Info white.png 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

SECURITY H7S OEMiRoT Provisioning STEP 3 script Appli.png
  • 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
SECURITY H7S OEMiRoT Provisioning Success 2.png
  • 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
teraterm config.png
  • Press the reset button (black button of the discovery board)
  • The OEMiRoT application is executed (figure below)
SECURITY H7S OEMiRoT Appli Teraterm.png


2.8. Debug Authentication and firmware modification or full regression

  • How to open the debugger, attach an IDE to make a step-by-step user application execution, make a modification of the user application and upload the modified firmware is explained in the following chapters.
  • If no further trials are done, it is advised to make a regression to retrieve an empty board.


3. Debug Opening (intrusive debug)

For a device in closed state the debugger is no open and you have an error message if you try to connect STM32CubeProgrammer.
To open the debug it is mandatory that the device has been provisioned in closed state with Certificate Debug Authentication.

Warning white.png Warning
If the device has been provisioned with Password Debug Authentication, only a full regression is possible and a debug opening is not allowed.
Info white.png Information
Only the owner of the key and certificate can open the debugger.


3.1. Prerequisites

Please follow OEMiRoT example with CERTIFICATE configuration until 2.7 OEMiRoT application execution. Don't perform a full regression, the device must be in closed state.

3.2. Debug Opening procedure

  • Open STM32CubeProgrammer
  • Select the shield Security DA ICON STM32CubeProgrammer.png
  • Click on "Discover" -> the product state "Closed" is displayed
  • Browse the paths for the root key and the certificate, as indicated in the figure below
  • Click on continue -> the permission window is open
  • Select "Level 3 Intrusive Debug"
Info white.png Information
For the OEMiRoT example the application code is in HDPL3, see OEMiRoT and OEMuRoT for STM32H7S article.

A debug opening in level 2 or in level 3 will make the application visible.

  • Click Execute -> A Debug Authentication Success message is displayed
SECURITY Debug opening for OEMiRoT usecase - STM32CubePG.png
  • The debugger is open and the content of the flash can be readout, as shown in figure below
SECURITY Debug opening for OEMiRoT usecase - Read memory.png
Info white.png Information
The memory mapping of the code is detailed in Project.map located in:

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

The debugger will stay open until the next hardware reset.

  • Disconnect STM32CubeProgrammer
Warning white.png Warning
! Don’t power ON / OFF the board, it closes the debugger.

3.3. IAR connection, step by step user application execution

To attach an IDE:

  • Disconnect STM32CubeProgrammer
Warning white.png Warning
! Don’t power ON / OFF the board, it closes the debugger
  • Open the Project.eww located in the EWARM.
  • Select: Project -> Attach to running target
  • Open the main.c
  • Set a break point, run the program in the debugger
  • Reset the board (black button) and the execution will stop at this point
  • Select: View->Memory-> Memory1 and enter the flash address => The nonsecure code is visible @ 0x70000400
SECURITY Debug opening for OEMiRoT usecase - IAR.png

4. Download a new image from a closed device

The following description shows how to access to bootloader from a closed device in order to download a new image. After a reset a firmware update will be generated.
Forced download feature allows to access to secure bootloader.
At the date of writing this article, the GUI graphical interface is not yet functional to use Forced download feature.

The following example shows how to proceed using the debug authentication script and download new image through command line.

4.1. Prerequisites

To follow the procedure described bellow the device must be provisioned in closed state with OEMiRoT.
If you followed the paragraph Debug opening, your device must be in closed state. Please disconnect and reconnect your board with the USB cable to be sure your device is not in debug opening mode.

If you didn't follow the debug opening part of this wiki, please perform OEMiRoT example with CERTIFICATE configuration until 2.7 OEMiRoT application execution. Don't perform a full regression, the device must be in closed state.

4.2. Firmware modification

Make some modifications of the OEMiRoT_Appli and rebuild all the file ->an encrypted image is created through postbuild command.

For example you can make this proposed modification in main.c file and rebuild the project :

SECURITY FW Update for OEMiRoT usecase - fw modif.png

If applicable: close IAR or Disconnect STM32CubeProgrammer

4.3. Debug Authentification

  • Unplug/ replug the Discovery board USB cable to make a hardware reset. If the debugger was open, it will be closed again.
  • Launch the dbg_auth.bat script.
Security Debug authentication script.png
  • Type "e" to select the Forced Download. (See the permission set during the certificate generation, DA setting using TPC).
  • The script will indicate an error. Ignore it, this will be fixed in later script version.


Security Debug authentication script execution.png

4.4. New application code image download

  • In a command prompt: execute the command indicated below
  • Depending on your PC administrator rights, you need to run it from the STM32CubeProgrammer installation directory: C:\Program Files\STMicroelectronics\STM32Cube\STM32CubeProgrammer_revx.x.x-H7RS-xxx\bin
  • Command to execute:
STM32_Programmer_CLI.exe -c port=COMxx br=921600  -elbl "ExternalLoader\MX66UW1G45G_STM32H7S78-DK_XSPIM1-SFIx.stldr" -d C:\Users\'''xxxxx'''\STM32Cube_FW_H7RS_Vx.x.x\Projects\STM32H7S78-DK\Applications\ROT\OEMiROT_Appli\Binary\rot_app_enc_sign.hex
Note:the xxx needs to be adapted for your configuration.
  • The new image of the application code is downloaded in the external flash donwload area defined during the OEMiRoT configuration defined previously
  • At next reset the OEMiRoT will detect that a new firmware needs to be installed and perform automatically the installation (this is transparent for a user)


Security Firmware upgrade command line.png

4.5. New installed application code execution

  • Launch the Teraterm (or equivalent)
  • Reminder:
    • 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 new OEMiRoT application is executed as shown in the figure below, and the modification made are displayed:
Security New OEMiRoT application execution.png

4.6. Full regression using graphic interface

Previously the regression script has been used.
Following an example showing how to proceed using the graphic interface of STM32CubeProgrammer.

  • Close Teraterm
  • Start STM32CubeProgrammer
  • Select the shield Security DA ICON STM32CubeProgrammer.png
  • Click on "Discover" -> the product state "Closed" is displayed
  • Browse the paths for the root key and the certificate, as indicated in the figure below
  • Click on continue -> the permission window is open
  • Select Full Regression
  • Click Execute -> A Debug Authentication Success message is displayed
Security Full regression Cube Progr.png
  • Using STM32CubeProgrammer, you can verify that the flash is empty and that the device is back in "Open" state.
Note: it's a good habit to make a full regression after completing trials. Reminder that it's important if you have regenerated the root key, to not loose this key in ordrer to be able to make a regression or a debugger opening.