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.
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 ExtraRoots;
let roots = from_variable.root_store?;
# Ok::
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.