mirror of
https://github.com/espressif/esp-idf.git
synced 2026-10-01 18:50:34 +03:00
feat(mbedtls): Add PSA Crypto driver for external secure elements
Add generic secure element PSA driver with runtime callback registration.
Consolidate Kconfig into single MBEDTLS_SECURE_ELEMENT_DRIVER_ENABLED option.
Closes https://github.com/espressif/esp-idf/issues/18388
(cherry picked from commit 1c20f525b4)
This commit is contained in:
Aditya Patwardhan
@@ -207,23 +207,23 @@ To use a custom TLS stack in your project, follow these steps:
|
||||
ATECC608A (Secure Element) with ESP-TLS
|
||||
--------------------------------------------------
|
||||
|
||||
ESP-TLS provides support for using ATECC608A cryptoauth chip with ESP32 series of SoCs. The use of ATECC608A is supported only when ESP-TLS is used with MbedTLS as its underlying SSL/TLS stack. ESP-TLS uses MbedTLS as its underlying TLS/SSL stack by default unless changed manually.
|
||||
ESP-TLS provides support for using ATECC608A cryptoauth chip with ESP32 series of SoCs via the PSA Crypto opaque driver interface. The use of ATECC608A is supported only when ESP-TLS is used with MbedTLS as its underlying SSL/TLS stack. ESP-TLS uses MbedTLS as its underlying TLS/SSL stack by default unless changed manually.
|
||||
|
||||
.. note::
|
||||
|
||||
ATECC608A chip interfaced to ESP32 series must be already configured. For details, please refer to `esp_cryptoauth_utility <https://github.com/espressif/esp-cryptoauthlib/blob/master/esp_cryptoauth_utility/README.md#esp_cryptoauth_utility>`_.
|
||||
|
||||
To enable the secure element support, and use it in your project for TLS connection, you have to follow the below steps:
|
||||
To enable the secure element support, and use it in your project for TLS connection, follow the steps below:
|
||||
|
||||
1) Add `esp-cryptoauthlib <https://github.com/espressif/esp-cryptoauthlib>`_ in your project, for details please refer `how to use esp-cryptoauthlib with ESP-IDF <https://github.com/espressif/esp-cryptoauthlib#how-to-use-esp-cryptoauthlib-with-esp-idf>`_.
|
||||
1) Add `esp-cryptoauthlib <https://github.com/espressif/esp-cryptoauthlib>`_ as a dependency in your project. For details, please refer to `how to use esp-cryptoauthlib with ESP-IDF <https://github.com/espressif/esp-cryptoauthlib#how-to-use-esp-cryptoauthlib-with-esp-idf>`_.
|
||||
|
||||
2) Enable the menuconfig option :ref:`CONFIG_ESP_TLS_USE_SECURE_ELEMENT`:
|
||||
2) Enable the menuconfig option :ref:`CONFIG_MBEDTLS_SECURE_ELEMENT_DRIVER_ENABLED`:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
menuconfig > Component config > ESP-TLS > Use Secure Element (ATECC608A) with ESP-TLS
|
||||
menuconfig > Component config > mbedTLS > Enable secure element hardware support
|
||||
|
||||
3) Select type of ATECC608A chip with following option:
|
||||
3) Select the type of ATECC608A chip:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
@@ -231,13 +231,40 @@ To enable the secure element support, and use it in your project for TLS connect
|
||||
|
||||
To know more about different types of ATECC608A chips and how to obtain the type of ATECC608A connected to your ESP module, please visit `ATECC608A chip type <https://github.com/espressif/esp-cryptoauthlib/blob/master/esp_cryptoauth_utility/README.md#find-type-of-atecc608a-chip-connected-to-esp32-wroom32-se>`_.
|
||||
|
||||
4) Enable the use of ATECC608A in ESP-TLS by providing the following config option in :cpp:type:`esp_tls_cfg_t`:
|
||||
4) Import the ATECC608A key and configure ESP-TLS to use it via :cpp:type:`esp_key_config_t`:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#include "psa/crypto.h"
|
||||
#include "psa_crypto_driver_secure_element.h"
|
||||
#include "psa_crypto_driver_secure_element_contexts.h"
|
||||
#include "esp_key_config.h"
|
||||
|
||||
/* Import ATECC608A key reference into PSA */
|
||||
psa_key_attributes_t key_attr = PSA_KEY_ATTRIBUTES_INIT;
|
||||
psa_set_key_lifetime(&key_attr, PSA_KEY_LIFETIME_SECURE_ELEMENT_VOLATILE);
|
||||
psa_set_key_usage_flags(&key_attr, PSA_KEY_USAGE_SIGN_HASH);
|
||||
psa_set_key_algorithm(&key_attr, PSA_ALG_ECDSA(PSA_ALG_SHA_256));
|
||||
psa_set_key_type(&key_attr, PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_SECP_R1));
|
||||
psa_set_key_bits(&key_attr, 256);
|
||||
|
||||
secure_element_opaque_key_t opaque_key = {
|
||||
.slot_id = 0, /* Private key slot on ATECC608A */
|
||||
};
|
||||
|
||||
psa_key_id_t psa_key_id;
|
||||
psa_import_key(&key_attr, (const uint8_t *)&opaque_key,
|
||||
sizeof(opaque_key), &psa_key_id);
|
||||
|
||||
/* Configure ESP-TLS to use the PSA key */
|
||||
esp_key_config_t key_config = {
|
||||
.source = ESP_KEY_SOURCE_PSA,
|
||||
.psa.key_id = psa_key_id,
|
||||
};
|
||||
|
||||
esp_tls_cfg_t cfg = {
|
||||
/* other configurations options */
|
||||
.use_secure_element = true,
|
||||
/* other configuration options */
|
||||
.client_key = &key_config,
|
||||
};
|
||||
|
||||
.. only:: SOC_DIG_SIGN_SUPPORTED
|
||||
|
||||
@@ -207,7 +207,7 @@ ESP-TLS 组件支持通过 :cpp:func:`esp_tls_register_stack` API 注册自定
|
||||
ESP-TLS 中的 ATECC608A（安全元件）
|
||||
-----------------------------------------
|
||||
|
||||
ESP-TLS 支持在 ESP32 系列芯片上使用 ATECC608A 加密芯片，但必须将 MbedTLS 作为 ESP-TLS 的底层 SSL/TLS 协议栈。未经手动更改，ESP-TLS 默认以 MbedTLS 为其底层 TLS/SSL 协议栈。
|
||||
ESP-TLS 支持通过 PSA Crypto 不透明驱动接口在 ESP32 系列芯片上使用 ATECC608A 加密芯片。使用 ATECC608A 时必须将 MbedTLS 作为 ESP-TLS 的底层 SSL/TLS 协议栈。未经手动更改，ESP-TLS 默认以 MbedTLS 为其底层 TLS/SSL 协议栈。
|
||||
|
||||
.. note::
|
||||
|
||||
@@ -215,13 +215,13 @@ ESP-TLS 支持在 ESP32 系列芯片上使用 ATECC608A 加密芯片，但必须
|
||||
|
||||
要启用安全元件支持，并将其应用于工程 TLS 连接，请遵循以下步骤：
|
||||
|
||||
1) 在工程中添加 `esp-cryptoauthlib <https://github.com/espressif/esp-cryptoauthlib>`_，详情请参阅 `如何在 ESP-IDF 中使用 esp-cryptoauthlib <https://github.com/espressif/esp-cryptoauthlib#how-to-use-esp-cryptoauthlib-with-esp-idf>`_。
|
||||
1) 在工程中添加 `esp-cryptoauthlib <https://github.com/espressif/esp-cryptoauthlib>`_ 作为依赖，详情请参阅 `如何在 ESP-IDF 中使用 esp-cryptoauthlib <https://github.com/espressif/esp-cryptoauthlib#how-to-use-esp-cryptoauthlib-with-esp-idf>`_。
|
||||
|
||||
2) 启用 menuconfig 选项 :ref:`CONFIG_ESP_TLS_USE_SECURE_ELEMENT`：
|
||||
2) 启用 menuconfig 选项 :ref:`CONFIG_MBEDTLS_SECURE_ELEMENT_DRIVER_ENABLED`：
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
menuconfig > Component config > ESP-TLS > Use Secure Element (ATECC608A) with ESP-TLS
|
||||
menuconfig > Component config > mbedTLS > Enable secure element hardware support
|
||||
|
||||
3) 选择 ATECC608A 芯片类型：
|
||||
|
||||
@@ -231,13 +231,40 @@ ESP-TLS 支持在 ESP32 系列芯片上使用 ATECC608A 加密芯片，但必须
|
||||
|
||||
如需了解更多 ATECC608A 芯片类型，或需了解如何获取连接到特定 ESP 模块的 ATECC608A 芯片类型，请参阅 `ATECC608A 芯片类型 <https://github.com/espressif/esp-cryptoauthlib/blob/master/esp_cryptoauth_utility/README.md#find-type-of-atecc608a-chip-connected-to-esp32-wroom32-se>`_。
|
||||
|
||||
4) 在 :cpp:type:`esp_tls_cfg_t` 中提供以下配置，在 ESP-TLS 中启用 ATECC608A：
|
||||
4) 初始化 PSA Crypto，导入 ATECC608A 密钥，并通过 :cpp:type:`esp_key_config_t` 配置 ESP-TLS 使用：
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#include "psa/crypto.h"
|
||||
#include "psa_crypto_driver_secure_element.h"
|
||||
#include "psa_crypto_driver_secure_element_contexts.h"
|
||||
#include "esp_key_config.h"
|
||||
|
||||
/* 将 ATECC608A 密钥引用导入 PSA */
|
||||
psa_key_attributes_t key_attr = PSA_KEY_ATTRIBUTES_INIT;
|
||||
psa_set_key_lifetime(&key_attr, PSA_KEY_LIFETIME_SECURE_ELEMENT_VOLATILE);
|
||||
psa_set_key_usage_flags(&key_attr, PSA_KEY_USAGE_SIGN_HASH);
|
||||
psa_set_key_algorithm(&key_attr, PSA_ALG_ECDSA(PSA_ALG_SHA_256));
|
||||
psa_set_key_type(&key_attr, PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_SECP_R1));
|
||||
psa_set_key_bits(&key_attr, 256);
|
||||
|
||||
secure_element_opaque_key_t opaque_key = {
|
||||
.slot_id = 0, /* ATECC608A 上的私钥槽位 */
|
||||
};
|
||||
|
||||
psa_key_id_t psa_key_id;
|
||||
psa_import_key(&key_attr, (const uint8_t *)&opaque_key,
|
||||
sizeof(opaque_key), &psa_key_id);
|
||||
|
||||
/* 配置 ESP-TLS 使用 PSA 密钥 */
|
||||
esp_key_config_t key_config = {
|
||||
.source = ESP_KEY_SOURCE_PSA,
|
||||
.psa.key_id = psa_key_id,
|
||||
};
|
||||
|
||||
esp_tls_cfg_t cfg = {
|
||||
/* 其他配置选项 */
|
||||
.use_secure_element = true,
|
||||
.client_key = &key_config,
|
||||
};
|
||||
|
||||
.. only:: SOC_DIG_SIGN_SUPPORTED
|
||||
|
||||
Reference in New Issue
Block a user