How to install a trusted application on STM32N6 MCUs

How to install a trusted application on STM32N6 MCUs

Literature

• UM2237 STM32CubeProgrammer software description
• AN5054 Secure programming using STM32CubeProgrammer
• BootRom wiki article
• Secure Boot wiki article
• Security features for STM32N6MCUs wiki article
• OEMuRoT for STM32N6

Prerequisites

• Hardware
  • STM32N6 discovery board
  • Discovery MB1860- STM32N6 (need USBC cable)

• Required tools
  • IAR: v9.40.1 + IAR patch to support STM32N6 (delivered with V0.5.0) + IAR Patch EWARMv9_STM32N6xx_V0.6.2
    • IAR patch is available in the STM32CubeFW: STM32Cube_FW_N6_Vx.x.x\Utilities\PC_Software
  • STM32CubeN6 FW version 1.0.0 or later
  • STM32CubeProgrammer version 2.18.0
  • Tera Term / Putty or equivalent terminal emulator

• STM32Cube Firmware
  • Download the STM32Cube_FW_N6 Cube firmware (advice is to place it close form the C: in order to avoid long windows paths).
  • A directory STM32N6-DK is included in "STM32Cube_FW_N6\Projects" .

• Open the env.bat file. If the STM32CubeProgrammer has not been installed in the default folder: C:\Program Files\STMicroelectronics\STM32Cube\STM32CubeProgrammer, the customized installation path needs to be updated:

1. Introduction

After this step by step you will know

• How to sign / encrypt a basic application (FSBL*) loaded by BootRom
• Which OTPs are concerned by BootRom Authenticity and integrity checks
• How to get the BootRom traces
• How to set the device in Secured-locked state

3 main steps:

1. Keys generation / provisioning in OTP
2. Application (FSBL*) generation and Flashing to external memory
3. FSBL* execution and locking the device

(*) FSBL: First stage bootloader/ Name of the application loaded by the boot ROM code

2. Keys Generation

BootRom secrets are:

• Keys used to sign the FSBL
• Keys used to encrypt/decrypt FSBL
• RMA password

In BootRom folder a script can be launched to generate these secrets.

Warning

If you already fused your OTPs in a previous operation with BootRom secrets (OTPs 160 to 167, 256 to 259, and 364 to 367),don't regenerate these keys: don't launch this script ! If you want to use the Keys provided by STM32CubeFW-N6 in Projects\STM32N6570-DK\ROT_Provisioning\BootROM\Keys folder , don't regenerate these keys: don't launch this script. If you regenerate these keys, the values fused in OTP won't be the same than the Keys values stored in the Keys folder and the encryption / signature of the FSBL will be wrong.

Warning

The keys_generation.bat script will overwrite all keys in the BootROM\Keys folder. Make sure to back up any existing keys before running this script.

If you want to generate your own secret keys, and if you didn't already fused tour OTPs(OTPs 160 to 167, 256 to 259, and 364 to 367), you can launch the script

keys-generation.bat (double click on it).

This script executes 3 command lines calling Keygen tool.

• The first command line generates the signing keys and the hash table composed of the hash of the eight public keys. rot1 to rot8 are the eight password associated to each private key.:

$ STM32MP_KeyGen_CLI.exe -abs %keys_pem_dir% -pwd rot1 rot2 rot3 rot4 rot5 rot6 rot7 rot8 -n 8

• The second command line generates a random RMA password:

$ STM32MP_KeyGen_CLI.exe -rand 16 RMA_password.bin

• The last command line generates a random Encryption secret file:

$ STM32MP_KeyGen_CLI.exe -rand 16 OEM_SECRET.bin

Information

If you want to regenerate only one or two keys you can execute the command line of your choice without launching the script

Once launched, this script generates the keys in Keys folder Projects\STM32N6570-DK\ROT_Provisioning\BootROM\Keys:

3. Keys provisioning

The keys previously generated must now be programmed in corresponding OTP words:

The Public key table hash (PKTH) is used to verify the authenticity of the FSBL and must be provisioned to OTP 160 to 167.

RMA password is used by ST in case of problem with the chip. OTPs allocated to RMA password are OTP 256 to 259.

OEM secret is used to encrypt / decrypt FSBL and must be programmed to OTP words 364 to 367.

Warning

Be careful before launching script Keys_Programming.bat , your keys can’t be changed anymore after burning OTP !! Once programmed , Keys folder must be kept his secret on a secure place in order to be able to sign and encrypt FSBL with same keys programmed in OTP

