1. Applicable products
Here is the list of 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 the SFI image test rely on the Secure Manager Access Kit (SMAK).
Follow SMAK prerequisites and SMAK package contents for the SFI environment setup.
3. Development at OEM offices: firmware creation
The purpose of this SFI service is to securely install the OEM firmware developed with Secure Manager.
Therefore, to use this SFI service, the OEM must develop its nonsecure application during the SMAK development phase.
The OEM firmware file is .hex extension.
STMicroelectronics provides an application to build STM32Cube_FW_H5_VX.X.X\Projects\STM32H573I-DK\Applications\ROT\SMAK_Appli\Binary\appli_enc_sign.hex.
4. Secure room at OEM offices: SFI image generation and HSM provisioning at OEM trusted offices
4.1. HSM programming
If you want to install your SFI with a chip-specific license, you need to program a STM32HSM-V2.
Inputs for HSM programming:
- OEM key (encryption AES key + nonce)
To program the HSM, you can follow the steps described in HSM programming.
After programming the HSM, it is now ready to be shipped to the Contract Manufacturer (CM) together With the SFI that will be created in SFI image generation
4.2. Generating a global license
If you want to install your SFI with a global license, simply follow the Generation and installation of the SFI
4.3. SFI image generation and installation
Once the OEM completes its nonsecure application development, the OEM must prepare and test the final encrypted image (SFI image) used for OEM secure manufacturing with the SMAK production preparation phase.
4.3.1. Step by step procedure
4.3.1.1. Step 1: Configuration
For this step, JSON and ini files will be modified. These files are designed to be customized and all the paths can be an absolute path or a relative path from the file itself
4.3.1.1.1. OEM Application
- Copy your OEM application in the Binary folder (named oem_app.hex hereafter)
cp oem_app.hex STM32Cube_FW_H5_VX.X.X\Projects\STM32H573I-DK\ROT_Provisioning\SM\Binary
- Copy the JSON template in the Binary folder :
cp STM32Cube_FW_H5_VX.X.X\Projects\STM32H573I-DK\ROT_Provisioning\SM\Binary\JSON\Templates\ns_app_template.json STM32Cube_FW_H5_VX.X.X\Projects\STM32H573I-DK\ROT_Provisioning\SM\Binary\JSON\ns_app_oem.json
This JSON file specifies to ROT_Provisioning\SM\provisioning.py the path of a nonsecure application to be installed in the SFI procedure.
- Modify the content of ns_app_oem.json by replacing the existing path with the path to your OEM application as shown in the code snippet below:
"binary":"../../Binary/oem_app.hex"
- Finally, modify STM32Cube_FW_H5_VX.X.X\Projects\STM32H573I-DK\ROT_Provisioning\SM\Config\sm.ini.
In this file, the dictionary images must contain a key "ns_app" and a corresponding path to a JSON file. In this case, the path is the path to ns_app_oem.json previously modified:
images = {"ns_app" : "../Binary/JSON/ns_app_oem.json",
4.3.1.1.2. Factory Internal Trusted Storage (FITS)
If you want to include a Factory ITS in your SFI, follow these steps below:
- Copy the default JSON in the Binary folder :
cp STM32Cube_FW_H5_VX.X.X\Projects\STM32H573I-DK\ROT_Provisioning\SM\Binary\JSON\fits_default.json STM32Cube_FW_H5_VX.X.X\Projects\STM32H573I-DK\ROT_Provisioning\SM\Binary\JSON\fits_oem.json
This JSON file specifies to ROT_Provisioning\SM\provisioning.py the path of a Factory ITS blob to be installed in the SFI procedure.
- Prepare your own FITS with your data or keys by following Factory ITS blob preparation
- Modify the content of fits_oem.json by replacing the existing path of the key
"binary"with the path to your FITS if you changed the default name:
{
"binary":"../ITS_Factory_Blob.bin",
"xml":"../../Images/SM_ITS.xml",
"auto_update":true
}
- Finally, modify STM32Cube_FW_H5_VX.X.X\Projects\STM32H573I-DK\ROT_Provisioning\SM\Config\sm.ini.
In this file, the dictionary images must contain a key "FITS" and a corresponding path to a JSON file. In this case, the path is the path to fits_oem.json previously copied:
images = {"ns_app" : "../Binary/JSON/ns_app_oem.json",
"module_0" : "../Binary/JSON/module_default.json",
"FITS" : "../Binary/JSON/fits_oem.json"}
If you don't want to include a Factory ITS in your SFI
- Modify STM32Cube_FW_H5_VX.X.X\Projects\STM32H573I-DK\ROT_Provisioning\SM\Config\sm.ini.
In this file, you should delete the key "FITS" in the dictionary images as the code snipper shown below:
With FITS:
images = {"ns_app" : "../Binary/JSON/ns_app_default.json",
"module_0" : "../Binary/JSON/module_default.json",
"FITS" : "../Binary/JSON/fits_default.json"}
Without FITS:
images = {"ns_app" : "../Binary/JSON/ns_app_default.json",
"module_0" : "../Binary/JSON/module_default.json"}
4.3.1.1.3. Secure module without license
- Copy your secure module in the Binary folder (named oem_module.hex hereafter):
cp module.hex STM32Cube_FW_H5_VX.X.X\Projects\STM32H573I-DK\ROT_Provisioning\SM\Binary
- Copy the JSON template in the Binary folder :
cp STM32Cube_FW_H5_VX.X.X\Projects\STM32H573I-DK\ROT_Provisioning\SM\Binary\JSON\Templates\module_template.json STM32Cube_FW_H5_VX.X.X\Projects\STM32H573I-DK\ROT_Provisioning\SM\Binary\JSON\module_oem.json
This JSON file specifies to ROT_Provisioning\SM\provisioning.py the path of a secure module to be installed in the SFI procedure.
- Modify the content of module_oem.json by replacing the existing path with the path to your OEM secure module as shown in the code snippet below:
"binary":"../../Binary/oem_module.hex"
- Finally, modify STM32Cube_FW_H5_VX.X.X\Projects\STM32H573I-DK\ROT_Provisioning\SM\Config\sm.ini.
In this file, the dictionary images must contain a key "module_0" and a corresponding path to a JSON file. In this case, the path is the path to module_oem.json previously modified:
images = {"ns_app" : "../Binary/JSON/ns_app_oem.json",
"module_0" : "../Binary/JSON/module_oem.json",
4.3.1.1.4. Secure module with a global license
- Copy your third-party secure module (3rdPartyModule.smu) and its license (3rdPartyGlobalLicense.bin) in the Binary folder:
cp 3rdPartyModule.smu STM32Cube_FW_H5_VX.X.X\Projects\STM32H573I-DK\ROT_Provisioning\SM\Binary
cp 3rdPartyGlobalLicense.bin STM32Cube_FW_H5_VX.X.X\Projects\STM32H573I-DK\ROT_Provisioning\SM\Binary
- Copy the JSON template in the Binary folder :
cp STM32Cube_FW_H5_VX.X.X\Projects\STM32H573I-DK\ROT_Provisioning\SM\Binary\JSON\Templates\module_with_global_license_template.json STM32Cube_FW_H5_VX.X.X\Projects\STM32H573I-DK\ROT_Provisioning\SM\Binary\JSON\module_with_global_license.json
This JSON file specifies to ROT_Provisioning\SM\provisioning.py the paths of a third-party secure module with its license to be installed in the SFI procedure.
- Modify the content of module_with_global_license.json by replacing the existing paths with the path to your third-party secure module and its license as shown in the code snippet below:
"binary":"../../Binary/3rdPartyModule.smu",
"license":"../../Binary/3rdPartyGlobalLicense.bin"
- Finally, modify STM32Cube_FW_H5_VX.X.X\Projects\STM32H573I-DK\ROT_Provisioning\SM\Config\sm.ini.
In this file, the dictionary images must contain a key "module_0" and a corresponding path to a JSON file. In this case, the path is the path to module_with_global_license.json previously modified:
images = {"ns_app" : "../Binary/JSON/ns_app_oem.json",
"module_0" : "../Binary/JSON/module_with_global_license.json",
4.3.1.1.5. Secure module with a chip-specific license
- Copy your third-party secure module in the Binary folder (named 3rdPartyModule.smu hereafter):
cp 3rdPartyModule.smu STM32Cube_FW_H5_VX.X.X\Projects\STM32H573I-DK\ROT_Provisioning\SM\Binary
- Copy the JSON template in the Binary folder :
cp STM32Cube_FW_H5_VX.X.X\Projects\STM32H573I-DK\ROT_Provisioning\SM\Binary\JSON\Templates\module_with_chip_specific_license_template.json STM32Cube_FW_H5_VX.X.X\Projects\STM32H573I-DK\ROT_Provisioning\SM\Binary\JSON\module_with_chip_specific_license.json
This JSON file specifies to ROT_Provisioning\SM\provisioning.py the path of a third-party secure module with a chip-specific license to be installed in the SFI procedure.
- Modify the content of module_with_chip_specific_license.json by replacing the existing path with the path to your third-party secure module as shown in the code snippet below:
"binary":"../../Binary/3rdPartyModule.smu"
- Finally, modify STM32Cube_FW_H5_VX.X.X\Projects\STM32H573I-DK\ROT_Provisioning\SM\Config\sm.ini.
In this file, the dictionary images must contain a key "module_0" and a corresponding path to a JSON file. In this case, the path is the path to module_with_chip_specific_license.json previously modified:
images = {"ns_app" : "../Binary/JSON/ns_app_oem.json",
"module_0" : "../Binary/JSON/module_with_chip_specific_license.json",
4.3.1.2. Step 2: Generation of the SFI
Follow Script provisioning.py step 1: Configuration.
After these steps, the SFI image is generated.
If no renaming, the important files for the installation are located in:
- STM32Cube_FW_H5_VX.X.X\Projects\STM32H573I-DK\ROT_Provisioning\SM\Binary\SecureManagerPackage.sfi The SFI image ready for testing
- STM32Cube_FW_H5_VX.X.X\Projects\STM32H573I-DK\ROT_Provisioning\SM\Keys\SFI_Global_License.bin The SFI global license
If there is a secure module, these files must be also kept:
- STM32Cube_FW_H5_VX.X.X\Projects\STM32H573I-DK\ROT_Provisioning\SM\Binary\modules.mcsv This file contains the secure module information's
- 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 configuration of a secure module with a global license phase
- The HSM card in case of a secure module with chip-specific license
4.3.1.3. Step 3: Installation of the SFI
Follow Script provisioning.py step 2: Installation.
After these steps, the SFI image is installed. The OEM application and secure module (if any) are running on target and ready for tests.
In case of issue:
- Check the STM32Cube_FW_H5_VX.X.X\Projects\STM32H573I-DK\ROT_Provisioning\SM\provisioning.log file
- Perform a regression by opening a terminal in STM32Cube_FW_H5_VX.X.X\Projects\STM32H573I-DK\ROT_Provisioning\SM\ and execute the command below:
python provisioning.py --regression -a
5. Programming at OEM-CM manufacturing: Secure Firmware Installation
In this step, the CM receives from the OEM:
- The SFI image to be installed (SecureManagerPackage.sfi)
- The SFI global license (SFI_Global_License.bin) or in case of SFI chip-specific license, the HSM card provisioned with the OEM key and initialized with a max counter of licenses
- In case of secure module:
- The secure module information's (modules.mcsv)
- The secure module itself
- In case of a secure module with a global license, the global license file (3rdPartyGlobalLicense.bin) or in case of a secure module chip-specific license, the HSM card provisioned with the secure module secret key and initialized with a max counter of licenses
The SFI process could be performed through a regular JTAG/SWD interface or the system bootloader interface (you can refer to the application note AN2606[1] for details on the supported interface for each microcontroller).
The following covers the JTAG/SWD and system bootloader interface for each of the sections below:
- Hardware connection
- Software adaptation
- Target initial state
- Secure firmware install
5.1. Hardware connection
5.1.1. Board
5.1.2. HSM card
Plug your HSM card provisioned with the SFI OEM key in case of SFI chip-specific license.
Let us assume that the HSM card is plugged in the smart card reader slot 1.
Plug your HSM card provisioned with the secure module secret key in case of secure module chip-specific license.
Let us assume that the HSM card is plugged in the smart card reader slot 2.
5.2. Target initial state
The target must be in Open product state. As you are in a manufacturing use case, this should be the default state.
If it is not the case, a debug authentication (DA) full regression must be performed by opening a terminal in STM32Cube_FW_H5_VX.X.X\Projects\STM32H573I-DK\ROT_Provisioning\SM.
python provisioning.py --regression -a
After this step, the device is ready for the SFI process.
5.3. Secure Firmware Install
This command starts the SFI process:
- With SFI global license
- Without secure module
and proceeds with the installation
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\H5\enc_signed_RSSe_SFI_STM32H5_2M_v2.0.1.0.bin
This command starts the SFI process with:
- With SFI chip-specific license
- Secure module with or without license (global or chip-specific)
and proceeds with the installation:
STM32_Programmer_CLI.exe -log sfi.log -c port=SWD mode=HotPlug -vb 1 -sfi SecureManagerPackage.sfi hsm=1 slot=1 -rsse RSSe\H5\enc_signed_RSSe_SFI_STM32H5_2M_v2.0.1.0.bin -mcsv modules.mcsv
This command starts the SFI process with:
- With SFI global license
- Secure module with or without license (global or chip-specific)
and proceeds with the installation:
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\H5\enc_signed_RSSe_SFI_STM32H5_2M_v2.0.1.0.bin -mcsv modules.mcsv
You can check the log of the process saved in the file sfi.log:
-------------------------------------------------------------------
STM32CubeProgrammer v2.17.0
-------------------------------------------------------------------
Log output file: sfi.log
ST-LINK SN : 002500423232510239353236
ST-LINK FW : V3J12M3
Board : STM32H573I-DK
Voltage : 3.29V
Warning: Connection to AP 0 requested and failed, Connection established with AP 1
SWD freq : 8000 KHz
Connect mode: Hot Plug
Reset mode : Software reset
Device ID : 0x484
Revision ID : --
Device name : STM32H56x/573
Flash size : 2 MBytes
Device type : MCU
Device CPU : Cortex-M33
BL Version : 0xE4
SFSP Version: v2.5.0
Debug in Low Power mode enabled
Protocol Information : static
SFI File Information :
SFI file path : SecureManagerPackage.sfi
SFI HSM slot ID : 1
SFI header information :
SFI protocol version : 2
SFI total number of areas : 14
SFI image version : 0
SFI Areas information :
Parsing Area 1/14 :
Area type : H
Area size : 16
Area destination address : 0x0
Parsing Area 2/14 :
Area type : O
Area size : 112
Area destination address : 0xFFD0100
Parsing Area 3/14 :
Area type : O
Area size : 192
Area destination address : 0xFFD09D0
Parsing Area 4/14 :
Area type : O
Area size : 112
Area destination address : 0xFFD0A80
Parsing Area 5/14 :
Area type : O
Area size : 272
Area destination address : 0xFFD0200
Parsing Area 6/14 :
Area type : S
Area size : 110808
Area destination address : 0x0
Parsing Area 7/14 :
Area type : S
Area size : 128184
Area destination address : 0x0
Parsing Area 8/14 :
Area type : S
Area size : 77800
Area destination address : 0x0
Parsing Area 9/14 :
Area type : F
Area size : 51712
Area destination address : 0x8100000
Parsing Area 10/14 :
Area type : F
Area size : 928
Area destination address : 0x8185C60
Parsing Area 11/14 :
Area type : F
Area size : 528
Area destination address : 0x81A6000
Parsing Area 12/14 :
Area type : F
Area size : 48
Area destination address : 0x81A7FD0
Parsing Area 13/14 :
Area type : m
Area size : 131072
Area destination address : 0x8186000
Parsing Area 14/14 :
Area type : C
Area size : 48
Area destination address : 0x0
Reading the chip Certificate...
Requesting Chip Certificate from device ...
Reading chip Certificate finished
Get Certificate done successfully
requesting license for the current STM32 device
Init Communication ...
ldm_LoadModule(): loading module "C:/Program Files/STMicroelectronics/STM32Cube/STM32CubeProgrammer_v2.17.0/bin\stlibp11_SAM.dll" ...
ldm_LoadModule(WIN32): OK loading library "C:/Program Files/STMicroelectronics/STM32Cube/STM32CubeProgrammer_v2.17.0/bin\stlibp11_SAM.dll": 0xA91B0000 ...
C_GetFunctionList() returned 0x00000000, g_pFunctionList=0xA921E490
P11 lib initialization Success!
Opening session with slot ID 1...
Succeed to Open session with reader slot ID 1
Succeed to generate license for the current STM32 device
Closing session with reader slot ID 1...
Session closed with reader slot ID 1
Closing communication with HSM...
Communication closed with HSM
Succeed to get License for Firmware from HSM slot ID 1
Starting Firmware Install operation...
Reconnecting...
Reconnected !
Time elapsed during option Bytes configuration: 00:00:01.232
Reconnecting...
Reconnected !
Reconnecting...
Reconnected !
Time elapsed during option Bytes configuration: 00:00:02.438
ST-LINK SN : 002500423232510239353236
ST-LINK FW : V3J12M3
Board : STM32H573I-DK
Voltage : 3.29V
SWD freq : 8000 KHz
Connect mode: Hot Plug
Reset mode : Software reset
Device ID : 0x484
Revision ID : --
Warning: Option Byte: SECBOOT_LOCK, value: 0xC3, was not modified.
Warning: Option Bytes are unchanged, Data won't be downloaded
Time elapsed during option Bytes configuration: 00:00:00.014
Warning: Option Byte: SECBOOTADD, value: 0xC0000, was not modified.
Warning: Option Byte: SECWM1_END, value: 0x7F, was not modified.
Warning: Option Byte: SECWM1_STRT, value: 0x0, was not modified.
Warning: Option Byte: SECWM2_END, value: 0x7F, was not modified.
Warning: Option Byte: SECWM2_STRT, value: 0x0, was not modified.
Warning: Option Byte: SRAM1_3_RST, value: 0x1, was not modified.
Warning: Option Byte: SRAM2_ECC, value: 0x0, was not modified.
Warning: Option Byte: SRAM2_RST, value: 0x0, was not modified.
Warning: Option Bytes are unchanged, Data won't be downloaded
Time elapsed during option Bytes configuration: 00:00:00.015
ST-LINK SN : 002500423232510239353236
ST-LINK FW : V3J12M3
Board : STM32H573I-DK
Voltage : 3.29V
SWD freq : 8000 KHz
Connect mode: Hot Plug
Reset mode : Software reset
Device ID : 0x484
Revision ID : --
Reconnecting...
Reconnected !
Reconnecting...
Reconnected !
Time elapsed during option Bytes configuration: 00:00:03.062
ST-LINK SN : 002500423232510239353236
ST-LINK FW : V3J12M3
Board : STM32H573I-DK
Voltage : 3.29V
SWD freq : 8000 KHz
Connect mode: Hot Plug
Reset mode : Software reset
Device ID : 0x484
Revision ID : --
Installing RSSe
Memory Programming ...
Opening and parsing file: enc_signed_RSSe_SFI_STM32H5_2M_v2.0.1.0.bin
File : enc_signed_RSSe_SFI_STM32H5_2M_v2.0.1.0.bin
Size : 55.31 KB
Address : 0x20054100
Erasing memory corresponding to segment 0:
Download in Progress:
File download complete
Time elapsed during download operation: 00:00:00.120
MCU Reset
ST-LINK SN : 002500423232510239353236
ST-LINK FW : V3J12M3
Board : STM32H573I-DK
Voltage : 3.29V
SWD freq : 8000 KHz
Connect mode: Hot Plug
Reset mode : Software reset
Device ID : 0x484
Revision ID : --
Get RSSe status...
RSS version = 2.2.0
RSSe version = 2.0.1
Starting SFI
Processing license...
Get RSSe status...
Processing Image Header
Get RSSe status...
Processing Area 1...
Get RSSe status...
Area Address = 0x0
Area Type = H
Processing Area 2...
Get RSSe status...
Area Address = 0xFFD0100
Area Type = O
Processing Area 3...
Get RSSe status...
Area Address = 0xFFD09D0
Area Type = O
Processing Area 4...
Get RSSe status...
Area Address = 0xFFD0A80
Area Type = O
Processing Area 5...
Get RSSe status...
Area Address = 0xFFD0200
Area Type = O
Processing Area 6...
Get RSSe status...
Area Address = 0x0
Area Type = S
Processing Area 7...
Get RSSe status...
Area Address = 0x0
Area Type = S
Processing Area 8...
Get RSSe status...
Area Address = 0x0
Area Type = S
Processing Area 9...
Get RSSe status...
Area Address = 0x8100000
Area Type = F
Processing Area 10...
Get RSSe status...
Area Address = 0x8185C60
Area Type = F
Processing Area 11...
Get RSSe status...
Area Address = 0x81A6000
Area Type = F
Processing Area 12...
Get RSSe status...
Area Address = 0x81A7FD0
Area Type = F
MCSV file parsing...
Total modules number: 1
+ Module number : [0]
Name : ./my_module_0_enc_sign_prod.hex
Type : None
Size : 128.00 KB
Address : 0x08186000
Processing Area 13...
Get RSSe status...
Area Address = 0x8186000
Area Type = m
Processing Area 14...
---- Is Last SFI Area !! ----
Can not verify last area
Area Address = 0x0
Area Type = C
SFI Process Finished!
SFI file SecureManagerPackage.sfi Install Operation Success
Time elapsed during SFI install operation: 00:00:22.037
At this step, the device is programmed with the secure manager, the secure module, the OEM nonsecure application, and the option bytes. The product state is Closed or Locked.
5.4. Troubleshooting
In case of failure:
- check sfi.log
- if not in Locked state, open a terminal in STM32Cube_FW_H5_VX.X.X\Projects\STM32H573I-DK\ROT_Provisioning\DA and execute the command below to come back in Open state and be able to launch a new SFI procedur:
python da.py --regression
6. References
AN4992 [1] Introduction to secure firmware install (SFI) for STM32 MCUs
AN6035 Third party programmers guide for STM32H5 MCUs => contact STMicroelectronics sales representative.
AN5391 Introduction to SFI tools, bootloader, and RSS interface for STM32 MCUs => contact STMicroelectronics sales representative.