How to start with Secure Manager (customized configuration) on STM32H5


This article guides STM32H573 users on their first steps with Secure Manager. Refer to the article Introduction to Secure Manager for further details on what Secure Manager is and what are the benefits of using it.

1. Introduction

See following reference articles to understand the Secure Manager concept:

This article describes how to get started with the Secure Manager Access Kit (SMAK). It details the package and provides a step-by-step guide on Secure Manager installation, customization and usage.

There are two ways to install the Secure Manager:

  • Running a script that installs the Secure Manager with ST defaults parameters. Refer to this wiki page for more information.
  • Running a script that guides the user through all the user configurable parameters of the Secure Manager.

The following part will focus on customization during the Secure Manager installation.

For any .bat scripts referred in the below sections, an equivalent .sh script version is available. The user can indifferently use the .bat or the .sh script version, depending on the OS environment.

2. Prerequisites

  • Hardware
    • STM32H573 discovery board: The STM32H573 devices have all the available security features, including the HardWare cryptographic accelerator. (Note: the Secure Manager is not supported on STM32H56x devices, the HW crypto is not available)
    • USB-C cable to connect Discovery MB1677- STM32H573
Figure 1 STM32H573-DK MB1677.png


  • Required tools
    • STM32Cube_H5_V1.2.0.
    • X-Cube-SEC-M-H5_V1.1.2 available upon request. It contains the Secure Manager binary.
    • STM32CubeProgrammer_2.16.0 including RSSe v2.0.1.0 (with STM32TrustedPackageCreator (TPC) selected at installation).
    • One of the supported IDE:
      • EWARM (IAR) : V9.20.1 and the patch EWARMv9_STM32H5xx_V1.1.1 or later to support the STM32H5 series
      • STM32CubeIDE : 1.15.0
      • MDK_ARM : V5.38.0.0 and the patch Keil_STM32H5_DFP.1.3.1 to support the STM32H5 series
    • Tera Term / Putty or equivalent UART terminal emulator.

These IDE patches can be found in the STM32CubeFW_H5 Cube firmware:

Figure 2 IDE patches in STM32CubeH5 Firmware Package
  • STM32Cube Firmware
    • Download the STM32 Cube Firmware H5.
    • Download the X-Cube Secure Manager expansion package and copy at the root of the STM32 Cube Firmware H5.
    • 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 (see the example in the figure below).
Error creating thumbnail: File missing
Figure 3 STM32CubeProgrammer installation path to update in env.bat file
Warning DB.png Important
If you want to use the X-Cube-SEC-M-H5_V1.1.1, you need to download the STM32Cube_FW_H5_V1.1.0 and the STM32Cube_FW_H5_V1.1.1 patch. All the files of the Cube patch V1.1.1 must be copy into the Cube V1.1.0.

Warning: The package X-Cube-SEC-M_H5_V1.1.1 is compatible only with STM32CubeProgrammer v2.14.

3. Package contents

In the STM32CubeH5 package, the folder ROT_Provisioning contains all the necessary files to install the Secure Manager.

Figure 4 High level overview of the package structure

Below, the detail of relevant directories to install and use the Secure Manager:

Figure 5 First part of the package structure of the STM32CubeH5
Figure 6 Second part of the package structure of the STM32CubeH5
Item Directory/Script name Description
1 Drivers SMAK is using drivers as any other STM32Cube app
2 secure_manager_api Secure Manager API used by SMAK project to call Secure services (PSA)
3 SMAK Appli Example of nonsecure application project compatible with Secure Manager
4 download.bat Script to download via STM32CubeProgrammer the nonsecure image in download slot
5 DA Debug Authentication, including script to perform full regression
6 Binary Secure Manager binaries used for installation
7 Config *.xml file to configure Secure Manager for installation
8 Helper Internal scripts used during Secure Manager installation, nonsecure application build
9 Images Generic *.xml file used to generate nonsecure application
10 Keys OEM Keys used during Secure Manager installation
11 License Module with global license example used during Secure Manager installation
12 its_blob Script to create a blob for ITS factory feature
13 provisioning Script to configure and install Secure Manager
14 provisioning_auto Script to install Secure Manager with the default configuration
15 SMAK_Appli Nonsecure application project template compatible with Secure Manager
16 Certificates Utilities used to get a certificate X509
17 ITSbuilder Utilities used to provision initial secure key and data in secure storage during the Secure Manager installation
18 ROT_AppliConfig Utilities used to update projects and configuration files
Warning DB.png Important
If the secure manager package V1.0.0 is installed, it is possible to update this version with both Secure Manager Core and STuRoT binaries in the folder ROT_Provisioning/SM/Binary :
  • SecureManagerCore_PROD_FWU_v1.1.0.bin
  • STuRoT_FWU_v1.1.1.bin

