rustls-native-certs allows rustls to use the platform's native certificate store when operating as a TLS client.
This is supported on Windows, macOS and Linux:
- On Windows, certificates are loaded from the system certificate store.
schannelcrate 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-frameworkcrate is used to access the keystore APIs.
- On Linux and other UNIX-like operating systems, the
openssl-probecrate is used to discover the filename of the system CA bundle.
rustls-native-certs is currently in development.
If you'd like to help out, please see CONTRIBUTING.md.
- 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.
This library exposes a single function with this signature:
pub fn load_native_certs() -> Result<rustls::RootCertStore, (Option<rustls::RootCertStore>, std::io::Error)>
On success, this returns a
rustls::RootCertStore loaded with a
snapshop of the root certificates found on this platform. This
function fails in a platform-specific way, expressed in a
When an error is returned, optionally a
rustls::RootCertStore is also
returned containing the certificates which could be loaded. This means
callers can opt-in to "best-effort" behaviour even in the presence of invalid
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.
Should I use this or
(Background: 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:
- 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.
- The OS certificate store is occasionally "attacked" by malware or just bad software.
- 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-certificatespackage 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 or were removed for mississuance.
- You may prefer to insulate yourself against local configuration for support or (perhaps inadvisable) security reasons.
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.