Sign Secure Boot V2 images with OpenSSL and Esptool from Espressif using PKCS11 library

Esptool is a Python-based, open-source, platform-independent utility to communicate with the ROM bootloader in Espressif chips.

Integrate OpenSSL with DigiCert® Software Trust Manager’s PKCS11 library, then use OpenSSL, to sign the image using Espressif’s detached signature functionality. Use these instructions set up, sign and verify signatures using the Esptool utility script bundled with the Espressif build system.

Prerequisites

DigiCert ONE API key
DigiCert ONE client authentication certificate
Software Trust Manager keypair
OpenSSL with DigiCert® Software Trust Manager PKCS11 library
Configure your credentials
Esptool (version 4.5 or higher)

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.

Install and configure Software Trust Manager PKCS11 with OpenSSL

Follow these instructions to install OpenSSL and configure it with Software Trust Manager PKCS11 library.

Sign with OpenSSL (DGST)

Example 1. RSA with PSS padding

Note

Espressif signing is only compatible with:

RSA 3072-bit keys.
Keys stored on DISK.

To sign, use the command:

openssl dgst -engine pkcs11 -keyform engine -sign "pkcs11:object=<keypair-alias>;type=private" -sha256 -sigopt rsa_padding_mode:pss -sigopt rsa_pss_saltlen:32 -sigopt rsa_mgf1_md:sha256 -out <signature-output-file> <input image>

Command example:

openssl dgst -engine pkcs11 -keyform engine -sign "pkcs11:object=keypair-1;type=private" -sha256 -sigopt rsa_padding_mode:pss -sigopt rsa_pss_saltlen:32 -sigopt rsa_mgf1_md:sha256 -out openssl-signature.bin hello_world.bin engine "pkcs11" set.

Example 2. ECDSA

Note

Espressif signing is only compatible with ECDSA 192 and 256-bit keys.

To sign, use the command:

openssl dgst -engine pkcs11 -keyform engine -sign "pkcs11:object=ecdsa-keypair-1;type=private" -sha256 -out openssl-ecdsa-signature.bin hello_world.bin
engine "pkcs11" set.

Command example:

openssl dgst -engine pkcs11 -keyform engine -verify "pkcs11:object=ecdsa-keypair-1;type=public" -signature openssl-ecdsa-signature.bin -sha256 hello_world.bin
engine "pkcs11" set.

Sign with espsecure.py

To sign, use the command:

espsecure.py sign_data --version 2 --pub-key <public-key-from-keypair-used-to-sign> --signature <signature-output-file-from-openssl> --output <final-signed-image-output-name> <input-image>

Command example:

Example 3. RSA

espsecure.py sign_data --version 2 --pub-key keypair-1.pem --signature openssl-signature.bin --output output.bin hello_world.bin
espsecure.py v4.5-dev

Note

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

Example of a correct RSA PEM public key:

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

. . .

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

Example 4. ECDSA

espsecure.py sign_data --version 2 --pub-key ecdsa-keypair-1.pem --signature openssl-ecdsa-signature.bin --output output-ecdsa.bin hello_world.bin
espsecure.py v4.5-dev

Note

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

Example of a correct ECDSA PEM public key:

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

. . .

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

Verify signature

Example 5. Verify RSA signature with espsecure.py

To verify signature, use the command:

espsecure.py verify_signature --version 2 --keyfile <public-key-from-keypair-used-to-sign> <final-signed-image>

Command example:

espsecure.py verify_signature --version 2 --keyfile keypair-1.pem output.bin
espsecure.py v4.5-dev

Example 6. Verify ECDSA signature with OpenSSL

To verify signature, use the command:

openssl dgst -engine pkcs11 -keyform engine -verify "pkcs11:object=<keypair-alias>;type=public" -signature <signature-output-file> -sha256 <input-image>

Command example:

espsecure.py verify_signature --version 2 --keyfile ecdsa-keypair-1.pem output-ecdsa.bin
espsecure.py v4.5-dev

Sign Secure Boot V2 images with OpenSSL and Esptool from Espressif using PKCS11 library

Prerequisites

Install Esptool

Note

Install and configure Software Trust Manager PKCS11 with OpenSSL

Sign with OpenSSL (DGST)

Note

Note

Sign with espsecure.py

Note

Note

Verify signature

Related articles