Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add deployment considerations section to README #142

Merged
merged 3 commits into from
Oct 2, 2024
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,29 @@ a system CA bundle is unavailable.
[openssl-probe]: https://github.com/alexcrichton/openssl-probe
[webpki-roots]: https://github.com/rustls/webpki-roots

## Deployment Considerations

When choosing to use `rustls-platform-verifier` or another trust store option, there are important differences to consider. These
complexspaces marked this conversation as resolved.
Show resolved Hide resolved
are primarily about root certificate availability:

| Backend | Updates | Roots used |
complexspaces marked this conversation as resolved.
Show resolved Hide resolved
|----------------------------------|---------------------------------|-------------------------------------------------------------------------------------------------------|
complexspaces marked this conversation as resolved.
Show resolved Hide resolved
| OS/platform (non-Linux/BSD) | Live pushes | System store, with correct (dis)trust decisions from every source available. |
cpu marked this conversation as resolved.
Show resolved Hide resolved
| `rustls-native-certs` + `webpki` | Live pushes | System store, with no (dis)trust decisions. All roots are treated equally regardless of their status. |
| `webpki-roots` + `webpki` | Static, manual updates required | Hardcoded Mozilla CA roots, and all roots are treated equally. |
complexspaces marked this conversation as resolved.
Show resolved Hide resolved

**In general**: It is the opinion of the `rustls` team and platform verifier maintainers that this is the best default available for client-side libraries and applications
complexspaces marked this conversation as resolved.
Show resolved Hide resolved
making connections to TLS servers when running on common operating systems. This is because it gets both live trust information (new roots, explicit markers, and auto-managed CRLs)
and better matches the common expectation of apps running on that platform (to use proxies, for example). Otherwise, it becomes your maintenance burden to
ship updates right away in order to handle increasing numbers of positive and negative trust events in the WebPKI/certificate ecosystem, or risk availability and security concerns.

Even though platform verifiers are sometimes implemented in memory-unsafe languages, it is very unlikely that Rust apps using this library will become a point of weakness.
This is due to either using a smaller set of servers or just being less exposed then other critical functions of the operating system, default web browser, etc.
cpu marked this conversation as resolved.
Show resolved Hide resolved
But if you are, for example, fuzzing or scanning all certificates on the open internet, using a 100% Rust option like `webpki` is a better and more secure option.
cpu marked this conversation as resolved.
Show resolved Hide resolved

`rustls-platform-verifier` is widely deployed by several applications that use the `rustls` stack, such as 1Password, Bitwarden, Signal, and `rustup`, on a wide set of OSes.
This means that it has received lots of exposure to edge cases and has real-world experience/expertise invested into it to ensure optimal compatibility and security.

## Installation and setup
On most platforms, no setup should be required beyond adding the dependency via `cargo`:
```toml
Expand Down