Key Manager

[中文]

The ESP32-C5's Key Manager peripheral provides hardware-assisted key deployment and recovery for cryptographic keys. It allows cryptographic keys to be provisioned and used without storing plaintext key material in flash, RAM, or eFuses.

The Key Manager is intended for applications that require secure handling of long-term cryptographic keys.

Note

The Key Manager peripheral is only supported on ESP32-C5 chip revision >= v1.2.

Key Manager provides the following properties:

  • Device uniqueness

    Keys are cryptographically bound to a Hardware Unique Key (HUK) that is unique to each chip.

  • No plaintext key storage

    Key material is never exposed to software accessible memory.

  • Flexible key lifecycle

    Keys can be deployed, recovered, or replaced by a newer key without reprogramming the eFuses for each key.

  • Resistance to physical extraction

    Reading flash or eFuses contents would not reveal usable key material.

Hardware Unique Key (HUK)

The Hardware Unique Key (HUK) is a device-specific unique key generated entirely in hardware HUK peripheral. It is generated using SRAM Physical Unclonable Function (PUF) and is reconstructed using the HUK recovery info stored in the key recovery info of a Key Manager deployed key. See ESP32-C5 Technical Reference Manual > Chapter Key Manager [PDF] > HUK Generator for more details about the HUK peripheral.

The HUK acts as the root of trust for all keys deployed through the Key Manager.

Key Deployment and Key Recovery

The Key Manager operates in two distinct phases:

  • Key deployment

    A cryptographic key is generated or securely introduced into the chip, and it gets bound to the HUK. This step is usually performed during manufacturing, first boot up or when generating transient or persistent keys during the application runtime.

  • Key recovery

    On subsequent boots, a Key Manager-deployed persistent key is restored using the previously generated key recovery information, without exposing the key value.

During deployment, the Key Manager generates a data structure referred to as esp_key_mgr_key_recovery_info_t. In case of persistent keys, the applications must store this data in non-volatile storage (for example, flash) in order to recover the key on later boots.

Supported Key Types

The Key Manager can manage keys for the following key types:

  • ECDSA

  • Flash Encryption (XTS-AES)

  • HMAC

  • Digital Signature peripherals

  • PSRAM Encryption

Each key is associated with a esp_key_mgr_key_purpose_t, which defines how the key can be used by hardware peripherals.

Key Deployment Modes

The Key Manager provides multiple key deployment modes to support different provisioning and security requirements.

Random Deploy Mode

In this mode, the Key Manager generates a random private key internally.

  • The key value is never known to the application software.

  • No external key material is required.

  • Intended for use cases where the key does not need to be backed up or exported.

AES Deploy Mode

In this mode, a user-specified private key is securely deployed.

  • The key is encrypted before being transmitted to the chip.

  • Auxiliary key material is used to protect the deployment process.

  • Intended for factory provisioning scenarios where the key value must be predefined.

ECDH0 Deploy Mode

In this mode, a private key is negotiated using Elliptic Curve Diffie-Hellman (ECDH).

  • The final private key is never transmitted.

  • The deployment process can occur over an untrusted channel.

  • Intended for high-security provisioning environments.

For detailed information various deployment modes, see ESP32-C5 Technical Reference Manual > Chapter Key Manager [PDF] > Section Key Manager.

Typical Workflows

First Boot or Manufacturing

A typical provisioning flow includes:

  1. Generating the Hardware Unique Key (HUK)

  2. Deploying required cryptographic keys using an appropriate deployment mode

  3. Storing the generated key_recovery_info in non-volatile storage

  4. Locking relevant security configuration eFuses, if required

This process is usually performed once per device.

Normal Boot

During a normal boot:

  1. The application provides the previously generated and stored key_recovery_info of a Key Manager-deployed key.

  2. The HUK is reconstructed automatically by hardware.

  3. The Key Manager recovers the deployed key internally.

  4. Cryptographic peripherals can use the recovered key.

Security Considerations

Applications using the Key Manager should consider the following:

  • Protect the key_recovery_info of a Key Manager-deployed key against unauthorized modification or loss.

  • Lock Key Manager's security-related eFuses after successful key deployment to prevent re-deployment of a key of the same type.

  • Avoid deploying new XTS-AES keys when Flash Encryption is already enabled unless explicitly intended.

