TLS

QUIC/TLS 1.3 for HTTP/3 lives in hopf-quic and is PQC-first (TLS 1.3 only, hybrid X25519MLKEM768 offered first) — it also runs on the same in-tree AWS-LC foundation, with no separate TLS record layer (QUIC packet protection replaces it). This page covers TCP TLS (1.2 + 1.3, same crypto provider and key-exchange policy).

Standards

Full requirement-by-requirement status, including gaps: Conformance → TLS.

Architecture

TcpListenerConfig / TcpConnectorConfig
        │  SharedTlsAcceptor / SharedTlsConnector   (hopf-core::tls::pem)
        ▼
TlsVariant::V13(TlsRecordEngine)        — HandshakeEngine + TLS 1.3 record layer
TlsVariant::V12(Tls12RecordEngine)      — tls12::Tls12Engine + TLS 1.2 record layer
TlsVariant::Negotiating(..)             — buffers the first flight, picks 1.3 or 1.2, then delegates
        │  driven via TlsRecordSink (TcpConnection is the sink)
        ▼
Endpoint  →  ProtocolHandler sees plaintext
             security_info() after handshake

There is no separate adapter crate in this path: PemAcceptor / SniAcceptor / TrustedConnector and their TLS-1.2 counterparts (private types in hopf-core/src/tls/pem.rs) implement the crate's own TlsAcceptor / TlsConnector traits directly; the PEM helper functions just return them as Arc<dyn TlsAcceptor> / Arc<dyn TlsConnector> (SharedTlsAcceptor / SharedTlsConnector).

TlsVariant is a thin enum, not a trait object: V13 wraps TlsRecordEngine (tls/record.rs), which frames HandshakeEngine's (tls/engine.rs) handshake messages into TLS 1.3 records and does the AEAD sealing/opening; V12 wraps tls12::Tls12RecordEngine (tls/tls12/record.rs) around tls12::Tls12Engine (tls/tls12/engine.rs) the same way for TLS 1.2/RFC 5246. Both record engines expose the same method set and consume the same TlsRecordSink, so TcpConnection pumps whichever one it got without caring which version is underneath.

The default PEM builders (acceptor_from_pem / connector_from_pem) produce TlsVariant::Negotiating: the server buffers the first flight until a complete ClientHello is seen, inspects its supported_versions (falling back to the legacy version field) to pick 1.3 or 1.2 (preferring 1.3), materializes the matching engine, and replays the buffered bytes into it — the same approach on the client side, keyed off the first ServerHello. One TCP connection speaks exactly one version for its life; there is no mid-connection renegotiation. Pin a fixed version with *_with_tcp_version_policy or the *_tls12 builders instead of negotiating. Credentials generated at run time (an ephemeral loopback CA, a test fixture) need no files: server_credentials_from_pem_bytes parses PEM from memory and acceptor_from_credentials / acceptor_from_credentials_with_client_auth build the acceptor from the resulting ServerCredentials, the latter verifying client certificates against DER CA certificates handed in directly.

hopf-core::dtls and hopf-core::dtls12 reuse this same HandshakeEngine / tls12::Tls12Engine machinery over UDP with their own DTLS record/reassembly layer and a parallel DtlsVersionPolicy — see Architecture → Security substrate and Limitations below; they are not reachable through this page's TlsAcceptor/TlsConnector/TlsVariant types.

Public API

use std::path::Path;
use hopf_core::{
    acceptor_from_pem, connector_from_pem, server_credentials_from_pem,
    acceptor_from_pem_with_client_auth, connector_from_pem_with_client_cert,
    ClientAuthPolicy,
};

// Server
let acceptor = acceptor_from_pem(
    Path::new("cert.pem"),
    Path::new("key.pem"),
    &[b"h2", b"http/1.1"],
)?;

// Client
let connector = connector_from_pem(Path::new("ca.pem"), &[b"h2", b"http/1.1"])?;

// Mutual TLS: server requires a client certificate, verified against client_roots.pem.
let acceptor = acceptor_from_pem_with_client_auth(
    Path::new("cert.pem"), Path::new("key.pem"),
    &[b"h2", b"http/1.1"], ClientAuthPolicy::Require,
    Path::new("client_roots.pem"),
)?;
// ClientAuthPolicy::Request is opportunistic mTLS — check
// SecurityInfo::peer_certificate_fingerprint() to see whether a client cert
// was actually presented on a given connection.

// Client side: present an identity certificate for mTLS.
let connector = connector_from_pem_with_client_cert(
    Path::new("ca.pem"), Path::new("client-cert.pem"), Path::new("client-key.pem"), &[],
)?;

Virtual hosting (SNI)

