QUIC-Aware Proxying Using HTTP

1.1. Conventions and Definitions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

1.2. Terminology

This document uses the following terms:¶

• Client: the client of all QUIC connections discussed in this document.¶

• Proxy: the endpoint that responds to the UDP proxying request.¶

• Target: the server that a client is accessing via a proxy.¶

• Client <-> Proxy HTTP stream: a single HTTP stream established from the client to the proxy.¶

• Socket: a UDP 4-tuple (local IP address, local UDP port, remote IP address, remote UDP port). In some implementations, this is referred to as a "connected" socket.¶

• Client-facing socket: the socket used to communicate between the client and the proxy.¶

• Target-facing socket: the socket used to communicate between the proxy and the target.¶

• Client Connection ID: a QUIC Connection ID that is chosen by the client, and is used in the Destination Connection ID field of packets from the target to the client.¶

• Target Connection ID: a QUIC Connection ID that is chosen by the target, and is used in the Destination Connection ID field of packets from the client to the target.¶

• Virtual Client Connection ID: a fake QUIC Connection ID that is chosen by the client that the proxy MUST use when sending QUIC packets in forwarded mode.¶

• Virtual Target Connection ID: a fake QUIC Connection ID that is chosen by the proxy that the client MUST use when sending QUIC packets in forwarded mode.¶

• Packet Transform: the procedure used to modify packets before they enter the client-proxy link.¶

1.3. Virtual Connection IDs

QUIC allows each endpoint of a connection to choose the connection IDs it receives with. Servers receiving QUIC packets can employ load balancing strategies such as those described in [QUIC-LB] that encode routing information in the connection ID. When operating in forwarded mode, clients send QUIC packets destined for the Target directly to the Proxy. Since these packets are generated using the Target Connection ID, load balancers would not be able to route packets to the correct Proxy if the packets were sent with the Target Connection ID. The Virtual Target Connection ID is a connection ID chosen by the Proxy that the Client uses when sending forwarded mode packets. The Proxy replaces the Virtual Target Connection ID with the Target Connection ID prior to forwarding the packet to the Target.¶

Similarly, QUIC requires that connection IDs aren't reused over multiple network paths to avoid linkability. The Virtual Client Connection ID is a connection ID chosen by the Client that the Proxy uses when sending forwarded mode packets. The Proxy replaces the Client Connection ID with the Virtual Client Connection ID prior to forwarding the packet to the Client. Clients take advantage of this to avoid linkability when migrating a client to proxy network path. The Virtual Client Connection ID allows the connection ID bytes to change on the wire without requiring the connection IDs on the client to target connection change.¶

Clients and Proxies not implementing forwarded mode do not need to consider Virtual Connection IDs since all Client<->Target datagrams will be encapsulated within the Client<->Proxy connection.¶

2.1. Stream Mapping

Each client <-> proxy HTTP stream MUST be mapped to a single target-facing socket.¶

(Client <-> Proxy HTTP Stream) => Target-facing socket

Multiple streams can map to the same target-facing socket, but a single stream cannot be mapped to multiple target-facing sockets. Each stream MUST also be associated with a single Packet Transform.¶

This mapping guarantees that any HTTP Datagram using a stream sent from the client to the proxy in tunnelled mode can be sent to the correct target.¶

2.2. Virtual Target Connection ID Mapping

Each pair of Virtual Target Connection ID and client-facing socket MUST map to a single target-facing socket and Target Connection ID.¶

(Client-facing socket + Virtual Target Connection ID)
    => (Target-facing socket + Target Connection ID)

Multiple pairs of Connection IDs and client-facing sockets can map to the same target-facing socket.¶

This mapping guarantees that any QUIC packet containing the Virtual Target Connection ID sent from the client to the proxy in forwarded mode can be sent to the correct target with the correct Target Connection ID. Thus, a proxy that does not allow forwarded mode does not need to maintain this mapping.¶

2.3. Client Connection ID Mappings

