]> Google LLC

asedeno@google.com

Transport Multiplexed Application Substrate over QUIC Encryption quic http datagram VPN proxy tunnels masque http-ng layer-2 ethernet This document describes how to proxy Ethernet frames in HTTP. This protocol is similar to IP proxying in HTTP, but for Layer 2 instead of Layer 3. More specifically, this document defines a protocol that allows an HTTP client to create Layer 2 Ethernet tunnel through an HTTP server to an attached physical or virtual Ethernet segment. 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 HTTP provides the CONNECT method (see ) for creating a TCP tunnel to a destination, a similar mechanism for UDP , and an additional mechanism for IP . However, these mechanisms can't carry layer 2 frames without further encapsulation inside of IP, for instance with EtherIP , GUE or L2TP , which imposes an additional MTU cost. This document describes a protocol for exchanging Ethernet frames with an HTTP server. Either participant in the HTTP connection can then relay Ethernet frames to and from a local or virtual interface, allowing the bridging of two Ethernet broadcast domains to establish a Layer 2 VPN. This can simplify connectivity to network-connected appliances that are configured to only interact with peers on the same Ethernet broadcast domain. This protocol supports all existing versions of HTTP by using HTTP Datagrams . When using HTTP/2 or HTTP/3 , it uses HTTP Extended CONNECT as described in and . When using HTTP/1.x , it uses HTTP Upgrade as defined in .

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. In this document, we use the term "Ethernet proxy" to refer to the HTTP server that responds to the Ethernet proxying request. The term "client" is used in the HTTP sense; the client constructs the Ethernet proxying request. If there are HTTP intermediaries (as defined in ) between the client and the Ethernet proxy, those are referred to as "intermediaries" in this document. The term "Ethernet proxying endpoints" refers to both the client and the Ethernet proxy. This document uses terminology from . Where this document defines protocol types, the definition format uses the notation from . This specification uses the variable-length integer encoding from . Variable-length integer values do not need to be encoded in the minimum number of bytes necessary. Note that, when the HTTP version in use does not support multiplexing streams (such as HTTP/1.1), any reference to "stream" in this document represents the entire connection.

Configuration of Clients Clients are configured to use Ethernet proxying over HTTP via a URL. Examples are shown below:

Tunnelling Ethernet over HTTP To allow negotiation of a tunnel for Ethernet over HTTP, this document defines the "connect-ethernet" HTTP upgrade token. The resulting Ethernet tunnels use the Capsule Protocol (see ) with HTTP Datagrams in the format defined in . To initiate an Ethernet tunnel associated with a single HTTP stream, a client issues a request containing the "connect-ethernet" upgrade token. By virtue of the definition of the Capsule Protocol (see ), Ethernet proxying requests do not carry any message content. Similarly, successful Ethernet proxying responses also do not carry any message content. Ethernet proxying over HTTP MUST be operated over TLS or QUIC encryption, or another equivalent encryption protocol, to provide confidentiality, integrity, and authentication.

Ethernet Proxy Handling Upon receiving an Ethernet proxying request:

• if the recipient is configured to use another HTTP proxy, it will act as an intermediary by forwarding the request to another HTTP server. Note that such intermediaries may need to re-encode the request if they forward it using a version of HTTP that is different from the one used to receive it, as the request encoding differs by version (see below).
• otherwise, the recipient will act as an Ethernet proxy. The Ethernet proxy can choose to reject the Ethernet proxying request or establish an Ethernet tunnel.

The lifetime of the Ethernet tunnel is tied to the Ethernet proxying request stream. A successful response (as defined in Sections and ) indicates that the Ethernet proxy has established an Ethernet tunnel and is willing to proxy Ethernet frames. Any response other than a successful response indicates that the request has failed; thus, the client MUST abort the request.

HTTP/1.1 Request When using HTTP/1.1 , an Ethernet proxying request will meet the following requirements:

• the method SHALL be "GET".
• the request SHALL include a single Host header field containing the host and optional port of the Ethernet proxy.
• the request SHALL include a Connection header field with value "Upgrade" (note that this requirement is case-insensitive as per ).
• the request SHALL include an Upgrade header field with value "connect-ethernet".

An Ethernet proxying request that does not conform to these restrictions is malformed. The recipient of such a malformed request MUST respond with an error and SHOULD use the 400 (Bad Request) status code. For example, if the client is configured with the URL "https://example.org/.well-known/masque/ethernet/" and wishes to open an Ethernet tunnel, it could send the following request.

Example HTTP/1.1 Request

HTTP/1.1 Response The server indicates a successful response by replying with the following requirements:

• the HTTP status code on the response SHALL be 101 (Switching Protocols).
• the response SHALL include a Connection header field with value "Upgrade" (note that this requirement is case-insensitive as per ).
• the response SHALL include a single Upgrade header field with value "connect-ethernet".
• the response SHALL meet the requirements of HTTP responses that start the Capsule Protocol; see .

If any of these requirements are not met, the client MUST treat this proxying attempt as failed and close the connection. For example, the server could respond with:

Example HTTP/1.1 Response

