alex/esp-idf
alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2024-10-05 20:47:46 -04:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Merge branch 'docs/mbedtls' into 'master'

Browse Source 
docs: Add documentation for `mbedtls`

Closes IDF-2167

See merge request espressif/esp-idf!17450
This commit is contained in:
Mahavir Jain 2022-03-17 11:30:39 +08:00
commit 2eddcc1b63
8 changed files with 115 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/en/api-guides/performance/ram-usage.rst
View File

@ -102,7 +102,7 @@ There are some ESP-IDF configuration options that can reduce heap usage at runti
- lwIP documentation has a section to configure :ref:`lwip-ram-usage`.
:SOC_WIFI_SUPPORTED: - :ref:`wifi-buffer-usage` describes options to either reduce numbers of "static" buffers or reduce the maximum number of "dynamic" buffers in use, in order to minimize memory usage at possible cost of performance. Note that "static" Wi-Fi buffers are still allocated from heap when Wi-Fi is initialized and will be freed if Wi-Fi is deinitialized.
:esp32: - The Ethernet driver allocates DMA buffers for the internal Ethernet MAC when it is initialized - configuration options are :ref:`CONFIG_ETH_DMA_BUFFER_SIZE`, :ref:`CONFIG_ETH_DMA_RX_BUFFER_NUM`, :ref:`CONFIG_ETH_DMA_TX_BUFFER_NUM`.
- mbedTLS TLS session memory usage can be minimized by enabling the ESP-IDF feature :ref:`CONFIG_MBEDTLS_DYNAMIC_BUFFER`.
- Several Mbed TLS configuration options can be used to reduce heap memory usage. See the :ref:`Mbed TLS <reducing_ram_usage_mbedtls>` docs for details.
:esp32: - In single core mode only, it's possible to use IRAM as byte accessible memory (added to the regular heap) by enabling :ref:`CONFIG_ESP32_IRAM_AS_8BIT_ACCESSIBLE_MEMORY`. Note that this option carries a performance penalty and the risk of security issues caused by executable data. If this option is enabled then it's possible to set other options to prefer certain buffers be allocated from this memory: :ref:`mbedTLS <CONFIG_MBEDTLS_MEM_ALLOC_MODE>`, :ref:`NimBLE <CONFIG_BT_NIMBLE_MEM_ALLOC_MODE>`.
:esp32: - Reduce :ref:`CONFIG_BTDM_CTRL_BLE_MAX_CONN` if using BLE.
:esp32: - Reduce :ref:`CONFIG_BTDM_CTRL_BR_EDR_MAX_ACL_CONN` if using Bluetooth Classic.

7
docs/en/api-guides/performance/size.rst
View File

@ -363,6 +363,8 @@ Enabling Nano formatting also reduces the stack usage of each function that call
.. _Newlib README file: https://sourceware.org/newlib/README
.. _minimizing_binary_mbedtls:
mbedTLS features
@@@@@@@@@@@@@@@@
@ -375,12 +377,13 @@ These include:
- :ref:`CONFIG_MBEDTLS_SHA512_C`
- :ref:`CONFIG_MBEDTLS_CLIENT_SSL_SESSION_TICKETS`
- :ref:`CONFIG_MBEDTLS_SERVER_SSL_SESSION_TICKETS`
- :ref:`CONFIG_MBEDTLS_SSL_CONTEXT_SERIALIZATION`
- :ref:`CONFIG_MBEDTLS_SSL_ALPN`
- :ref:`CONFIG_MBEDTLS_SSL_RENEGOTIATION`
- :ref:`CONFIG_MBEDTLS_CCM_C`
- :ref:`CONFIG_MBEDTLS_GCM_C`
- :ref:`CONFIG_MBEDTLS_ECP_C` (Alternatively: Leave this option enabled but disable some of the elliptic curves listed in the sub-menu.)
- :ref:`CONFIG_MBEDTLS_SSL_RENEGOTIATION`
- Change :ref:`CONFIG_MBEDTLS_TLS_MODE` if both Server & Client are not needed
- Change :ref:`CONFIG_MBEDTLS_TLS_MODE` if both server & client functionalities are not needed
- Consider disabling some ciphersuites listed in the "TLS Key Exchange Methods" sub-menu (i.e. :ref:`CONFIG_MBEDTLS_KEY_EXCHANGE_RSA`)
The help text for each option has some more information.

