From c67dac7225943cb0f23c8793b7f041e867183854 Mon Sep 17 00:00:00 2001
From: Harshit Malpani <harshit.malpani@espressif.com>
Date: Fri, 10 Nov 2023 16:37:39 +0800
Subject: [PATCH] docs: Add documentation for using TLS v1.2 and v1.3
 simultaneously

---
 .../protocols/esp_http_client.rst             | 14 +++++++++++++
 docs/en/api-reference/protocols/esp_tls.rst   | 20 +++++++++++++++++++
 .../protocols/esp_http_client.rst             | 14 +++++++++++++
 .../zh_CN/api-reference/protocols/esp_tls.rst | 20 +++++++++++++++++++
 4 files changed, 68 insertions(+)

diff --git a/docs/en/api-reference/protocols/esp_http_client.rst b/docs/en/api-reference/protocols/esp_http_client.rst
index 7cce2f3365..9ec6fde049 100644
--- a/docs/en/api-reference/protocols/esp_http_client.rst
+++ b/docs/en/api-reference/protocols/esp_http_client.rst
@@ -138,6 +138,20 @@ Expected data types for different HTTP Client events in the event loop are as fo
 
 The :cpp:type:`esp_http_client_handle_t` received along with the event data will be valid until :cpp:enumerator:`HTTP_EVENT_DISCONNECTED <esp_http_client_event_id_t::HTTP_EVENT_DISCONNECTED>` is not received. This handle has been sent primarily to differentiate between different client connections and must not be used for any other purpose, as it may change based on client connection state.
 
+TLS Protocol Version
+--------------------
+
+TLS protocol version to be used for the underlying TLS connection can be set in :cpp:type:`esp_http_client_config_t`. Please refer to the **TLS Protocol Version** section in the :doc:`/api-reference/protocols/esp_tls` for more details.
+
+The TLS protocol version for the HTTP client can be configured as follows:
+
+    .. code-block:: c
+
+        #include "esp_http_client.h"
+        esp_http_client_config_t config = {
+            .tls_version = ESP_HTTP_CLIENT_TLS_VER_TLS_1_2,
+        };
+
 API Reference
 -------------
 
diff --git a/docs/en/api-reference/protocols/esp_tls.rst b/docs/en/api-reference/protocols/esp_tls.rst
index 241c5d9c49..8a10f8035d 100644
--- a/docs/en/api-reference/protocols/esp_tls.rst
+++ b/docs/en/api-reference/protocols/esp_tls.rst
@@ -244,6 +244,26 @@ ESP-TLS will not check the validity of ``ciphersuites_list`` that was set, you s
 
    This feature is supported only in the MbedTLS stack.
 
+TLS Protocol Version
+--------------------
+
+ESP-TLS provides the ability to set the TLS protocol version for the respective TLS connection. Once the version is specified, it should be exclusively used to establish the TLS connection. This provides an ability to route different TLS connections to different protocol versions like TLS 1.2 and TLS 1.3 at runtime.
+
+.. note::
+
+   At the moment, the feature is supported only when ESP-TLS is used with MbedTLS as its underlying SSL/TLS stack.
+
+To set TLS protocol version with ESP-TLS, set :cpp:member:`esp_tls_cfg_t::tls_version` to the required protocol version from :cpp:type:`esp_tls_proto_ver_t`. If the protocol version field is not set, then the default policy is to allow TLS connection based on the server requirement.
+
+The ESP-TLS connection can be configured to use the specified protocol version as follows:
+
+    .. code-block:: c
+
+        #include "esp_tls.h"
+        esp_tls_cfg_t cfg = {
+            .tls_version = ESP_TLS_VER_TLS_1_2,
+        };
+
 API Reference
 -------------
 
diff --git a/docs/zh_CN/api-reference/protocols/esp_http_client.rst b/docs/zh_CN/api-reference/protocols/esp_http_client.rst
index ecd32f1d6f..21ebf032d6 100644
--- a/docs/zh_CN/api-reference/protocols/esp_http_client.rst
+++ b/docs/zh_CN/api-reference/protocols/esp_http_client.rst
@@ -138,6 +138,20 @@ ESP HTTP 客户端诊断信息
 
 在无法接收到 :cpp:enumerator:`HTTP_EVENT_DISCONNECTED <esp_http_client_event_id_t::HTTP_EVENT_DISCONNECTED>` 之前，与事件数据一起接收到的 :cpp:type:`esp_http_client_handle_t` 将始终有效。这个句柄主要是为了区分不同的客户端连接，无法用于其他目的，因为它可能会随着客户端连接状态的变化而改变。
 
+TLS 协议版本
+--------------------
+
+可在 :cpp:type:`esp_http_client_config_t` 中设置用于底层 TLS 连接的 TLS 协议版本。了解更多信息，请参考 :doc:`/api-reference/protocols/esp_tls` 中的 **TLS 协议版本** 章节。
+
+HTTP 客户端的 TLS 协议版本可按如下方式配置：
+
+    .. code-block:: c
+
+        #include "esp_http_client.h"
+        esp_http_client_config_t config = {
+            .tls_version = ESP_HTTP_CLIENT_TLS_VER_TLS_1_2,
+        };
+
 API 参考
 ---------
 
diff --git a/docs/zh_CN/api-reference/protocols/esp_tls.rst b/docs/zh_CN/api-reference/protocols/esp_tls.rst
index 369882c7f8..da30593ca1 100644
--- a/docs/zh_CN/api-reference/protocols/esp_tls.rst
+++ b/docs/zh_CN/api-reference/protocols/esp_tls.rst
@@ -244,6 +244,26 @@ ESP-TLS 不会检查 ``ciphersuites_list`` 的有效性，因此需调用 :cpp:f
 
    此功能仅在 MbedTLS 协议栈中有效。
 
+TLS 协议版本
+--------------------
+
+ESP-TLS 能够为 TLS 连接设置相应的 TLS 协议版本，指定版本将用于建立专用 TLS 连接。也就是说，在运行时不同的 TLS 连接可以配置到 TLS 1.2、TLS 1.3 等不同协议版本。
+
+.. note::
+
+   目前，仅在 MbedTLS 作为 ESP-TLS 的底层 SSL/TLS 协议栈时支持此功能。
+
+要在 ESP-TLS 中设置 TLS 协议版本，请设置 :cpp:member:`esp_tls_cfg_t::tls_version`，从 :cpp:type:`esp_tls_proto_ver_t` 中选择所需版本。如未指定协议版本字段，将默认根据服务器要求建立 TLS 连接。
+
+ESP-TLS 连接的协议版本可按如下方式配置：
+
+    .. code-block:: c
+
+        #include "esp_tls.h"
+        esp_tls_cfg_t cfg = {
+            .tls_version = ESP_TLS_VER_TLS_1_2,
+        };
+
 API 参考
 -------------