API Reference

Header File

  • components/esp_security/include/esp_key_mgr.h

  • This header file can be included with:

    #include "esp_key_mgr.h"

  • This header file is a part of the API provided by the esp_security component. To declare that your component depends on esp_security, add the following to your CMakeLists.txt:

    REQUIRES esp_security

    or

    PRIV_REQUIRES esp_security

Functions

void key_mgr_wait_for_state(esp_key_mgr_state_t state)

Wait for the Key Manager to reach the given state.

Parameters:

state -- The state to wait for

esp_err_t esp_key_mgr_deploy_key_in_aes_mode(const esp_key_mgr_aes_key_config_t *key_config, esp_key_mgr_key_recovery_info_t *key_info)

Deploy key in AES deployment mode.

Parameters:

  • key_config -- [in] AES key configuration

  • key_info -- [out] A writable struct of esp_key_mgr_key_recovery_info_t type. The recovery information for the deployed key shall be stored here.

Returns:

  • ESP_OK on success

  • ESP_FAIL or relevant error code on failure

esp_err_t esp_key_mgr_deploy_key_in_ecdh0_mode(const esp_key_mgr_ecdh0_key_config_t *key_config, esp_key_mgr_key_recovery_info_t *key_info, esp_key_mgr_ecdh0_info_t *ecdh0_key_info)

Deploy key in ECDH0 deployment mode.

Parameters:

  • key_config -- [in] ECDH0 key configuration

  • key_info -- [out] A writable struct of esp_key_mgr_key_recovery_info_t type. The recovery key info for the deployed key shall be stored here.

  • ecdh0_key_info -- [out] A writable struct of esp_key_mgr_ecdh0_info_t type. The ECDH0 info to recover the actual key shall be stored here.

Returns:

  • ESP_OK on success

  • ESP_FAIL or relevant error code on failure

esp_err_t esp_key_mgr_deploy_key_in_random_mode(const esp_key_mgr_random_key_config_t *key_config, esp_key_mgr_key_recovery_info_t *key_info)

Deploy key in Random deployment mode.

Parameters:

  • key_config -- [in] Random key configuration

  • key_info -- [out] A writable struct of esp_key_mgr_key_recovery_info_t type. The recovery key info for the deployed key shall be stored here.

Returns:

  • ESP_OK on success

  • ESP_FAIL or relevant error code on failure

esp_err_t esp_key_mgr_activate_key(esp_key_mgr_key_recovery_info_t *key_recovery_info)

Recover and Activate a key from the given key info.

Note

Once a key of particular type is activated through Key Manager, then a different key of the same type cannot be activated at the same time. This key must be deactivated first through a call to esp_key_mgr_deactivate_key() before activating other key of the same type.

Parameters:

key_recovery_info -- [in] The key recovery info required to recover the key

Returns:

  • ESP_OK on success

  • ESP_FAIL or relevant error code on failure

esp_err_t esp_key_mgr_deactivate_key(esp_key_mgr_key_type_t key_type)

De-activate a key of the given type.

The key which is de-activated can no longer be used for any operation.

Parameters:

key_type -- [in] The type of the key to deactivate

Returns:

  • ESP_OK on success

  • ESP_FAIL or relevant error code on failure

Structures

struct esp_key_mgr_aes_key_config_t

Configuration for deploying a key in AES mode.

Public Members

esp_key_mgr_key_type_t key_type

Type of key to deploy

esp_key_mgr_key_len_t key_len

Length of the key

bool use_pre_generated_huk_info

Use pre-generated HUK info if true

bool use_pre_generated_sw_init_key

Use pre-generated software init key if true

esp_key_mgr_huk_info_t huk_info

HUK recovery info

uint8_t sw_init_key[KEY_MGR_SW_INIT_KEY_SIZE]

Software init key

uint8_t k2_info[KEY_MGR_K2_INFO_SIZE]

K2 info for AES deployment

uint8_t k1_encrypted[2][KEY_MGR_K1_ENCRYPTED_SIZE]

