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 function. 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-S3 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-S3 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-S3 Technical Reference Manual > Digital Signature (DS) [PDF].
Signature Calculation with IDF¶
For more detailed information on the workflow and the registers used, see ESP32-S3 Technical Reference Manual > Digital Signature (DS) [PDF].
Three parameters need to be prepared to calculate the digital signature:
the eFuse key block ID which is used as key for the HMAC,
the location of the encrypted private key parameters,
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 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-S3 chip must be configured before it can be used for a TLS connection. The configuration involves the following steps -
Randomly generate a 256 bit value called the Initialization Vector (IV).
Randomly generate a 256 bit value called the HMAC_KEY.
Calculate the encrypted private key paramters from the client private key (RSA) and the parameters generated in the above steps.
Then burn the 256 bit HMAC_KEY on the efuse, which can only be read by the DS peripheral.
For more details, see ESP32-S3 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 Signature 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 partition onto the ESP32-S3. 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 authentication. The ssl part is internally performed with ESP-TLS. See example README for more details.
API Reference¶
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()andesp_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 signature is invalid.
ESP_ERR_HW_CRYPTO_DS_INVALID_PADDING if the message padding is incorrect, the signature can be read though since the message digest matches.
- Parameters
message: the message to be signed; its length is determined by data->rsa_lengthdata: the encrypted signing key data (AES encrypted RSA key + IV)key_id: the HMAC key ID determining the HMAC key of the HMAC which will be used to decrypt the signing key datasignature: the destination of the signature, should be (data->rsa_length + 1)*4 bytes long
-
esp_err_t
esp_ds_start_sign(const void *message, const esp_ds_data_t *data, hmac_key_id_t key_id, esp_ds_context_t **esp_ds_ctx)¶ Start the signing process.
This function yields a context object which needs to be passed to
esp_ds_finish_sign()to finish the signing process.- Note
This function locks the HMAC, SHA, AES and RSA components, so the user has to ensure to call
esp_ds_finish_sign()in a timely manner.- Return
ESP_OK if successful, the ds operation was started now and has to be finished with
esp_ds_finish_sign()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
- Parameters
message: the message to be signed; its length is determined by data->rsa_lengthdata: the encrypted signing key data (AES encrypted RSA key + IV)key_id: the HMAC key ID determining the HMAC key of the HMAC which will be used to decrypt the signing key dataesp_ds_ctx: the context object which is needed for finishing the signing process later
-
bool
esp_ds_is_busy(void)¶ Return true if the DS peripheral is busy, otherwise false.
- Note
Only valid if
esp_ds_start_sign()was called before.
-
esp_err_t
esp_ds_finish_sign(void *signature, esp_ds_context_t *esp_ds_ctx)¶ Finish the signing process.
- Return
ESP_OK if successful, the ds operation has been finished and the result is written to signature.
ESP_ERR_INVALID_ARG if one of the parameters is NULL
ESP_ERR_HW_CRYPTO_DS_INVALID_DIGEST if the message digest didn’t match; the signature is invalid.
ESP_ERR_HW_CRYPTO_DS_INVALID_PADDING if the message padding is incorrect, the signature can be read though since the message digest matches.
- Parameters
signature: the destination of the signature, should be (data->rsa_length + 1)*4 bytes longesp_ds_ctx: the context object retreived byesp_ds_start_sign()
-
esp_err_t
esp_ds_encrypt_params(esp_ds_data_t *data, const void *iv, const esp_ds_p_data_t *p_data, const void *key)¶ Encrypt the private key parameters.
- Return
ESP_OK if successful, the ds operation has been finished and the result is written to signature.
ESP_ERR_INVALID_ARG if one of the parameters is NULL or p_data->rsa_length is too long
- Parameters
data: Output buffer to store encrypted data, suitable for later use generating signatures. The allocated memory must be in internal memory and word aligned since it’s filled by DMA. Both is asserted at run time.iv: Pointer to 16 byte IV buffer, will be copied into ‘data’. Should be randomly generated bytes each time.p_data: Pointer to input plaintext key data. The expectation is this data will be deleted after this process is done and ‘data’ is stored.key: Pointer to 32 bytes of key data. Type determined by key_type parameter. The expectation is the corresponding HMAC key will be stored to efuse and then permanently erased.
Structures¶
-
struct
esp_digital_signature_data¶ Encrypted private key data. Recommended to store in flash in this format.
- Note
This struct has to match to one from the ROM code! This documentation is mostly taken from there.
Public Members
-
esp_digital_signature_length_t
rsa_length¶ RSA LENGTH register parameters (number of words in RSA key & operands, minus one).
Max value 127 (for RSA 4096).
This value must match the length field encrypted and stored in ‘c’, or invalid results will be returned. (The DS peripheral will always use the value in ‘c’, not this value, so an attacker can’t alter the DS peripheral results this way, it will just truncate or extend the message and the resulting signature in software.)
- Note
In IDF, the enum type length is the same as of type unsigned, so they can be used interchangably. See the ROM code for the original declaration of struct
ets_ds_data_t.
-
uint8_t
iv[ESP_DS_IV_LEN]¶ IV value used to encrypt ‘c’
-
uint8_t
c[ESP_DS_C_LEN]¶ Encrypted Digital Signature parameters. Result of AES-CBC encryption of plaintext values. Includes an encrypted message digest.
-
struct
esp_ds_p_data_t¶ Plaintext parameters used by Digital Signature.
Not used for signing with DS peripheral, but can be encrypted in-device by calling esp_ds_encrypt_params()
- Note
This documentation is mostly taken from the ROM code.
Macros¶
-
ESP32S3_ERR_HW_CRYPTO_DS_HMAC_FAIL¶ HMAC peripheral problem
-
ESP32S3_ERR_HW_CRYPTO_DS_INVALID_KEY¶ given HMAC key isn’t correct, HMAC peripheral problem
-
ESP32S3_ERR_HW_CRYPTO_DS_INVALID_DIGEST¶ message digest check failed, result is invalid
-
ESP32S3_ERR_HW_CRYPTO_DS_INVALID_PADDING¶ padding check failed, but result is produced anyway and can be read
-
ESP_DS_IV_LEN¶
-
ESP_DS_C_LEN¶
Type Definitions¶
-
typedef struct esp_ds_context
esp_ds_context_t¶
-
typedef struct esp_digital_signature_data
esp_ds_data_t¶ Encrypted private key data. Recommended to store in flash in this format.
- Note
This struct has to match to one from the ROM code! This documentation is mostly taken from there.