Follow the Firmware Update (FWU) example with selecting the Secure Manager and STuRoT menu.

Both components must be updated to be compliant with the supported configuration.

4. Script provisioning.bat step 1: Configuration

This section details the customization of the Secure Manager installation.
For more information on each configuration item, refer to Secure Manager configuration section in SMAK for STM32H5.

The configuration steps described below are based on the provisioning.bat script execution for the STM32H573I-DK Discovery kit in the STM32CubeH5 Package.

Figure 7 Secure Manager installation script

Note:
In the figure above two scripts are shown:
- The provisioning_auto.bat to install the default configuration (used in the article).
- The provisioning.bat to customize the configuration (used in this article).

First :

  • Connect the STM32H573-DK using the USB-C cable.
  • Execute the provisioning.bat script.

4.1. General configuration

This step allows the user to configure various general configuration items of the system. If this part has no need to be updated (ST default configuration), the user can press any key on the script provisioning.bat to skip this part and go to the next step SM Keys configuration.

The following table lists the general configuration parameters that can be changed:

Parameter Description Default Value Possible Value
Authentication of Modules with license Type of authentication for module with license (third party module with or without counting installation). Other modules are not concerned by this setting. 0xbd 0xbd: Modules with license are not signed by OEM.
0xce: Modules with license are signed by OEM.
Flash Layout configuration Index Predefined flash layout configuration 0x0 0x0: no module.
0x1: one module.
Note: configuration details are described below.
SRAM Secure/NonSecure interface area size Size of the shared SRAM area between the nonsecure and the secure. This area is located at the end of the SRAM1 and is used to communicate data. 0x10 (16kB) Minimum 4KB
Maximum 248KB
with a granularity of 1kB.
Secure SRAM End address End address of the SRAM3 allocated to Secure Manager and module. The remaining area of the SRAM3 is allocated to nonsecure application 0x30068fff: 24KB allocated to module (if any) 0x30062fff: Minimum value, for Secure Manager only (no SRAM allocated to the module)
0x30069fff: Maximum value (End address of the SRAM3); with a granularity of 4kB.
NS reserved area size Area reserved to the nonsecure application (for example: NV data, filesystem). This area reduces by half of the value the available size for nonsecure application. 0kB: No NS reserved area Minimum 0KB
Maximum 512kB
with a granularity of 16kB.
Jump into ST bootloader when no valid SecureManager / Module / NS application Authorized the STuRoT (second boot stage) to jump into the ST bootloader when the authenticity and the integrity is not verified of at least one image Enabled Enabled
Disabled

Below, the detail of the predefined flash layout configuration:

Figure 8 predefined Flash mappings


To proceed with the configuration, open the STM32TrustedPackageCreator tool:

Figure 9 Steps to configure the general memory configuration of the Secure Manager

4.2. SM Keys configuration

This step allows to customize the SM authentication and encryption keys. These keys are used for the nonsecure application image and for OEM module image (if any). These keys are located in the folder Projects\STM32H573I-DK\ROT_Provisioning\SM\Keys. The user can press any key on the script provisioning.bat to skip this part and go to the next step Other configuration.

Warning white.png Warning
In production phase, the OEM must not use the default SM keys from ST.


In the STM32TrustedPackageCreator tool:

Figure 10 Steps to regenerate the default SM keys used for the nonsecure application

4.3. Other configuration

The user can press any key in the script provisioning.bat to skip this part and go to the next step Debug authentication (DA) configuration.
This step allows to customize the following parameters:

Parameters Description Default Value Possible Value
Clock configuration Configuration of the clock during the Secure Manager initialization (including the boot stage) 0x2 0x0: 64Mhz
0x1: 200Mhz
0x2: 250MHz
Jump into ST bootloader when no valid STuRoT Enable the STiRoT (first boot stage) to jump into the ST bootloader when the authenticity and the integrity of the STuRoT image (second boot stage) is not verified Enabled Enabled
Disabled
Minimal Product State The boot stage will execute the application only if the product state programmed is equal or greater to this value 0x0000c600: TZ-Closed 0x0000c600: TZ-Closed
0x00007200: Closed
0x00005C00: Locked
Warning white.png Warning
The Minimal product state must be configured in compliance with the configured product state (see Option Bytes (OB) configuration).

To proceed with the configuration, open STM32TrustedPackageCreator tool:

Figure 11 Steps to configure the generic configuration of Secure Manager

4.4. Debug authentication (DA) configuration

This step allows to customize the debug authentication (DA) key and permission, located in Projects\STM32H573I-DK\ROT_Provisioning\DA\Keys. If the key or the permission is changed, the user must follow the article introduction to Debug Authentication to generate the certificate accordingly to these modifications. The user can press any key on the script provisioning.bat to skip this part and go to the next step. In Production usecase, this customization is mandatory.

Warning white.png Warning
During the development, the OEM can use the default keys provided by ST.
During the production preparation phase, the OEM must change the DA keys and regenerate the DA certificates.

In the STM32TrustedPackageCreator tool:

Figure 12 Steps to customize the Debug Authentication Root key and permission associated.

4.5. Option Bytes (OB) configuration

This part allows to customize the Option Bytes configuration. It regenerates the Option_Bytes.csv file located in Projects\STM32H573I-DK\ROT_Provisioning\SM\Config with the user configuration selected. This Option Bytes configuration will be applied when the Secure Manager is installed. The user can press any key on the script provisioning.bat to skip this part and go to the next step.

Note:

  • If the minimal product state has been changed in the part Other configuration, the user can change the product state to the according value in this step, to allow the platform to boot until nonsecure application.
  • In the STM32TrustedPackageCreator tool, the user can modify all the option bytes of the STM32H573 but only the following option bytes are effectively configurable by the user, the other option bytes configuration is ignored (not configurable in the Secure Manager context).
register BitField Description
OPTSR_PRG

IWDG_STDBY
IWDG_STOP
IO_VDDIO2_HSLV
IO_VDD_HSLV
PRODUCT_STATE
NRST_STDBY
NRST_STOP
IWDG_SW
BORH_EN
BOR_LEV

independent watchdog counter active in Standby mode
independent watchdog counter active in Stop mode
configuration of pads below 2.7 V for VDDIO2 power rail
configuration of pads below 2.7 V for VDD power rail
product state
reset when entering Standby mode
reset when entering Stop mode
independent watchdog hardware or software control
high BOR level
supply level threshold that activates/releases the reset

OPTSR2_PRG

SRAM3_ECC
BKPRAM_ECC
SRAM1_3_RST

SRAM3 error code correction
BKPRAM error code correction
SRAM1 and SRAM3 erase on reset


In the STM32TrustedPackageCreator tool:

Figure 13 Steps to customize the default Option Bytes configuration

4.6. Factory ITS blob preparation

The Internal Trusted Storage of the Secure Manager can be initialized securely with preloaded keys and data during Secure Manager installation. This feature allows to start the nonsecure application execution with keys/ and/or data already provisioned in the device and ready to be used.
This step allows to customize this initial trusted storage provisioning located in Projects\STM32H573I-DK\ROT_Provisioning\SM\Binary\ITS_Factory.bin. The user can press any key on the script provisioning.bat to skip this part and go to the next step.

The utility ITSbuilder located in Utilities\PC_Software\ITSbuilder is used to regenerate the blob file with data and/or keys as input. This blob file is formated to be recognized and implemented by the Secure Manager. This utility is called in its_blob script located in Projects\STM32H573I-DK\ROT_Provisioning\SM\its_blob.bat. Below, the principal of this script with the default value located in Projects\STM32H573I-DK\ROT_Provisioning\SM\Binary and Projects\STM32H573I-DK\ROT_Provisioning\SM\Keys

Figure 14 Steps to generate a blob file with the initial trusted storage

To customize the initial trusted storage provisioning :

Figure 15 Steps to customize the initial trusted storage provisioning

Note: You can verify in the generated file its_blob.log (located in Projects\STM32H573I-DK\ROT_Provisioning\SM\its_blob.log) the blob composition and the possible errors.

