How to start with OEMiRoT on STM32H503

How to start with OEMiRoT on STM32H50345min

Target description

Through this practical example the user will learn how to perform the following operations

Perform the provisioning:
- Initial Option Bytes programming
- Code image generation and flashing
- Debug Authentication password provisioning
Execute the installed firmware
Flash new User application in CLOSED state
Perform a full regression with Password Authentication method

Prerequisites

RM0492 STM32H503xx Reference Manual
Introduction to Debug Authentication for STM32H5
knowledge of STM32CubeProgrammer
knowledge of JTAG / SWD interface

Hardware

Nucleo-STM32H503RB board revB min : MB1814-H503RB-B01

Required tools

STM32CubeProgrammer^[1] 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 task bar to simplify the DA How to process :

STM32Cube_FW_H5_V1.0.0 ^[2] or upper
IAR Embedded Workbench v9.20.1 or upper
Tera Term or equivalent UART Terminal emulator

Literature

RM0492 STM32H503xx Reference Manual
UM2237 STM32CubeProgrammer software description
UM2238 STM32 Trusted Package Creator tool software description
AN5054 Secure programming using STM32CubeProgrammer
AN2606 STM32 microcontroller system memory boot mode
Introduction to Debug Authentication for STM32H5 MCUs

Environment setup

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

Download the STM32CubeH5 package and install it

A directory NUCLEO-H503RB is included in the Projects directory

Warning

Place STM32CubeH5 package close to the C: root to avoid long windows path.

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 :NUCLEO-H503RB\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. STM32H503 device specific behaviors

STM32H503 devices are based on STM32H5x3 devices architecture without any Arm® TrustZone®.
In order to allow regression thanks to the debug authentication, the STM32H503 should be provisioned with a Debug Authentication password.

Information

If you want to practice debug authentication mechanism, you can start with this article : How to start with DA access on STM32H503

The flash interface doesn't provide OBKeys -> OTP is used to provision Debug Authentication password.

Warning

Once provisioned during the provisioning step (see Provisioning step) Debug Authentication password can't be changed anymore.

It is the user responsibility to keep and protect this Debug Authentication password and to restrict its access .

2. Step 1 : Configuration management - OEMiRoT Keys generation

At this step the following two keys pair will be generated

ECDSA-256 encryption key
ECDSA-256 authentication key

These keys will be used to encrypt and authenticate the user application.

Run the provided script Keygen.bat :

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

Warning

If you are using STM32Cube_FW_H5_V.2.0 you have to modify keygen.bat script before launching it : please replace at line 40

set "imgtool=%tpc_dir%\Utilities\Windows\imgtool.exe" by set "imgtool="%tpc_dir%"\Utilities\Windows\imgtool.exe"

Once you get the success message, keys are well generated in folders

Projects\NUCLEO-H503RB\ROT_Provisioning\OEMiROT\Keys
Applications\ROT\OEMiROT_Boot\Src\key.c.

3. Step 2 : Code and data image generation

Check that the STM32H5 IAR provided patch in Utilities\PC_Software\IDEs_Patches\EWARM folder is correctly installed and check that your IAR Embedded Workbench version is recent enough.

Please refer to OEMiRoT STM32H5 How to Introduction if you want more details about OEMiROT_Boot and OEMiROT_Appli firmwares.

Two code examples for IAR Embedded Workbench are provided

OEMiROT_Boot corresponds to the Secure Boot AKA OEMiRoT.

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

OEMiROT_Appli is an example of application firmware that will be authenticate by OEMiRoT before been launched.

Information

In this example OEMiROT_Boot code is waiting for one user code image and one data image. To activate or not data you can modify the MCUBOOT_DATA_IMAGE_NUMBER to 0 or 1.

See flash_layout.h file in Projects\NUCLEO-H503RB\Applications\ROT\OEMiROT_Boot\Inc folder :

3.1. OEMiROT_Boot project compilation

Open the Project.eww located in the EWARM directory :