Each pair of Client Connection ID and target-facing socket MUST map to a single stream on a single client <-> proxy HTTP stream. Additionally, when supporting forwarded mode, the pair of Client Connection ID and target-facing socket MUST map to a single client-facing socket and Virtual Client Connection ID.¶

(Target-facing socket + Client Connection ID) => (Client <-> Proxy HTTP Stream)
(Target-facing socket + Client Connection ID)
    => (Client-facing socket + Virtual Client Connection ID)

Multiple pairs of Connection IDs and target-facing sockets can map to the same HTTP stream or client-facing socket.¶

These mappings guarantee that any QUIC packet sent from a target to the proxy can be sent to the correct client, in either tunnelled or forwarded mode. Note that this mapping becomes trivial if the proxy always opens a new target-facing socket for every client request with a unique stream. The mapping is critical for any case where target-facing sockets are shared or reused.¶

2.4. Detecting Connection ID Conflicts

In order to be able to route packets correctly in both tunnelled and forwarded mode, proxies check for conflicts before creating a new mapping. If a conflict is detected, the proxy will reject the client's request, as described in Section 5.¶

Two sockets conflict if and only if all members of the 4-tuple (local IP address, local UDP port, remote IP address, and remote UDP port) are identical.¶

Two Connection IDs conflict if and only if one Connection ID is equal to or a prefix of another. For example, a zero-length Connection ID conflicts with all connection IDs. This definition of a conflict originates from the fact that QUIC short headers do not carry the length of the Destination Connection ID field, and therefore if two short headers with different Destination Connection IDs are received on a shared socket, one being a prefix of the other prevents the receiver from identifying which mapping this corresponds to.¶

The proxy treats two mappings as being in conflict when a conflict is detected for all elements on the left side of the mapping diagrams above.¶

Since very short Connection IDs are more likely to lead to conflicts, particularly zero-length Connection IDs, a proxy MAY choose to reject all requests for very short Connection IDs as conflicts, in anticipation of future conflicts.¶

2.5. Stateless Resets for Forwarded Mode QUIC Packets

While the lifecycle of forwarding rules are bound to the lifecycle of the client<->proxy HTTP stream, a peer may not be aware that the stream has terminated. If the above mappings are lost or removed without the peer's knowledge, they may send forwarded mode packets even though the Client or Proxy no longer has state for that connection. To allow the Client or Proxy to reset the client<->target connection in the absence of the mappings above, a stateless reset token corresponding to the Virtual Connection ID can be provided.¶

Consider a proxy that initiates closure of a client<->proxy QUIC connection. If the client is temporarily unresponsive or unreachable, the proxy might have considered the connection closed and removed all connection state (including the stream mappings used for forwarding). If the client never learned about the closure, it might send forwarded mode packets to the proxy, assuming the stream mappings and client<->proxy connection are still intact. The proxy will receive these forwarded mode packets, but won't have any state corresponding to the destination connection ID in the packet. If the proxy has provided a stateless reset token for the Virtual Target Connection ID, it can send a stateless reset packet to quickly notify the client that the client<->target connection is broken.¶

2.6. Stateless Resets from the Target

Reuse of target-facing sockets is only possible because QUIC connection IDs allow distinguishing packets for multiple QUIC connections received with the same 5-tuple. One exception to this is Stateless Reset packets, in which the connection ID is not used, but rather populated with unpredictable bits followed by a Stateless Reset token, to make it indistinguishable from a regular packet with a short header. In order for the proxy to correctly recognize Stateless Reset packets, the client SHOULD share the Stateless Reset token for each registered Target Connection ID. When the proxy receives a Stateless Reset packet, it can send the packet to the client as a tunnelled datagram. Although Stateless Reset packets look like short header packets, they are not technically short header packets and do not contain negotiated connection IDs, and thus are not eligible for forwarded mode.¶

4.1. New Proxied Connection Setup

To initiate QUIC-aware proxying, the client sends a REGISTER_CLIENT_CID capsule containing the initial Client Connection ID that the client has advertised to the target as well as a Virtual Connection ID that the proxy MUST use when sending forwarded mode packets. If forwarded mode is not supported, the Virtual Connection ID Length MUST be zero.¶

