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

• If the recipient is configured to use another HTTP server, it will act as an intermediary by forwarding the request to the other 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 IP proxy. The IP proxy can choose to reject the IP proxying request. Otherwise, it extracts the optional "target" and "ipproto" variables from the URI it has reconstructed from the request headers, decodes their percent-encoding, and establishes an IP tunnel.

• The method SHALL be "GET".
• The request SHALL include a single Host header field containing the host and optional port of the IP proxy.
• The request SHALL include a Connection header field with value "Upgrade" (note that this requirement is case-insensitive, as per Section 7.6.1 of [HTTP]).
• The request SHALL include an Upgrade header field with value "connect-ip".

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

• 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 Section 7.6.1 of [HTTP]).
• The response SHALL include a single Upgrade header field with value "connect-ip".
• The response SHALL meet the requirements of HTTP responses that start the Capsule Protocol; see Section 3.2 of [HTTP-DGRAM].

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

• The :method pseudo-header field SHALL be "CONNECT".
• The :protocol pseudo-header field SHALL be "connect-ip".
• 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 URI Template after the URI Template expansion process has been completed; see Section 3. Variables in the URI Template can determine the scope of the request, such as requesting full-tunnel IP packet forwarding, or a specific proxied flow; see Section 4.6.

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

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

HEADERS
:status = 200
capsule-protocol = ?1

target:

The variable "target" contains a hostname or IP prefix of a specific host to which the client wants to proxy packets. If the "target" variable is not specified or its value is "*", the client is requesting to communicate with any allowable host. "target" supports using DNS names, IPv6 prefixes, and IPv4 prefixes. Note that IPv6 scoped addressing zone identifiers [IPv6-ZONE-ID] are not supported. If the target is an IP prefix (IP address optionally followed by a percent-encoded slash followed by the prefix length in bits), the request will only support a single IP version. If the target is a hostname, the IP proxy is expected to perform DNS resolution to determine which route(s) to advertise to the client. The IP proxy SHOULD send a ROUTE_ADVERTISEMENT capsule that includes routes for all addresses that were resolved for the requested hostname, that are accessible to the IP proxy, and belong to an address family for which the IP proxy also sends an Assigned Address.

ipproto:

The variable "ipproto" contains an Internet Protocol Number; see the defined list in the "Assigned Internet Protocol Numbers" IANA registry [IANA-PN]. If present, it specifies that a client only wants to proxy a specific IP protocol for this request. If the value is "*", or the variable is not included, the client is requesting to use any IP protocol. The IP protocol indicated in the "ipproto" variable represents an allowable next header value carried in IP headers that are directly sent in HTTP Datagrams (the outermost IP headers). ICMP traffic is always allowed, regardless of the value of this field.

• If "target" contains an IPv6 literal or prefix, the colons (":") MUST be percent-encoded. For example, if the target host is "2001:db8::42", it will be encoded in the URI as "2001%3Adb8%3A%3A42".
• If present, the IP prefix length in "target" SHALL be preceded by a percent-encoded slash ("/"): "%2F". The IP prefix length MUST represent a decimal integer between 0 and the length of the IP address in bits, inclusive.
• If "target" contains an IP prefix and the prefix length is strictly less than the length of the IP address in bits, the lower bits of the IP address that are not covered by the prefix length MUST all be set to 0.
• "ipproto" MUST represent a decimal integer between 0 and 255 inclusive or the wildcard value "*".

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

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

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

Request ID:

Request identifier, encoded as a variable-length integer. If this address assignment is in response to an Address Request (see Section 4.7.2), then this field SHALL contain the value of the corresponding field in the request. Otherwise, this field SHALL be zero.

IP Version:

IP Version of this address assignment, encoded as an unsigned 8-bit integer. It MUST be either 4 or 6.

IP Address:

Assigned IP address. If the IP Version field has value 4, the IP Address field SHALL have a length of 32 bits. If the IP Version field has value 6, the IP Address field SHALL have a length of 128 bits.

IP Prefix Length:

