]> Google LLC

dschinazi.ietf@gmail.com

Google LLC

abhisinghietf@gmail.com

Transport MASQUE quic http datagram udp proxy tunnels quic in quic turtles all the way down masque http-ng listen bind The mechanism to proxy UDP in HTTP only allows each UDP proxying request to transmit to a specific host and port. This is well suited for UDP client-server protocols such as HTTP/3, but is not sufficient for some UDP peer-to-peer protocols like WebRTC. This document defines an extension to UDP proxying in HTTP that enables such use-cases. About This Document The latest revision of this draft can be found at . Status information for this document may be found at . Discussion of this document takes place on the MASQUE Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction The mechanism to proxy UDP in HTTP allows creating tunnels for communicating UDP payloads to a fixed host and port; this enables proxying of HTTP/3 connections, since they run over UDP. Similarly, the HTTP CONNECT method (see ) allows proxying HTTP/1.x and HTTP/2, which run over TCP. Combining both allows proxying the majority of a Web browser's HTTP traffic. However, WebRTC relies on ICE to provide connectivity between two Web browsers, and ICE relies on the ability to send and receive UDP packets to multiple hosts. While in theory it might be possible to accomplish this using multiple UDP proxying HTTP requests, HTTP semantics do not guarantee that distinct requests will be handled by the same server. This can lead to the UDP packets being sent from distinct IP addresses, thereby preventing ICE from operating correctly. Consequently, UDP proxying requests cannot enable WebRTC connectivity between peers. This document describes an extension to UDP Proxying in HTTP that allows sending and receiving UDP payloads to multiple hosts within the scope of a single UDP proxying HTTP request.

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 when, and only when, they appear in all capitals, as shown here. This document uses terminology from and notational conventions from . This document uses the terms Boolean, List, and String from to specify syntax and parsing. This document uses Augmented Backus-Naur Form and parsing/serialization behaviors from .

Bound UDP Proxying Mechanism In unextended UDP proxying requests, the target host is encoded in the HTTP request path or query. For bound UDP proxying, the target is either conveyed in each HTTP Datagram (see ), or registered via capsules and then compressed (see Sections and ). When performing URI Template Expansion of the UDP proxying template (see ), the client follows the same template as unextended UDP proxying and sets the "target_host" and the "target_port" variables to one of its targets. It adds the Connect-UDP-Bind header field as specified in to request bind. If the proxy supports bound UDP proxying, it returns the Connect-UDP-Bind response header field value set to true. When "target_host" and "target_port" are set to a valid target, the client is requesting bound UDP proxying but would accept fallback to unextended UDP proxying to that target. If the client does not have a specific target, or if it wants bound UDP proxying without fallback, it sets both the "target_host" and the "target_port" variables to the '*' character (ASCII character 0x2A). Note that the '*' character MUST be percent-encoded before sending, per . If only one of the "target_host" and the "target_port" variables is set to the '*' character, the request is malformed. The recipient of such a malformed request MUST respond with an error and SHOULD use the 400 (Bad Request) status code.

Context Identifiers As with unextended UDP proxying, the semantics of HTTP Datagrams are conveyed by Context IDs (see ). Endpoints first allocate a new Context ID (per , clients allocate even Context IDs while proxies allocate odd ones), and then use the COMPRESSION_ASSIGN capsule (see ) to convey the semantics of the new Context ID to their peer. This process is known as registering the Context ID. Each Context ID can have either compressed or uncompressed semantics. The uncompressed variant encodes the target IP and port into each HTTP Datagram. Conversely, the compressed variant exchanges the target IP and port once in the capsule during registration, and then relies on shared state to map from the Context ID to the IP and port. Context ID 0 was reserved by unextended UDP proxying to represent UDP payloads sent to and from the "target_host" and "target_port" from the URI template. When the mechanism from this document is in use:

• if the "target_host" and "target_port" variables are set to '*', then Context ID 0 MUST NOT be used in HTTP Datagrams. If one is received, the recipient MUST abort the request stream.
• otherwise, HTTP Datagrams with Context ID 0 have the same semantics as in unextended UDP proxying.