2
docs/en/api-reference/protocols/esp_tls.rst
View File

@ -53,6 +53,8 @@ The ESP-TLS provides multiple options for TLS server verification on the client
* **skip server verification**: This is an insecure option provided in the ESP-TLS for testing purpose. 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:Enabling this option comes with a potential risk of establishing a TLS connection with a server which has a fake identity, provided that the server certificate is not provided either through API or other mechanism like ca_store etc.*
.. _esp_tls_wolfssl:
Underlying SSL/TLS Library Options
----------------------------------
The ESP-TLS component has an option to use mbedtls or wolfssl as their underlying SSL/TLS library. By default only mbedtls is available and is

1
docs/en/api-reference/protocols/index.rst
View File

@ -17,6 +17,7 @@ Application Protocols
esp_https_server
icmp_echo
mdns
mbedtls
Code examples for this API section are provided in the :example:`protocols` directory of ESP-IDF examples.

96
docs/en/api-reference/protocols/mbedtls.rst Normal file
View File

@ -0,0 +1,96 @@
Mbed TLS
========
`Mbed TLS <https://github.com/ARMmbed/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:: ESP-IDF uses a `fork <https://github.com/espressif/mbedtls>`_ of Mbed TLS which includes a few patches (related to hardware routines of certain modules like ``bignum (MPI)`` and ``ECC``) over vanilla Mbed TLS.
Mbed TLS supports SSL 3.0 up to TLS 1.3 and DTLS 1.0 to 1.2 communication by providing the following:
- TCP/IP communication functions: listen, connect, accept, read/write.
- SSL/TLS communication functions: init, handshake, read/write.
- X.509 functions: CRT, CRL and key handling
- Random number generation
- Hashing
- Encryption/decryption
.. note:: Mbed TLS is in the process of migrating all the documentation to a single place. In the meantime, users can find the documentation at the `old Mbed TLS site <https://tls.mbed.org/api>`_ .
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>`__.
.. 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.
Application Examples
--------------------
Examples in ESP-IDF use :doc:`/api-reference/protocols/esp_tls` which provides a simplified API interface for accessing the commonly used TLS functionality.
Refer to the examples :example:`protocols/https_server/simple` (Simple HTTPS server) and :example:`protocols/https_request` (Make HTTPS requests) for more information.
If the Mbed TLS API is to be used directly, refer to the example :example:`protocols/https_mbedtls`.
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.
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.
Important Config Options
------------------------
Following is a brief list of important config options accessible at ``Component Config -> mbedTLS``. The full list of config options can be found :ref:`here <CONFIG_MBEDTLS_MEM_ALLOC_MODE>`.
.. list::
- :ref:`CONFIG_MBEDTLS_SSL_PROTO_TLS1_2`: Support for TLS 1.2
- :ref:`CONFIG_MBEDTLS_SSL_PROTO_TLS1_3`: Support for TLS 1.3
- :ref:`CONFIG_MBEDTLS_CERTIFICATE_BUNDLE`: Support for trusted root certificate bundle (more about this: :doc:`/api-reference/protocols/esp_crt_bundle`)
- :ref:`CONFIG_MBEDTLS_CLIENT_SSL_SESSION_TICKETS`: Support for TLS Session Resumption: Client session tickets
- :ref:`CONFIG_MBEDTLS_SERVER_SSL_SESSION_TICKETS`: Support for TLS Session Resumption: Server session tickets
- :ref:`CONFIG_MBEDTLS_HARDWARE_SHA`: Support for hardware SHA acceleration
:SOC_AES_SUPPORT_AES_128: - :ref:`CONFIG_MBEDTLS_HARDWARE_AES`: Support for hardware AES acceleration
:not esp32c2: - :ref:`CONFIG_MBEDTLS_HARDWARE_MPI`: Support for hardware MPI (bignum) acceleration
:esp32c2: - :ref:`CONFIG_MBEDTLS_HARDWARE_ECC`: Support for hardware ECC acceleration
.. 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>`__.
Performance and Memory Tweaks
-----------------------------
.. _reducing_ram_usage_mbedtls:
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` | |
+------------------------------+--------------------------------------------------+----------------------+
.. note:: These values are subject to change with change in configuration options and versions of Mbed TLS.
Reducing Binary Size
^^^^^^^^^^^^^^^^^^^^
Under ``Component Config -> mbedTLS``, there are multiple Mbed TLS features which are enabled by default but can be disabled if not needed to save code size. More information can be about this can be found in :ref:`Minimizing Binary Size <minimizing_binary_mbedtls>` docs.

14
docs/en/migration-guides/protocols.rst
View File

@ -1,12 +1,14 @@
Migration of Protocol Components to ESP-IDF 5.0
===============================================
.. _migration_guide_mbedtls:
Mbed TLS
--------
For ESP-IDF v5.0, `Mbed TLS <https://github.com/ARMmbed/mbedtls>`_ has been updated from v2.x to v3.1.0.
The official guide for Mbed TLS to migrate from version 2.x to version 3.0 or greater can be found `here <https://github.com/ARMmbed/mbedtls/blob/development/docs/3.0-migration-guide.md>`__.
The official guide for Mbed TLS to migrate from version 2.x to version 3.0 or greater can be found `here <https://github.com/espressif/mbedtls/blob/9bb5effc3298265f829878825d9bd38478e67514/docs/3.0-migration-guide.md>`__.
Breaking Changes (Summary)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -16,18 +18,18 @@ Most structure fields are now private
- Direct access to fields of structures (``struct`` types) declared in public headers is no longer supported.
- Appropriate accessor functions (getter/setter) must be used for the same. A temporary workaround would be to use ``MBEDTLS_PRIVATE`` macro (**not recommended**).
- For more details, refer to the official guide `here <https://github.com/ARMmbed/mbedtls/blob/development/docs/3.0-migration-guide.md#most-structure-fields-are-now-private>`__.
- For more details, refer to the official guide `here <https://github.com/espressif/mbedtls/blob/9bb5effc3298265f829878825d9bd38478e67514/docs/3.0-migration-guide.md#most-structure-fields-are-now-private>`__.
SSL
^^^
- Removed the support for TLS 1.0, 1.1 and DTLS 1.0
- Removed the support for SSL 3.0
- Removed support for TLS 1.0, 1.1 and DTLS 1.0
- Removed support for SSL 3.0
Deprecated functions were removed from cryptography modules
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- The functions ``mbedtls_*_ret()`` (related to MD, SHA, RIPEMD, RNG, HMAC modules) was renamed to replace the corresponding functions without ``_ret`` appended and updated return value.
- For more details, refer to the official guide `here <https://github.com/ARMmbed/mbedtls/blob/development/docs/3.0-migration-guide.md#deprecated-functions-were-removed-from-hashing-modules>`__.
- For more details, refer to the official guide `here <https://github.com/espressif/mbedtls/blob/9bb5effc3298265f829878825d9bd38478e67514/docs/3.0-migration-guide.md#deprecated-functions-were-removed-from-hashing-modules>`__.
Deprecated Config Options
@ -50,7 +52,7 @@ Miscellaneous
Disabled Diffie-Hellman Key Exchange modes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The Diffie-Hellman Key Exchange modes have now been disabled by default due to security risks (see warning text `here <https://github.com/espressif/mbedtls/blob/HEAD/include/mbedtls/dhm.h>`__). Related configs are given below:
The Diffie-Hellman Key Exchange modes have now been disabled by default due to security risks (see warning text `here <https://github.com/espressif/mbedtls/blob/9bb5effc3298265f829878825d9bd38478e67514/include/mbedtls/dhm.h#L20>`__). Related configs are given below:
- ``MBEDTLS_DHM_C`` : Support for the Diffie-Hellman-Merkle module
- ``MBEDTLS_KEY_EXCHANGE_DHE_PSK`` : Support for Diffie-Hellman PSK (pre-shared-key) TLS authentication modes

1
docs/zh_CN/api-reference/protocols/index.rst
View File

@ -17,6 +17,7 @@
esp_https_server
icmp_echo
mdns
mbedtls
此 API 部分的示例代码存放在 ESP-IDF 示例项目的 :example:`protocols` 目录下。

1
docs/zh_CN/api-reference/protocols/mbedtls.rst Normal file
View File

@ -0,0 +1 @@
.. include:: ../../../en/api-reference/protocols/mbedtls.rst