Mirrors/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2026-10-02 03:00:34 +03:00
Code Issues Packages Projects Releases Wiki Activity

docs(key-manager): Add Key-Manager peripheral related documentation

Browse Source
This commit is contained in:
harshal.patil
2026-03-18 16:42:21 +05:30
parent bc2c857bc9
commit 629a4e2444
28 changed files with 1645 additions and 239 deletions
Download Patch File Download Diff File Expand all files Collapse all files
components/esp_hal_security/include/hal/key_mgr_types.h
+23 -16
View File
@@ -1,5 +1,5 @@
/*
* SPDX-FileCopyrightText: 2023-2025 Espressif Systems (Shanghai) CO LTD
* SPDX-FileCopyrightText: 2023-2026 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
@@ -48,7 +48,7 @@ typedef enum {
ESP_KEY_MGR_PSRAM_XTS_AES_KEY, /* PSRAM XTS-AES key */
} esp_key_mgr_key_type_t;
/*
/**
* @brief Key Manager key usage type
*/
typedef enum {
@@ -112,30 +112,37 @@ typedef enum {
ESP_KEY_MGR_FORCE_USE_KM_DS_KEY = 3,
} esp_key_mgr_force_use_km_key_t;
// store huk info, occupy 96 words
/**
* @brief HUK info structure, stores HUK recovery information
*/
typedef struct PACKED_ATTR {
#define HUK_INFO_LEN 660
uint8_t info[HUK_INFO_LEN];
uint32_t crc;
uint8_t info[HUK_INFO_LEN]; /*!< HUK info data */
uint32_t crc; /*!< CRC of the HUK info */
} esp_key_mgr_huk_info_t;
// store key info, occupy 512 bits
/**
* @brief Key info structure, stores key recovery information (512 bits)
*/
typedef struct PACKED_ATTR {
#define KEY_INFO_LEN 64
uint8_t info[KEY_INFO_LEN];
uint32_t crc;
uint8_t info[KEY_INFO_LEN]; /*!< Key info data */
uint32_t crc; /*!< CRC of the key info */
} esp_key_mgr_key_info_t;
/**
* @brief Key recovery info structure containing all data needed to recover a deployed key
*/
typedef struct WORD_ALIGNED_ATTR PACKED_ATTR {
#define KEY_HUK_SECTOR_MAGIC 0xDEA5CE5A
uint32_t magic;
uint32_t version; // for backward compatibility
uint8_t key_type;
uint8_t key_len;
uint8_t key_deployment_mode;
uint8_t reserved[13];
esp_key_mgr_huk_info_t huk_info;
esp_key_mgr_key_info_t key_info[2]; // at most 2 key info (XTS-512_1 and XTS-512_2), at least use 1
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) */
} esp_key_mgr_key_recovery_info_t;
#ifdef __cplusplus
components/esp_security/include/esp_key_mgr.h
+70 -55
View File
@@ -1,5 +1,5 @@
/*
* SPDX-FileCopyrightText: 2023-2025 Espressif Systems (Shanghai) CO LTD
* SPDX-FileCopyrightText: 2023-2026 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
@@ -33,36 +33,48 @@ extern "C" {
#define KEY_MGR_ECDH0_INFO_SIZE 64
#define KEY_MGR_PLAINTEXT_KEY_SIZE 32
/**
* @brief Configuration for deploying a key in AES mode
*/
typedef struct {
esp_key_mgr_key_type_t key_type;
esp_key_mgr_key_len_t key_len;
bool use_pre_generated_huk_info;
bool use_pre_generated_sw_init_key;
WORD_ALIGNED_ATTR esp_key_mgr_huk_info_t huk_info;
WORD_ALIGNED_ATTR uint8_t sw_init_key[KEY_MGR_SW_INIT_KEY_SIZE];
WORD_ALIGNED_ATTR uint8_t k2_info[KEY_MGR_K2_INFO_SIZE];
WORD_ALIGNED_ATTR uint8_t k1_encrypted[2][KEY_MGR_K1_ENCRYPTED_SIZE];
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 */
WORD_ALIGNED_ATTR esp_key_mgr_huk_info_t huk_info; /*!< HUK recovery info */
WORD_ALIGNED_ATTR uint8_t sw_init_key[KEY_MGR_SW_INIT_KEY_SIZE]; /*!< Software init key */
WORD_ALIGNED_ATTR uint8_t k2_info[KEY_MGR_K2_INFO_SIZE]; /*!< K2 info for AES deployment */
WORD_ALIGNED_ATTR uint8_t k1_encrypted[2][KEY_MGR_K1_ENCRYPTED_SIZE]; /*!< Encrypted K1 key data */
} esp_key_mgr_aes_key_config_t;
/**
* @brief Configuration for deploying a key in ECDH0 mode
*/
typedef struct {
esp_key_mgr_key_type_t key_type;
esp_key_mgr_key_len_t key_len;
bool use_pre_generated_huk_info;
WORD_ALIGNED_ATTR esp_key_mgr_huk_info_t huk_info;
WORD_ALIGNED_ATTR uint8_t k1_G[2][KEY_MGR_ECDH0_INFO_SIZE];
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 */
WORD_ALIGNED_ATTR esp_key_mgr_huk_info_t huk_info; /*!< HUK recovery info */
WORD_ALIGNED_ATTR uint8_t k1_G[2][KEY_MGR_ECDH0_INFO_SIZE]; /*!< K1*G points for ECDH0 deployment */
} esp_key_mgr_ecdh0_key_config_t;
/**
* @brief Configuration for deploying a key in Random mode
*/
typedef struct {
esp_key_mgr_key_type_t key_type;
esp_key_mgr_key_len_t key_len;
bool use_pre_generated_huk_info;
WORD_ALIGNED_ATTR esp_key_mgr_huk_info_t huk_info;
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 */
WORD_ALIGNED_ATTR esp_key_mgr_huk_info_t huk_info; /*!< HUK recovery info */
} esp_key_mgr_random_key_config_t;
/**
* @brief ECDH0 key info generated during ECDH0 deployment
*/
typedef struct {
esp_key_mgr_key_type_t key_type;
esp_key_mgr_key_len_t key_len;
WORD_ALIGNED_ATTR uint8_t k2_G[2][KEY_MGR_ECDH0_INFO_SIZE];
esp_key_mgr_key_type_t key_type; /*!< Type of key */
esp_key_mgr_key_len_t key_len; /*!< Length of the key */
WORD_ALIGNED_ATTR uint8_t k2_G[2][KEY_MGR_ECDH0_INFO_SIZE]; /*!< K2*G points from ECDH0 deployment */
} esp_key_mgr_ecdh0_info_t;
/**
@@ -74,63 +86,66 @@ void key_mgr_wait_for_state(esp_key_mgr_state_t state);
/**
* @brief Deploy key in AES deployment mode
* @input
* key_config(input) AES key configuration
* key_info(output) A writable struct of esp_key_mgr_key_info_t type.
* The recovery information for the the deployed key shall be stored here (Make sure that the memory is valid during the deployment process).
*
* @param[in] key_config AES key configuration
* @param[out] key_info A writable struct of esp_key_mgr_key_recovery_info_t type.
* The recovery information for the deployed key shall be stored here.
* @return
* ESP_OK for success
* ESP_FAIL/relevant error code for failure
* - ESP_OK on success
* - ESP_FAIL or relevant error code on failure
*/
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);
/**
* @brief Deploy key in ECDH0 deployment mode
* @input
* key_config(input) ECDH0 key configuration
* key_info(output) A writable struct of esp_key_mgr_key_info_t type. The recovery key info for the deployed key shall be stored here (Make sure that the memory is valid during the deployment process).
* ecdh0_key_info A writable struct of esp_key_mgr_ecdh0_info_t. The ecdh0 info to recover the actual key shall be stored here.
*
* @param[in] key_config ECDH0 key configuration
* @param[out] key_info A writable struct of esp_key_mgr_key_recovery_info_t type.
* The recovery key info for the deployed key shall be stored here.
* @param[out] ecdh0_key_info A writable struct of esp_key_mgr_ecdh0_info_t type.
* The ECDH0 info to recover the actual key shall be stored here.
* @return
* ESP_OK for success
* ESP_FAIL/relevant error code for failure
* - 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);
/**
* @brief Deploy key in Random deployment mode
* @input
* key_config(input) Random key configuration
* key_info(output) A writable struct of esp_key_mgr_key_info_t type. The recovery key info for the deployed key shall be stored here (Make sure that the memory is valid during the deployment process).
*
* @param[in] key_config Random key configuration
* @param[out] key_info A writable struct of esp_key_mgr_key_recovery_info_t type.
* The recovery key info for the deployed key shall be stored here.
* @return
* ESP_OK for success
* ESP_FAIL/relevant error code for failure
* - 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);
/*
/**
* @brief 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
* @input
* key_info The key info required to recover the key
* @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.
*
* @param[in] key_recovery_info The key recovery info required to recover the key
* @return
* ESP_OK for success
* ESP_FAIL/relevant error code for failure
* - 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);
/*
* @brief De-activate a key from the given key info
* The key which is de-activated can no longer be used for any operation
* @input
* key_info The key info required to recover the key
/**
* @brief De-activate a key of the given type
*
* The key which is de-activated can no longer be used for any operation.
*
* @param[in] key_type The type of the key to deactivate
* @return
* ESP_OK for success
* ESP_FAIL/relevant error code for failure
* - 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);