mirror of
https://github.com/espressif/esp-idf.git
synced 2026-04-27 19:13:21 +00:00
feat(docs): Added migration guide
This commit is contained in:
Aditya Patwardhan
@@ -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 \
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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:
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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`。请使用以下替代函数：
|
||||
|
||||
|
||||
Reference in New Issue
Block a user