The COMPRESSION_ASSIGN capsule The Compression Assign capsule (capsule type 0x11) is used to register the semantics of a Context ID. It has the following format:

Compression Assign Capsule Format

It contains the following fields:

IP Version:

The IP Version of the following IP Address field. MUST be 0, 4 or 6. Setting this to zero indicates that this capsule registers an uncompressed Context ID. Otherwise, the capsule registers a compressed Context ID for the IP address and UDP port it carries.

IP Address:

The IP Address of this context. This field is omitted if the IP Version field is set to 0. Otherwise, it has a length of 32 bits when the corresponding IP Version field value is 4, and 128 when the IP Version is 6.

UDP Port:

The UDP Port of this context, in network byte order. This field is omitted if the IP Version field is set to 0.

When an endpoint receives a COMPRESSION_ASSIGN capsule, it MUST either accept or reject the corresponding registration:

• if it accepts the registration, first the receiver MUST save the mapping from Context ID to address and port (or save the fact that this Context ID is uncompressed). Second, the receiver MUST return a COMPRESSION_ACK capsule with the Context ID set to the one from the received COMPRESSION_ASSIGN capsule back to its peer, indicating it has accepted the registration.
• if it rejects the registration, the receiver MUST respond by sending a COMPRESSION_CLOSE capsule with the Context ID set to the one from the received COMPRESSION_ASSIGN capsule.

As mandated in , clients can only allocate even Context IDs, while proxies can only allocate odd ones. Since the value 0 was reserved by unextended UDP proxying, the Context ID value of COMPRESSION_ASSIGN can never be zero. Endpoints MUST NOT send two COMPRESSION_ASSIGN capsules with the same Context ID. If a recipient detects a repeated Context ID, it MUST treat the capsule as malformed. Receipt of a malformed capsule MUST be treated as an error processing the Capsule Protocol, as defined in . If the uncompressed Context ID is closed, the proxy MUST NOT open new compressed Context IDs. Allowing the proxy to do so would permit traffic from source tuples not selected by the client, defeating the IP restriction described in . Note that compressed Context IDs that were established prior to the closing of the uncompressed Context ID are not impacted. Only one Context ID can be used per IP-port tuple. Endpoints MUST NOT register a Context ID for a tuple for which there is already an existing Context ID. This can however happen if both endpoints register Context IDs simultaneously for the same tuple before learning that the peer also opened one. If an endpoint detects that both it and its peer have opened a Context ID for the same tuple, the endpoint MUST close the Context ID that was opened by the proxy. If an endpoint receives a COMPRESSION_ASSIGN capsule whose tuple matches another open Context ID that was opened by its peer, it MUST treat the capsule as malformed. Endpoints MAY pre-emptively use Context IDs not yet acknowledged by the peer via COMPRESSION_ACK, knowing that those HTTP Datagrams can be dropped if they arrive before the corresponding COMPRESSION_ASSIGN capsule, or if the peer rejects the registration.

The COMPRESSION_ACK capsule The Compression Acknowledgment capsule (capsule type 0x12) serves to confirm registration of a Context ID that was received via a COMPRESSION_ASSIGN capsule.

Compression Acknowledgment Capsule Format

An endpoint can only send a COMPRESSION_ACK capsule if it received a COMPRESSION_ASSIGN capsule with the same Context ID. If an endpoint receives COMPRESSION_ACK capsule for a Context ID it did not attempt to register via COMPRESSION_ASSIGN, that capsule is considered malformed.

The COMPRESSION_CLOSE capsule The Compression Close capsule (capsule type 0x13) serves two purposes. It can be sent as a direct response to a received COMPRESSION_ASSIGN capsule, to indicate that the registration was rejected. It can also be sent later to indicate the closure of a previously assigned registration.

Compression Close Capsule Format

