Security:How to start with STiRoT on STM32H573

How to start with STiRoT on STM32H57385min

Target description

The purpose of this article is to explain step by step how to use the STM32CubeFW example provided by ST, for STiRoT, using the STM32H57 discovery board.
Based on the following description, it is straightforward to use the STiRoT example provided in the STM32CubeFW for the Nucleo-H533.

• How to use the script provided by ST and perform all the required steps.
• How to install and run the user application example which is provided.
• How to perform a regression to retrieve an empty board with initial settings.

Based on this STM32CubeFW example, additional exercises are proposed

• To generate a certificate chain.
• To reopen the debugger for product states other than OPEN
• To attach an IDE
• To perform a firmware upgrade using the bootloader

Introduction

• Start by reading the STiRoT STM32H5 How to intro article.
• For more details and to get an overview on STiRoT, read the STiRoT for STM32H5 and STiRoT articles.

Two examples are provided in the STM32Cube_FW:
One example with a secure and non secure application code, and one example with a fully secured application code (Both examples without uRoT).
The fully secured application code example is used in this "getting started".

Through this practical example you will learn:

• What STiRoT is and how to use the STM32CubeFW example which is provided.
• How to configure the STiRoT and the debug authentication for this example.
• How to generate an encrypted and signed image for the user application firmware and user data.
• What the device provisioning is and how to perform the setup of the device.
• How the user application and user data are installed.
• How to perform a debug authentication and reopen the debugger.
• How to read the installed user application firmware using the STM32CubeProgrammer
• How to attach an IDE on a running target and execute step by step, the secure user application
• How to perform a regression to retrieve an empty board
• The principle of certificate chain.

Prerequisites

• Hardware
  • STM32H573 discovery board: the STM32H573 devices have all the available security features, including the HW crypto accelerator. (Note that for the STM32H56x devices, the HW crypto is not available)
    
  • Discovery MB1677- STM32H573 (need USBC cable)

Figure 1 STM32H573 DK MB1677.png

• Required tools
  • STM32Cube_FW_H5_V1.0.0 or later
  • STM32CubeProgrammer_rev2.13.0 or more recent (with trusted package creator (TPC) selected at installation).
  • IAR Embedded Workbench^® rev 9.20.1 or later.
  • Tera Term / Putty or equivalent terminal emulator.

Information

The TPC installed together with CubeProgrammer in the bin folder located in default STM32CubeProgrammer path : C:\Program Files\STMicroelectronics\STM32Cube\STM32CubeProgrammer\bin You can pin this tool to the taskbar to simplify the "STiRoT Getting started" process :

• STM32Cube Firmware
  • Download the STM32CubeFW_H5 Cube firmware (Place it as close as possible to the C: root, to avoid long windows path)
  • A directory STM32H573I-DK is included in the “Projects” directory
  • If the STM32CubeProgrammer has not been installed in the default folder:C:\Program Files\STMicroelectronics\STM32Cube\STM32CubeProgrammer, the customized installation path needs to be updated in the environment variable: env.bat
  • Check that the selected application path is correct: for the following tutorial the STiRoT fully secured example is described => The STiROT_Appli must be active.

Figure 2: STM32Cube_FW_H5

• Check that the selected application path is correct, as shown in the figure below: for the following tutorial, the STiRoT fully secured example is described => The STiROT_Appli must be active.

Figure 3 STM32H573 env.bat

Literature

• Wiki pages:
  • STiRoT STM32H5 How to intro article.
  • STiRoT for STM32H5 article.
  • STiRoT article.
  • Debug Authentication STM32H5 How to Introduction article.
• UM2237 STM32CubeProgrammer software description
• UM2238 STM32 trusted package creator (TPC) tool software description
• AN5054 Secure programming using STM32CubeProgrammer

Step by step instructions

• The different stages to configure and use the STiRoT are based on a script provided in the STM32CubeFW (provisioning.bat)
• The following documentation is a guide through all the steps of this script, and explains how to perform each of them.

1. STiRoT and debug authentication configuration

This chapter explains how to start with the provisioning script.
It is used to first configure the STiRoT and the debug authentication.
The figure below shows where the script is located in the STM32CubeFW.

• Launch the provisioning.bat (double click) and keep it running during all the following steps

• Note: For Linux and Mac operating systems, the end users may have to change manually the attribute of .sh scripts to executable.

Figure 4 STM32H573 STiRoT provisioning.bat

1.1. STiRoT configuration

As indicated by the script, the first step is to define the appropriate STiRoT configuration and to generate the related STiROT_Config.obk file. This file will be used in a later step to configure the MCU and to set the related option bytes.

Figure 5 STM32H573 STiRoT configuration

The STiRoT configuration is based on the STiROT_Config.xml file.
A default file is provided in the STM32Cube_FW.

Figure 6 STM32ube_FW STiROT_Config_xml.png

The STiROT_Config.xml file can be opened and updated using the STM32 trusted package creator but this file can be modified using a text editor.

The following parameters can be defined in the STiROT_Config.xml

• The number of images managed (code image only, or code and data images)
• Mapping information (offset and size of each execution and download slots)
• Size of the secure area when the firmware is not fully secured.
• Product state minimum allowed
• ECDSA-256 encryption key
• ECDSA-256 authentication key
• High speed boot (240Mhz vs 64Mhz) capability
• SRAM2 erasing in case of reset activation
• SRAM2 ECC management activation

Note:
In order to mitigate the risk of attacks, some major information are duplicated between option bytes and Obkeys configuration such as sram2_ecc, sram2_rst, secure watermark, product_state.
The STiRoT does not start (reset generated) if an error is detected during the control of these information. In this case, a regression must be done before restarting the provisioning process with a correct configuration.
This does not happen if the product is used according to specifications and if the product is not subject to an attack.
To understand what happens during the boot sequence, the status provided through the discovery command of the debug authentication needs to be analyzed.
The debug authentication and discovery command launched with the STM32CubeProgrammer are explained later in this article.
The discovery command can be launched through an STM32CubeProgrammer CLI command (.\STM32_Programmer_CLI.exe -c port=swd debugauth=2)

1.1.1. STiRoT configuration file generation (STiROT_Config.obk)

To generate a customized configuration file, you must follow these steps:

1. Open the trusted package creator (TPC) and select H5 (TPC installed together with CubeProgrammer)
2. Open the Obkey tab
3. Select the STiROT_Config.xml file
4. Update the parameters (this example is for a fully secured code and data)
5. The default encryption and authentication keys can be regenerated
6. Generate the file by clicking "Generate OBkey".

The STiROT_Config.obk file is generated, and the modified parameters are saved in STiROT_Config.xml file
(Click on the picture to view it in full screen)

• For a commercial product, it is mandatory to regenerate the encryption and authentication keys.

Figure 7 STM32Cube FW STiRoT configuration

• Note: The user application is fully secured, the code is executed at 0x0C00 0000 address alias (see SECBOOTADD in RM0481)
• When the STiROT_Config.obk file generation is completed, a "Success OBKey File Generation" window is displayed.
  

Note: For multiple screen displays, this window may appear on another screen, or behind an open file (before clicking OK, trusted package creator (TPC) remains freezed)

1.2. Debug authentication configuration

• A default working configuration enabling all the DA capabilities (regression, debug opening) is provided in the STM32CubeFW. This configuration can be used for this tutorial.
• Warning: for your own application, it is mandatory to define you own custom DA configuration. For a commercial product, it is important to regenerate the debug authentication root key (key_1_root.pem, as explained in next section)
• The following sections explain how to define a custom configuration.
• Press any key in the provisioning script window. The next step is indicated: debug authentication configuration. The following section describes how to complete this step.

Figure 8 STM32H573 STiRoT DA configuration