Encrypted K1 key data

struct esp_key_mgr_ecdh0_key_config_t

Configuration for deploying a key in ECDH0 mode.

Public Members

esp_key_mgr_key_type_t key_type

Type of key to deploy

esp_key_mgr_key_len_t key_len

Length of the key

bool use_pre_generated_huk_info

Use pre-generated HUK info if true

esp_key_mgr_huk_info_t huk_info

HUK recovery info

uint8_t k1_G[2][KEY_MGR_ECDH0_INFO_SIZE]

K1*G points for ECDH0 deployment

struct esp_key_mgr_random_key_config_t

Configuration for deploying a key in Random mode.

Public Members

esp_key_mgr_key_type_t key_type

Type of key to deploy

esp_key_mgr_key_len_t key_len

Length of the key

bool use_pre_generated_huk_info

Use pre-generated HUK info if true

esp_key_mgr_huk_info_t huk_info

HUK recovery info

struct esp_key_mgr_ecdh0_info_t

ECDH0 key info generated during ECDH0 deployment.

Public Members

esp_key_mgr_key_type_t key_type

Type of key

esp_key_mgr_key_len_t key_len

Length of the key

uint8_t k2_G[2][KEY_MGR_ECDH0_INFO_SIZE]

K2*G points from ECDH0 deployment

Macros

KEY_MGR_SW_INIT_KEY_SIZE
KEY_MGR_ASSIST_INFO_SIZE
KEY_MGR_KEY_RECOVERY_INFO_SIZE
KEY_MGR_HUK_INFO_SIZE
KEY_MGR_HUK_RISK_ALERT_LEVEL
KEY_MGR_KEY_INFO_SIZE
KEY_MGR_K2_INFO_SIZE
KEY_MGR_K1_ENCRYPTED_SIZE
KEY_MGR_ECDH0_INFO_SIZE
KEY_MGR_PLAINTEXT_KEY_SIZE

Header File

  • components/esp_hal_security/include/hal/key_mgr_types.h

  • This header file can be included with:

    #include "hal/key_mgr_types.h"

  • This header file is a part of the API provided by the esp_hal_security component. To declare that your component depends on esp_hal_security, add the following to your CMakeLists.txt:

    REQUIRES esp_hal_security

    or

    PRIV_REQUIRES esp_hal_security

Structures

struct esp_key_mgr_huk_info_t

HUK info structure, stores HUK recovery information.

Public Members

uint8_t info[HUK_INFO_LEN]

HUK info data

uint32_t crc

CRC of the HUK info

struct esp_key_mgr_key_info_t

Key info structure, stores key recovery information (512 bits)

Public Members

uint8_t info[KEY_INFO_LEN]

Key info data

uint32_t crc

CRC of the key info

struct esp_key_mgr_key_recovery_info_t

Key recovery info structure containing all data needed to recover a deployed key.

Public Members

uint32_t magic

Magic number for validation

uint32_t version

Version for backward compatibility

uint8_t key_type

Type of the deployed key

uint8_t key_len

Length of the deployed key

uint8_t key_deployment_mode

Deployment mode used for the key

uint8_t reserved[13]

Reserved for future use

esp_key_mgr_huk_info_t huk_info

HUK recovery info

esp_key_mgr_key_info_t key_info[2]

Key info (up to 2 entries for XTS-AES-256)

Macros

KEY_MGR_ASSIST_INFO_LEN
HUK_INFO_LEN
KEY_INFO_LEN
KEY_HUK_SECTOR_MAGIC

Enumerations

enum esp_key_mgr_state_t

State of Key Manager: idle, load, gain or busy.

Values:

enumerator ESP_KEY_MGR_STATE_IDLE
enumerator ESP_KEY_MGR_STATE_LOAD
enumerator ESP_KEY_MGR_STATE_GAIN
enumerator ESP_KEY_MGR_STATE_BUSY
enum esp_key_mgr_key_len_t

Length of the deployed key (XTS-AES, ECDSA)

Values:

