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 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 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 :

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. 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.

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

File:SECURITY path Pwd.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

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 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.

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

• • To the question Is your password already provisioned ? answer
    • Yes if you already did a provisioning in this device
    • No if you never did a provisioning on this device : In this case script propose you to create user.bin file. This step has been already done in Password definition .
• 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

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

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

• 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
• If the regression has succeeded the following message should be displayed
  

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 in CubeProgrammer and select “Debug Authentication”
• Click “Discover” the information window will be filled

• Enter the password.bin file

• Click Full regression and you get this successfull message box :

• 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.