1.. _espsecure:
2
3espsecure.py
4============
5
6``espsecure.py`` is a tool for manipulating data that relates to the secure boot and flash encryption features of ESP32 and later Espressif chips.
7
8For more details, see the ESP-IDF documentation which explains this tool and how to use it to enable the relevant features:
9
10*  `Secure Boot <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/security/secure-boot-v2.html>`_
11*  `Flash Encryption <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/security/flash-encryption.html>`_
12
13.. _hsm_signing:
14
15Remote Signing using an external HSM
16------------------------------------
17
18An external Hardware Security Module (HSM) can be used for remote signing of images in secure boot v2 scheme.
19
20You 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``.
21
22The following command should be used to get an image signed using an external HSM. ::
23
24    python espsecure.py sign_data --version 2 --hsm --hsm-config <hsm_config_file> --output <signed_image> <datafile>
25
26The 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.
27
28If the public key is not stored in the external HSM, you can specify the ``--pub-key`` argument to supply the public key. ::
29
30    python espsecure.py sign_data --version 2 --hsm --hsm-config <hsm_config_file> --pub-key <public_key> --output <signed_image> <datafile>
31
32.. note::
33    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.
34
35Verifying the Signed Image
36~~~~~~~~~~~~~~~~~~~~~~~~~~
37
38Once the signed image is generated, we can verify it using the following command: ::
39
40    python espsecure.py verify_signature --version 2 --hsm --hsm-config <hsm_config_file> <signed_image>
41
42If the public key is not stored in the external HSM, you can specify the ``--keyfile`` argument to supply the public key. ::
43
44    python espsecure.py verify_signature --version 2 --keyfile <public_key> <signed_image>
45
46
47HSM config file
48~~~~~~~~~~~~~~~
49
50An HSM config file is required with the fields (``pkcs11_lib``, ``credentials``, ``slot``, ``label``, ``label_pubkey``)
51populated corresponding to the HSM used.
52
53To 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.
54Alternatively, you could also add a ``credentials`` field in the HSM config file to store the (plaintext) User PIN to automate the signing workflow.
55
56Below is a sample HSM config file (``hsm_config.ini``) for using `SoftHSMv2 <https://github.com/opendnssec/SoftHSMv2>`_ as an external HSM: ::
57
58    # hsm_config.ini
59
60    # Config file for the external Hardware Security Module
61    # to be used to generate signature.
62
63    [hsm_config]
64
65    # PKCS11 shared object/library module of the HSM vendor
66    pkcs11_lib = /usr/local/lib/softhsm/libsofthsm2.so
67
68    # HSM login credentials
69    credentials = 1234
70
71    # Slot number to be used
72    slot = 1108821954
73
74    # Label of the object used to store the private key
75    label = Private Key for Digital Signature
76
77    # Label of the object used to store corresponding public key
78    # label_pubkey is the same as label if the label for public key
79    # is not explicitly specified while key-pair generation.
80    label_pubkey = Public Key for Digital Signature
81