Git Product home page Git Product logo

rustls-native-certs's Introduction

Logo

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 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 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 crate is used to access the keystore APIs.
  • On Linux and other UNIX-like operating systems, the 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.

rustls Documentation

Release history:

  • 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:

pub fn load_native_certs() -> Result<Vec<Certificate>, std::io::Error>

On success, this returns a Vec<Certificate> 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.

Should I use this or webpki-roots?

(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:

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.

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 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-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 or were removed for mississuance.
  • 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.

rustls-native-certs's People

Contributors

alex avatar ctz avatar djc avatar est31 avatar freaky avatar jsha avatar keruspe avatar pimterry avatar

Stargazers

 avatar  avatar

Watchers

 avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.