The objective of this article is to guide STM32H573 users on their first steps with the Secure Manager package. For further details on what the Secure Manager is and what are the benefits of using it, refer to the article Introduction to Secure Manager.
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. Only the arrangement of the nonsecure application image slots is configurable in 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 (cut 1.1).
- 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 SMDK, contact STMicroelectronics and get qualified to sign an NDA.
1.2. Package contents
The Secure Manager Access Kit is included in the STM32CubeH5 downloadable package, here is the breakdown of the directory and file contents:
| Item | Description |
|---|---|
| BSP | SMAK is using drivers like any other STM32Cube app. |
| Example | Example |
| Example | Example |
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 (see package contents earlier). 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.
In the same SM_Config_Keys file the OB values may be customized.
The obvious limitation is that the configured final PRODUCT_STATE must be TZ-Closed or Closed for the SM to install. Mind the OB generation path selector in lower right corner and set it to Option_Bytes.csv to align with the batches.
2.3. 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 |
|---|---|---|---|---|---|---|---|
| 0 | 584kB | 0x0806E000 | 0x081000000 | 48kB | 0 | - | - |
| 1 | 456kB | 0x0808E000 | 0x081000000 | 48kB | 128kB | 0x0806E000 | 0x08172000 |
2.4. 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.5. 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 NS application in the TZ-Closed state. Removing the debug certificate would block such development.
2.6. 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.7. 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.
Please note the requirement to put SW1 on the board 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 - no more access by debugger
- Boot Path is configured to start from STiRoT - boot lock
- Memory mapping for non-secure application is fixed - regression is necessary to change the layout
- Keys to manage non-secure application images are fixed - again, until regression.
- Regression solution is based on 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
Note: The IAR EWARM is used as an example, but the scenario should be similar in other IDEs.
- Open SMAK_Appli project file
The SMAK_Appli template is by default available by following this path:
C:\Users\***\STM32Cube\Repository\STM32Cube_FW_H5_V1.1.0\Projects\STM32H573I-DK\Templates\ROT\SMAK_Appli\
- Do intended modification to your application
- 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.
As an initial step in the development loop, the application can be modified in a way that it is visible on the terminal screen.
For example, in the main.c, edit:
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 that is done and test passed, select 2 for Installation Application.
Results are immediate. And, 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 download using the CLI STM32CubeProgrammer.
The development of application part that interfaces with the Secure Manager or its Modules needs to adhere to workflow that respects the secure TrustZone isolation. 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.
- Encrypted and signed binary is stored in Binary subfolder of the app
- Using the download.bat the appli_enc_sign.bin file is installed on the DK.
Alternatively, instead of the batch file, the installation can be done step-by-step in following way:
- 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 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 erroneous results due to mistakes in using the Secure Manager, provided scripts and tools, and the Non-Secure Application example. Analysis starts from finding error message in the provisioning.bat, regression.bat, terminal or on command screen.
| Error message | Probable root cause | Remedy |
|---|---|---|
| Cannot connect to access port 1 | SW1 in wrong position during script execution | Re-run the script with correct switch position |
| Debug Authentication failed (after "Writing magic number") | Debugger is attached | Re-run the script with debugger disconnected |
|
| ||
|
| ||
| NS application doesn’t 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