Once an endpoint has either sent or received a COMPRESSION_CLOSE for a given Context ID, it MUST NOT send any further datagrams with that Context ID. Since the value 0 was reserved by unextended UDP proxying, a COMPRESSION_CLOSE capsule with Context ID set to zero is malformed. Endpoints MAY close any Context ID regardless of which endpoint registered it. This is useful for example, when a mapping is unused for a long time. Another potential use is restricting some targets (see ). Once a registration is closed, endpoints can instead use an uncompressed Context ID to exchange UDP payloads for the given target, if such a Context has been registered (see ). Once a Context ID has been closed, that ID cannot be reused; see .

Uncompressed Operation If the client wishes to send or receive uncompressed datagrams, it MUST first send a COMPRESSION_ASSIGN capsule (see ) to the proxy with the IP Version set to zero. This registers the Context ID as having uncompressed semantics: all HTTP Datagrams with this Context ID have the following format:

Uncompressed Bound UDP Proxying HTTP Datagram Format

It contains the following fields:

IP Version:

The IP Version of the following IP Address field. MUST be 4 or 6.

IP Address:

The IP Address of this proxied UDP packet. When sent from client to proxy, this is the target host to which the proxy will send this UDP payload. When sent from proxy to client, this represents the source IP address of the UDP packet received by the proxy. This field has a length of 32 bits when the corresponding IP Version field value is 4, and 128 when the IP Version is 6.

UDP Port:

The UDP Port of this proxied UDP packet in network byte order. When sent from client to proxy, this is the target port to which the proxy will send this UDP payload. When sent from proxy to client, this represents the source UDP port of the UDP packet received by the proxy.

UDP Payload:

The unmodified UDP Payload of this proxied UDP packet (referred to as "data octets" in ).

A client MUST NOT open an uncompressed Context ID if one is already open. If a server receives a request to open an uncompressed Context ID and it already has one open, then the server MUST treat the second capsule as malformed. Note that it's possible for the client to close the uncompressed Context ID and reopen it later with a different Context ID, as long as there aren't two uncompressed Context IDs open at the same time. Only the client can request uncompressed Context IDs. If a client receives a COMPRESSION_ASSIGN capsule with the IP Version set to 0, it MUST treat it as malformed.

Compressed Operation Endpoints MAY choose to compress the IP and port information per datagram for a given target using Context IDs. This is accomplished by registering a compressed Context ID using the COMPRESSION_ASSIGN capsule (see ). If the Context ID in an HTTP Datagram matches one previously registered for compressed operation, the rest of the HTTP Datagram represents the UDP payload:

Compressed Bound UDP Proxying HTTP Datagram Format

It contains the following field:

UDP Payload:

The unmodified UDP Payload of this proxied UDP packet (referred to as "data octets" in ).

The Connect-UDP-Bind Header Field The "Connect-UDP-Bind" header field’s value is a Boolean Structured Field set to true. Clients and proxy both indicate support for this extension by sending the Connect-UDP-Bind header field with a value of ?1. Once an endpoint has both sent and received the Connect-UDP-Bind header field set to true, this extension is enabled. Any other value type MUST be handled as if the field were not present by the recipients (for example, if this field is defined multiple times, its type becomes a List and therefore is to be ignored). This document does not define any parameters for the Connect-UDP-Bind header field value, but future documents might define parameters. Receivers MUST ignore unknown parameters.

The Proxy-Public-Address Response Header Field Upon accepting the request, the proxy MUST select at least one public IP address to bind. The proxy MAY assign more addresses. For each selected address, it MUST select an open port to bind to this request. From then and until the tunnel is closed, the proxy SHALL send packets received on these IP-port tuples to the client. The proxy MUST communicate the selected addresses and ports to the client using the "Proxy-Public-Address" header field. The header field is a List. Each member of the List is a String, comprised of the ip-port tuple. The format of the String is defined using IP-literal, IPv4address, and port from .

Proxy Address Format

