The objective of this article is to guide STM32H573 users on their first steps with the Secure Manager package. Refer to the article Introduction to Secure Manager for further details on what the 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 with a STM32H57x with factory settings or after a full regression, to a state where the 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 with the development of API calls.
There are several ways to install the Secure Manager, from a step-by-step meticulous checklist to a simple batch execution. The arrangement of the nonsecure application image slots is only configurable from the SMAK form.
1.1. Prerequisites
- To use the Secure Manager, a compatible STM32 MCU is needed. This article describes usage with STM32H573 in particular, the only device in the STM32H5 series that currently supports the Secure Manager. The package was tested with STM32H573I-DK Discovery kit rev C.
- On the software side, the STM32CubeMX toolset is needed, including the STM32CubeProgrammer and the Trusted Package Creator. The package was tested with STM32CubeProgrammer 2.14. The Trusted Package Creator is not installed by default, it must be checked as an installation option. The STM32CubeMX downloads the STM32CubeH5 Package, containing the HAL 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 H5. These are included within the package:
- A Tera Term or similar terminal SW is needed to communicate with the embedded software using a virtual COM port.
- There is no extra cost or licensing hurdle for the SMAK.
- To use the SMDK, contact STMicroelectronics and get qualified to sign the required NDA.
1.2. Package contents
The SMAK is included in the STM32CubeH5 downloadable package. The different directories and files are detailed below:
Item | Description |
---|---|
BSP | SMAK is using drivers like any other STM32Cube app. |
Example TBC | Example TBC |
Example TBC | Example TBC |
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 needed, 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 addresses and the communication virtual port number must be edited.
2.2. SMAK Keys configuration
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 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 key 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.3. Option Bytes configuration
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.4. Memory configuration
The memory layout and partitioning are also configurable.
Predefined configuration parameters are:
- ITS size
- Module number and their size
- Nonsecure App size
Customizable parameters are:
- Module SRAM size
- Shared S/NS buffer size
- NS reserved area (shared with NS app size)
Basic settings are easily accessible by opening another xml file in the STM32 Trusted Package Creator tool:
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 | NS 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 |
To learn more about memory configuration, continue reading SMAK Memory mapping.
2.5. Other configuration
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.6. Debug authentication (DA) configuration
Provisioning the debug authentication (DA) keys and certificate is strongly recommended.
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.7. Customization of ITS Blob
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).
2.8. 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
- layout configuration
- DA configuration
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. Just add a functionality and download it using, for example, STM32CubeProgrammer.
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. 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.bin file is installed on the DK.
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 example Nonsecure User App includes calls to the PSA API cryptography services. These include the following:
- RNG
- AES
- AES-GCM
- AES-CBC
- AES-CCM
- Hash
- SHA224
- SHA256
- Asymmetric
- RSA 2048
- ECDSA (DUA User Key)
- ECDSA (Factory ITS Key)
All menu options in the "Cryptography" section are self-contained tests with no user interaction.
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 into this 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
Observe how the token encompasses all the installed components. 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 |
5. Generating from STM32CubeMX
The Secure Manager can also be configured using the STM32CubeMX visual tool, along with other components of the Secure Boot. For further details, refer to the following article: How to start with STM32CubeMX and Secure Manager on STM32H573