How to start with ST-uRoT on STM32H573

How to start with ST-uRoT 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.

• 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

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.

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

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)

• 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.

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)

• 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. OEMiROT Step by step: Debug Authentication

2.1. Certificate chain generation

• Perform a full regression (if not already done at step 5), disconnect/reconnect the USB cable.
• Check Step 0 and do/redo Step 1.1.
• Open STM32TrustedPackageCreator, select H5 and select the DA CertifGen tab.
• The example is provided with one root, one intermediate and one LEAF key pair.
• The first certificate to generate is the ROOT certificate.
• This certificate defines the permission defined by the owner generating the certificates.
• The second certificate to generate is the intermediate certificate, chained with the ROOT certificate
• The owner for instance an OEM is defining the permission of this intermediate certificate
• The last certificate to generate is the LEAF certificate, chained with the intermediate certificate

To use the certificate chain for debug opening or regression, the LEAF certificate is used as an input for STM32CubeProgrammer (since this certificate is the last of the chain), but the permission is defined by the aggregation of all mask permissions. For instance, if the debug opening in L3 is not allowed in one of the masks of the chain, this debug opening will not be allowed (even if it is allowed in the LEAF mask). The root certificate can also be used by the owner of the root key for debug opening or regression according to the permission defined during the root certificate generation.

Certificate Chain generation (ROOT certificate) using STM32TrustedPackageCreator

• Select STM32H5 and ROOT; enter the path for the private key, the public root key and where the certificate will be stored (overwrite the default stored certificate).
• Set the permission mask for the ROOT: Setting 1 will give the permission.

• Click .

Certificate Chain generation (INTERMEDIATE certificate)

• Select INTERMEDIATE and enter the path for the private root key and the intermediate public keys.

We use one intermediate certificate for this example, but the same step can be done several times to add several intermediate certificates, each with its own key pair and permission mask.

• Set the permission mask for the INTERMEDIATE certificate.

• Click .

Information

Reminder: every added certificate of the chain can have equal or less permission than the previous certificate of the chain.

Certificate Chain generation (LEAF certificate)

• Select LEAF and enter the path for the private intermediate key and the path for the public LEAF key.

This certificate is the last of the chain.

• Set the permission mask for the LEAF certificate.

• Click 120px|middle

Information

The LEAF certificate can have equal or less permission than the intermediate certificate chained with the LEAF.

2.2. Secure Debug Opening

• Redo the exercise starting at step 3, set the “closed” state.
• Click in STM32CubeProgrammer and select “Debug Authentication”.
• Click “Discover”, and the information window will be filled.

• Enter the path for the key and the certificate (an example with a certificate chain will be shown later, in this example only a single certificate is used (ROOT)):

• Click Continue .

2.2.1. Secure Debug opening using STM32CubeProgrammer and ROOT certificate

Information

For the OEMiROT example the application code is in HDPL3. A SECURE debug opening in level 2 or in level 3 will make the secure application visible.

• Select the Secure Intrusive Debug (level 3).

• Click Execute, and the following success Message is displayed:

• Disconnect STM32CubeProgrammer.
• Now that the debug is open the secure flash memory content can be read out.

Warning

! Don’t power ON / OFF the board, it closes the debugger.

• With STM32CubeProgrammer: Connect the board.
• The secure part of the flash memory is now visible @0x0C012400.

Information

The memory mapping of the nonsecure code is detailed in Project_s.map located in: Projects\STM32H573I-DK\Applications\ROT\OEMiROT_Appli_TrustZone\EWARM\Secure\STM32H573I-DK_S\List

2.2.2. Secure Debug opening, attach IAR®, read flash content and code execution

To attach an IDE:

• Disconnect STM32CubeProgrammer.
• Open the Project.eww located in the EWARM directory:

Projects\STM32H573I-DK\Applications\ROT\OEMiROT_Appli_TrustZone\EWARM

• Select the secure Project:

• Select: Project -> Attach to running target.
• Open the main.c.
• Set a break point, the execution will stop at this point.
• Reset the board (SW reset, black button).

• Select: View Memory1 -> enter the flash memory address.
• The secure code is visible @ 0x0C012400.

2.2.3. Close the debugger through hardware reset

• Close the debug in IAR®
• Disconnect/reconnect the USB cable / A hardware reset will close the debugger again.
• Click in STM32CubeProgrammer and select “Debug Authentication”.
• Click “Discover” , and the information window is filled again, it shows that the state is closed.

2.3. Nonsecure Debug Opening

2.3.1. Nonsecure Debug opening using STM32CubeProgrammer and ROOT certificate

• Enter the path for the root private key and certificate.

• Click Continue.

Information

For the OEMiROT example the application code is in HDPL3. A NON-SECURE debug opening in level 2 or in level 3 will make the secure application invisible

