From 893b1562a84f71d06f0dcd236aacc2150ee9f4ad Mon Sep 17 00:00:00 2001 From: Daniel McCarney Date: Tue, 6 Aug 2024 10:23:24 -0400 Subject: [PATCH] docs: update workspace README * Add webpki-root-certs and describe why you should probably prefer webpki-roots * Removes the regenerating sources information - this is covered by each individual crate's README. The Warning is left since this is valuable top-level context to remember for each crate. --- README.md | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 0c7afa7..b5489e9 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,14 @@ -This workspace contains the crates webpki-roots and webpki-ccadb. +This workspace contains the crates `webpki-roots`, `webpki-root-certs` and `webpki-ccadb`. -The webpki-roots crate contains Mozilla's root certificates for use with -the [webpki](https://github.com/rustls/webpki) or -[rustls](https://github.com/rustls/rustls) crates. +The `webpki-roots` crate contains Mozilla's trusted root certificates for use with +the [webpki](https://github.com/rustls/webpki) or [rustls](https://github.com/rustls/rustls) crates. -The webpki-ccadb crate populates the root certificates for the webpki-roots crate +The `webpki-root-certs` is similar to `webpki-roots`, but for use with other projects +that require the full self-signed X.509 certificate for each trusted root. This is +unnecessary overhead for `webpki` and `rustls` and you should prefer using +`webpki-roots` for these projects. + +The `webpki-ccadb` crate populates the root certificates for the webpki-roots crate using the data provided by the [Common CA Database (CCADB)](https://www.ccadb.org/). Inspired by [certifi.io](https://certifi.io/en/latest/). @@ -13,7 +17,7 @@ Inspired by [certifi.io](https://certifi.io/en/latest/). # Warning -This library is suitable for use in applications that can always be recompiled and instantly deployed. +These libraries are suitable for use in applications that can always be recompiled and instantly deployed. For applications that are deployed to end-users and cannot be recompiled, or which need certification before deployment, consider a library that uses the platform native certificate verifier such as [rustls-platform-verifier]. This has the additional benefit of supporting OS provided CA constraints @@ -22,11 +26,6 @@ and revocation data. [rustls-platform-verifier]: https://docs.rs/rustls-platform-verifier # License -The underlying data is MPL-licensed, and `webpki-roots/src/lib.rs` -is therefore a derived work. -# Regenerating sources -Sources are generated in an integration test, in `webpki-roots/tests/codegen.rs`. The test -will fail if the sources are out of date relative to upstream, and update -`webpki-roots/src/lib.rs` if so. The code is generated in deterministic order so changes -to the source should only result from upstream changes. +The underlying data is MPL-licensed, and the data in `webpki-roots` and `webpki-root-certs` +is therefore a derived work.