espsecure.py

espsecure.py is a tool for manipulating data that relates to the secure boot and flash encryption features of ESP32 and later Espressif chips.

For more details, see the ESP-IDF documentation which explains this tool and how to use it to enable the relevant features:

• Secure Boot

• Flash Encryption

Remote Signing using an external HSM

An external Hardware Security Module (HSM) can be used for remote signing of images in secure boot v2 scheme.

You must install esptool.py package with the hsm extra using the command pip install 'esptool[hsm]' to use this feature. esp_hsm_sign provides a PKCS #11 interface to communicate with the external HSM and is integrated in espsecure.py.

The following command should be used to get an image signed using an external HSM.

python espsecure.py sign_data --version 2 --hsm --hsm-config <hsm_config_file> --output <signed_image> <datafile>

The above command first extracts the public key from the HSM, generates a signature for an image using the HSM, and then creates a signature block and appends it to the image to generate a signed image.

If the public key is not stored in the external HSM, you can specify the --pub-key argument to supply the public key.

python espsecure.py sign_data --version 2 --hsm --hsm-config <hsm_config_file> --pub-key <public_key> --output <signed_image> <datafile>

Note

In case you are using ESP-IDF, then an unsigned application can be generated by disabling CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES configuration option in the project settings.

Verifying the Signed Image

Once the signed image is generated, we can verify it using the following command:

python espsecure.py verify_signature --version 2 --hsm --hsm-config <hsm_config_file> <signed_image>

If the public key is not stored in the external HSM, you can specify the --keyfile argument to supply the public key.

python espsecure.py verify_signature --version 2 --keyfile <public_key> <signed_image>

HSM config file

An HSM config file is required with the fields (pkcs11_lib, credentials, slot, label, label_pubkey) populated corresponding to the HSM used.

To access an HSM token of a selected slot, you will also need to pass in the token User PIN and thus you will be prompted to type in the User PIN. Alternatively, you could also add a credentials field in the HSM config file to store the (plaintext) User PIN to automate the signing workflow.

Below is a sample HSM config file (hsm_config.ini) for using SoftHSMv2 as an external HSM:

# hsm_config.ini

# Config file for the external Hardware Security Module
# to be used to generate signature.

[hsm_config]

# PKCS11 shared object/library module of the HSM vendor
pkcs11_lib = /usr/local/lib/softhsm/libsofthsm2.so

# HSM login credentials
credentials = 1234

# Slot number to be used
slot = 1108821954

# Label of the object used to store the private key
label = Private Key for Digital Signature

# Label of the object used to store corresponding public key
# label_pubkey is the same as label if the label for public key
# is not explicitly specified while key-pair generation.
label_pubkey = Public Key for Digital Signature