Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

QUIC MITM across changing flows

A QUIC connection can outlive the UDP flow that first carried it. Transparent proxies may receive a new platform flow when an application changes its socket. Migration routing joins that flow to its original connection; independent client connections keep independent endpoints, relays and origin connections.

flowUDP / platform flowadmissionSource admissionflow->admissionpeekClientHello inspector + migration routeradmission->peekpolicyInspection + policypeek->policynew connectionknownExisting dedicated endpointpeek->knownknown CID + destinationfreshNew dedicated endpoint + MITM relaypolicy->freshinterceptforwardforwardpolicy->forwardforward unchangedvalidateAuthenticate packet + validate pathknown->validaterelayExisting connection + relayvalidate->relay

QuicMitmIngress connects the ClientHello inspector with the MITM relay. It routes a new platform flow back to an existing connection when the original destination and connection identifier match. Ordinary traffic stays on that connection’s dedicated endpoint. A match is only a routing hint: QUIC must still authenticate the packet and validate the path. Rejected known traffic is dropped, never forwarded to another origin.

Keep registries within a trusted policy identity, such as one process generation or one authenticated tunnel tenant. QuicMitmIngressByIdentity manages these isolated registries; unknown identities must remain isolated too. Apply source admission before routing, including to known-CID flows, to bound path churn. The logical connection and its admission guards must outlive the individual platform flows that carry it.

Bounds and flow lifetime

Registration budgets limit migration bookkeeping, separately from flow admission. At capacity, new connections can still use independent endpoints, but cannot migrate between platform flows. Existing registrations remain available until their connections close. Path budgets apply per connection, so an interface change can move many connections at once. Use telemetry to see whether these budgets fit your workload and when capacity pressure disables migration support.

One platform association carries one intercepted connection. A second handshake on its active tuple is refused; supporting several independent connections on that tuple needs a different transport arrangement. Obsolete paths can be retired, but the authenticated current path is protected. Reusing that active tuple remains subject to its original flow lifetime.

Ingress and egress move independently

A client’s port change usually leaves the origin-facing connection alone. A network or policy change can require reassessing either side. QuicMigrationLayer makes that decision explicit: keep a path, refresh its transport information, or replace its transport. QuicEgressMigration adapts a replacement-socket factory to this policy, or replaces egress through the original connector and connect request with QuicEgressMigration::from_connector. New ingress flows join their existing connection through the router; egress changes remain subject to QUIC’s migration constraints.

Network observations are hints, not proof that a particular connection failed. Both QUIC migration and UDP forwarding recovery subscribe to the same rama::net::availability::NetworkChanges source, which carries a routing revision and whether the network is available, unavailable or unknown; an unknown network never prepares a replacement. Reuse the original connector and its policy restrictions when preparing a replacement. Bound concurrent preparations during network-wide changes, set decision deadlines, and choose whether a failed preparation preserves the connection or closes it. Newer observations supersede unfinished work.

The Apple example uses provider network-path observations to reassess egress when connectivity returns. An ingress port change alone does not replace egress. Physical interface changes and recovery still need platform testing.

Forwarding without interception

Pass-through keeps QUIC end-to-end between the client and origin. Those peers validate migration; Rama only forwards their datagrams. If a proxy network change makes its outgoing UDP transport unusable, an opt-in recovering forwarding bridge can prepare a replacement through the original connector while keeping the incoming flow alive. It preserves the original peer and routing restrictions. Datagrams in flight may be lost, never replayed.

The Apple example enables this recovery for confirmed QUIC pass-through, sharing network observations and the preparation budget with MITM. Its uninspectable fallback and generic multi-peer UDP handler retain their existing behaviour: arbitrary UDP protocols need an explicit decision about source-address changes. Recovery cannot guarantee continuity during an incomplete QUIC handshake or after the real endpoints have closed their connection.

See the UDP forwarding API reference for recovery controls and failure policies.

See the migration API reference and telemetry reference for configuration and event details. The conditional QUIC MITM example and Apple transparent-proxy example show how the layers fit into a complete proxy.

The model follows QUIC path validation and migration, MsQuic’s distinct local/peer address events, and Apple’s network path observations.