How to start with STiRoT OEMuRoT on STM32H7S

Revision as of 18:21, 21 February 2024 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.

How to start with STiRoT OEMuRoT 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 STiRoT, using the STM32H7S discovery board.

  • Chapter1: describes an example of provisioning using password and a full regression using the STM32CubeFW script.
  • Chapter2: describes an example of provisioning using the root key and a certificate.

Based on this STM32CubeFW example, additional exercises are proposed (debugger opening, attach an IDE to make a step-by-step user application execution, modification of the user application and upload of the modified firmware) in the How to start with DA access on STM32H7RS, Debug Opening section article.
As explained later in this article, for the OEMuRoT application code the same application code as for the OEMiRoT has been reused (it explain why the previous article link is pointing to the OEMiRoT use case).


Introduction

Two examples are provided in the STM32Cube_FW:

  • An example with a single boot stage: STiRoT
  • An example with two boot stages: STiRoT - OEMuRoT

The two boot stages example is used in this "getting started".

Through this practical example you will learn:

  • What is STiRoT and OEMuRoT for STM32H7S and how to use the STM32CubeFW example which is provided.
  • How to configure the STiRoT 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.
  • 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)
Figure 1 STM32H7S DK MB1736
  • Required tools
    • STM32Cube_FW_H7RS_V1.0.0RC3 or later
    • STM32CubeProgrammer_rev0.0.7-H7RS-B01 or more recent (with trusted package creator (TPC) selected at installation).
    • IAR Embedded Workbench® rev 9.20.1 or later.
    • IAR Patch EWARMv9_STM32H7R-Sxx_V0.10.0 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"
Figure 2: STM32Cube_FW_H7RS
  • Open the env.bat file
  • 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.
  • Update the COM port to be aligned with your COM port number.
File:env.bat General setting.png
Figure 3 env.bat general setting
  • Use the Windows device manager to find out your COM port number, as shown in figure below
Figure 4 Find out the COM Port number
  • Check that the selected application path is correct: for the following tutorial the ROT/STiROT_Appli must be active.
File:env.bat STiRoT setting.png
Figure 5 env.bat_STiRoT_setting



1. Example with PASSWORD configuration

1.1. STiRoT-OEMuRoT and debug authentication configuration

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

1.1.1. Preliminary stage (Step 0)

  • The different steps to configure and use the STiRoT, OEMuRoT are based on a script provided in the STM32CubeFW: STM32H7S78-DK\ROT_Provisioning\STiROT_OEMuROT\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.
Figure 6 STiRoT OEMuRoT provisioning script


  • 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)
Figure 7 Script Step0: Provisioning with Password


1.1.1.1. iLoader

As explained in the introduction article, an immutable loader code example is provided in the STM32Cube_FW_H7RS (see STiRoT_STM32H7S_How_to_Intro article).
The role of this application is to handle the transfers between internal RAM and the external flash memory.
This application will be installed in the user flash and write protected.
  • Next action required by the script is to compile all the iLoader application example files.
File:iLoader provisioning script.png
Figure 8 Provisioning script, iLoader appli compilation
  • iLoader compilation using an IDE
The figure below shows where the provided iLoader application example is located.
Figure 9 iLoader application directory
  • The figure below shows the example using IAR
Figure 10 H7S iLoader compilation using IAR


  • Select "Project-STiROT_iLoader": Project-> Rebuild All => The compilation should be executed without reported warning or error.


1.1.1.2. OEMuRoT Boot

For the OEMuRoT boot application code (updatable Root of Trust boot), the OEMiRoT application is used.
Figure 11 OEMiRoT Boot
  • OEMiRoT (application used for the OEMuRoT) compilation using an IDE
The figure below shows where the provided application example for IAR is located.
Figure 12 OEMuRoT_Boot (OEMiRoT_Boot application used)
  • Open the project with IAR
  • Select "Project-STM32H7S78-DK_EOMiROT_Boot": Project-> Rebuild All => The compilation should be executed without reported warning or error.
  • As shown in the figure below, two files are created. Through the automatically launched Post-build command an encrypted and signed image is created.
