Proxying IP 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 17 August 2023.¶

Copyright Notice

Copyright (c) 2023 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 and a similar mechanism for UDP [CONNECT-UDP]. However, these mechanisms cannot tunnel other IP protocols [IANA-PN] nor convey fields of the IP header.¶

This document describes a protocol for tunnelling IP to an HTTP server acting as an IP-specific proxy over HTTP. This can be used for various use cases such as point-to-network VPN, secure point-to-point communication, or general-purpose packet tunnelling.¶

IP proxying operates similarly to UDP proxying [CONNECT-UDP], whereby the proxy itself is identified with an absolute URL, optionally containing the traffic's destination. Clients generate these URLs using a URI Template [TEMPLATE], as described in Section 3.¶

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 "IP proxy" to refer to the HTTP server that responds to the IP proxying request. If there are HTTP intermediaries (as defined in Section 3.7 of [HTTP]) between the client and the proxy, those are referred to as "intermediaries" in this document.¶

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 on 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 IP proxying over HTTP via an URI Template [TEMPLATE]. The URI template MAY contain two variables: "target" and "ipproto"; see Section 4.6. The optionality of the variables needs to be considered when defining the template so that either the variable is self-identifying or it is possible to exclude it in the syntax.¶

Examples are shown below:¶

https://example.org/.well-known/masque/ip/{target}/{ipproto}/
https://proxy.example.org:4443/masque/ip?t={target}&i={ipproto}
https://proxy.example.org:4443/masque/ip{?target,ipproto}
https://masque.example.org/?user=bob

The following requirements apply to the URI Template:¶

