How to start with OEM-iROT on STM32H50345min
Target description
This tutorial shows how to make a provisioning and then a full regression on a STM32H503 device. Provisioning process goes through 3 steps :
- Initial Option Bytes programming
- Code image generation and flashing
- Password provisioning
The last step shows a full regression.
Prerequisites
- knowledge of STM32CubeProgrammer
- knowledge of JTAG / SWD interface
Hardware
- Nucleo MB1814 with STM32H503
Required tools
- STM32CubeProgrammer[1] Software programming tool for STM32 (v2.13.0 min)
- Including STM32TrustedPackageCreator
- STM32Cube_FW_H5_V1.0.0 or later
- IAR Embedded Workbench v9.20.1
- Tera Term or equivalent terminal emulator
Literature
- UM2237 STM32CubeProgrammer software description
- UM2238 STM32 Trusted Package Creator 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 DA process.
- Download the STM32CubeFW_H5 Cube firmware
A directory NUCLEO-H503RB is included in the Projects directory
- STM32CubeProgrammer default folder is : C:\Program Files\STMicroelectronics\STM32Cube\STM32CubeProgrammer
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. Step 1 : Configuration management - OEMiROT Keys generation
At this step the following keys will be generated:
- ECDSA-256 encryption private key
- ECDSA-256 encryption public 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 folder Projects\NUCLEO-H503RB\ROT_Provisioning\OEMiROT\Keys.
2. Step 2 : Code and data image generation
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 is an example of application managed by OEMiROT
2.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:…..\Projects\NUCLEO-H503RB\Applications\ROT\OEMiROT_Boot\Binary\OEMiROT_Boot.bin
2.2. OEMiROT_Appli project compilation and code image generation
2.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 of the code with STM32Cube Package Creator:
- 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 code image is create here :..\Projects\NUCLEO-H503RB\Applications\ROT\OEMiROT_Appli\Binary\rot_app_enc_sign.hex
2.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)
- Update the default configuration if required
- Firmware area size
- Version number
- Dependency with the other (Data) 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
- An encrypted signed file will be created : rot_app_enc_sign.hex
2.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 Data image when simultaneous installation is required for compatibility reasons.
- Binary file to be used as input file
- Output file to be filled with the signed and encrypted binary (hex format)
- Launch the generation
- An encrypted signed file will be created : data_enc_sign.hex in ./Projects\NUCLEO-H503RB\ROT_Provisioning\OEMiROT\Binary folder.
3. Step 3 : Device provisioning
On STM32H503 MCUs Debug Authentication is using password to make regression.
3.1. Password definition
If you have not yet provisioned any password in the chip, you have the possibility to update the default password in user_password.bin file located in Projects\NUCLEO-H503RB\ROT_Provisioning\DA folder.
Board_password.bin and Password.bin files will be automatically updated with the new password saved in user_password.bin during provisioning script (see Provisioning step).
You can also use the default password.
3.2. Provisioning
The provided “provisioning” script will
- Set the option bytes of the device
- Configure the OEMiROT on the device
- Provision the 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 the step 4 explaining the regression. If the flash is not erased, the provisioning script will anyway erase it.
- Connect the board
- 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
- 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 so you can press any key to continue.
- To the question Is your password already provisioned ? answer
Press a key to continue and the product state can be chosen (OPEN or PROVISIONED or CLOSED or LOCKED)
Make a trial with CLOSED state