Skip to main content

Sign Secure Boot V2 images with Esptool from Espressif

Esptool is a Python-based, open-source, platform-independent utility to communicate with the ROM bootloader in Espressif chips. Integrate Esptool with DigiCert​​®​​ Software Trust Manager’s PKCS11 library to sign image files.

Note

Espressif only supports:

  • RSA 3072 bit keys.

  • ECDSA 192 and 256 bit keys.

Prerequisites

Install Esptool

To install Esptool, run the following command from command line:

pip install esptool[hsm]

Note

For additional context, refer to Installation and dependancies.

Download and configure PKCS11 library

A HSM configuration file is required for Esptool to use DigiCert​​®​​ Software Trust Manager PKCS11 library. This file is required in sign commands.

Download PKCS11 library

To download the Software Trust Manager PKCS11 library:

  1. Sign in to DigiCert ONE.

  2. Navigate to Software Trust Manager > Resources > Client tool repository.

  3. Select your operating system.

  4. Click the download icon next to Software Trust Manager PKCS#11 Library.

Create configuration file

To create the HSM configuration file:

  1. Open a text editor or IDE.

  2. Copy and paste the content below:

    [hsm_config]
pkcs11_lib =<path to the Software Trust Manager PKCS11 library>
credentials =NONE
slot =0
label =<keypair-alias>

  3. Input the necessary values.

    Example:

    [hsm_config]
pkcs11_lib =C:\Tools\smpkcs11.dll 
credentials =NONE
slot =0
label =keypair-1

  4. Save the file as hsm-config.ini

Sign

To sign, use:

espsecure.py sign_data --version 2 --hsm --hsm-config <hsm-config-ini> --output <signed-output-filename> <input-image-file>

Command example:

espsecure.py sign_data --version 2 --hsm --hsm-config hsm-config.ini --output v2-rsa-pss-hello_world.bin hello_world.bin
espsecure.py v4.5-dev

Command output:

Trying to establish a session with the HSM.
Session creation successful with HSM slot 0.
Trying to extract public key from the HSM.
Config option 'label_pubkey' not found, using config option 'label' for public key.
Got public key with label keypair-1.
Connection closed successfully
Trying to establish a session with the HSM.
Session creation successful with HSM slot 0.
Got private key metadata with label keypair-1.
Signing payload using the HSM.
Signature generation successful.
Connection closed successfully
Pre-calculated signatures found
1 signing key(s) found.
Signed 196608 bytes of data from hello_world.bin. Signature sector now has 1 signature blocks.

Verify signature

Download the public key of the keypair used in signing. The downloaded public key is required in the command to verify a signed image file.

Note

If you download the public key from the UI, you must remove the EC/RSA keyword in the header and footer of the PEM file.

The beginning and end of the ECDSA/RSA PEM public key, should read as follows:

-----BEGIN PUBLIC KEY-----

. . .

-----END PUBLIC KEY-----

To verify, use:

espsecure.py verify_signature --version 2 --keyfile <public-key-file-of-keypair> <image-file-to-verify>

Command example:

espsecure.py verify_signature --version 2 --keyfile keypair-1.pem v2-rsa-pss-hello_world.bin

Command output:

espsecure.py v4.5-dev
Signature block 0 is valid (RSA).
Signature block 0 verification successful using the supplied key (RSA).
Signature block 1 invalid. Skipping.
Signature block 2 invalid. Skipping.
In this section: