rustls-extra-roots 0.1.0

Trust the built-in Mozilla roots plus an additional PEM bundle named by an environment variable — additive, not replacing, and fatal when the bundle cannot be used.
Documentation

rustls-extra-roots

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.

fn main() -> std::process::ExitCode {
    // Refuse to start if SSL_CERT_FILE names a bundle that cannot be used.
    if !rustls_extra_roots::startup_check() {
        return std::process::ExitCode::FAILURE;
    }

    let roots = rustls_extra_roots::root_store().unwrap();
    // ... hand `roots` to rustls ...
    std::process::ExitCode::SUCCESS
}

Three rules

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 — but be deliberate about it.

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. Every error names the file, because "invalid certificate" with no path is the least useful message a deployment can fail with. A file of only a private key — the plausible operator mistake — counts as unusable.

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

What it does Why it is not this
webpki-roots Compiles the Mozilla set in No way to extend it
rustls-native-certs Reads the OS trust store Replaces the Mozilla set; a distroless or scratch container has no store to read
webpki-roots-patcher Patches roots into a binary Needs LD_PRELOAD around the process

What is missing is the boring middle: compiled-in roots, plus one file, from inside the process.

A different variable name

use rustls_extra_roots::ExtraRoots;

let roots = ExtraRoots::from_variable("CORPORATE_CA_BUNDLE").root_store()?;
# Ok::<(), rustls_extra_roots::TrustError>(())

Crypto providers

root_store() and friends need no crypto provider: assembling a trust store is not a cryptographic operation, and this crate selects none.

client_config() does, because rustls reads the process-default provider to pick cipher suites. 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 — which is the right choice from inside a library.

Features

  • tracing (default) — two log lines, both about why a process is or is not starting. Optional because a library should not conscript a caller into a log facade; on by default because a silent failure here is the thing this crate exists to prevent.

License

MIT or Apache-2.0, at your option.