If the mapping is created successfully, the client will receive a ACK_CLIENT_CID capsule that contains the same Client Connection ID that was requested.¶

Since clients are always aware whether or not they are using a QUIC proxy, clients are expected to cooperate with proxies in selecting Client Connection IDs. A proxy detects a conflict when it is not able to create a unique mapping using the Client Connection ID (Section 2.4). It can reject requests that would cause a conflict and indicate this to the client by replying with a CLOSE_CLIENT_CID capsule. In order to avoid conflicts, clients SHOULD select Client Connection IDs of at least 8 bytes in length with unpredictable values. A client also SHOULD NOT select a Client Connection ID that matches the ID used for the QUIC connection to the proxy, as this inherently creates a conflict.¶

If the rejection indicated a conflict due to the Client Connection ID, the client MUST select a new Connection ID before sending a new request, and generate a new packet. For example, if a client is sending a QUIC Initial packet and chooses a Connection ID that conflicts with an existing mapping to the same target server, it will need to generate a new QUIC Initial.¶

4.2. Adding New Client Connection IDs

Since QUIC connection IDs are chosen by the receiver, an endpoint needs to communicate its chosen connection IDs to its peer before the peer can start using them. In QUICv1, this is performed using the NEW_CONNECTION_ID frame.¶

Prior to informing the target of a new chosen client connection ID, the client MUST send a REGISTER_CLIENT_CID capsule request containing the new Client Connection ID and Virtual Client Connection ID.¶

The client should only inform the target of the new Client Connection ID once an ACK_CLIENT_CID capsule is received that contains the echoed connection ID.¶

4.3. Sending With Forwarded Mode

Support for forwarded mode is determined by the "Proxy-QUIC-Forwarding" header, see Section 5.¶

Once the client has learned the target server's Connection ID, such as in the response to a QUIC Initial packet, it can send a REGISTER_TARGET_CID capsule containing the Target Connection ID to request the ability to forward packets.¶

The client MUST wait for an ACK_TARGET_CID capsule that contains the echoed connection ID and Virtual Target Connection ID before using forwarded mode.¶

Prior to receiving the proxy server response, the client MUST send short header packets tunnelled in HTTP Datagram frames. The client MAY also choose to tunnel some short header packets even after receiving the successful response.¶

If the Target Connection ID registration is rejected, for example with a CLOSE_TARGET_CID capsule, it MUST NOT forward packets to the requested Target Connection ID, but only use tunnelled mode. The request might also be rejected if the proxy does not support forwarded mode or has it disabled by policy.¶

QUIC long header packets MUST NOT be forwarded. These packets can only be tunnelled within HTTP Datagram frames to avoid exposing unnecessary connection metadata.¶

When forwarding, the client sends a QUIC packet with the Virtual Target Connection ID in the QUIC short header, using the same socket between client and proxy that was used for the main QUIC connection between client and proxy.¶

When forwarding, the proxy sends a QUIC packet with the Virtual Client Target Connection ID in the QUIC short header, using the same socket between client and proxy that was used for the main QUIC connection between client and proxy.¶

Prior to sending a forwarded mode packet, the sender MUST replace the Connection ID with the Virtual Connection ID. If the Virtual Connection ID is larger than the Connection ID, the sender MUST extend the length of the packet by the difference between the two lengths, to include the entire Virtual Connection ID. If the Virtual Connection ID is smaller than the Connection ID, the sender MUST shrink the length of the packet by the difference between the two lengths.¶

Clients and proxies supporting forwarded mode MUST be able to handle Virtual Connection IDs of different lengths than the corresponding Connection IDs.¶

4.4. Receiving With Forwarded Mode

If the client has indicated support for forwarded mode with the "Proxy-QUIC-Forwarding" header, the proxy MAY use forwarded mode for any Client Connection ID for which it has a valid mapping.¶

