STM32 KeyGen is a tool that generates the ECC key pairs needed for signing binary images. The generated keys are used by the STM32 SigningTool for signing process. STM32 KeyGen tool is used only by the ROM, refer to STM32 MPU ROM code secure boot article for more information.
1. KeyGen Overview
The STM32 Key Generator software generates four types of files:
- Public Key file:
- Contains the generated ECC public key in PEM format.
- Private Key file:
- Contains the encrypted ECC private key in PEM format. The encryption could be done using the AES128CBC or AES256CBC ciphers. The cipher selection is done using the --prvkey-enc option.
- Hash public key file:
- Contains the SHA-256 hash of the public key in binary format. The SHA-256 hash is calculated based on the public key without any encoding format. The first byte of the public key is used to indicate whether the public key is in compressed or uncompressed format. Since only uncompressed format is supported, this byte is removed.
- PKH table file:
- Contains the Hashes of Algo + ECDSA public keys
2. Install STM32 Key Generator
This section describes the requirements and procedure to use the STM32 Key Generator software.
2.1. Linux Install
The STM32 Key Generator software has been tested on Ubuntu 20 and 22 (both 32-bit and 64-bit) and should work on other distributions.
To install the STM32 Key Generator tool, the installation of STM32CubeProgrammer is needed. To run the the STM32 Key Generator tool, launch the ./STM32_KeyGen_CLI.sh script.
2.2. Windows install
To install the STM32 Key Generator tool for windows, the installation of STM32CubeProgrammer is needed. To run the the STM32 Key Generator tool, launch the executable STM32_KeyGen_CLI.exe.
3. STM32 Key Generator command line interface
The following section describes how to use the STM32 Key Generator from command line.
3.1. Command line options
The generation process can be tailored by the requester. The available options are:
- --private-key (-prvk)
Description: Private key file path (.pem extension).
Syntax: -prvk <private_key_file_path>
- --public-key (-pubk)
Description: Public key file path (.pem extension).
Syntax: -pubk <public_key_file_path>
- --public-key-hash (-hash)
Description: Hash image file path (.bin extension).
Syntax: -hash <hash_file_path>
- --absolute-path (-abs)
Description: Absolute path for output files.
Syntax: -abs <absolue_path_folder_path>
- --password (-pwd)
Description: Password of the private keys. The password must contain 4 characters at least.
Note: you must include 8 passwords to match the 8 keypairs.
Syntax : -pwd <Password1> <Password2> <Password3> <Password4> <Password5> <Password6> <Password7> <Password8>
Example: -pwd azerty azerty azerty azerty azerty azerty azerty azerty
- --prvkey-enc (-pe)
Description: Encrypting private key algorithm (AES128/AES256) The AES256 algorithm is the default algorithm.
Syntax: -pe aes128
- --ecc-algo (-ecc)
Description: ECC algorithm for keys generation (prime256v1/brainpoolP256t1/ prime384v1/ brainpoolP384t1). The prime256v1 is the default algorithm.
1. prime256v1 2. brainpoolP256t1 3. prime384v1 4. brainpoolP384t1
Syntax: -ecc 1
- --help (-h and -?)
Description: Show help.
Syntax : --help
- --version (-v)
Description: Display the tool version.
Syntax : --version
- --number-key (-n)
Description: Generate number of key pairs {1 or 8} with Hash of table file.
Syntax: -n <number>
For STM32N6: use 8 as number of key paths.
Example: -n 8
- --random (-rand)
Description: Generate random data and save the result in a binary file.
Syntax: -rand <number_Bytes> <output_path.bin>
Example: -rand 16 OEM_KEY.bin
3.2. Examples
This following section presents some examples of how to use the STM32 Key Generator software.
3.2.1. Example 1: Key creation using the AES256 algorithm
STM32_KeyGen_CLI -abs /home/user/KeyFolder/ -pwd abc1 abc2 abc3 abc4 abc5 abc6 abc7 abc8 -n 8
Files (publicKey[x].pem & privateKey[x].pem & publicKeyhash.bin) will be created in the folder /home/user/KeyFolder/
The private key is encrypted with the default algorithm aes256
3.2.2. Example 2: Key creation using the AES128 algorithm
STM32_KeyGen_CLI -abs /home/user/keyFolder/ -pwd abc1 abc2 abc3 abc4 abc5 abc6 abc7 abc8 -n 8 -pe aes128
Files (publicKey[x].pem & privateKey[x].pem & publicKeyhash.bin) will be created in /home/user/KeyFolder/ folder.
The private key is encrypted with the algorithm aes128
3.2.3. Example 3: Generate 8 key pairs in the working directory
./STM32_KeyGen_CLI.exe -abs . -pwd abc1 abc2 abc3 abc4 abc5 abc6 abc7 abc8 -n 8
We get as output the following files:
- 8 public key files: publicKey0x{0..7}.pem
- 8 private key files: privateKey0x{0..7}.pem
- 8 public key hash files: publicKeyHash0x{0..7}.bin
- 1 file of PKTH: publicKeysHashHashes.bin
3.2.4. Example 4: Generate 384 keys (prime384v1)
STM32_KeyGen_CLI.exe -abs /home/user/KeyFolder/ -pwd azerty azerty azerty azerty azerty azerty azerty azerty -n 8 -ecc 3
8 key packets will be created in the folder /home/user/KeyFolder/ where prime384v1 curve is selected.
3.3. Standalone mode
When executing the STM32 Key Generator in standalone mode, you have to enter an absolute path and a password only. If the user presses <Enter>, the files are generated in the folder <C:\Users\User_Name\.STM32_KeyGen/>.
Then, you must enter the password twice and select one of the four algorithms (prime256v1/brainpoolP256t1/brainpoolP256t1/brainpoolP384t1) by pressing 1, 2, 3, or 4 key, respectively.
Finally, select an encrypting algorithm (AES256/AES128) by pressing 1 or 2 key respectively.