How to start with OEMiRoT on STM32U3

How to start with OEMiRoT on STM32U385 - Arm® TrustZone® enabledClock.png85min

Literature

  • RM0487 STM32U3 Reference Manual (not yet officially available)
  • UM2237 STM32CubeProgrammer software description
  • UM2238 STM32TrustedPackageCreator tool software description
  • AN5054 Secure programming using STM32CubeProgrammer
  • AN2606 STM32 microcontroller system memory boot mode
  • It is advised to read the RDP for STM32U3 article.
  • It is advised to read the OEMiRoT_OEMuRoT_for_STM32U3 article.



Target description

The purpose of this article is to explain step by step how to use the OEMiRoT STM32CubeFW example provided by ST.
The provided example is using the STM32U385 Nucleo board, a device embedding hardware cryptographic accelerators (contrarily to STM32U375).
No example is provided for the STM32U375 and no ST board is available for this device.
But OEMiRoT is possible for the STM32U375 using mbed-crypto middleware.


Introduction

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

  • Run the OEMiRoT example of the STM32CubeFW
    • Provisioning preparation
    • Code and data compilation and encrypted image generation
    • Perform the provisioning and install the firmware and data files
    • Execute the installed firmware
    • Modify the user application and perform a firmware update
    • Perform a full regression
    • Provisioning in RDP>0
    • Regression using password

Prerequisites

  • Hardware
    • U385RG-Q Nucleo board (MB1841)
Figure 1 Nucleo board STM32U385
  • Required tools
    • STM32Cube_FW_U3_V1.1.0 [1] or upper
    • STM32CubeProgrammer[2] Software programming tool for STM32 (STM32CubeProgrammer API v2.18.0-RC3 or later version)
      • Including STM32TrustedPackageCreator
    • IAR Embedded Workbench rev 9.20.1 + patch STM32U37x-38x
      • The patch is available in the STM32CubeFW: STM32Cube_FW_U3_Vx.x.x\Utilities\PC_Software
    • Tera Term or equivalent UART Terminal emulator
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 the task bar to simplify the OEMiRoT Getting started process :

Security PinToTask.png


  • Environment setup
    • Download the STM32CubeU3 package and install it
Warning white.png Warning
Place STM32CubeFW_U3 Cube firmware close to the C: root to avoid a long Windows® path.


  • A directory NUCLEO-STM32U385RG-Q is included in the CubeFW Projects directory.
The ROT_Provisioning\OEMiRoT directory contains the different tools, configuration files and scripts.
The Applications\ROT directory contains the different code examples used in this step by step.


Figure 2 STM32Cube_FW_U3
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 :Projects\NUCLEO-U385RG-Q\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"
set imgtool="C:\Program Files\STMicroelectronics\STM32Cube\STM32CubeProgrammer\bin\Utilities\Windows\imgtool.exe"


1. OEMiRoT configuration and launch of the provisioning script↑

This chapter explains how to start with the configuration and launch of the provisioning script.

1.1. Setting of the images configuration↑

  • Open the flash_layout.h using a text editor:
STM32Cube_FW_U3_Vx.x.x\Projects\NUCLEO-U385RG-Q\Applications\ROT\OEMiROT_Boot\Inc
Figure 3 Configuration of number of images

The flash_layout file defines different settings such as the flash area split and the number/type of images.

  • For this tutorial, set the data images for secure and non-secure as shown in the figure above and keep the default settings for all other parameters.
The image generation for the user application and data will be explained later in this article.
Info white.png Information
The image installation mode is also defined in the flash_layout.h file: 
#define MCUBOOT_OVERWRITE_ONLY: (defined by default) if undefined: swap mode is selected allowing to keep the previously installed application.

Refer to OEMiRoT_OEMuRoT_for_STM32U3 article.

1.2. Launch the provisioning script↑

The scripts are located in \Projects\NUCLEO-U385RG-Q\ROT_Provisioning\OEMiROT.

  • Launch one of the provided scripts depending on your IDE:
    • For EWARM or MDK-ARM: launch the provisioning.bat script.
    • For STM32CubeIDE: launch the provisioning.sh script.
  • Keep the script running during the complete process, it will guide you through all the steps.
Figure 4 Script launch and RDP selection

1.2.1. RDP level selection↑

  • As indicated by the script, the RDP level needs to be defined.
    • it is advised to make first trials in RDP0.
    • Before increasing the RDP level, ensure to have a good understanding of the role of the other RDP levels.
    • Refer to the RM0487 and to the documentations indicated at the beginning of this article.