4.7. SFI global license configuration

This step is highly recommended for a Production usecase. It allows to regenerate a SFI Global License with new key and nonce, located in Projects\STM32H573I-DK\ROT_Provisioning\SM\Keys. The user can press any key on the script provisioning.bat to skip this part and go to the next step.

In the STM32TrustedPackageCreator tool:

Figure 16 Steps to customize the SFI globale license

4.8. Module & license


When the general configuration contains at least one module, the provisioning.bat displays the prompt below:

Figure 17 Module with license

The user can select the type of module to be installed:

  • Module without license (developed by OEM): OEM module
  • Module with global license (without installation counting, developed by third-party entity): third-party module with global license
  • Module with chip specific license (with installation counting) (ie: developed by third-party entity): third-party module with chip specific license (STM32HSM-V2 is needed)

If an installation of a third-party module (with license) is chosen, the Authentication of Modules with license parameter in general configuration will be applied.

  • 0xbd: Modules with license are not signed by OEM.
    • OEM has to integrate the third-party module directly.
  • 0xce: Modules with license are signed by OEM.
    • The third-party module will be automatically signed with OEM keys.

4.8.1. Module and Initial attestation

When you use the Initial attestation feature, the result of the token (SIGNER_ID field) will depend on the origin of the module:

  • Module developed by OEM: Module without license
    • This is the hash of the public OEM key below
Figure 18 OEM Module without license
  • Module developed by third-party entity: Module with license
    • This is the hash of the public third-party key below
Figure 19 Third-party Module with license

For further information on this feature, refer to Initial attestation.

4.8.2. Module without license

To install a module without license, just press ‘1’ on the prompt:

Figure 20 Installation of Module without license

With this choice, a dummy module will be created (dummy.bin above), then signed and encrypted with OEM keys. The resulting firmware image is Module_0.hex.

4.8.3. Module with global license

To install a module with global license (without installation counting), just press ‘2’ on the prompt:

Figure 21 Installation of Module with global license

A module with global license, the associated license and the third-party key are available in the package above. If you want to install another module, copy it with its license and third-party key in the same location, and using the same name.

4.8.4. Module with chip specific license

To install a module with chip specific license (with installation counting), just press ‘3’ on the prompt:

Figure 22 Installation of Module with chip specific license

To install a module with chip specific license, you need to copy the module provided by the third-party in ROT_Provisioning/SM/Binary/config_1_module_0_with_chip_specific_license_not_oem_sign.smu, the third-party key in ROT_Provisioning/SM/License/SMU_ThirdParty_pub.pem with the sames names and insert the corresponding STM32HSM-V2 in your reader.


4.9. SFI file generation

This step generates the SFI file that contain all the required files for the device configuration, the Secure Manager binary and a nonsecure default application. The SFI file is located in Projects\STM32H573I-DK\ROT_Provisioning\SM\Binary\SecureManagerPackage.sfi

5. Script provisioning.bat step 2: Installation

After completion of step 1, follow the indications of the script as shown in the figure below.
The step 2 of the script installs the Secure Manager and a nonsecure default application. If the configuration one module has been selected, a dummy module is installed by default.

Figure 23 Secure Manager and default application installation

Once the installation is complete:

  • A message displays indicating that the board is correctly confirmed.
  • On the STM32H573I-DK board, led1, led2, led3 and led4 should blink.This is part of the default installed code by the script.

In case of issue:

  • Check the provisioning.log file (in directory: \Projects\STM32H573I-DK\ROT_Provisioning\SM).
  • Perform a regression (Refer to the chapter below) and restart at the beginning of this article.

5.1. Default installed code execution

As mentioned above, after the script execution is complete, the four led should blink. This corresponds to the default installed application code.

  • Start Tera Term or another terminal emulator, as in the figure below.
    • Select > Serial > select your COM port.
    • Setup > Serial port > set Speed to 115200 baudrate, Data to 8 bit and Stop bit to 1bit > New setting.
Figure 24 Tera Term setting
  • Press the reset button of the discovery board (B2 black button).
  • The default installed code makes four led blinking and outputs the information shown in the terminal (see figure below): the memory configuration selected by the user, the Secure Manager version and the version of the installed ST Updatable Root of Trust (STuRoT).

