How to start with STM32CubeMX OEMiRoT Boot path on STM32H573

Target description

This article explains how to proceed step by step to generate a boot path using STM32CubeMx.
The example below shows how to configure and provision a boot path for an OEMiROT with a secure and non-secure user application initial code generation.
Read the Secure Boot STM32H5 How to Introduction article before starting the practical example described below.

More technical details you might need to understand this getting started are available in the following articles:

• Introduction article: Introduction to Secure boot and Secure firmware update
  
• Specific STM32H5 boot path article: Secure Boot for STM32H5
• OEMiROT article OEMiRoT-OEMuRoT for STM32H5

The How to start described in this article uses the boot path number 1 of the figure below.

Prerequisites

To execute the example described below, you need:

• The Discovery board: STM32H573I-DK

• The following tools:
  • STM32CubeMX_6.9.0 or later (refer to STM32CubeMX ST web page)
  • IAR Embedded Workbench rev 9.20.1 or later
  • STM32CubeProgrammer rev 2.13.0

Note:

• STM32 Trusted Package Creator (TPC) is automatically installed during the STM32CubeMX installation. A TPC version is dedicated to STM32CubeMX and installed in the STM32CubeMX/utilities folder.
• The latest STM32Cube_FW revision is installed through STM32CubeMX (refer to appendix).
• If needed, set the windows environment variable (refer to appendix). It is mandatory in case the H5 does not appear in the “Access to MCU Selector” of STM32CubeMx.

1. OEMiROT_Boot firmware compilation

Before starting the STM32CubeMX project configuration, it is advised to compile the project OEMiROT_Boot. OEMiROT_Boot is executed in HDPL1 in the user flash memory and performs authenticity and integrity checks of the user application.
It also configures the number of user applications and images. This project is located in STM32CubeH5 firmware: C:\STM32Cube_FW_H5_V1.1.0\Projects\STM32H573I-DK\Applications\ROT\OEMiROT_Boot

-

Open the OEMiROT_Boot project with your preferred IDE (EWARM/MDK-ARM or STM32CubeIDE) and rebuild all files.

For more information, refer to OEMiRoT STM32H5 How to Introduction.

2. Setting the STM32CubeMX project

Launch STM32CubeMX.

• 1) Click on Access to MCU selector (easier for this example to enable only the needed GPIOs, so it is advised to use the MCU selector instead of the board selector).
• 2) Select the STM32H5 series and device used in STM32H5-DK.
• 3) Click on Start project.
• 4) Enable the TrustZone, as shown in Figure 1. For the OEMiROT boot path, the TZ must be enabled.

Set the STM32CubeMX project:

• 1) Type the name of the project (the related folder is created)
• 2) Chose the folder for this project (avoid long path)
• 3) Check that Secure Project and Non Secure Project are ticked (should be the setting by default)
• 4) Select the Toolchain. In this example, EWARN is used.

• 5) File -> Save Project -> the project folder (if not already existing) and the STM32H5_OEMiROT_SLed_NSLed.ioc file is created

OEMiRoT_Boot project location

If you want to use another repository for the STM32CubeH5 MCU Package than the default STM32CubeMX folder, you can define it in
Project Manager--> Project Tab-->MCU and Firmware Package:

• Uncheck Use Default Firmware Location.
• Define the path you want to use in Firmware Relative Path.

3. GPIO configuration

For this proposed example, three GPIOs must be configured for the Discovery board:

• PF4 for the blue LED (LD4 on the Discovery board) used in the secure user application code
• PC13 for the blue user button used in the secure user application code
• PI9 for the green LED (LD1 on the Discovery board) used in the non-secure user application code

In STM32CubeMX, select the Pinout & Configuration window.

To configure the GPIO for the blue LED, proceed as follows:

• Click left on PF4: select GPIO_Output -> a push-pull output needed to drive a LED is configured
• Click right on PF4: and select Cortex-M33 secure. This GPIO is then assigned to the secure user application code

To configure the user blue button, proceed as follows:

• Click left on PC13: select GPIO_Input
• Click right on PC13: and select Cortex-M33 secure. This GPIO is then assigned to the secure user application code

To configure the GPIO for the green LED, proceed as follows:

• Click left on PI9: select GPIO_Output -> a push-pull output needed to drive a LED is configured
• Click right on PI9: and select Cortex-M33 non-secure. This GPIO is then assigned to the non-secure user application code

• Select GPIO: The summary of the settings is displayed as shown in the figure below.

4. Configure the OEMiROT boot path

To configure the boot path number 1 of Figure 1, proceed as follows:

• 1) Click on "Boot Path and Debug Authentication".
• 2) Click on "Select".
• 3) Select the OEMiRoT. The TZ activation is already chosen. This selection defines the UBE option byte (but you do not need to take care of the setting of this option byte).
• 4) Click on "Next".
• 5) Select Secure Application (since for this example there is no uROT, so no second boot stage).
• 6) Click Finish.

Note: Depending on the STM32CubeMX version, the Debug Authentication Configure button cannot be selected before completing the OEMiROT boot path configuration.

OEMiROT_Boot firmware

You can view the OEMiROT_Boot firmware path in Boot path and Linker tabs.

This firmware is located by default in the STM32CubeH5 MCU Package installed through STM32CubeMX.
If necessary, the OEMiRoT_Boot might be compiled by the user during the provisioning.
If you want to change the OEMiRoT_Boot firmware location please refer to paragraph 2 Setting the STM32CubeMX project, then OEMiRoT_Boot project location. In fact if this firmware is not located closed to root of C:/ errors can occur during compilation.

OEMiROT configuration

In the Project Manager window, select Edit Config, as shown in the figure below.

It automatically opens STM32Trusted Package Creator (TPC).
Then, the following window is displayed.

• Generate the OBKey file:

Notes:

• The figure above, shows the path of the OEMiROT_Config.xml file is located. This file contains all the configuration parameters for the OEMiROT.
• The configuration of the OEMiRoT is made in the OEMiROT_Boot firmware. During the provisioning, the download area stores the encrypted user application, which is decrypted by the OEMiROT and installed in the execution area (refer to the OEMiRoT STM32H5 How to Introduction article).
• For a commercial product, it's important to regenerate the authentication keys and the encryption key.

As mentioned above, for this example, you do not need to make any other updates to the default configuration.

Select H5-Image Gen1, as shown in the figure below. This window needs no modification, just some explanations:

• The OEMiROT_S_Code_Image.xml file contains the settings needed to generate the images.
• Two paths are indicated for binary files:
  • The code compilation using the IDE creates a binary file containing the compiled secure application.
  • The IDE also performs a postbuild command to generate from this binary input files a single encrypted and signed binary image.

Note: The above-mentioned paths are updated by STM32CubeMx and must not be modified.

Select H5-Image Gen2, and you have the same information for the non-secure image generation with the file OEMiROT_NS_Code_Image.xml.

• Close STM32 Trusted Package Creator.

5. Debug Authentication configuration

For more details, refer to the Debug Authentication for STM32H5 article.

STM32CubeFW provides a default configuration (fully functional) and related OBKey files.
To customize the Debug Authentication, proceed as follows:

• In STM32CubeMX -> Project Manager -> Select: Debug Authentication Configure.
  

• The STM32Trusted Package Creator is launched (TPC installed together with STM32CubeProgrammer) and the DA_Config.xml file is automatically open.
  
• The "key_1_root" key is needed to reopen the device or to perform a regression. To protect your own developed application, this key must be regenerated. If regenerated, it is important not to lose this new key.
• Do not regenerate the key for this example.
• The permission mask is set to allow all possible regressions and debug openings in the secure and non-secure user application code.
  

Refer to Debug Authentication STM32H5 How to Introduction article for more details.
This permission mask called the SOC mask, is stored in the device during provisioning.
The root key owner has the defined privileges to perform regression or open the debugger according to set permissions.

• Generate the OBKey file used during the provisioning process. Click:

• Close STM32Trusted Package Creator.

6. Initial Code Generation and modification

Select Project Manager in STM32CubeMX.

• Ensure Sign Binaries is selected -> At each user application code compilation using the IDE an encrypted and signed binary is created containing both secure and non-secure user application (compilation -> postbuild command).
• Note that start and end addresses are indicated for the secure and non-secure according to the OEMiROT configuration.

• Click Generate Code.
  • You can have the following warning message. Click yes to generate the code.
  • Or if you want to enable the Instruction Cache, through the Pinout & Configuration Tab select ICache located just below the GPIO configuration.

• Open the generated user application.

Open the secure user application code.

• In main.c file, comment out NonSecure_Init() for the jump into the non-secure user application code (replaced with the code below).
• Insert the following code as shown in the figure below.
  

‎

                 HAL_GPIO_TogglePin(GPIOF, GPIO_PIN_4);
                 HAL_Delay(500);
                 if (HAL_GPIO_ReadPin(GPIOC, GPIO_PIN_13) == 0x1)
                  {
                   NonSecure_Init(); 
                  }
‎

This code makes the blue LED blink with the chosen Delay, showing the execution of the secure user application.
If the user blue button is pushed, the jump in the non-secure code is done through the Non-Secure_Init.

• Compile the code using the IDE (Project -> Rebuild all).
  
• Note: The secure code must be compiled first (before the non-secure code).

Open the non-secure user application.