• Select Nonsecure Intrusive debug (level 3).

• Click Execute and the following success Message is displayed:

• Now that the debug is open the secure flash memory content can be read out.

Warning

! Don’t power ON / OFF the board, it closes the debugger.

• Connect the board to STM32CubeProgrammer if it has not been automatically connected.
• The Nonsecure part of the flash is now visible @ 0x08018400.

Information

The memory mapping of the nonsecure code is detailed in Project_ns.map located in: Projects\STM32H573I-DK\Applications\ROT\OEMiROT_Appli_TrustZone\EWARM\NonSecure\STM32H573I-DK_NS\List

Information

If you try to read the Secure Part of the flash memory @ 0x0C012400 you have an error message:

2.3.2. Nonsecure Debug opening, attach IAR®, read flash content and code execution

To attach an IDE:

• Disconnect STM32CubeProgrammer.
• Open the Project.eww located in the EWARM.
• Select the Nonsecure project.

• Select: Project -> Attach to running target.
• Open the main.c.
• Set a break point, the execution will stop at this point.
• Select: View->Memory-> Memory1 and enter the flash address => The nonsecure code is visible @ 0x08018400.

2.3.3. Close the debugger through hardware reset

• Close the debug in IAR® .
• Disconnect/reconnect the USB cable / A hardware reset will close the debugger again.
• Click in STM32CubeProgrammer and select “Debug Authentication”.
• Click “Discover” , and the information window is filled again, it shows that the state is closed.

2.4. Partial Regression

2.4.1. Partial Regression using the LEAF key and certificate chain

• Enter the path for the leaf private key and LEAF chain certificate:

• Click Continue.

Warning

The LEAF certificate was generated without the permission of partial regression, which implies that in this step it will not be possible to do partial regression with such a LEAF certificate.

• Select Partial regression.

• Click Execute.

The partial regression has not been allowed by the LEAF mask (only a full regression allowed) and you have the following error Message:

• Click on “Discover”, and the window state is filled again.

2.4.2. Partial Regression using the root key and certificate

2.4.2.1. Partial regression ->TZ-CLOSED State

• Enter the path for the root private key and certificate.

• Click Continue.
• Select Partial regression.

• Click Execute and the following success Message is displayed:

• Disconnect from STM32CubeProgrammer.

The product is now in TZ-CLOSED.

2.4.2.2. Run the code

• Open PUTTY (or another terminal emulator).
• Select “Serial" and the COMxx port.
• Set speed to 115200.
• Data 8 bits / Parity None / Stop 1 bit
• Click Open.

• Reset the board using the SW reset button on the board.

-> Only the Boot code is displayed:

• Nonsecure code and data have been erased during partial regression.
• Debug is not possible anymore.
• New code and data can be downloaded.

2.4.2.3. Download a new application code

• Open the project OEMiROT_Appli_TrustZone.
• Select the Nonsecure project.
• Change const uint8_t UserAppId = 'A' line 61 in the main.c file to:

const uint8_t UserAppId = ‘C’; 

• Select: Project-> Rebuild all.
• Open STM32CubeProgrammer and Connect the board.
• Select the “Erasing & Programming” tab.
• Browse nonsecure encrypted code image HEX file that we previously generated in folder Application\ROT\OEMiROT_Appli_TrustZone\Binary

• Click Start Programming.
• Browse non secure encrypted data image HEX file in folder ROT_Provisioning\OEMiROT\Binary

• Click Start Programming.

Warning

!!! A partial regression erases nonsecure code and data. It is necessary to download Code AND Data to visualize new firmware in the terminal.

• Disconnect STM32CubeProgrammer.
• Open PUTTY (or another terminal emulator).
• Select “Serial" and the COMxx port.
• Set speed to 115200.
• Data 8 bits / Parity None / Stop 1 bit
• Click Open.

• Reset the board using the SW reset button on the board.
  • Boot Code and new firmware are displayed.
  • Non secure debug is possible.

Nonsecure debug:

• Disconnect STM32CubeProgrammer.
• Open the Project.eww located in the EWARM.
• Select the Nonsecure Project.

• Select: Project -> Attach to running target.
• Open the main.c.
• Set a break point, the execution will stop at this point.
• Select: View -> Memory -> Memory1 and enter the flash memory address => Non secure code is visible @ 0x08018400.

Warning

!! If code is jumping to secure code, it still works but the user cannot debug / see secure world.

2.5. Full Regression using the LEAF key and certificate

• Close the debug in IAR®
• Click in STM32CubeProgrammer and select “Debug Authentication”.
• Click “Discover”.
• Enter the path for the LEAF private key and LEAF chain certificate.

• Click Continue.
• Select Full Regression:

• Click Execute and the following success Message is displayed:

• Check with STM32CubeProgrammer that the flash memory content is well erased and that the option bytes and product state are at their default values.