At this step, the debug authentication will be configured and the related (DA_Config.obk) will be generated.
The DA_Config.obk is used to configure the conditions to reopen a protected device and the debugger. This file will be used in a later step to configure the MCU and to set the related option bytes.

The debug authentication configuration is based on the DA_Config.xml file used as input for the trusted package creator. A default file is provided in the STM32Cube_FW.

Figure 9 STM32H573 STiRoT DA config xml

Two files are included in the “DA\Config” directory:

• DA_Config.xml : a configuration based on certificates for the H5 crypto parts (such file is used for this tutorial)
• DA_ConfigWithPassword.xml : is not used for STiRoT (only for use cases with TrustZone^® not activated)

1.2.1. DA configuration file generation (DA_Config.obk)

To generate a customized configuration file the following steps need to be followed:

1. Open the trusted package creator and select H5 (installed through the "CubeProgrammer Installation")
2. Open the Obkey tab
3. Select the DA_Config.xml file
4. Update the parameters
5. Generate the file by clicking "Generate OBkey".

The DA_Config.obk file is generated, and the modified parameters are saved in DA_Config.xml file
(Click on the picture to view it in full screen)

Figure 10 STM32H573 STiRoT DA configuration

• Note:: The level 1 (HDPL1) is reserved for the STiRoT, a debug opening in level 1 is not allowed (even when selected in the permission mask). (see wiki article dedicated to lifecycle).
• Warning: For a commercial product, it is important to regenerate the debug authentication root key (key_1_root.pem), as the key provided in the STM32CubeFW is public. You must store it in a safe place.

1.2.2. Short explanation about the permission masks

For more information on the debug authentication and the related permission masks, refer to the: Debug Authentication for STM32H5 article.
During the previous step, the permissions to reconnect a debugger and to make a regression were chosen.
This permission mask is called the "SOC_MASK".
The SOC permissions are included in the DA_Config.obk generated file and used for the configuration stored into the device. The owner of the root key (key_1_root.pem) and the related certificate (cert_root.b64) can request these defined permissions.
It is possible to define different permissions for different users, for instance for different OEMs or final customers. Refer to debug authentication and certificate chain chapter.

• Note: If the root key is regenerated (see the "regenerate" button in the figure above), you must regenerate the root certificate (cert_root.b64) using the STM32 Trusted Package Creator, as shown in next section.

1.2.3. Regenerate the root certificate in case the root key is regenerated

• The following steps are only required if the root key (key_1_root.pem) has been regenerated.
• In the STM32 trusted package creator (TPC), select the DA CertifGen.
• Open the link to the private and public root key located in the CubeFW DA/Keys folder, as shown in the figure below.
• Select the certificate file in the CubeFW DA/Certificates folder, as shown in the figure below. A warning message is displayed, confirm you wish to overwrite the existing certificate.
• Click "Generate Certificate"

(Click on the picture to view it in full screen)

Figure 11 Root Certificate re-generation

1.3. STiRoT and DA configuration completion

• Press any key in the provisioning script window.
• The operations described in the following figure are executed by the script, completing the step1 actions

(Click on the picture to view it in full screen)

Figure 12 STM32H573 STiRoT and DA configuration completion

2. User application code and data images generation

• User application code:
  • Two user application code examples are provided in the STM32Cube_FW_H5

Figure 13 STM32Cube FW appli

• STiROT_Appli, fully secured application code (used for this tutorial)
• STiROT_Appli_Trustzone^®, secure and non-secure application code examples
• These user applications are compiled. Through a post build command called by the IDE (in our case, the IAR^TM), this binary is signed and encrypted. This is what is meant by "image creation". The post build command is using the STM32 trusted package creator (TPC), and has no consequences to the user. In the compilation window you can check that the post build is executed.
  • If a user application code binary is available, the generation of a signed and encrypted binary can be performed directly using the STM32 trusted package creator (TPC).

Figure 14 STM32Cube FW appli

• User data:
  • An example of data file is provided in the STM32Cube_FW_H5.
  • In this example, the data are for the sake of demonstration, they are intended to be read out only to show the process and have no other value. In a real case application, these data can be keys or any other secret data.
    

