Espressif ESP32-S2 User Manual

Chapter 2. API Reference
1) Randomly generate a 256 bit value called the Initialization Vector (IV).
2) Randomly generate a 256 bit value called the HMAC_KEY.
3) Calculate the encrypted private key paramters from the client private key (RSA) and the parameters generated
in the above steps.
4) Then burn the 256 bit HMAC_KEY on the efuse, which can only be read by the DS peripheral.
For more details, see ESP32-S2 Technical Reference Manual > Digital Signature (DS) [PDF].
To configure the DS peripheral for development purposes, you can use the python script configure_ds.py. More
details about the configure_ds.py script can be found at mqtt example README .
The encrypted private key parameters obtained after the DS peripheral configuration are then to be kept in flash.
Furthermore, they are to be passed to the DS peripheral which makes use of those parameters for the Digital Signa-
ture operation. Non Volatile Storage can be used to store the encrypted private key parameters in flash. The script
configure_ds.py creates an NVS partition for the encrypted private key parameters. Then the script flashes this par-
tition onto the ESP32-S2. The application then needs to read the DS data from NVS, which can be done with the
function esp_read_ds_data_from_nvs in file ssl_mutual_auth/main/app_main.c
The process of initializing the DS peripheral and then performing the Digital Signature operation is done internally
with help of ESP-TLS. Please refer to Digital Signature with ESP-TLS in ESP-TLS for more details. As mentioned in
the ESP-TLS documentation, the application only needs to provide the encrypted private key parameters to the esp_tls
context (as ds_data), which internally performs all necessary operations for initializing the DS peripheral and then
performing the DS operation.
Example for SSL Mutual Authentication using DS
The example ssl_ds shows how to use the DS peripheral for mutual authentication. The example uses mqtt_client
(Implemented through ESP-MQTT) to connect to broker test.mosquitto.org using ssl transport with mutual authenti-
cation. The ssl part is internally performed with ESP-TLS. See example README for more details.
API Reference
Header File
• components/esp_hw_support/include/soc/esp32s2/esp_ds.h
Functions
esp_err_t esp_ds_sign(const void *message, const esp_ds_data_t *data, hmac_key_id_t key_id, void
*signature)
Sign the message.
This function is a wrapper around esp_ds_finish_sign() and esp_ds_start_sign(), so do not
use them in parallel. It blocks until the signing is finished and then returns the signature.
Note This function locks the HMAC, SHA, AES and RSA components during its entire execution time.
Return
• ESP_OK if successful, the signature was written to the parameter signature.
• ESP_ERR_INVALID_ARG if one of the parameters is NULL or data->rsa_length is too long or 0
• ESP_ERR_HW_CRYPTO_DS_HMAC_FAIL if there was an HMAC failure during retrieval of
the decryption key
• ESP_ERR_NO_MEM if there hasn’t been enough memory to allocate the context object
• ESP_ERR_HW_CRYPTO_DS_INVALID_KEY if there’s a problem with passing the HMAC
key to the DS component
• ESP_ERR_HW_CRYPTO_DS_INVALID_DIGEST if the message digest didn’t match; the sig-
nature is invalid.
• ESP_ERR_HW_CRYPTO_DS_INVALID_PADDING if the message padding is incorrect, the sig-
nature can be read though since the message digest matches.
Parameters
• message: the message to be signed; its length is determined by data->rsa_length
• data: the encrypted signing key data (AES encrypted RSA key + IV)
Espressif Systems 277
Submit Document Feedback
Release v4.4

Espressif ESP32-S2 Specifications

General

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