SFIx Step-by-step on STM32H735G-DK
75min
Target description
This tutorial shows how to use SFI for installing:
- Secure internal firmware
- Secure external firmware.
On this page, we provide an example of Discovery kit STM32H735-DK, the internal firmware to install to the flash memory of the STM32H735 chip, and the external firmware to install to the external memory embedded on the board: MX25LM51245G.
The process goes through three steps at the OEM (original equipment manufacturer) and the CM (Contract Manufacturer) sites.
- Development @ OEM: the application code that runs on STM32 is generated.
- Secure Room @ OEM: code prepared during the development is encrypted and packaged to be sent for manufacturing. The Secure Room is isolated, and its resources are not visible outside of it.
- Manufacturing @ CM: the encrypted code received by the OEM Secure Room is installed using SFI tools.
Prerequisites
- Knowledge of STM32CubeProgrammer
- Knowledge of JTAG/SWD Interface
- STM32CubeMX introduction
Hardware
- STM32H735-DK[1] Discovery kit with STM32H735IG MCU with Bootloader version 9.3 min
- STM32-HSM[2] SAM for Secure Firmware Installation
- Smartcard reader
- Laptop built-in
- External
- STLINK-V3[3] modular in-circuit debugger and programmer for STM32/STM8
- USB cable Type-A to Micro-B
- Jump wires
Software
- STM32CubeProgrammer[4] Software programming tool for STM32 (v2.10 min)
- Including STM32TrustedPackageCreator
- STM32CubeMX[5] STM32Cube initialization code generator
- STM32CubeIDE[6] Integrated Development Environment for STM32
- X-CUBE-SFI Expansion package[7] The STM32CubeExpansion_SFI Secure Firmware Install shows how to go through SFI installation process for STM32 devices to protect OEM firmware during the CM product manufacturing stage.
Literature
- AN4992 STM32 MCUs secure firmware install (SFI) overview
- UM2237 STM32CubeProgrammer software description
- UM2238 STM32 Trusted Package Creator tool software description
- AN5054 Secure programming using STM32CubeProgrammer
- AN2606 STM32 microcontroller system memory boot mode
- RM0468 STM32H723/733, STM32H725/735 and STM32H730 Value line advanced Arm®-based 32-bit MCUs
- UM2679 STM32H735G-DK Discovery kit
- UM2448 STLINK-V3SET debugger/programmer for STM8 and STM32
- STM32HSM-V2 Data brief HSM v2
1. Environment setup
Before starting, the first step is to prepare the environment to go through the SFI process.
Refer to the Environment setup on the article: Step1 Tools installation
2. Development @ OEM: Firmware creation
The first step is to create a code containing data to install in the external memory. This code is called "External firmware". The second step of the process is to create a demo application for STM32H735G-DK using OTFDEC to decrypt the code installed in external memory. This code is called "Internal firmware".
You can use the example project developed in X-CUBE-SFI or create a new project.
2.1. External firmware
The firmware to install in external memory with the SFIx process is encrypted by the RSS.
RSS uses the AES algorithm (advanced encryption standard) to encrypt the external firmware.
OTFD Key address, region number, and region mode are given by the user during the SFIx process as input parameters.
OTFD region_number values:
- 0 to 3: OTFD1
- 4 to 7: OTFD2
OTFD region_mode (uint32_t) bit [1:0]:
- 0: instruction only (AES-CTR)
- 1: data only (AES-CTR)
- 2: instruction + data (AES-CTR)
- 3: instruction only (Enhanced cipher)
OTFD key_address in internal flash memory
For this example, we use known data as external firmware saved in a binary file.
This data is encrypted by RSS during the SFIx process using OTFD Key.
X-CUBE-SFI package gives an example of external firmware: Ext_Mem.bin placed in X-Cube-SFI_V1.0.0\Projects\STM32H735G-DK\Applications\SFIx\OEM_SecureRoom\Binary
You can open this file with STM32CubeProgrammer:
2.2. Internal firmware
The functionality of the internal firmware in our example is to decrypt via OTFDEC data saved in the external memory during SFIx operation.
X-CUBE-SFI already propose an application binary for STM32H735G-DK.
In the package X-CUBE-SFI you can find the application in OEM_Dev: Path: X-Cube-SFI_V1.0.0\Projects\STM32H735G-DK\Applications\SFIx\OEM_Dev.
Choose the toolchain you want to use (EWARM, MDK-ARM, or STM32CubeIDE) and compile the code. This page explains how to compile the code with the STM32CubeIDE toolchain:
Open folder "STM32CubeIDE" , then double click on .cproject. Select a directory as a workspace and launch the IDE. Once the workspace is successfully imported, select Project > Build Project. This generates the binary file we use in the next paragraphs.
In the file "main.c" of the project you can see the declaration of parameter uint32_t Plain[0x100].
This parameter contains exactly the data in clear that we want to flash in the external flash.
The Internal firmware:
- Configures OCTOSPI and OTFDEC interfaces
- Reads in external memory the data installed during the SFIx process
- Decrypts this data via OTFDEC
- Compares data decrypted with data in plain
- If the data is the same, the green LED is ON, else if data is different, the red LED is ON, and the green LED is OFF.
You can now close the STM32CubeIDE toolchain. Open X-CUBE-SFI package and in folder OEM_Dev\STM32CubeIDE, launch the TransferBinToSecureRoom.bat script needed to
- Create the OEM_SecureRoom/Binary folder
- Copy the binary generated by the compilation in this folder.
3. Secure Room @ OEM: SFIx package generation and HSM provisioning
In the Secure Room, the following two steps are performed:
- SFIx package generation: Option bytes configuration and code prepared during the development are encrypted and packaged to be sent for manufacturing.
- HSM Provisioning: the HSM is provisioned with the keys used for encryption and with the max license counter.
3.1. SFIx package generation
10min
In this step, the application binary files and the option byte configuration are encrypted in an SFIx package.
The following inputs are needed:
- External firmware binary file (created in the previous step), download address in external FLASH region number and mode (used by RSS)
- Internal firmware binary file (created in the previous step) and download address in FLASH.
- Key binary file used by RSS to encrypt external firmware
- AES Key
- Nonce
- Option bytes
3.1.1. Inputs preparation
For the two first input parameters above the process is described below.
For other parameters refer to the SFI package generation in the article: SFI package generation
3.1.1.1. External Firmware binary files and download address
For this example, we install external firmware in address 0x90000000. For external firmware, it is necessary to give:
- Region number
- Region mode
- AES key address
These parameters are used by RSS to encrypt external firmware. In our case
- Region number = 0
- Region mode = 2
- AES key address = 0x080C0000
3.1.1.2. Key binary file used by RSS to encrypt external firmware
RSS uses this Key to encrypt external firmware. This Key has to be installed in a known address of the flash memory. In this example, we use 0x080C0000. X-CUBE-SFI package shows a key example: Fixed_Key.bin in X-Cube-SFI_V1.0.0\Projects\STM32H735G-DK\Applications\SFIx\OEM_SecureRoom\Binary
Note that in X-CUBE-SFI package internal firmware, we use the same key to decrypt external firmware via OTFDEC to recover clear data.
3.1.2. SFI package generation using STM32 Trusted Package Creator CLI (command line interface)
3.1.2.1. Command launched from STM32CubeProgrammer\bin folder
You can use this command line to generate sfi package:
STM32TrustedPackageCreator_CLI.exe -sfi -fir OEM_Dev.bin 0x08000000 -fir Fixed_Key.bin 0x080C0000 -firx Ext_Mem.bin 0x90000000 0 2 0x080C0000 -k aeskey.bin -n nonce.bin -ob ob.csv -v 1 --ramsize 0x1E000 --token 0x080FF000 -hash 1 -o OEM_Dev.sfix
3.1.2.2. Command launched from another folder (X-CUBE-SFI example)
X-CUBE-SFI package gives an example of a script used to generate the output file from another directory.
In Folder "Scripts" in X-Cube-SFI_V1.0.0\Projects\STM32H735G-DK\Applications\SFIx\OEM_SecureRoom\Scripts, you can open the script "GenerateSFIx_Fixed_Key_OEM_Dev.bat" with Notepad for example.
Script description:
- STM32TrustedPackageCreator executable Path is defined in "TOOLDIR":
SET TOOLDIR=c:\Program Files\STMicroelectronics\STM32Cube\STM32CubeProgrammer\bin.
SET TOOL=%TOOLDIR%\STM32TrustedPackageCreator_CLI.exe
- Files previously created are set as "KEY", "NONCE" and "OPTBYTE" parameters:
SET SECURE_ROOM=..\..\OEM_SecureRoom
SET KEYDIR=%SECURE_ROOM%\Keys
SET KEY=%KEYDIR%\aeskey.bin
SET NONCE=%KEYDIR%\nonce.bin
SET OPTION_BYTES_DIR=%SECURE_ROOM%\OptionBytes
SET OPTBYTE=%OPTION_BYTES_DIR%\ob.csv
- Internal Firmware binary file and address are defined as "BINARY", and "BINARY_BASE_ADD".
SET APP_INPUT_DIR=%SECURE_ROOM%\Binary
SET BINARY=%APP_INPUT_DIR%\OEM_Dev.bin
SET BINARY_BASE_ADD=0x08000000
- An additional firmware binary file containing OTFDEC Key used by RSS to encrypt external firmware is defined as "KEY_BINARY" at address "KEY_BINARY_BASE_ADD".
SET KEY_BINARY=%APP_INPUT_DIR%\Fixed_Key.bin
SET KEY_BINARY_BASE_ADD=0x080C0000
- External binary and address are defined as "OTFDEC_BINARY", and "OTFDEC_BINARY_BASE_ADD".
For external firmware, we also have to enter the Region number "OTFDEC_REGION_NUMBER" and region mode "OTFDEC_REGION_MODE".
SET OTFDEC_BINARY=%APP_INPUT_DIR%\Ext_Mem.bin
SET OTFDEC_BINARY_BASE_ADD=0x90000000
SET OTFDEC_REGION_NUMBER=0
SET OTFDEC_REGION_MODE=2
- Image version is marked "0", Output sfix file is created in "OUT_BIN" path as "OUT_FILE" (OEM_Dev.sfix):
SET OUT_BIN=..\Binary
SET OUT_FILE=%OUT_BIN%\OEM_Dev.sfix
SET VERSION=0
- At least we can launch the command line calling all previously defined parameters:
"%TOOL%" -sfi -fir %BINARY% %BINARY_BASE_ADD% -fir %KEY_BINARY% %KEY_BINARY_BASE_ADD% -firx %OTFDEC_BINARY% %OTFDEC_BINARY_BASE_ADD% %OTFDEC_REGION_NUMBER% %OTFDEC_REGION_MODE% %KEY_BINARY_BASE_ADD% -k %KEY% -n %NONCE% -ob %OPTBYTE% -v %VERSION% --ramsize 0x1E000 --token 0x080FF000 -hash 1 -o %OUT_FILE%
Once launched the succeed message displays:
Output file with sfix extension is now generated, and you can transfer this file in the binary folder used in the last step launching "TransferSFIxToCM.bat" script placed in this directory: X-Cube-SFI_V1.0.0\Projects\STM32H735G-DK\Applications\SFIx\OEM_SecureRoom\Scripts.
3.1.3. SFI package generation using STM32 Trusted Package Creator GUI (graphical user interface)
SFIx panel of STM32TrustedPackageCreator, enter parameters described in Inputs preparation
External firmware parameters:
Once all parameters are browsed you can click on "Generate SFIx" button.
The right panel displays the size of the package generated, and the address it is installed in the flash memory.
3.2. HSM programming
Refer to the HSM programming on the article: HSM programming
4. Manufacturing @ CM: secure firmware installation
In this step, the CM receives from the OEM the HSM card provisioned with the secret key and initialized with a max counter of licenses, and the sfi package to be installed (including the firmware in encrypted form and the option bytes configuration).
The SFI process could be performed through a regular SWD interface.
6min
4.1. Hardware connection
Plug a micro-USB cable into the ST-LINK connector (CN15) and make sure that JP7 is in the STLK position.
4.2. Option bytes regression
The following steps configure the device to regress the option bytes configuration to a default state:
STM32_Programmer_CLI.exe -c port=SWD mode=HOTPLUG -ob RDP=0xAA nWRP0=1 nWRP1=1 nWRP2=1 nWRP3=1 nWRP4=1 nWRP5=1 nWRP6=1 nWRP7=1 BOOT_CM7_ADD0=0x0800 BOOT_CM7_ADD1=0x1FF0 SECURITY=0 -e all -rst -ob displ
The external memory of the board must be erased before starting the SFIx process. To erase external memory:
- Plug a micro-USB cable into the ST-LINK connector (CN15) and make sure that JP7 is in the STLK position.
- Launch STM32CubeProgrammer, go to the "Erasing & Programming" tab, and then "Erase external memory". You can then erase the full external flash, or select the sectors to erase and wait operation completed:
After this step, the device is ready for the SFIx process.
4.3. Firmware install
This command starts the SFI process and proceeds with the installation.
The command line below must be launched from the path: C:\Program Files\STMicroelectronics\STM32Cube\STM32CubeProgrammer\bin. OEM_Dev.sfix is the output sfix file previously generated, and MX25LM51245G_STM32H735G-DK.stldr file is the external loader needed to access external memory used in this board: MX25LM51245G. These two files must be saved in the C:\Program Files\STMicroelectronics\STM32Cube\STM32CubeProgrammer\bin path to launch the command.
You can find all external loader files in the folder ExternalLoader:
path: C:\Program Files\STMicroelectronics\STM32Cube\STM32CubeProgrammer\bin\ExternalLoader
STM32_Programmer_CLI.exe -vb 1 -c port=SWD mode=HOTPLUG reset=crst -sfi protocol=static OEM_Dev.sfix hsm=1 slot=1 -el MX25LM51245G_STM32H735G-DK.stldr hsm=1 slot=1
After this step, the device is programmed with the OEM application code. Green led is ON: The data installed in external memory is decrypted via OTFDEC and compared to clear data.
5. References