Add ESP certificate bundle feature

Adds the ESP certificate bundle feature that enables users to bundle a
root certificate bundle together with their application.

Default bundle includes all Mozilla root certificates

Closes IDF-296

docs/en/api-reference/protocols/esp_crt_bundle.rst

@@ -0,0 +1,82 @@
+ESP x509 Certificate Bundle
+===========================
+
+Overview
+--------
+
+The ESP x509 Certificate Bundle API provides an easy way to include a bundle of custom x509 root certificates for TLS server verification.
+
+.. note:: 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.
+
+When generating the bundle you may choose between:
+
+ * The full root certificate bundle from Mozilla, containing more than 130 certificates. The current bundle was updated Wed Jan 23 04:12:09 2019 GMT.
+ * A pre-selected filter list of the name of the most commonly used root certificates, reducing the amount of certificates to around 35 while still having around 90 % coverage according to market share statistics.
+
+In addition it is possible to specify a path to a certificate file or a directory containing certificates which then will be added to the generated bundle.
+
+.. note:: Trusting all root certificates means the list will have to be updated if any of the certificates are retracted. This includes removing them from `cacrt_all.pem`.
+
+Configuration
+-------------
+
+Most configuration is done through menuconfig. Make and CMake will generate 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_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:
+
+.. code:: c
+
+    esp_tls_cfg_t cfg = {
+         .crt_bundle_attach = esp_crt_bundle_attach,
+    };
+
+This is done to avoid embedding the certificate bundle unless activated by the user.
+
+If using mbedTLS directly then the bundle may be activated by directly calling the attach function during the setup process:
+
+.. code:: c
+
+    mbedtls_ssl_config conf;
+    mbedtls_ssl_config_init(&conf);
+
+    esp_crt_bundle_attach(&conf);
+
+
+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.haxx.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/all>`_.
+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_bundle:
+
+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 IDF, then the certificate list can be downloaded from Mozilla as described in :ref:`updating_bundle`.
+
+
+
+Application Example
+-------------------
+
+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`.
+
+HTTPS example that uses ESP-TLS and the default bundle: :example:`protocols/https_request`.
+
+HTTPS example that uses mbedTLS and the default bundle: :example:`protocols/https_mbedtls`.
+
+API Reference
+-------------
+
+.. include-build-file:: inc/esp_crt_bundle.inc
+

docs/en/api-reference/protocols/index.rst

@@ -17,6 +17,7 @@ Application Protocols
     Modbus <modbus>
     Websocket Client <esp_websocket_client>
     :esp32: ESP Serial Slave Link <esp_serial_slave_link>
+    Certificate Bundle <esp_crt_bundle>
 
 Code examples for this API section are provided in the :example:`protocols` directory of ESP-IDF examples.