Figure 15 STM32Cube FW data file

2.1. STM32CubeFW providing user application code compilation

• Press any key in the provisioning script window.

Figure 16 STM32H573 STiRoT script user application code image generation

1. Open the Project.eww located in the EWARM directory
2. The settings should be correct by default, but the following points must be checked
   • Open Project -> Option -> General Options. The device and CPU core are automatically recognized (see figure below)
   • Open Project -> Option -> Build Actions. Check the path for the post build script. This script is using the env.bat where the path to the CubeProgrammer is defined.
   • Open Project -> Option -> C/C++Compiler. Check the included directories. For a Discovery board, it is: USE_STM32H73I_DK
3. Perform: Project -> Rebuild all (do not upload the code to the device using the IDE, only perform a compilation to generate the image)

Figure 17 STM32H573 STiRoT IAR^TM code compilation

The following binary files are created:

• \STM32H573I-DK\Applications\ROT\STiROT_Appli\Binary\appli.bin
• \STM32H573I-DK\Applications\ROT\STiROT_Appli\Binary\appli_enc_sign.hex

2.2. User application code encrypted and signed image generation

The previous section described the two generated binaries.
The "appli.bin" is the binary obtained by compilation of the used application code with the IDE.
The "appli_enc_sign.hex" is the signed and encrypted binary obtained by the launch of the post build command. This post build command is launched directly by the IDE and is using the STM32 trusted package creator (TPC).

This section shows how to manually perform the operations done by the post build.
An encrypted and signed binary is generated starting from a compiled binary file.
The image generation is based on the STiROT_Code_Image.xml file.

1. Open the trusted package creator (TPC) and select H5
2. Open tab ImageGen
3. Select the template for the relevant image: STiRoT_Code_Image.xml (directory: \STM32H573I-DK\ROT_Provisioning\STiROT\Image)
4. Update the default configuration if required
   • Update the version number if wanted
   • Enable the 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)
5. Launch the generation: click "Generate Image"
6. An encrypted signed file is created: \STM32H573I-DK\Applications\ROT\STiROT_Appli\Binary\appli_enc_sign.hex

(Click on the picture to view it in full screen)

Figure 18 STM32H573 STiRoT User application code image generation with TPC

2.3. User data encrypted and signed image generation

• Press any key in the provisioning script window. The script describes the last action for step 2, to be done manually

(Click on the picture to view it in full screen)

Figure 19 STM32H573 STiRoT data image

• During step 1.1, the configuration firmware and data image were selected (see figure 7)
• The data file provided as an example contains meaningless data. These data are read back and displayed when the application code is executed.

An encrypted and signed binary is generated starting from the provided example data binary file
The image generation is based on the STiROT_Data_Image.xml file.

1. Open the trusted package creator (TPC) and select H5
2. Open tab ImageGen
3. Select the template for the relevant image: STiRoT_Data_Image.xml (STiRoT directory)
4. Update the default configuration if required
   • Update the version number
   • Enable the dependency with the other (code) image when simultaneous installation is required for compatibility reasons.
   • Select the binary file to be used as an input file
   • Select the output file to be filled with the signed and encrypted binary (hex format)
5. Launch the generation: click on "Generate Image"
6. An encrypted signed file is created: \STM32H573I-DK\ROT_Provisioning\STiROT\Binary\data_enc_sign.hex

Figure 20 STM32H573 data image generation with TPC

3. Device provisioning, code and data image download into flash, product state setting

During this step:

• The option bytes are programmed into the STM32H573 Discovery board device
• The encrypted and signed user application code and data images are flashed into the device
• The final product status is chosen
• For a user, the STiRoT is executed as a "black box". If the previous steps have been correctly followed, the device provisioning and boot are straightforward. In case of an issue, the status provided through the discovery command of the debug authentication must be analyzed. Details about the discovery status commands are available in following article appendix STiROT for STM32H5 execution status

