# Key Manager

[中文]

The ESP32-S31'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.

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-S31 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

- HMAC

- Digital Signature peripherals

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.

### ECDH1 Deploy Mode

This mode is similar to ECDH0 Deploy Mode, with additional flexibility for manufacturing workflows.

- Supports negotiated key deployment using auxiliary recovery data

- Allows updating deployed keys by replacing auxiliary information

- Intended for large-scale manufacturing with controlled trust assumptions

For detailed information various deployment modes, see ESP32-S31 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_ecdh1_mode(const esp_key_mgr_ecdh1_key_config_t *key_config, esp_key_mgr_key_recovery_info_t *key_info)

  Deploy key in ECDH1 deployment mode.

  Parameters:

    - key_config -- [in] ECDH1 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_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_ecdh1_key_config_t

  Configuration for deploying a key in ECDH1 mode.

  ECDH1 requires the same init_key/k2_info inputs as AES mode plus the ECDH k1*G public point(s). Unlike ECDH0, k2*G is computed by the user locally and is not read back from the Key Manager.

  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 ECDH1 deployment

  uint8_t k1_G[2][KEY_MGR_ECDH0_INFO_SIZE]

    K1*G points for ECDH1 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?

- Thank you! We received your feedback.
- If you have any comments, fill in Espressif Documentation Feedback Form.

- We value your feedback.
- Let us know how we can improve this page by filling in Espressif Documentation Feedback Form.