For more details about uRoT, refer to the Secure_Boot_for_STM32H5 article.


Figure 25 Default installed application execution
Warning DB.png Important
The Locked state closes definitively your device. So it's a final state adding a further protection level, but the device can't be changed or debugger reopened anymore by any method.

6. Using Secure Manager

Secure Manager is now installed, with the STM32H573 in TZ-Closed state. Now you can develop your own nonsecure application, using the usual development tools such as STM32CubeIDE.

The sections below show you how to do that using the example SMAK_Appli ( number 3 referred here ), provided in the STM32Cube package for STM32H5 MCUs, from developing and debugging, to using PSA services, such as firmware update or cryptography.


6.1. Building and running a nonsecure application

You can follow this article to get the SMAK_Appli running.

6.2. The example application

Now that SMAK_Appli is running, a user interface is accessible using the virtual COM port with the same configuration as in here. It showcases the Secure Manager features, accessing the secure services such as firmware update or using the embedded certificates.

Figure 26 Application terminal screen

6.3. Update of the user application

The following is describing two use cases to update the firmware:

  • Using a script based on STM32CubeProgrammer: This option works only in state TZ-Closed.
  • Using the PSA API: This is only way to update the firmware in state Closed/Locked.

6.3.1. Using download.bat

This scenario starts with a SMAK and previous application loaded into the DK.

  • Update the application code, for example, edit the main.c:
const uint8_t UserAppId = 'A';

to

const uint8_t UserAppId = 'B';
  • Build new version using the "Make" command. It will run:
    • a prebuild command: It updates the memory configuration according to the Secure Manager configuration.
    • a postbuild command: It generates the encrypted and signed firmware using STM32TrustedPackageCreator and the Secure Manager configuration.
Figure 27 The postbuild actions log
  • Two binaries are generated in the binary folder :
    • app_enc_sign.bin: Signed, encrypted fimware image and unconfirmed image, used for the firmware update.
    • app_enc_sign.hex: Signed, encrypted but confirmed image.
Figure 28 The firmware images relative to download.bat
  • Flash the image using download.bat, and you have a new application running
  • The new code is running
Figure 29 Screenshot of modified application running
  • In Firmware Update > Get all applications Status, we confirm that the firmware has been flashed with version 1.0.0
Figure 30 Active slot state after download.bat

6.3.2. Using the PSA API

A step-by-step firmware update can be done using the PSA API. This demonstrates how over the air updates can be used and implemented.

The first step is to prepare the image configuration, by updating the image version:

  • In STM32TrustedPackageCreator >> H5 >> Image Gen open SMAK_Appli/SM_Code_Image_bin.xml
  • Update the version to 2.0.0
  • Click on Generate image
Figure 31 Using STM32TrustedPackageCreator to generate an image

Then, upload the firmware:

  • On the terminal, Select Firmware Update > Download Non-Secure App
  • In the PC terminal app, select YMODEM data sending - select the appli_enc_sign.bin generated with the version 2.0.0
  • Success confirmation will be shown:
Figure 32 Firmware upload confirmation
  • 2.0.0 version is in the download slot with a state of 0x1 Candidate:
Figure 33 Download slot state

Now, the installation can be completed.

  • From the Firmware Update Menu, select Request Install Non-Secure App. The Download Slot state updates to 0x5 Reboot needed
  • Select Install all requested Applications (reboot) from the Firmware Update Menu.
    • The PSA API manages the secure reboot and the images are swapped. The new firmware (2.0.0) is now running, but is in state 0x4 pending install
    • The previous firmware (1.0.0) is still preserved in the download slot.
Figure 34 Active and download slot state after reboot
  • The new firmware needs to be accepted with Firmware Update > Accept Non-Secure App. A reboot prior the acceptation will lead to a rollback to firmware 1.0.0. It is used to revert an update in case the firmware has an issue (e.g. cloud connection issue). for a case of a new update running into a problem.
  • Check the image state with Get all applications Status from the Firmware Update Menu, and confirm:
    • Active slot is running firmware 2.0.0 in state 0x2 installed.
    • Previous firmware is not installable from the download slot anymore.
Figure 35 Active and download slot state after the complete firmware update

6.4. Cryptography example

The nonsecure user application example includes calls to the PSA API cryptography services:

