1ESP x509 Certificate Bundle
2===========================
3
4Overview
5--------
6
7The ESP x509 Certificate Bundle API provides an easy way to include a bundle of custom x509 root certificates for TLS server verification.
8
9.. note:: The bundle is currently not available when using WolfSSL.
10
11The 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.
12
13When generating the bundle you may choose between:
14
15 * The full root certificate bundle from Mozilla, containing more than 130 certificates. The current bundle was updated Tue Oct  5 09:35:35 2021 GMT.
16 * 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.
17
18In 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.
19
20.. 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`.
21
22Configuration
23-------------
24
25Most configuration is done through menuconfig. Make and CMake will generate the bundle according to the configuration and embed it.
26
27 * :ref:`CONFIG_MBEDTLS_CERTIFICATE_BUNDLE`: automatically build and attach the bundle.
28 * :ref:`CONFIG_MBEDTLS_DEFAULT_CERTIFICATE_BUNDLE`: decide which certificates to include from the complete root list.
29 * :ref:`CONFIG_MBEDTLS_CUSTOM_CERTIFICATE_BUNDLE_PATH`: specify the path of any additional certificates to embed in the bundle.
30
31To enable the bundle when using ESP-TLS simply pass the function pointer to the bundle attach function:
32
33.. code:: c
34
35    esp_tls_cfg_t cfg = {
36         .crt_bundle_attach = esp_crt_bundle_attach,
37    };
38
39This is done to avoid embedding the certificate bundle unless activated by the user.
40
41If using mbedTLS directly then the bundle may be activated by directly calling the attach function during the setup process:
42
43.. code:: c
44
45    mbedtls_ssl_config conf;
46    mbedtls_ssl_config_init(&conf);
47
48    esp_crt_bundle_attach(&conf);
49
50
51Generating the List of Root Certificates
52----------------------------------------
53The list of root certificates comes from Mozilla's NSS root certificate store, which can be found `here <https://wiki.mozilla.org/CA/Included_Certificates>`_
54The 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>`_.
55Another 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>`_
56
57The 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>`_.
58These 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.
59
60.. _updating_bundle:
61
62Updating the Certificate Bundle
63-------------------------------
64
65The 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`.
66
67
68
69Application Example
70-------------------
71
72Simple 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`.
73
74HTTPS example that uses ESP-TLS and the default bundle: :example:`protocols/https_request`.
75
76HTTPS example that uses mbedTLS and the default bundle: :example:`protocols/https_mbedtls`.
77
78API Reference
79-------------
80
81.. include-build-file:: inc/esp_crt_bundle.inc
82
83