enumerator ESP_KEY_MGR_ECDSA_LEN_192
enumerator ESP_KEY_MGR_ECDSA_LEN_256
enumerator ESP_KEY_MGR_ECDSA_LEN_384
enumerator ESP_KEY_MGR_XTS_AES_LEN_128
enumerator ESP_KEY_MGR_XTS_AES_LEN_256
enum esp_key_mgr_key_type_t

Type of the key.

Values:

enumerator ESP_KEY_MGR_ECDSA_KEY
enumerator ESP_KEY_MGR_FLASH_XTS_AES_KEY
enumerator ESP_KEY_MGR_HMAC_KEY
enumerator ESP_KEY_MGR_DS_KEY
enumerator ESP_KEY_MGR_PSRAM_XTS_AES_KEY
enum esp_key_mgr_key_usage_t

Key Manager key usage type.

Values:

enumerator ESP_KEY_MGR_USE_OWN_KEY
enumerator ESP_KEY_MGR_USE_EFUSE_KEY
enumerator ESP_KEY_MGR_USAGE_INVALID
enum esp_key_mgr_key_purpose_t

Key Purpose to be set for a particular key in the Key Manager.

Values:

enumerator ESP_KEY_MGR_KEY_PURPOSE_INVALID
enumerator ESP_KEY_MGR_KEY_PURPOSE_ECDSA_192
enumerator ESP_KEY_MGR_KEY_PURPOSE_ECDSA_256
enumerator ESP_KEY_MGR_KEY_PURPOSE_FLASH_256_1
enumerator ESP_KEY_MGR_KEY_PURPOSE_XTS_AES_256_1
enumerator ESP_KEY_MGR_KEY_PURPOSE_FLASH_256_2
enumerator ESP_KEY_MGR_KEY_PURPOSE_XTS_AES_256_2
enumerator ESP_KEY_MGR_KEY_PURPOSE_FLASH_128
enumerator ESP_KEY_MGR_KEY_PURPOSE_XTS_AES_128
enumerator ESP_KEY_MGR_KEY_PURPOSE_HMAC
enumerator ESP_KEY_MGR_KEY_PURPOSE_DS
enumerator ESP_KEY_MGR_KEY_PURPOSE_PSRAM_256_1
enumerator ESP_KEY_MGR_KEY_PURPOSE_PSRAM_256_2
enumerator ESP_KEY_MGR_KEY_PURPOSE_PSRAM_128
enumerator ESP_KEY_MGR_KEY_PURPOSE_ECDSA_384_L
enumerator ESP_KEY_MGR_KEY_PURPOSE_ECDSA_384_H
enum esp_key_mgr_key_generator_mode_t

Key Manager Generator mode.

Values:

enumerator ESP_KEY_MGR_KEYGEN_MODE_RANDOM
enumerator ESP_KEY_MGR_KEYGEN_MODE_AES
enumerator ESP_KEY_MGR_KEYGEN_MODE_ECDH0
enumerator ESP_KEY_MGR_KEYGEN_MODE_ECDH1
enumerator ESP_KEY_MGR_KEYGEN_MODE_RECOVER
enumerator ESP_KEY_MGR_KEYGEN_MODE_EXPORT
enum esp_key_mgr_interrupt_type_t

Key Manager interrupt types.

Values:

enumerator ESP_KEY_MGR_INT_PREP_DONE
enumerator ESP_KEY_MGR_INT_PROC_DONE
enumerator ESP_KEY_MGR_INT_POST_DONE
enum esp_key_mgr_force_use_km_key_t

Force use key manager key type.

Note

This is used to force the key manager to use a specific key type.

Values:

enumerator ESP_KEY_MGR_FORCE_USE_KM_ECDSA_KEY
enumerator ESP_KEY_MGR_FORCE_USE_KM_XTS_AES_KEY
enumerator ESP_KEY_MGR_FORCE_USE_KM_HMAC_KEY
enumerator ESP_KEY_MGR_FORCE_USE_KM_DS_KEY

Examples

See security/key_manager for an example demonstrating key deployment using the Key Manager and using the deployed key to perform signing operations.

This example shows how to:

  • Initialize the Key Manager

  • Deploy keys using the AES deployment mode

  • Use the PSA interface to perform signing operations using the Key Manager deployed key

Was this page helpful?