Difference between revisions of "KeyGen tool"

[quality revision] [quality revision]
(Merge articles)
m
 
Applicable for STM32MP13x lines, STM32MP15x lines

STM32 KeyGen is a tool that generates the ECC key pairs needed for signing binary images. The generated keys will be used by Signing tool for signing process.


1 KeyGen Overview[edit]

The STM32MP Key Generator software generates three 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.


2 Install STM32MP Key Generator[edit]

This section describes the requirements and procedure to use the STM32MP Key Generator software.


2.1 Linux Install[edit]

The STM32MP Key Generator software is tested on Ubuntu 14.04 and 16.04 32-bit and 64-bit and should work on any distribution.

To install the STM32MP Key Generator tool, you need to install the STM32CubeProgrammer. To run it, you will need to launch the ./STM32MP_KeyGen_CLI.sh script.

2.2 Windows install[edit]

To install the STM32MP Key Generator tool for windows, you need to install the STM32CubeProgrammer. To run it, launch the STM32MP_KeyGen_CLI.exe executable

3 STM32MP Key Generator command line interface[edit]

The following section describes how to use the STM32MP Key Generator from command line


3.1 Command line options[edit]

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 key. The password must contain 4 characters at least.

Note: you must include 8 passwords when you would like to generate 8 keypairs

Syntax 1: -pwd <password>

Syntax 2: -pwd <Password1> <Password2> <Password3> <Password4> <Password5> <Password6> <Password7> <Password8>

Example: -pwd 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) The prime256v1 is the default algorithm.

Syntax: -ecc prime256v1


  • --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 header v1: use just one key path for STM32MP15xx products

For header v2: use 8 key paths for STM32MP13xx products

3.2 Examples[edit]

This following section presents some examples of how to use the STM32MP Key Generator software.

3.2.1 Example 1: Key creation using the AES256 algorithm[edit]

STM32MP_KeyGen_CLI -abs /home/user/KeyFolder/ -pwd azerty