Projects\NUCLEO-H503RB\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 check that your IAR Embedded Workbench version is recent enough

Perform: Project -> Rebuild all (don’t upload the code, only perform a compilation)

The following binary is created thanks a postbuild script:
Projects\NUCLEO-H503RB\Applications\ROT\OEMiROT_Boot\Binary\OEMiROT_Boot.bin

3.2. OEMiROT_Appli project compilation and code image generation

3.2.1. OEMiROT_Appli project compilation and code image generation with IAR

Open the Project.eww located in the EWARM directory :

Projects\NUCLEO-H503RB\Applications\ROT\OEMiROT_Appli\EWARM

Open Project -> Option -> General Options

The device and CPU core should be automatically recognized.

Open Project -> Option -> Build Actions

Here is the command line which will create an image with the code in clear and also an encrypted and signed image thanks the STM32TrustedPackageCreator tool.

Perform: Project -> Rebuild all (don’t upload the code, only perform a compilation)

The following image is created:

Binary file is generated here :
Projects\NUCLEO-H503RB\Applications\ROT\OEMiROT_Appli\Binary\rot_app.bin

Encrypted and signed code image is create here :
Projects\NUCLEO-H503RB\Applications\ROT\OEMiROT_Appli\Binary\rot_app_enc_sign.hex

3.2.2. Code image generation using STM32TrustedPackageCreator

The code image has been created directly through postbuild command in IAR but you also have the possibility to generate this image using STM32TrustedPackageCreator.

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

Open STM32TrustedPackageCreator
Select H5
Open tab ImageGen
Select the template for the relevant image: OEMiRoT_Code_Image.xml (Projects\NUCLEO-H503RB\ROT_Provisioning\OEMiROT\Images directory)

Information

Paths of Keys used to encrypt and sign are set in the xml template file

Update the default configuration if required
- Firmware area size
- Version number
- Dependency with the other image when simultaneous installation is required for compatibility reasons.
- Select the binary file to be used as input file
- Select the output file to be filled with the signed and encrypted binary (hex format)
Launch the generation using the Generate image button
An encrypted signed file will be created : rot_app_enc_sign.hex

You get the success message :

3.3. Data image generation

During this step an image file will be created from data file provided as example for this tutorial.

Here are the steps to generate images:

Open STM32TrustedPackageCreator
Select H5
Open tab ImageGen'
Select the template for the relevant image: OEMiRoT_Data_Image.xml (Projects/NUCLEO-H503RB/ROT_Provisioning/OEMiROT/Images/OEMiRoT_Data_Image.xml directory)
Update the default configuration if required
- Version number
- Dependency with the other firmware image when simultaneous installation is required for compatibility reasons.
- Binary file to be used as input filer : rot_app.bin' file is an example of data that could be displayed by the firmware example.
- Output file to be filled with the signed and encrypted binary (hex format)
Launch the generation using the Generate image button
An encrypted signed file will be created : data_enc_sign.hex in Projects\NUCLEO-H503RB\ROT_Provisioning\OEMiROT\Binary folder.

You get the success message :

4. Step 3 : Device provisioning

In order to allow regression thanks to the debug authentication, the STM32H503 should be provisioned with a Debug Authentication password.
, the STM32H503 should be provisioned with a Debug Authentication password.

4.1. Debug Authentication password definition

If you have not yet provisioned any Debug Authentication password in the chip, you have the possibility to update the default Debug Authentication password in user_password.bin file located in Projects\NUCLEO-H503RB\ROT_Provisioning\DA folder.

For a commercial product it's mandatory to define your own password.

Warning

Debug Authentication password is provisioned on OTP(One Time Programming). Once provisioned during the provisioning step (see Provisioning step) it can't be changed anymore

user_passord.bin : where you define the Debug Authentication password(16 bytes) that will be provisioned

board_password.bin : HASH of user Debug Authentication password which will be provisioned in the chip

