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. Preparing the installation
This section details provisioning with the Secure Manager Access Kit (SMAK), from the Open product state on a STM32H57x with factory settings or after a full regression, to a state where Secure Manager is installed and the product is in TZ-Closed state. When the product is in TZ-Closed state, it is ready for nonsecure application development including the PSA API calls.
There are different methods to install Secure Manager, from a step-by-step meticulous checklist to a simple batch execution. This article presents the whole selection of configurable parameters to install Secure Manager. Most of the configurable parameters are optional and can only be used in particular scenarios. Optional parts are indicated.
1.1. Prerequisites
- A compatible STM32 MCU is needed to use Secure Manager. This article describes the use of Secure Manager with the STM32H573 product line, the device from the STM32H5 series supporting Secure Manager.
- STM32H573I-DK Discovery kit rev C was used to test Secure Manager. The use STM32H573I-DK Discovery kit rev C is required.
- On the software side, the STM32CubeMX toolset is needed, including the STM32CubeProgrammer and the STM32 Trusted Package Creator. The package was tested with STM32CubeProgrammer 2.14. The Trusted Package Creator is not installed by default, this is an installation option. The STM32CubeMX downloads the STM32CubeH5 Package, containing the HAL, the Secure Manager binaries and the examples.
- The package supports IAR Embedded Workbench, STM32CubeIDE and Keil IDE. It was tested with IAR v9.20.1, STM32CubeIDE V1.13 and Keil V5.37. IDE may need to be patched with product description files to support the STM32H5 series. These are included within the package:
- A Tera Term or similar terminal emulator is needed to communicate with the embedded software using a virtual COM port.
1.2. Package contents
The SMAK is included in the STM32CubeH5 downloadable package. The different directories and files are detailed below:
Item | Directory name | Description |
---|---|---|
1 | Drivers | SMAK is using drivers as any other STM32Cube app |
2 | Middlewares | Secure Manager API, used by SMAK project to call Secure services (PSA) |
3 | SMAK Appli | Example from the 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 |
2. Installation
This section introduces the automated installation by using a prepared script for the STM32H573I-DK Discovery kit in the STM32CubeH5 Package. This section also explains the configuration and the customization of the installation process.
If no customization is made, one single step is needed, which is running provisioning_auto.bat.
2.1. Environment configuration
A batch file called env.bat is by default placed at the following location:
C:\Users\***\STM32Cube\Repository\STM32Cube_FW_H5_V1.1.0\Projects\STM32H573I-DK\ROT_Provisioning
This batch file needs to be edited. To continue with the installation, both the address and the communication virtual port number must be edited.
2.2. Skipping configuration with default settings
For a first experience with Secure Manager, it is possible to skip the optional configuration and install only the default image.
The following sections describe the configurable parameters. All the changes made in configuration are applied once the provisioning.bat is executed.
2.3. SMAK Keys configuration (optional)
If you do not need to customize keys, skip this part and go here.
As an example, keys are used with external modules. The OEM keys are in the SMAK/Keys subfolder. The easiest way to modify the keys is to open the STM32 Trusted Package Creator tool:
- Select H5 (H5 stands for STM32H5 series) in the leftmost pane, and then the OBkey tab.
- Open the key configuration file and regenerate the keys as needed:
- SMAK authentication key is used for the signed installed application.
- SMAK encryption key is used to provide confidentiality on the installed user application.
The keys are stored in the Keys subfolder (Refer to Package contents). When done, click Generate OBKey in the lower right corner of the window. The new SM_Config_Keys.obk file will be used at the next provisioning.
2.4. Option Bytes configuration (optional)
The example works with default OB, skip here.
The Option Bytes values can be customized using the same SM_Config_Keys file.
The obvious limitation is that the configured final PRODUCT_STATE must be TZ-Closed or Closed.
Use the OB generation path selector in lower right corner and set it to Option_Bytes.csv to align with the batches.
2.5. Memory configuration
This part configuration part is optional, the example works with default mapping, unless you need to add a module skip here.
The memory layout and partitioning are configurable. Predefined configuration parameters are:
- ITS size
- Module number and their size
- Nonsecure application size
Customizable parameters are:
- Module SRAM size
- Shared S/NS buffer size
- NS reserved area (shared with nonsecure application size)
Basic settings are easily accessible by opening another xml file in the STM32 Trusted Package Creator tool:
The setting of "Secure SRAM end address" is by default reserving space for a configuration with one module. Set to minimal value if no modules are installed.
When finished with settings, click on Generate OBKey in lower right corner. The new SM_Config_General.obk file will be used at next provisioning.
Two basic configurations are available for preselection, here are their basic parameter settings:
Configuration index | Nonsecure application | Active slot address | Download slot address | ITS | Module 0 | Module slot address | Module download |
---|---|---|---|---|---|---|---|
SMAK_0 | 584kB | 0x0806E000 | 0x081000000 | 48kB | 0 | - | - |
SMAK_1 | 456kB | 0x0808E000 | 0x081000000 | 48kB | 128kB | 0x0806E000 | 0x08172000 |
Using provisioning_auto.bat, if a SMAK_1 configuration is selected, the module is installed without a license. The provisioning.bat displays a prompt for license options. Choices are:
- module without license
- module with global license
- module with chip specific license
The license authentication method is selected withing the STM32 Trusted Package Creator tool:
Choosing "Modules with license shall be signed by OEM" results in keys and authentication stored in ROT_Provisioning/SM/Keys will be used, see OEM Keys section for reference.
Choosing "Modules with license shall not be signed by OEM" means a third party authentication will be provided later.
In handling the module and the license file, the provisioning batch will give clear instructions. The idea is to copy the files provided from the module provider and replace the placeholder dummy files in the package.
Straightforward and recommended way to replace the module is to rename the new file to the file name of the former one (config_1_module_0_with_global_license_not_oem_sign.smu). The other option is to manually edit the batch file. To learn more about memory configuration, continue reading SMAK Memory mapping.
2.6. Other configuration
This category contains the smaller configuration articles, their review can be left for advanced studies and skipped in initial familiarization with the Secure Manager. Third customization xml file is the SM_Config_Other.xml, opened and regenerated analogically to the general and key configuration. The settings there are probably going to be kept unchanged for most projects, but they are still there for review.
2.7. Debug authentication (DA) configuration
Generating own debug authentication (DA) keys and certificate is strongly recommended for all but evaluation purposes. You can skip it if unique DA configuration is not needed.
The configuration consists of the setting of the key and the root permission mask.
The article introduction to Debug Authentication details the process.
When modifying the default settings, consider the need to actually debug the nonsecure application in the TZ-Closed state. Removing the debug certificate would block such development.
2.8. Customization of ITS Blob
Internal storage may include preloaded secured keys and data, but it's not mandatory to configure and may be skipped.
There is no visual aid to the ITS Blob modifications. All the changes are realized using the its_blob.bat (its_blob.sh). See the package structure above. The batch calls ITSBuilder tool, which comes with built-in help (run ITSBuilder --help).
The result is a file called ITS_Factory_Blob.bin and contains keys and data according to the modifications of the its_blob batch file.
2.9. SFI preparation
For unique SFI license and encryption key continue reading, else skip.
The STM32Trusted Package Creator tool can also be used to cryptographically link the output binary to SFI manufacturing process.
In top line of tabs choose the "License Gen" one and select SFIG license type (SFIG for SFI generating). Then the tool can re-generate SFI_Encryption_Key.bin and SFI_Encryption_Nonce.bin for unique SFI handling. In the right pane then select the file to generate license to (by default the previous will be overwritten).
Conclude the license customization process by clicking "Generate License" in lower right corner.
2.10. Installation process
In the basic scenario, all that is required is to execute the provisioning.bat and follow the instructions on the screen. The process requires you to manipulate the SW1 switch on the STM32H573I-DK board to complete the provisioning correctly.
The batch file works in two steps. In step 1, it prepares the SFI package, which contains the following:
- keys configuration ( details here )
- layout configuration (details here )
- DA configuration ( details here )
All these are prepared in the STM32 Trusted Package Creator tool.
On the board, SW1 must be set to position 0.
In case of failure, return to the default state using regression.bat and check the provisioning log for troubleshooting.
The previously updated environment configuration is now used to communicate with the STM32H573I-DK board and to upload the SFI package.
Follow the instructions to manipulate the SW1, to assert the correct state on the BOOT0 pin. The Secure Manager is installed when finished.
After installation:
- Secure Domain is closed. It can no longer be accessed by the debugger.
- Boot Path is configured to start from STiRoT, with boot lock.
- Memory mapping for the nonsecure application is fixed. Regression is necessary to change the layout.
- Keys to manage the nonsecure application images are fixed until regression.
- Regression solution is based on the OEM Certificate.
3. Using the Secure Manager
The Secure Manager is now provisioned, with the STM32H573 in TZ-Closed state. It is possible to code and debug in the nonsecure domain of the MCU by using the usual development tools, for example STM32CubeIDE. The STM32Cube package for STM32H5 MCUs contains a template called SMAK_Appli ( number 15 referred here ). Just add a functionality and download it using, for example, STM32CubeProgrammer.
During evaluation of the tools and early experiments with the Secure Manager Application Kit and the nonsecure application development it's highly recommended to keep the default DA configuration intact and conclude each experiment by running regression.bat to get safely back to the Open product state.
3.1. Direct download
The IAR EWARM is used as an example, but the scenario should be similar in other IDEs. This is the suggested workflow for development in TZ-Closed state, not applicable to other Product State values.
- Open SMAK_Appli project file. The SMAK_Appli template is by default available at C:\Users\***\STM32Cube\Repository\STM32Cube_FW_H5_V1.1.0\Projects\STM32H573I-DK\Templates\ROT\SMAK_Appli\
- Edit your application as intended.
- When ready, click Download and Debug as with normal application development.
- The IDE may display a warning at this point. This is due to the unusual program entry point, and can be safely ignored.
- A breakpoint must be placed to your main in order to start a debug session. The debug authentication session is valid as long as the debugger is connected to the target.
3.2. The template application
The template application contains a user interface. This user interface works with the terminal application on the host PC, using the virtual COM port with baudrate 115200, 8bit data, no parity. It showcases the PSA functionality, provided by the Secure Manager, in service of the user application.
The suggested way of upgrading the nonsecure User App, in Closed or even Locked Product State, is described below.
To be able to check the changes made, the application can be edited in a way that it is visible on the terminal screen.
For example, edit the main.c as follows:
const uint8_t UserAppId = 'A';
to
const uint8_t UserAppId = 'B';
and rebuild the application normally. The postbuild script will produce an encrypted binary.
Running the template application, use the terminal to enter:
- 4 to select Firmware update, then
- 3 to select Download nonsecure app.
Send the encrypted binary using YMODEM on your software terminal. Once it is sent and the test is passed, select 2 for Installation Application.
Results are immediate. Unless you select the option Validation nonsecure app, the application is reverted to the previous version on next reboot. This two-slot system is the default behavior, implemented to have the reset option as a panic button in case the newly downloaded firmware is not working properly.
3.3. Update of the user application
The project is packed with batch files that automate necessary post-build actions and patch downloads using the CLI STM32CubeProgrammer.
The development of the application part that interfaces with the Secure Manager or its modules needs to be compliant with the workflow followed by the secure TrustZone isolation. The new application binary must be installed using the means of the Secure Manager update services, and then executed in TZ-closed or Closed product state.
- This scenario starts with a SMAK and previous application loaded into the DK.
- Update the new version as usual.
- Build new version using "Make" command. The idea is that the pre-build and post-build commands are executed properly. The prebuild updates the memory configuration with the one selected during the secure manager installation. In the postbuild.log, you can see STM32 Trusted Package Creator is used to encrypt and sign the firmware. File:SM howto postbuild.pngThe postbuild actions log
- Encrypted and signed binary is stored in the Binary subfolder of the app
- Using the download.bat the appli_enc_sign.hex file is installed on the DK. The appli_enc_sign.bin is an intermediate.
Alternatively, instead of using the batch file, the installation can be done step-by-step:
- In the example, nonsecure user App start by selecting "Firmware Update" menu option.
- Select "Download Non-Secure app". App displays PSA API calls used for that action.
- In the PC terminal app, select YMODEM data sending - select the appli_enc_sign.bin.
- The Application should confirm successful programming.
- Still from within the Firmware Update Menu, select "Request Install Non-Secure App". The App displays the PSA API calls used for that action.
- To conclude the installation, a reboot is required. Select "Install all requested Applications (reboot)" from the Firmware Update Menu.
- The PSA API manages the secure reboot and the installation is concluded. The new FW is running after the boot.
- The previous FW is still preserved, for a case of a new update running into a problem. Unless the new FW is validated, old FW will be installed back on the next reboot. Validate the new FW using the Firmware Update Menu option "Accept Non-Secure App".
- Selecting "Get all applications Status" from the Firmware Update Menu lists the current state of both the Active slot (from which the FW is running) and the Download slot.
3.4. Cryptography example
The Nonsecure User App example includes calls to the PSA API cryptography services. Here is their list:
- RNG
- AES
- AES-GCM
- AES-CBC
- AES-CCM
- Hash
- SHA224
- SHA256
- Asymmetric
- 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. They are however complete and can be used to learn about use of cryptography in nonsecure application under Secure Manager.
3.5. Working with the certificates
Certificate handling in the example application provides functions to build a certificate of X509 structure for DUA Key pairs. Key pairs may be used for authentication with a cloud service (Initial Attestation) or to create a secure communication (TLS). These keys are generated unique per device and are based on ECC - ECDSA.
The application only offers one choice in the "Certificates" menu option, which calls the SM APIs to display the certificate size and the certificate.pem file contents. By copying the text from the screen and saving it as a pem file, the file can be parsed using openssl tools.
To use the exported certificate, it must be verified using a certification authority certificate. In a real world application that would be, for example, an OEM certificate. For this example, dummy certificate is provided. Save the exported certificate.pem to this folder:
Then verify the certificate by running:
openssl verify -CAfile st_ca_01_dua_user_certificate.pem certificate.pem
This admits the certificate to be used in secure communication session initiation.
To try the Initial Attestation, change the certificate type in the application code. In cert.c source file, look for DUA_USER being used as a parameter to the function call (there should be two such calls, one for UTIL_CERT_GetCertificateSize and the other for UTIL_CERT_GetCertificate).
Change these two values to DUA_INITIAL_ATTEST.
Rebuild and download the new firmware. There is no visible change to the example execution, but parsing the exported certificate.pem file will yield:
To admit the device into the cryptographic system, extract the public key using:
openssl x509 -in certificate.pem -pubkey -noout > pubkey.pem
This public key can be used with the Initial Attestation token to verify the token signature.
3.6. Initial Attestation
The Initial Attestation menu section again only contains one option, used to get the attestation token. The token contains information about the installed firmware and device state. Terminal screenshot of the action follows:
As with the certificate, copy the token to a text file. To work with the generated token, tool is included in the package under:
.../Middlewares/Third_party/trustedfirmware/tools/iat-verifier/st_tools
To use it:
- Save the token as eat.txt to the folder.
- Make sure Python version 3 or newer is installed.
- Check other prerequisites in st_tools/readme.txt.
- Run checkiat.sh to decode the token
The token covers all the installed components using hash values. The token can optionally be signed using the certificate described in the previous section.
4. Troubleshooting
This section summarizes common errors generated when using the Secure Manager, the provided scripts and tools, and the nonsecure application example.
The analysis starts with finding the error message on the provisioning.bat, the regression.bat, the terminal or the command screen.
Error message | Probable root cause | Remedy |
---|---|---|
Cannot connect to access port 1 | SW1 in wrong position during script execution | Run again the script with correct switch position |
Debug Authentication failed (after "Writing magic number") | Debugger is attached | Run again the script with debugger disconnected |
Product is open while trying to run regression script | No need to regress | |
DA certificate not updated after generated a new DA root key | Use trusted package creator tool to generate correct certificate chain | |
Nonsecure application does not boot after update | Configuration error | Check relative paths in batch files. Rebuild the whole project |