SFIx Step-by-step on STM32H735 Discovery Kit

SFIx Step-by-step on STM32H735G-DK75min

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 Discovery kit with STM32H735IG MCU with Bootloader version 9.3 min

• STM32-HSM SAM for Secure Firmware Installation
• Smartcard reader
  • Laptop built-in
  • External

• STLINK-V3 modular in-circuit debugger and programmer for STM32/STM8
• USB cable Type-A to Micro-B
• Jump wires

Software

• STM32CubeProgrammer Software programming tool for STM32 (v2.10 min)
  • Including STM32TrustedPackageCreator
• STM32CubeMX STM32Cube initialization code generator
• STM32CubeIDE Integrated Development Environment for STM32
• X-CUBE-SFI Expansion package 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

Warning

OTFD Key address input is different from the encryption key file that we describe after. The encryption key file is used by HSM, not by OTFDEC for external firmware

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.

Information

In this paragraph, we use the STM32CubeIDE toolchain but the process is the same for EWARM and MDK-ARM toolchains

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.

Warning

The assumption is that the Secure Room is isolated and its resources are not accessible from the outside world.

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

Information

Encryption Key used by OTFDEC to decrypt external firmware installed via SFIx process can be defined by the user or randomly generated. In this wiki page, we describe how to use a Key defined by the user called "fixed key " in the xcube-sfi example. The key is placed in a known address in user flash. The other option is to use a random key. In this case, the user chooses an address in user flash where the key is randomly generated. The key area file is used only in this case. In the xcube-sfi package, the script used to generate the sfix package using the key area file is called GenerateSFIx_Random_Key_OEM_Dev.bat For more information refer to use cases "generation of SFIx with the key area" described in AN5054 Secure programming using STM32CubeProgrammer

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:

Information

Command line below must be launched from the path: C:\Program Files\STMicroelectronics\STM32Cube\STM32CubeProgrammer\bin . Files called in the command line must also be saved in this folder.

 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.

Information

X-CUBE-SFI package uses command line interface to generate SFI package. If you want to use this CLI, you can manage a script with your directories. If you prefer GUI (graphical user interface) follow the next paragraph

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.

Information

The Option Bytes regression step configures the OB to their default state (this operation may not be needed if the CM runs the SFI process on a virgin part).

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

Information

You can also use the script placed in C:\X-Cube-SFI_V1.0.0\Projects\STM32H735G-DK\Applications\SFIx\CM\Scripts: ReadHSMInfo.bat to read HSM information PrepareTarget_SWD.bat to prepare target to SFI process and erase external memory FlashSFIx_SWD_OEM_Dev.bat to start the SFIx process and proceed with the installation

Information

You can refer to AN5054 for details on ST-HSM and slot parameters.

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.