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.

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

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 = {

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;
 

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;

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)
  *

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)))
 {

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``.
 

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`` 自动映射。