• Configure your board in Dev Boot mode:

da_programming.bat

• Launch keys-Programming.bat script (double click) in Projects\STM32N6570-DK\ROT_Provisioning\BootRom folder:

The script requests confirmation for each OTP programming: answer YES for the three requests.

Some warning messages are displayed after programming RMA password, it is OK:

A success message is displayed for each file programming:

4. Load a signed FSBL and get the BootRom traces

The keys are now programmed in OTP.

In this chapter, we learn how to sign the FSBL with the keys previously generated.

We will also use the templates given as example in Github to get the BootRom traces.

The BootRom traces are used to know if the FSBL is correctly signed: in secured-unlocked state the FSBL signature is checked by BootRom, but FSBL is executed even if signature is wrong.

In secured-locked state, if the signature is wrong the FSBL won't be executed → BootRom traces are used in secured-unlocked state to verify if FSBL is correctly signed before locking the device. They give the result of the signature and encryption checks.

4.1. Generate and compile FSBL

FSBL properties

• make user leds blinking
• print the BootRom traces to UART

Information

BootRom traces give the result of the BootRom signature check

FSBL example has been developed based on the template from STM32CubeFW_N6 located in Projects\STM32N6570-DK\Templates\Template folder.

From template, here are the functionalities added:

• BootRom traces
  • rom_trace_parser.c and rom_trace_parser.h respectively added to scr and inc folder of the application project
  • function void print_and_sort_sec_nsec_bootrom_traces(uint32_t buffer_size) added in main file and called at the beginning of the application
• UART connection → to display BootRom traces

Note that BootRom traces are stored in SRAM2 internal memory:

@0x341037F0: Secure BootRom traces address

@0x241077F0: Nonsecure BootRom traces address

Please load the application from Github:BootRom_traces

Download the code:

click to "Code", then "Download ZIP" :

Copy/paste the folder BootRom_Traces to Projects\STM32N6570-DK\ROT_Provisioning folder:

Copy/paste the folder Template_BootRom_traces to Projects\STM32N6570-DK\Templates folder:

Open the IAR project included in Template_BootRom_traces folder and compile it:

After build success, the image is generated in Templates \ Template_BootRom_traces \ EWARM \ FSBL\Template_BootRom_traces \ Exe.

This image is not signed, not encrypted. It also doesn't have a header.

Without header, this image won't be loaded by BootRom in secured-unlocked state neither in secured-locked state.

4.2. Sign and load the FSBL

In ROT_Provisioning\BootRom_Traces folder the script Sign_Load_FW.bat will first sign and add a header to the FSBL and then download it in external flash memory of the discovery board @0x7000'0000.

SigningTool command line to sign the FSBL:

$ STM32_SigningTool_CLI.exe -bin "%binary_file%" -pubk "%auth_key_pair0_pem%" "%auth_key_pair1_pem%" "%auth_key_pair2_pem%" "%auth_key_pair3_pem%" "%auth_key_pair4_pem%"  "%auth_key_pair5_pem%" "%auth_key_pair6_pem%" "%auth_key_pair7_pem%" -prvk "%auth_priv_key%" -pwd rot1 -iv 0x00000000 -of 0x00000001 -la 0x34180000 -t fsbl -o "%trusted_file%" -hv 2.3 -dump "%trusted_file%"

• Check that your board is connected to the computer in Dev Boot mode:

• Launch the script Sign_Load_FW.bat (double click)

→ The signed FSBL is now installed in external flash memory.

4.3. Execute the FSBL

Set the Flash boot configuration and launch Teraterm:

Press the reset button of the board and:

1- At reset, BootRom checks if an FSBL is installed in external flash memory

2- The BootRom copies the FSBL to Internal RAM download area. If FSBL is signed, it controls the signature

3- BootRom jumps into internal RAM and executes the FSBL directly from download area. (The FSBL size is limited to 512KB). User can get BootRom traces.

4.3.1. Case 1: FSBL correctly signed

From Teraterm you get these BootRom traces:

4.3.2. Case 2:FSBL signed with wrong keys

To test the signature with wrong keys, a repository Keys_wrong is included in ROT_Provisioning\BootRom_Traces which contains wrong keys example.

- Modify the script Sign_Load_FW.bat at line 9 and replace "pushd "%projectdir%"\..\BootROM\Keys" by "pushd "%projectdir%"\Keys_wrong",

