Getting started with SFI on STM32H5 MCUs using the Secure Manager

1. Applicable products

The following table shows the applicable products for SFI on STM32H5 with Secure Manager:

Type	Products
Microcontroller	STM32H573xx

2. Environment setup

As explained in SFI Image generation, the secure firmware install (SFI) image generation and test rely on the Secure Manager Access Kit (SMAK).

Read SMAK prerequisites and SMAK package contents for the SFI environment setup and Script provisioning: Configuration to configure the Secure Manager installation, including the minimal and final product states.

In the rest of this wiki, the pathX-CUBE-SEC-M-H5_VX.Y.Z\Projects\STM32H573I-DK\ROT_Provisioning\SM is referred to as SM.

3. Firmware development (on OEM premises)

The purpose of this SFI service is to securely install the OEM firmware developed with the Secure Manager.
To use this SFI service, the OEM must develop their nonsecure application during the SMAK development phase.

The OEM firmware file has a .hex extension. STMicroelectronics provides an application to build the X-CUBE-SEC-M-H5_VX.Y.Z\Projects\STM32H573I-DK\Applications\ROT\SMAK_Appli\Binary\appli_enc_sign.hex file.

4. SFI image generation and HSM provisioning (on secure OEM premises)

4.1. SFI with chip-specific license

To install an SFI with a chip-specific license, program an STM32HSM-V2 hardware security model (HSM). To do so, and configure the environment, follow the steps described in the How to start with Secure Manager customized config on STM32H5: SFI chip-specific license configuration wiki page.

After this first step, the configuration file SM\Config\sm.ini must look like this:

[sfi_generation]
license_key_encryption = ../Keys/SFI_Encryption_Key.bin
license_key_nonce = ../Keys/SFI_Encryption_Nonce.bin

[sfi_license]
# Type of license for the SFI: choose "global" for global license or "chip-specific" for chip-specific license
license_type = chip-specific
global_license_path  = ../Keys/SFI_Global_License.bin
hsm_license_slot = 1

When the HSM has been programmed, it can be used with the SFI that is created during the SFI image generation and installation.

4.2. SFI with global license

To install an SFI with a global license, generate a new global license and configure the environment.

To generate a global license and configure the environment, follow the SFI license configuration step in the How to start with Secure Manager customized configuration on STM32H5 wiki page.

After this step, the configuration file SM\Config\sm.ini must look like this:

[sfi_generation]
license_key_encryption = ../Keys/SFI_Encryption_Key.bin
license_key_nonce = ../Keys/SFI_Encryption_Nonce.bin

[sfi_license]
# Type of license for the SFI: choose "global" for global license or "chip-specific" for chip-specific license
license_type = global
global_license_path  = ../Keys/SFI_Global_License.bin
hsm_license_slot = 1

When the global license has been generated, it can be used with the SFI that is created during the SFI image generation and installation.

4.3. SFI image generation and installation

Once the OEM completes their nonsecure application development, they must prepare and test the final encrypted image (SFI image) to be used for OEM secure manufacturing with the SMAK production preparation phase.

The following sections provide step-by-step guidance through the SFI image generation and installation procedure.

4.3.1. Step 1: Profile selection

In the step described in the Security:How to start with Secure Manager customized config on STM32H5: Configuration Profile file: large.ini or ext_flash.ini wiki page, a profile is selected. In this next step, the configuration file varies based on the selected profile, as shown in the table below:

Profile	Configuration file
Large	SM\Config\Profile_Large\large.ini
External Flash	SM\Config\Profile_External_Flash\ext_flash.ini

In the following sections, these paths above are referred to as large.ini and ext_flash.ini.

4.3.2. Step 2: Configuration

In this step, JSON and .ini files are modified. These files can be customized, and all paths can be either absolute or relative to the file itself.

4.3.2.1. OEM Application

1. Copy the signed and encrypted OEM application (named oem_app.hex hereafter) to the Binary folder:
   

   cp oem_app.hex X-CUBE-SEC-M-H5_VX.Y.Z\Projects\STM32H573I-DK\ROT_Provisioning\SM\Binary
   

2. Copy the JSON template to the Binary folder:
   

   cp X-CUBE-SEC-M-H5_VX.Y.Z\Projects\STM32H573I-DK\ROT_Provisioning\SM\Binary\JSON\Templates\ns_app_template.json X-CUBE-SEC-M-H5_VX.Y.Z\Projects\STM32H573I-DK\ROT_Provisioning\SM\Binary\JSON\ns_app_oem.json
   

   This JSON file specifies the path of the nonsecure application to be installed during the SFI procedure to the SM\provisioning.py script.
