TLS backends

Active contributors: yuchen, ewang, andrew

Purpose

Pingora supports four TLS backends behind a thin shim. Each is a separate workspace crate. They are mutually exclusive cargo features at the umbrella-crate level: openssl, boringssl, s2n, rustls. The choice happens at compile time.

The four crates

Crate	TLS library	Notes
pingora-openssl	openssl	Production-grade, well-tested, requires native OpenSSL + Perl 5 to build
pingora-boringssl	boring	FIPS-capable, requires Clang to build
pingora-rustls	rustls	Pure-Rust, "Highly Experimental" per pingora/Cargo.toml
pingora-s2n	s2n-tls	AWS s2n-tls bindings

Each crate is small (a lib.rs plus an ext.rs of helpers, ~5–10K lines of source). The heavy lifting happens in the upstream TLS library; these crates are glue.

Directory layout (per crate)

pingora-{openssl,boringssl,rustls,s2n}/src/
├── lib.rs              Re-exports + crate-specific configuration
└── ext.rs              Pingora-specific extensions: keylog, SNI helpers, ...

pingora-boringssl additionally has boring_tokio.rs — its own integration with tokio because the boring crate doesn't ship a tokio adapter.

Key abstractions

The user-facing surface is mostly in pingora-core's TLS shim:

Type	File	What it is
TlsAcceptCallbacks	pingora-core/src/listeners/tls/mod.rs	Server-side TLS configuration
TlsConnect	pingora-core/src/connectors/tls/mod.rs	Client-side TLS dialer
SslDigest, SslDigestExtensions	pingora-core/src/protocols/tls/digest.rs	Per-connection TLS info reported in proxy phases

Each backend crate exposes its native types (SslContext, ServerConfig, etc.) for advanced configuration. Most code paths in pingora-core go through the shim and don't care which backend is active.

How it works

graph TD
    user[User code]
    pcore[pingora-core/src/tls<br/>thin dispatch shim]
    feat{Feature gate}
    op[pingora-openssl]
    bo[pingora-boringssl]
    ru[pingora-rustls]
    s2n[pingora-s2n]
    user --> pcore
    pcore --> feat
    feat -->|openssl| op
    feat -->|boringssl| bo
    feat -->|rustls| ru
    feat -->|s2n| s2n

pingora-core/src/tls, connectors/tls/, listeners/tls/, protocols/tls/ each contain a small dispatch layer that picks a backend at compile time via #[cfg(feature = "openssl")] etc. End-user code rarely cares which backend is in use.

The mTLS extension HttpProxy::new_mtls (added in 0.7.0) takes a client cert + key and configures the upstream connector to present them. SSLKEYLOGFILE support for rustls landed in 0.7.0 to make Wireshark debugging possible.

Integration points

• Pingora's HTTP/2 implementation uses ALPN through the backend's API; pingora-s2n/src/ext.rs had to handle ALPN explicitly via custom code (commit b370102).
• The s2n_config_cache_size YAML key (s2n-tls only) controls the size of an internal LRU cache of s2n_config objects.

Choosing a backend

• OpenSSL — the default for most users. Mature, broadly compatible.
• BoringSSL — pick this if you need FIPS or to match Cloudflare's production. Build complexity higher.
• rustls — pick this if you can't have native dependencies. Read the warning twice. The codebase explicitly says "don't rely on it (yet)".
• s2n-tls — pick this if you specifically want AWS's TLS implementation (e.g. to align with other AWS-using infrastructure).

Entry points for modification

• TLS-backend-specific changes → the relevant pingora-{name} crate.
• Cross-backend changes → pingora-core/src/tls, connectors/tls/, listeners/tls/. Watch for #[cfg(feature = "...")].

Key source files

File	Purpose
pingora-openssl/src/lib.rs	OpenSSL re-exports
pingora-openssl/src/ext.rs	OpenSSL extensions
pingora-boringssl/src/lib.rs	BoringSSL re-exports
pingora-boringssl/src/ext.rs	BoringSSL extensions
pingora-boringssl/src/boring_tokio.rs	tokio integration for boring
pingora-rustls/src/lib.rs	rustls re-exports + ext
pingora-s2n/src/lib.rs	s2n re-exports
pingora-core/src/tls/	Backend-dispatch shim
pingora-core/src/connectors/tls/	Outbound TLS
pingora-core/src/listeners/tls/	Inbound TLS
pingora-core/src/protocols/tls/	TLS stream abstraction