1.2.2. Authentication and encryption keys setting↑

  • Open TrustedPackageCreator (TPC)
  • Select the "Shield" Icon and open the OEMiRoT_Config.xml file, as show in the figure below.


Figure 5 Keys regeneration and option byte file
  • Three different keys are shown.
    • The authentication key for the Secure application/data and the Non-Secure application/data.
    • The key for the encryption of the applications and data.
  • The default keys are advised to be used for trials.
  • For a commercial product, obviously the keys need to be regenerated.
    • The keys can be regenerated using TPC.
  • Keep the path and name for the output file as shown in the figure. This file will be used by the script during the provisioning.
  • Click on "Generate OBkey" (right bottom of the TPC window, not shown in the figure above)
    • The OEMiRoT_Keys.bin file is generated in the ROT_Provisioning\OEMiROT\Binary folder.

2. Code and data images generation↑

2.1. OEMiRoT_Boot firmware compilation↑

A boot firmware example is provided in the CubeFW for the different supported IDE.
For this tutorial IAR Embedded Workbench is used.

Figure 6 Image generation of the Boot firmware
  • Open the OEMiRoT_Boot project with your preferred tool chain.
    • The OEMiRoT_Boot firmware is available at: STM32Cube_FW_U3_Vx.x.x\Projects\NUCLEO-U385RG-Q\Applications\ROT\OEMiROT_Boot
  • STM32U385RG should be automatically selected in the product option (see figure below)
    • For IAR: menu: Project -> Option -> General Option
    • If it's not the case, please check if your IDE version is supporting this product or if the STM32U3 patch is correctly installed (see prerequisites at the beginning of this article)
Figure 7 General option product selection
  • Perform: Project -> Rebuild All (don’t upload the code, only perform a compilation)

2.2. User application code compilation↑

As indicated by the script, the next step is to compile the user application.

Figure 8 Script, user application

The user application is split into two parts: a secure application and a non-secure application.

  • Open the OEMiRoT_Appli_TrustZone application code using your preferred tool chain.
    • STM32Cube_FW_U3_Vx.x.x\Projects\NUCLEO-U385RG-Q\Applications\ROT\OEMiROT_Appli_TrustZone\EWARM
    • Verify that the STM32U385 appears in the menu: Project -> Option -> General Option (see figure 6)
    • Open Project -> Option -> Build Actions and check the correct paths for the command line (see figure below)
Figure 9 Build Actions menu in IAR
  • Through the postbuild command, the binaries are automatically encrypted and signed using the keys defined in the section "Authentication and encryption keys setting".
  • As shown in the figure below, the user application code example is divided in two different codes, one secure and one non-secure.
  • Compile first the secure code: click right on "Appli_TrustZone_S" => RebuildAll (don’t upload the code, only perform a compilation)
  • Proceed in the same way to compile the "Appli_TrustZone_NS".


Figure 10 Secure and Non-Secure user application
  • As shown in the figure below for each user application a binary is created and through the postbuild command encrypted and signed binaries are also created.


Figure 11 Encrypted and signed user application


  • Notes
    • The encrypted and signed images generation for the secure and non-secure application codes can also been done graphically using STM32TrustedPackageCreator (TPC). How to proceed is shown in the next section for the data images creation.
      • The OEMiROT_S_Code_Image.xml and the OEMiROT_NS_Code_Image.xml files can be open with TPC.
      • These files are located in the same folder as for the data (see next section).
      • The dependencies with other images can also be managed.
    • These .xml files can also be directly edited with a text editor and changes done directly (e.g. image dependency).
      • In case of modifications of these xml files relaunch the IDE compilation and the new encrypted and signed images will be created though the postbuild command.

2.3. Secure data image generation↑

As indicated by the script the next step is to generate the encrypted and signed images of the data.

  • A binary file for the secure data and a binary file for the non-secure data are provided as exemple.
    • s_data.bin and ns_data.bin in folder Projects\NUCLEO-U385RG-Q\ROT_Provisioning\OEMiROT\Binary
    • These files can be open using STM32CubeProgrammer => tab "Open file" => select s_data.bin or ns_data.bin.