When a single IP-Port tuple is provided in the Proxy-Public-Address field, the proxy MUST use the same public IP and Port for the lifetime of the tunnel. When multiple tuples are provided, maintaining address stability per address family for the duration of the tunnel is RECOMMENDED. Note that since the addresses are conveyed in HTTP response headers, a subsequent change of addresses on the proxy cannot be conveyed to the client. If the proxy only shares IP addresses from a single address family, that indicates that the proxy only supports that family. The client SHOULD NOT attempt to register compressed Context IDs or send uncompressed datagrams intended for targets whose IP address families were not indicated via the IP addresses listed in the Proxy-Public-Address header field, as the proxy will drop those datagrams and reject those registrations.

Proxy Behavior After accepting the bound UDP proxying request, the proxy uses an assigned IP address and port to transmit UDP payloads received from the client to the target IP Address and UDP Port specified in each HTTP Datagram received from the client. The proxy uses the same ports to listen for UDP packets from any authorized target and forwards them to the client by encapsulating them in HTTP Datagrams, using the corresponding Context ID. If the proxy receives UDP payloads that don't correspond to any registration (i.e., no compression for the given target was ever established and there is no uncompressed registration), the proxy will either drop the datagram or temporarily buffer it (see ).

Restricting IPs If a client does not wish to receive datagrams from unknown senders, it can close the uncompressed Context ID (or not open it in the first place). In that scenario, the proxy effectively acts as a firewall against unwanted or unknown IPs.

Security Considerations The security considerations described in also apply here. Since TURN can be run over this mechanism, implementors will benefit from reviewing the security considerations in . Since unextended UDP proxying requests carry the target as part of the request, the proxy can protect against unauthorized targets by rejecting requests before creating the tunnel, and communicate the rejection reason in response header fields. The uncompressed Context ID allows transporting datagrams to and from any target. Clients that keep the uncompressed Context ID open need to be able to receive from all targets. If the UDP proxy were to reject unextended UDP proxying requests to some targets (as recommended in ), then for bound UDP proxying requests where the uncompressed Context ID is open, the UDP proxy needs to perform checks on the target of each uncompressed Context ID datagram it receives. Similarly, the UDP proxy needs to perform checks on the IP address and port of received COMPRESSION_ASSIGN capsules and reject the registration of compressed Context IDs to disallowed targets. When an endpoint accepts the registration of a Context ID, it will need to store it in memory. To prevent unbounded memory growth, endpoints MUST place a limit on how many Context IDs can be open simultaneously and reject registrations beyond the limit. Note that if the compression response (COMPRESSION_ACK or COMPRESSION_CLOSE) cannot be immediately sent due to flow or congestion control, an upper limit on how many compression responses the endpoint is willing to buffer MUST be set to prevent memory exhaustion. The proxy MUST abort the request stream if this limit is reached.

Operational Considerations When moving traffic between uncompressed and compressed Context IDs, the effective MTU will change. This can hinder Datagram Packetization Layer PMTU Discovery (DPLPMTUD) between the client and the target . To avoid that, if an endpoint intends to use compression, it SHOULD request it as early as possible.

IANA Considerations

HTTP Fields This document requests IANA to register the following new items in the "HTTP Field Name" registry maintained at <>: New Fields

Field Name	Structured Type
Connect-UDP-Bind	Item
Proxy-Public-Address	List

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

Status:

provisional (permanent if this document is approved)

Reference:

This document

Comments:

None

Capsules This document requests IANA to register the following new items to the "HTTP Capsule Types" registry maintained at <>: New Capsules

Value	Capsule Type
0x11	COMPRESSION_ASSIGN
0x12	COMPRESSION_ACK
0x13	COMPRESSION_CLOSE

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

Status:

provisional (permanent if this document is approved)

Reference:

This document

Change Controller:

IETF

Contact:

MASQUE Working Group masque@ietf.org

Notes:

None