3.1. Device programming using the script

• Press any key in the provisioning script window.
• The previously generated option byte files are used by the script to program the option bytes accordingly.
• The user application code and user data are flashed into the device.
• The selected product state is typed in the script.
  • If no text is entered, the device stays in open state.
  • Select the open state during the development phase. In this product status, modifications can be done without performing any regression.
  • !! Locked is a final product stage that can no longer be changed, the embedded FW and product configuration cannot be modified by any method anymore.
• Press any key in the provisioning script window.
• This finalizes the device configuration.

Figure 21 STM32H573 device provisioning, user application and data images flashing, final product state setting

3.2. Some explanations about the images flashing

The figure shows the operations done by the STiRoT

• The encrypted user application code is written in the download area
• After authenticity and integrity verifications, the user application code is decrypted and written in the user flash execution area
• The encrypted data are written in the download area
• The data authenticity and integrity are verified. Then, the data are decrypted and re-encrypted with the derived hardware unique key (DHUK) and stored in the secure storage area (OB keys area)

Figure 22 STM32H5 STiRoT user application and data images flashing

4. Execution of the installed user application

• Open Tera Term (or another terminal emulator)
• Select “ Serial” and the COMxx port
• Setup -> Serial port …
• Set speed to 115200 and data to 8 bit
• Click: New Setting

Figure 23 Tera term setting

• Reset the board (black reset button)
  • The code installed during the previous steps is executed

Figure 24 STiRoT user application execution

• The menu 1 launches the standard bootloader located in the system flash. At next reset, the STiRoT decrypts and installs the new versions of the user application and user data images, after a successful check of the authenticity and the integrity of each image.
• The menu 2 displays the first 32 bytes of the data.bin file, as shown in figure above.

• Note: About the menu launching the bootloader: if the device is set in a state other than open, the connection is not possible through ST-LINK as a debug authentication is needed (this is explained in the next chapters). It is possible to connect the device only through the CubeProgrammer (e.g. USB DFU).

• Disconnect the Tera Term as it is not needed for the next steps.

4.1. Product in open state and user application code modification

If the device is in open product state, the application code can be modified and re-flashed without any specific debug opening procedure.
Note: In a real case development phase, refer to the appendix section 8.1 of the STiRoT introduction article STiRoT for STM32H5 Application development phase

To make a modification of the user application code, proceed as follows:

• Start the IDE (e.g IAR^TM)
• Select: Project -> Attach it to running target
• Set a break point
• Click on the reset button on the board (black reset button)
• The code execution stops at break point.
• Make a modification, for instance in a printf.
• Rebuild the user application code, the post build command is launched and the new signed and encrypted image is generated.
• There are different solutions to upload the new code image for this tutorial example. (The code is installed by the STiRoT at next hardware reset)
  • Through the bootloader as shown in next section
  • By manually flashing the new image in the download area
  • The simplest way is to rerun the provisioning script (no need to perform a regression)

Note: When no further modification is done, other than the user application code, the STiROT_Config.obk and STiROT_Config.obk have no need to be regenerated, the script can be run through. In case of any doubt, follow the steps indicated in the provisioning script.

4.2. Product in a state other than open, using the bootloader to flash a new user application image

If the device is not in open state (as in this tutorial)

• A debug authentication is required to connect a debugger or an IDE on the running target
  • How to reopen the debug under some specific conditions, is explained in chapter 6.
  • An example of firmware update using the Bootloader is shown in section 6.5
• It is possible to upload a new firmware/data image(s) using the bootloader without opening the debugger:
  • The prerequisite is that the STiRoT and DA configuration have not changed since the previous provisioning. In addition, the authentication and encryption keys must not have been regenerated. (Otherwise a regression and new provisioning are required)
  • Perform the following steps
    • Open the user application code using the IDE
    • Modify the code and compile it. The encrypted image is generated through the post build.
    • Connect the Tera Term and execute the application as described at the beginning of this chapter (see figure 23)
    • Selecting "1" in the menu launches the bootloader
    • Disconnect Tera Term (this is advised but only needed if a UART connection is used), and launch the STM32CubeProgrammer
    • Upload the new image. This new encrypted image is flashed in the download user flash area (see figure 22)
    • Disconnect the STM32CubeProgrammer
    • Perform a hardware reset (black button). This action launches the STiRoT. The STiRoT detects a new image is available and installs it.
    • Connect Tera Term. After a reset, the new installed user application is executed.