• In main.c file, insert the following code as shown in the figure below.
  

‎

    HAL_GPIO_TogglePin(GPIOI, GPIO_PIN_9);
    HAL_Delay(800);
‎

This code makes the green LED blink with the chosen Delay, showing the execution of the non-secure user application.

• Compile the code using the IDE (Project -> Rebuild all).
  

Two binaries are created as shown in the figure below.

• The binary obtained after the signature and encryption of the binary of the secure application
• The binary obtained after the signature and encryption of the binary of the non-secure application

Both binaries are generated through the automatically called postbuild command.

7. Device Provisioning

For the device provisioning, the OBKey files generated previously configure the device OEMiROT and the Debug Authentication according to the permission mask.
The encrypted and signed binary is uploaded in the download area defined during the OEMiROT_Boot configuration.
The OEMiROT_Boot firmware verifies the authenticity, decrypts, and installs the secure and non-secure user applications in the execution area defined during the OEMiROT_Boot configuration.

For the provisioning, the STM32CubeProgrammer Command Line (CLI) is called automatically by the provisioning script.
It is important that the path to the STM32CubeProgrammer is correct in the env.bat file. Check and update as shown in the figure below.
! Do not modify the path to the STM32TrustedPackageCreator included in STM32CubeMX.

The provisioning of the device is performed using the provided provisioning script.

• Connect your board with the USB cable (USB ST-LINK connector).
• Click twice on the provisioning.bat shown in the figure below.
• The provisioning Step 1 is the configuration.
  • The OEMiROT configuration setting was done previously (generation of the related OEMiRoT_Config.obk file).
  • The DA configuration setting was done previously (generation of the related DA_Config.obk file).
• The provisioning Step 2 is the image generation.
  • If not done at the beginning: OEMiRoT_Boot firmware compilation, you must open the OEMiROT_Boot project with the IDE you prefer (EWARM/MDK-ARM or STM32CubeIDE) and rebuild all files.
  • The image generation of the user application code was done previously during the compilation and the postbuild command.
  • The image generation is not applicable for this example -> type any key.
• The provisioning Step 3 is the board provisioning.
  • Before typing any key, check the indicated boot switch position.
  • The STM32H5 device provisioning is executed, the configuration is stored, and the user application codes are installed.

• Note: For Linux and Mac operating systems, the end users may have to change manually the attribute of .sh scripts to executable.

• The last Step is the product state setting. In this example, the device is set in CLOSED.
• After the message that the board is correctly configured, the script can be closed.

Refer to Security: Introduction_to_Silicon_device_life_cycle and Security: Debug_Authentication articles for detail explanations.

8. Code execution

• Press the black reset button. The blue LED blinks, showing that the secure user application is executed.
• Press the blue button. The green LED blinks, showing that the jump to the non-secure application is successful and that the non-secure code is executed.

9. STM32CubeProgrammer Discovery command

• Start STM32CubeProgrammer and try to connect.
• The error message below is displayed because the device is set in the CLOSED state, and the debugger cannot be connected even to view the non-secure user application code.
• To reopen the debugger, a Debug Authentication is needed, and only the root key owner might proceed.

The product state can be checked using the Discovery command (refer to figure below):

• 1) In STM32CubeProgrammer, click on the shield icon
• 2) Select Debug Authentication
• 3) Click on Discover. The lifecycle CLOSED is displayed.

An example of how to reopen the debugger, view the code, and attach an IDE to perform a step-by-step application execution is shown in chapter 3 of the article How to start with OEMiRoT on STM32H573 and 563–TrustZone enabled

10. Regression

The regression removes the user applications and protections.
After completing a hands-on, if your board is not in the OPEN state, it is advised to perform a regression, mainly if you regenerate the root key.

• Click twice to start the regression script shown in the figure below.
• The regression is performed automatically. The Debug Authentication is done using the root and using the permission defined during the OEMiROT configuration.

• Note: For Linux and Mac operating systems, the end users may have to change manually the attribute of .sh scripts to executable.

• You can connect STM32CubeProgrammer and check that the debugger is again open and that the flash memory is fully erased.

11. Appendix

11.1. STM32CubeFW installation

STM32CubeFW must be installed through STM32CubeMX.

• Step 1: The repository folder must be defined:
  • In STM32CubeMx: Help menu -> Updater Settings
  • Browse the repository chosen for STM32CubeFW

• Step 2: STM32CubeFW installation
  • In STM32CubeMX: Select Install/Remove.
  • In the description frame: Select STM32H5.
  • Select the CubeFW Package to install.
  • In case you already have the STM32CubeFW zip file. Dragging and dropping this file in the description window installs the firmware.

Note: only official STM32CubeFW release can be installed by STM32CubeMX.