Figure 36 The Cryptography menu contents
  • RNG: Generate a random of 16 bytes
  • AES: Examples of encryption/decryption with a test key of 128 bits (imported and destroyed during the test)
    • AES-GCM
    • AES-CBC
    • AES-CCM
  • Hash:
    • SHA224
    • SHA256
  • Asymmetric: Encryption/Decryption asymmetric example
    • RSA 2048
    • ECDSA (DUA User Key)
    • ECDSA (Factory ITS Key)

All the menu options in the Cryptography section are self-contained tests with no user interaction. It is a good introduction about use of cryptography in a nonsecure application in a secure manager context.

6.5. Certificates Device Unique Authentication

In STM32H573, key pairs are provisioned in System Flash (DUA : Device Unique Authentication).

  • ST DUA Key pair Init Attest : used to authenticate with a cloud (sign the initial attestation token).
  • ST DUA Key pair User : used to create secure communication (TLS).

They are unique per device and have the following characteristics:

  • Type : ECC Key pair (secp_r1)
  • Algorithm : ECDSA
  • Usage : Sign/Verif

In the SMAK_Appli example, the menu Certificates (5) allows the user to retrieve the X509 certificate of the DUA Initial Attest and DUA User of the device. It will display the certificate in PEM format. This menu calls APIs of certificates utility located in Utilities\Certificates. It gets the size and the certificate according to the certificate ID.

Figure 37 Certificate Menu

6.5.1. DUA User X509 certificate

In Certificates menu, select the DUA USER X509 certificate item. This example displays:

  • The size of the certificate DUA User. This size depends on the key provision in the device. Its value will change.
  • The certificate in PEM format. This content must be saved a certificate.pem file to be visualized by a trustedfirmware tools (middleware provided in the STM32CubeH5).
Figure 38 Example of DUA User certificate of SMAK_Appli

Once the certificate is saved:

  • Open a bash terminal
  • Run the following command:
openssl x509 -in certificate.pem -text
  • Below, an example of DUA User certificate
Figure 39 Example of DUA User certificate
  • Run the following command to verify the certificate authenticity with the ST Root CA certificate, located in Utilities\Certificates\st_ca_01_dua_user_certificate.pem:
openssl verify -CAfile st_ca_01_dua_user_certificate.pem certificate.pem

The certificate.pem can be exchanged with another device.

6.5.2. DUA Initial Attestation X509 certificate

In Certificates menu, select the DUA Initial Attestation X509 certificate item. This example displays:

  • The size of the certificate DUA Initial Attestation. This size depends on the key provision in the device. Its value will change.
  • The certificate in PEM format. This content must be saved a certificate.pem file to be visualized by a trustedfirmware tools (middleware provided in the STM32CubeH5).
Figure 40 Example of DUA Initial Attestation in PEM format

Save the content as certificate.pem and then use openssl to display the content:

openssl x509 -in certificate.pem -text 
Figure 41 Initial Attestation certificate in the exploded form

The public key of this certificate can be used with the Initial Attestation token to verify the token signature. Obtain an extract in PEM format with the following command:

openssl x509 -in certificate.pem -pubkey -noout > pubkey.pem

The public key of this certificate can be extracted in ANS1 format to verify the field INSTANCE_ID of the decoded token (Initial Attestation) with the following command:

openssl x509 -in certificate.pem -pubkey -noout | openssl pkey -pubin -outform der | openssl asn1parse -inform der -out pubkey_der.bin -noout && dd if=pubkey_der.bin of=pubkey.bin bs=1 skip=26 count=65


6.6. Initial attestation

The Initial Attestation token contains information about the installed firmware, and the device state. Obtain it from the menu Initial Attestation > Token:

Figure 42 Token response terminal screen

To see the token content, a tool is included in the package under:

 .../Utilities/PC_Software/IAT_Verifier/st_tools/

Before using it, make sure that the prerequisites below are met:

  • Save the token as eat.txt to the folder.
  • Make sure Python version 3 or higher is installed.
  • Check st_tools/readme.txt.
  • Optional DUA Initial Attestation pubkey.


Now you can run st_tools/check_iat.sh. Note: python is called in the script by using a path environment variable.

