Espressif ESP32-S2 User Manual

Chapter 2. API Reference
HMAC on the ESP32-S2
On the ESP32-S2, the HMAC module works with a secret key burnt into the eFuses. This eFuse key can be made
completely inaccessible for any resources outside the cryptographic modules, thus avoiding key leakage.
Furthermore, the ESP32-S2 has three different application scenarios for its HMAC module:
1. HMAC is generated for software use
2. HMAC is used as a key for the Digital Signature (DS) module
3. HMAC is used for enabling the soft-disabled JTAG interface
The first mode is also called Upstream mode, while the last two modes are also called Downstream modes.
eFuse Keys for HMAC Six physical eFuse blocks can be used as keys for the HMAC module: block 4 up to
block 9. The enum hmac_key_id_t in the API maps them to HMAC_KEY0 …HMAC_KEY5. Each key has a
corresponding eFuse parameter key purpose determining for which of the three HMAC application scenarios (see
below) the key may be used:
Key Purpose Application Scenario
8 HMAC generated for software use
7 HMAC used as a key for the Digital Signature (DS) module
6 HMAC used for enabling the soft-disabled JTAG interface
5 HMAC both as a key for the DS module and for enabling JTAG
This is to prevent the usage of a key for a different function than originally intended.
To calculate an HMAC, the software has to provide the ID of the key block containing the secret key as well as the
key purpose (see ESP32-S2 Technical Reference Manual > eFuse Controller (eFuse) [PDF]). Before the HMAC key
calculation, the HMAC module looks up the purpose of the provided key block. The calculation only proceeds if the
provided key purpose matches the purpose stored in the eFuses of the key block provided by the ID.
HMAC Generation for Software Key Purpose value: 8
In this case, the HMAC is given out to the software (e.g. to authenticate a message).
The API to calculate the HMAC is esp_hmac_calculate(). Only the message, message length and the eFuse
key block ID have to be provided to that function. The rest, like setting the key purpose, is done automatically.
HMAC for Digital Signature Key Purpose values: 7, 5
The HMAC can be used as a key derivation function to decrypt private key parameters which are used by the Digital
Signature module. A standard message is used by the hardware in that case. The user only needs to provide the eFuse
key block and purpose on the HMAC side (additional parameters are required for the Digital Signature component in
that case). Neither the key nor the actual HMAC are ever exposed to outside the HMAC module and DS component.
The calculation of the HMAC and its hand-over to the DS component happen internally.
For more details, see ESP32-S2 Technical Reference Manual > Digital Signature (DS) [PDF].
HMAC for Enabling JTAG Key Purpose values: 6, 5
The third application is using the HMAC as a key to enable JTAG if it was soft-disabled before. Following is the
procedure to re-enable the JTAG
Setup
1. Generate a 256-bit HMAC secret key to use for JTAG re-enable.
2. Write the key to an eFuse block with key purpose HMAC_DOWN_ALL (5) or HMAC_DOWN_JTAG (6).
This can be done using the ets_efuse_write_key() function in the firmware or using espefuse.py from the host.
3. Configure the eFuse key block to be read protected using the esp_efuse_set_read_protect(), so that software
cannot read back the value.
Espressif Systems 273
Submit Document Feedback
Release v4.4

Espressif ESP32-S2 Specifications

General

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