How to start with OEMiRoT on STM32H7S

How to start with OEMiRoT on STM32H7S

Literature

• Wiki pages:
  • OEMiRoT STM32H7S How to intro article.
  • OEMiRoT for STM32H7S]] article.

• • Debug Authentication for STM32H7S article.
• 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

• 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

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.

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: CERTIFICATE (for explanation about certificate and password refer to intro article)

File:Provisioning preliminary stage.png

Figure 6 Provisioning Step 0

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.

1. Select the shield
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

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.

1.2.1. Debug Authentication configuration

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

Figure 13 Debug Authentication configuration with password

Figure 13 Debug Authentication configuration

• 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 14 Debug Authentication with password, OBkey gen

Figure 14 Debug Authentication with certificate, OBkey generation

• 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 15 DA configuration with password generated obk and bin files

Figure 15 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 16 Security OB script and icf file update