|
Coming soon |
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 demonstrates how to configure and provision a boot path for an STiROT (ST immutable Root of Trust) with a secure and nonsecure user application initial code generation.
This initial code is modified to use two LEDs and the user button present on the discovery board.
The obtained user application is:
- In the secure user application, the blue LED blinks
- Use the user button to jump to the nonsecure user application
- In the nonsecure user application, the green LED blinks.
Read the Secure Boot STM32H5 How to Introduction article before starting the practical example described below.
For more technical details which may be useful for this getting started, check out 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 example described in this article uses boot path number 2, as shown in the figure below.
Note: This boot path includes STiROT (one boot stage, no OEMuROT), a secure user application, and a nonsecure user application.
Prerequisites
To execute the example described below, you'll need an STM32H573I-DK discovery board:
And the following tools:
- STM32CubeMx_6.9.0 or later (see STM32CubeMX ST web page)
- 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 is 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 STM32CubeMx “Access to MCU Selector”.
1. Setting up the STM32CubeMX project
Launch STM32CubeMX
- 1) Click on "Access to MCU Selector" (for this example, it's easier to enable only the needed GPIOs, so it's advised to use the MCU selector instead of the board selector).
- 2) From the "Series" column, select STM32H5, and select the device used in STM32H5-DK
- 3) Click start project
- 4) Enable TrustZone, as shown in Figure 3. (For the STiROT boot path, TrustZone needs to be enabled).
Create STM32CubeMX project:
- 1) Type the name of the project (if it doesn't already exist, the related folder will be created).
- 2) Choose a folder for the project (avoid long path).
- 3) Check that both Secure Project and Nonsecure Project checkboxes are ticked (they should be checked by default).
- 4) Select the relevant toolchain; for this example EWARM is used.
- 5) Go to File > Save Project. The project folder (if it doesn't already exist) and the STM32H5_STiROT_SLed_NSLed.ioc file will be created.
2. GPIO configuration
For this example, three GPIOs need 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 nonsecure user application code
In STM32CubeMX, select the Pinout & Configuration window:
To configure the GPIO for the blue LED:
- Click on PF4 and 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 assigns the GPIO to the secure user application code
To configure the blue user button:
- Click left on PC13 and select GPIO_Input
- Click right on PC13 and select Cortex-M33 secure. This assigns the GPIO 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
- Click on System Core and select GPIO. A summary of the newly configured settings is displayed as shown in the figure below:
3. STiROT boot path configuration
To configure the boot path (number 2 in Figure 10), proceed as follows:
- 1) Click on "Boot Path and Debug Authentication".
- 2) Click on "Select".
- 3) Select ST immutable Root of Trust (ST-iROT). TrustZone was already activated in the steps described above, (Figure 3); this selection will define 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" (in this example, there is no OEMiROT, so no second boot stage).
- 6) Click on Finish.
Note: in some STM32CubeMx versions, the Debug Authentication Configure button can't be selected before completing the STiROT boot path configuration.
When you click on "Finish", the message indicated by number 7 in Figure 10 will most likely appear.
Probably you have the message indicated in the figure above.
The default configuration file is set for a fully secure user application, so the next two figures demonstrate how to proceed.
In the Project Manager window, select "Edit Config Files", as shown in the figure below:
This automatically opens the STM32Trusted Package Creator (TPC), and the following window is displayed (Figure 12).
- 1) Deselect "Is the firmware full secure", if it is not (the rest of the configuration is valid for this example).
- 2) Click on "Generate OBKey".
Notes:
- Figure 12 above shows the path where the STiROT_Config.xml file is located. This file contains the complete settings for the STiROT.
- A default firmware execution area and download area are defined. During the provisioning stage, the download area is used to store the encrypted user application, which is decrypted by the STiROT and then installed in the execution area (refer to the STiROT_for_STM32H5 article).
- The firmware area size is the total size of the secure and nonsecure user application codes (the secure area size is indicated separately).
- The generated STiROT_Config.obk file is used during the provisioning stage to configure the STiROT in the device.
As mentioned above, for this example you don't need to make any other changes to the default configuration.
However, if you write your own code that doesn'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 13 below. There's no modification to be done in this window, but here are 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 nonsecure user applications is created.
- The IDE will also perform a post-build command to generate a single encrypted and signed binary image from these binary input files.
- Note: The abovementioned paths are updated by STM32CubeMx and must not be modified.
- Close the STM32 Trusted Package Creator
4. Debug Authentication
Refer to the Debug_Authentication_for_STM32H5_MCUs article for more details.
A (fully functional) default configuration file and related OBKey file are provided with the STM32Cube firmware.
To customize Debug Authentication, follow these steps:
- In STM32CubeMx, go to the Project Manager tab and select "Boot Path and Debug Authentication". Click the Configure button.
This launches the STM32 Trusted Package Creator (installed with STM32CubeProgrammer) and the DA_Config.xml file is automatically open .
- The "key_1_root" key is needed to reopen the device or to perform a regression. To protect your 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 nonsecure user applications. See Debug_Authentication_STM32H5_How_to_Introduction 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 now has the defined privileges to perform a regression or open the debugger, according to the set permissions.
- Click on "Generate OBkey" to generate the OBKey file that will be used during the provisioning:
- Close STM32 Trusted Package Creator
5. Initial Code Generation and Modication
- In STM32CubeMX, select Project Manager.
- Ensure "Sign Binary(ies)" is selected. With each user application code compilation using the IDE, an encrypted and signed binary file is created, containing both the secure and nonsecure user applications (compilation -> post-build command)
- Note that the start and end addresses are indicated for the secure and nonsecure applications, as defined by the STiROT configuration.
- Click on "Generate Code". If this popup message appears, follow the steps below:
- Click "Yes" to generate the code.
- If you want to enable the instruction cache, select the Pinout tab (see Figure 9, select ICache located just below the GPIO configuration).
- Open the generated user application.
Open the secure user application code
- Comment out NonSecure_Init(), used for switching to the nonsecure 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 blink with the chosen delay, showing that the secure user application is running.
If the blue user button is pushed, the jump to the nonsecure application is done via Non-Secure_Init().
- Compile the code using the IDE (Project > Rebuild all).
Note: the secure code needs to be compiled first (before the nonsecure code).
Open the nonsecure 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 blink with the chosen delay, showing that the nonsecure user application is running.
- Compile the code using the IDE (Project > Rebuild all).
For this STiROT use case, two binary files are created, as shown in Figure 21 below:
- The assembled binary code of the secure and nonsecure user applications.
- The binary code obtained after the encryption and signature of the assembled binary code. This signed and encrypted file is generated through the automatically called post-build command ("Sign Binary(ies)" ticked, as shown in Figure 16).
6. Device Provisioning
For the device provisioning the OBKey files generated previously are used 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 provisioning 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)
- As first step the script will update the option bytes accordingly
- The provisioning 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 provisioning Step 3 is the board provisioning
- Before typing any key, check the indicated boot switch position
- The STM32H5 device provisioning is executed, the configuration is stored, and the user application codes are installed
- The last Step is the product state setting, for this example the device is set in CLOSED
- After the message that the board is correctly configured, the script can be closed.
See Security:Introduction_to_Silicon_device_life_cycle and Security:Debug_Authentication articles for detail explanations.
7. Code execution
- Press the black reset button, the blue LED is blinking showing that the secure user application is executed
- Press the blue button, the green LED is blinking showing that the jump to the non-secure application has been successful and that the non-secure code is executed.
8. STM32CubeProgrammer, discovery command
- Start STM32CubeProgrammer and try to connect.
- The error message below is displayed because the device has been set in CLOSED state and the debugger can't be connected even to see the non-secure user application code.
- To reopen the debugger a Debug Authentication is needed and the opening can only be done by the owner of the root key.
The product state can be seen using the Discovery command (see figure below):
- 1) In STM32CubeProgrammer click on the shield icon
- 2) Select Debug Authentication
- 3) Click on Discover, the lifecycle CLOSED is displayed.
An example on how to reopen the debugger, view the code and attach an IDE to perform a step by step application execution is shown in the chapter 6.1 of the article :How_to_start_with_ST-iROT_on_STM32H573
9. Regression
The regression will remove the user applications and protections.
After completing a handson, if your board is not in OPEN state, it's advised to perform a regression mainly if you have regenerated the root key.
- Double click to start the regression script shown in the figure below
- The regression is performed automatically. The Debug Authentication is done using the root and using the permission defined during the STiROT configuration
- You can connect STM32CubeProgrammer and see that the debugger is again open and that the flash is fully erased.
10. Appendix
10.1. STM32CubeMX installation
To install STM32CubeMX, refer to the following link: STM32CubeMX ST web page
10.2. 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.
