Mirrors/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2026-10-01 18:50: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_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);