Figure 12 Encrypted and signed user data generation
  • To generate the encrypted and signed images of these data files launch STM32TrustedPackageCreator.exe
  • Click on shield and open the OEMiROT_S_Data_Image.xml file located in the OEMiRoT/Images folder (see figure below)
  • Click on "Generate Image"


Figure 13 Encrypted and signed user data generation with TPC
Info white.png Information
The script will also generate the data images (secure and non-secure). So in case the Data_Image.xml don't need any update, it not necessary to open STM32TrustedPackageCreator to regenerate a new image, it will be done automatically by the script.

2.4. Non-Secure data image generation↑

  • Proceed in the same way as explained in the previous section to generate the non-secure data image
  • Open the OEMiROT_NS_Data_Image.xml file and generate the image
  • As shown in the figure below two new files have been created: s_data_enc_sign.bin and ns_data_enc_sign.bin


Figure 14 Encrypted and signed generated data images

3. Board Provisioning↑

  • Connect the Nucleo board using the USB STLK port.
  • The script will automatically perform the provisioning of the device using all the files generated during the previous steps.

3.1. Boot pin to set to VSS↑

  • As indicated by the script, the boot pin needs to be set to VSS (through the on board-pull down on the pin5 of CN7).
Figure 15 OEM2 key provisioning

3.2. OTP programming and flash programming↑

As indicated by the script the OEM2 key is provisioned.
For RDP0 level the provisioning of this key would not be needed, but the script will perform it by default.
The advantage is that the regression of the board will always be possible, also in case accidentally the user sets the device to RDP2.

  • An example password file is provided: \Projects\NUCLEO-U385RG-Q\ROT_Provisioning\OEMiROT\Keys\oem2_password.txt
    • For trials it's advised to use this default value text file.
    • For commercial products obviously, a personal password has to be defined and kept secret in order to be able to make a regression if needed in future.
  • The script will automatically set the OTPs and install the different codes and data.
  • As shown in the figure below, at the end of the automatic process, a message is displayed confirming that the board is correctly provisioned.
Figure 16 Nucleo board provisioning
  • Close the script

4. Execution of the installed application↑

  • Open Tera Term (or another terminal emulator)
  • Select “ Serial” and the COMxx port related to the STLink
  • Setup -> Serial port …
  • Set speed to 115200 and data to 8 bit
  • Click: New Setting
Figure 17 Tera term setting
  • Reset the board (black reset button)
    • The code installed during the previous steps is executed
Figure 18 User application code execution
  • The different menus can be tried out typing the related number on your keyboard.


5. Regression↑

A regression will re-intialize the device, removing all the installed applications and option byte settings.

  • If connected to the device, close the Tera Term or STM32CubeProgrammer.
  • Launch the regression.bat or regression.sh script located in: STM32Cube_FW_U3_Vx.x.x\Projects\NUCLEO-U385RG-Q\ROT_Provisioning\OEMiROT
  • When the regression is completed a confirmation message is displayed according to the figure below.
Figure 19 Regression script
  • With STM32CubeProgrammer the flash and option bytes can be readout to verify that the device has been reinitialized.

6. RDP1 provisioning↑

The provisioning in RDP1 is not described in this article.

  • After a regression the provisioning script can be launched again and the RDP1 can be defined.
Warning white.png Warning
It is important to recompile the OEMiRoT_Boot project so the RDP setting is done correctly. Without recompilation, the risk is to lock a device due to a bad provisioning
  • The best way to proceed is to follow all the indications of the provisioning script and to regenerate all the firmware images.
Info white.png Information
if the provisioning is indicated by the script as successfully completed, but that the code is not executed and the option bytes can't be read anymore using the STLink: refer to the appendix to upgrade the firmware of the on-board STLink (in the " Change Type" it is advised to not select the Mass Storage, since the mass storage can create cases interpreted as an intrusion by the STLink).
  • Reminder: in RDP1 using STM32CubeProgrammer, it is not possible to read the content of the flash since readout protected, but it is possible to read the Option Bytes values.

7. RDP2 provisioning and Firmware Update↑

7.1. Provisioning in RDP2↑

Previous sections are describing how to use the script, generate the different encrypted and signed images and perform the board provisioning.

  • Disconnect and reconnect the USB cable to perform a power on reset.
  • Launch the provisioning script (STM32Cube_FW_U3_Vx.x.x\Projects\NUCLEO-U385RG-Q\ROT_Provisioning\OEMiROT\provisioning.bat or .sh).
    • For EWARM or MDK-ARM: launch the provisioning.bat script.
    • For STM32CubeIDE: launch the provisioning.sh script.


