| RFC 9484 | Proxying IP in HTTP | October 2023 |
| Pauly, et al. | Standards Track | [Page] |
This document describes how to proxy IP packets in HTTP. This protocol issimilar to UDP proxying in HTTP but allows transmitting arbitrary IP packets.More specifically, this document defines a protocol that allows an HTTP clientto create an IP tunnel through an HTTP server that acts as an IP proxy. Thisdocument updates RFC 9298.¶
This is an Internet Standards Track document.¶
This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841.¶
Information about the current status of this document, any errata, and how to provide feedback on it may be obtained athttps://www.rfc-editor.org/info/rfc9484.¶
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.¶
HTTP provides the CONNECT method (seeSection 9.3.6 of [HTTP]) forcreating a TCP[TCP] tunnel to a destination and a similar mechanismfor UDP[CONNECT-UDP]. However, these mechanisms cannot tunnel otherIP protocols[IANA-PN] nor convey fields of the IP header.¶
This document describes a protocol for tunnelling IP through an HTTP serveracting as an IP-specific proxy over HTTP. This can be used for various usecases, such as remote access VPN, site-to-site VPN, secure point-to-pointcommunication, or general-purpose packet tunnelling.¶
IP proxying operates similarly to UDP proxying[CONNECT-UDP],whereby the proxy itself is identified with an absolute URL, optionallycontaining the traffic's destination. Clients generate these URLs using a URITemplate[TEMPLATE], as described inSection 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 usesHTTP Extended CONNECT, as described in[EXT-CONNECT2] and[EXT-CONNECT3]. When using HTTP/1.x[HTTP/1.1], it uses HTTP Upgrade, as defined inSection 7.8 of [HTTP].¶
This document updates[CONNECT-UDP] to change the "masque" well-known URI;seeSection 12.3.¶
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 thatresponds to the IP proxying request. The term "client" is used in the HTTPsense; the client constructs the IP proxying request. If there are HTTPintermediaries (as defined inSection 3.7 of [HTTP]) between the client andthe IP proxy, those are referred to as "intermediaries" in this document. Theterm "IP proxying endpoints" refers to both the client and the IP proxy.¶
This document uses terminology from[QUIC]. Where this documentdefines protocol types, the definition format uses the notation fromSection 1.3 of [QUIC]. This specification uses the variable-length integer encodingfromSection 16 of [QUIC]. Variable-length integer values do notneed 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 theentire connection.¶
Clients are configured to use IP proxying over HTTP via a URI Template[TEMPLATE]. The URI TemplateMAY contain two variables: "target" and"ipproto"; seeSection 4.6. The optionality of the variables needs to beconsidered when defining the template so that the variable is eitherself-identifying or possible to exclude 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=bobThe following requirements apply to the URI Template:¶
ClientsSHOULD validate the requirements above; however, clientsMAY use ageneral-purpose URI Template implementation that lacks this specificvalidation. If a client detects that any of the requirements above are not metby a URI Template, the clientMUST reject its configuration and abort therequest without sending it to the IP proxy.¶
As with UDP proxying, some client configurations for IP proxies will only allowthe user to configure the proxy host and proxy port. Clients with suchlimitationsMAY attempt to access IP proxying capabilities using the defaulttemplate, 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 IPproxy, respectively. IP proxy deploymentsSHOULD offer service at this locationif they need to interoperate with such clients.¶
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 CapsuleProtocol (seeSection 3.2 of [HTTP-DGRAM]) with HTTP Datagrams in the formatdefined inSection 6.¶
To initiate an IP tunnel associated with a single HTTP stream, a client issuesa request containing the "connect-ip" upgrade token.¶
When sending its IP proxying request, the clientSHALL perform URI Templateexpansion to determine the path and query of its request; seeSection 3.¶
By virtue of the definition of the Capsule Protocol (seeSection 3.2 of [HTTP-DGRAM]), IP proxying requests do not carry any message content.Similarly, successful IP proxying responses also do not carry any messagecontent.¶
IP proxying over HTTPMUST be operated over TLS or QUIC encryption, or anotherequivalent encryption protocol, to provide confidentiality, integrity, andauthentication.¶
Upon receiving an IP proxying request:¶
IP proxiesMUST validate whether the decoded "target" and "ipproto" variablesmeet the requirements inSection 4.6. If they do not, the IP proxyMUST treat therequest as malformed; seeSection 8.1.1 of [HTTP/2] andSection 4.1.2 of [HTTP/3].If the "target" variable is a DNS name, the IP proxyMUST perform DNSresolution (to obtain the corresponding IPv4 and/or IPv6 addresses via A and/orAAAA records) before replying to the HTTP request. If errors occur during thisprocess, the IP proxyMUST reject the request andSHOULD send details using anappropriate Proxy-Status header field[PROXY-STATUS]. For example,if DNS resolution returns an error, the proxy can use thedns_error proxyerror type fromSection 2.3.2 of [PROXY-STATUS].¶
The lifetime of the IP forwarding tunnel is tied to the IP proxying requeststream. The IP proxyMUST maintain all IP address and route assignmentsassociated with the IP forwarding tunnel while the request stream is open. IPproxiesMAY choose to tear down the tunnel due to a period of inactivity, buttheyMUST close the request stream when doing so.¶
A successful IP proxying response (as defined in Sections4.3 and4.5)indicates that the IP proxy has established an IP tunnel and is willing toproxy IP payloads. Any response other than a successful IP proxying response indicates thatthe request has failed; thus, the clientMUST abort the request.¶
Along with a successful IP proxying response, the IP proxy can send capsules to assignaddresses and advertise routes to the client (Section 4.7). The client canalso assign addresses and advertise routes to the IP proxy fornetwork-to-network routing.¶
When using HTTP/1.1[HTTP/1.1], an IP proxying request will meet the followingrequirements:¶
An IP proxying request that does not conform to these restrictions ismalformed. The recipient of such a malformed requestMUST respond with an errorandSHOULD use the 400 (Bad Request) status code.¶
For example, if the client is configured with URI Template"https://example.org/.well-known/masque/ip/{target}/{ipproto}/" and wishes toopen an IP forwarding tunnel with no target or protocol limitations, it couldsend the following request:¶
GET https://example.org/.well-known/masque/ip/*/*/ HTTP/1.1Host: example.orgConnection: UpgradeUpgrade: connect-ipCapsule-Protocol: ?1
The server indicates a successful IP proxying response by replying with the followingrequirements:¶
If any of these requirements are not met, the clientMUST treat this proxyingattempt as failed and close the connection.¶
For example, the server could respond with:¶
HTTP/1.1 101 Switching ProtocolsConnection: UpgradeUpgrade: connect-ipCapsule-Protocol: ?1
When using HTTP/2[HTTP/2] or HTTP/3[HTTP/3], IP proxying requests use HTTPExtended CONNECT. This requires that servers send an HTTP Setting, as specifiedin[EXT-CONNECT2] and[EXT-CONNECT3], and that requests use HTTPpseudo-header fields with the following requirements:¶
An IP proxying request that does not conform to these restrictions ismalformed; seeSection 8.1.1 of [HTTP/2] andSection 4.1.2 of [HTTP/3].¶
For example, if the client is configured with URI Template"https://example.org/.well-known/masque/ip/{target}/{ipproto}/" and wishes toopen an IP forwarding tunnel with no target or protocol limitations, it couldsend the following request:¶
HEADERS:method = CONNECT:protocol = connect-ip:scheme = https:path = /.well-known/masque/ip/*/*/:authority = example.orgcapsule-protocol = ?1
The server indicates a successful IP proxying response by replying with the followingrequirements:¶
If any of these requirements are not met, the clientMUST treat this proxyingattempt as failed and abort the request. As an example, any status code in the3xx range will be treated as a failure and cause the client to abort therequest.¶
For example, the server could respond with:¶
HEADERS:status = 200capsule-protocol = ?1
Unlike UDP proxying requests, which require specifying a target host, IPproxying requests can allow endpoints to send arbitrary IP packets to any host.The client can choose to restrict a given request to a specific IP prefix or IPprotocol by adding parameters to its request. When the IP proxy knows that arequest is scoped to a target prefix or protocol, it can leverage thisinformation to optimize its resource allocation; for example, the IP proxy canassign the same public IP address to two IP proxying requests that are scopedto different prefixes and/or different protocols.¶
The scope of the request is indicated by the client to the IP proxy via the"target" and "ipproto" variables of the URI Template; seeSection 3.Both the "target" and "ipproto" variables are optional; if they are notincluded, they are considered to carry the wildcard value "*".¶
The variable "target" contains a hostname or IP prefix of a specific host towhich the client wants to proxy packets. If the "target" variable is notspecified or its value is "*", the client is requesting to communicate withany allowable host. "target" supports using DNS names, IPv6 prefixes, and IPv4prefixes. Note that IPv6 scoped addressing zone identifiers[IPv6-ZONE-ID] arenot supported. If the target is an IP prefix (IP address optionally followed bya percent-encoded slash followed by the prefix length in bits), the requestwill only support a single IP version. If the target is a hostname, the IPproxy is expected to perform DNS resolution to determine which route(s) toadvertise to the client. The IP proxySHOULD send a ROUTE_ADVERTISEMENT capsulethat includes routes for all addresses that were resolved for the requestedhostname, that are accessible to the IP proxy, and belong to an address familyfor which the IP proxy also sends an Assigned Address.¶
The variable "ipproto" contains an Internet Protocol Number; see the defined list in the"Assigned Internet Protocol Numbers" IANA registry[IANA-PN]. If present, itspecifies that a client only wants to proxy a specific IP protocol for thisrequest. If the value is "*", or the variable is not included, the client isrequesting to use any IP protocol. The IP protocol indicated in the "ipproto"variable represents an allowable next header value carried in IP headers thatare directly sent in HTTP Datagrams (the outermost IP headers). ICMP trafficis always allowed, regardless of the value of this field.¶
Using the terms IPv6address, IPv4address, and reg-name from[URI], the"target" and "ipproto" variablesMUST adhere to the format inFigure 6, using notation from[ABNF]. Additionally:¶
target = IPv6prefix / IPv4prefix / reg-name / "*"IPv6prefix = IPv6address ["%2F" 1*3DIGIT]IPv4prefix = IPv4address ["%2F" 1*2DIGIT]ipproto = 1*3DIGIT / "*"
IP proxiesMAY perform access control using the scoping information provided bythe client, i.e., if the client is not authorized to access any of the destinationsincluded in the scope, then the IP proxy can immediately reject the request.¶
This document defines multiple new capsule types that allow endpoints toexchange IP configuration information. Both endpointsMAY send any number ofthese new capsules.¶
The ADDRESS_ASSIGN capsule (capsule type 0x01) allows an endpoint to assign its peer a list of IP addresses orprefixes. Every capsule contains the full list of IPprefixes currently assigned to the receiver. Any of these addresses can be usedas the source address on IP packets originated by the receiver of this capsule.¶
ADDRESS_ASSIGN Capsule { Type (i) = 0x01, Length (i), Assigned Address (..) ...,}The ADDRESS_ASSIGN capsule contains a sequence of zero or more AssignedAddresses.¶
Assigned Address { Request ID (i), IP Version (8), IP Address (32..128), IP Prefix Length (8),}Each Assigned Address contains the following fields:¶
Request identifier, encoded as a variable-length integer. If this addressassignment is in response to an Address Request (seeSection 4.7.2), then thisfieldSHALL contain the value of the corresponding field in the request.Otherwise, this fieldSHALL be zero.¶
IP Version of this address assignment, encoded as an unsigned 8-bit integer. ItMUST be either 4 or 6.¶
Assigned IP address. If the IP Version field has value 4, the IP AddressfieldSHALL have a length of 32 bits. If the IP Version field has value 6, theIP Address fieldSHALL have a length of 128 bits.¶
The number of bits in the IP address that are used to define the prefix thatis being assigned, encoded as an unsigned 8-bit integer. ThisMUST be less thanor equal to the length of the IP Address field in bits. If the prefix lengthis equal to the length of the IP address, the receiver of this capsule isallowed to send packets from a single source address. If the prefix length isless than the length of the IP address, the receiver of this capsule is allowedto send packets from any source address that falls within the prefix. If theprefix length is strictly less than the length of the IP address in bits, thelower bits of the IP Address field that are not covered by the prefix lengthMUST all be set to 0.¶
If any of the capsule fields are malformed upon reception, the receiver of thecapsuleMUST follow the error-handling procedure defined inSection 3.3 of [HTTP-DGRAM].¶
If an ADDRESS_ASSIGN capsule does not contain an address that was previouslytransmitted in another ADDRESS_ASSIGN capsule, it indicates that the addresshas been removed. An ADDRESS_ASSIGN capsule can also be empty, indicating thatall addresses have been removed.¶
In some deployments of IP proxying in HTTP, an endpoint needs to be assigned anaddress by its peer before it knows what source address to set on its ownpackets. For example, in the remote access VPN case (Section 8.1), theclient cannot send IP packets until it knows what address to use.In thesedeployments, the endpoint that is expecting an address assignmentMUST send anADDRESS_REQUEST capsule. This isn't required if the endpoint does not need anyaddress assignment, for example, when it is configured out-of-band with staticaddresses.¶
While ADDRESS_ASSIGN capsules are commonly sent in response to ADDRESS_REQUESTcapsules, endpointsMAY send ADDRESS_ASSIGN capsules unprompted.¶
The ADDRESS_REQUEST capsule (capsule type 0x02) allows an endpoint to request assignment of IP addresses from its peer.The capsule allows the endpoint to optionally indicate a preference for whichaddress it would get assigned.¶
ADDRESS_REQUEST Capsule { Type (i) = 0x02, Length (i), Requested Address (..) ...,}The ADDRESS_REQUEST capsule contains a sequence of one or more RequestedAddresses.¶
Requested Address { Request ID (i), IP Version (8), IP Address (32..128), IP Prefix Length (8),}Each Requested Address contains the following fields:¶
Request identifier, encoded as a variable-length integer. This is theidentifier of this specific address request. Each request from a given endpointcarries a different identifier. Request IDsMUST NOT be reused by an endpointandMUST NOT be zero.¶
IP Version of this address request, encoded as an unsigned 8-bit integer. ItMUST be either 4 or 6.¶
Requested IP address. If the IP Version field has value 4, the IP AddressfieldSHALL have a length of 32 bits. If the IP Version field has value 6, theIP Address fieldSHALL have a length of 128 bits.¶
Length of the IP Prefix requested in bits, encoded as an unsigned 8-bitinteger. ItMUST be less than or equal to the length of the IP Address field inbits. If the prefix length is strictly less than the length of the IP addressin bits, the lower bits of the IP Address field that are not covered by theprefix lengthMUST all be set to 0.¶
If the IP address is all-zero (0.0.0.0 or ::), this indicates that the senderis requesting an address of that address family but does not have a preferencefor a specific address. In that scenario, the prefix length still indicates thesender's preference for the prefix length it is requesting.¶
If any of the capsule fields are malformed upon reception, the receiver of thecapsuleMUST follow the error-handling procedure defined inSection 3.3 of [HTTP-DGRAM].¶
Upon receiving the ADDRESS_REQUEST capsule, an endpointSHOULD assign one ormore IP addresses to its peer and then respond with an ADDRESS_ASSIGN capsuleto inform the peer of the assignment. For each Requested Address, the receiverof the ADDRESS_REQUEST capsuleSHALL respond with an Assigned Address with amatching Request ID. If the requested address was assigned, the IP Address andIP Prefix Length fields in the Assigned Address responseSHALL be set to theassigned values. If the requested address was not assigned, the IP addressSHALL be all-zero, and the IP Prefix LengthSHALL be the maximum length(0.0.0.0/32 or ::/128) to indicate that no address was assigned. These addressrejectionsSHOULD NOT be included in subsequent ADDRESS_ASSIGN capsules. Notethat other Assigned Address entries that do not correspond to any Request IDcan also be contained in the same ADDRESS_ASSIGN response.¶
If an endpoint receives an ADDRESS_REQUEST capsule that contains zero RequestedAddresses, itMUST abort the IP proxying request stream.¶
Note that the ordering of Requested Addresses does not carry any semantics.Similarly, the Request ID is only meant as a unique identifier; it does notconvey any priority or importance.¶
The ROUTE_ADVERTISEMENT capsule (capsule type 0x03) allows an endpoint to communicate to its peer that it is willingto route traffic to a set of IP address ranges. This indicates that the senderhas an existing route to each address range and notifies its peer that, if thereceiver of the ROUTE_ADVERTISEMENT capsule sends IP packets for one of theseranges in HTTP Datagrams, the sender of the capsule will forward them along itspreexisting route. Any address that is in one of the address ranges can beused as the destination address on IP packets originated by the receiver ofthis capsule.¶
ROUTE_ADVERTISEMENT Capsule { Type (i) = 0x03, Length (i), IP Address Range (..) ...,}The ROUTE_ADVERTISEMENT capsule contains a sequence of zero or more IP AddressRanges.¶
IP Address Range { IP Version (8), Start IP Address (32..128), End IP Address (32..128), IP Protocol (8),}Each IP Address Range contains the following fields:¶
IP Version of this range, encoded as an unsigned 8-bit integer. ItMUST beeither 4 or 6.¶
Inclusive start and end IP address of the advertised range. If the IP Versionfield has value 4, these fieldsSHALL have a length of 32 bits. If the IPVersion field has value 6, these fieldsSHALL have a length of 128 bits. TheStart IP AddressMUST be less than or equal to the End IP Address.¶
The Internet Protocol Number for traffic that can be sent to this range,encoded as an unsigned 8-bit integer. If the value is 0, all protocols areallowed. If the value is not 0, it represents an allowable next header valuecarried in IP headers that are sent directly in HTTP Datagrams (the outermostIP headers). ICMP traffic is always allowed, regardless of the value of thisfield.¶
If any of the capsule fields are malformed upon reception, the receiver of thecapsuleMUST follow the error-handling procedure defined inSection 3.3 of [HTTP-DGRAM].¶
Upon receiving the ROUTE_ADVERTISEMENT capsule, an endpointMAY update itslocal state regarding what its peer is willing to route (subject to localpolicy), such as by installing entries in a routing table.¶
Each ROUTE_ADVERTISEMENT contains the full list of address ranges. If multipleROUTE_ADVERTISEMENT capsules are sent in one direction, eachROUTE_ADVERTISEMENT capsule supersedes prior ones. In other words, if a givenaddress range was present in a prior capsule but the most recently receivedROUTE_ADVERTISEMENT capsule does not contain it, the receiver will considerthat range withdrawn.¶
If multiple ranges using the same IP protocol were to overlap, some routingtable implementations might reject them. To prevent overlap, the ranges areordered; this places the burden on the sender and makes verification by thereceiver much simpler. If an IP Address Range A precedes an IP Address Range Bin the same ROUTE_ADVERTISEMENT capsule, theyMUST follow these requirements:¶
If an endpoint receives a ROUTE_ADVERTISEMENT capsule that does not meet theserequirements, itMUST abort the IP proxying request stream.¶
Since setting the IP protocol to zero indicates all protocols are allowed, therequirements above make it possible for two routes to overlap when one has its IPprotocol set to zero and the other has it set to non-zero. EndpointsMUST NOT send aROUTE_ADVERTISEMENT capsule with routes that overlap in such a way. Validatingthis requirement isOPTIONAL, but if an endpoint detects the violation, itMUSTabort the IP proxying request stream.¶
Both request scoping (seeSection 4.6) and the ROUTE_ADVERTISEMENT capsule (seeSection 4.7.3) use Internet Protocol Numbers. These numbers represent both upperlayers (as defined inSection 2 of [IPv6], with examples that include TCP andUDP) and IPv6 extension headers (as defined inSection 4 of [IPv6], with examplesthat include Fragment and Options headers). IP proxiesMAY reject requests to scopeto protocol numbers that are used for extension headers. Upon receivingpackets, implementations that support scoping or routing by Internet Protocol NumberMUST walk the chain of extensions to find the outermost non-extension Internet ProtocolNumber to match against the scoping rule. Note that the ROUTE_ADVERTISEMENTcapsule uses Internet Protocol Number 0 to indicate that all protocols are allowed;it does not restrict the route to the IPv6 Hop-by-Hop Options header(Section 4.3 of [IPv6]).¶
The mechanism for proxying IP in HTTP defined in this document allows futureextensions to exchange HTTP Datagrams that carry different semantics from IPpayloads. Some of these extensions can augment IP payloads with additional dataor compress IP header fields, while others can exchange data that is completelyseparate from IP payloads. In order to accomplish this, all HTTP Datagramsassociated with IP proxying request streams start with a Context ID field; seeSection 6.¶
Context IDs are 62-bit integers (0 to 262-1). Context IDs areencoded as variable-length integers; seeSection 16 of [QUIC]. The Context IDvalue of 0 is reserved for IP payloads, while non-zero values are dynamicallyallocated. Non-zero even-numbered Context IDs are client-allocated, andodd-numbered Context IDs are proxy-allocated. The Context ID namespace is tiedto a given HTTP request; it is possible for a Context ID with the same numericvalue to be simultaneously allocated in distinct requests, potentially withdifferent semantics. Context IDsMUST NOT be re-allocated within a given HTTPrequest butMAY be allocated in any order. The Context ID allocationrestrictions to the use of even-numbered and odd-numbered Context IDs exist inorder to avoid the need for synchronization between endpoints. However, once aContext ID has been allocated, those restrictions do not apply to the use ofthe 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 thesemantics and format of a given Context ID. This document does not define howregistration occurs. Future extensionsMAY use HTTP header fields or capsulesto register Context IDs. Depending on the method being used, it is possible fordatagrams to be received with Context IDs that have not yet been registered.For instance, this can be due to reordering of the packet containing thedatagram and the packet containing the registration message during transmission.¶
When associated with IP proxying request streams, the HTTP Datagram Payloadfield of HTTP Datagrams (see[HTTP-DGRAM]) has the format defined inFigure 13. Note that, when HTTP Datagrams are encoded using QUIC DATAGRAMframes, the Context ID field defined below directly follows the Quarter StreamID field that 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:¶
A variable-length integer that contains the value of the Context ID. If anHTTP/3 datagram that carries an unknown Context ID is received, the receiverSHALL either drop that datagram silently or buffer it temporarily (on the orderof a round trip) while awaiting the registration of the corresponding ContextID.¶
The payload of the datagram, whose semantics depend on value of the previousfield. 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).¶
This document defines a tunneling mechanism that is conceptually an IP link.However, because links are attached to IP routers, implementations might needto handle some of the responsibilities of IP routers if they do not delegatethem to another implementation, such as a kernel.¶
The IP forwarding tunnels described in this document are not fully featured"interfaces" in the IPv6 addressing architecture sense[IPv6-ADDR].In particular, they do not necessarily have IPv6 link-local addresses.Additionally, IPv6 stateless autoconfiguration or router advertisement messagesare not used in such interfaces, and neither is neighbor discovery.¶
When using HTTP/2 or HTTP/3, a clientMAY optimistically start sending proxied IP packets before receivingthe response to its IP proxying request, noting however that those may not beprocessed by the IP proxy if it responds to the request with a failure or ifthe datagrams are received by the IP proxy before the request. Since receivingaddresses and routes is required in order to know that a packet can be sentthrough the tunnel, such optimistic packets might be dropped by the IP proxy ifit chooses to provide different addressing or routing information than what theclient assumed.¶
Note that it is possible for multiple proxied IP packets to be encapsulated inthe same outer packet, for example, because a QUIC packet can carry more than one QUICDATAGRAM frame. It is also possible for a proxied IP packet to span multipleouter packets, because a DATAGRAM capsule can be split across multiple QUIC orTCP packets.¶
The requirements in this section are a repetition of requirements that apply toIP routers in general and might not apply to implementations of IP proxyingthat rely on external software for routing.¶
When an endpoint receives an HTTP Datagram containing an IP packet, it willparse the packet's IP header, perform any local policy checks (e.g., sourceaddress validation), check their routing table to pick an outbound interface,and then send the IP packet on that interface or pass it to a localapplication. The endpoint can also choose to drop any received packets insteadof forwarding them. If a received IP packet fails any correctness or policychecks, that is a forwarding error, not a protocol violation, as far as IPproxying is concerned; seeSection 7.2.1. IP proxying endpointsMAYimplement additional filtering policies on the IP packets they forward.¶
In the other direction, when an endpoint receives an IP packet, it checks to seeif the packet matches the routes mapped for an IP tunnel and performs the sameforwarding checks as above before transmitting the packet over HTTP Datagrams.¶
When IP proxying endpoints forward IP packets between different links, theywill decrement the IP Hop Count (or TTL) upon encapsulation but not upondecapsulation. In other words, the Hop Count is decremented right before an IPpacket is transmitted in an HTTP Datagram. This prevents infinite loops in thepresence of routing loops and matches the choices in IPsec[IPSEC].This does not apply to IP packets generated by the IP proxying endpoint itself.¶
Implementers need to ensure that they do not forward any link-local trafficbeyond the IP proxying interface that it was received on. IP proxying endpointsalso need to properly reply to packets destined to link-local multicastaddresses.¶
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 inturn be sent in QUIC DATAGRAM frames that cannot be fragmented[DGRAM], the MTU of an IP tunnel can be limited by the MTU of theQUIC connection that IP proxying is operating over. This can lead to situationswhere the IPv6 minimum link MTU is violated. IP proxying endpoints that operateas routers and support IPv6MUST ensure that the IP tunnel link MTU is at least1280 bytes (i.e., that they can send HTTP Datagrams with payloads of at least 1280bytes). This can be accomplished using various techniques:¶
If an endpoint is using QUIC DATAGRAM frames to convey IPv6 packets and itdetects that the QUIC MTU is too low to allow sending 1280 bytes, itMUST abortthe IP proxying request stream.¶
Since IP proxying endpoints often forward IP packets onwards to other networkinterfaces, they need to handle errors in the forwarding process. For example,forwarding can fail if the endpoint does not have a route for the destinationaddress, if it is configured to reject a destination prefix by policy, or ifthe MTU of the outgoing link is lower than the size of the packet to beforwarded. In such scenarios, IP proxying endpointsSHOULD use ICMP[ICMP][ICMPv6] to signal the forwarding error to itspeer by generating ICMP packets and sending them using HTTP Datagrams.¶
Endpoints are free to select the most appropriate ICMP errors to send. Someexamples that are relevant for IP proxying include the following:¶
In order to receive these errors, endpoints need to be prepared to receive ICMPpackets. If an endpoint does not send ROUTE_ADVERTISEMENT capsules, such as aclient opening an IP flow through an IP proxy, itSHOULD process proxied ICMPpackets from its peer in order to receive these errors. Note that ICMP messagescan originate from a source address different from that of the IP proxyingpeer and also from outside the target if scoping is in use (seeSection 4.6).¶
IP proxying in HTTP enables many different use cases that can benefit from IPpacket proxying and tunnelling. These examples are provided to help illustratesome of the ways in which IP proxying in HTTP can be used.¶
The following example shows a point-to-network VPN setup, where a clientreceives a set of local addresses and can send to any remote host through theIP proxy. Such VPN setups can be either full-tunnel or split-tunnel.¶
In this case, the client does not specify any scope in its request. The IPproxy assigns the client an IPv4 address (192.0.2.11) and a full-tunnel routeof all IPv4 addresses (0.0.0.0/0). The client can then send to any IPv4 hostusing its assigned address as its source address.¶
[[ From Client ]] [[ From IP Proxy ]]SETTINGS H3_DATAGRAM = 1 SETTINGS ENABLE_CONNECT_PROTOCOL = 1 H3_DATAGRAM = 1STREAM(44): HEADERS:method = CONNECT:protocol = connect-ip:scheme = https:path = /vpn:authority = proxy.example.comcapsule-protocol = ?1 STREAM(44): HEADERS :status = 200 capsule-protocol = ?1STREAM(44): DATACapsule 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) // AnyDATAGRAMQuarter Stream ID = 11Context ID = 0Payload = Encapsulated IP Packet DATAGRAM Quarter Stream ID = 11 Context ID = 0 Payload = Encapsulated IP Packet
A setup for a split-tunnel VPN (the case where the client can only access aspecific set of private subnets) is quite similar. In this case, the advertisedroute is restricted to 192.0.2.0/24, rather than 0.0.0.0/0.¶
[[ 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.41 IP Protocol = 0) // Any (IP Version = 4 Start IP Address = 192.0.2.43 End IP Address = 192.0.2.255 IP Protocol = 0) // Any
The following example shows how to connect a branch office network to acorporate network such that all machines on those networks can communicate. Inthis example, the IP proxying client is attached to the branch office network192.0.2.0/24, and the IP proxy is attached to the corporate network203.0.113.0/24. There are legacy clients on the branch office network that onlyallow maintenance requests from machines on their subnet, so the IP proxy isprovisioned with an IP address from that subnet.¶
In this case, the client does not specify any scope in its request. The IPproxy assigns the client an IPv4 address (203.0.113.100) and a split-tunnelroute to the corporate network (203.0.113.0/24). The client assigns the IPproxy an IPv4 address (192.0.2.200) and a split-tunnel route to the branchoffice network (192.0.2.0/24). This allows hosts on both networks tocommunicate with each other and allows the IP proxy to perform maintenance onlegacy hosts in the branch office. Note that IP proxying endpoints willdecrement the IP Hop Count (or TTL) when encapsulating forwarded packets, soprotocols that require that field be set to 255 will not function.¶
[[ From Client ]] [[ From IP Proxy ]]SETTINGS H3_DATAGRAM = 1 SETTINGS ENABLE_CONNECT_PROTOCOL = 1 H3_DATAGRAM = 1STREAM(44): HEADERS:method = CONNECT:protocol = connect-ip:scheme = https:path = /corp:authority = proxy.example.comcapsule-protocol = ?1 STREAM(44): HEADERS :status = 200 capsule-protocol = ?1STREAM(44): DATACapsule Type = ADDRESS_ASSIGN(Request ID = 0IP Version = 4IP Address = 192.0.2.200IP Prefix Length = 32)STREAM(44): DATACapsule Type = ROUTE_ADVERTISEMENT(IP Version = 4Start IP Address = 192.0.2.0End IP Address = 192.0.2.255IP Protocol = 0) // Any STREAM(44): DATA Capsule Type = ADDRESS_ASSIGN (Request ID = 0 IP Version = 4 IP Address = 203.0.113.100 IP Prefix Length = 32) STREAM(44): DATA Capsule Type = ROUTE_ADVERTISEMENT (IP Version = 4 Start IP Address = 203.0.113.0 End IP Address = 203.0.113.255 IP Protocol = 0) // AnyDATAGRAMQuarter Stream ID = 11Context ID = 0Payload = Encapsulated IP Packet DATAGRAM Quarter Stream ID = 11 Context ID = 0 Payload = Encapsulated IP Packet
The following example shows an IP flow forwarding setup, where a clientrequests to establish a forwarding tunnel to target.example.com using the Stream Control Transmission Protocol (SCTP) (IPprotocol 132) and receives a single local address and remote address it canuse for transmitting packets. A similar approach could be used for any other IPprotocol that isn't easily proxied with existing HTTP methods, such as ICMP,Encapsulating Security Payload (ESP), etc.¶
In this case, the client specifies both a target hostname and an Internet ProtocolNumber in the scope of its request, indicating that it only needs tocommunicate with a single host. The IP proxy is able to perform DNS resolutionon behalf of the client and allocate a specific outbound socket for the clientinstead of allocating an entire IP address to the client. In this regard, therequest is similar to a regular CONNECT proxy request.¶
The IP proxy assigns a single IPv6 address to the client (2001:db8:1234::a) anda route to a single IPv6 host (2001:db8:3456::b) scoped to SCTP. The clientcan send and receive SCTP IP packets to the remote host.¶
[[ From Client ]] [[ From IP Proxy ]]SETTINGS H3_DATAGRAM = 1 SETTINGS ENABLE_CONNECT_PROTOCOL = 1 H3_DATAGRAM = 1STREAM(44): HEADERS:method = CONNECT:protocol = connect-ip:scheme = https:path = /proxy?target=target.example.com&ipproto=132:authority = proxy.example.comcapsule-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)DATAGRAMQuarter Stream ID = 11Context ID = 0Payload = Encapsulated SCTP/IP Packet DATAGRAM Quarter Stream ID = 11 Context ID = 0 Payload = Encapsulated SCTP/IP Packet
The following example shows a setup where a client is proxying UDP packetsthrough an IP proxy in order to control connection establishment racing throughan IP proxy, as defined in Happy Eyeballs[HEv2]. This example is avariant of the proxied flow but highlights how IP-level proxying can enablenew capabilities, even for TCP and UDP.¶
As with proxied flows, the client specifies both a target hostname and an InternetProtocol Number in the scope of its request. When the IP proxy performs DNSresolution on behalf of the client, it can send the various remote addressoptions to the client as separate routes. It can also ensure that the clienthas both IPv4 and IPv6 addresses assigned.¶
The IP proxy assigns both an IPv4 address (192.0.2.3) and an IPv6address (2001:db8:1234::a) to the client, as well as an IPv4 route(198.51.100.2) and an IPv6 route (2001:db8:3456::b), which represent theresolved addresses of the target hostname, scoped to UDP. The client can sendand receive UDP IP packets to either one of the IP proxy addresses to enableHappy Eyeballs through the IP proxy.¶
[[ From Client ]] [[ From IP Proxy ]]SETTINGS H3_DATAGRAM = 1 SETTINGS ENABLE_CONNECT_PROTOCOL = 1 H3_DATAGRAM = 1STREAM(44): HEADERS:method = CONNECT:protocol = connect-ip:scheme = https:path = /proxy?target=target.example.com&ipproto=17:authority = proxy.example.comcapsule-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)...DATAGRAMQuarter Stream ID = 11Context ID = 0Payload = Encapsulated IPv6 PacketDATAGRAMQuarter Stream ID = 11Context ID = 0Payload = Encapsulated IPv4 Packet
Extensions to IP proxying in HTTP can define behavior changes to thismechanism. Such extensionsSHOULD define new capsule types to exchangeconfiguration information if needed. It isRECOMMENDED for extensions thatmodify addressing to specify that their extension capsules be sent before theADDRESS_ASSIGN capsule and that they do not take effect until theADDRESS_ASSIGN capsule is parsed. This allows modifications to addressassignment to operate atomically. Similarly, extensions that modify routingSHOULD behave similarly with regard to the ROUTE_ADVERTISEMENT capsule.¶
Bursty traffic can often lead to temporally correlated packet losses; in turn,this can lead to suboptimal responses from congestion controllers in protocolsrunning inside the tunnel. To avoid this, IP proxying endpointsSHOULD striveto avoid increasing burstiness of IP traffic; theySHOULD NOT queue packets inorder to increase batching beyond the minimal amount required to take advantageof hardware offloads.¶
When the protocol running inside the tunnel uses congestion control (e.g.,[TCP] or[QUIC]), the proxied traffic will incur at least two nestedcongestion controllers. When tunneled packets are sent using QUIC DATAGRAMframes, the outer HTTP connectionMAY disable congestion control for thosepackets that contain only QUIC DATAGRAM frames encapsulating IP packets.Implementers will benefit from reading the guidance inSection 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 trafficwill incur at least two nested loss recovery mechanisms. This can reduceperformance, as both can sometimes independently retransmit the same data. Toavoid this, IP proxyingSHOULD be performed over HTTP/3 to allow leveraging theQUIC DATAGRAM frame.¶
When using HTTP/3 with the QUIC Datagram extension[DGRAM], IP packets aretransmitted in QUIC DATAGRAM frames. Since these frames cannot be fragmented,they can only carry packets up to a given length determined by the QUICconnection configuration and the Path MTU (PMTU). If an endpoint is using QUICDATAGRAM frames and it attempts to route an IP packet through the tunnel thatwill not fit inside a QUIC DATAGRAM frame, the IP proxySHOULD NOT send the IPpacket in a DATAGRAM capsule, as that defeats the end-to-end unreliabilitycharacteristic that methods such as Datagram Packetization Layer PMTU Discovery(DPLPMTUD) depend on[DPLPMTUD]. In this scenario, the endpointSHOULD drop the IP packet and send an ICMP Packet Too Big message to the senderof the dropped packet; seeSection 3.2 of [ICMPv6].¶
If an IP proxying endpoint with a connection containing an IP proxying requeststream disables congestion control, it cannot signal Explicit CongestionNotification (ECN)[ECN] support on that outer connection. That is,the QUIC senderMUST mark all IP headers with the Not ECN-Capable Transport (Not-ECT) codepoint for QUICpackets that are outside of congestion control. The endpoint can still reportECN feedback via QUIC ACK_ECN frames or the TCP ECN-Echo (ECE) bit, as the peer might nothave disabled congestion control.¶
Conversely, if congestion control is not disabled on the outer congestion, theguidance in[ECN-TUNNEL] about transferring ECN marks between innerand outer IP headers does not apply because the outer connection will reactcorrectly to congestion notifications if it uses ECN. The inner traffic canalso use ECN, independently of whether it is in use on the outer connection.¶
Tunneled IP packets can have Differentiated Services Code Points (DSCPs)[DSCP] set in the traffic class IP header field to request aparticular per-hop behavior. If an IP proxying endpoint is configured as partof a Differentiated Services domain, itMAY implement traffic differentiationbased on these markings. However, the use of HTTP can limit the possibilitiesfor differentiated treatment of the tunneled IP packets on the path between theIP proxying endpoints.¶
When an HTTP connection is congestion-controlled, marking packets withdifferent DSCPs can lead to reordering between them, and that can in turn leadthe underlying transport connection's congestion controller to perform poorly.If tunneled packets are subject to congestion control by the outer connection,they need to avoid carrying DSCP markings that are not equivalent in forwardingbehavior to prevent this situation. In this scenario, the IP proxying endpointMUST NOT copy the DSCP field from the inner IP header to the outer IP header ofthe packet carrying this packet. Instead, an application would need to useseparate connections to the proxy, one for each DSCP. Note that this documentdoes not define a way for requests to scope to particular DSCP values; suchsupport is left to future extensions.¶
If tunneled packets use QUIC datagrams and are not subject to congestioncontrol by the outer connection, the IP proxying endpointsMAY translate theDSCP field value from the tunneled traffic to the outer IP header. IP proxyingendpointsMUST NOT coalesce multiple inner packets into the same outer packetunless they have the same DSCP marking or an equivalent traffic class. Notethat the ability to translate DSCP values is dependent on the tunnel ingressand egress belonging to the same Differentiated Service domain or not.¶
There are significant risks in allowing arbitrary clients to establish a tunnelthat permits sending to arbitrary hosts, regardless of whether tunnels arescoped to specific hosts or not. Bad actors could abuse this capability to sendtraffic and have it attributed to the IP proxy. HTTP servers that support IPproxyingSHOULD restrict its use to authenticated users. Depending on thedeployment, possible authentication mechanisms include mutual TLS between IPproxying endpoints, HTTP-based authentication via the HTTP Authorization header[HTTP], or even bearer tokens. Proxies can enforce policies for authenticatedusers to further constrain client behavior or deal with possible abuse. Forexample, proxies can rate limit individual clients that send an excessivelylarge amount of traffic through the proxy. As another example, proxies canrestrict address (prefix) assignment to clients based on certain clientattributes, such as geographic location.¶
Address assignment can have privacy implications for endpoints. For example, ifa proxy partitions its address space by the number of authenticated clients andthen assigns distinct address ranges to each client, target hosts could usethis information to determine when IP packets correspond to the same client.Avoiding such tracking vectors may be important for certain proxy deployments.ProxiesSHOULD avoid persistent per-client address (prefix) assignment whenpossible.¶
Falsifying IP source addresses in sent traffic has been common for denial-of-service attacks. Implementations of this mechanism need to ensure that they donot facilitate such attacks. In particular, there are scenarios where anendpoint knows that its peer is only allowed to send IP packets from a givenprefix. For example, that can happen through out-of-band configurationinformation or when allowed prefixes are shared via ADDRESS_ASSIGN capsules.In such scenarios, endpointsMUST follow the recommendations from[BCP38] to prevent source address spoofing.¶
Limiting request scope (seeSection 4.6) allows two clients to share one of theproxy's external IP addresses if their requests are scoped to different InternetProtocol Numbers. If the proxy receives an ICMP packet destined for thatexternal 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 thattriggered the ICMP response. Forwarding such packets can accidentally divulgeinformation about one client's traffic to another client. To avoid this,proxies that forward ICMP on shared external IP addressesMUST inspect theinvoking packet included in the ICMP packet and only forward the ICMP packet tothe client whose scoping matches the invoking packet.¶
Implementers will benefit from reading the guidance in[TUNNEL-SECURITY]. Since there are known risks with some IPv6extension headers (e.g.,[ROUTING-HDR]), implementers need to followthe latest guidance regarding handling of IPv6 extension headers.¶
Transferring DSCP markings from inner to outer packets (seeSection 10.3) exposes end-to-end flow level information to anon-path observer between the IP proxying endpoints. This can potentially exposea single end-to-end flow. Because of this, such use of DSCPs inprivacy-sensitive contexts isNOT RECOMMENDED.¶
Opportunistic sending of IP packets (seeSection 7.1) is not allowedin HTTP/1.x because a server could reject the HTTP Upgrade andattempt to parse the IP packets as a subsequent HTTP request,allowing request smuggling attacks; see[OPTIMISTIC]. In particular,an intermediary that re-encodes a request from HTTP/2 or 3 toHTTP/1.1MUST NOT forward any received capsules until it has parsed asuccessful IP proxying response.¶
IANA has registered "connect-ip" in the "HTTP UpgradeTokens" registry maintained at<https://www.iana.org/assignments/http-upgrade-tokens>.¶
IANA has created the "MASQUE URI Suffixes" registry maintained at<https://www.iana.org/assignments/masque>. The registration policy is Expert Review; seeSection 4.5 of [IANA-POLICY]. This new registry governs the path segment thatimmediately follows "masque" in paths that start with "/.well-known/masque/";see<https://www.iana.org/assignments/well-known-uris> for the registrationof "masque" in the "Well-Known URIs" registry.¶
This new registry contains threecolumns:¶
An ASCII string containing only characters allowed in tokens; seeSection 5.6.2 of [HTTP]. Entries in this registryMUST all have distinctentries in this column.¶
A description of the entry.¶
An optional reference defining the use of the entry.¶
The registry's initial entries are as follows:¶
| Path Segment | Description | Reference |
|---|---|---|
| udp | UDP Proxying | RFC 9298 |
| ip | IP Proxying | RFC 9484 |
Designated experts for this registry are advised that they should approve allrequests as long as the expert believes that both (1) the requested PathSegment will not conflict with existing or expected future IETF work and (2)the use case is relevant to proxying.¶
IANA has updated the entry for the "masque"URI suffix in the "Well-Known URIs" registry maintained at<https://www.iana.org/assignments/well-known-uris>.¶
IANA has updated the "Reference" field to include thisdocument and has replaced the "Related Information" field with"For sub-suffix allocations, see the registry at<https://www.iana.org/assignments/masque>.".¶
IANA has added the following values to the "HTTP CapsuleTypes" registry maintained at<https://www.iana.org/assignments/masque>.¶
| Value | Capsule Type |
|---|---|
| 0x01 | ADDRESS_ASSIGN |
| 0x02 | ADDRESS_REQUEST |
| 0x03 | ROUTE_ADVERTISEMENT |
All of these new entries use the following values for these fields:¶
The design of this method was inspired by discussions in the MASQUE WorkingGroup around[PROXY-REQS]. The authors wouldlike to thank participants in those discussions for their feedback.Additionally,Mike Bishop,Lucas Pardue, andAlejandro Sedeñoprovided valuable feedback on the document.¶
Most of the text on client configuration is based on the corresponding text in[CONNECT-UDP].¶