5. Full regression

This chapter explains how to perform a full regression of the device. The STiRoT CubeFW example used in this "getting started" is for a fully secured user application code. A partial regression removing all the non secure code and data is pointless. The opening of the debug, to access the secure user application code, is explained in the debug authentication chapter.

As mentioned, if the device is in open state, there is no need to perform a regression. A new provisioning of option bytes and image flashing can be done using the script. If a regression trial is done, it is no longer be executed and an error message is displayed. For all the other product states, a regression is needed to make any change in the STiRoT configuration, in the user code or for the data.

• A full regression erases the user stored content and secrets.
  • Erase the OB keys.
  • Erase the complete user flash content.
  • Erase the data of the secure storage (HDPL1 to HDPL3)
  • Reset the secure option bytes to their default value.
  • Set the product in open state.

5.1. Full regression using script (included in the STM32CubeFW)

There are two ways to perform a full regression

• Using the script provided in the STM32CubeFW, or
• Using the CubeProgrammer (explained in next section)

The figure below shows where to find the regression script:

Figure 25 STM32H5 regression script

• To perform a full regression:
  • Launch the regression script (double click)
  • Note: For Linux and Mac operating systems, the end users may have to change manually the attribute of .sh scripts to executable.
  • Answer “Y” to the question “The TrustZone^® feature is enabled?”
  • A regression success confirmation message is displayed in the script.

Figure 26 regression completed

• When connecting the STM32CubeProgrammer, the user flash is sometimes erased and the product is back in open state.

5.2. Full regression using the STM32CubeProgrammer

Instead of using the script as described in previous section, STM32CubeProgrammer can be used as shown below:

• Disconnect the STM32CubeProgrammer, remove/plug the USB cable.
• Rerun the provisioning script and set the product state to "closed"
• Open the STM32CubeProgrammer and select “debug authentication”
• Click “discover”. The information window is automatically filled in and shows that the device is in closed state.
• Enter the path for the root key and the root certificate.

(Click on the picture to view it in full screen)

Figure 27 STM32CubeProgrammer key and certificate selection

• Click Continue
• Select "Full Regression" and click "Execute"

Figure 28 Full regression using STM32CubeProgrammer

• When connecting the STM32CubeProgrammer, the user flash can get erased and the product is back in open state.

This ends the first part of this tutorial on how to use the provided STM32CubeFW example.
Based on this example, you can proceed with further exercises described in next sections.
You'll find the processes to reopen the debugger, attach an IDE, perform a firmware upgrade, to generate and use a certificate chain.

6. Debug authentication

Two methods exists to perform a regression or a debug opening in a secure way. This is ensured by the debug authentication.
Two cases:

• When the Trust Zone is disabled: only a regression is possible. This is done using a password.
• When the Trust Zone is enabled: unless a product is in locked state, the user can perform a regression or a debug opening, if he has the right key, certificate and related permission.

For an STiRoT use case, the TrustZone^® is implicitly enabled, a key and related certificate are used
The permission of the root key and root certificate owner are defined during the debug authentication configuration (see section 1.2). The permission to make a full regression was used in last section.

For detail explanations about the debug authentication, refer to following articles:

• Debug Authentication for STM32H5
• Debug Authentication STM32H5 How to Introduction

The owner of the root key and root certificate can use the permissions defined during the debug authentication configuration (see figure 10).

6.1. Debug opening using the STM32CubeProgrammer and ROOT certificate

To perform an intrusive debug opening and to read the flash content using the STM32CubeProgrammer, proceed as follows:

