STM32 SigningTool

1. Purpose

STM32 Signing Tool is a key tool that guarantees a secure platform and ensures the signing of binary images using ECC keys generated by STM32 KeygenTool. The signed binary images are used during the STM32 MPU ROM code secure boot sequence that supports a trusted boot chain. This action ensures an authentication and integrity check of the loaded images.

2. STM32 Signing Tool overview

The STM32 Signing Tool software generates a signed binary image file, a public key file, and a private key file:

Binary image file : Contains the binary data to be programmed for the device.
Public key file: Contains the generated ECC public key in PEM format (generated with the STM32 KeygenTool).
Private key file: Contains the encrypted ECC private key in PEM format (generated with the STM32 KeygenTool).

If the image entry is an .stm32 file that already contains a STM32 header and info, it is possible to generate a signed binary file from the given .stm32 file using the batch file mode. In this case, the parameters Entry point of image, Load address of image, and Image version are not mandatory.

Signing tool usage block diagram:

3. STM32 Signing Tool install

This section describes the requirements and procedure to use the STM32 Signing Tool software.

3.1. Linux install

The STM32 Signing Tool has been tested on Ubuntu 14.04 and 16.04 (both 32-bit and 64-bit) and should work on other distributions.

To install the STM32 Signing Tool, the installation of STM32CubeProgrammer is needed.

To run the STM32 Signing Tool, launch the ./STM32_SigningTool_CLI.

3.2. Windows install

To install the STM32 Signing Tool, the installation of STM32CubeProgrammer is needed.

To run it, launch the executable STM32_SigningTool_CLI.exe.

4. Command line options

Available options are:

--binary-image (-bin), --input (-in)

Description: Binary image file path

Syntax 1: -bin /home/User/binaryFile.bin

Syntax 2: -in /home/User/binaryFile.bin

--public-key -pubk

Description: Public key file paths

Syntax: -pubk <File_Path{1..8}>

For header v2.3 (STM32N6): Use 8 key paths

--private-key -prvk

Description: Private key file path

Syntax: -prvk <File_Path>

--password -pwd

Description: Password of the private key to prepare the signature

Syntax: -pwd <Password>

--load-address -la

Description: Load address of image, value in hex format

Syntax: -la <Load_Address>

Example: -la 0x2ffe0000

--entry-point -ep

Description: Image entry point, value in hex format

Syntax: -ep <Entry_Point>

Example: 0x2ffe4000

--image-version -iv

Description: Image version, Default is 0

Syntax: -iv <Version>

--algorithm -a

Description: Algorithm used: 1. (P-256 NIST) 2. (Brainpool 256), 1- P256NIST is the default algorithm

Syntax: -a <AlgoNbr>

--option-flags -of

Description: Option flags of image, default is 0 (For more information, check Option flags in STM32 header for binary files article)

Syntax: -of <Option_Flags>

Example: 0x00000001

Note: -of option flag is an extension to pass a device settings

For STM32N6 (b0=1: Authentication Enable and/or b1=1: FSBL encryption Enable)

For Authentication only: -of 0x00000001

For Authentication + FSBL Encryption: -of 0x00000003

If the command "--option-flags" is not mentioned, the tool will not create a signed image (Default: Authentication Disable)

	b0=1 (Enable authentication)	b0=0 (Disable authentication)	No -of command
Input contains STM32 header: Yes	Sign	Nothing	Nothing
Input contains STM32 header: No	Sign	Add header without signing	Add header without signing

Signature and authentication are mandatory on secure closed chip

--output -o

Description: Output file path

Syntax: -o <Output_File_Path>

--silent -s

Description: Silent mode, no prompt messages

Syntax: -s

--binary-type -type

Description: Identify binary file, possible values: ssbl, fsbl, teeh, teed, teex, copro (For more information, check Binary type in STM32 header for binary files article)

Syntax: --binary-type <type>

--enc-dc -encdc

Description: Encryption derivation constant for FSBL encryption

Syntax: -encdc <Deriv_hexVal>

--enc-key -enck

Description: OEM secret file for FSBL encryption

Syntax: -enck <Key_Path>

--dump-header --dump

Description: Parse and dump image header

Syntax: -dump <File_Path>

5. STM32 Signing Tool usage examples

This section presents examples of how to use the STM32 Signing Tool software.

If the image entry is an .stm32 file that already contains a header and info the only mandatory options are: public key, private key, password and Binary type.