3. Modify the content of ns_app_oem.json by replacing the existing path with the path to the OEM application, as shown in the code snippet below:
   

   {
      '''"binary":"../../Binary/oem_app.hex"''',
      "active_slot":false
   }
   

4. Depending on the selected profile, modify large.ini or ext_flash.ini. In this file, the images dictionary must contain an "ns_app" key and a corresponding path to a JSON file. In this case, the path corresponds to that of the previously modified ns_app_oem.json file:
   

   images = {"ns_app"   : "../../Binary/JSON/ns_app_oem.json",
   

4.3.2.2. Factory internal trusted storage (FITS)

Follow the steps below to include a factory ITS in the SFI.

1. Copy the default JSON to the Binary folder:
   

   cp X-CUBE-SEC-M-H5_VX.Y.Z\Projects\STM32H573I-DK\ROT_Provisioning\SM\Binary\JSON\fits_default.json X-CUBE-SEC-M-H5_VX.Y.Z\Projects\STM32H573I-DK\ROT_Provisioning\SM\Binary\JSON\fits_oem.json
   

   This JSON file specifies the path of a factory ITS blob to be installed during the SFI procedure to the SM\provisioning.py script.
2. Prepare a custom FITS (named oem_its_blob.bin hereafter) with custom data and/or keys by following the steps on the Factory ITS blob preparation section of the linked wiki page.
3. Modify the content of fits_oem.json by replacing the existing path with the path to the custom FITS, as shown in the code snippet below:
   

   {
      "binary":"../../Binary/oem_its_blob.bin",
      "xml":"../../Images/SM_ITS.xml",
      "auto_update":true
   }
   

4. Finally, depending on the selected profile, modify large.ini|ext_flash.ini.
   In this file, the images dictionary must contain an "FITS" key and a corresponding path to a JSON file. In this case, the path corresponds to that of the previously modified fits_oem.json file:
   

   images = {"ns_app"   : "../../Binary/JSON/ns_app_oem.json",
             "FITS"     : "../../Binary/JSON/fits_oem.json"}
   

   If no factory ITS is needed in the SFI, delete the "FITS" key and its corresponding path in the images dictionary.

4.3.2.3. Secure module

The table below shows how to include the three types of modules in the SFI:

• Secure module without license
• Secure module with a global license
• Secure module with a chip-specific license

Type of module	File(s) to copy to SM\Binary	Copy of the JSON template in SM\Binary\JSON	Content of the JSON file	Content of large.ini|ext_flash.ini In this file, the images dictionary must contain a "module_0" key and a corresponding path to a JSON file.
Module without license	oem_module.hex Note: Image already signed and encrypted	Copy SM\Binary\JSON\Templates\module_template.json to SM\Binary\JSON\module_oem.json	module_oem.json { "license_type":"no_license", "binary":"../../Binary/oem_module.hex" }	images = {"ns_app" : "../../Binary/JSON/ns_app_oem.json", "module_0" : "../../Binary/JSON/module_oem.json",
Module with global license	3rdPartyModule.smu 3rdPartyGlobalLicense.bin	Copy SM\Binary\JSON\Templates\Profile_Large\module_with_global_license_Large_template.json to SM\Binary\JSON\module_global_license.json Note: The selected profile does not affect the template mentioned above because the binary and license paths are updated afterwards.	module_global_license.json { "license_type":"global_license", "binary":"../../Binary/3rdPartyModule.smu", "license":"../../Binary/3rdPartyGlobalLicense.bin" }	images = {"ns_app" : "../../Binary/JSON/ns_app_oem.json", "module_0" : "../../Binary/JSON/module_global_license.json",
Module with chip-specific license	3rdPartyModule.smu	Copy SM\Binary\JSON\Templates\module_with_chip_specific_license_template.json to SM\Binary\JSON\module_chip_specific_license.json	module_chip_specific_license.json { "license_type":"chip_specific_license", "binary":"../../Binary/3rdPartyModule.smu" }	images = {"ns_app" : "../../Binary/JSON/ns_app_oem.json", "module_0" : "../../Binary/JSON/module_chip_specific_license.json",

4.3.2.4. External flash driver (External Flash profile only)

With the External Flash profile, an external flash driver must be included in the SFI procedure. STMicroelectronics provides an example of an external flash driver project compatible with the default external flash memory on the STM32H573I-DK board. This project is located at X-CUBE-SEC-M-H5_VX.Y.Z\Projects\STM32H573I-DK\Applications\ROT\External_Flash_Driver.

1. Copy the external flash driver (named Ext_Flash_Driver.bin hereafter) to the Binary folder:
   

   cp Ext_Flash_Driver.bin X-CUBE-SEC-M-H5_VX.Y.Z\Projects\STM32H573I-DK\ROT_Provisioning\SM\Binary
   

2. Copy the default JSON file to the Binary folder:
   

    cp X-CUBE-SEC-M-H5_VX.Y.Z\Projects\STM32H573I-DK\ROT_Provisioning\SM\Binary\JSON\external_flash_driver_default.json X-CUBE-SEC-M-H5_VX.Y.Z\Projects\STM32H573I-DK\ROT_Provisioning\SM\Binary\JSON\external_flash_driver_oem.json
   

   This JSON file specifies the path of an external flash driver to be installed during the SFI procedure to the SM\provisioning.py script.
3. Modify the content of external_flash_driver_oem.json by replacing the existing path with the path to the external flash driver, as shown in the code snippet below:
   

   {
      "binary":"../../Binary/Ext_Flash_Driver.bin",
      "xml":"../../Images/SM_External_Flash_Driver_Image.xml",
      "auto_update":true
   }
   

4. Finally, modify ext_flash.ini.
   In this file, the images dictionary must contain an "external_flash_driver" key and a corresponding path to a JSON file. In this case, the path is that of the previously modified external_flash_driver_oem.json file:
   

   images = {"ns_app"   : "../../Binary/JSON/ns_app_oem.json",
             "module_0" : "../../Binary/JSON/module_oem.json",
             "external_flash_driver" : "../../Binary/JSON/external_flash_driver_oem.json"
   

4.3.3. Step 3: SFI image generation

Open a terminal in the Projects\STM32H573I-DK\ROT_Provisioning\SM folder and execute the following command:

python provisioning.py --sfi-gen -a

Information

In the step above, there is no difference between the generation of an SFI with a global license and that with a chip-specific license.

This generates the SFI image. If the file is not renamed, the important files for the installation are listed in the table below:

Files	Large profile	External Flash profile
License of the SFI	If a global license was selected for the installation of the SFI: SM\Keys\SFI_Global_License.bin If a chip-specific license was selected for the installation of the SFI: The HSM card for the SFI must be retained
SFI	SM\Binary\Output\Profile_Large\SecureManagerPackage.sfi	SM\Binary\Output\Profile_External_Flash\SecureManagerPackage.sfix
If there is a secure module	SM\Binary\Output\Profile_Large\modules.mcsv	SM\Binary\Output\Profile_External_Flash\modules.ecsv
	The secure module itself, with the same path provided during the configuration phase. The global license (if any), with the same path provided during the secure module with a global license phase. The HSM card in case of a secure module with chip-specific license.

4.3.4. Step 4: SFI installation

To test the SFI before the programming phase at the OEM-CM manufacturer, make sure that all files generated during the previous step remain in the same location.

1. Connect the STM32H573I-DK using the USB Type-C® cable.
2. If a chip-specific license was selected for the installation of the SFI:
   The HSM card for the SFI must be plugged in the smart-card reader slot defined in SFI with chip-specific license.
3. If a chip-specific license was selected for the installation of the module:
   The HSM card for the module must be plugged into a different smart-card reader than the one used for the HSM, if applicable.
4. Open a terminal in the SM folder and execute the following command:
   

   python provisioning.py --sfi-flash -a
   

Information

For the command above, all files from step 3 must retain their original names.

The SFI image is now installed. The OEM application and secure module (if any) are running on the target device and are ready for testing.

If the installation fails:

• Check the SM\provisioning.log file.
• Perform a regression by opening a terminal in the X-CUBE-SEC-M-H5_VX.Y.Z\Projects\STM32H573I-DK\ROT_Provisioning\DA\ folder and execute the command below:

  python da.py --regression
  

  Then, repeat steps 3 and 4.

5. Secure firmware installation (programmed during OEM-CM manufacturing)

In this step, the contract manufacturer (CM) receives the following from the OEM:

• The SFI image to be installed (SecureManagerPackage.{sfi|sfix})
• The SFI global license (SFI_Global_License.bin) or, in the case of an SFI chip-specific license, the HSM card provisioned with the OEM key and initialized with a maximum number of licenses
• In the case of a secure module:
  • The secure module information (modules.{mcsv|ecsv})
  • The global license file (3rdPartyGlobalLicense.bin) or, in the case of a secure module chip-specific license, the HSM card provisioned with the secure module secret key and initialized with a maximum number of licenses

The SFI process can be performed through a regular JTAG/SWD interface or the system bootloader interface. Refer to the application note AN2606 for further details on the supported interface for each microcontroller).

5.1. Hardware

STM32H573I-DK board

5.2. Target initial state

The target must be in "Open" product state. In the manufacturing use-case, this is the default product state.

If the target is not in an "Open" state, a full debug authentication (DA) regression must be performed by launching a terminal in X-CUBE-SEC-M-H5_VX.Y.Z\Projects\STM32H573I-DK\ROT_Provisioning\DA and executing the following command:

python da.py --regression

The device is now ready for the SFI process.

5.3. Secure firmware install

All commands below presume that the following files are in the same folder as STM32_Programmer_CLI.exe. If this is not the case, adapt the path accordingly:

• SecureManagerPackage.sfi/SecureManagerPackage.sfix
• SFI_Global_License.bin
• modules.mcsv/modules.ecsv (making sure this file uses the correct paths)
• RSSe: X-CUBE-SEC-M-H5_VX.Y.Z\Projects\STM32H573I-DK\ROT_Provisioning\SM\Binary\RSSe_SFI_H56x_H573_v3.1.0.bin

The table below summarizes all possible commands for both profiles:

Profile	Base	SFI	SFI license	External Loader	RSSe	Secure module (if any)
Large profile	STM32_Programmer_CLI.exe -log sfi.log -c port=SWD mode=HotPlug -vb 1	-sfi SecureManagerPackage.sfi	Global license: hsm=0 SFI_Global_License.bin Chip-specific license: hsm=1 slot=1 Note: The slot number can be updated to match the use-case.		-rsse RSSe_SFI_H56x_H573_v3.1.0.bin	-mcsv modules.mcsv
External Flash profile		-sfi SecureManagerPackage.sfix		-el ./ExternalLoader/MX25LM51245G_STM32H573I-DK-RevB-SFIx.stldr		-ecsv modules.ecsv

Before running a command:

• If a chip-specific license was selected for the installation of the SFI:
  The HSM card for the SFI must be plugged into the smart-card reader slot defined in the "SFI license" column of the table above.
• If a chip-specific license was selected for the installation of the module:
  The HSM card for the module must be plugged into a smart-card reader other than the one used for the SFI HSM, if applicable.

The extract below shows an example command for the Large profile with a global SFI license and a secure module.

STM32_Programmer_CLI.exe -log sfi.log -c port=SWD mode=HotPlug -vb 1 -sfi SecureManagerPackage.sfi hsm=0 SFI_Global_License.bin -rsse RSSe_SFI_H56x_H573_v3.1.0.bin -mcsv modules.mcsv

The extract below shows an example command for the External Flash profile, with a chip-specific SFI license and without a secure module.

STM32_Programmer_CLI.exe -log sfi.log -c port=SWD mode=HotPlug -vb 1 -sfi SecureManagerPackage.sfix hsm=1 slot=1 -el ./ExternalLoader/MX25LM51245G_STM32H573I-DK-RevB-SFIx.stldr -rsse RSSe_SFI_H56x_H573_v3.1.0.bin

The process log is stored in the sfi.log file.

Information

Refer to the application note AN5054 for further details on HSM and slot parameters.

The device is programmed with the Secure Manager, the secure module, the nonsecure OEM application, and the option bytes. The product state is now "Closed" or "Locked".

Warning

Contrary to the "Closed" product state, the "Locked" product state prohibits any form of debug reopening and regression.

5.4. Troubleshooting

If an error eccors:

• Check sfi.log.
• If the device is not in the "Locked" state, open a terminal in the X-CUBE-SEC-M-H5_VX.Y.Z\Projects\STM32H573I-DK\ROT_Provisioning\DA folder and execute the command below to return to the "Open" state and relaunch the SFI procedure:
  

  python da.py --regression
  

6. Further reading

• Introduction to secure firmware install (SFI) for STM32 MCUs (AN4992, available from st.com)
• Third-party programmers guide for STM32H5 MCUs (AN6035, available upon request from an STMicroelectronics sales representative)
• Introduction to SFI tools, bootloader, and RSS interface for STM32 MCUs (AN5391, available upon request from an STMicroelectronics sales representative)