mirror of
https://github.com/espressif/esp-idf.git
synced 2025-08-07 20:00:53 +00:00
docs: Update CN translation in protocols
This commit is contained in:
Zhang Shuxian
@@ -25,15 +25,15 @@ Simple HTTPS example that uses ESP-TLS to establish a secure socket connection:
|
||||
Tree Structure for ESP-TLS Component
|
||||
-------------------------------------
|
||||
|
||||
.. code-block:: none
|
||||
.. code-block:: none
|
||||
|
||||
├── esp_tls.c
|
||||
├── esp_tls.h
|
||||
├── esp_tls_mbedtls.c
|
||||
├── esp_tls_wolfssl.c
|
||||
└── private_include
|
||||
├── esp_tls_mbedtls.h
|
||||
└── esp_tls_wolfssl.h
|
||||
├── esp_tls.c
|
||||
├── esp_tls.h
|
||||
├── esp_tls_mbedtls.c
|
||||
├── esp_tls_wolfssl.c
|
||||
└── private_include
|
||||
├── esp_tls_mbedtls.h
|
||||
└── esp_tls_wolfssl.h
|
||||
|
||||
The ESP-TLS component has a file :component_file:`esp-tls/esp_tls.h` which contains the public API headers for the component. Internally, the ESP-TLS component operates using either MbedTLS or WolfSSL, which are SSL/TLS libraries. APIs specific to MbedTLS are present in :component_file:`esp-tls/private_include/esp_tls_mbedtls.h` and APIs specific to WolfSSL are present in :component_file:`esp-tls/private_include/esp_tls_wolfssl.h`.
|
||||
|
||||
@@ -53,9 +53,9 @@ ESP-TLS provides multiple options for TLS server verification on the client side
|
||||
* **psk_hint_key**: To use pre-shared keys for server verification, :ref:`CONFIG_ESP_TLS_PSK_VERIFICATION` should be enabled in the ESP-TLS menuconfig. Then the pointer to the PSK hint and key should be provided to the :cpp:type:`esp_tls_cfg_t` structure. The ESP-TLS will use the PSK for server verification only when no other option regarding server verification is selected.
|
||||
* **skip server verification**: This is an insecure option provided in the ESP-TLS for testing purposes. The option can be set by enabling :ref:`CONFIG_ESP_TLS_INSECURE` and :ref:`CONFIG_ESP_TLS_SKIP_SERVER_CERT_VERIFY` in the ESP-TLS menuconfig. When this option is enabled the ESP-TLS will skip server verification by default when no other options for server verification are selected in the :cpp:type:`esp_tls_cfg_t` structure.
|
||||
|
||||
.. warning::
|
||||
.. warning::
|
||||
|
||||
Enabling this option comes with a potential risk of establishing a TLS connection with a server that has a fake identity, provided that the server certificate is not provided either through API or other mechanisms like ca_store etc.
|
||||
If this option is enabled, there is a risk of establishing a TLS connection with a server that has a fake identity, unless the server certificate is provided through the API or other mechanisms like ``ca_store``.
|
||||
|
||||
ESP-TLS Server Cert Selection Hook
|
||||
----------------------------------
|
||||
@@ -92,22 +92,27 @@ How to Use WolfSSL with ESP-IDF
|
||||
|
||||
There are two ways to use WolfSSL in your project:
|
||||
|
||||
1) Directly add WolfSSL as a component in your project with the following three commands::
|
||||
- Add WolfSSL as a component directly to your project. For this, go to your project directory and run:
|
||||
|
||||
(First, change the directory (cd) to your project directory)
|
||||
mkdir components
|
||||
cd components
|
||||
git clone --recursive https://github.com/espressif/esp-wolfssl.git
|
||||
.. code-block:: none
|
||||
|
||||
2) Add WolfSSL as an extra component in your project.
|
||||
mkdir components
|
||||
cd components
|
||||
git clone --recursive https://github.com/espressif/esp-wolfssl.git
|
||||
|
||||
* Download WolfSSL with::
|
||||
- Add WolfSSL as an extra component in your project.
|
||||
|
||||
git clone --recursive https://github.com/espressif/esp-wolfssl.git
|
||||
1. Download WolfSSL with:
|
||||
|
||||
* Include ESP-WolfSSL in ESP-IDF with setting ``EXTRA_COMPONENT_DIRS`` in ``CMakeLists.txt`` of your project as done in `wolfssl/examples <https://github.com/espressif/esp-wolfssl/tree/master/examples>`_. For reference see :ref:`optional_project_variable` in :doc:`build-system.</api-guides/build-system>`.
|
||||
.. code-block:: none
|
||||
|
||||
After the above steps, you will have the option to choose WolfSSL as the underlying SSL/TLS library in the configuration menu of your project as follows::
|
||||
git clone --recursive https://github.com/espressif/esp-wolfssl.git
|
||||
|
||||
2. Include ESP-WolfSSL in ESP-IDF with setting ``EXTRA_COMPONENT_DIRS`` in ``CMakeLists.txt`` of your project as done in `wolfssl/examples <https://github.com/espressif/esp-wolfssl/tree/master/examples>`_. For reference see :ref:`optional_project_variable` in :doc:`build-system </api-guides/build-system>`.
|
||||
|
||||
After the above steps, you will have the option to choose WolfSSL as the underlying SSL/TLS library in the configuration menu of your project as follow:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
idf.py menuconfig > ESP-TLS > SSL/TLS Library > Mbedtls/Wolfssl
|
||||
|
||||
@@ -151,24 +156,28 @@ To enable the secure element support, and use it in your project for TLS connect
|
||||
|
||||
1) Add `esp-cryptoauthlib <https://github.com/espressif/esp-cryptoauthlib>`_ in your project, for details please refer `how to use esp-cryptoauthlib with ESP-IDF <https://github.com/espressif/esp-cryptoauthlib#how-to-use-esp-cryptoauthlib-with-esp-idf>`_.
|
||||
|
||||
2) Enable the following menuconfig option::
|
||||
2) Enable the menuconfig option :ref:`CONFIG_ESP_TLS_USE_SECURE_ELEMENT`:
|
||||
|
||||
menuconfig > Component config > ESP-TLS > Use Secure Element (ATECC608A) with ESP-TLS
|
||||
.. code-block:: none
|
||||
|
||||
3) Select type of ATECC608A chip with following option::
|
||||
menuconfig > Component config > ESP-TLS > Use Secure Element (ATECC608A) with ESP-TLS
|
||||
|
||||
menuconfig > Component config > esp-cryptoauthlib > Choose Type of ATECC608A chip
|
||||
3) Select type of ATECC608A chip with following option:
|
||||
|
||||
To know more about different types of ATECC608A chips and how to obtain the type of ATECC608A connected to your ESP module, please visit `ATECC608A chip type <https://github.com/espressif/esp-cryptoauthlib/blob/master/esp_cryptoauth_utility/README.md#find-type-of-atecc608a-chip-connected-to-esp32-wroom32-se>`_.
|
||||
.. code-block:: none
|
||||
|
||||
4) Enable the use of ATECC608A in ESP-TLS by providing the following config option in :cpp:type:`esp_tls_cfg_t`.
|
||||
menuconfig > Component config > esp-cryptoauthlib > Choose Type of ATECC608A chip
|
||||
|
||||
.. code-block:: c
|
||||
To know more about different types of ATECC608A chips and how to obtain the type of ATECC608A connected to your ESP module, please visit `ATECC608A chip type <https://github.com/espressif/esp-cryptoauthlib/blob/master/esp_cryptoauth_utility/README.md#find-type-of-atecc608a-chip-connected-to-esp32-wroom32-se>`_.
|
||||
|
||||
esp_tls_cfg_t cfg = {
|
||||
/* other configurations options */
|
||||
.use_secure_element = true,
|
||||
};
|
||||
4) Enable the use of ATECC608A in ESP-TLS by providing the following config option in :cpp:type:`esp_tls_cfg_t`:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
esp_tls_cfg_t cfg = {
|
||||
/* other configurations options */
|
||||
.use_secure_element = true,
|
||||
};
|
||||
|
||||
.. only:: SOC_DIG_SIGN_SUPPORTED
|
||||
|
||||
@@ -226,7 +235,7 @@ To know more about different types of ATECC608A chips and how to obtain the type
|
||||
|
||||
|
||||
TLS Ciphersuites
|
||||
------------------------------------
|
||||
----------------
|
||||
|
||||
ESP-TLS provides the ability to set a ciphersuites list in client mode. The TLS ciphersuites list informs the server about the supported ciphersuites for the specific TLS connection regardless of the TLS stack configuration. If the server supports any ciphersuite from this list, then the TLS connection will succeed; otherwise, it will fail.
|
||||
|
||||
@@ -259,12 +268,12 @@ To set TLS protocol version with ESP-TLS, set :cpp:member:`esp_tls_cfg_t::tls_ve
|
||||
|
||||
The ESP-TLS connection can be configured to use the specified protocol version as follows:
|
||||
|
||||
.. code-block:: c
|
||||
.. code-block:: c
|
||||
|
||||
#include "esp_tls.h"
|
||||
esp_tls_cfg_t cfg = {
|
||||
.tls_version = ESP_TLS_VER_TLS_1_2,
|
||||
};
|
||||
#include "esp_tls.h"
|
||||
esp_tls_cfg_t cfg = {
|
||||
.tls_version = ESP_TLS_VER_TLS_1_2,
|
||||
};
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
@@ -42,11 +42,11 @@ Application Examples
|
||||
MQTT Message Retransmission
|
||||
---------------------------
|
||||
|
||||
A new MQTT message is created by calling :cpp:func:`esp_mqtt_client_publish <esp_mqtt_client_publish()>` or its non blocking counterpart :cpp:func:`esp_mqtt_client_enqueue <esp_mqtt_client_enqueue()>`.
|
||||
A new MQTT message can be created by calling :cpp:func:`esp_mqtt_client_publish <esp_mqtt_client_publish()>` or its non-blocking counterpart :cpp:func:`esp_mqtt_client_enqueue <esp_mqtt_client_enqueue()>`.
|
||||
|
||||
Messages with QoS 0 is sent only once. QoS 1 and 2 have different behaviors since the protocol requires extra steps to complete the process.
|
||||
Messages with QoS 0 are sent only once. QoS 1 and 2 behave differently since the protocol requires additional steps to complete the process.
|
||||
|
||||
The ESP-MQTT library opts to always retransmit unacknowledged QoS 1 and 2 publish messages to avoid losses in faulty connections, even though the MQTT specification requires the re-transmission only on reconnect with Clean Session flag been set to 0 (set :cpp:member:`disable_clean_session <esp_mqtt_client_config_t::session_t::disable_clean_session>` to true for this behavior).
|
||||
The ESP-MQTT library opts to always retransmit unacknowledged QoS 1 and 2 publish messages to prevent data loss in faulty connections, even though the MQTT specification requires the re-transmission only on reconnect with Clean Session flag been set to 0 (set :cpp:member:`disable_clean_session <esp_mqtt_client_config_t::session_t::disable_clean_session>` to true for this behavior).
|
||||
|
||||
QoS 1 and 2 messages that may need retransmission are always enqueued, but first transmission try occurs immediately if :cpp:func:`esp_mqtt_client_publish <esp_mqtt_client_publish>` is used. A transmission retry for unacknowledged messages will occur after :cpp:member:`message_retransmit_timeout <esp_mqtt_client_config_t::session_t::message_retransmit_timeout>`. After :ref:`CONFIG_MQTT_OUTBOX_EXPIRED_TIMEOUT_MS` messages will expire and be deleted. If :ref:`CONFIG_MQTT_REPORT_DELETED_MESSAGES` is set, an event will be sent to notify the user.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user