certificates/README.md

TLS/SSL certificates used in Adafruit software

CircuitPython, NINA-FW, Adafruit IO Arduino libraries, and other Adafruit software need a current set of TLS root certificates for secure web access. Microsoft, Mozilla, Android, curl, and other projects maintain lists of root and related certificates. Those lists are quite complete, and too large for some embedded firmware.

This repo includes a tool to combine local or fetched root certificate lists and filter them to the most commonly needed roots. There is also a testing tool, and a .pem file canonicalization tool. Projects can then use this repo as a submodule to have access to an updated list of root certificates.

Currently the certificates are filtered from the curl root list, which is based on the Mozilla root list, and from a local file.

To generate the root certificate bundles, manually use the tools in tools/:

• extra.pem is a list of certificates needed but not present in the Mozilla root list.
• generate_pem_files.py generates a full and a filtered list from the Mozilla root list.
• include.txt contains regexps to filter the full list.
• exclude.txt contains regexps to exclude specific items from the filtered list.
• test_site_coverage.py tests a given roots.pem against a long list of URL's.
• urls.txt is that list of URLs. Add to it as necessary. Some are commented out, for reasons noted.
• sort_pem_certificates.py will canonicalize a .pem file by labeling and sorting the certificates, and optionally changing the certificates' base64 line lengths.

The resulting filtered root certificate bundles are in data/:

• data/roots-full.pem contains the full Mozilla list, plus certificates in tools/extra.pem
• data/roots-filtered.pem contains the filtered list, with comments describing each certificate.

An alternative for Espressif to using this repo is to use the full and "common" (CMN) lists generated by ESP-IDF, in components/mbedtls/esp_crt_bundle/. Use CONFIG_MBEDTLS_CERTIFICATE_BUNDLE_DEFAULT_FULL, CONFIG_MBEDTLS_CERTIFICATE_BUNDLE_DEFAULT_CMN, etc.