5.1. Example 1

./STM32_SigningTool_CLI.exe -bin /home/user/input.bin -pubk publicKey00.pem publicKey01.pem publicKey02.pem publicKey03.pem publicKey04.pem publicKey05.pem publicKey06.pem publicKey07.pem -prvk privateKey00.pem -pwd azerty -t fsbl -iv 0x00000000 -la 0x20000000 -ep 0x08000000 -of 0x80000001 -hv 2.3 -o /home/user/output.stm32

Sign a binary file using header version 2.3 that includes 8 public keys for authentication flow.

5.2. Example 2

./STM32_SigningTool_CLI.exe -bin /home/user/input.bin -pubk publicKey00.pem publicKey01.pem publicKey02.pem publicKey03.pem publicKey04.pem publicKey05.pem publicKey06.pem publicKey07.pem -prvk privateKey00.pem -iv 0x00000000 -pwd azerty -la 0x20000000 -ep 0x08000000 -t fsbl -of 0x00000003 -encdc 0x25205f0e -enck /home/user/OEM_SECRET.bin -hv 2.3 -o /home/user/output.stm32

Sign a binary file using header version 2.3 that includes 8 public keys for authentication + encryption flow.

5.3. Example 3

./STM32_SigningTool_CLI.exe -dump /home/user/output.stm32

Verify the resulting image by parsing the output file and checking each header field.

      -------------------------------------------------------------------
                          STM32 Signing Tool 
      -------------------------------------------------------------------


Header description:

    Magic: 0x53544d32
    Signature: 1a 01 09 ff 86 99 09 3b 6a 27 95 76 3e 7e e8 cd 05 36 0e c7 eb 74 d0 84 77 2d f9 7e ce fb d8 80
               59 be 2c 4d 14 3a 66 a3 2c 34 63 86 5c e1 49 3d 77 38 10 59 b2 a2 2b b5 3f 85 5e 05 cf 46 da 01
               00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
    Checksum: 0x15b7
    Header version: 0x20300
    Size: 0x1e0
    Load address: 0x2ffe0000
    Entry point: 0x341802f5
    Image version: 0x0
    Extension: 0x80000001

    ECDSA  : 256

Authentication header detected:
    Type: 0x53540002
    Size: 0x174
    Key index: 0x6
    Key number: 0x8
    ECDSA Algo: 0x1
    ECDSA pub key: 17 29 9d 9b f1 ad 71 38 f5 4c 86 c7 e8 4f cb 35 ad 64 98 34 50 5b a0 bf 69 7c ac 24 e1 18 c1 4f
                   df 59 de 10 d9 59 1d 9a 90 2c 5c 49 cc 3b 42 78 73 fc fe b8 9e bc ec 76 8b 3c 3c 61 05 a6 f1 6a
                   00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00

    Key 0: 64 ce 24 38 4b 65 30 5a a8 24 e8 a3 d8 d4 ef 09 f7 9d 40 3f 23 a4 5e e6 99 db a8 58 ef 38 f6 6c
    Key 1: 4f ab 24 2b fa db aa 2d 53 45 bf 10 a1 24 48 e5 8e 7f ee 0e 3d df bd 0d 61 8f 99 f9 2d 75 7e 48
    Key 2: 6c 20 77 89 4d 16 35 70 62 18 d9 60 12 f3 ff 3f 9e be 5e 9f f4 1d f3 97 d5 58 bd 9c e8 4e de 99
    Key 3: 53 ea 33 2e d6 ff fd 3d 38 50 c1 a9 9c 0d d4 40 eb 7a 03 ae fb 7f 2c c0 bb 77 2a ac cb f0 b1 47
    Key 4: 38 f9 31 24 a5 06 79 96 8b 98 81 0b 72 0b 4f da f6 49 8c 3f e4 d4 a6 85 b1 5e 8c 64 a1 9e e8 9a
    Key 5: 24 10 1c 57 ea 4d 92 d7 26 fe 5c a4 ec 8f 47 f0 3b 16 11 32 d1 4e d6 e1 5a f1 98 86 6a 50 dd 78
    Key 6: d0 06 6e d9 0d e8 85 b8 0e e5 f7 b8 29 fb 0a 1d df 75 7c 95 1b e4 f5 e6 17 9a 36 19 59 40 89 59
    Key 7: be d9 ce dc 0e 5f a8 eb 86 ed 5f 38 00 bf 18 17 ff af ec f7 4b f8 b7 82 03 39 6f d5 05 87 99 78