use hopf_core::{acceptor_from_pem_with_sni, server_credentials_from_pem};

// One listener, one cert per hostname, dispatched by client SNI.
// `default_cert_path`/`default_key_path` back an unmatched or absent SNI.
let b_creds = server_credentials_from_pem(Path::new("b-cert.pem"), Path::new("b-key.pem"))?;
let acceptor = acceptor_from_pem_with_sni(
    Path::new("a-cert.pem"), Path::new("a-key.pem"),
    [("b.example.com".to_string(), b_creds)],
    &[b"h2", b"http/1.1"],
)?;
// A hostname with no matching entry (or no SNI at all) falls back to the
// default credentials rather than failing the handshake.

Sessions support send_close_notify via TlsVariant's inherent methods, driven the same way on both TLS versions.

Configuration

The PEM builders take no numeric knobs beyond what's listed below; everything else is a fixed, spec-conformant default. Key exchange always prefers the hybrid post-quantum group X25519MLKEM768 when the peer supports it, falling back through SecP256r1MLKEM768 / SecP384r1MLKEM1024 to classical curves — this isn't a caller-adjustable setting via the PEM helpers. QUIC uses the same crypto provider but pins TLS 1.3, so every QUIC handshake is PQC-first with no 1.2 fallback.

Cargo features

None. hopf-core::tls is always built in — it's not gated behind a feature flag.

Wiring listeners and connectors

use hopf_core::TcpListenerConfig;

// TLS-from-accept (HTTPS, implicit FTPS/SMTPS, …)
let cfg = TcpListenerConfig::new(addr, factory)
    .with_tls(acceptor);

// Cleartext first, then STARTTLS (SMTP, explicit FTPS, …)
let cfg = TcpListenerConfig::new(addr, factory)
    .with_starttls_acceptor(acceptor);

Client dial:

use hopf_core::TcpConnectorConfig;

let cfg = TcpConnectorConfig::new(addr, factory)
    .with_tls(connector, "server.example.com");

Protocol crates:

• FTP — FtpConfig::with_tls / implicit_ftps
• SMTP — SmtpConfig::with_tls / implicit_tls
• HTTP — AlpnHttpEndpoint after TLS ALPN
• Cookbook: TLS echo

SecurityInfo

After handshake, Endpoint::security_info() reports (via core SecurityInfo): secure flag, ALPN protocol, TLS protocol version, cipher suite, the SNI hostname the peer requested (sni(), server side), and — when mTLS presented a client certificate — its SHA-256 fingerprint as lowercase hex (peer_certificate_fingerprint()) and full certificate chain (peer_certificate_chain()), server side. Handlers may gate AUTH or HTTP/2 on this metadata (ProtocolHandler::security_established). The fingerprint is the cert_key expected by SASL EXTERNAL's CredentialStore::authenticate_certificate.

Examples

cargo run -p tls-echo -- 127.0.0.1:8443 cert.pem key.pem

See Cookbook: TLS echo. No environment variables.

Limitations

• insecure_connector / insecure_connector_tls12 perform no validation at all — opportunistic STARTTLS only, never where the peer's identity matters.
• Hybrid PQC key-exchange preference is fixed (hybrid-first) — not customizable via the PEM builders.
• Session tickets aren't wired into the simple PEM builders; enabling resumption means constructing a HandshakeConfig/Tls12Config directly.
• RFC 8446 §4.1.3's downgrade sentinel is not implemented on the negotiating client's 1.2-fallback path.
• record_size_limit (RFC 8449) is TLS 1.3 only — the TLS 1.2 engine neither sends nor answers it.
• Encrypted Client Hello is shared-mode only (no split-mode backend), and a real ECH offer does not support session resumption or 0-RTT.
• QUIC crypto is configured in hopf-quic, not here (though it shares this module's AWS-LC provider and key-exchange policy).
• No DTLS through this page's types. DTLS 1.2 and DTLS 1.3 (RFC 6347 / RFC 9147) are implemented — hopf-core::dtls / dtls12, reusing this same handshake engine over a UDP driver with per-peer version negotiation — but as a low-level seam only, not yet exposed through the generic Endpoint/ProtocolHandler contract or through this page's TlsAcceptor/TlsConnector/TlsVariant types. See Conformance → TLS and Architecture → Security substrate.

Independent verification

Production TCP TLS is entirely hopf-core::tls as described above. The workspace additionally runs socket-level interop tests that complete real handshakes against rustls (TLS 1.3 and 1.2, both roles, ALPN, mTLS, resumption, STARTTLS) so wire behaviour is checked against a second implementation, not only Hopf-to-Hopf loops. DTLS gets a separate real-peer suite (OpenSSL). Status tables: Conformance → TLS.

GitHub