Figure 13 OEMuRoT_Boot image (OEMiRoT_Boot appli used)

1.1.2. Configuration management (Step1)

The next operation performed automatically by the script is the update of "STiROT_Config.xml", "ob_flash_programming.bat" and "stm32h7s7xx_flash.icf" according to the STiROT_iLoader parameters. The mentioned "update_stirot_iloader_setup.log" file is located in the directory: STM32Cube_FW_H7RS_Vx.x.x\Projects\STM32H7S78-DK\ROT_Provisioning\STiROT

Figure 14 Script Step1: STiRoT configuration


1.1.2.1. STiRoT configuration

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

  • Open STM32TrustedPackageCreator.
  1. Select the shield
  2. Select OBkey tab
  3. Select the STiRoT_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). The image will be generated later on in this handson.
  4. Generate OBkey
  5. The confirmation window is displayed
Note:: The STiROT_Config.xml file is different for a single or two boot (OEMuRoT boot) stages configuration. In this case, take care to take the file located under ROT_Provisioning\STiROT_OEMuROT
Figure 15 H7S STiRoT OBkey generation
According to the path specified in the STiROT_Config.xml, a STiROT_Config.obk file is generated as shown in the figure below.
This file will be used by the script during the provisioning step.
Figure 16 STiRoT configuration generated obk file

1.1.2.2. Debug Authentication configuration

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

Figure 17 Debug Authentication configuration with password


  • Using STM32TrustedPackageCreator
  1. Select the shield
  2. Select OBkey tab DA_ConfigWithPassword.xml configuration file.
  3. A default password is provided.
  4. Generate OBkey
  5. The confirmation window is displayed
  6. The second confirmation window is displayed
Figure 18 Debug Authentication with password, OBkey gen


  • Warning: for a commercial product, it is important to define your own password. 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 password binary and a DA_Config.obk file are generated as shown in the figure below.
These files will be used by the script during the provisioning step.
Figure 19 DA configuration with password generated obk and bin files


  • The option bytes programming script and icf file are automatically updated (for details, see figure below for the related log files)
Figure 20 Security OB script and icf file update

1.1.2.3. OEMuRoT configuration

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

Figure 21 OEMuRoT configuration
  • Open STM32TrustedPackageCreator.
  1. Select the shield
  2. Select OBkey tab
  3. Select the OEMuROT_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). The image will be generated later on in this handson.
  4. Generate OBkey
  5. The confirmation window is displayed
Figure 22 OEMuRoT OBkey generation

According to the path specified in the OEMuROT_Config.xml, an OEMuROT_Config.obk file is generated as shown in the figure below. This file will be used by the script during the provisioning step.

Figure 23 Generated OEMuRoT configuration file

The STiRoT option byte file and the OEMuRoT imgage configuration file are automatically updated (for details, see figure below for the related log files)

Figure 24 STiRoT OEMuRoT script update

1.2. Image Generation of OEMuROT Application (Step2)

The Step 2 of the script is the generation of the OEMuRoT application firmware image.

Figure 25 OEMuRoT image generation
  • For the OEMuRoT application code example the same application is used as the OEMiRoT application provided example. (see figure below)
Figure 26 OEMuRoT appli (use of OEMiRoT appli example)
  • Open the OEMiRoT application example with your IDE (in this example with IAR)
  • Select the STiROT_Appli -> Project -> Rebuild All
  • The compiled binary file is created and through the postbuild command the encrypted and signed image is automatically generated.
Figure 27 OEMiRoT signed and encrypted image

1.3. Board programming

In the next steps the script will automatically perform

  • The provisioning of the Option Byte
  • Flash the previously generated images in the download areas (areas defined in the .xml configuration files)
  • Perform the needed reset to install the code
  • Set the final state of the product
Figure 28 STiRoT-OEMuRoT, DK board programming
  • If all the steps have been executed successfully, a confirmation is displayed as shown in the figure above.

1.4. 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
Figure 23 Teraterm configuration
  • Press the reset button (black button of the discovery board)
  • The STiRoT application is executed (figure below)


Figure 29 STiRoT-OEMuRoT execution
  • In the figure above you can see the jump into the OEMuRoT application, that is then executed.
  • Since the device is in "CLOSED" the menu calling the bootloader makes not sense in this case.
