How to start with OEMiRoT on STM32H533

How to start with OEMiRoT on STM32H53385min

Target description

Through this practical example, the user can learn how to perform the following operations:

• Run the OEMiRoT example of the STM32CubeFW:
  • Provisioning preparation.
  • Code and data compilation and encrypted image generation.
  • Perform the provisioning and install the firmware and data files.
  • Execute the installed firmware.
  • Perform a full regression.
• Debug authentication:
  • Create a certificate chain.
  • Perform a regression using the LEAF certificate of the certificate chain.
  • Debug opening (secure and nonsecure) using root certificate.
  • Attach CubeProgrammer and attach an IDE once the debugger is open.
  • Read secure and nonsecure firmware.
  • Perform a partial regression and download new code and data nonsecure.

This OEMiRoT step by step tutorial is divided in two main parts:

• Provisioning:
  • Configuration
  • Device provisioning
  • Application code execution
  • Full regression

• Debug authentication:
  • Certificate chain
  • Debug opening (secure and nonsecure)
  • Regression (partial and full)

Prerequisites

• Knowledge of STM32CubeProgrammer
• Knowledge of JTAG / SWD interface
  

Hardware

• Nucleo board STM32H533RE

Required tools

• STM32Cube_FW_H5_V1.2.0 or upper
• STM32CubeProgrammer software programming tool for STM32 (v2.13.0 min)
  • Including STM32TrustedPackageCreator

Information

TPC installed together with CubeProgrammer in bin folder located in default STM32CubeProgrammer path: C:\Program Files\STMicroelectronics\STM32Cube\STM32CubeProgrammer\bin. You can pin this tool to the task bar to simplify the OEMiRoT getting started process:

• IAR Embedded Workbench® rev 9.20.1
• Tera Term or equivalent UART terminal emulator

Literature

• UM2237 STM32CubeProgrammer software description
• UM2238 STM32TrustedPackageCreator tool software description
• AN5054 Secure programming using STM32CubeProgrammer
• AN2606 STM32 microcontroller system memory boot mode

Environment setup

Before starting, the first step is to prepare the environment to be able to go through the OEMiRoT process.

• Download the STM32CubeH5 package and install it.

Warning

Place STM32CubeFW_H5 Cube firmware close to the C: root to avoid a long Windows® path.

An STM32H573I-DK directory is included in the projects directory:

Warning

In case the STM32CubeProgrammer has not been installed in the default folder, the customized installation paths need to be updated in the following script: Projects\NUCLEO-H533RE\ROT_Provisioning\env.bat :: ============================================================================== :: General :: ============================================================================== :: Configure tools installation path set stm32programmercli="C:\Program Files\STMicroelectronics\STM32Cube\STM32CubeProgrammer\bin\STM32_Programmer_CLI.exe" set stm32tpccli="C:\Program Files\STMicroelectronics\STM32Cube\STM32CubeProgrammer\bin\STM32TrustedPackageCreator_CLI.exe"

1. Introduction

This article shows an OEMiRoT example use case for STM32H533 devices with TrustZone® enabled.

All the article is based on the STM32CubeH5 package OEMiRoT example for STM32H533 MCUs.

2. OEMiRoT step by step: Provisioning / Code execution / Regression

2.1. Step 1 : OEMiRoT and debug authentication configuration

2.1.1. OEMiRoT configuration

At this step, the file (OEMiRoT_Config.obk) used to configure the OEMiRoT is generated. A default file is provided in the example that can be used without modification for a first trial in this path:
Projects\NUCLEO-H533RE\ROT_Provisioning\OEMiROT\Binary

STM32TrustedPackageCreator is used to setup this file using the OEMiRoT_Config.xml as an input located in the config folder:

Projects\NUCLEO-H533RE\ROT_Provisioning\OEMiROT\Config

At this step, the following keys pair is generated:

• ECDSA-256 encryption key
• ECDSA-256 authentication secure key
• ECDSA-256 authentication nonsecure key

To generate a customized configuration file, proceed as follows:

• Open STM32TrustedPackageCreator and select H5.
• Open the OBkey tab.
• Select the OEMiROT_Config.xml file in folder ROT_Provisioning\OEMiROT\Config.
• Update the parameters if needed.
• The default keys can be regenerated.
• For a commercial product the keys need to be regenerated.

• Generate the file:
  

The OEMiROT_Config.obk file is generated. The modified parameters are saved in Binary\OEMiROT_Config.obk.

2.1.2. Debug authentication configuration

At this step, the file DA_Config.obk is generated in the DA\Binary folder. This file is used to configure the conditions to reopen a protected device and the debugger. A default file is provided in the STM32CubeFW_H5 example that can be used without modification for a first trial.