• The URI Template MUST be a level 3 template or lower.¶
• The URI Template MUST be in absolute form, and MUST include non-empty scheme, authority and path components.¶
• The path component of the URI Template MUST start with a slash "/".¶
• All template variables MUST be within the path or query components of the URI.¶
• The URI template MAY contain the two variables "target" and "ipproto" and MAY contain other variables. If the "target" or "ipproto" variables are included, their values MUST NOT be empty. Clients can instead use "*" to indicate wildcard or no-preference values; see Section 4.6.¶
• The URI Template MUST NOT contain any non-ASCII unicode characters and MUST only contain ASCII characters in the range 0x21-0x7E inclusive (note that percent-encoding is allowed; see Section 2.1 of [URI].¶
• The URI Template MUST NOT use Reserved Expansion ("+" operator), Fragment Expansion ("#" operator), Label Expansion with Dot- Prefix, Path Segment Expansion with Slash-Prefix, nor Path-Style Parameter Expansion with Semicolon-Prefix.¶

Clients SHOULD validate the requirements above; however, clients MAY use a general-purpose URI Template implementation that lacks this specific validation. If a client detects that any of the requirements above are not met by a URI Template, the client MUST reject its configuration and abort the request without sending it to the IP proxy.¶

As with UDP proxying, some client configurations for IP proxies will only allow the user to configure the proxy host and proxy port. Clients with such limitations MAY attempt to access IP proxying capabilities using the default template, which is defined as: "https://$PROXY_HOST:$PROXY_PORT/.well-known/masque/ip/{target}/{ipproto}/", where $PROXY_HOST and $PROXY_PORT are the configured host and port of the IP proxy, respectively. IP proxy deployments SHOULD offer service at this location if they need to interoperate with such clients.¶

4. Tunnelling IP over HTTP

To allow negotiation of a tunnel for IP over HTTP, this document defines the "connect-ip" HTTP Upgrade Token. The resulting IP 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 IP tunnel associated with a single HTTP stream, a client issues a request containing the "connect-ip" upgrade token.¶

When sending its IP proxying request, the client SHALL perform URI template expansion to determine the path and query of its request, see Section 3.¶

By virtue of the definition of the Capsule Protocol (see Section 3.2 of [HTTP-DGRAM]), IP proxying requests do not carry any message content. Similarly, successful IP proxying responses also do not carry any message content.¶

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

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

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

HEADERS
:status = 200
capsule-protocol = ?1

target = IPv6prefix / IPv4prefix / reg-name / "*"
IPv6prefix = IPv6address ["%2F" 1*3DIGIT]
IPv4prefix = IPv4address ["%2F" 1*2DIGIT]
ipproto = 1*3DIGIT / "*"

ADDRESS_ASSIGN Capsule {
  Type (i) = ADDRESS_ASSIGN,
  Length (i),
  Assigned Address (..) ...,
}

Assigned Address {
  Request ID (i),
  IP Version (8),
  IP Address (32..128),
  IP Prefix Length (8),
}

ADDRESS_REQUEST Capsule {
  Type (i) = ADDRESS_REQUEST,
  Length (i),
  Requested Address (..) ...,
}

Requested Address {
  Request ID (i),
  IP Version (8),
  IP Address (32..128),
  IP Prefix Length (8),
}

ROUTE_ADVERTISEMENT Capsule {
  Type (i) = ROUTE_ADVERTISEMENT,
  Length (i),
  IP Address Range (..) ...,
}

IP Address Range {
  IP Version (8),
  Start IP Address (32..128),
  End IP Address (32..128),
  IP Protocol (8),
}

5. Context Identifiers

The mechanism for proxying IP in HTTP defined in this document allows future extensions to exchange HTTP Datagrams that carry different semantics from IP payloads. Some of these extensions can augment IP payloads with additional data or compress IP header fields, while others can exchange data that is completely separate from IP payloads. In order to accomplish this, all HTTP Datagrams associated with IP proxying request streams start with a Context ID field; see Section 6.¶

Context IDs are 62-bit integers (0 to 2⁶²-1). Context IDs are encoded as variable-length integers; see Section 16 of [QUIC]. The Context ID value of 0 is reserved for IP 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 IP 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 IP proxying request streams, the HTTP Datagram Payload field of HTTP Datagrams (see [HTTP-DGRAM]) has the format defined in Figure 13. 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:¶

IP Proxying HTTP Datagram Payload {
  Context ID (i),
  Payload (..),
}

The IP 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.¶

IP packets 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 IP packet (from the IP Version field until the last byte of the IP Payload).¶

Clients MAY optimistically start sending proxied IP packets before receiving the response to its IP proxying request, noting however that those may not be processed by the IP proxy if it responds to the request with a failure, or if the datagrams are received by the IP proxy before the request. Since receiving addresses and routes is required in order to know that a packet can be sent through the tunnel, such optimistic packets might be dropped by the IP proxy if it chooses to provide different addressing or routing information than what the client assumed.¶

When an endpoint receives an HTTP Datagram containing an IP packet, it will parse the packet's IP header, perform any local policy checks (e.g., source address validation), check their routing table to pick an outbound interface, and then send the IP packet on that interface or pass it to a local application.¶

In the other direction, when an endpoint receives an IP packet, it checks to see if the packet matches the routes mapped for an IP tunnel, and performs the same forwarding checks as above before transmitting the packet over HTTP Datagrams.¶

Note that endpoints will decrement the IP Hop Count (or TTL) upon encapsulation but not decapsulation. In other words, the Hop Count is decremented right before an IP packet is transmitted in an HTTP Datagram. This prevents infinite loops in the presence of routing loops, and matches the choices in IPsec [IPSEC].¶

IPv6 requires that every link have an MTU of at least 1280 bytes [IPv6]. Since IP proxying in HTTP conveys IP packets in HTTP Datagrams and those can in turn be sent in QUIC DATAGRAM frames which cannot be fragmented [DGRAM], the MTU of an IP tunnel can be limited by the MTU of the QUIC connection that IP proxying is operating over. This can lead to situations where the IPv6 minimum link MTU is violated. IP proxying endpoints that support IPv6 MUST ensure that the IP tunnel link MTU is at least 1280 (i.e., that they can send HTTP Datagrams with payloads of at least 1280 bytes). This can be accomplished using various techniques:¶

• if both IP proxying endpoints know for certain that HTTP intermediaries are not in use, the endpoints can pad the QUIC INITIAL packets of the underlying QUIC connection that IP proxying is running over. (Assuming QUIC version 1 is in use, the overhead is 1 byte type, 20 bytes maximal connection ID length, 4 bytes maximal packet number length, 1 byte DATAGRAM frame type, 8 bytes maximal quarter stream ID, one byte for the zero Context ID, and 16 bytes for the AEAD authentication tag, for a total of 51 bytes of overhead which corresponds to padding QUIC INITIAL packets to 1331 bytes or more.)¶
• IP proxying endpoints can also send ICMPv6 echo requests with 1232 bytes of data to ascertain the link MTU and tear down the tunnel if they do not receive a response. Unless endpoints have an out of band means of guaranteeing that the previous techniques is sufficient, they MUST use this method. If an endpoint does not know an IPv6 address of its peer, it can send the ICMPv6 echo request to the link local all nodes multicast address (ff02::1).¶

If an endpoint is using QUIC DATAGRAM frames to convey IPv6 packets, and it detects that the QUIC MTU is too low to allow sending 1280 bytes, it MUST abort the IP proxying request stream.¶

Endpoints MAY implement additional filtering policies on the IP packets they forward.¶

7. Error Signalling

Since IP proxying endpoints often forward IP packets onwards to other network interfaces, they need to handle errors in the forwarding process. For example, forwarding can fail if the endpoint does not have a route for the destination address, or if it is configured to reject a destination prefix by policy, or if the MTU of the outgoing link is lower than the size of the packet to be forwarded. In such scenarios, IP proxying endpoints SHOULD use ICMP [ICMP] [ICMPv6] to signal the forwarding error to its peer.¶

Endpoints are free to select the most appropriate ICMP errors to send. Some examples that are relevant for IP proxying include:¶

• For invalid source addresses, send Destination Unreachable Section 3.1 of [ICMPv6] with code 5, "Source address failed ingress/egress policy".¶
• For unroutable destination addresses, send Destination Unreachable Section 3.1 of [ICMPv6] with a code 0, "No route to destination", or code 1, "Communication with destination administratively prohibited".¶
• For packets that cannot fit within the MTU of the outgoing link, send Packet Too Big Section 3.2 of [ICMPv6].¶

In order to receive these errors, endpoints need to be prepared to receive ICMP packets. If an endpoint does not send ROUTE_ADVERTISEMENT capsules, such as a client opening an IP flow through an IP proxy, it SHOULD process proxied ICMP packets from its peer in order to receive these errors. Note that ICMP messages can originate from a source address different from that of the IP proxying peer.¶

8. Examples

IP proxying in HTTP enables many different use cases that can benefit from IP packet proxying and tunnelling. These examples are provided to help illustrate some of the ways in which IP proxying in HTTP can be used.¶

[[ From Client ]]             [[ From IP Proxy ]]

SETTINGS
  H3_DATAGRAM = 1

                              SETTINGS
                                ENABLE_CONNECT_PROTOCOL = 1
                                H3_DATAGRAM = 1

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

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

STREAM(44): DATA
Capsule Type = ADDRESS_REQUEST
(Request ID = 1
 IP Version = 4
 IP Address = 0.0.0.0
 IP Prefix Length = 32)

                              STREAM(44): DATA
                              Capsule Type = ADDRESS_ASSIGN
                              (Request ID = 1
                               IP Version = 4
                               IP Address = 192.0.2.11
                               IP Prefix Length = 32)

                              STREAM(44): DATA
                              Capsule Type = ROUTE_ADVERTISEMENT
                              (IP Version = 4
                               Start IP Address = 0.0.0.0
                               End IP Address = 255.255.255.255
                               IP Protocol = 0) // Any

DATAGRAM
Quarter Stream ID = 11
Context ID = 0
Payload = Encapsulated IP Packet

                              DATAGRAM
                              Quarter Stream ID = 11
                              Context ID = 0
                              Payload = Encapsulated IP Packet

[[ From Client ]]             [[ From IP Proxy ]]

                              STREAM(44): DATA
                              Capsule Type = ADDRESS_ASSIGN
                              (Request ID = 0
                               IP Version = 4
                               IP Address = 192.0.2.42
                               IP Prefix Length = 32)

                              STREAM(44): DATA
                              Capsule Type = ROUTE_ADVERTISEMENT
                              (IP Version = 4
                               Start IP Address = 192.0.2.0
                               End IP Address = 192.0.2.255
                               IP Protocol = 0) // Any

[[ From Client ]]             [[ From IP Proxy ]]

SETTINGS
  H3_DATAGRAM = 1

                              SETTINGS
                                ENABLE_CONNECT_PROTOCOL = 1
                                H3_DATAGRAM = 1

STREAM(44): HEADERS
:method = CONNECT
:protocol = connect-ip
:scheme = https
:path = /proxy?target=target.example.com&ipproto=132
:authority = proxy.example.com
capsule-protocol = ?1

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

                              STREAM(44): DATA
                              Capsule Type = ADDRESS_ASSIGN
                              (Request ID = 0
                               IP Version = 6
                               IP Address = 2001:db8:1234::a
                               IP Prefix Length = 128)

                              STREAM(44): DATA
                              Capsule Type = ROUTE_ADVERTISEMENT
                              (IP Version = 6
                               Start IP Address = 2001:db8:3456::b
                               End IP Address = 2001:db8:3456::b
                               IP Protocol = 132)

DATAGRAM
Quarter Stream ID = 11
Context ID = 0
Payload = Encapsulated SCTP/IP Packet

                              DATAGRAM
                              Quarter Stream ID = 11
                              Context ID = 0
                              Payload = Encapsulated SCTP/IP Packet

[[ From Client ]]             [[ From IP Proxy ]]

SETTINGS
  H3_DATAGRAM = 1

                              SETTINGS
                                ENABLE_CONNECT_PROTOCOL = 1
                                H3_DATAGRAM = 1

STREAM(44): HEADERS
:method = CONNECT
:protocol = connect-ip
:scheme = https
:path = /proxy?ipproto=17
:authority = proxy.example.com
capsule-protocol = ?1

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

                              STREAM(44): DATA
                              Capsule Type = ADDRESS_ASSIGN
                              (Request ID = 0
                               IP Version = 4
                               IP Address = 192.0.2.3
                               IP Prefix Length = 32),
                              (Request ID = 0
                               IP Version = 6
                               IP Address = 2001:db8::1234:1234
                               IP Prefix Length = 128)

                              STREAM(44): DATA
                              Capsule Type = ROUTE_ADVERTISEMENT
                              (IP Version = 4
                               Start IP Address = 198.51.100.2
                               End IP Address = 198.51.100.2
                               IP Protocol = 17),
                              (IP Version = 6
                               Start IP Address = 2001:db8:3456::b
                               End IP Address = 2001:db8:3456::b
                               IP Protocol = 17)
...

DATAGRAM
Quarter Stream ID = 11
Context ID = 0
Payload = Encapsulated IPv6 Packet

DATAGRAM
Quarter Stream ID = 11
Context ID = 0
Payload = Encapsulated IPv4 Packet

9. Extensibility Considerations

Extensions to IP proxying in HTTP can define behavior changes to this mechanism. Such extensions SHOULD define new capsule types to exchange configuration information if needed. It is RECOMMENDED for extensions that modify addressing to specify that their extension capsules be sent before the ADDRESS_ASSIGN capsule and that they do not take effect until the ADDRESS_ASSIGN capsule is parsed. This allows modifications to address assignement to operate atomically. Similarly, extensions that modify routing SHOULD behave similarly with regards to the ROUTE_ADVERTISEMENT capsule.¶

10. Security Considerations

There are significant risks in allowing arbitrary clients to establish a tunnel that permits sending to arbitrary hosts, as that could allow bad actors to send traffic and have it attributed to the IP proxy. IP proxies SHOULD restrict its use to authenticated users. The HTTP Authorization header [HTTP] MAY be used to authenticate clients. More complex authentication schemes are out of scope for this document but can be implemented using extensions.¶

Falsifying IP source addresses in sent traffic has been common for denial of service attacks. Implementations of this mechanism need to ensure that they do not facilitate such attacks. In particular, there are scenarios where an endpoint knows that its peer is only allowed to send IP packets from a given prefix. For example, that can happen through out of band configuration information, or when allowed prefixes are shared via ADDRESS_ASSIGN capsules. In such scenarios, endpoints MUST follow the recommendations from [BCP38] to prevent source address spoofing.¶

Limiting request scope (see Section 4.6) allows two clients to share one of the proxy's external IP addresses if their requests are scoped to different IP protocol numbers. If the proxy receives an ICMP packet destined for that external IP address, it has the option to forward it back to the clients. However, some of these ICMP packets carry part of the original IP packet that triggered the ICMP response. Forwarding such packets can accidentally divulge information about one client's traffic to another client. To avoid this, proxies that forward ICMP on shared external IP addresses MUST inspect the invoking packet included in the ICMP packet and only forward the ICMP packet to the client whose scoping matches the invoking packet.¶

11. IANA Considerations

Acknowledgments

The design of this method was inspired by discussions in the MASQUE working group around [PROXY-REQS]. The authors would like to thank participants in those discussions for their feedback. Additionally, Mike Bishop, Lucas Pardue, and Alejandro Sedeño provided valuable feedback on the document.¶

Most of the text on client configuration is based on the corresponding text in [CONNECT-UDP].¶

Authors' Addresses