But it is usefull during developement phase where the device is kep in "OPEN" state.
For a CLOSED device a debug opening is needed and an image download procedure explained in chapter zzzz

Note: reminder: the OEMiRoT provided application code example has been used for the OEMuRoT.

1.5. Full regression

  • There are two ways to perform a regression
    • Using the graphic interface of the STM32CubeProgrammer. It will be shown in the second part of this handson.
    • Using the regression script provided in the STM32CubeFW, shown in the example below.
  • Launch the script as shown in the figure below
Figure 30 Security Regression Script
  • 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.
Figure 31 Security Full Regression Password


2. Example with CERTIFICATE configuration

2.1. STiRoT-OEMuRoT and debug authentication configuration

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

2.1.1. Preliminary stage (Step 0)

  • The different steps to configure and use the STiRoT, OEMuRoT are based on a script provided in the STM32CubeFW: STM32H7S78-DK\ROT_Provisioning\STiROT_OEMuROT\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.
Figure 32 STiRoT OEMuRoT provisioning script
  • 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)
File:Provisioning preliminary stage.png
Figure 33 Script Step0: Provisioning


2.1.1.1. iLoader

As explained in the introduction article, an immutable loader code example is provided in the STM32Cube_FW_H7RS (see STiRoT_STM32H7S_How_to_Intro article).
The role of this application is to handle the transfers between internal RAM and the external flash memory.
This application will be installed in the user flash and write protected.
  • If you have done the handson in chapter 1 (configuration with password), you have already compiled and used this application that is the same for all STiRoT CubeFW examples.
  • Compile all the iLoader application example files in case not already done during previous handson.
  • Next action required by the script is to compile all the iLoader application example files.
File:iLoader provisioning script.png
Figure 34 Provisioning script, iLoader appli compilation
  • iLoader compilation using an IDE
The figure below shows where the provided iLoader application example is located.
Figure 35 iLoader application directory
  • The figure below shows the example using IAR
Figure 36 H7S iLoader compilation using IAR


  • Select "Project-STiROT_iLoader": Project-> Rebuild All => The compilation should be executed without reported warning or error.


2.1.1.2. OEMuRoT Boot

For the OEMuRoT boot application code (updatable Root of Trust boot), the OEMiRoT application is used.
Figure 37 OEMiRoT Boot
  • If you have done the handson in chapter 1 (configuration with password), you have already generated the encrypted and signed image. This image is still valid if the encryption and signature keys have not been regenerated.
  • OEMiRoT (application used for the OEMuRoT) compilation using an IDE, in case the image has not yet been generated or the keys have been regenerated.
The figure below shows where the provided application example for IAR is located.
Figure 38 OEMuRoT_Boot (OEMiRoT_Boot application used)
  • Open the project with IAR
  • Select "Project-STM32H7S78-DK_EOMiROT_Boot": Project-> Rebuild All => The compilation should be executed without reported warning or error.
  • As shown in the figure below, two files are created. Through the automatically launched Post-build command an encrypted and signed image is created.
Figure 39 OEMuRoT_Boot image (OEMiRoT_Boot appli used)


2.1.2. Configuration Management (Step1)

The next operation performed automatically by the script is the update of "STiROT_Config.xml", "ob_flash_programming.bat" and "stm32h7s7xx_flash.icf" according to the STiROT_iLoader parameters.
The mentioned "update_stirot_iloader_setup.log" file is located in the directory: STM32Cube_FW_H7RS_Vx.x.x\Projects\STM32H7S78-DK\ROT_Provisioning\STiROT

Figure 40 Script Step1: STiRoT configuration

2.1.2.1. STiRoT configuration

The next step indicated by the script is to open the STiROT_Config.xml file, update to the wanted configuration and to generate the Option Byte file (obk).

  • Open STM32TrustedPackageCreator.
  1. Select the shield
  2. Select OBkey tab
  3. Select the STiRoT_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). The image will be generated later on in this handson.
  4. Generate OBkey
  5. The confirmation window is displayed
