How to start with STiRoT on STM32H7S

How to start with STiRoT 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.


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 single boot stage example is used in this "getting started".

Through this practical example you will learn:

  • What is STiRoT 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.1.0 or later
    • STM32CubeProgrammer_rev2.16.0 or more recent (with trusted package creator (TPC) selected at installation).
    • IAR Embedded Workbench® rev 9.60 or later.
    • or IAR Embedded Workbench® rev 9.20.1 or later + IAR Patch EWARMv9_STM32H7R-Sxx_Vx.x.x
      • IAR patch is available in the STM32CubeFW: STM32Cube_FW_H7RS_Vx.x.x\Utilities\PC_Software
    • 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 from 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.
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.
Figure 5 env.bat_STiRoT_setting


1. Example with PASSWORD configuration

1.1. STiRoT and debug authentication configuration

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

1.1.1. Preliminary stage

  • The different steps to configure and use the STiRoT are based on a script provided in the 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.
The figure below shows where the script is located in the STM32CubeFW.
Figure 6 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
  • 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.
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.2. Configuration Management

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 11 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 STiROT_Config.obk (OBKey) 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
Figure 12 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 13 STiRoT configuration generated OBKey file
1.1.2.2. Debug Authentication configuration

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

Figure 14 Debug Authentication configuration with password


  • Using STM32TrustedPackageCreator
  1. Select the shield
  2. Select OBkey tab
  3. Select the DA_ConfigWithPassword.xml configuration file. All the default settings for this hands-on are already filled-in and a default password is provided.
  4. Generate OBkey
  5. The confirmation window is displayed
Figure 15 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 16 DA configuration with password generated OBKey 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 17 Security OB script and icf file update

1.2. Image Generation of STiRoT Application

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

Figure 18 Script Step2: Application code image generation
  • The STiRoT application exemple is available in the ROT directory.
Figure 19 STiRoT Appli directory
  • Open the STiRoT example with your IDE, the figure below show the example using IAR.
Figure 20 Security H7 STiRoT appli compilation
  • 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 21 Security STiRoT Appli Image Creation

1.3. 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
Figure 22 Script Step3: Provisioning and STiRoT Application Image flashing
  • If all the steps have been executed successfully, a confirmation is displayed as shown in the figure above.

1.4. STiRoT 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 24 STiRoT appli execution

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 25 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 26 Security Full Regression Password


2. Example with CERTIFICATE configuration

2.1. STiRoT and debug authentication configuration

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

2.1.1. 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.
Figure 27 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)
Figure 28 Script Step0: Provisioning


  • iLoader
As explained in the introduction article, an immutable loader code example is provided in the STM32Cube_FW_H7RS.
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.
Figure 29 Provisioning script, iLoader appli compilation
  • iLoader compilation using an IDE
The figure below shows where the provided iLoader application example is located.
Figure 30 iLoader application directory
  • The figure below shows the example using IAR
Figure 31 H7S iLoader compilation using IAR


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

2.1.2. Configuration Management

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 32 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 STiROT_Config.obk (OBKey) 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
Figure 33 H7S STiRoT OBkey generation


According to the path specified in the STiROT_Config.xml, a STiROT_Config.obk (OBKey) file is generated as shown in the figure below.
This file will be used by the script during the provisioning step.
Figure 34 STiRoT configuration generated OBKey file
2.1.2.2. Debug Authentication configuration

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

Figure 35 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 36 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 (OBKey) file is generated as shown in the figure below.
This file will be used by the script during the provisioning step.
Figure 37 DA configuration generated OBKey file
  • The option bytes programming script and icf file are automatically updated (for details, see figure below for the related log files)
Figure 38 Security OB script and icf file update

2.2. Image Generation of STiRoT Application

The Step 2 of the script is the generation of the application firmware image.
You can reuse the previously generated image: if you have already generated the image during the previous example (configuration with Password) and that the keys (authentication and encryption) have not been regenerated.
In this case, go to next section.

Figure 39 Script Step2: Application code image generation
  • The STiRoT application exemple is available in the ROT directory.
Figure 40 STiRoT Appli directory
  • Open the STiRoT example with your IDE, the figure below show the example using IAR.
Figure 41 Security H7 STiRoT appli compilation
  • 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 42 Security STiRoT Appli Image Creation

2.3. 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
Figure 43 Script Step3: Provisioning and STiRoT Application Image flashing
  • If all the steps have been executed successfully, a confirmation is displayed as shown in the figure above.

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


Figure 45 STiRoT appli execution
  • 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 chapters.
  • If you decide to not perform the tutorial proposed below, it is advised to make a regression to retrieve an empty board.

3. Debug Opening (intrusive debug)

Since the device is in closed state, the debugger is no open and you have an error message if you try to connect STM32CubeProgrammer.

  • If the device has been provisioned with Password Debug Authentication, only a full regression is possible and a debug opening is not allowed.
  • If the device has been provisioned with Root key/Certificate Debug Authentication, the owner of the key and certificate can open the debugger.

3.1. Debug Opening procedure

  • Open STM32CubeProgrammer
  • Select the shield
  • 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 2 Intrusive Debug" (the STiRoT application is execute in HDPL2, see STiRoT_for_STM32H7RS article)
  • Click Execute -> A Debug Authentication Success message is displayed.


Figure 46 Debugger Opening
  • The debugger is open and the content of the flash can be readout, as shown in figure below
Figure 47 Flash readout , debugger reopened

The debugger will stay open until the next power on reset.

  • Disconnect STM32CubeProgrammer

3.2. IAR connection, step by step user application execution

  • Launch IAR
  • Select Project -> Attach to Running Target (see figure below) (the STM32CubeProgrammer must be disconnected first)


Figure 48 Debugger reopened, IAR connection

Some trials you can do are indicated in the figure below

  1. Set a break point
  2. Click on "break"
  3. Click on "Reset"
  4. Try out some step by step executions
  5. Click on "Go" -> the execution will stop at the break point.
Figure 49 User application execution step by step using IAR
  • Make a modification of the user application code, for instance as proposed in the figure below
  • Project -> Rebuild All
  • The new application image created through the postbuild command, will be used in the firmware update example described in next chapter.
Figure 50 User application modifications


4. Firmware Update for a Closed device

The following description shows how to perform a Firmware Update.
At the date of writing this article, the GUI graphical interface is not yet functional to perform a firmware update.
The following example shows how to proceed using the debug authentication script and updating the firmware through command line.

4.1. Debug Authentification

  • In the previous section the encrypted and signed image has been created for the modified firmware. If it's not the case, open the STiRoT_Appli, make some modifications and rebuild all the file -> image creation through postbuild command.
  • If applicable: close IAR or Disconnect STM32CubeProgrammer
  • Unplug/ replug the Discovery board USB cable to make a power on reset. If the debugger was open, it will be closed again.
  • Launch the dbg_auth.bat script
Figure 51 Debug authentication script
  • 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


Figure 52 Debug authentication script execution

4.2. 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\STiROT_Appli\Binary\appli_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 STiRoT configuration defined previously.
  • At next reset the STiRoT will detect that a new firmware needs to be installed and perform automatically the installation (this is transparent for a user).


Figure 53 Firmware upgrade example, command line execution

4.3. 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 STiRoT application is executed as shown in the figure below
Figure 54 New STiRoT application execution

4.4. 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
  • 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.
Figure 55 Full regression using STM32CubeProgrammer graphic interface
  • 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.


Retrieved from "https://wiki.stmicroelectronics.cn/stm32mcu/index.php?title=Security:How_to_start_with_STiRoT_on_STM32H7S&oldid=60671"