Coming soon |
Version for review planed for wk18
Target description
The purpose of this article is to explain how to proceed step by step to generate a boot path using STM32CubeMx.
The example below will show how to configure and provision a boot path for an STiROT (ST Immutable Root of Trust) with a secure and non-secure user application initial code generation.
This initial code is modified to use two leds and the user button presents on the discovery board.
The obtained user application is:
- Blinking the bue led in the secure user application
- Use the user button to jump in the non-secure user application
- Blinking the green led in the non-secure user application
Read the Secure Boot STM32H5 How to Introduction article before starting the practical example described below.
More technical details you may need to understand this getting started are available in the following articles:
- Introduction article: Introduction to Secure boot and Secure firmware update.
- Specific STM32H5 bootpaths article: Secure Boot for STM32H5
- STiROT article STiROT for STM32H5
The How to start described in this article is using the Boot path number 2 of the figure below.
Prerequisites
To execute the example described below, you need:
- Discovery board: STM32H573I-DK|
- The following tools:
- STM32CubeMx_6.9.0 or later (for installation, see appendix)
- IAR Embedded Workbench rev 9.20.1 or later
- STM32CubeProgrammer rev 2.13.0
Note:
- STM32 Trusted Package Creator (TPC) is automatically installed during the STM32CubeMX installation. This TPC version dedicated to STM32CubeMX and installed in the STM32CubeMX/utilities folder.
- The latest STM32Cube_FW revision is installed through STM32CubeMX (see appendix)
- If needed set the windows environment variable (see appendix). It is required in case the H5 doesn’t appear in the “Access to MCU Selector” of STM32CubeMx
1. Setting the STM32CubeMX project
Launch STM32CubeMX
- 1) Click on Access to MCU selector (easier for this example to enable only the needed GPIOs, so it's advised to use the MCU selector instead of the board selector).
- 2) Select STM32H5 serie and select the device used in STM32H5-DK
- 3) Click start project
- 4) Enable the TrustZone, as shown in the figure 1, for the STiROT bootpath the TZ needs to be enabled.
Set the STM32CubeMX project:
- 1) Type the name of the project (the related folder will be created)
- 2) Chose the folder for this project (avoid long path)
- 3) Tick both: Secure and non Secure projects
- 4) Select the Toolchain, for this example EWARN is used
- 5) File -> Save Project -> the project folder (if not already existing) and the STM32H5_STiROT_SLed_NSLed.ioc file is created
2. Configure the STiROT bootpath
To configure the bootpath number 2 of the figure 1 proceed as follow:
- 1) Click on "Boot path Configuration"
- 2) Click on "Select"
- 3) Select the STiROT. The TZ activation has already been chosen (figure2), this selection is defining the UBE option byte (figure1) (but you don't need to take care about the setting of this option byte).
- 4) Click on "Next"
- 5) Select Secure Application (since for this example there is no OEMuROT, so no second boot stage)
- 6) Click Finish
Probably you have the message indicated in the figure above.
The default configuration file is set for a full secure user application, the next two figures show how to proceed.
In the Project Manager window, select Edit Config, as shown in the figure below.
It will automatically open STM32Trusted Package Creator (TPC).
And the following window is displayed.
- 1) Deselect "Is the firmware fulll secure" in case it was not the case, (the rest of the configuration is valid for this example)
- 2) Generate the OBKey file
Notes:
- The figure above, shows the path where the STiROT_Config.xml file is located. This file contains the complete setting for the STiROT.
- A default firmware execution and download area is defined. During the provisioning the donwload area is used to store the encryped user application, that is decrypted by the STiROT and installed in the execution area (refer to the STiROT_for_STM32H5 article).
- The firmware area size is the total size of the secure and non secure user application codes (the secure area size is indicated separately)
- The generated STiROT_Config.obk is used during the provisioning to configure the STiROT in the device.
As mentioned above, for this example you don't need to make any other updates of the default configuration.
But if you make your own code that don't fit in these defined sizes, you will need to redo the configuration and regenerate the OBKey when the final code size is defined.
To protect your code, you need to regenerate the encryption and authentication keys.
Select H5-Image Gen1 as shown in figure below
No modification to be done in this window, just some explanations:
- The STiROT_Code_Image.xml file contains the settings needed to generate the images.
- Two paths are indicated for binary files:
- During the code compilation using the IDE, a binary file containing the compiled secure and non-secure user application is created.
- The IDE will also perform a postbuild command to generate from this binary input file an encrypted and signed binary image.
- Close STM32 Trusted Package Creator
3. Debug Authentication
Refer to the Debug_Authentication_for_STM32H5_MCUs article for more details
Next version of STM32CubeMX will support the Debug Authentication setting.
But the DA default configuration provided in the example is fully functional.
- Launch the STM32Trusted Package Creator (the one installed together with STM32CubeProgrammer, not the application included in STM32CubeMX)
- Select the path for the DA_Config.xml.
- The "key_1_root" key is needed to reopen the device or to perform a regression. To protect you own developed application, this key needs to be regenerated. If regenerated, it's important to not lose this new key.
- Don't regenerate the key for this example
- The permission mask is set to allow all possible regressions and debug openings in the secure and non-secure user application. See Debug_Authentication_STM32H5_How_to_Introduction article for more details. This permission mask, called the SOC mask is stored in the device during the provisioning process. The owner of the root key has then the defined privileges to perform a regression or open the debugger.
- Generate the OBKey file that will be used during the provisioning, click:
4. GPIO configuration
For this proposed example three GPIO needs to be configured for the discovery board:
- PF4 for the blue LED used in the secure user application code
- PC13 for the blue user button used in the secure user application code
- PI9 for the green LED used in the non-secure user application code
In the STM32CubeMX select the Pinout & Configuration window
To configure the GPIO for the blue LED proceed as follow:
- Click left on PF4: select GPIO_Output -> a push pull output will be configured need to drive an LED
- Click right on PF4: and select Cortex-M33 secure. This GPIO is then assigned to the secure user application code
To configure the user bue button proceed as follow:
- Click left on PC13: select GPIO_Input
- Click right on PC13: and select Cortex-M33 secure. This GPIO is then assigned to the secure user application code
To configure the GPIO for the green LED proceed as follow:
- Click left on PI9: select GPIO_Output -> a push pull output will be configured need to drive an LED
- Click right on PI9: and select Cortex-M33 non-secure. This GPIO is then assigned to the non-secure user application code
- Select GPIO: the summary of the settings are displayed as shown in the figure below
5. Initial Code Generation and modication
Select Project Manager in STM32CubeMX
- Select Sign Binaries -> at each user application code compilation using the IDE an encrypted and signed binary is created containing bot secure and non secure user application (compilation -> postbuild commanf)
- Note that start and end address are indicated for the secure and non-secure according to the STiROT configuration
- Click Generate Code
- Open generated initial generated user application
Open the secure user application code
- Comment out NonSecure_Init() for the jump into the non secure user application code (replaced with the code below).
- Insert the following code as shown in the figure below
HAL_GPIO_TogglePin(GPIOF,GPIO_PIN_4);
HAL_Delay(500);
if (HAL_GPIO_ReadPin(GPIOC,GPIO_PIN_13) == 0x1)
{
NonSecure_Init();
}
This code will make the blue LED blinking with the chosen Delay, showing that the secure user application is executed.
If the user blue button is pushed the jump in the non secure code is done through the Non-Secure_Init .
- Compile the code using the IDE (Project -> Rebuild all).
- Note: the secure code need to be compiled first (before the non-secure code)
Open the non-secure user application
- Insert the following code as shown in the figure below
HAL_GPIO_TogglePin(GPIOI,GPIO_PIN_9);
HAL_Delay(800);
This code will make the geen LED blinking with the chosen Delay, showing that the non-secure user application is executed.
- Compile the code using the IDE (Project -> Rebuild all).
Two binaries are created as shown in the figure below.
- The assembled binary of the secure and non-secure user application
- The binary obtained after encryption and signature of the assembled binary. The signed and encrypted file is generated through the automatically called postbuild command (select in the window figure 13).
6. Device Provisioning
For the device provisioning the OBKey files generated previously are user to configure the device STiROT accordingly and to configure the Debug Authentication according to the permission mask.
The encrypted and signed binary is uploaded in the download area defined during the STiROT configuration.
The STiROT verifies the authenticity, decrypt and install the secure and non-secure user applications in the execution area defined during the STiROT configuration.
For the provisioning STM32CubeProgrammer Command Line (CLI) are called automatically by the provisioning script.
It's important that the path to the STM32CubeProgrammer is correct in the env.bat file. Check and update as shown in the figure below:
! Don't modify the path to the STM32TrustedPackageCreator included in the STM32CubeMX.
The provisioning of the device is done using the provided provisioning script.
- Connect your board with the USB cable (USB STLink connector)
- Double click on the provisioning.bat shown in the figure below
- The Step 1 is the configuration
- The STiROT configuration setting done previously (generation of the related STiRoT_Config.obk file)
- The DA configuration setting done previously (generation of the related DA_Config.obk file)
- The Step 2 is the image generation
- The user application code image generation has been done previously during the compilation and the postbuild.
- The image generation is not applicable for this example -> type any key
- The Step 3 is the provisioning of the STM32H5 device
- Before typing any key, check the indicated boot switch position
- The provisioning is executed, the board configuration is done and the user application codes are installed
- The last Step is the product state setting
7. Appendix
7.1. STM32CubeFW installation
The STM32CubeFW needs to be installed through STM32CubeMX.
- Step 1: the repository folder has to be defined:
- In STM32CubeMx: Help menu -> Updater Settings
- Browse the repository you have chosen for the STM32CubeFW
- Step 2: STM32CubeFW installation
- In STM32CubeMX: Select Install/Remove
- In the description frame: select STM32H5
- Select the CubeFW package to install
- In case you have locally the zip file of the STM32CubeFWH5: it can be installed by drag and drop this file in the description window
Note: only official STM32CubeFW release can be installed by STM32CubeMX.