ADR#0015: Rust TLS Library
Context
First-party Rust code needs one default TLS implementation for both the client side (outbound HTTP, WebSocket, and other network clients) and the server side (in-process HTTPS listeners). Without one default, TLS choices drift across crates: some link OpenSSL through native-tls, others link rustls, and a single process can end up with two independent TLS stacks, two certificate-trust models, and two sets of security advisories to track.
The Rust ecosystem offers two mainstream backends:
- rustls is a pure-Rust TLS implementation. It is memory-safe by construction, stewarded by the Internet Security Research Group (ISRG) (the nonprofit behind Let's Encrypt) under its Prossimo memory-safety program, and has been through independent third-party security audits. Its default cryptographic provider is aws-lc-rs, which offers a FIPS 140-3 validated mode;
ringis available as an alternative provider. - OpenSSL (reached through
native-tlsor theopensslcrate) is battle tested and ubiquitous, but it is C code with a long history of memory-safety CVEs, and it introduces a systemlibssldependency into the build and runtime image.
The workspace has already converged on rustls in practice. reqwest, tokio-tungstenite, twilight-gateway, and opentelemetry-otlp are all configured with their rustls feature sets, and rustls-pemfile, rustls-pki-types, and rustls-webpki are pinned as workspace dependencies. No first-party crate depends on native-tls or openssl.
ADR#0002 makes shared cross-cutting concerns the responsibility of dedicated reusable packages, and ADR#0007 and ADR#0008 establish the pattern of naming one default technology and treating anything else as a documented exception.
Decision
Prefer rustls as the TLS implementation for first-party Rust code unless there is a strictly necessary reason to use something else.
- Use rustls for both client and server TLS. For HTTP clients such as
reqwest, enable therustls-tlsfeature family rather than anynative-tlsor OpenSSL feature. - Prefer the aws-lc-rs cryptographic provider for rustls, so that a FIPS 140-3 validated path stays available for future compliance requirements without a library change. Use the
ringprovider only when a target platform or build constraint cannot support aws-lc-rs. - For in-process HTTPS on an
axumservice, useaxum-serverwith itstls-rustlsfeature. It consumes the existingaxum::Routerdirectly and provides certificate hot-reload, which keeps rotation off the critical path. - Load certificates and keys with the already-pinned rustls tooling (
rustls-pemfile,rustls-pki-types,rustls-webpki) rather than introducing a parallel parsing stack. - Do not introduce
native-tls, theopensslcrate, or a vendor TLS SDK as the primary TLS boundary when rustls can satisfy the requirement.
Amended 2026-10-30: the workspace has one rustls crypto provider, aws-lc-rs. async-nats is built with its
aws-lc-rsfeature instead ofring. Third-party crates such as reqwest, hyper-rustls and bollard can still compileringinto the same rustls, and rustls panics rather than choose between two compiled-in providers, so the provider is installed rather than inferred:trogon_nats::connectinstalls aws-lc-rs as the process default, idempotently, before it builds a TLS configuration, and binaries do not install providers themselves. See ADR#0081.
Prefer terminating TLS at the deployment edge (ingress, load balancer, or service mesh) when the platform provides it, so that certificate lifecycle and cipher policy stay centralized. In-process TLS is the deliberate exception, for when the deployment does not terminate TLS in the path, when end-to-end encryption with no plaintext hop is required, or when a compliance requirement demands encryption into the process. When in-process TLS is used, it uses rustls per this decision.
Amended 2026-10-30: for NATS clients, in-process TLS is the norm rather than the exception. Every NATS connection terminates TLS in the client process, and no sidecar or service mesh is assumed, because nats-server needs the client's own certificate for
verify: trueand for the auth callout's certificate scheme, and because deployments such as the compose stack have no mesh. See ADR#0081.
Exceptions
Using something other than rustls requires a concrete constraint, not a preference. Valid exceptions include:
- A required dependency only exposes a
native-tlsor OpenSSL interface and offers no rustls-backed option. - A compliance or certification requirement mandates a specific validated OpenSSL module that the rustls plus aws-lc-rs path cannot satisfy.
- Interoperability with a peer requires a cipher suite, protocol extension, or legacy TLS behavior that rustls does not support.
- A target platform or build environment cannot support any available rustls cryptographic provider.
When an exception is used, isolate the non-rustls TLS to the boundary that requires it, and document the exception at that package, service, or deployment boundary. Do not let it become the default for unrelated code.
Consequences
- A single process and build graph carries one TLS implementation and one certificate-trust model, not two.
- First-party binaries avoid a system
libssldependency, which reduces image size, attack surface, and OS-level OpenSSL patching for those binaries. - Code review should reject new
native-tlsoropensslfeatures on first-party crates unless they satisfy the exception rules and are documented. - The pinned
rustls-*workspace dependencies remain the shared toolkit for certificate handling. - Choosing aws-lc-rs as the default provider keeps a FIPS 140-3 validated path open without a later library migration.
- Existing non-rustls TLS usage, if any is introduced through a dependency, can be migrated to rustls when touched for related work.
References
- ADR#0002: Rust Crate Boundaries
- ADR#0007: Configuration Sources
- ADR#0008: OpenTelemetry Observability
- rustls
- ISRG Prossimo: rustls initiative
- Internet Security Research Group (ISRG)
- Let's Encrypt
- aws-lc-rs
- ring
- axum
- axum-server
- reqwest
- tokio-tungstenite
- twilight-gateway
- opentelemetry-otlp
- rustls-pemfile
- rustls-pki-types
- rustls-webpki
- native-tls
- openssl (crate)
- OpenSSL
- NIST FIPS 140-3
- NIST Cryptographic Module Validation Program (CMVP)