Pad header detected:
    Type: 0x5354ffff
    Size: 0x2c
    Padding values: 75 ed 91 c2 4c 23 b5 ac 68 97 de 96 e8 f5 5a db 5b 8a 0e b5 f5 4e 06 99 0e 04 39 1d 35 07 71
                    1c af e6 0a 24

Post header 2.3 information :
    Binary type: 0x10
    Non authenticated payload length: 0x0
    Non authenticated payload hash: 0x0

5.4. Example 4

./STM32_SigningTool_CLI.exe -in input.bin -nk -of 0x0 -iv 1 -hv 2.3 -o output.stm32

Add a header without signing and without deploying keys.

6. Standalone mode

When executing the STM32 Signing Tool in standalone mode, an absolute path must be entered first, then enter the password must be entered twice for confirmation.
After specifying one of the two algorithms, enter the image version, image entry point, image load address, and finally the option flags value.
By pressing enter, the output file path proposed by default is selected. If desired, a different output file path can be specified.

7. PKCS#11 solution

The signed binary images are used during the STM32 secure boot sequence that supports a trusted boot chain. This action ensures an authentication and integrity check of the loaded images.
The classic signing command requests that all public and private keys be provided as input files. These are directly accessible by any person who is allowed to execute the signing service. Ultimately, this can be considered to be a security leak. There are several solutions to protect keys against any attempts to steal key data. In this context, the PKCS#11 solution has been adopted.

The PKCS#11 API can be used to handle and store cryptographic keys. This interface specifies how to communicate with cryptographic devices such as HSMs (Hardware Security Modules) and smartcards. The purpose of these devices is to generate cryptographic keys and sign information without revealing private-key material to the outside world.

Software applications can call the API to use these objects for:

Generating symmetric/asymmetric keys
Encryption and decryption
Computing and verifying the digital signature

PKCS #11 presents to applications a common, logical view of the device that is called a cryptographic token and it assigns a slot ID to each token. An application identifies the token that it wants to access by specifying the appropriate slot ID.

The STM32 Signing Tool is used to manage the key objects stored on smartcards and similar PKCS#11 security tokens where sensitive private keys never leave the device.
The STM32 Signing Tool uses the PKCS#11 interface to manipulate and sign input binaries basing on ECDSA public/private keys which are stored in security tokens (Hardware or Software).

7.1. Additional PKCS#11 commands

--module (-m)

Description: Specify a PKCS#11 module/Library path to load (dll, so).

Syntax: -m <Module_Path>

--key-index (-ki)

Description: List of used keys indexes in hex format. Use 1 index for Header v1 and 8 indexes for header v2(separated by space).

Syntax: -ki <values>

--slot-index (-si)

Description: Specify the index of the slot to use (default 0x0).

Syntax: -si <hexValue>

--active-keyIndex (-aki)

Description: Specify the actual active key index (default 0).

Syntax: -aki < hexValue >

7.2. PKH/PKTH file generation

After the processing of the signing operation, the tool will systematically generate the PKH files to be used after for OTP Fuse:

PKTH file named pkcsPublicKeysHashHashes.bin

7.3. Examples

The tool can sign input files for header v2.3 with a minimal difference in the command line:

Header v2.3

-bin input.bin -iv <value> -pwd <value> -la <value> -ep <value> -t <type> -of <value> --key-index <value0> <value1> <value2> <value3> <value4> <value5> <value6> <value7> -aki <active_index> --module <module_path> --slot-index <index> -hv 2.3 -o output.stm32

An error on the command line, or an inability of the tool to identify the key objects that match, causes an error message to be displayed. This indicates the source of the problem.

The SigningTool is able only to use preconfigured HSMs and it is not designed to manage or create new security objects. Therefore, it is necessary to install free software to set up a suitable environment. The keys can then be generated, and information about objects obtained.

Error examples:

Invalid slot index:

Figure 1: HSM TOKEN_NOT_RECOGNIZED

Unknown key object that is mentioned in --key-index command:

Figure 2: HSM OBJECT_HANDLE_INVALID

The tool treats the objects sequentially. If it cannot identify the matching key objects on the first try, the signing operation stops the process. An error message is then displayed to indicate the source of the problem.