Note:: The STiROT_Config.xml file is different for a single or two boot (OEMuRoT boot) stages configuration. In this case, take care to take the file located under ROT_Provisioning\STiROT_OEMuROT
Figure 41 H7S STiRoT OBkey generation
According to the path specified in the STiROT_Config.xml, a STiROT_Config.obk file is generated as shown in the figure below.
This file will be used by the script during the provisioning step.
Figure 42 STiRoT configuration generated obk file


2.1.2.2. Debug Authentication configuration

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

  • If you have done the handson in chapter 1 (configuration with password), you have already generated the Option Byte configuration file (obk) that is still valid. Unless the Debug Authentication root key has been changed or you want to change the configuration.
Figure 43 Debug Authentication configuration


  • Using STM32TrustedPackageCreator
  1. Select the shield
  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
Figure 44 Debug Authentication with certificate, OBkey generation


  • 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.
Figure 45 DA configuration generated obk file
  • The option bytes programming script and icf file are automatically updated (for details, see figure below for the related log files)
Figure 46 Security OB script and icf file update

2.1.2.3. OEMuRoT configuration

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

  • If you have done the handson in chapter 1 (configuration with password), you have already generated the Option Byte configuration file (obk) that is still valid. Unless you have regenerated the encryption and authentication keys or want to do it.
Figure 47 OEMuRoT configuration
  • Open STM32TrustedPackageCreator.
  1. Select the shield
  2. Select OBkey tab
  3. Select the OEMuROT_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). The image will be generated later on in this handson.
  4. Generate OBkey
  5. The confirmation window is displayed
Figure 48 OEMuRoT OBkey generation

According to the path specified in the OEMuROT_Config.xml, an OEMuROT_Config.obk file is generated as shown in the figure below. This file will be used by the script during the provisioning step.

Figure 49 Generated OEMuRoT configuration file

The STiRoT option byte file and the OEMuRoT imgage configuration file are automatically updated (for details, see figure below for the related log files)

Figure 50 STiRoT OEMuRoT script update

2.2. Image Generation of OEMuROT Application (Step2)

The Step 2 of the script is the generation of the OEMuRoT application firmware image.

  • If you have done the handson in chapter 1 (configuration with password), you have already generated the OEMuRoT application image that is still valid. Unless you have regenerated the encryption and authentication keys during the OEMuRoT configuration in previous section.
Figure 51 OEMuRoT image generation
  • For the OEMuRoT application code example the same application is used as the OEMiRoT application provided example. (see figure below)
Figure 52 OEMuRoT appli (use of OEMiRoT appli example)
  • Open the OEMiRoT application example with your IDE (in this example with IAR)
  • Select the STiROT_Appli -> Project -> Rebuild All
  • The compiled binary file is created and through the postbuild command the encrypted and signed image is automatically generated.
Figure 53 OEMiRoT signed and encrypted image

2.3. Board programming

In the next steps the script will automatically perform

  • The provisioning of the Option Byte
  • Flash the previously generated images in the download areas (areas defined in the .xml configuration files)
  • Perform the needed reset to install the code
  • Set the final state of the product
Figure 54 STiRoT-OEMuRoT, DK board programming
  • If all the steps have been executed successfully, a confirmation is displayed as shown in the figure above.

2.4. 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
Figure 55 Teraterm configuration
  • Press the reset button (black button of the discovery board)
  • The STiRoT application is executed (figure below)


Figure 56 STiRoT-OEMuRoT execution
  • In the figure above you can see the jump into the OEMuRoT application, that is then executed.
  • Since the device is in "CLOSED" state, the menu calling the bootloader makes not sense in this case.
But it is usefull during development phase where the device is kept in "OPEN" state.
For a CLOSED device a debug opening is needed and an image download procedure is needed (see next chapter)

Note: reminder: the OEMiRoT provided application code example has been used for the OEMuRoT.

  • Close Teraterm

2.5. 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 article:
  • If no further trials are done, it is advised to make a regression to retrieve an empty board.
Retrieved from "https://wiki.st.com/stm32mcu/index.php?title=Security:How_to_start_with_STiRoT_OEMuRoT_on_STM32H7S&oldid=50002"