HTTP/2 and HTTP/3 Requests When using HTTP/2 or HTTP/3 , Ethernet proxying requests use HTTP Extended CONNECT. This requires that servers send an HTTP Setting as specified in and and that requests use HTTP pseudo-header fields with the following requirements:

• The :method pseudo-header field SHALL be "CONNECT".
• The :protocol pseudo-header field SHALL be "connect-ethernet".
• The :authority pseudo-header field SHALL contain the authority of the IP proxy.
• The :path and :scheme pseudo-header fields SHALL NOT be empty. Their values SHALL contain the scheme and path from the configured URL; see .

An Ethernet proxying request that does not conform to these restrictions is malformed; see and . For example, if the client is configured with the URL "https://example.org/.well-known/masque/ethernet/" and wishes to open an Ethernet tunnel, it could send the following request.

Example HTTP/2 or HTTP/3 Request

HTTP/2 and HTTP/3 Responses The server indicates a successful response by replying with the following requirements:

• the HTTP status code on the response SHALL be in the 2xx (Successful) range.
• the response SHALL meet the requirements of HTTP responses that start the Capsule Protocol; see .

If any of these requirements are not met, the client MUST treat this proxying attempt as failed and abort the request. As an example, any status code in the 3xx range will be treated as a failure and cause the client to abort the request. For example, the server could respond with:

Example HTTP/2 or HTTP/3 Response

Context Identifiers The mechanism for proxying Ethernet in HTTP defined in this document allows future extensions to exchange HTTP Datagrams that carry different semantics from Ethernet frames. Some of these extensions can augment Ethernet payloads with additional data or compress Ethernet frame header fields, while others can exchange data that is completely separate from Ethernet payloads. In order to accomplish this, all HTTP Datagrams associated with Ethernet proxying requests streams start with a Context ID field; see . Context IDs are 62-bit integers (0-2⁶²-1). Context IDs are encoded as variable-length integers; see . The Context ID value of 0 is reserved for Ethernet payloads, while non-zero values are dynamically allocated. Non-zero even-numbered Context-IDs are client allocated, and odd-numbered Context IDs are proxy-allocated. The Context ID namespace is tied to a given HTTP request; it is possible for a Context ID with the same numeric value to be simultaneously allocated in distinct requests, potentially with different semantics. Context IDs MUST NOT be re-allocated within a given HTTP request but MAY be allocated in any order. The Context ID allocation restrictions to the use of even-numbered and odd-numbered Context IDs exist in order to avoid the need for synchronization between endpoints. However, once a Context ID has been allocated, those restrictions do not apply to the use of the Context ID; it can be used by either the client or the Ethernet proxy, independent of which endpoint initially allocated it. Registration is the action by which an endpoint informs its peer of the semantics and format of a given Context ID. This document does not define how registration occurs. Future extensions MAY use HTTP header fields or capsules to register Context IDs. Depending on the method being used, it is possible for datagrams to be received with Context IDs that have not yet been registered. For instance, this can be due to reordering of the packet containing the datagram and the packet containing the registration message during transmission.

HTTP Datagram Payload Format When associated with Ethernet proxying request streams, the HTTP Datagram Payload field of HTTP Datagrams (see ) has the format defined in . Note that when HTTP Datagrams are encoded using QUIC DATAGRAM frames, the Context ID field defined below directly follows the Quarter Stream ID field which is at the start of the QUIC DATAGRAM frame payload.

Ethernet Proxying HTTP Datagram Format

The Ethernet Proxying HTTP Datagram Payload contains the following fields:

Context ID:

A variable-length integer that contains the value of the Context ID. If an HTTP/3 datagram which carries an unknown Context ID is received, the receiver SHALL either drop that datagram silently or buffer it temporarily (on the order of a round trip) while awaiting the registration of the corresponding Context ID.

Payload:

The payload of the datagram, whose semantics depend on value of the previous field. Note that this field can be empty.

Ethernet frames are encoded using HTTP Datagrams with the Context ID set to zero. When the Context ID is set to zero, the Payload field contains a full Layer 2 Ethernet Frame (from the MAC destination field until the last byte of the Frame check sequence field).

Ethernet Frame Handling This document defines a tunnelling mechanism that is conceptually an Ethernet link. Implementations might need to handle some of the responsibilities of an Ethernet switch or bridge if they do not delegate them to another implementation such as a kernel. Those responsibilities are beyond the scope of this document, and include, but are not limited to, the handling of broadcast packets and multicast groups.

Examples Ethernet proxying in HTTP enables the bridging of Ethernet broadcast domains. These examples are provided to help illustrate some of the ways in which Ethernet proxying can be used.

Remote Access L2VPN The following example shows a point to point VPN setup where a client appears to be connected to a remote Layer 2 network.

L2VPN Tunnel Setup HOST 1 | +--------------------+ L2 | Layer 2 | | Client |<--Layer 2 Tunnel---| Proxy +------------+---> HOST 2 | +--------------------+ | Broadcast | +--------+ +--------+ Domain +---> HOST 3 ]]>

In this case, the client connects to the Ethernet proxy and immediately can start sending ethernet frames to the attached broadcast domain.

VPN Full-Tunnel Example

