Skip to content

Commit

Permalink
docs: update workspace README
Browse files Browse the repository at this point in the history
* 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.
  • Loading branch information
cpu committed Aug 7, 2024
1 parent dfdf31f commit 893b156
Showing 1 changed file with 12 additions and 13 deletions.
25 changes: 12 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
@@ -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/).

Expand All @@ -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
Expand All @@ -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.

0 comments on commit 893b156

Please sign in to comment.