Figure 20 Launch script for RDP2
  • All the steps requested by the script are described in the previous sections.
Warning white.png Warning
It is important to recompile the OEMiRoT_Boot project so the RDP setting is done correctly. Without recompilation the risk is to lock a device due to a bad provisioning


  • The last provisioning steps are shown in the figure below.
    • The RDP has been set to level 2.
    • A confirmation of correct programming is indicated as shown in the figure.
Figure 21 Board provisioning in RDP2
  • Launch STM32CubeProgrammer and try to connect the board.
  • Since the device has been set to RDP2 the debugger is disabled.
Figure 22 Debugger disabled in RDP2

7.2. Execute installed application in RDP2↑

As explained in previous section, execute the installed application as following:

  • Open Tera Term (or another terminal emulator)
  • Select “ Serial” and the COMxx port related to the STLink
  • Setup -> Serial port …
  • Set speed to 115200 and data to 8 bits
  • Click: New Setting
Figure 23 User application code execution
  • Keep the script open

7.3. User application update↑

7.3.1. User application modification↑

  • Open the user application with your preferred tool chain: STM32Cube_FW_U3_Vx.x.x\Projects\NUCLEO-U385RG-Q\Applications\ROT\OEMiROT_Appli_TrustZone
  • Modify the non-secure application, for instance as shown in the figure below


Figure 24 User application modification


  • Compile the code without uploading the application (don't connect to the board)
  • Through the postbuild, a new encrypted and signed binary has been automatically created: STM32Cube_FW_U3_Vx.x.x\Projects\NUCLEO-U385RG-Q\Applications\ROT\OEMiROT_Appli_TrustZone\Binary\rot_tz_ns_app_enc_sign.bin
  • In the script, type 3 to launch the upgrade menu.
Figure 25 Script menu for firmware and data update
  • Type 3 to select the NonSecure user application download.
  • The new encrypted and signed binary can be transferred in the dedicated download slot of the device using the YMODEM protocol.
  • This can be done directly using your terminal emulator as shown below for Tera Term.


Figure 26 New application image transfer into the device download slot
  • If applicable, other new generated images can also be uploaded typing the corresponding number and using the previous procedure.
  • Perform a reset pushing the black button of the Nucleo board.
  • The modified user application is executed (#B).

A new application has been installed without requiring a regression, the device has been kept in RDP2

Figure 27 New installed user application execution

7.4. Regresssion↑

  • The debugger is deactivated since the device is in RDP2. A connection trial using CubeProgrammer will generate an error.
  • Unplug and replug the USB cable of the board to perform a hardware reset.
  • Launch the script: STM32Cube_FW_U3_Vx.x.x\Projects\NUCLEO-U385RG-Q\ROT_Provisioning\OEMiROT\regression.bat or .sh
  • Note:
    • The regression from RDP2 is possible thanks to the previously provisioned OEM key2.
    • The technical background is explained in section 3.10.1 of RM0487. Check the impact of the OEM Lock option byte (table 16 of RM)
    • The regression script is performing automatically all the needed operations to regress from RDP2 to RDP1 and in a second step from RDP1 to RDP0.
Figure 28 Launch of regression script in RDP2
  • Proceed as mentioned in the script, unplug and replug the USB cable and click to continue the script execution
  • As shown in figure above, the script is unlocking the RDP2 using the provisioned password.
  • After a successful execution, the script will end as shown below.


Figure 29 End of regression script from RDP2

8. Appendix↑

8.1. STLink firmware update↑

The Nucleo board embeds an STLink.
It is advised to have the latest STLink firmware installed on the board.

To perform the update, proceed as follows (see picture below):

  • The board must be connected with the USB STLink cable.
  • Open the STM32CubeProgrammer but don't connect the device
  • Click:
    • "Firmware upgrade"
    • Open in update mode
    • Tick "Change Type"
    • Tick "STM32Debug + VCP" (for OEmiRoT, it is advised to select the option without the Mass storage)
    • "Upgrade"
Figure 30 On-board STLink firmware upgrade


9. References↑

  1. ↑ STM32Cube_FW_U3_V1.1.0
  2. ↑ STM32CubeProgrammer



Retrieved from "https://wiki.stmicroelectronics.cn/stm32mcu/index.php?title=Security:How_to_start_with_OEMiRoT_on_STM32U3&oldid=70823"