Proxying Ethernet in HTTP

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 23 April 2025.¶

Copyright Notice

Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. Introduction

HTTP provides the CONNECT method (see Section 9.3.6 of [HTTP]) for creating a TCP [TCP] tunnel to a destination, a similar mechanism for UDP [CONNECT-UDP], and an additional mechanism for IP [CONNECT-IP]. However, these mechanisms can't carry layer 2 frames without further encapsulation inside of IP, for instance with EtherIP [ETHERIP], GUE [GUE] or L2TP [L2TP] [L2TPv3], 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 [HTTP-DGRAM]. When using HTTP/2 [HTTP/2] or HTTP/3 [HTTP/3], it uses HTTP Extended CONNECT as described in [EXT-CONNECT2] and [EXT-CONNECT3]. When using HTTP/1.x [HTTP/1.1], it uses HTTP Upgrade as defined in Section 7.8 of [HTTP].¶

2. 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.¶

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 Section 3.7 of [HTTP]) 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 [QUIC]. Where this document defines protocol types, the definition format uses the notation from Section 1.3 of [QUIC]. This specification uses the variable-length integer encoding from Section 16 of [QUIC]. 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.¶

3. Configuration of Clients

Clients are configured to use Ethernet proxying over HTTP via a URI Template [TEMPLATE]. The URI Templates used by this protocol do not require any variables; implementations or extensions MAY specify their own. An implementation that supports connecting to different Ethernet segments might add a "vlan-identifier" variable to specify which segment to connect to. The optionality of variable needs to be considered when defining the template so that the variable is either self-identifying or possible to exclude in the syntax. URI Templates specified for this protocol MAY use the well-known location [WELL-KNOWN] registered by this document.¶

Examples are shown below:¶

https://example.org/.well-known/masque/ethernet/
https://example.org/.well-known/masque/ethernet/{vlan-identifier}/
https://proxy.example.org:4443/masque/ethernet/
https://proxy.example.org:4443/masque/ethernet?vlan={vlan-identifier}
https://masque.example.org/?user=bob

4. 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 Section 3.2 of [HTTP-DGRAM]) with HTTP Datagrams in the format defined in Section 6.¶

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 Section 3.2 of [HTTP-DGRAM]), 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.¶

GET https://example.org/.well-known/masque/ethernet/ HTTP/1.1
Host: example.org
Connection: Upgrade
Upgrade: connect-ethernet
Capsule-Protocol: ?1

HTTP/1.1 101 Switching Protocols
Connection: Upgrade
Upgrade: connect-ethernet
Capsule-Protocol: ?1

HEADERS
:method = CONNECT
:protocol = connect-ethernet
:scheme = https
:path = /.well-known/masque/ethernet/
:authority = example.org
capsule-protocol = ?1

HEADERS
:status = 200
capsule-protocol = ?1

5. 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 could augment Ethernet payloads with additional data or compress Ethernet frame header fields, while others could 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 Section 6.¶

Context IDs are 62-bit integers (0-2⁶²-1). Context IDs are encoded as variable-length integers; see Section 16 of [QUIC]. 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.¶

6. HTTP Datagram Payload Format

When associated with Ethernet proxying request streams, the HTTP Datagram Payload field of HTTP Datagrams (see [HTTP-DGRAM]) has the format defined in Figure 5. 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 Payload {
  Context ID (i),
  Payload (..),
}

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), as defined by IEEE 802.3, with support for optional IEEE 802.1Q tagging (see Section 9.2).¶

7. 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, or the local termination of PAUSE frames.¶

8. 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.¶

[[ From Client ]]             [[ From Ethernet Proxy ]]

SETTINGS
  H3_DATAGRAM = 1

                              SETTINGS
                                ENABLE_CONNECT_PROTOCOL = 1
                                H3_DATAGRAM = 1

STREAM(44): HEADERS
:method = CONNECT
:protocol = connect-ethernet
:scheme = https
:path = /.well-known/masque/ethernet/
:authority = proxy.example.com
capsule-protocol = ?1

                              STREAM(44): HEADERS
                              :status = 200
                              capsule-protocol = ?1

DATAGRAM
Quarter Stream ID = 11
Context ID = 0
Payload = Encapsulated Ethernet Frame

                              DATAGRAM
                              Quarter Stream ID = 11
                              Context ID = 0
                              Payload = Encapsulated Ethernet Frame

9. Performance Considerations

When the protocol running inside the tunnel uses congestion control (e.g., [TCP] or [QUIC]), the proxied traffic will incur at least two nested congestion controllers. When tunneled packets are sent using QUIC DATAGRAM frames, the outer HTTP connection MAY disable congestion control for those packets that contain only QUIC DATAGRAM frames encapsulating Ethernet frames. Implementers will benefit from reading the guidance in Section 3.1.11 of [UDP-USAGE].¶

When the protocol running inside the tunnel uses loss recovery (e.g., [TCP] or [QUIC]) and the outer HTTP connection runs over TCP, the proxied traffic will incur at least two nested loss recovery mechanisms. This can reduce performance, as both can sometimes independently retransmit the same data. To avoid this, Ethernet proxying SHOULD be performed over HTTP/3 to allow leveraging the QUIC DATAGRAM frame.¶

10. 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 [HTTP], 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. Ethernet proxying endpoints could be configured to limit forwarding to pre-configured MAC addresses, though such filtering is outside the scope of this protocol. Dynamic signalling or negotiation of MAC address filtering is left to future extensions.¶

11. IANA Considerations

12. References

Acknowledgments

Much of the initial version of this draft borrows heavily from [CONNECT-IP].¶

The author would like to thank Alexander Chernyakhovsky and David Schinazi for their advice while preparing this document, and Etienne Dechamps for useful discussion on the subject material. Additionally, Mirja Kühlewind and Magnus Westerlund provided valuable feedback on the document.¶

Author's Address