Once a client has sent "Proxy-QUIC-Forwarding" with a value of "?1", it MUST be prepared to receive forwarded short header packets on the socket between itself and the proxy for any Virtual Client Connection ID that it has registered with a REGISTER_CLIENT_CID capsule. The client uses the Destination Connection ID field of the received packet to determine if the packet was originated by the proxy, or merely forwarded from the target. The client replaces the Virtual Client Connection ID with the real Client Connection ID before processing the packet further.¶

4.5. Connection Maintenance in Forwarded Mode

When a client and proxy are using forwarded mode, it is possible that there can be long periods of time in which no ack-eliciting packets (see Section 2 of [QUIC-RETRANSMISSION]) are exchanged between the client and proxy. If these periods extend beyond the effective idle timeout for the client-to-proxy QUIC connection (see Section 10.1 of [QUIC]), the QUIC connection might be closed by the proxy if the proxy does not use forwarded packets as an explicit liveness signal. To avoid this, clients SHOULD send keepalive packets to the proxy before the idle timeouts would be reached, which can be done using a PING frame or another ack-eliciting frame as described in Section 10.1.1 of [QUIC].¶

5.1. Removing Mapping State

For any registration capsule for which the proxy has sent an acknowledgement, any mappings last until either endpoint sends a close capsule or the either side of the HTTP stream closes.¶

A client that no longer wants a given Connection ID to be forwarded by the proxy sends a CLOSE_CLIENT_CID or CLOSE_TARGET_CID capsule.¶

If a client's connection to the proxy is terminated for any reason, all mappings associated with all requests are removed.¶

A proxy can close its target-facing socket once all UDP proxying requests mapped to that socket have been removed.¶

5.2. Handling Connection Migration

If a proxy supports QUIC connection migration, it needs to ensure that a migration event does not end up sending too many tunnelled or proxied packets on a new path prior to path validation.¶

Specifically, the proxy MUST limit the number of packets that it will proxy to an unvalidated client address to the size of an initial congestion window. Proxies additionally SHOULD pace the rate at which packets are sent over a new path to avoid creating unintentional congestion on the new path.¶

When operating in forwarded mode, the proxy reconfigures or removes forwarding rules as the network path between the client and proxy changes. In the event of passive migration, the proxy automatically reconfigures forwarding rules to use the latest active and validated network path for the HTTP stream. In the event of active migration, the proxy removes forwarding rules in order to not send packets with the same connection ID bytes over multiple network paths. After initiating active migration, clients are no longer able to send forwarded mode packets since the proxy will have removed forwarding rules. Clients can proceed with tunnelled mode or can request new forwarding rules via REGISTER_CLIENT_CID and REGISTER_TARGET_CID capsules. Each of these capsules will contain new virtual connection IDs to prevent packets with the same connection ID bytes being used over multiple network paths. Note that the Client Connection ID and Target Connection ID can stay the same while the Virtual Target Connection ID and Virtual Client Connection ID change.¶

5.3. Handling ECN Marking

Explicit Congestion Notification marking [ECN] uses two bits in the IP header to signal congestion from a network to endpoints. When using forwarded mode, the proxy replaces IP headers for packets exchanged between the client and target; these headers can include ECN markings. Proxies SHOULD preserve ECN markings on forwarded packets in both directions, to allow ECN to function end-to-end. If the proxy does not preserve ECN markings, it MUST set ECN marks to zero on the IP headers it generates.¶

Forwarded mode does not create an IP-in-IP tunnel, so the guidance in [ECN-TUNNEL] about transferring ECN markings between inner and outer IP headers does not apply.¶

A proxy MAY additionally add ECN markings to signal congestion being experienced on the proxy itself.¶

6.1. The identify transform

The identity transform does not modify the packet in any way. When this transform is in use, a global passive adversary can trivially correlate pairs of packets that crossed the forwarder, providing a compact proof that a specific client was communicating to a specific target.¶

The identity transform is identified by the value "identity" Section 10.3.¶

Use of this transform is NOT RECOMMENDED if the scramble transform is supported by both the client and the proxy. Implementations MAY choose to not implement or support the identity transform, depending on the use cases and privacy requirements of the deployment.¶