• A full regression must have been done previously. If it is not the case, start by running a full regression.
• Redo the previous steps 1 to 3 and set the device in "closed" state.
• STM32CubeProgrammer: select “debug authentication”.
• Click on “Discover” the ST_LIFECYCLE_CLOSED is displayed in the information window.
• Enter the path for the root private key and root certificate
• Click "Continue"

Figure 29 STM32H573 debug opening

• Select "intrusive debug level2" (for the STM32CubeFW STiRoT example, the secure user application is executed in HDPL2)
• Click "execute"

Figure 30 STM32H5 Intrusive Debug

• The debug is open and the flash content can be read out.
• ! The debug remains open as long as you do not perform a power-on reset.
• Reset the board (HW reset), use the black button of the discovery board.
• On the STM32CubeProgrammer, click "connect", (crosscheck: access port 1; Hot plug).
• The flash content is now visible.

Figure 31 STM323H573 Debug Opening, STM32CubeProgrammer connection

6.1.1. IDE attachment, read flash content, user application code execution with break point and code modification

6.1.1.1. Attach an IDE and read device memory content

• Disconnect the STM32CubeProgrammer
• Open the IDE
• Reset the board (HW reset), use the black button on the discovery board. To reopen the secure code, this must be executed.
• If IAR^TM is used:
  • Select: Project -> attach to running target.
  • Select: View Memory1 -> enter the flash address => the flash content is visible.

Figure 32 STM32H573 Debug opening, connect IAR

6.1.1.2. Execute the user application and set a break point

• Open the main.c
• Set a break point, perform a hardware reset (discovery board black button), the execution stops at the break point, and the assembler code becomes visible.

(Click on the picture to view it in full screen)

Figure 33 Attach IAR^TM, user application execution stops at break point

6.1.1.3. User application modification and new compilation

It is possible to directly update the code and compile it using the IDE to generate a new image.
As the device is set in a state other than open, this modified user application cannot be uploaded directly using the IDE.
It needs an encrypted and signed image (see section 2.1 and 2.2) to be uploaded in the download area (see section 3.2).
The authentication and encryption keys defined during the STiRoT configuration (see section 1.1.1) must be used.
The STiRoT does not install a firmware if the image has not been encrypted and signed with the provisioned keys.
How to upload and install a new user application code image is described in chapter 6.5.

To modify the user application and generate a new image, proceed as follows:

• Make a modification in the code; for instance add “test” in one printf as shown in the figure below.
• Recompile the application. A new code image is automatically generated through the post build command.
• Close IAR^TM

Figure 34 IAR^TM attached, user application code modification

6.1.2. Close the debugger performing a power-on reset

• In the STM323CubeProgrammer, click on "discover", the lifecycle indicates that the debug is still open.
• Disconnect/reconnect the USB cable. A power-on reset closes the debugger again.
• Click again on "discover", the indicated lifecycle is "closed".

6.1.3. Upload the new image using the bootloader

• Connect the Tera Term and execute the application that was installed previously.
• Select "1" in the menu to launch the bootloader.

Figure 35 STiRoT user application execution, bootloader launch

• Disconnect Tera Term (this is recommended only if the UART connection is used) and launch the STM32CubeProgrammer.
• Connect the board via UART on the STM32CubeProgrammer without performing any reset or power OFF power ON (do not disconnect the board from your laptop).

Figure 36 Connect through UART

• In the STM32CubeProgrammer, select the “Erasing & Programming” tab.
• Click on "Browse" and select the path location of the new encrypted and signed user application code.

Figure 37 Select path for new encrypted and signed image

• Click on Start Programming.
• Disconnect the STM32CubeProgrammer.
• Perform a HW reset (use the black button). The STiRoT is executed, it detects a new image in the download area and installs it (after an authentication and integrity verification)
• Connect the Tera Term
• Reset the board (use the black button). The new application is executed and displayed by the Tera Term.

Figure 38 STM32H573 modified code execution

