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§
- Extra
Roots - Which environment variable names the bundle.
Enums§
- Config
Error - Why a client configuration could not be built.
- Trust
Error - 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
bundlein addition to the built-in roots, using an explicitly supplied crypto provider. - configured_
bundle - The bundle
DEFAULT_VARIABLEnames, if it names one. - root_
store - Trust roots: the built-in set, plus whatever
DEFAULT_VARIABLEnames. - root_
store_ from - Trust roots: the built-in set, plus
bundleif given. - startup_
check - The startup check against
DEFAULT_VARIABLE, logged, as a single call amaincan branch on. - validate_
at_ startup - Fail now if a bundle configured under
DEFAULT_VARIABLEis unusable.