fix(esp-tls): Keep deprecated use_secure_element field for compatibility

Restore the use_secure_element field in esp_tls_cfg_t, esp_tls_cfg_server_t and httpd_ssl_config_t, and esp_transport_ssl_use_secure_element(), as deprecated no-ops so that existing code keeps compiling. Setting them now fails at runtime with ESP_ERR_NOT_SUPPORTED, as the feature is accessed via the esp_key_config_t interface. To be removed in the next major release. No compile-time deprecation attribute on this release branch; the field and function stay warning-free here and carry only documentation notes.
2026-09-22 13:01:16 +03:00 · 2026-07-15 12:33:55 +05:30
parent 49d1a84c0b
commit 3e6429e881
8 changed files with 71 additions and 4 deletions
--- 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
--- 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 = {
@@ -1017,6 +1026,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 = {
--- 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;

--- a/components/esp_https_server/src/https_server.c
+++ b/components/esp_https_server/src/https_server.c
@@ -348,6 +348,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;
--- a/components/tcp_transport/include/esp_transport_ssl.h
+++ b/components/tcp_transport/include/esp_transport_ssl.h
@@ -206,6 +206,18 @@ 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);
+
 /**
 * @brief      Set the ds_data handle in ssl context.(used for the digital signature operation)
 *
--- 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)))
 {
--- 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 <https://github.com/espressif/esp-cryptoauthlib>`_ 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``.

--- 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 文档 <https://github.com/espressif/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`` 自动映射。