The number of bits in the IP address that are used to define the prefix that is being assigned, encoded as an unsigned 8-bit integer. This MUST be less than or equal to the length of the IP Address field in bits. If the prefix length is equal to the length of the IP address, the receiver of this capsule is allowed to send packets from a single source address. If the prefix length is less than the length of the IP address, the receiver of this capsule is allowed to send packets from any source address that falls within the prefix. If the prefix length is strictly less than the length of the IP address in bits, the lower bits of the IP Address field that are not covered by the prefix length MUST all be set to 0.

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

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

Request ID:

Request identifier, encoded as a variable-length integer. This is the identifier of this specific address request. Each request from a given endpoint carries a different identifier. Request IDs MUST NOT be reused by an endpoint and MUST NOT be zero.

IP Version:

IP Version of this address request, encoded as an unsigned 8-bit integer. It MUST be either 4 or 6.

IP Address:

Requested IP address. If the IP Version field has value 4, the IP Address field SHALL have a length of 32 bits. If the IP Version field has value 6, the IP Address field SHALL have a length of 128 bits.

IP Prefix Length:

Length of the IP Prefix requested in bits, encoded as an unsigned 8-bit integer. It MUST be less than or equal to the length of the IP Address field in bits. If the prefix length is strictly less than the length of the IP address in bits, the lower bits of the IP Address field that are not covered by the prefix length MUST all be set to 0.

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

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

IP Version:

IP Version of this range, encoded as an unsigned 8-bit integer. It MUST be either 4 or 6.

Start IP Address and End IP Address:

Inclusive start and end IP address of the advertised range. If the IP Version field has value 4, these fields SHALL have a length of 32 bits. If the IP Version field has value 6, these fields SHALL have a length of 128 bits. The Start IP Address MUST be less than or equal to the End IP Address.

IP Protocol:

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 are allowed. If the value is not 0, it represents an allowable next header value carried in IP headers that are sent directly in HTTP Datagrams (the outermost IP headers). ICMP traffic is always allowed, regardless of the value of this field.

• The IP Version of A MUST be less than or equal to the IP Version of B.
• If the IP Version of A and B are equal, the IP Protocol of A MUST be less than or equal to the IP Protocol of B.
• If the IP Version and IP Protocol of A and B are both equal, the End IP Address of A MUST be strictly less than the Start IP Address of B.

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

Context ID:

A variable-length integer that contains the value of the Context ID. If an HTTP/3 datagram that 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.

• 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 outer QUIC connection that IP proxying is running over. (Assuming QUIC version 1 is in use, the overhead is 1 byte for the type, 20 bytes for the maximal connection ID length, 4 bytes for the maximal packet number length, 1 byte for the DATAGRAM frame type, 8 bytes for the maximal Quarter Stream ID, 1 byte for the zero Context ID, and 16 bytes for the Authenticated Encryption with Associated Data (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 are 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).

• 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 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]).

Value:

connect-ip

Description:

Proxying of IP Payloads

Expected Version Tokens:

None

References:

RFC 9484

Path Segment:

An ASCII string containing only characters allowed in tokens; see Section 5.6.2 of [HTTP]. Entries in this registry MUST all have distinct entries in this column.

Description:

A description of the entry.

Reference:

An optional reference defining the use of the entry.

Status:

permanent

Reference:

RFC 9484

Change Controller:

IETF

Contact:

masque@ietf.org

Notes:

None

[ABNF]

D. Crocker, and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/RFC5234, January 2008,
<https://www.rfc-editor.org/info/rfc5234>.

[BCP38]

P. Ferguson, and D. Senie, "Network Ingress Filtering: Defeating Denial of Service Attacks which employ IP Source Address Spoofing", BCP 38, RFC 2827, DOI 10.17487/RFC2827, May 2000,
<https://www.rfc-editor.org/info/rfc2827>.

[DGRAM]

T. Pauly, E. Kinnear, and D. Schinazi, "An Unreliable Datagram Extension to QUIC", RFC 9221, DOI 10.17487/RFC9221, March 2022,
<https://www.rfc-editor.org/info/rfc9221>.

