From 8694115a75f228cd426d38ede037e025143b3f4e Mon Sep 17 00:00:00 2001 From: Aditya Patwardhan Date: Fri, 9 Jan 2026 17:32:39 +0530 Subject: [PATCH] feat(docs): Added migration guide --- docs/doxygen/Doxyfile | 1 + docs/en/api-reference/protocols/esp_tls.rst | 13 ++++--- .../release-6.x/6.0/protocols.rst | 39 ++++++++++++++++++- .../zh_CN/api-reference/protocols/esp_tls.rst | 13 ++++--- .../release-6.x/6.0/protocols.rst | 39 ++++++++++++++++++- 5 files changed, 91 insertions(+), 14 deletions(-) diff --git a/docs/doxygen/Doxyfile b/docs/doxygen/Doxyfile index a2602bfb10..25c74a51af 100644 --- a/docs/doxygen/Doxyfile +++ b/docs/doxygen/Doxyfile @@ -264,6 +264,7 @@ INPUT = \ $(PROJECT_PATH)/components/esp_wifi/wifi_apps/nan_app/include/esp_nan.h \ $(PROJECT_PATH)/components/esp-tls/esp_tls_errors.h \ $(PROJECT_PATH)/components/esp-tls/esp_tls.h \ + $(PROJECT_PATH)/components/esp-tls/esp_tls_custom_stack.h \ $(PROJECT_PATH)/components/fatfs/diskio/diskio_impl.h \ $(PROJECT_PATH)/components/fatfs/diskio/diskio_rawflash.h \ $(PROJECT_PATH)/components/fatfs/diskio/diskio_sdmmc.h \ diff --git a/docs/en/api-reference/protocols/esp_tls.rst b/docs/en/api-reference/protocols/esp_tls.rst index 3118d9dcc4..22078cbee1 100644 --- a/docs/en/api-reference/protocols/esp_tls.rst +++ b/docs/en/api-reference/protocols/esp_tls.rst @@ -115,11 +115,7 @@ How to Use Custom TLS Stack with ESP-IDF To use a custom TLS stack in your project, follow these steps: -1. Enable the custom stack option in menuconfig: - - .. code-block:: none - - idf.py menuconfig > Component config > ESP-TLS > Choose SSL/TLS library for ESP-TLS > Custom TLS stack +1. Enable the custom stack option ``CONFIG_ESP_TLS_CUSTOM_STACK`` (Component config > ESP-TLS > SSL/TLS Library > Custom TLS stack) in menuconfig. 2. Implement all required functions defined in the :cpp:type:`esp_tls_stack_ops_t` structure. The required functions are: @@ -155,6 +151,7 @@ To use a custom TLS stack in your project, follow these steps: #include "esp_tls_custom_stack.h" static const esp_tls_stack_ops_t my_tls_ops = { + .version = ESP_TLS_STACK_OPS_VERSION, .create_ssl_handle = my_create_ssl_handle, .handshake = my_handshake, .read = my_read, @@ -184,7 +181,10 @@ To use a custom TLS stack in your project, follow these steps: .. code-block:: c void app_main(void) { - esp_err_t ret = esp_tls_register_stack(&my_tls_ops); + // The second parameter is user context passed to global callbacks + // (init_global_ca_store, set_global_ca_store, etc.) + // Use NULL if not needed, or pass a pointer for C++ implementations + esp_err_t ret = esp_tls_register_stack(&my_tls_ops, NULL); if (ret != ESP_OK) { ESP_LOGE("APP", "Failed to register TLS stack: %s", esp_err_to_name(ret)); return; @@ -418,3 +418,4 @@ API Reference .. include-build-file:: inc/esp_tls.inc .. include-build-file:: inc/esp_tls_errors.inc +.. include-build-file:: inc/esp_tls_custom_stack.inc 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 5118ede413..e06346a47c 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 @@ -58,7 +58,44 @@ For more information: ESP-TLS ------- -**Removed Deprecated API** +Removed wolfSSL Support +~~~~~~~~~~~~~~~~~~~~~~~ + +The built-in wolfSSL TLS stack support has been removed from ESP-TLS. Users who were using wolfSSL should migrate to either: + +1. **mbedTLS (Recommended)**: The default TLS stack, fully integrated and maintained within ESP-IDF. +2. **Custom TLS Stack**: Register your own TLS implementation using the new custom stack API (see below). + +**Removed Kconfig Options** + +The following Kconfig options have been removed: + +- ``CONFIG_ESP_TLS_USING_WOLFSSL`` - Use ``CONFIG_ESP_TLS_USING_MBEDTLS`` or ``CONFIG_ESP_TLS_CUSTOM_STACK`` instead +- ``CONFIG_ESP_DEBUG_WOLFSSL`` - For mbedTLS debugging, use ``CONFIG_MBEDTLS_DEBUG`` +- ``CONFIG_ESP_TLS_OCSP_CHECKALL`` - OCSP functionality should be handled by the chosen TLS stack + +**Migration Steps for wolfSSL Users** + +If your project was using wolfSSL via ESP-TLS: + +1. **Option A - Switch to mbedTLS**: + + - Remove ``CONFIG_ESP_TLS_USING_WOLFSSL=y`` from your sdkconfig + - The default ``CONFIG_ESP_TLS_USING_MBEDTLS`` will be used automatically + - No code changes required for standard TLS operations + +2. **Option B - Use Custom Stack API**: + + If you need to continue using wolfSSL or another TLS library, you can register it as a custom stack: + + - Enable ``CONFIG_ESP_TLS_CUSTOM_STACK`` in menuconfig + - Implement the :cpp:type:`esp_tls_stack_ops_t` interface for your TLS library + - Call :cpp:func:`esp_tls_register_stack` before creating any TLS connections + + For detailed documentation on implementing a custom TLS stack, see :ref:`esp_tls_custom_stack`. + +Removed Deprecated API +~~~~~~~~~~~~~~~~~~~~~~ The deprecated :cpp:func:`esp_tls_conn_http_new` function has been removed. Use either: diff --git a/docs/zh_CN/api-reference/protocols/esp_tls.rst b/docs/zh_CN/api-reference/protocols/esp_tls.rst index 5ae78a63e2..3c3dc283ec 100644 --- a/docs/zh_CN/api-reference/protocols/esp_tls.rst +++ b/docs/zh_CN/api-reference/protocols/esp_tls.rst @@ -115,11 +115,7 @@ ESP-TLS 组件支持通过 :cpp:func:`esp_tls_register_stack` API 注册自定 要在工程中使用自定义 TLS 协议栈，请遵循以下步骤： -1. 在 menuconfig 中启用自定义协议栈选项： - - .. code-block:: none - - idf.py menuconfig > Component config > ESP-TLS > Choose SSL/TLS library for ESP-TLS > Custom TLS stack +1. 在 menuconfig 中启用自定义协议栈选项 ``CONFIG_ESP_TLS_CUSTOM_STACK`` (Component config > ESP-TLS > SSL/TLS Library > Custom TLS stack)。 2. 实现 :cpp:type:`esp_tls_stack_ops_t` 结构中定义的所有必需函数。必需函数包括： @@ -155,6 +151,7 @@ ESP-TLS 组件支持通过 :cpp:func:`esp_tls_register_stack` API 注册自定 #include "esp_tls_custom_stack.h" static const esp_tls_stack_ops_t my_tls_ops = { + .version = ESP_TLS_STACK_OPS_VERSION, .create_ssl_handle = my_create_ssl_handle, .handshake = my_handshake, .read = my_read, @@ -184,7 +181,10 @@ ESP-TLS 组件支持通过 :cpp:func:`esp_tls_register_stack` API 注册自定 .. code-block:: c void app_main(void) { - esp_err_t ret = esp_tls_register_stack(&my_tls_ops); + // 第二个参数是传递给全局回调函数的用户上下文 + // (init_global_ca_store, set_global_ca_store 等) + // 如果不需要可以传 NULL，或者为 C++ 实现传递一个指针 + esp_err_t ret = esp_tls_register_stack(&my_tls_ops, NULL); if (ret != ESP_OK) { ESP_LOGE("APP", "Failed to register TLS stack: %s", esp_err_to_name(ret)); return; @@ -418,3 +418,4 @@ API 参考 .. include-build-file:: inc/esp_tls.inc .. include-build-file:: inc/esp_tls_errors.inc +.. include-build-file:: inc/esp_tls_custom_stack.inc 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 df9d88c4f1..0ff74a50a2 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 @@ -58,7 +58,44 @@ ESP-IDF 已移除内置的 ``json`` 组件。用户应迁移至使用 `IDF 组 ESP-TLS ------- -**已移除的废弃 API** +移除 wolfSSL 支持 +~~~~~~~~~~~~~~~~~ + +ESP-TLS 已移除内置的 wolfSSL TLS 协议栈支持。使用 wolfSSL 的用户应迁移至以下方案： + +1. **mbedTLS（推荐）**：默认 TLS 协议栈，完全集成并在 ESP-IDF 中维护。 +2. **自定义 TLS 协议栈**：使用新的自定义协议栈 API 注册您自己的 TLS 实现（详见下文）。 + +**已移除的 Kconfig 选项** + +以下 Kconfig 选项已被移除： + +- ``CONFIG_ESP_TLS_USING_WOLFSSL`` - 请改用 ``CONFIG_ESP_TLS_USING_MBEDTLS`` 或 ``CONFIG_ESP_TLS_CUSTOM_STACK`` +- ``CONFIG_ESP_DEBUG_WOLFSSL`` - 对于 mbedTLS 调试，请使用 ``CONFIG_MBEDTLS_DEBUG`` +- ``CONFIG_ESP_TLS_OCSP_CHECKALL`` - OCSP 功能应由所选 TLS 协议栈处理 + +**wolfSSL 用户迁移步骤** + +如果您的项目通过 ESP-TLS 使用 wolfSSL： + +1. **方案 A - 切换到 mbedTLS**： + + - 从 sdkconfig 中移除 ``CONFIG_ESP_TLS_USING_WOLFSSL=y`` + - 将自动使用默认的 ``CONFIG_ESP_TLS_USING_MBEDTLS`` + - 标准 TLS 操作无需更改代码 + +2. **方案 B - 使用自定义协议栈 API**： + + 如果您需要继续使用 wolfSSL 或其他 TLS 库，可以将其注册为自定义协议栈： + + - 在 menuconfig 中启用 ``CONFIG_ESP_TLS_CUSTOM_STACK`` + - 为您的 TLS 库实现 :cpp:type:`esp_tls_stack_ops_t` 接口 + - 在创建任何 TLS 连接之前调用 :cpp:func:`esp_tls_register_stack` + + 有关实现自定义 TLS 协议栈的详细文档，请参阅 :ref:`esp_tls_custom_stack`。 + +已移除的废弃 API +~~~~~~~~~~~~~~~~ 已移除废弃函数 :cpp:func:`esp_tls_conn_http_new`。请使用以下替代函数：