- save it

- set the board configuration to dev mode

- launch the script Sign_Load_FW.bat

- execute the FSBL in Flash boot mode

Now, as you have signed the FSBL with wrong keys, you will get the following BootRom traces:

5. Load a signed and encrypted application and get the BootRom traces

During this step, the FSBL is be signed and encrypted.

First, follow these steps to erase the external memory sector previously programmed:

• Set the dev Boot configuration

• Open STM32CubeProgrammer and connect the board via ST-LINK
• Select the external flash loader:

• Erase the 512K of external memory:

If the encryption is done with wrong keys, the FSBL won't be executed in secured-unlocked state neither in secured-locked state.

The keys are already programmed in OTP.

5.1. Encrypt, sign and load the FSBL

In BootRom_Traces folder the script Sign_Encrypt_Load_FW.bat will

• generate a signed binary file with a header from the FSBL. This binary will be flashed @0x7000'0000

• generate a binary file with a header from the FSBL. This binary will be flashed @0x7004'0000

SigningTool command line to sign and encrypt the FSBL:

$ STM32_SigningTool_CLI.exe -bin "%binary_file%" -pubk "%auth_key_pair0_pem%" "%auth_key_pair1_pem%" "%auth_key_pair2_pem%" "%auth_key_pair3_pem%" "%auth_key_pair4_pem%"  "%auth_key_pair5_pem%" "%auth_key_pair6_pem%" "%auth_key_pair7_pem%" -prvk "%auth_priv_key%" -iv 0x00000000 -pwd rot1 -of 0x00000003 -la 0x34180000 -t fsbl -encdc 0x25205f0e -enck "%OEM_secret_file%" -o "%trusted_file%" -hv 2.3 -dump "%trusted_file%"

SigningTool command line to add a header to FSBL:

$ STM32_SigningTool_CLI.exe -bin "%binary_file%" -nk -iv 0x00000000 -of 0x80000000 -la 0x34180000 -t fsbl -o-o "%trusted_file%" -hv 2.3 -dump "%trusted_file%"

Check that your board is connected to the computer in Dev-Boot mode:

Launch the script Sign_Encrypt_Load_FW.bat (double click)

5.2. Execute the FSBL

Set the Flash boot configuration and launch Teraterm:

5.2.1. FSBL correctly signed and encrypted

If encryption and signature succeed here is the boot flow:

1- At reset BootRom checks if an FSBL is installed in external flash @0x7000'0000

2- The BootRom copies the signed and encrypted FSBL1 to Internal RAM download area.

BootRom controls signature and encryption.

3- Signature and encryption OK:

→ BootRom jumps into internal RAM and

executes FSBL1 from Download area.

→ User can get BootRom traces

The FSBL2 is not used.

Here are the BootRom traces results:

5.2.2. FSBL signed and encrypted with wrong keys

If the secure boot fails with FSBL1 the BootRom code clears the download buffer and then downloads the FSBL2 image installed @0x7004'0000 into the download buffer area.(ref 3.5.3 Access image on serial NOR device from UM3234 How to proceed with BootRom on STM32N6)

If FSBL is encrypted / signed with wrong keys here is the boot flow:

1- At reset BootRom checks if an FSBL is installed @0x7000'0000

2- The BootRom copies the FSBL1 to Internal RAM download area and controls integrity / authenticity.

3- Decryption KO

→ BootRom checks if an FSBL is installed @0x70040000.

4- The BootRom copies the FSBL2 to Internal RAM download area and controls integrity / authenticity

5- Controls OK

→ BootRom jumps into internal RAM and executes FSBL2 directly from Download area

→ User can get BootRom traces

Here are the BootRom traces results:

6. Lock the device and execute trusted application

Before setting the product state secured-locked, the device must be provisioned with the BootRom secrets.

We previously provisioned these keys and flash the binary signed files.

Now we will see how to set the product state from secured-unlocked to secured-locked:

The script exampleenable_secure_boot.bat located in Projects\STM32N6570-DK\ROT_Provisioning\BootROM folder sets the device in secured-locked state.

• Set the device in dev boot mode

• launch the script enable_secure_boot.bat (double-click)
• Once the success message is displayed, set the device in flash boot mode and open Teraterm:

Then go to the Teraterm Window:

You can now see the BootROM traces.

In this case, the BootRom traces are not necessary as we can see that the code is executed (the leds are blinking) : That means that the signature and encryption checks succeeded.