[DSCP]

K. Nichols, S. Blake, F. Baker, and D. Black, "Definition of the Differentiated Services Field (DS Field) in the IPv4 and IPv6 Headers", RFC 2474, DOI 10.17487/RFC2474, December 1998,
<https://www.rfc-editor.org/info/rfc2474>.

[ECN]

K. Ramakrishnan, S. Floyd, and D. Black, "The Addition of Explicit Congestion Notification (ECN) to IP", RFC 3168, DOI 10.17487/RFC3168, September 2001,
<https://www.rfc-editor.org/info/rfc3168>.

[EXT-CONNECT2]

P. McManus, "Bootstrapping WebSockets with HTTP/2", RFC 8441, DOI 10.17487/RFC8441, September 2018,
<https://www.rfc-editor.org/info/rfc8441>.

[EXT-CONNECT3]

R. Hamilton, "Bootstrapping WebSockets with HTTP/3", RFC 9220, DOI 10.17487/RFC9220, June 2022,
<https://www.rfc-editor.org/info/rfc9220>.

[HTTP]

R. Fielding, M. Nottingham, and J. Reschke, "HTTP Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110, June 2022,
<https://www.rfc-editor.org/info/rfc9110>.

[HTTP-DGRAM]

D. Schinazi, and L. Pardue, "HTTP Datagrams and the Capsule Protocol", RFC 9297, DOI 10.17487/RFC9297, August 2022,
<https://www.rfc-editor.org/info/rfc9297>.

[HTTP/1.1]

R. Fielding, M. Nottingham, and J. Reschke, "HTTP/1.1", STD 99, RFC 9112, DOI 10.17487/RFC9112, June 2022,
<https://www.rfc-editor.org/info/rfc9112>.

[HTTP/2]

M. Thomson, and C. Benfield, "HTTP/2", RFC 9113, DOI 10.17487/RFC9113, June 2022,
<https://www.rfc-editor.org/info/rfc9113>.

[HTTP/3]

M. Bishop, "HTTP/3", RFC 9114, DOI 10.17487/RFC9114, June 2022,
<https://www.rfc-editor.org/info/rfc9114>.

[IANA-POLICY]

M. Cotton, B. Leiba, and T. Narten, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 8126, DOI 10.17487/RFC8126, June 2017,
<https://www.rfc-editor.org/info/rfc8126>.

[ICMP]

J. Postel, "Internet Control Message Protocol", STD 5, RFC 792, DOI 10.17487/RFC0792, September 1981,
<https://www.rfc-editor.org/info/rfc792>.

[ICMPv6]

A. Conta, S. Deering, and M. Gupta, "Internet Control Message Protocol (ICMPv6) for the Internet Protocol Version 6 (IPv6) Specification", STD 89, RFC 4443, DOI 10.17487/RFC4443, March 2006,
<https://www.rfc-editor.org/info/rfc4443>.

[IPv6]

S. Deering, and R. Hinden, "Internet Protocol, Version 6 (IPv6) Specification", STD 86, RFC 8200, DOI 10.17487/RFC8200, July 2017,
<https://www.rfc-editor.org/info/rfc8200>.

[IPv6-ZONE-ID]

B. Carpenter, S. Cheshire, and R. Hinden, "Representing IPv6 Zone Identifiers in Address Literals and Uniform Resource Identifiers", RFC 6874, DOI 10.17487/RFC6874, February 2013,
<https://www.rfc-editor.org/info/rfc6874>.

[PROXY-STATUS]

M. Nottingham, and P. Sikora, "The Proxy-Status HTTP Response Header Field", RFC 9209, DOI 10.17487/RFC9209, June 2022,
<https://www.rfc-editor.org/info/rfc9209>.

[QUIC]

J. Iyengar, and M. Thomson, "QUIC: A UDP-Based Multiplexed and Secure Transport", RFC 9000, DOI 10.17487/RFC9000, May 2021,
<https://www.rfc-editor.org/info/rfc9000>.

[RFC2119]

S. Bradner, "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.