6.2. The scramble transform

The scramble transform implements length-preserving unauthenticated re-encryption of QUIC packets while preserving the QUIC invariants. When the scramble transform is in use, a global passive adversary cannot simply compare the packet contents on both sides of the proxy to link the client and target. However, the scramble transform does not defend against analysis of packet sizes and timing, nor does it protect privacy against an active attacker.¶

Deployments that implement the version of the scramble transform defined in this document MUST use the value "scramble-dt". The finalized version is expected to use the reserved value "scramble" Section 10.3.¶

The scramble transform is initialized using a 32-byte random symmetric key. When offering or selecting this transform, the client and server each generate the key that they will use to encrypt scrambled packets and MUST add it to the Proxy-QUIC-Transform header in an sf-binary parameter named "scramble-key". If either side receives a scramble transform without the "scramble-key" parameter, forwarding mode MUST be disabled.¶

This transform relies on the AES-128 block cipher, which is represented by the syntax AES-ECB(key, plaintext_block) as in [RFC9001]. The corresponding decryption operation is written here as AES-ECB-inv(key, ciphertext_block). It also uses AES in Counter Mode ([SP800-38A], Section 6.5), which is represented by the syntax AES-CTR(key, iv, input) for encryption and decryption (which are identical). In this syntax, iv is an array of 16 bytes containing the initial counter block. The counter is incremented by the standard incrementing function ([SP800-38A], Appendix B.1) on the full block width.¶

In brief, the transform applies AES in counter mode (AES-CTR) using an initialization vector drawn from the packet, then encrypts the initialization vector with AES-ECB. The detailed procedure is as follows:¶

1. Let k1, k2 = scramble_key[:16], scramble_key[16:32].¶

2. Let L be the Connection ID length.¶

3. Let cid = packet[1:L+1], i.e., the Connection ID.¶

4. Let iv = packet[L+1:L+17], i.e., the 16 bytes following the Connection ID.¶

5. Let ctr_input = packet[0] | packet[L+17:].¶

6. Let ctr_output = AES-CTR(k1, iv, ctr_input).¶

7. Let header = ctr_output[0] & 0x7F. This ensures that the Header Form bit is zero, as required by the QUIC invariants ([RFC8999], Section 5.2).¶

8. Encrypt iv with the block cipher: encrypted_iv = AES-ECB(k2, iv).¶

9. Produce the output packet as:
   header | cid | encrypted_iv | ctr_output[1:].¶

The inverse transform operates as follows:¶

1. Decrypt the AES-CTR initialization vector:
   iv = AES-ECB-inv(k2, packet[L+1:L+17]).¶

2. Compute the other variables exactly as in the forward transform. (AES-CTR encryption and decryption are identical.)¶

3. Produce the output: header | cid | iv | ctr_output[1:].¶

The encryption keys used in this procedure do not depend on the packet contents, so each party only needs to perform AES initialization once for each connection.¶

NOTE: The security of this arrangement relies on every short-header QUIC packet containing a distinct 16 bytes following the Connection ID. This is true for the original ciphersuites of QUICv1, but it is not guaranteed by the QUIC Invariants. Future ciphersuites and QUIC versions could in principle produce packets that are too short or repeat the values at this location. When using the scramble transform, clients MUST NOT offer any configuration that could cause the client or target to violate this requirement.¶

9.1. Passive Attacks

A passive attacker aims to deanonymize a client by correlating traffic across both sides of the proxy. When using forwarded mode with the identity packet transform (see Section 6.1), such correlation is trivial by matching a subset of QUIC packet bytes as packets enter the proxy on one side and exit on the other. Packet transforms such as scramble mitigate this by cryptographically preventing such byte comparisons (see Section 6.2).¶

Regardless of which packet transform is used, both tunnelled and forwarded mode are still vulnerable to size and timing attacks, without the addition of techniques that go beyond the analysis in this document, such as padding and adding chaff packets. Such techniques could be supported in future packet transforms, subject to additional security analysis.¶