References Normative References This document describes how to proxy UDP in HTTP, similar to how the HTTP CONNECT method allows proxying TCP in HTTP. More specifically, this document defines a protocol that allows an HTTP client to create a tunnel for UDP communications through an HTTP server that acts as a proxy. The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document describes the overall architecture of HTTP, establishes common terminology, and defines aspects of the protocol that are shared by all versions. In this definition are core protocol elements, extensibility mechanisms, and the "http" and "https" Uniform Resource Identifier (URI) schemes. This document updates RFC 3864 and obsoletes RFCs 2818, 7231, 7232, 7233, 7235, 7538, 7615, 7694, and portions of 7230. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. This document defines the core of the QUIC transport protocol. QUIC provides applications with flow-controlled streams for structured communication, low-latency connection establishment, and network path migration. QUIC includes security measures that ensure confidentiality, integrity, and availability in a range of deployment circumstances. Accompanying documents describe the integration of TLS for key negotiation, loss detection, and an exemplary congestion control algorithm. This document describes a set of data types and associated algorithms that are intended to make it easier and safer to define and handle HTTP header and trailer fields, known as "Structured Fields", "Structured Headers", or "Structured Trailers". It is intended for use by specifications of new HTTP fields. This document obsoletes RFC 8941. Internet technical specifications often need to define a formal syntax. Over the years, a modified version of Backus-Naur Form (BNF), called Augmented BNF (ABNF), has been popular among many Internet specifications. The current specification documents ABNF. It balances compactness and simplicity with reasonable representational power. The differences between standard BNF and ABNF involve naming rules, repetition, alternatives, order-independence, and value ranges. This specification also supplies additional rule definitions and encoding for a core lexical analyzer of the type common to several Internet specifications. [STANDARDS-TRACK] A URI Template is a compact sequence of characters for describing a range of Uniform Resource Identifiers through variable expansion. This specification defines the URI Template syntax and the process for expanding a URI Template into a URI reference, along with guidelines for the use of URI Templates on the Internet. [STANDARDS-TRACK] This document describes HTTP Datagrams, a convention for conveying multiplexed, potentially unreliable datagrams inside an HTTP connection. In HTTP/3, HTTP Datagrams can be sent unreliably using the QUIC DATAGRAM extension. When the QUIC DATAGRAM frame is unavailable or undesirable, HTTP Datagrams can be sent using the Capsule Protocol, which is a more general convention for conveying data in HTTP connections. HTTP Datagrams and the Capsule Protocol are intended for use by HTTP extensions, not applications. A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource. This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet. The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier. This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme. [STANDARDS-TRACK] Informative References This document describes a protocol for Network Address Translator (NAT) traversal for UDP-based communication. This protocol is called Interactive Connectivity Establishment (ICE). ICE makes use of the Session Traversal Utilities for NAT (STUN) protocol and its extension, Traversal Using Relay NAT (TURN). This document obsoletes RFC 5245. If a host is located behind a NAT, it can be impossible for that host to communicate directly with other hosts (peers) in certain situations. In these situations, it is necessary for the host to use the services of an intermediate node that acts as a communication relay. This specification defines a protocol, called "Traversal Using Relays around NAT" (TURN), that allows the host to control the operation of the relay and to exchange packets with its peers using the relay. TURN differs from other relay control protocols in that it allows a client to communicate with multiple peers using a single relay address. The TURN protocol was designed to be used as part of the Interactive Connectivity Establishment (ICE) approach to NAT traversal, though it can also be used without ICE. This document obsoletes RFCs 5766 and 6156. This document specifies Datagram Packetization Layer Path MTU Discovery (DPLPMTUD). This is a robust method for Path MTU Discovery (PMTUD) for datagram Packetization Layers (PLs). It allows a PL, or a datagram application that uses a PL, to discover whether a network path can support the current size of datagram. This can be used to detect and reduce the message size when a sender encounters a packet black hole. It can also probe a network path to discover whether the maximum packet size can be increased. This provides functionality for datagram transports that is equivalent to the PLPMTUD specification for TCP, specified in RFC 4821, which it updates. It also updates the UDP Usage Guidelines to refer to this method for use with UDP datagrams and updates SCTP. The document provides implementation notes for incorporating Datagram PMTUD into IETF datagram transports or applications that use datagram transports. This specification updates RFC 4960, RFC 4821, RFC 6951, RFC 8085, and RFC 8261. This document describes how to proxy IP packets in HTTP. This protocol is similar to UDP proxying in HTTP but allows transmitting arbitrary IP packets. More specifically, this document defines a protocol that allows an HTTP client to create an IP tunnel through an HTTP server that acts as an IP proxy. This document updates RFC 9298.

