diff --git a/components/esp-tls/esp_tls.h b/components/esp-tls/esp_tls.h index 3232aef5d60..5f84f10813b 100644 --- a/components/esp-tls/esp_tls.h +++ b/components/esp-tls/esp_tls.h @@ -189,6 +189,13 @@ typedef struct esp_tls_cfg { underneath socket will be configured in non blocking mode after tls session is established */ + bool use_secure_element; /*!< @deprecated No longer functional; setting this to true + makes the connection fail with ESP_ERR_NOT_SUPPORTED. + Use `client_key` (esp_key_config_t) together with + CONFIG_MBEDTLS_SECURE_ELEMENT_DRIVER_ENABLED instead. + Kept only for source compatibility; will be removed in + the next major release. */ + int timeout_ms; /*!< Network timeout in milliseconds. Note: If this value is not set, by default the timeout is set to 10 seconds. If you wish that the session should wait @@ -340,6 +347,13 @@ typedef struct esp_tls_cfg_server { esp_tls_ecdsa_curve_t ecdsa_curve; /*!< ECDSA curve to use (SECP256R1 or SECP384R1) */ + bool use_secure_element; /*!< @deprecated No longer functional; setting this to true + makes the connection fail with ESP_ERR_NOT_SUPPORTED. + Use `server_key` (esp_key_config_t) together with + CONFIG_MBEDTLS_SECURE_ELEMENT_DRIVER_ENABLED instead. + Kept only for source compatibility; will be removed in + the next major release. */ + uint32_t tls_handshake_timeout_ms; /*!< TLS handshake timeout in milliseconds. Note: If this value is not set, by default the timeout is set to 10 seconds. If you wish that the session should wait diff --git a/components/esp-tls/esp_tls_mbedtls.c b/components/esp-tls/esp_tls_mbedtls.c index 06b9511cff9..e7ebe3a747e 100644 --- a/components/esp-tls/esp_tls_mbedtls.c +++ b/components/esp-tls/esp_tls_mbedtls.c @@ -752,6 +752,15 @@ static esp_err_t set_server_config(esp_tls_cfg_server_t *cfg, esp_tls_t *tls) #endif // CONFIG_ESP_TLS_SERVER_MIN_AUTH_MODE_OPTIONAL } + /* use_secure_element is deprecated and non-functional: the cryptoauthlib + * mbedTLS-ALT integration is not compatible with the PSA-based mbedTLS. + * The field is kept for source compatibility only. */ + if (cfg->use_secure_element) { + ESP_LOGE(TAG, "use_secure_element is no longer supported. Use server_key (esp_key_config_t) with " + "CONFIG_MBEDTLS_SECURE_ELEMENT_DRIVER_ENABLED instead. See the ESP-TLS migration guide."); + return ESP_ERR_NOT_SUPPORTED; + } + if (cfg->server_key != NULL && cfg->server_key->source == ESP_KEY_SOURCE_BUFFER) { /* Unified key config with buffer source */ esp_tls_pki_t pki = { @@ -1025,6 +1034,15 @@ esp_err_t set_client_config(const char *hostname, size_t hostlen, esp_tls_cfg_t #endif } + /* use_secure_element is deprecated and non-functional: the cryptoauthlib + * mbedTLS-ALT integration is not compatible with the PSA-based mbedTLS. + * The field is kept for source compatibility only. */ + if (cfg->use_secure_element) { + ESP_LOGE(TAG, "use_secure_element is no longer supported. Use client_key (esp_key_config_t) with " + "CONFIG_MBEDTLS_SECURE_ELEMENT_DRIVER_ENABLED instead. See the ESP-TLS migration guide."); + return ESP_ERR_NOT_SUPPORTED; + } + if (cfg->client_key != NULL && cfg->client_key->source == ESP_KEY_SOURCE_BUFFER) { /* Unified key config with buffer source */ esp_tls_pki_t pki = { diff --git a/components/esp_https_server/include/esp_https_server.h b/components/esp_https_server/include/esp_https_server.h index 288d1bbf72d..2c92b6c2dd6 100644 --- a/components/esp_https_server/include/esp_https_server.h +++ b/components/esp_https_server/include/esp_https_server.h @@ -132,6 +132,12 @@ struct httpd_ssl_config { /** Enable tls session tickets */ bool session_tickets; + /** @deprecated No longer functional; setting this to true makes server start fail with + * ESP_ERR_NOT_SUPPORTED. Use `server_key` (esp_key_config_t) together with + * CONFIG_MBEDTLS_SECURE_ELEMENT_DRIVER_ENABLED instead. Kept only for source + * compatibility; will be removed in the next major release. */ + bool use_secure_element; + /** User callback for esp_https_server */ esp_https_server_user_cb *user_cb; diff --git a/components/esp_https_server/src/https_server.c b/components/esp_https_server/src/https_server.c index 7424f5effdb..16af012c2cb 100644 --- a/components/esp_https_server/src/https_server.c +++ b/components/esp_https_server/src/https_server.c @@ -352,6 +352,15 @@ static esp_err_t create_secure_context(const struct httpd_ssl_config *config, ht #endif } + /* use_secure_element is deprecated and non-functional; it is kept only for + * source compatibility. */ + if (config->use_secure_element) { + ESP_LOGE(TAG, "use_secure_element is no longer supported. Use server_key (esp_key_config_t) with " + "CONFIG_MBEDTLS_SECURE_ELEMENT_DRIVER_ENABLED instead. See the ESP-TLS migration guide."); + ret = ESP_ERR_NOT_SUPPORTED; + goto exit; + } + if (config->use_ecdsa_peripheral) { #ifdef CONFIG_MBEDTLS_HARDWARE_ECDSA_SIGN (*ssl_ctx)->tls_cfg->use_ecdsa_peripheral = config->use_ecdsa_peripheral; diff --git a/components/tcp_transport/include/esp_transport_ssl.h b/components/tcp_transport/include/esp_transport_ssl.h index b0ec044a305..620b1c306c9 100644 --- a/components/tcp_transport/include/esp_transport_ssl.h +++ b/components/tcp_transport/include/esp_transport_ssl.h @@ -206,6 +206,19 @@ void esp_transport_ssl_set_common_name(esp_transport_handle_t t, const char *com */ void esp_transport_ssl_set_ciphersuites_list(esp_transport_handle_t t, const int *ciphersuites_list); +/** + * @brief Set the ssl context to use secure element (atecc608a) for client(device) private key and certificate + * + * @deprecated No longer functional; the TLS connection will fail with ESP_ERR_NOT_SUPPORTED when + * this option is set. Use esp_transport_ssl_set_client_key_config() (esp_key_config_t) + * together with CONFIG_MBEDTLS_SECURE_ELEMENT_DRIVER_ENABLED instead. Kept only for + * source compatibility; will be removed in the next major release. + * + * @param t ssl transport + */ +void esp_transport_ssl_use_secure_element(esp_transport_handle_t t) +__attribute__((deprecated("Use esp_transport_ssl_set_client_key_config() with CONFIG_MBEDTLS_SECURE_ELEMENT_DRIVER_ENABLED instead"))); + /** * @brief Set the ds_data handle in ssl context.(used for the digital signature operation) * diff --git a/components/tcp_transport/transport_ssl.c b/components/tcp_transport/transport_ssl.c index 0f01ebecb87..f3059d275c6 100644 --- a/components/tcp_transport/transport_ssl.c +++ b/components/tcp_transport/transport_ssl.c @@ -502,6 +502,14 @@ void esp_transport_ssl_set_ciphersuites_list(esp_transport_handle_t t, const int ssl->cfg.ciphersuites_list = ciphersuites_list; } +/* Deprecated and non-functional; kept only for source compatibility. Setting + * use_secure_element makes the connection fail with ESP_ERR_NOT_SUPPORTED. */ +void esp_transport_ssl_use_secure_element(esp_transport_handle_t t) +{ + GET_SSL_FROM_TRANSPORT_OR_RETURN(ssl, t); + ssl->cfg.use_secure_element = true; +} + #ifdef CONFIG_MBEDTLS_CERTIFICATE_BUNDLE void esp_transport_ssl_crt_bundle_attach(esp_transport_handle_t t, esp_err_t ((*crt_bundle_attach)(void *conf))) { diff --git a/docs/en/migration-guides/release-6.x/6.0/protocols.rst b/docs/en/migration-guides/release-6.x/6.0/protocols.rst index 29b74474ff1..814efcc84df 100644 --- a/docs/en/migration-guides/release-6.x/6.0/protocols.rst +++ b/docs/en/migration-guides/release-6.x/6.0/protocols.rst @@ -107,7 +107,7 @@ The new API requires you to create the :cpp:type:`esp_tls_t` structure using :cp Unified Private Key Interface ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The ``use_secure_element`` field has been removed from :cpp:type:`esp_tls_cfg`, :cpp:type:`esp_tls_cfg_server`, and :cpp:type:`httpd_ssl_config`. The ATECC608A secure element and all other hardware-backed key sources (DS peripheral, ECDSA peripheral, Key Manager) are now accessed through a unified :cpp:type:`esp_key_config_t` interface via PSA Crypto key IDs. +The ``use_secure_element`` field in :cpp:type:`esp_tls_cfg`, :cpp:type:`esp_tls_cfg_server`, and :cpp:type:`httpd_ssl_config` is deprecated and no longer functional: setting it to ``true`` makes the connection (or server start) fail with ``ESP_ERR_NOT_SUPPORTED``. The field is kept only for source compatibility and will be removed in the next major release. The ATECC608A secure element and all other hardware-backed key sources (DS peripheral, ECDSA peripheral, Key Manager) are now accessed through a unified :cpp:type:`esp_key_config_t` interface via PSA Crypto key IDs. **Migration Steps** @@ -115,7 +115,7 @@ The ``use_secure_element`` field has been removed from :cpp:type:`esp_tls_cfg`, 2. The ``atcab_init()`` call is no longer performed internally by ESP-TLS. Applications using the ATECC608A must ensure the secure element is initialized at the application level before use. Refer to the `esp-cryptoauthlib documentation `_ for details. -3. The ``esp_transport_ssl_use_secure_element()`` function has been removed from ``tcp_transport``. Use ``esp_transport_ssl_set_client_key_config()`` instead. +3. The ``esp_transport_ssl_use_secure_element()`` function in ``tcp_transport`` is deprecated and no longer functional (the connection will fail with ``ESP_ERR_NOT_SUPPORTED``). Use ``esp_transport_ssl_set_client_key_config()`` instead. 4. The Kconfig options for the secure element driver have been consolidated from ``CONFIG_MBEDTLS_ATCA_HW_ECDSA_SIGN`` / ``CONFIG_MBEDTLS_ATCA_HW_ECDSA_VERIFY`` into a single ``CONFIG_MBEDTLS_SECURE_ELEMENT_DRIVER_ENABLED``. The old names are automatically mapped via ``sdkconfig.rename``. diff --git a/docs/zh_CN/migration-guides/release-6.x/6.0/protocols.rst b/docs/zh_CN/migration-guides/release-6.x/6.0/protocols.rst index f1eb34a1795..4f8e6fa9a6a 100644 --- a/docs/zh_CN/migration-guides/release-6.x/6.0/protocols.rst +++ b/docs/zh_CN/migration-guides/release-6.x/6.0/protocols.rst @@ -107,7 +107,7 @@ ESP-TLS 已移除内置的 wolfSSL TLS 协议栈支持。使用 wolfSSL 的用 统一私钥接口 ~~~~~~~~~~~~~ -:cpp:type:`esp_tls_cfg`、:cpp:type:`esp_tls_cfg_server` 和 :cpp:type:`httpd_ssl_config` 中的 ``use_secure_element`` 字段已被移除。ATECC608A 安全元件和所有其他硬件支持的密钥源（DS 外设、ECDSA 外设、密钥管理器）现在通过统一的 :cpp:type:`esp_key_config_t` 接口和 PSA Crypto 密钥 ID 来访问。 +:cpp:type:`esp_tls_cfg`、:cpp:type:`esp_tls_cfg_server` 和 :cpp:type:`httpd_ssl_config` 中的 ``use_secure_element`` 字段已被弃用且不再起作用：将其设置为 ``true`` 会使连接（或服务器启动）失败并返回 ``ESP_ERR_NOT_SUPPORTED``。保留该字段仅是为了源代码兼容性，它将在下一个主版本中被移除。ATECC608A 安全元件和所有其他硬件支持的密钥源（DS 外设、ECDSA 外设、密钥管理器）现在通过统一的 :cpp:type:`esp_key_config_t` 接口和 PSA Crypto 密钥 ID 来访问。 **迁移步骤** @@ -115,7 +115,7 @@ ESP-TLS 已移除内置的 wolfSSL TLS 协议栈支持。使用 wolfSSL 的用 2. ``atcab_init()`` 调用不再由 ESP-TLS 内部执行。使用 ATECC608A 的应用程序必须确保在使用前在应用层初始化安全元件。详情请参阅 `esp-cryptoauthlib 文档 `_。 -3. ``esp_transport_ssl_use_secure_element()`` 函数已从 ``tcp_transport`` 中移除。请改用 ``esp_transport_ssl_set_client_key_config()``。 +3. ``tcp_transport`` 中的 ``esp_transport_ssl_use_secure_element()`` 函数已被弃用且不再起作用（连接将失败并返回 ``ESP_ERR_NOT_SUPPORTED``）。请改用 ``esp_transport_ssl_set_client_key_config()``。 4. 安全元件驱动的 Kconfig 选项已从 ``CONFIG_MBEDTLS_ATCA_HW_ECDSA_SIGN`` / ``CONFIG_MBEDTLS_ATCA_HW_ECDSA_VERIFY`` 合并为 ``CONFIG_MBEDTLS_SECURE_ELEMENT_DRIVER_ENABLED``。旧名称通过 ``sdkconfig.rename`` 自动映射。