128 lines
5.8 KiB
Markdown
128 lines
5.8 KiB
Markdown
|
|
|
|
**rustls-native-certs** allows [rustls](https://github.com/rustls/rustls) to use the
|
|
platform's native certificate store when operating as a TLS client.
|
|
|
|
This is supported on Windows, macOS and Linux:
|
|
|
|
- On all platforms, the `SSL_CERT_FILE` environment variable is checked first.
|
|
If that's set, certificates are loaded from the path specified by that variable,
|
|
or an error is returned if certificates cannot be loaded from the given path.
|
|
If it's not set, then the platform-specific certificate source is used.
|
|
- On Windows, certificates are loaded from the system certificate store.
|
|
The [`schannel`](https://github.com/steffengy/schannel-rs) crate is used to access
|
|
the Windows certificate store APIs.
|
|
- On macOS, certificates are loaded from the keychain.
|
|
The user, admin and system trust settings are merged together as documented
|
|
by Apple. The [`security-framework`](https://github.com/kornelski/rust-security-framework)
|
|
crate is used to access the keystore APIs.
|
|
- On Linux and other UNIX-like operating systems, the
|
|
[`openssl-probe`](https://github.com/alexcrichton/openssl-probe) crate is used to discover
|
|
the filename of the system CA bundle.
|
|
|
|
# Status
|
|
rustls-native-certs is currently in development.
|
|
|
|
If you'd like to help out, please see [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
|
|
[](https://github.com/rustls/rustls-native-certs/actions/workflows/rust.yml)
|
|
[](https://docs.rs/rustls-native-certs)
|
|
|
|
## Release history:
|
|
|
|
* 0.7.0 (2023-12-03)
|
|
- Switched to using the [pki-types](https://github.com/rustls/pki-types) crate.
|
|
- `load_native_certs` now returns `Vec<pki_types::CertificateDer<'static>>` instead of `Vec<Certificate>`
|
|
- the `Certificate` newtype has been removed.
|
|
- Update dependencies.
|
|
* 0.6.3 (2023-06-14)
|
|
- Bump MSRV to 1.60.
|
|
- Windows: avoid storing certificates which are currently invalid.
|
|
- Implement `AsRef<[u8]>` for `Certificate`.
|
|
* 0.6.2 (2022-04-14):
|
|
- Update dependencies.
|
|
* 0.6.1 (2021-10-25):
|
|
- Allow overrides using `SSL_CERT_FILE` on all platforms.
|
|
* 0.6.0 (2021-10-24):
|
|
- Remove rustls dependency entirely.
|
|
* 0.5.0 (2020-11-22):
|
|
- Update dependencies.
|
|
- Make rustls dependency optional, for use with reqwest's certificate types. Thanks to @est31.
|
|
* 0.4.0 (2020-07-05):
|
|
- Update dependencies.
|
|
* 0.3.0 (2020-02-24):
|
|
- Support wider range of UNIX platforms.
|
|
- Update dependencies.
|
|
* 0.2.0 (2020-01-26):
|
|
- Return valid certificates even in the presence of invalid ones. This allows
|
|
callers to opt-in to "best effort" behaviour.
|
|
* 0.1.0 (2019-11-04):
|
|
- Initial release.
|
|
|
|
# API
|
|
|
|
This library exposes a single function with this signature:
|
|
|
|
```rust
|
|
pub fn load_native_certs() -> Result<Vec<pki_types::CertificateDer<'static>>, std::io::Error>
|
|
```
|
|
|
|
On success, this returns a `Vec<pki_types::CertificateDer<'static>>` loaded with a
|
|
snapshot of the root certificates found on this platform. This
|
|
function fails in a platform-specific way, expressed in a `std::io::Error`.
|
|
|
|
This function can be expensive: on some platforms it involves loading
|
|
and parsing a ~300KB disk file. It's therefore prudent to call
|
|
this sparingly.
|
|
|
|
# Worked example
|
|
|
|
See [`examples/google.rs`](examples/google.rs).
|
|
|
|
# Should I use this or `webpki-roots`?
|
|
|
|
(Background: [webpki-roots](https://crates.io/crates/webpki-roots) is a crate that compiles-in Mozilla's set of root certificates.)
|
|
|
|
This crate is preferable in many ways to *webpki-roots*.
|
|
To sum up the pros and cons:
|
|
|
|
Pros:
|
|
|
|
- **This crate respects local configuration of root certificates**: both
|
|
removal of roots that the user finds untrustworthy, and addition of locally-trusted roots.
|
|
_The latter case is exceedingly important if your application is required to work in
|
|
enterprise environments with "transparent" TLS-terminating middleboxes._
|
|
- **This crate instantaneously reflects underlying system configuration**. _Since webpki-roots
|
|
compiles in root certificates, getting an update to these requires taking regular updates
|
|
to this crate, plus recompilation and redeployment of the application. This is a long-winded
|
|
process that may become a liability in the event of a severe misissuance._
|
|
- **This crate is compatible with developer aids** such as [mkcert](https://github.com/FiloSottile/mkcert).
|
|
|
|
Cons:
|
|
|
|
- **Use of the OS certificate store is not the same as relying on OS trust verification**
|
|
because platform verifiers might impose additional criteria before deciding whether to trust
|
|
a root ostensibly included in the OS certificate store (for example, an expiration date).
|
|
- **The OS certificate store is occasionally "attacked" by [malware](https://en.wikipedia.org/wiki/Superfish)**
|
|
or just [bad software](https://sennheiser.zendesk.com/hc/en-us/articles/360011888254).
|
|
- **The OS update system may, in fact, be quite poor at keeping the root certificates up-to-date**
|
|
if it is disabled or out-of-support.
|
|
- **The quality of the `ca-certificates` package on debian-based Linux distributions is poor**.
|
|
At the time of writing, this ships many certificates not included in the Mozilla
|
|
set, either because they [failed an audit and were withdrawn](https://bugzilla.mozilla.org/show_bug.cgi?id=1448506) or
|
|
[were removed for mississuance](https://bugzilla.mozilla.org/show_bug.cgi?id=1552374).
|
|
- **You may prefer to insulate yourself against local configuration** for support or
|
|
(perhaps inadvisable) security reasons.
|
|
|
|
# License
|
|
|
|
rustls-native-certs is distributed under the following three licenses:
|
|
|
|
- Apache License version 2.0.
|
|
- MIT license.
|
|
- ISC license.
|
|
|
|
These are included as LICENSE-APACHE, LICENSE-MIT and LICENSE-ISC
|
|
respectively. You may use this software under the terms of any
|
|
of these licenses, at your option.
|