Figure 43 The decoded token
ID Description Expected Value
1 0x1+hash of initial attestation public key ANS1 format. (SHA256) Unique for every device
2 32 bytes of the ROM SW version, at 0x0BF96000-0x0BF9601F -
3 Hash of the public authentication key of the Secure Manager Core B1CCBE5A67CB2820331D28E6D9A950FE54D61A685C5ADE86D6B95758F852FE41
4 Hash of the Secure Manager Core image D378EBE382CDA5888447971163B1F36F6B4169A59CA69932BD807D382C1FC333
5 Hash of the public authentication key of the STuRoT component 5C2D51B78C38406CE416F8B5053F5F2F8D262F71FDE9429DD9EC2A2302215266
6 Hash of the STuRoT image CCCDC59D9F882DC36FD0E5DC486F25DED4FE2ECB00F30B110FE23B74944E6637

}


All the hashes correspond to the binary provided with the X-Cube-SEC-M_H5_v1.1.2

There is the same mechanism for nonsecure application (NSPE) and Secure Module (ARoT)

Figure 44 Other component of the EAT

For the Secure Module, the SIGNER_ID means:

  • In the case of a module with a license (developed by third-party entity), the hash of the public third-party key.
  • In the case of a module without a license (developed by OEM), the hash of the public key.

See the initial attestation psa specification v1.0.0 to have more information on each field.

One of the feature of the check_iat.sh is to verify the signature with the public key of initial attestation.

  • Get the public key of initial attestation (referred here)
  • Modify the script to enable the signature verification (script is in readonly mode, change the permission before)
    • Set the path to the .pem
    • Uncomment the check_iat line
  • Run checkiat.sh
Figure 45 Signature verification success

7. Troubleshooting

This section summarizes common errors generated when using the Secure Manager, the provided scripts and tools, and the nonsecure application example.

7.1. Provisioning & regression scripts

The analysis starts with finding the error message on the provisioning.bat, the regression.bat, the terminal or the command screen.

Error Possible root cause Remedy
[CubeProg] Error: Cannot connect to access port 1!
during provisioning.bat
SW1 switch on the board is in wrong position during script execution Run again the script with SW1 switch in position 0
[CubeProg] Error: Cannot connect to access port 1!
during provisioning.bat
Board is not in Open product state Run regression.bat script
[CubeProg] Error: Cannot connect to access port 1!
during provisioning.bat
Board is not erased Mass erase the board
[CubeProg] Error: Execution of RSS CMD failed, returned value = 0x1 Error: Failed to Process Area Number 6 of type S
during provisioning.bat
CubeProgrammer doesn't contain the RSSe compatible with the secure manager package Install the CubeProgrammer version mentioned in the pre-requisites
Screenshot 2023-08-24 141836.png
Debugger is attached Disconnect debugger and run again the script
Screenshot 2023-08-24 141836.png
Device resets in loop due to early fault Remove JP6 jumper on STM32H573I-DK board, then run the regression.bat at the same time that you put back the jumper
SM howto tbst.png
Product is open while trying to run regression script No need to perform regression
SM howto tbst2.png
DA certificate is not updated after generating a new DA root key Use Trusted Package Creator tool to generate the correct certificate chain

7.2. Project build, download and debug

Error Probable root cause Remedy
Secure Manager configuration has been changed and the application does not boot after build and download.bat Project not correctly updated with the latest configuration Force the reconfiguration by doing a full rebuild of the application
Prebuild/postbuild not working after using and moving SMAK_Template Project relative path to ROT_Provisioning not up to date Edit the project env.bat/sh with the relative path to ROT_Provisioning.
Postbuild not working ROT_Provisioning folder not in the same drive as the project Keep it in the same drive.
Download.bat script not working Product state is Closed or Locked Ensure product state is TZ-Closed or use PSA FWU service to download application image.
Fail to attach debugger Product state is Closed or Locked Check product state running discovery.bat script. If Closed, debug can be opened with DA (dbg_auth.bat script).
Fail to connect to target Early fault (in SystemInit for example) in the nonsecure Try again

7.3. Application execution

Error Probable root cause Remedy
Error -132 while using psa_fwu_write() Data offset should be 16 bytes aligned Ensure it's aligned
Infinite loop when using HAL driver to write in flash Writing in secure area Reset is needed
Error when calling psa api with large data SRAM Secure/NonSecure interface area size too small Increase it during SM installation