OEMiRoT STM32H5 How to Introduction

Coming soon

OEM-iROT stands for Original Equipment Manufacturer immutable Root of Trust. The users can develop OEM-iROT on all the STM32H5xx devices.

1. Introduction

This wiki article describes OEMiROT process steps that are developed in STM32CubeH5 firmware and has to be read before the How to articles about OEMiROT :

• How to start with OEM-iROT on STM32H573–TrustZone enabled
• How to start with OEM-iROT on STM32H503

For more informations about OEMiROT operations possibilities you can refer to OEMiROT fo)r STM32H5 MCUs .

2. OEM-iROT services

1) The secure boot (Root of Trust services):

It is an immutable code that is always executed after a system reset. It activates STM32 runtime protections, and verifies the authenticity and integrity of the application code before every execution.

• Integrity: to ensure that a firmware about to be executed has not been corrupted or maliciously modified.
  
• Authenticity: to verify that a firmware is coming from a trusted and known source in order to prevent unauthorized entities to install and execute code.
  

2) The Secure Firmware Update:

It is an immutable code that detects if a new firmware image is available, checks its authenticity and verifies the integrity of the code before installing it after decryption.

3. OEM-iROT process in STM32CubeH5 firmware examples

At each Reset, the OEM-iROT firmware located in User Flash is first executed in HDPL1. It is the user's responsibility to develop a root of trust firmware that:

• First checks authenticity and integrity of user application
• Secondly jumps to the user application or bootloader depending on the authenticity and integrity checks.

After a successful check of authenticity and integrity of the user application, OEM-iROT can jump directly in HDPL2 or HDPL3 (user application can be installed in HDPL2 or HDPL3). User Application can be a fully secure application, a full nonsecure application, or a combined secure/ nonsecure application. If parameters configured in User Root of Trust are not respected or if Authenticity and integrity checks fail, OEM-iROT executes bootloader to download new user application and user data. It is the user’s responsibility to activate all the required security protections during the User Application execution.

3.1. OEM-iROT provisioning steps

3.1.1. Step 1 - OEM-iROT and Debug Authentication configuration

3.1.1.1. OEM-iROT configuration

STM32TrustedPackageCreator tool is used to generate OEM-iROT configuration file (.obk) based on template provided in STM32CubeH5 Software package. This configuration file generates keys that will be used to

• At binary generation step:
  • Encrypt the data
  • Sign the user application
• In the device:
  • Decrypt the data
  • Check signature (authorization)

All other parameters are configured directly by the User in his Root of Trust firmware located in HDPL1 in User Flash. This code must be able to perform authenticity and integrity checks of the User application and data images. It also configures the number of User application and images:

• Number of data image
• Number of code image

These parameters are defined in OEMiROT_boot applications available for each OEMiROT example in the folders Applications\ROT\OEMiROT_Boot\Inc\flash_layout.h.

3.1.1.2. DA configuration

STM32TrustedPackageCreator is also used to generate the Debug Authentication configuration file (.obk) based on template provided in STM32CubeH5 software package. This file is used to configure the conditions to reopen a protected device and the debugger. Depending on the User application additional configuration files could be generated.

For more details about debug authentication mechanisms, please refer to Introduction to Debug Authentication for STM32H5 MCUs.

3.1.2. Step 2 – Code and data image generation

STM32CubeH5 FW package is delivering user application projects for each OEM-iROT example in Applications\ROT folders.

The compilation of the user application projects generate a binary file. This binary file will be used as input file for the generation of the encrypted code images .hex.
Associated with an xml configuration file User can update the Firmware area size and the version of the image.

STM32CubeH5 FW package is also delivering binaries data file examples in ROT_Provisioning\OEMiROT\Binary folder that can be encrypted.

3.1.2.1. User application code image generation

The user application code binary file is generated by any IDE during compilation.

The image creation is done automatically by the IDE during the user application compilation by calling STM32TrustedPackageCreator in a postbuild command.

STM32TrustedPackageCreator can be launched separately to generate the encrypted and signed image file using the same encryption and authenticity keys provisioned during the OEM-iROT configuration.

STM32TrustedPackageCreator is using a configuration file to generate images.

xml files examples are available for each OEM-iROT project example in the STM32Cube_FW (ROT_Provisioning\OEMiROT\Config) and can be edited using STM32TrustedPackageCreator.

3.1.2.2. User Data Image generation

STM32TrustedPackageCreator needs to be launched separately to generate the encrypted and signed image file using the same encryption and authenticity keys provisioned during the OEMiROT configuration. These keys are also used for the user application code image generation.

STM32TrustedPackageCreator is using an xml configuration file for each OEM-iROT project example in the STM32Cube_FW(ROT_Provisioning\OEMiROT\Images ). These files can be edited using STM32TrustedPackageCreator.

3.1.3. Step 3 – Product state setting

The following figure shows the possible product state.
(for more details, refer to product lifecycle and Debug Authentication articles).

The provided script Provisioning.bat given as example in STM32CubeH5 firmware is guiding the user during this phase.
At the end of the provisioning script execution, the product state can be chosen, and the related option byte will be automatically set.
The product state is chosen depending on the user application development phase and the wanted security level.

• Open:
  

• This state is mainly used during development phase since the device is fully open.
  
• Debug is fully open.
  
• The Trust Zone can be disabled or enabled (TZEN option byte programming).
  
• Bootloader can be used.
  

• Provisioning:
  

• This state is used during the provisioning.
  

It is the device state during the provisioning script execution (Provisioning.bat given as example in STM32CubeH5 firmware)

So this state will not be part of the proposed state that can be chosen at the end of the script execution.

• The debug is only available when non secure user application is executed.
  
• The Trust Zone can be disabled or enabled (TZEN option byte programming).
  
• Bootloader can be used.
  
• Secure Firmware install can be launched in this state (not anymore possible in following states).
  

• Provisioned:
  

• In this state the OEM-iROT setup is done.
  
• Debug is available only when non secure user application is executed.
  
• Debug access for secure application can be available by launching the Debug Authentication (see Debug Authentication setting).
  
• The OEM-iROT can launch the bootloader if the verification of the code located in the next isolation level is failing (authentication, integrity or missing code)
  

• TZ-Closed:
  

• The Trust Zone closed state is used when

• the OEM-iROT and the secure user application are provisioned (case 1)
• the OEM-iROT and the uROT+Secure user application are provisioned (case2) (see section 5.1.2).
  

• For case 2, the uROT is allowing the update of the next isolation level (Code and Data).
  

• uROT can launch the bootloader if the verification of the code located in the next isolation level is failing (authentication, integrity or missing code).
  

• The debug is only available when non secure user application is executed.
  
• Debug access for secure application can be available by launching the Debug Authentication (see Debug Authentication setting).
  

• Closed:
  

• This state is used when the product is fully provisioned.
  
• The debug is fully closed but can be open by launching the Debug Authentication (see Debug Authentication setting) .
  

• Locked:
  

• This state is used when the product is fully provisioned, and no changes are done anymore.
  
• Locked is definitive product state that can’t be changed anymore, the embedded FW and product configuration can’t be modified by any method.
  
• The debug is definitively closed and can’t be reopen through debug authentication.
  
• No regression is possible anymore
  

4. How to start with STM32 and OEM-iROT

You can refer to the following pages for getting started examples of OEM-iROT.

• How to start with OEM-iROT on STM32H573–TrustZone enabled
• How to start with OEM-iROT on STM32H503