Espressif ESP32-S2 User Manual

Chapter 2. API Reference
2.2.7 Digital Signature (DS)
The Digital Signature (DS) module provides hardware acceleration of signing messages based on RSA. It uses pre-
encrypted parameters to calculate a signature. The parameters are encrypted using HMAC as a key-derivation func-
tion. In turn, the HMAC uses eFuses as input key. The whole process happens in hardware so that neither the
decryption key for the RSA parameters nor the input key for the HMAC key derivation function can be seen by the
software while calculating the signature.
For more detailed information on the hardware involved in signature calculation and the registers used, see ESP32-S2
Technical Reference Manual > Digital Signature (DS) [PDF].
Private Key Parameters
The private key parameters for the RSA signature are stored in flash. To prevent unauthorized access, they are AES-
encrypted. The HMAC module is used as a key-derivation function to calculate the AES encryption key for the private
key parameters. In turn, the HMAC module uses a key from the eFuses key block which can be read-protected to
prevent unauthorized access as well.
Upon signature calculation invocation, the software only specifies which eFuse key to use, the corresponding eFuse
key purpose, the location of the encrypted RSA parameters and the message.
Key Generation
Both the HMAC key and the RSA private key have to be created and stored before the DS peripheral can be used.
This needs to be done in software on the ESP32-S2 or alternatively on a host. For this context, the IDF provides
esp_efuse_write_block() to set the HMAC key and esp_hmac_calculate() to encrypt the private
RSA key parameters.
You can find instructions on how to calculate and assemble the private key parameters in ESP32-S2 Technical Reference
Manual > Digital Signature (DS) [PDF].
Signature Calculation with IDF
For more detailed information on the workflow and the registers used, see ESP32-S2 Technical Reference Manual >
Digital Signature (DS) [PDF].
Three parameters need to be prepared to calculate the digital signature:
1. the eFuse key block ID which is used as key for the HMAC,
2. the location of the encrypted private key parameters,
3. and the message to be signed.
Since the signature calculation takes some time, there are two possible API versions to use in IDF. The first one is
esp_ds_sign() and simply blocks until the calculation is finished. If software needs to do something else during
the calculation, esp_ds_start_sign() can be called, followed by periodic calls to esp_ds_is_busy() to
check when the calculation has finished. Once the calculation has finished, esp_ds_finish_sign() can be
called to get the resulting signature.
Note: Note that this is only the basic DS building block, the message length is fixed. To create signatures of arbitrary
messages, the input is normally a hash of the actual message, padded up to the required length. An API to do this is
planned in the future.
Configure the DS peripheral for a TLS connection
The DS peripheral on ESP32-S2 chip must be configured before it can be used for a TLS connection. The configu-
ration involves the following steps -
Espressif Systems 276
Submit Document Feedback
Release v4.4

Espressif ESP32-S2 Specifications

General

Brand	Espressif
Model	ESP32-S2
Category	Single board computers
Language	English