Site-to-Site L2VPN The following example shows a site-to-site VPN setup where a client joins a locally attached broadcast domain to a remote broadcast domain through the Proxy.

Site-to-site L2VPN Example HOST 1 | Broadcast Broadcast | HOST B <---+ Domain Domain +---> HOST 2 | | HOST C <---+ +---> HOST 3 ]]>

In this case, the client connects to the Ethernet proxy and immediately can start relaying Ethernet frames from its attached broadcast domain to the proxy. The difference between this example and is limited to what the Client is doing with the the tunnel; the exchange between the Client and the Proxy is the same as in above.

Security Considerations There are risks in allowing arbitrary clients to establish a tunnel to a Layer 2 network. Bad actors could abuse this capability to attack hosts on that network that they would otherwise be unable to reach. HTTP servers that support Ethernet proxying SHOULD restrict its use to authenticated users. Depending on the deployment, possible authentication mechanisms include mutual TLS between IP proxying endpoints, HTTP-based authentication via the HTTP Authorization header , or even bearer tokens. Proxies can enforce policies for authenticated users to further constrain client behavior or deal with possible abuse. For example, proxies can rate limit individual clients that send an excessively large amount of traffic through the proxy. Users of this protocol may send arbitrary Ethernet frames through the tunnel, including frames with falsified source MAC addresses. This could allow impersonation of other hosts, poisoning of ARP and CAM tables, and cause a denial of service to other hosts on the network. These are the same attacks available to an arbitrary client with physical access to the network.

IANA Considerations

HTTP Upgrade Token This document will request IANA to register "connect-ethernet" in the HTTP Upgrade Token Registry maintained at <>.

Value:

connect-ethernet

Description:

Proxying of Ethernet Payloads

Expected Version Tokens:

None

References:

This document

Updates to the MASQUE URI Suffixes Registry This document will request IANA to register "ethernet" in the MASQUE URI Suffixes Registry maintained at $IANA_URL_TBD, created by CONNECT-IP . New MASQUE URI Suffixes

Path Segment	Description	Reference
ethernet	Ethernet Proxying	This Document

References Normative References The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document specifies the HTTP/1.1 message syntax, message parsing, connection management, and related security concerns. This document obsoletes portions of RFC 7230. This specification describes an optimized expression of the semantics of the Hypertext Transfer Protocol (HTTP), referred to as HTTP version 2 (HTTP/2). HTTP/2 enables a more efficient use of network resources and a reduced latency by introducing field compression and allowing multiple concurrent exchanges on the same connection. This document obsoletes RFCs 7540 and 8740. The QUIC transport protocol has several features that are desirable in a transport for HTTP, such as stream multiplexing, per-stream flow control, and low-latency connection establishment. This document describes a mapping of HTTP semantics over QUIC. This document also identifies HTTP/2 features that are subsumed by QUIC and describes how HTTP/2 extensions can be ported to HTTP/3. 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. This document specifies the Transmission Control Protocol (TCP). TCP is an important transport-layer protocol in the Internet protocol stack, and it has continuously evolved over decades of use and growth of the Internet. Over this time, a number of changes have been made to TCP as it was specified in RFC 793, though these have only been documented in a piecemeal fashion. This document collects and brings those changes together with the protocol specification from RFC 793. This document obsoletes RFC 793, as well as RFCs 879, 2873, 6093, 6429, 6528, and 6691 that updated parts of RFC 793. It updates RFCs 1011 and 1122, and it should be considered as a replacement for the portions of those documents dealing with TCP requirements. It also updates RFC 5961 by adding a small clarification in reset handling while in the SYN-RECEIVED state. The TCP header control bits from RFC 793 have also been updated based on RFC 3168. 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. 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. This document describes the Layer Two Tunneling Protocol (L2TP). [STANDARDS-TRACK] This document describes "version 3" of the Layer Two Tunneling Protocol (L2TPv3). L2TPv3 defines the base control protocol and encapsulation for tunneling multiple Layer 2 connections between two IP nodes. Additional documents detail the specifics for each data link type being emulated. [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. This document defines a mechanism for running the WebSocket Protocol (RFC 6455) over a single stream of an HTTP/2 connection. The mechanism for running the WebSocket Protocol over a single stream of an HTTP/2 connection is equally applicable to HTTP/3, but the HTTP-version-specific details need to be specified. This document describes how the mechanism is adapted for HTTP/3. 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. Informative References Quantonium Independent Microsoft This specification describes Generic UDP Encapsulation (GUE), which is a scheme for using UDP to encapsulate packets of different IP protocols for transport across layer 3 networks. By encapsulating packets in UDP, specialized capabilities in networking hardware for efficient handling of UDP packets can be leveraged. GUE specifies basic encapsulation methods upon which higher level constructs, such as tunnels and overlay networks for network virtualization, can be constructed. GUE is extensible by allowing optional data fields as part of the encapsulation, and is generic in that it can encapsulate packets of various IP protocols.

Acknowledgments Much of the initial version of this draft borrows heavily from . The author would like to thank Alexander Chernyakhovsky and David Schinazi for their advice while preparing this document.