Signing tool

Applicable for

1. Purpose[edit | edit source]

STM32MP Signing Tool is a key tool that guarantees a secure platform, it ensures the signing of binary images using ECC keys generated by KeyGen tool. 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. STM32MP Signing Tool overview[edit | edit source]

The STM32MP Signing Tool software generates a signed binary file from:

Binary image file : contains the binary data to be programmed for the STM32MP1 series device.
Public key file: contains the generated ECC public key in PEM format (generated with the KeyGen tool).
Private key file: contains the encrypted ECC private key in PEM format (generated with the KeyGen tool).

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

Signing tool usage block diagram:

3. STM32MP Signing Tool install[edit | edit source]

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

3.1. Linux install[edit | edit source]

The STM32MP Signing Tool is tested on Ubuntu 14.04 and 16.04 32-bit and 64-bit and should work on any distribution.

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

To run the STM32MP Signing Tool, launch the ./STM32MP_SigningTool_CLI.

3.2. Windows install[edit | edit source]

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

To run it, launch the executable STM32MP_SigningTool_CLI.exe.

4. Command line options[edit | edit source]

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 files paths

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

For header v1: use just one key path for STM32MP15xx products

For header v2: use 8 key paths for others

--private-key -prvk

Description : private key file path

Syntax : -prvk <File_Path>

--password -pwd

Description : password of the private key

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 : used algorithm : 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)

Syntax : -of <Option_Flags>

Example: 0x00000001

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

for STM32MP13 (b0=1: Authentication Enable and/or b1=1: FSBL encryption Enable)

For Authentication: -of 0x00000001, -of 0x00000001

For Authentication + FSBL Encryption : -of 0x00000003, -of 0x00000003

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

MP13	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

for STM32MP15 (b0=1: Authentication Disable or b0=0: Authentication Enable)

Example : -of 0x00000000, -of 0x00000001

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

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

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)

Syntax : --binary-type <type>

--enc-dc -encdc

Description: Encryption derivation constant for FSBL encryption [header v2]

Syntax: -encdc <Deriv_hexVal>

--enc-key -enck

Description: OEM secret file for FSBL encryption [header v2]

Syntax: -enck <Key_Path>

--dump-header --dump

Description: Parse and dump image header

Syntax: -dump <File_Path>

--header-version (-hv)

Description : Signing header version, possible values : 1 2 2.1 2.2

Example for STM32MP15: -hv 2

Example for STM32MP25: -hv 2.2

--no-keys (-nk)

Description : Adding empty header without key options

Note: need to disable authentication option with Option flags command

5. STM32MP Signing Tool usage examples[edit | edit source]

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

5.1. Example 1[edit | edit source]

./STM32MP_SigningTool_CLI -bin /home/User/BinaryFile.bin –pubk /home/user/publicKey.pem –prvk /home/user/privateKey.pem –iv 5 –pwd azerty –la 0x20000000 –ep 0x08000000

The default algorithm is selected (prime256v1) and the option flags value is 0 (default value). The signed output binary file (BinaryFile_Signed.bin) is created in the folder /home/user/

5.2. Example 2[edit | edit source]

./STM32MP_SigningTool_CLI -bin /home/User/Folder1/BinaryFile.bin –pubk /home/user/publicKey.pem –prvk /home/user/privateKey.pem –iv 5 –pwd azerty –s –la 0x20000000 –ep 0x08000000 –a 2 –o /home/user/Folder2/Folder3/signedFile.bin

BrainpoolP256t1 algorithm is selected in this example.

5.3. Example 3[edit | edit source]

./STM32MP_SigningTool_CLI -bin /home/User/Folder1/BinaryFile.stm32 –pubk /home/user/publicKey.pem –prvk /home/user/privateKey.pem –pwd azerty -t <type> –o /home/user/Folder2/Folder3/signedFile.bin

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

5.4. Example 4[edit | edit source]

./STM32MP_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 -o /home/user/output.stm32

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

5.5. Example 5[edit | edit source]

./STM32MP_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 -o /home/user/output.stm32

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

5.6. Example 6[edit | edit source]

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

Verify the resulted image by parsing the output file and check each header field.

5.7. Example 7[edit | edit source]

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

Add a header without signing and without deploying keys.

6. Standalone mode[edit | edit source]

When executing the STM32MP Signing Tool in standalone mode, an absolute path must be entered at 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[edit | edit source]

The signed binary images are used during the STM32MP 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 to put all public and private keys as input files which are directly accessible by any person who is allowed to execute the signing service, so that can be considered as a security leak. There are several solutions to protect keys against any attempts to steal keys data and based on this context, we will adopt the PKCS#11 solution.

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 smart cards. 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:

Generate 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 STM32SigningTool is used to manage the key objects stored on smart cards and similar PKCS#11 security tokens where sensitive private keys never leave the device.
The STM32SigningTool 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[edit | edit source]

--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[edit | edit source]

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

PKH file named pkcsHashPublicKey0x{active_key_index}.bin for header v1
PKTH file named pkcsPublicKeysHashHashes.bin for header v2

7.3. Examples[edit | edit source]

The tool can sign input files for both header v1 and header v2 with a minimal difference in the command line:

Header v1

-bin input.bin -iv <value> -pwd <value> -la <value> -ep <value> -t <type> -of <value> --key-index <value> -aki 0 --module <module_path> --slot-index <index> -o output.stm32

Header v2

-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> -o output.stm32

If there’s an error on the command line or if the tool is not able to identify the key objects that match, an error message will be displayed and indicates the problem’s source.

The SigningTool is able only to use preconfigured HSMs and it is not designed to manage or create new security objects, so we need to install and resort to some free software to setup a suitable environment then generates keys and get information about objects.

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 sequentially the objects and if it is not able to identify the key objects that match at the first time, the signing operation will stop, and an error message will be displayed to indicate the problem’s source.