6.2. How to generate a certificate chain

The previous sections explained how to use the configured permissions for the owner of the root key and the root certificate.
Giving different permissions to an OEM or to the field is feasible using a certificate chain.

This section explains how to generate a certificate chain using the STM32 trusted package creator (TPC).

6.2.1. Root certificate

• Select STM32H5 and root.
• Enter the path to the private key, to the public root key and to certificate storage area (overwrite the default stored certificate).
• Set the permission mask for the root certificate. Enter "1" to give permission.

The STiRoT example described in this tutorial is for a fully secured user application code. For the non secure debug, this is not applicable (no difference if selected or not)

• Click on "Generate Certificate".

(Click on the picture to view it in full screen)

Figure 39 STM32H573 certificate chain, root

Note:

• Permissions set as not allowed for the SOC mask (see section 1.2 and figure 10) are also not allowed using this new root certificate. (Even if the new certificate has set it as allowed).

6.2.2. Intermediate certificate

The owner of the root key defines the permission for the owner of the intermediate key.

• The owner of the root key receives the public key of the intermediate.
• The owner of the root key generates the intermediate certificate the following way:
  • Select INTERMEDIATE and enter the path for the private root key and the intermediate public keys
  • Set the permission mask for the INTERMEDIATE certificate
  • Enter the path to the root certification (cert_root.b64)
  • Enter the path to the intermediate certificate for replace (cert_intermediate.b64)
  • Click on "Generate Certificate".

Figure 40 STM32H573 certificate chain, intermediate

Note:

• Every permission set, as not allowed for the SOC mask or not allowed for the root certificate, is also not allowed for the intermediate certificate, even if the intermediate certificate set it as allowed. In other words, a certificate in the chain can only define an identical or lesser permission than the previous certificate of the chain.

In this tutorial, one intermediate certificate is used. But the same steps can be repeated several times to add several intermediate certificates, each with their own key pair and permission mask.

6.2.3. Leaf certificate

The principle is that the owner of an intermediate private key defines the permission for the owner of the private leaf key.

• The owner of the intermediate private key receives the public key of the leaf.
• The owner of the intermediate private key generates the leaf certificate, the following way:
  • Select leaf and enter the path for the private intermediate key and for the public leaf key
  • Set the permission mask for the leaf certificate
  • Click on "Generate Certificate".

Figure 41 STM32H573 certificate chain, leaf

Note:

• The leaf certificate can have an identical or lesser permission than the intermediate certificate chained with the LEAF. In other words, the permission of the leaf certificate is the result of the permission of all the masks (if one permission is not allowed in one of the mask it is also not allowed for the leaf certificate).
• This certificate is the last of the certificate chain

A debug authentication can be performed using the root certificate and related private key (as shown in section 6.1) or using the leaf certificate and related private key (as shown in next section).

6.3. Full regression using the leaf key and certificate chain

The goal of this last part is to show that the owner of the leaf private key and related certificate can only perform a full regression as defined during the certificate chain configuration.

• Select “debug authentication” in the STM32CubeProgrammer.
• Click on “discover”. The information window is filled.
• Enter the path for the leaf private key and leaf chain certificate.
• Click "Continue".

Figure 42 STM32H573 regression using the leaf certificate

• Select partial regression -> click on "execute".
• Reminder: the permission is the aggregation of the complete certification chain, so the least permission (for instance, if the partial regression is not allowed in one of the mask of the certificates chain, the partial regression is not performed, and an error message is displayed (even if the leaf certificate allows it)
• An error message is displayed since the partial regression is not set as allowed by the leaf mask during the certificate chain generation (only a full regression is allowed) (see figure below)

Figure 43 STM32H573 leaf partial regression not allowed

• Select full regression -> click on "execute".
• The STM32CubeProgrammer shows that the user flash is erased and that the device is set back in "open" state.

• Note: A regression is not possible any longer if the regenerated key(s) or certificate are lost. It is thus recommended to make a full regression after completion of a tutorial.