Example In the example below, the client is configured with URI Template "https://example.org/.well-known/masque/udp/{target_host}/{target_port}/" and listens for traffic on the proxy, eventually decides that it no longer wants to listen for connections from new targets, and limits its communication with only 203.0.113.11:60000 and no other UDP target. :method = CONNECT :protocol = connect-udp :scheme = https :path = /.well-known/masque/udp/%2A/%2A/ :authority = proxy.example.org connect-udp-bind = ?1 capsule-protocol = ?1 <-------- STREAM(44): HEADERS :status = 200 connect-udp-bind = ?1 capsule-protocol = ?1 proxy-public-address = "192.0.2.45:54321", \ "[2001:db8::1234]:54321" // Register Context ID 2 to be used for uncompressed UDP payloads // to/from any target. CAPSULE --------> Type = COMPRESSION_ASSIGN Context ID = 2 IP Version = 0 // Proxy confirms registration. <-------- CAPSULE Type = COMPRESSION_ACK Context ID = 2 // Target talks to Client using the uncompressed Context ID. <-------- DATAGRAM Quarter Stream ID = 11 Context ID = 2 IP Version = 4 IP Address = 192.0.2.42 UDP Port = 50000 UDP Payload = Encapsulated UDP Payload // Client responds on the same uncompressed Context ID. DATAGRAM --------> Quarter Stream ID = 11 Context ID = 2 IP Version = 4 IP Address = 192.0.2.42 UDP Port = 50000 UDP Payload = Encapsulated UDP Payload // Another target talks to Client using the uncompressed Context ID. <-------- DATAGRAM Quarter Stream ID = 11 Context ID = 2 IP Version = 4 IP Address = 203.0.113.11 UDP Port = 60000 UDP Payload = Encapsulated UDP Payload // Client responds on the same uncompressed Context ID. DATAGRAM --------> Quarter Stream ID = 11 Context ID = 2 IP Version = 4 IP Address = 203.0.113.11 UDP Port = 60000 UDP Payload = Encapsulated UDP Payload // Register 203.0.113.11:60000 to compress it in the future. CAPSULE --------> Type = COMPRESSION_ASSIGN Context ID = 4 IP Version = 4 IP Address = 203.0.113.11 UDP Port = 60000 // Proxy confirms registration. <-------- CAPSULE Type = COMPRESSION_ACK Context ID = 4 // Omit IP and Port for future packets intended for // 203.0.113.11:60000 hereon. DATAGRAM --------> Context ID = 4 UDP Payload = Encapsulated UDP Payload <-------- DATAGRAM Context ID = 4 UDP Payload = Encapsulated UDP Payload // Request packets without a corresponding compressed Context // to be dropped by closing the uncompressed Context ID. CAPSULE --------> Type = COMPRESSION_CLOSE Context ID = 2 // Context ID 4 = 203.0.113.11:60000 traffic is accepted, // and other traffic is dropped at the proxy. ]]>

Comparison with CONNECT-IP While the use cases described in could be supported using IP proxying in HTTP , it would require that every HTTP Datagram carries a complete IP header. This would lead to both inefficiencies in the wire encoding and reduction in available Maximum Transmission Unit (MTU). Furthermore, Web browsers would need to support IPv4 and IPv6 header generation, parsing, validation and error handling.

Acknowledgments This proposal is the result of many conversations with MASQUE working group participants. In particular, the authors would like to thank , , , , , , , , , , and for their reviews.