diff --git a/docs/en/api-reference/protocols/esp_tls.rst b/docs/en/api-reference/protocols/esp_tls.rst index 22078cbee1..a91a857229 100644 --- a/docs/en/api-reference/protocols/esp_tls.rst +++ b/docs/en/api-reference/protocols/esp_tls.rst @@ -194,15 +194,15 @@ To use a custom TLS stack in your project, follow these steps: // ... create TLS connections as usual using esp_tls_conn_new(), etc. ... } -Important Notes ---------------- +.. important:: + + * The custom stack must be registered **before** creating any TLS connections. Calling :cpp:func:`esp_tls_register_stack` after TLS connections have been created will not affect existing connections. + * The :cpp:type:`esp_tls_stack_ops_t` structure must point to a static/global structure (not on the stack) as it's stored by reference. + * Your implementation should store stack-specific context data in the ``priv_ctx`` and ``priv_ssl`` fields of the :cpp:type:`esp_tls_t` structure. + * All required function pointers must be non-NULL. Optional functions can be NULL if not supported. + * The registration function can only be called once. Subsequent calls will return ``ESP_ERR_INVALID_STATE``. + * For detailed function signatures and requirements, see :component_file:`esp-tls/esp_tls_custom_stack.h`. -* The custom stack must be registered before creating any TLS connections. Calling :cpp:func:`esp_tls_register_stack` after TLS connections have been created will not affect existing connections. -* The :cpp:type:`esp_tls_stack_ops_t` structure must point to a static/global structure (not on the stack) as it's stored by reference. -* Your implementation should store stack-specific context data in the ``priv_ctx`` and ``priv_ssl`` fields of the :cpp:type:`esp_tls_t` structure. -* All required function pointers must be non-NULL. Optional functions can be NULL if not supported. -* The registration function can only be called once. Subsequent calls will return ``ESP_ERR_INVALID_STATE``. -* For detailed function signatures and requirements, see :component_file:`esp-tls/esp_tls_custom_stack.h`. ATECC608A (Secure Element) with ESP-TLS -------------------------------------------------- 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 e06346a47c..6644764ec5 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 @@ -64,7 +64,7 @@ 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). +2. **Custom TLS Stack**: Register your own TLS implementation using the new custom stack API (see Option B below). **Removed Kconfig Options** @@ -78,13 +78,13 @@ The following Kconfig options have been removed: If your project was using wolfSSL via ESP-TLS: -1. **Option A - Switch to mbedTLS**: +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**: +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: diff --git a/docs/zh_CN/api-reference/protocols/esp_tls.rst b/docs/zh_CN/api-reference/protocols/esp_tls.rst index 3c3dc283ec..8e11dbef63 100644 --- a/docs/zh_CN/api-reference/protocols/esp_tls.rst +++ b/docs/zh_CN/api-reference/protocols/esp_tls.rst @@ -108,7 +108,7 @@ ESP-TLS 组件支持通过 :cpp:func:`esp_tls_register_stack` API 注册自定 .. note:: - 由于自定义协议栈实现位于 ESP-TLS 内部，切换到自定义协议栈不会更改工程的 ESP-TLS 特定代码。 + 由于自定义协议栈的实现封装在 ESP-TLS 内部，因此切换为自定义协议栈并不会影响项目中与 ESP-TLS 相关的代码。 在 ESP-IDF 中使用自定义 TLS 协议栈 ---------------------------------------- @@ -121,30 +121,30 @@ ESP-TLS 组件支持通过 :cpp:func:`esp_tls_register_stack` API 注册自定 * ``create_ssl_handle`` - 为新连接初始化 TLS/SSL 上下文 * ``handshake`` - 执行 TLS 握手 - * ``read`` - 从 TLS 连接读取解密数据 - * ``write`` - 写入并加密数据到 TLS 连接 - * ``conn_delete`` - 清理 TLS 连接并释放资源 + * ``read`` - 从 TLS 连接读取已解密的数据 + * ``write`` - 向 TLS 连接写入数据，并在发送前完成加密 + * ``conn_delete`` - 清理 TLS 连接并释放相关资源 * ``net_init`` - 初始化网络上下文 * ``get_ssl_context`` - 获取协议栈特定的 SSL 上下文 * ``get_bytes_avail`` - 获取可用于读取的字节数 - * ``init_global_ca_store`` - 初始化全局 CA 存储 + * ``init_global_ca_store`` - 初始化全局 CA 证书存储 * ``set_global_ca_store`` - 将 CA 证书加载到全局存储 - * ``get_global_ca_store`` - 获取全局 CA 存储 - * ``free_global_ca_store`` - 释放全局 CA 存储 + * ``get_global_ca_store`` - 获取全局 CA 证书存储 + * ``free_global_ca_store`` - 释放全局 CA 证书存储 * ``get_ciphersuites_list`` - 获取支持的密码套件列表 可选函数（如果不支持，可以为 NULL）： - * ``get_client_session`` - 获取客户端会话票据（如果启用了 CONFIG_ESP_TLS_CLIENT_SESSION_TICKETS） - * ``free_client_session`` - 释放客户端会话（如果启用了 CONFIG_ESP_TLS_CLIENT_SESSION_TICKETS） - * ``server_session_ticket_ctx_init`` - 初始化服务器会话票据上下文（如果启用了 CONFIG_ESP_TLS_SERVER_SESSION_TICKETS） - * ``server_session_ticket_ctx_free`` - 释放服务器会话票据上下文（如果启用了 CONFIG_ESP_TLS_SERVER_SESSION_TICKETS） - * ``server_session_create`` - 创建服务器会话（服务器端，如果提供了 server_session_init 可以为 NULL） - * ``server_session_init`` - 初始化服务器会话（服务器端，如果提供了 server_session_create 可以为 NULL） - * ``server_session_continue_async`` - 继续异步服务器握手（服务器端，如果提供了 server_session_create 可以为 NULL） - * ``server_session_delete`` - 删除服务器会话（服务器端，可以为 NULL，将使用 conn_delete） + * ``get_client_session`` - 获取客户端会话票据（须启用 :ref:`CONFIG_ESP_TLS_CLIENT_SESSION_TICKETS`） + * ``free_client_session`` - 释放客户端会话（须启用 :ref:`CONFIG_ESP_TLS_CLIENT_SESSION_TICKETS`） + * ``server_session_ticket_ctx_init`` - 初始化服务器会话票据上下文（须启用 :ref:`CONFIG_ESP_TLS_SERVER_SESSION_TICKETS`） + * ``server_session_ticket_ctx_free`` - 释放服务器会话票据上下文（须启用 :ref:`CONFIG_ESP_TLS_SERVER_SESSION_TICKETS`） + * ``server_session_create`` - 创建服务器会话（服务器端，如果提供了 server_session_init，该接口可以为 NULL） + * ``server_session_init`` - 初始化服务器会话（服务器端，如果提供了 server_session_create，该接口可以为 NULL） + * ``server_session_continue_async`` - 继续服务器端的异步握手（服务器端，如果提供了 server_session_create，该接口可以为 NULL） + * ``server_session_delete`` - 删除服务器会话（服务器端，该接口可以为 NULL，此时将使用 ``conn_delete`` 进行清理） -3. 创建一个包含函数实现的静态/全局结构： +3. 创建一个包含函数实现的静态/全局结构体： .. code-block:: c @@ -176,33 +176,33 @@ ESP-TLS 组件支持通过 :cpp:func:`esp_tls_register_stack` API 注册自定 .server_session_delete = NULL, }; -4. 在创建任何 TLS 连接之前注册您的自定义协议栈： +4. 在创建任何 TLS 连接之前注册自定义协议栈： .. code-block:: c void app_main(void) { // 第二个参数是传递给全局回调函数的用户上下文 - // (init_global_ca_store, set_global_ca_store 等) - // 如果不需要可以传 NULL，或者为 C++ 实现传递一个指针 + //（如 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; } - // 现在所有 TLS 连接都将使用您的自定义协议栈 + // 现在所有 TLS 连接都将使用你的自定义协议栈 // ... 像往常一样使用 esp_tls_conn_new() 等创建 TLS 连接 ... } -重要说明 ---------------- +.. important:: + + * 必须在创建任何 TLS 连接 **之前** 注册自定义协议栈。在创建 TLS 连接后调用 :cpp:func:`esp_tls_register_stack` 不会影响现有连接。 + * :cpp:type:`esp_tls_stack_ops_t` 结构必须指向静态或全局结构体（不在栈上），因为系统会以引用方式存储该结构体。 + * 你的实现应将协议栈特定的上下文数据存储在 :cpp:type:`esp_tls_t` 结构的 ``priv_ctx`` 和 ``priv_ssl`` 字段中。 + * 所有必需函数的指针必须为非 NULL。可选函数如果不支持可以为 NULL。 + * 注册函数只能调用一次。后续调用将返回 ``ESP_ERR_INVALID_STATE``。 + * 更多函数签名和要求，请参阅 :component_file:`esp-tls/esp_tls_custom_stack.h`。 -* 必须在创建任何 TLS 连接之前注册自定义协议栈。在创建 TLS 连接后调用 :cpp:func:`esp_tls_register_stack` 不会影响现有连接。 -* :cpp:type:`esp_tls_stack_ops_t` 结构必须指向静态/全局结构（不在栈上），因为它按引用存储。 -* 您的实现应将协议栈特定的上下文数据存储在 :cpp:type:`esp_tls_t` 结构的 ``priv_ctx`` 和 ``priv_ssl`` 字段中。 -* 所有必需的函数指针必须为非 NULL。可选函数如果不支持可以为 NULL。 -* 注册函数只能调用一次。后续调用将返回 ``ESP_ERR_INVALID_STATE``。 -* 有关详细的函数签名和要求，请参阅 :component_file:`esp-tls/esp_tls_custom_stack.h`。 ESP-TLS 中的 ATECC608A（安全元件） ----------------------------------------- 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 0ff74a50a2..b362580da7 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 @@ -61,35 +61,35 @@ ESP-TLS 移除 wolfSSL 支持 ~~~~~~~~~~~~~~~~~ -ESP-TLS 已移除内置的 wolfSSL TLS 协议栈支持。使用 wolfSSL 的用户应迁移至以下方案： +ESP-TLS 已移除内置的 wolfSSL TLS 协议栈支持。使用 wolfSSL 的用户应迁移至以下两个方案之一： 1. **mbedTLS（推荐）**：默认 TLS 协议栈，完全集成并在 ESP-IDF 中维护。 -2. **自定义 TLS 协议栈**：使用新的自定义协议栈 API 注册您自己的 TLS 实现（详见下文）。 +2. **自定义 TLS 协议栈**：使用自定义协议栈 API（见下文方案 B）注册自己的 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_DEBUG_WOLFSSL`` - 进行 mbedTLS 调试，请使用 ``CONFIG_MBEDTLS_DEBUG`` - ``CONFIG_ESP_TLS_OCSP_CHECKALL`` - OCSP 功能应由所选 TLS 协议栈处理 **wolfSSL 用户迁移步骤** -如果您的项目通过 ESP-TLS 使用 wolfSSL： +如果你的项目通过 ESP-TLS 使用 wolfSSL： -1. **方案 A - 切换到 mbedTLS**： +1. **方案 A - 切换到 mbedTLS** - 从 sdkconfig 中移除 ``CONFIG_ESP_TLS_USING_WOLFSSL=y`` - 将自动使用默认的 ``CONFIG_ESP_TLS_USING_MBEDTLS`` - - 标准 TLS 操作无需更改代码 + - 使用标准 TLS 操作，无需更改代码 -2. **方案 B - 使用自定义协议栈 API**： +2. **方案 B - 使用自定义协议栈 API** - 如果您需要继续使用 wolfSSL 或其他 TLS 库，可以将其注册为自定义协议栈： + 如需要继续使用 wolfSSL 或其他 TLS 库，可以将其注册为自定义协议栈： - 在 menuconfig 中启用 ``CONFIG_ESP_TLS_CUSTOM_STACK`` - - 为您的 TLS 库实现 :cpp:type:`esp_tls_stack_ops_t` 接口 + - 为你的 TLS 库实现 :cpp:type:`esp_tls_stack_ops_t` 接口 - 在创建任何 TLS 连接之前调用 :cpp:func:`esp_tls_register_stack` 有关实现自定义 TLS 协议栈的详细文档，请参阅 :ref:`esp_tls_custom_stack`。