STM32TrustedPackageCreator will be used to setup this file using the DA_Config.xml as an input located in the DA\Config path.

The following parameters can be defined at this step:

• Hash (SHA256) of the root public key
• Permissions list (full regression, partial regression, debug opening (HDPL1 S/NS, HDPL2 S/NS, HDPL3)

Two files are included in the DA directory:

• DA_Config.xml: configuration based on certificates for H5 crypto parts (this file is used for this tutorial).
• DA_ConfigWithPassword: configuration based on password: when TrustZone® is disabled.

Warning

The device can be blocked if the password provisioning is done during this tutorial since TrustZone® is enabled.

To generate a customized configuration file, proceed as follows:

• Open STM32TrustedPackageCreator and select H5.
• Open the OBkey tab.
• Select the DA_Config.xml file.
• Update the parameters if needed. For a first trial, we recommend keeping the default key, because in the regression step we use the default certificate that is linked to the default DA keys.

Warning

If a customized DA key is generated here, make sure the customized root key file is well saved/kept because it is used later on for debug reopening and regression. If this key is lost, the device might be locked forever.

• For a commercial product it's mandatory to regenerate the Debug Authentication key.

• Generate the file:
  

2.2. Step 2: Code and data image generation

2.2.1. STM32CubeFW provided code compilation

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

• OEMiROT_Boot corresponds to the secure boot.

It performs authenticity and integrity checks of the project firmware and data images.

• OEMiROT_Appli_TrustZone is an example of a secure and nonsecure application managed by OEMiROT.

OEMiROT_Boot project configuration

Number of code images and data images is defined in the flash_layout.h file in the Projects\NUCLEO-H533RE\Applications\ROT\OEMiROT_Boot\Inc folder.

In this example we want to use:

• 1 secure code image
• 1 nonsecure code image

Update the file flash_layout.h as shown in the figure below:

Information

During the OEMiROT_Boot execution, if the number of images is wrong, the bootloader is launched to load new code and/or data images.

OEMiROT_Boot project compilation

• Open the Project.eww located in the EWARM directory: Projects\NUCLEO-H533RE\Applications\ROT\OEMiROT_Boot\EWARM
• 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 (do not upload the code, only perform a compilation)

The following binary is created: Projects\NUCLEO-H533RE\Applications\ROT\OEMiROT_Boot\Binary\OEMiROT_Boot.bin

OEMiROT_Appli_TrustZone project compilation –secure project

• Open the Project.eww located in the EWARM directory:

Projects\NUCLEO-H533RE\Templates\ROT\OEMiROT_Appli_TrustZone\EWARM

• Select the secure project:

• Open Project -> Option -> General Options

The device and CPU core should be automatically recognized.

• Open Project -> Option -> Build Actions

Here is the command line that creates an image of the code with STM32TrustedPackageCreator:

• Perform: Project -> Rebuild all (do not upload the code, only perform a compilation)

The following image is created: Projects\NUCLEO-H533RE\Templates\ROT\OEMiROT_Appli_TrustZone\Binary\rot_tz_s_app_enc_sign.hex
Do not close the EWARM project.

OEMiROT_Appli_TrustZone project compilation –nonsecure project

• Select the nonsecure project:

• Open Project -> Option -> Build Actions and check the correct paths for the command line.

This postbuild command creates an image of the compiled nonsecure code thanks to STM32TrustedPackageCreator.

• Perform: Project -> Rebuild all (do not upload the code, only perform a compilation)

The following image is created: Projects\NUCLEO-H533RE\Templates\ROT\OEMiROT_Appli_TrustZone\Binary\rot_tz_ns_app_enc_sign.hex

2.2.2. Firmware encrypted image generation with STM32TrustedPackageCreator

During this step two image files will be created from secure and nonsecure binary code files.

In the previous steps, secure and nonsecure code images have been created directly from the EWARM postbuild command (rot_tz_ns_app_enc_sign.hex and rot_tz_s_app_enc_sign.hex).

We show here how to perform manually an encrypted / signed code image (equivalent to what the postbuild command has executed).

• Open STM32TrustedPackageCreator and select the shield.
• Open the image gen tab.
• Select the template for the relevant image: OEMiRoT_S_Code_Image.xml (ROT_Provisioning\OEMiROT\Images directory)
• Update the default configuration if required:
  • Update the version number.
  • Select the binary file to be used as an input file.
  • Select the output file to be filled with the signed and encrypted binary (HEX format).
• Launch the generation.
• An encrypted signed file is created: rot_tz_s_app_enc_sign.hex

Resume from step 1 and select the OEMiRoT_NS_Code_Image.xml template to generate a rot_tz_ns_app_enc_sign.hex image.

Information

If you want to make a different configuration with, for example, 2 code images and 2 data images (one data secure and one data nonsecure), you can refer to this article Data image generation to generate images of data.

2.3. Step 3: Device provisioning, code and data image download into the flash memory, product state setting

The provided “provisioning” script will:

• Set the option bytes of the device.
• Configure the OEMiRoT and the DA on the device.
• Install the images (code and data).
• Set the final chosen product state according to user selection.

Before launching the script, connect the STM32CubeProgrammer and check that the device is in an open state.

If the device is not in an open state, refer to step 5, which explains the regression. If the flash memory is not erased, the provisioning script erases it anyway.

• Check that the BOOT pin is disconnected from VDD (For NUCLEO-H533RE board: disconnect CN7/pin5 from CN7/pin7).
• Connect the board and check that the STM32CubeProgrammer is disconnected.
• Open the folder OEMiRoT in: Projects\NUCLEO-H533RE\ROT_Provisioning\OEMiROT
• Double-click the provided provisioning.bat script to run it.
• Note: For Linux and Mac operating systems, the end users may have to change manually the attribute of .sh scripts to executable.
• Step 1 and step 2 have been previously executed: press any key to continue with Step 3.
• Step 3: The script proceeds with the option byte programming and flashing the code and data image.

The product state can be chosen (OPEN or PROVISIONED or TZ-CLOSED or CLOSED or LOCKED).

Warning

Reminder: LOCKED is a definitive product step that cannot be changed anymore.

Make a first trial setting the product in CLOSED state and complete the tutorial until the end.

2.4. Step 4: Execute the installed firmware

The code installed during the previous steps is executed. There is an infinite loop in the code that makes the green LED LED2 blink:

You can check that this LED is blinking on your board.

Warning

For this example, you cannot access to the bootloader in a closed state. User application developped in OEMiRoT_Appli_TrustZone does not give access to the secure bootloader via a terminal, it only makes the green LED blink. If the user wants to develop an application that gives access to the bootloader in a closed state, they can follow the example of the application developed for the STM32H573 -DK board (Projects\STM32H573I-DK\Applications\ROT\OEMiROT_Appli_TrustZone folder) or the NUCLEO-H563ZI board (Projects\NUCLEO-H563ZI\Applications\ROT\OEMiROT_Appli_TrustZone folder). Refer to the wiki article How to start with OEMiRoT on STM32H573 and 563–Arm® TrustZone® enabled to see how to proceed to download a new image of the code from a closed device. To access the bootloader from a closed state the user can perform a partial regression. A partial regression erases nonsecure code and nonsecure data. After a partial regression access to the bootloader is allowed and the user can download a new version of his nonsecure code. To perform a partial regression, follow the wiki article How to start with OEMiRoT on STM32H573 and 563–Arm® TrustZone® enabled.

2.5. Step 5: Regression

• A full regression erases the user-stored contents and secrets.
  • Erase the user flash memory content.
  • Erase the OBkeys.
  • Reset the secure option bytes to their default value.
  • Set the product in an open state.

• If the product is in an open state, a full regression is not needed: The device is not secured and changes can be done without any authentication. In case the regression script is executed, it indicates some errors.
• If the product is not in an open state, the only way to change the OEMiRoT is to first do a full regression.

2.5.1. Full regression from provisioned state using a script (included in the STM32CubeFW)

The regression can be done using the provided script or using the STM32CubeProgrammer.

To perform a full regression:

• Launch the regression script.

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

• If the regression has succeeded, the following message should be displayed:

• Connect STM32CubeProgrammer. Check that the flash memory content is well erased and that the option bytes and product state are at their default values.

2.5.2. Full regression from closed state using STM32CubeProgrammer

• Disconnect STM32CubeProgrammer.
• Redo the exercise starting at step 3, set the “closed” state.
• Click in STM32CubeProgrammer and select debug authentication.
• Click “Discover”, and the information window will be filled:

• Enter the paths for the key and the certificate (example with a certificate chain will be shown later, in this example only a single certificate is used (ROOT)):
• Click continue.
• The opening method and permission are selected. Only the opening method defined by the certificate mask (during provisioning) is possible.
• Click execute and you have the success message.

• Check with STM32CubeProgrammer that the flash memory content is well erased and that the option bytes and product state are at their default values.
• The TZ stays enabled and can be disabled using the STM32CubeProgrammer.

3. OEMiRoT step by step: Debug authentication

For debug authentication operations, refer to the wiki article How to start with OEMiRoT on STM32H573 and 563–Arm® TrustZone® enabled that describes how you can proceed to:

• Generate a certificate chain.
• Open the debug.
• Make a partial regression.