Skip to main content

Crate rustls_extra_roots

Crate rustls_extra_roots 

Source
Expand description

The built-in Mozilla roots, plus a corporate CA bundle the environment names.

A program that makes outbound TLS connections from inside a corporate network usually needs two things trusted at once: the public certificate authorities, and whichever internal CA the network’s inspecting proxy presents. This crate is the twenty lines that combine them, plus the three rules that turn out to matter.

§Three rules worth knowing first

The bundle is additional, not a replacement. The variable is spelled SSL_CERT_FILE by default, and OpenSSL gives that name the opposite meaning: setting it there replaces the default trust store. Here it adds to it, because a corporate CA is issued alongside the public ones rather than instead of them. If that is not the meaning you want, name a different variable — see ExtraRoots::from_variable — but be deliberate about it. A deployment that set SSL_CERT_FILE expecting OpenSSL’s meaning gets a larger trust set than it intended, never a smaller one: the safe direction to be wrong in, but still worth knowing.

A configured bundle that cannot be used is fatal. Not a warning. Silently falling back to the default roots is how a certificate problem becomes a TLS handshake failure three hops away, in a different service, hours later. If the operator said to load a file, and the file cannot be loaded, validate_at_startup says so and the process should not start. Every error names the file, because “invalid certificate” with no path is the least useful message a deployment can fail with.

Blank is absent. SSL_CERT_FILE="" means the variable was not set. A templated container definition whose source was empty produces exactly that, and reading it as “load the file named empty string” fails a service for a reason nobody can see in the definition.

§Why not something that already exists

webpki-roots compiles the Mozilla set in and offers no way to extend it. rustls-native-certs reads the operating system’s store, which is a different thing: it replaces the Mozilla set with the host’s, and in a distroless or scratch container there is no host store to read. webpki-roots-patcher solves the same problem with LD_PRELOAD. What is missing is the boring middle: compiled-in roots, plus one file, from inside the process.

§Examples

The usual call. With no bundle configured this is the Mozilla root set:

let roots = rustls_extra_roots::root_store().expect("no bundle is configured here");
assert!(!roots.is_empty());

Checking a specific file, which is what the startup check does:

use std::path::Path;

let error = rustls_extra_roots::root_store_from(Some(Path::new("/nonexistent.pem")))
    .expect_err("the file is not there");

assert!(error.to_string().contains("/nonexistent.pem"));

Under a different variable name, for a program that already means something else by SSL_CERT_FILE:

use rustls_extra_roots::ExtraRoots;

let roots = ExtraRoots::from_variable("CORPORATE_CA_BUNDLE")
    .root_store()
    .expect("nothing is configured under that name here");

§Crypto providers

root_store and friends need no crypto provider: assembling a trust store is not a cryptographic operation. client_config does, because rustls reads the process-default provider to pick cipher suites — this crate deliberately selects none, so either install one (CryptoProvider::install_default, or enable ring / aws-lc-rs on your own rustls dependency) or call client_config_with_provider to be explicit.

Structs§

ExtraRoots
Which environment variable names the bundle.

Enums§

ConfigError
Why a client configuration could not be built.
TrustError
Why the trust roots could not be assembled.

Constants§

DEFAULT_VARIABLE
The environment variable consulted when no other name is given.

Functions§

bundle_from_value
The blank-is-absent rule, separated from the environment that carries it.
client_config
A client configuration trusting root_store, with no client certificate.
client_config_with_provider
A client configuration trusting bundle in addition to the built-in roots, using an explicitly supplied crypto provider.
configured_bundle
The bundle DEFAULT_VARIABLE names, if it names one.
root_store
Trust roots: the built-in set, plus whatever DEFAULT_VARIABLE names.
root_store_from
Trust roots: the built-in set, plus bundle if given.
startup_check
The startup check against DEFAULT_VARIABLE, logged, as a single call a main can branch on.
validate_at_startup
Fail now if a bundle configured under DEFAULT_VARIABLE is unusable.