How to start with OEMiRoT on STM32H503

How to start with OEMiRoT on STM32H503Clock.png45min

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

Hardware

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

Required tools

  • STM32CubeProgrammer[1] Software programming tool for STM32 (v2.13.0 min)
    • Including STM32TrustedPackageCreator
Info white.png 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 :

Security PinToTask.png

  • 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

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 white.png Warning
Place STM32CubeH5 package close to the C: root to avoid long windows path.
SECURITY Path NUCLEOH503.png


Warning white.png 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.

Info white.png 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 white.png 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

Warning white.png 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"

Security PATH Keygen script 2.png

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.
SECURITY PATH OEMiROT applis for H503 2.png
Info white.png 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 :

SECURITY H503 device Flash Layout config.png

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
SECURITY H503 device on IAR.png

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.

SECURITY H503 device postbuild on IAR.png
  • 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)
Info white.png 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
SECURITY H503 device Code image Generation via TPC 2.png

You get the success message :

SECURITY TPC image generation success message.png

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.
SECURITY H503 device Data image Generation via TPC.png

You get the success message :

SECURITY TPC image generation success message.png

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 white.png 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
Security user passwd folder H503.png


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

Security OPEN STATE STM32CubeProgrammer.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
SECURITY H503 device PROVISIONING SCRIPT STEPS1-2.png
  • Step 3 : The script will proceed with the option byte programming and flashing the code and data image
Warning white.png 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.

Security H503 device PROVISIONING SCRIPT from step3.png
  • Press a key to continue and the product state can be chosen (OPEN , PROVISIONED , CLOSED or LOCKED)
Warning white.png 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
Security PuTTY Configuration.png

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 :

SECURITY H503 device Putty message Flash new code.png
  • Close/disconnect the terminal emulator
Warning white.png 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; 
SECURITY H503 device Modify OEMiROT Appli.png
  • 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)
SECURITY H503 device Connect UART CubeProgrammer.png
  • Select SECURITY ICON Erasing and Programming CubeProgrammer.png“Erasing & Programming” tab
  • Browse encrypted code image .hex file that we previously generated in folder Projects\NUCLEO-H503RB\Applications\ROT\OEMiROT_Appli\Binary
SECURITY H503 device flash new code on CubeProgrammer.png
  • Click Start Programming
  • You can also here download encrypted data image .hex file data_enc_sign.hex :
Security H503 device flash new data on CubeProgrammer.png
  • Click Start Programming
  • Disconnect STM32CubeProgrammer
  • Open PUTTY(or another terminal emulator)
  • Select “Serial" and the COMxx port
  • Set speed to 115200
  • Click: Open
Security PuTTY Configuration.png
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)

Security regression folder H503.png

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
    Security RegressionSuccess.png

Connect STM32CubeProgrammer and check that the flash content is well erased and that the option bytes and product state are at default values.

7.2. Full regression using STM32CubeProgrammer

  • Disconnect the CubeProgrammer, remove/plug the USB cable
  • Redo the exercise starting at step1, set the “CLOSED” state
  • Select Security DA icon.png in CubeProgrammer and select “Debug Authentication”
  • Click “Discover” the information window will be filled
SECURITY H503 device Discovery cmd CubeProgrammer.png
  • Enter the password.bin file
Security da-password select file CP.png
  • Click Full regression and you get this successfull message box :
SECURITY DA Success Message w CubeProgrammer debug reopen.png
  • Check with CubeProgrammer that the flash content is well erased and that the product state and option bytes are at default values thanks ST link SWD.

8. References