Files (publicKey.pem & privateKey.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[edit]

STM32MP_KeyGen_CLI -abs /home/user/keyFolder/ -pwd azerty -pe aes128

Files (publicKey.pem & privateKey.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: Key creation when one or both the destination folders are missing[edit]

STM32MP_KeyGen_CLI -pubk /home/user/public.pem -prvk /home/user/Folder1/Folder2/private.pem -hash /home/user/pubKeyHash.bin -pwd azerty

Even if Folder1 and Folder2 does not exist they will be created.

3.2.4 Example 4: Generate 8 key pairs in the working directory[edit]

./STM32MP_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.3 Standalone mode[edit]

When executing the STM32MP Key Generator in standalone mode, you have to enter an absolute path and a password only. In case user press <Enter> the files will be generated in the folder <C:\Users\User_Name\.STM32AP_KeyGen/>

Then you have to enter the password twice and select one of the two algorithms (prime256v1/brainpoolP256t1) by pressing 1 or 2 key respectively.

And finally, select an encrypting algorithm (AES256/AES128) by pressing 1 or 2 key respectively.


<noinclude>{{ApplicableFor
|MPUs list=STM32MP13x, STM32MP15x
|MPUs checklist=STM32MP13x, STM32MP15x
}}</noinclude>
STM32 KeyGen is a tool that generates the ECC key pairs needed for signing binary images. The generated keys will be used by [[Signing tool]] for signing process.

{{ReviewsComments|-- LDE<br />Could be useful to add a link to Secure boot page here}}

==KeyGen Overview==
The STM32MP Key Generator software generates three 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.

==Install STM32MP Key Generator ==

This section describes the requirements and procedure to use the STM32MP Key Generator software.

===Linux Install===

The STM32MP Key Generator software is tested on Ubuntu 14.04 and 16.04 32-bit and 64-bit and should work on any distribution.

To install the STM32MP Key Generator tool, you need to install the [[STM32CubeProgrammer]]. To run it, you will need to launch the ./STM32MP_KeyGen_CLI.sh script.

===Windows install===

To install the STM32MP Key Generator tool for windows, you need to install the [[STM32CubeProgrammer]]. To run it, launch the STM32MP_KeyGen_CLI.exe executable

==STM32MP Key Generator command line interface==

The following section describes how to use the STM32MP Key Generator from command line

===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 key. The password must contain 4 characters at least.

Note: you must include 8 passwords when you would like to generate 8 keypairs

Syntax 1: -pwd <password>


Syntax 2: -pwd <Password1> <Password2> <Password3> <Password4> <Password5> <Password6> <Password7> <Password8>


Example: -pwd 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) The prime256v1 is the default algorithm.

Syntax: -ecc prime256v1

* --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 header v1: use just one key path for STM32MP15xx products

For header v2: use 8 key paths for STM32MP13xx products

===Examples===

This following section presents some examples of how to use the STM32MP Key Generator software.

====Example 1: Key creation using the AES256 algorithm====
<pre>STM32MP_KeyGen_CLI -abs /home/user/KeyFolder/ -pwd azerty</pre>
{{ReviewsComments|-- [[User:Arnaud Pouliquen|Arnaud Pouliquen]] ([[User talk:Arnaud Pouliquen|talk]]) 14:39, 25 November 2019 (CET)<br />STM32AP_KeyGen_CLI  or STM32MP_KeyGen_CLI? at least For linux stm32cube programmer it is STM32MP_KeyGen_CLI}}

Files (publicKey.pem & privateKey.pem & publicKeyhash.bin) will be created in the folder /home/user/KeyFolder/

The private key is encrypted with the default algorithm aes256

====Example 2: Key creation using the AES128 algorithm====
<pre>STM32MP_KeyGen_CLI -abs /home/user/keyFolder/ -pwd azerty -pe aes128</pre>


Files (publicKey.pem & privateKey.pem & publicKeyhash.bin) will be created in /home/user/KeyFolder/ folder.

The private key is encrypted with the algorithm aes128

====Example 3: Key creation when one or both the destination folders are missing====
<pre>STM32MP_KeyGen_CLI -pubk /home/user/public.pem -prvk /home/user/Folder1/Folder2/private.pem -hash /home/user/pubKeyHash.bin -pwd azerty</pre>


Even if Folder1 and Folder2 does not exist they will be created.

====Example 4: Generate 8 key pairs in the working directory====
<pre>./STM32MP_KeyGen_CLI.exe -abs . -pwd abc1 abc2 abc3 abc4 abc5 abc6 abc7 abc8 -n 8</pre>


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

===Standalone mode===

When executing the STM32MP Key Generator in standalone mode, you have to enter an absolute path and a password only. In case user press <Enter> the files will be generated in the folder <C:\Users\User_Name\.STM32AP_KeyGen/>


Then you have to enter the password twice and select one of the two algorithms (prime256v1/brainpoolP256t1) by pressing 1 or 2 key respectively.

And finally, select an encrypting algorithm (AES256/AES128) by pressing 1 or 2 key respectively.
<noinclude>

[[Category:KeyGen tool]]
{{PublicationRequestId | 10543 | 2019-02-04 | StephenG}}</noinclude>
(One intermediate revision by one other user not shown)
Line 1: Line 1:
  +
<noinclude>{{ApplicableFor
  +
|MPUs list=STM32MP13x, STM32MP15x
  +
|MPUs checklist=STM32MP13x, STM32MP15x
  +
}}</noinclude>
 
STM32 KeyGen is a tool that generates the ECC key pairs needed for signing binary images. The generated keys will be used by [[Signing tool]] for signing process.
 
STM32 KeyGen is a tool that generates the ECC key pairs needed for signing binary images. The generated keys will be used by [[Signing tool]] for signing process.
   
Line 127: Line 131:
   
 
<pre>STM32MP_KeyGen_CLI -abs /home/user/KeyFolder/ -pwd azerty</pre>
 
<pre>STM32MP_KeyGen_CLI -abs /home/user/KeyFolder/ -pwd azerty</pre>
{{ReviewsComments|-- [[User:Arnaud Pouliquen|Arnaud Pouliquen]] ([[User talk:Arnaud Pouliquen|talk]]) 14:39, 25 November 2019 (CET)<br />STM32AP_KeyGen_CLI  or STM32MP_KeyGen_CLI? at least For linux stm32cube programmer it is STM32MP_KeyGen_CLI}}
 
   
 
Files (publicKey.pem & privateKey.pem & publicKeyhash.bin) will be created in the folder /home/user/KeyFolder/
 
Files (publicKey.pem & privateKey.pem & publicKeyhash.bin) will be created in the folder /home/user/KeyFolder/