From ca964dfbcc030eae500390810f44e9a9b5168e5f Mon Sep 17 00:00:00 2001 From: Aditya Patwardhan Date: Wed, 23 Dec 2020 23:30:40 +0530 Subject: [PATCH] esp-tls: Changed default behaviour for esp-tls client ( for security purpose) By default esp-tls client will now return error if no server verify option is provided, earlier it used to skip the verification by default. Added config option to skip server verification by default (for testing purpose) Updated required docs --- components/esp-tls/Kconfig | 19 +++++++++++++++++++ components/esp-tls/esp_tls_mbedtls.c | 5 +++++ components/esp-tls/esp_tls_wolfssl.c | 5 +++++ docs/en/api-reference/protocols/esp_tls.rst | 15 +++++++++++++++ 4 files changed, 44 insertions(+) diff --git a/components/esp-tls/Kconfig b/components/esp-tls/Kconfig index d47dedb940..b92b788828 100644 --- a/components/esp-tls/Kconfig +++ b/components/esp-tls/Kconfig @@ -52,6 +52,25 @@ menu "ESP-TLS" Enable support for pre shared key ciphers, supported for both mbedTLS as well as wolfSSL TLS library. + config ESP_TLS_INSECURE + bool "Allow potentially insecure options" + help + You can enable some potentially insecure options. These options should only be used for testing pusposes. + Only enable these options if you are very sure. + + config ESP_TLS_SKIP_SERVER_CERT_VERIFY + bool "Skip server certificate verification by default (WARNING: ONLY FOR TESTING PURPOSE, READ HELP)" + depends on ESP_TLS_INSECURE + help + After enabling this option the esp-tls client will skip the server certificate verification + by default. Note that this option will only modify the default behaviour of esp-tls client + regarding server cert verification. The default behaviour should only be applicable when + no other option regarding the server cert verification is opted in the esp-tls config + (e.g. crt_bundle_attach, use_global_ca_store etc.). + 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. + config ESP_WOLFSSL_SMALL_CERT_VERIFY bool "Enable SMALL_CERT_VERIFY" depends on ESP_TLS_USING_WOLFSSL diff --git a/components/esp-tls/esp_tls_mbedtls.c b/components/esp-tls/esp_tls_mbedtls.c index 94aa13fc04..bfd8e27da0 100644 --- a/components/esp-tls/esp_tls_mbedtls.c +++ b/components/esp-tls/esp_tls_mbedtls.c @@ -492,7 +492,12 @@ esp_err_t set_client_config(const char *hostname, size_t hostlen, esp_tls_cfg_t return ESP_ERR_INVALID_STATE; #endif } else { +#ifdef CONFIG_ESP_TLS_SKIP_SERVER_CERT_VERIFY mbedtls_ssl_conf_authmode(&tls->conf, MBEDTLS_SSL_VERIFY_NONE); +#else + ESP_LOGE(TAG, "No server verification option set in esp_tls_cfg_t structure. Check esp_tls API reference"); + return ESP_ERR_MBEDTLS_SSL_SETUP_FAILED; +#endif } if (cfg->use_secure_element) { diff --git a/components/esp-tls/esp_tls_wolfssl.c b/components/esp-tls/esp_tls_wolfssl.c index 9e79010c08..15ee7da3b0 100644 --- a/components/esp-tls/esp_tls_wolfssl.c +++ b/components/esp-tls/esp_tls_wolfssl.c @@ -201,7 +201,12 @@ static esp_err_t set_client_config(const char *hostname, size_t hostlen, esp_tls return ESP_ERR_INVALID_STATE; #endif } else { +#ifdef CONFIG_ESP_TLS_SKIP_SERVER_CERT_VERIFY wolfSSL_CTX_set_verify( (WOLFSSL_CTX *)tls->priv_ctx, WOLFSSL_VERIFY_NONE, NULL); +#else + ESP_LOGE(TAG, "No server verification option set in esp_tls_cfg_t structure. Check esp_tls API reference"); + return ESP_ERR_WOLFSSL_SSL_SETUP_FAILED; +#endif } if (cfg->clientcert_buf != NULL && cfg->clientkey_buf != NULL) { diff --git a/docs/en/api-reference/protocols/esp_tls.rst b/docs/en/api-reference/protocols/esp_tls.rst index 74f4775740..85d792403e 100644 --- a/docs/en/api-reference/protocols/esp_tls.rst +++ b/docs/en/api-reference/protocols/esp_tls.rst @@ -38,6 +38,21 @@ The ESP-TLS component has a file :component_file:`esp-tls/esp_tls.h` which cont of the two SSL/TLS Libraries between mbedtls and wolfssl for its operation. API specific to mbedtls are present in :component_file:`esp-tls/private_include/esp_tls_mbedtls.h` and API specific to wolfssl are present in :component_file:`esp-tls/private_include/esp_tls_wolfssl.h`. +TLS Server verification +----------------------- + +The ESP-TLS provides multiple options for TLS server verification on the client side. The ESP-TLS client can verify the server by validating the peer's server certificate or with the help of pre-shared keys. The user should select only one of the following options in the :cpp:type:`esp_tls_cfg_t` structure for TLS server verification. If no option is selected then client will return a fatal error by default at the time of the TLS connection setup. + + * **cacert_buf** and **cacert_bytes**: The CA certificate can be provided in a buffer to the :cpp:type:`esp_tls_cfg_t` structure. The ESP-TLS will use the CA certificate present in the buffer to verify the server. The following variables in :cpp:type:`esp_tls_cfg_t` structure must be set. + + * ``cacert_buf`` - pointer to the buffer which contains the CA cert. + * ``cacert_bytes`` - size of the CA certificate in bytes. + * **use_global_ca_store**: The ``global_ca_store`` can be initialized and set at once. Then it can be used to verify the server for all the ESP-TLS connections which have set ``use_global_ca_store = true`` in their respective :cpp:type:`esp_tls_cfg_t` structure. See API Reference section below on information regarding different API used for initializing and setting up the ``global_ca_store``. + * **crt_bundle_attach**: The ESP x509 Certificate Bundle API provides an easy way to include a bundle of custom x509 root certificates for TLS server verification. More details can be found at :doc:`ESP x509 Certificate Bundle` + * **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 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 the server verification is selected. + * **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.* + 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