[RFC8174]

B. Leiba, "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017,
<https://www.rfc-editor.org/info/rfc8174>.

[TCP]

W. Eddy, "Transmission Control Protocol (TCP)", STD 7, RFC 9293, DOI 10.17487/RFC9293, August 2022,
<https://www.rfc-editor.org/info/rfc9293>.

[TEMPLATE]

J. Gregorio, R. Fielding, M. Hadley, M. Nottingham, and D. Orchard, "URI Template", RFC 6570, DOI 10.17487/RFC6570, March 2012,
<https://www.rfc-editor.org/info/rfc6570>.

[URI]

T. Berners-Lee, R. Fielding, and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005,
<https://www.rfc-editor.org/info/rfc3986>.

[CONNECT-UDP]

D. Schinazi, "Proxying UDP in HTTP", RFC 9298, DOI 10.17487/RFC9298, August 2022,
<https://www.rfc-editor.org/info/rfc9298>.

[DPLPMTUD]

G. Fairhurst, T. Jones, M. Tüxen, I. Rüngeler, and T. Völker, "Packetization Layer Path MTU Discovery for Datagram Transports", RFC 8899, DOI 10.17487/RFC8899, September 2020,
<https://www.rfc-editor.org/info/rfc8899>.

[ECN-TUNNEL]

B. Briscoe, "Tunnelling of Explicit Congestion Notification", RFC 6040, DOI 10.17487/RFC6040, November 2010,
<https://www.rfc-editor.org/info/rfc6040>.

[HEv2]

D. Schinazi, and T. Pauly, "Happy Eyeballs Version 2: Better Connectivity Using Concurrency", RFC 8305, DOI 10.17487/RFC8305, December 2017,
<https://www.rfc-editor.org/info/rfc8305>.

[IANA-PN]

IANA, "Protocol Numbers",
<https://www.iana.org/assignments/protocol-numbers>.

[IPSEC]

S. Kent, and K. Seo, "Security Architecture for the Internet Protocol", RFC 4301, DOI 10.17487/RFC4301, December 2005,
<https://www.rfc-editor.org/info/rfc4301>.

[IPv6-ADDR]

R. Hinden, and S. Deering, "IP Version 6 Addressing Architecture", RFC 4291, DOI 10.17487/RFC4291, February 2006,
<https://www.rfc-editor.org/info/rfc4291>.

[OPTIMISTIC]

Meta Platforms, Inc., B. M. Schwartz, "Security Considerations for Optimistic Use of HTTP Upgrade", Internet-Draft draft-schwartz-httpbis-optimistic-upgrade-00, August 2023,
<https://datatracker.ietf.org/doc/html/draft-schwartz-httpbis-optimistic-upgrade-00>.

[PROXY-REQS]

Google LLC, A. Chernyakhovsky, D. McCall, and D. Schinazi, "Requirements for a MASQUE Protocol to Proxy IP Traffic", Internet-Draft draft-ietf-masque-ip-proxy-reqs-03, August 2021,
<https://datatracker.ietf.org/doc/html/draft-ietf-masque-ip-proxy-reqs-03>.

[ROUTING-HDR]

J. Abley, P. Savola, and G. Neville-Neil, "Deprecation of Type 0 Routing Headers in IPv6", RFC 5095, DOI 10.17487/RFC5095, December 2007,
<https://www.rfc-editor.org/info/rfc5095>.

[TUNNEL-SECURITY]

S. Krishnan, D. Thaler, and J. Hoagland, "Security Concerns with IP Tunneling", RFC 6169, DOI 10.17487/RFC6169, April 2011,
<https://www.rfc-editor.org/info/rfc6169>.

[UDP-USAGE]

L. Eggert, G. Fairhurst, and G. Shepherd, "UDP Usage Guidelines", BCP 145, RFC 8085, DOI 10.17487/RFC8085, March 2017,
<https://www.rfc-editor.org/info/rfc8085>.

Tommy Pauly

David Schinazi

Alex Chernyakhovsky

Mirja Kühlewind

Magnus Westerlund