da_password.bin : output file in order to open the DA access for regression

create_password.bat script automatically launched by the provisioning.bat script to create the board-password.bin and password.bin files used for provisioning and regression.

board_password.bin and da_password.bin files will be automatically updated with the new Debug Authentication password saved in user_password.bin during provisioning script (see Provisioning step). You can also use the default Debug Authentication password.

4.2. Provisioning

The provisioning could be done thanks to the script NUCLEO-H503RB\ROT_Provisioning\OEMiROT\provisioning.bat

This script will :

Set the option bytes of the device
Configure the OEMiRoT on the device
Provision the Debug Authentication password on the device if not yet provisioned
Install the images (code and data)
Set the final chosen product state according user selection

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

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

Security Provisioning Script for H503 OEMiROT 2.png

If it’s not the case refer to Full regression explaining the regression. If the flash is not erased, the provisioning script will anyway erase it.

Disconnect STM32CubeProgrammer.

Open folder OEMiRoT in: Projects\NUCLEO-H503RB\ROT_Provisioning\OEMiROT
Run the provided provisioning.bat script (double click)
Steps 1 and step 2 have been previously executed : press any key to continue until Step 3

Step 3 : The script will proceed with the option byte programming and flashing the code and data image

Warning

For a first provisioning of the chip the operation may take some time.

If you already provisioned the board in the past with a password, the step which configures the password in the script is not taken into account as the password has already been programmed in OTP.

Press a key to continue and the product state can be chosen (OPEN , PROVISIONED , CLOSED or LOCKED)

Warning

Reminder that LOCKED is a definitive product step that can’t be changed anymore.

Make a trial with CLOSED state

5. Check the installed firmware behavior

Open PUTTY(or another terminal emulator)
Select “Serial" and the COMxx port
Set speed to 115200
Data 8 bits / Parity None / Stop 1 bit
Click: Open

Reset the board (SW reset button on the board) : The code installed during previous steps will be executed

Security H503 device NEW Firmware display on Putty.png

The menu of the installed code has two options

The menu 1 will launch the standard bootloader located in the system flash
The menu 2 will display datas from data.bin

6. Flash new User application in CLOSED state

In the Terminal emulator choose Start Bootloader : Write 1 and press enter.

--> This message is displayed :

Close/disconnect the terminal emulator

Warning

To insure the embedded bootloader is still executed, Don't power OFF/ON the board and don't Reset the device

Open the project Project.eww in OEMiROT_Appli folder : .\Projects\NUCLEO-H503RB\Applications\ROT\OEMiROT_Appli\EWARM
Change const uint8_t UserAppId = 'A' line 60 in main.c file by :

const uint8_t UserAppId = ‘B’;

Select: Project-> Rebuild all

Connect the board via UART on STM32CubeProgrammer without performing any reset or power OFF power ON (don't disconnect the board from your laptop)

Select “Erasing & Programming” tab
Browse encrypted code image .hex file that we previously generated in folder Projects\NUCLEO-H503RB\Applications\ROT\OEMiROT_Appli\Binary

Click Start Programming
You can also here download encrypted data image .hex file data_enc_sign.hex :

Click Start Programming
Disconnect STM32CubeProgrammer

Open PUTTY(or another terminal emulator)
Select “Serial" and the COMxx port
Set speed to 115200
Click: Open

Security H503 device NEW Firmware display on Putty-B.png

Reset the board (SW reset button on the board)

Boot Code and new firmware are displayed

7. Full regression

A full regression will erase the user stored contents.
- Erase the user flash content
- Set the product in open state

If the product is in Open state, a full regression is not needed since the device is not secured and changes can be done without any authentication.

In case the regression script is executed, it will indicate some errors

If the product is not in Open state, the only way to change the product state is to first do a full regression

7.1. Full regression using the provided script

The regression can be done using the provided script or using CubeProgrammer (see 4.2)

To perform a full regression

Launch the regression.bat script located in ROT_Provisioning\DA
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