diff --git a/README.md b/README.md index 79f6968..d532d50 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ 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. +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. @@ -17,11 +17,20 @@ Currently the certificates are filtered from the [`curl` root list](https://curl.se/docs/caextract.html), which is based on the Mozilla root list, and from a local file. -- `tools/extra.pem` is a list of certificates needed but not present in the Mozilla root list. -- `tools/filter_certs.py` does the filtering to the most common root cert providers. -- `tools/filters.txt` contains regexps to match those providers or the cert names -- `tools/test_site_coverage.py` tests a given `roots.pem` against a long list of URL's. -- `tools/urls.txt` is that list of URLs. Add to it as necessary. Some are commented out, for reasons noted. +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 bundle is in `data/`. -- `data/roots.pem` contains the filtered list, with comments describing each certificate. +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/`](https://github.com/espressif/esp-idf/tree/master/components/mbedtls/esp_crt_bundle). Use `CONFIG_MBEDTLS_CERTIFICATE_BUNDLE_DEFAULT_FULL`, `CONFIG_MBEDTLS_CERTIFICATE_BUNDLE_DEFAULT_CMN`, etc.