Skip to content

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:

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 the rustls-tls feature family rather than any native-tls or 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 ring provider only when a target platform or build constraint cannot support aws-lc-rs.
  • For in-process HTTPS on an axum service, use axum-server with its tls-rustls feature. It consumes the existing axum::Router directly 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, the openssl crate, 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-rs feature instead of ring. Third-party crates such as reqwest, hyper-rustls and bollard can still compile ring into the same rustls, and rustls panics rather than choose between two compiled-in providers, so the provider is installed rather than inferred: trogon_nats::connect installs 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: true and 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-tls or 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 libssl dependency, which reduces image size, attack surface, and OS-level OpenSSL patching for those binaries.
  • Code review should reject new native-tls or openssl features 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 ​

Released under the Apache License 2.0.