mirror of
https://github.com/espressif/esp-idf.git
synced 2025-09-25 01:37:22 +00:00
docs: Provide Chinese translation for protocols/esp_crt_bundle.rst and mbedtls.rst
This commit is contained in:
Ren Pei Ying
@@ -1,6 +1,8 @@
|
||||
ESP x509 Certificate Bundle
|
||||
===========================
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
@@ -10,7 +12,7 @@ The ESP x509 Certificate Bundle API provides an easy way to include a bundle of
|
||||
|
||||
The bundle is currently not available when using WolfSSL.
|
||||
|
||||
The bundle comes with the complete list of root certificates from Mozilla's NSS root certificate store. Using the gen_crt_bundle.py python utility the certificates' subject name and public key are stored in a file and embedded in the {IDF_TARGET_NAME} binary.
|
||||
The bundle comes with the complete list of root certificates from Mozilla's NSS root certificate store. Using the gen_crt_bundle.py python utility, the certificates' subject name and public key are stored in a file and embedded in the {IDF_TARGET_NAME} binary.
|
||||
|
||||
When generating the bundle you may choose between:
|
||||
|
||||
@@ -26,10 +28,10 @@ In addition, it is possible to specify a path to a certificate file or a directo
|
||||
Configuration
|
||||
-------------
|
||||
|
||||
Most configuration is done through menuconfig. CMake will generate the bundle according to the configuration and embed it.
|
||||
Most configuration is done through menuconfig. CMake generates the bundle according to the configuration and embed it.
|
||||
|
||||
* :ref:`CONFIG_MBEDTLS_CERTIFICATE_BUNDLE`: automatically build and attach the bundle.
|
||||
* :ref:`CONFIG_MBEDTLS_DEFAULT_CERTIFICATE_BUNDLE`: decide which certificates to include from the complete root list.
|
||||
* :ref:`CONFIG_MBEDTLS_DEFAULT_CERTIFICATE_BUNDLE`: decide which certificates to include from the complete root certificate list.
|
||||
* :ref:`CONFIG_MBEDTLS_CUSTOM_CERTIFICATE_BUNDLE_PATH`: specify the path of any additional certificates to embed in the bundle.
|
||||
|
||||
To enable the bundle when using ESP-TLS simply pass the function pointer to the bundle attach function:
|
||||
@@ -56,15 +58,16 @@ If using mbedTLS directly then the bundle may be activated by directly calling t
|
||||
|
||||
Generating the List of Root Certificates
|
||||
----------------------------------------
|
||||
|
||||
The list of root certificates comes from Mozilla's NSS root certificate store, which can be found `here <https://wiki.mozilla.org/CA/Included_Certificates>`_
|
||||
|
||||
The list can be downloaded and created by running the script ``mk-ca-bundle.pl`` that is distributed as a part of `curl <https://github.com/curl/curl>`_.
|
||||
|
||||
Another alternative would be to download the finished list directly from the curl website: `CA certificates extracted from Mozilla <https://curl.se/docs/caextract.html>`_
|
||||
|
||||
The common certificates bundle were made by selecting the authorities with a market share of more than 1 % from w3tech's `SSL Survey <https://w3techs.com/technologies/overview/ssl_certificate>`_.
|
||||
|
||||
These authorities were then used to pick the names of the certificates for the filter list, `cmn_crt_authorities.csv`, from `this list <https://ccadb-public.secure.force.com/mozilla/IncludedCACertificateReportPEMCSV>`_ provided by Mozilla.
|
||||
The common certificates bundle were made by selecting the authorities with a market share of more than 1% from w3tech's `SSL Survey <https://w3techs.com/technologies/overview/ssl_certificate>`_.
|
||||
|
||||
These authorities were then used to pick the names of the certificates for the filter list, ``cmn_crt_authorities.csv``, from `this list <https://ccadb-public.secure.force.com/mozilla/IncludedCACertificateReportPEMCSV>`_ provided by Mozilla.
|
||||
|
||||
|
||||
Updating the Certificate Bundle
|
||||
@@ -73,9 +76,8 @@ Updating the Certificate Bundle
|
||||
The bundle is embedded into the app and can be updated along with the app by an OTA update. If you want to include a more up-to-date bundle than the bundle currently included in ESP-IDF, then the certificate list can be downloaded from Mozilla as described in :ref:`updating_bundle`.
|
||||
|
||||
|
||||
|
||||
Application Example
|
||||
-------------------
|
||||
Application Examples
|
||||
--------------------
|
||||
|
||||
Simple HTTPS example that uses ESP-TLS to establish a secure socket connection using the certificate bundle with two custom certificates added for verification: :example:`protocols/https_x509_bundle`.
|
||||
|
||||
@@ -87,4 +89,3 @@ API Reference
|
||||
-------------
|
||||
|
||||
.. include-build-file:: inc/esp_crt_bundle.inc
|
||||
|
||||
|
||||
@@ -1,6 +1,8 @@
|
||||
Mbed TLS
|
||||
========
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
`Mbed TLS <https://github.com/Mbed-TLS/mbedtls>`_ is a C library that implements cryptographic primitives, X.509 certificate manipulation and the SSL/TLS and DTLS protocols. Its small code footprint makes it suitable for embedded systems.
|
||||
|
||||
.. note::
|
||||
@@ -16,6 +18,9 @@ Mbed TLS supports SSL 3.0 up to TLS 1.3 and DTLS 1.0 to 1.2 communication by pro
|
||||
- Hashing
|
||||
- Encryption/decryption
|
||||
|
||||
Supported TLS versions include SSL 3.0, TLS 1.0, TLS 1.1, TLS 1.2, and TLS 1.3, but on the latest ESP-IDF, SSL 3.0, TLS 1.0, and TLS 1.1 have been removed from Mbed TLS. Supported DTLS versions include DTLS 1.0, DTLS 1.1, and DTLS 1.2, but on the latest ESP-IDF, DTLS 1.0 has been removed from Mbed TLS.
|
||||
|
||||
|
||||
Mbed TLS Documentation
|
||||
----------------------
|
||||
|
||||
@@ -27,12 +32,11 @@ For Mbed TLS documentation please refer to the following (upstream) pointers:
|
||||
Mbed TLS Support in ESP-IDF
|
||||
---------------------------
|
||||
|
||||
Please find the information about the Mbed TLS versions present in different branches of ESP-IDF `here <https://github.com/espressif/mbedtls/wiki#mbed-tls-support-in-esp-idf>`__.
|
||||
|
||||
Please find the information about the Mbed TLS versions presented in different branches of ESP-IDF `here <https://github.com/espressif/mbedtls/wiki#mbed-tls-support-in-esp-idf>`__.
|
||||
|
||||
.. note::
|
||||
|
||||
Please refer the :ref:`ESP-IDF Migration Guide <migration_guide_mbedtls>` to migrate from Mbed TLS version 2.x to version 3.0 or greater.
|
||||
Please refer the :ref:`migration_guide_mbedtls` to migrate from Mbed TLS version 2.x to version 3.0 or greater.
|
||||
|
||||
Application Examples
|
||||
--------------------
|
||||
@@ -47,7 +51,7 @@ If the Mbed TLS API is to be used directly, refer to the example :example:`proto
|
||||
Alternatives
|
||||
------------
|
||||
|
||||
:doc:`/api-reference/protocols/esp_tls` acts as an abstraction layer over the underlying SSL/TLS library and thus has an option to use Mbed TLS or wolfSSL as the underlying library. By default, only Mbed TLS is available and used in ESP-IDF whereas wolfSSL is available publicly at https://github.com/espressif/esp-wolfSSL with the upstream submodule pointer.
|
||||
:doc:`/api-reference/protocols/esp_tls` acts as an abstraction layer over the underlying SSL/TLS library and thus has an option to use Mbed TLS or wolfSSL as the underlying library. By default, only Mbed TLS is available and used in ESP-IDF whereas wolfSSL is available publicly at `<https://github.com/espressif/esp-wolfSSL>` with the upstream submodule pointer.
|
||||
|
||||
Please refer to :ref:`ESP-TLS: Underlying SSL/TLS Library Options <esp_tls_wolfssl>` docs for more information on this and comparison of Mbed TLS and wolfSSL.
|
||||
|
||||
@@ -71,7 +75,7 @@ Following is a brief list of important config options accessible at ``Component
|
||||
|
||||
.. note::
|
||||
|
||||
Mbed TLS v3.0.0 and later support only TLS 1.2 and TLS 1.3 (SSL 3.0, TLS 1.0, TLS 1.1 and DTLS 1.0 are not supported). The support for TLS 1.3 is experimental and only supports the client-side. More information about this can be found out `here <https://github.com/espressif/mbedtls/blob/9bb5effc3298265f829878825d9bd38478e67514/docs/architecture/tls13-support.md>`__.
|
||||
Mbed TLS v3.0.0 and later support only TLS 1.2 and TLS 1.3 (SSL 3.0, TLS 1.0, TLS 1.1, and DTLS 1.0 are not supported). The support for TLS 1.3 is experimental and only supports the client-side. More information about this can be found out `here <https://github.com/espressif/mbedtls/blob/9bb5effc3298265f829878825d9bd38478e67514/docs/architecture/tls13-support.md>`__.
|
||||
|
||||
|
||||
Performance and Memory Tweaks
|
||||
@@ -84,19 +88,28 @@ Reducing Heap Usage
|
||||
|
||||
The following table shows typical memory usage with different configs when the :example:`protocols/https_request` example (with Server Validation enabled) was run with Mbed TLS as the SSL/TLS library.
|
||||
|
||||
+------------------------------+--------------------------------------------------+----------------------+
|
||||
| Mbed TLS Test | Related Configs | Heap Usage (approx.) |
|
||||
+==============================+==================================================+======================+
|
||||
| Default | NA | 42196 B |
|
||||
+------------------------------+--------------------------------------------------+----------------------+
|
||||
| Enable SSL Variable Length | :ref:`CONFIG_MBEDTLS_SSL_VARIABLE_BUFFER_LENGTH` | 42120 B |
|
||||
+------------------------------+--------------------------------------------------+----------------------+
|
||||
| Disable Keep Peer Certificate| :ref:`CONFIG_MBEDTLS_SSL_KEEP_PEER_CERTIFICATE` | 38533 B |
|
||||
+------------------------------+--------------------------------------------------+----------------------+
|
||||
| Enable Dynamic TX/RX Buffer | :ref:`CONFIG_MBEDTLS_DYNAMIC_BUFFER` | 22013 B |
|
||||
| | :ref:`CONFIG_MBEDTLS_DYNAMIC_FREE_CONFIG_DATA` | |
|
||||
| | :ref:`CONFIG_MBEDTLS_DYNAMIC_FREE_CA_CERT` | |
|
||||
+------------------------------+--------------------------------------------------+----------------------+
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:widths: 25 60 30
|
||||
:align: center
|
||||
|
||||
* - Mbed TLS Test
|
||||
- Related Configs
|
||||
- Heap Usage (approx.)
|
||||
* - Default
|
||||
- NA
|
||||
- 42196 B
|
||||
* - Enable SSL Variable Length
|
||||
- :ref:`CONFIG_MBEDTLS_SSL_VARIABLE_BUFFER_LENGTH`
|
||||
- 42120 B
|
||||
* - Disable Keep Peer Certificate
|
||||
- :ref:`CONFIG_MBEDTLS_SSL_KEEP_PEER_CERTIFICATE`
|
||||
- 38533 B
|
||||
* - Enable Dynamic TX/RX Buffer
|
||||
- :ref:`CONFIG_MBEDTLS_DYNAMIC_BUFFER`
|
||||
:ref:`CONFIG_MBEDTLS_DYNAMIC_FREE_CONFIG_DATA`
|
||||
:ref:`CONFIG_MBEDTLS_DYNAMIC_FREE_CA_CERT`
|
||||
- 22013 B
|
||||
|
||||
.. note::
|
||||
|
||||
@@ -110,4 +123,4 @@ Under ``Component Config -> mbedTLS``, there are multiple Mbed TLS features whic
|
||||
|
||||
|
||||
.. _`API Reference`: https://mbed-tls.readthedocs.io/projects/api/en/v3.4.1/
|
||||
.. _`Knowledge Base`: https://mbed-tls.readthedocs.io/en/latest/kb/
|
||||
.. _`Knowledge Base`: https://mbed-tls.readthedocs.io/en/latest/kb/
|
||||
Reference in New Issue
Block a user