How to migrate a nonsecure application from Secure Manager v2.x.x to v3.x.x

This article guides STM32H573 users through the migration of the Secure Manager from X-CUBE-SEC-M-H5 v2.x.x to v3.x.x following an ABI break, that is, a change in the application binary interface that breaks compatibility between previously working binary components.

1. Introduction

A change in Secure Manager introduced an ABI break in the cryptography service for both supported profiles, Large and External Flash. As a result, a nonsecure application compiled with Secure Manager v2.x.x can no longer communicate correctly with Secure Manager v3.x.x at the cryptographic interface level, because the parameters exchanged between the nonsecure application and the Secure Manager are no longer interpreted in the same way.

During a firmware update, if the nonsecure application and the Secure Manager are updated independently, cryptographic operations may no longer work correctly. The dependency mechanism between the nonsecure application and the Secure Manager must be used to avoid ABI break issues. This mechanism keeps both components aligned, maintains communication, and helps ensure compatibility across versions. As a general recommendation, this approach should be kept as a best practice for future versions.

SMuRoT v3.x.x can be updated either before or after the Secure Manager and the nonsecure application.

2. Prerequisite

The target system can be based on X-CUBE-SEC-M-H5 v2.0.0 or v2.1.0. The following procedure uses the SMAK_Appli nonsecure application from v2.1.0 as an example. Adapt the procedure as needed for the application.

This migration procedure applies to devices already deployed in the field. New devices can follow the standard regression flow instead.

The X-CUBE-SEC-M-H5 v3.0.0 package and Secure Manager v3.0.10 (Large profile) will be used as examples, but the procedure remains the same for later versions of X-CUBE-SEC-M-H5, the Secure Manager, and the External Flash profile.

3. Step 1: Enabling the dependency on Secure Manager

First, rebuild the nonsecure application with the middleware from X-CUBE-SEC-M-H5 v3.0.0.

Then, update the firmware update XML file for the nonsecure application and enable the dependency on Secure Manager v3.0.10 (Large profile).

Figure 1: Dependency configuration (example for the Large profile)

An example XML file for SMAK_Appli is available here: X-CUBE-SEC-M-H5_V3.0.0/Projects/STM32H573I-DK/Applications/ROT/SMAK_Appli/Images/SM_Code_Image_bin.xml.

4. Step 2: Firmware update with the new nonsecure application

Perform the firmware update of the new nonsecure application by downloading it, requesting installation, and rebooting, as shown in the SMAK_Appli example below:

Figure 2: Firmware update of the nonsecure application

The new nonsecure application remains in the download slot until the dependency is satisfied:

Figure 3: Firmware update of the nonsecure application - dependency not satisfied

5. Step 3: Firmware update with the Secure Manager v3.0.0

The Secure Manager binary for the firmware update is available here X-CUBE-SEC-M-H5_V3.0.0/Projects/STM32H573I-DK/ROT_Provisioning/SM/Binary/{Profile_External_Flash|Profile_Large}/SecureManagerCore_H573_PROD_FWU_{Ext_Flash|Large}_v3.0.*.bin.

Perform the firmware update of the Secure Manager v3.0.10 (Large profile) by downloading it, requesting its installation, and rebooting. The following figures are taken from the SMAK_Appli with the Large profile.

Figure 4: Firmware update of the Secure Manager (Large profile)

After reboot, the nonsecure application and the Secure Manager are installed together because the dependency is now satisfied.

Figure 5: Firmware update of the nonsecure application and the Secure Manager (Large profile) - dependency satisfied

6. Step 4: Accepting images

The nonsecure application must be accepted first:

Figure 6: Accepting the update of the nonsecure application

Then accept the Secure Manager:

Figure 7: Accept the update of the Secure Manager

6.1. Reset during the firmware update

If a reset occurs after the nonsecure application is accepted (step 4), the Secure Manager image remains in the active slot in state 0x4 PENDING_INSTALL because of the dependency mechanism as shown in the figure below.

Figure 8: Secure Manager after reset

The Secure Manager does not depend on any other image. If it is accepted first and a reset occurs, the nonsecure application is swapped independently, which breaks the cryptographic service.

7. Troubleshooting

Error in TZ-Closed	Error in Closed and Locked	Probable root cause	Remedy
Failure of cryptographic operations		Firmware update of Secure Manager or nonsecure application only: Download / Request Install / Reset. Or Firmware update of both the nonsecure application with new middleware v3.0.0 and the Secure Manager (without dependency), but accept only the nonsecure application and reset. Or Firmware update both the nonsecure application with new middleware v3.0.0 and the Secure Manager (with or without dependency), but accept only the Secure Manager and reset.	If no image is accepted: the system can be recovered by aborting the firmware update with a reset. Then follow this procedure to update the nonsecure application and Secure Manager together. If one image is accepted: If cryptography is not used to perform the firmware update, update the nonsecure application or the Secure Manager to restore full functionality. If cryptography is used during the firmware update process, the system cannot be recovered and requires a regression.
Error on exit: the system returns to the nonsecure application error handler.	It is impossible to accept the Secure Manager update -> rollback to image v1. Or It is impossible to accept the nonsecure application update -> rollback to image v1.	Firmware update: only one image is updated (Secure Manager or nonsecure application) through the following sequence: Download / Request installation / Reset / Accept.
The SM_Platform service example provided with SMAK_Appli does not work.		SMuRoT or Secure Manager is not updated to the new version.	Update SMuRoT or the Secure Manager to v3.0.0 to enable the new SM_Platform service.