Unlike tunnelled mode where packets are fully encapsulated in the client-to-proxy connection, clients using forwarded mode to access multiple target servers over the same client-to-proxy connection expose the number of target servers they are communicating with on each connection to passive attackers that can observe the client-to-proxy traffic. This additional metadata revealed on each packet simplifies size and timing attacks.¶

9.2. Active Attacks

An active attacker is an adversary that can inject, modify, drop, and view packets in the network. Some active attacks have different effects between forwarded mode and tunnelled mode, but active attacks can be used to correlate flows in either mode.¶

Both tunnelled mode and forwarded mode (regardless of packet transform) are vulnerable to packet injection in the target-to-client direction. An attacker can inject a burst of packets with a known QUIC Connection ID and see which Connection ID is used for the corresponding burst on the proxy-to-client network path.¶

Packet injection with a known QUIC Connection ID can also happen in the client-to-proxy direction, which only affects forwarded mode since tunnelled mode sends packets within an authenticated and integrity protected QUIC connection to the proxy (see [RFC9001]). None of the packet transforms defined in this document provide integrity protection. Even if a packet transform did provide integrity protection, attackers can inject replayed packets. Protection against replayed packets is similarly provided by QUIC in tunnelled mode, but not provided by any of the forwarded mode packet transforms defined in this document.¶

An active attacker can modify packets in the client-to-proxy direction, which would cause a tunnelling proxy to silently drop packets, while a forwarding proxy would forward the packets. In this way, forwarded mode is less vulnerable to flow recognition based on corrupting a portion of packets in a burst.¶

10.1. HTTP Header

This document registers the "Proxy-QUIC-Forwarding" header in the "Hypertext Transfer Protocol (HTTP) Field Name Registry" <https://www.iana.org/assignments/http-fields>.¶

    +-----------------------+----------+--------+---------------+
    | Header Field Name     | Protocol | Status |   Reference   |
    +-----------------------+----------+--------+---------------+
    | Proxy-QUIC-Forwarding |   http   |  exp   | This document |
    +-----------------------+----------+--------+---------------+

10.2. Proxy QUIC Forwarding Parameter Names

This document establishes a new registry, "Proxy QUIC Forwarding Parameter Names", for parameter names to use with the Proxy-QUIC-Forwarding header field, in <https://www.iana.org/assignments/masque/masque.xhtml>. Registrations in this registry are assigned using the Specification Required policy (Section 4.6 of [IANA-POLICY]).¶

    +-----------------------+-------------------------------------+---------------+--------------------------------+
    | Parameter Name        | Description                         | Reference     | Notes                          |
    +-----------------------+-------------------------------------+---------------+--------------------------------+
    | accept-transform      | contains supported transforms       | This document | Section {{client-behavior}}    |
    +-----------------------+-------------------------------------+---------------+--------------------------------+
    | transform             | indicates selected transforms       | This document | Section {{proxy-behavior}}     |
    +-----------------------+-------------------------------------+---------------+--------------------------------+
    | scramble-key          | contains key for scramble transform | This document | Section {{scramble-transform}} |
    +-----------------------+-------------------------------------+---------------+--------------------------------+

10.3. Packet Transform Names

This document establishes a new registry for packet transform names in <https://www.iana.org/assignments/masque/masque.xhtml> and defines two initial transforms: "identity" and "scramble". Prior to finalization, deployments that implement the version of the scramble transform defined in this document should use the value "scramble-dt". Once the design team proposal is adopted and a new draft is submitted, the wire identifier will become "scramble-XX" where XX is the draft number. Registrations in this registry are assigned using the Specification Required policy (Section 4.6 of [IANA-POLICY]).¶

10.4. Capsule Types

This document registers six new values in the "HTTP Capsule Types" registry established by [HTTP-DGRAM]. Note that the codepoints below will be replaced with lower values before publication.¶

All of these new entries use the following values for these fields:¶

Status:

provisional (permanent when this document is published)¶

Reference:

This document¶

Change Controller:

IETF¶

Contact:

masque@ietf.org¶

Notes:

None¶