]> Google LLC

bemasc@google.com

art httpbis Internet-Draft HTTP proxying features have long been part of the core HTTP specification. However, the core proxying functionality has several important deficiencies in modern HTTP environments. This specification defines alternative proxy service configurations for HTTP requests and TCP connections. These services are identified by URI Templates and designed for parallelism with DoH, MASQUE, and Oblivious HTTP.

Introduction

History An HTTP forward proxy (or just "proxy" in the HTTP standards) is an HTTP service that acts on behalf of the client as an intermediary for some or all HTTP requests. HTTP/1.0 defines the initial HTTP proxying mechanism: the client formats its request target in "absolute form" (i.e. with a full URI in the Request-Line) and delivers it to the proxy, which reissues it to the origin specified in the URI (). In this specification, we call this behavior an "HTTP request proxy". With the introduction of "https" URIs, a new proxying mechanism was needed to enable TLS connections to traverse the proxy. To enable this, HTTP/1.1 introduced the CONNECT method. In this method, the request target specifies a host and port number, and the proxy forwards TCP payloads between the client and this destination (). In this specification, we call this behavior a "TCP transport proxy". These two methods sufficed until the introduction of HTTP/3, which uses a UDP transport. The MASQUE effort has filled the gap by defining proxy mechanisms that are capable of proxying UDP datagrams , and more generally IP datagrams . The destination host and port number (if applicable) are encoded into the HTTP resource path, and end-to-end datagrams are wrapped into HTTP Datagrams on the client-proxy path.

Problems Classic HTTP request proxies and TCP transport proxies are identified by an origin, not a URI. The proxy service does not have a path of its own. This prevents any origin from hosting multiple distinct proxy services and makes it difficult to manage a proxy service in a fashion similar to other HTTP services. In some circumstances, it may be possible to work around this limitation by hosting many origins on a single server (virtual-hosting). In HTTP/1.1, the "Host" header was introduced to support such virtual-hosting by distinguishing the hostname of the proxy (in the Host header) from the hostname of the destination (in the absolute-form request URI). However, in HTTP/2 and HTTP/3, this distinction no longer exists. As a result, classic HTTP request proxies are not compatible with virtual-hosting in HTTP/2 or HTTP/3. Classic TCP transport proxies can be used with a host that is specified as a domain name or an IP address. However, because only a single IP address can be specified, Happy Eyeballs and cross-IP fallback can only be used when the host is a domain name. For requests to succeed, the client must know which address families are supported by the proxy.

Overview This specification describes alternative protocols for HTTP request proxies and TCP transport proxies in HTTP. Like other modern HTTP access services such as DoH, CONNECT-UDP, and CONNECT-IP, the proxy is identified by a URI Template. Proxy interactions reuse standard HTTP components and semantics, avoiding changes to the core HTTP protocol.

Conventions and Definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

Modern HTTP Request Proxies A modern HTTP request proxy is identified by a URI Template containing a variable named "target_uri". To convert an HTTP request into a proxied request, the client MUST substitute the request's URI into this variable, expand the template, and use the result as the new request URI. HTTP headers work the same as in classic HTTP request proxies. A modern HTTP request proxy is also suitable for use as an Oblivious HTTP relay, if it provides the required privacy guarantees.

Example Consider a proxy identified as "https://example.com/proxy{?target_uri}". Requests would then be transformed as follows: Notes on this example:

• The HTTP method is not altered.
• The request-related headers such as Content-Type are preserved, but the Host header (or :authority in HTTP/2 and HTTP/3) is altered.
• Certain characers in the target URI are percent-encoded during URI Template expansion.
• The scheme, which is implicit in the original request, is explicit in the transformed request. The scheme in this example is "https", indicating that the client is asking the proxy to establish a secure connection to the target.
• The client can add Proxy-* headers to communicate with the proxy.

Modern TCP transport proxies A modern TCP transport proxy for HTTP is identified by a URI Template containing variables named "target_host" and "tcp_port". The client substitutes the destination host and port number into these variables to produce the request URI. The "target_host" variable MUST be a domain name, an IP address literal, or a list of IP addresses. The "tcp_port" variable MUST be a single integer. If "target_host" is a list (as in ), the server SHOULD perform the same connection procedure as if these addresses had been returned in response to A and AAAA queries for a domain name.

In HTTP/1.1 In HTTP/1.1, the client uses the proxy by issuing a request as follows:

• The method SHALL be "GET".
• The request SHALL include a single Host header field containing the origin of the proxy.
• The request SHALL include a Connection header field with the value "Upgrade".
• The request SHALL include an "Upgrade" header field with the value "connect-tcp".
• The request's target SHALL be the URI derived from expansion of the proxy's URI Template.

If the request is well-formed and permissible, the proxy MUST attempt the TCP connection before returning its response header. If the TCP connection is successful, the response SHALL be as follows:

• The HTTP status code SHALL be 101 (Switching Protocols).
• The response SHALL include a Connection header field with the value "Upgrade".
• The response SHALL include a single Upgrade header field with the value "connect-tcp".

If the request is malformed or impermissible, the proxy MUST return a 4XX error code. If the TCP connection failed, the proxy MUST NOT return a 101 or 2XX status code. If the proxy observes an unclean shutdown from the client (e.g. a TCP RST or TLS error), it SHOULD send a TCP RST to the target. If the proxy receives a TCP RST from the target, it SHOULD send a TLS "internal_error" alert to the client, or set the TCP RST bit if TLS is not in use.

Example Consider a proxy identified as "https://example.com/proxy{?target_host,tcp_port}". To establish a TCP connection to 192.0.2.1:443, the following exchange would occur:

Modern TCP transport proxy in HTTP/1.1

In HTTP/2 and HTTP/3 In HTTP/2 and HTTP/3, the client uses the proxy by issuing an "extended CONNECT" request as follows:

• The :method pseudo-header field SHALL be "CONNECT".
• The :protocol pseudo-header field SHALL be "connect-tcp".
• The :authority pseudo-header field SHALL contain the authority of the proxy.
• The :path and :scheme pseudo-header fields SHALL contain the path and scheme of the request URI derived from the proxy's URI Template.

From this point on, the request and response streams SHALL conform to all the usual requirements for non-extended CONNECT in this HTTP version.

Additional Examples

Template expansion The names of the variables in the URI Template uniquely identify the capabilities of the proxy. Undefined variables are permitted in URI Templates, so a single template can be used for multiple purposes:

Multipurpose templates

Multipurpose templates can be useful when a single client may benefit from access to multiple complementary services (e.g. TCP and UDP), or when the proxy is used by a variety of clients with different needs.

Sample exchanges A modern HTTP request proxy can be used as an Oblivious HTTP Relay. For example, suppose the relay is identified as "https://proxy.example.org/relay{?target_uri}", and the Oblivious HTTP Gateway is "https://example.com/gateway". The client would send requests to the proxy as follows:

Use of an HTTP request proxy as an Oblivious relay

If a modern HTTP request proxy supports HTTP/2 and Extended CONNECT, it is even possible to reach a modern TCP transport proxy through it:

Use of a TCP transport proxy through an HTTP request proxy

Modern TCP transport proxies support requests that offer multiple IP addresses:

TCP transport proxy request with multiple IP addresses

Security Considerations None

Operational considerations Modern HTTP proxies can make use of standard HTTP gateways and path-routing to ease implementation and allow use of shared infrastructure. However, current gateways might need modifications to support these services. A compatible gateway must:

• support Extended CONNECT.
• convert HTTP/1.1 Upgrade requests into Extended CONNECT.
• allow the CONNECT method to pass through to the origin.
• forward Proxy-* request headers to the origin.

IANA Considerations IF APPROVED, IANA is requested to add the following entry to the HTTP Upgrade Token Registry:

• Value: "connect-tcp"
• Description: Proxying of TCP payloads
• Reference: (This document)

References Normative References In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. A URI Template is a compact sequence of characters for describing a range of Uniform Resource Identifiers through variable expansion. This specification defines the URI Template syntax and the process for expanding a URI Template into a URI reference, along with guidelines for the use of URI Templates on the Internet. [STANDARDS-TRACK] Informative References The Hypertext Transfer Protocol (HTTP) is an application-level protocol with the lightness and speed necessary for distributed, collaborative, hypermedia information systems. This memo provides information for the Internet community. This memo does not specify an Internet standard of any kind. The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document describes the overall architecture of HTTP, establishes common terminology, and defines aspects of the protocol that are shared by all versions. In this definition are core protocol elements, extensibility mechanisms, and the "http" and "https" Uniform Resource Identifier (URI) schemes. This document updates RFC 3864 and obsoletes RFCs 2818, 7231, 7232, 7233, 7235, 7538, 7615, 7694, and portions of 7230. This document describes how to proxy UDP in HTTP, similar to how the HTTP CONNECT method allows proxying TCP in HTTP. More specifically, this document defines a protocol that allows an HTTP client to create a tunnel for UDP communications through an HTTP server that acts as a proxy. Apple Inc. Google LLC Google LLC Ericsson Ericsson This document describes a method of proxying IP packets over HTTP. This protocol is similar to CONNECT-UDP, but allows transmitting arbitrary IP packets, without being limited to just TCP like CONNECT or UDP like CONNECT-UDP. This document describes HTTP Datagrams, a convention for conveying multiplexed, potentially unreliable datagrams inside an HTTP connection. In HTTP/3, HTTP Datagrams can be sent unreliably using the QUIC DATAGRAM extension. When the QUIC DATAGRAM frame is unavailable or undesirable, HTTP Datagrams can be sent using the Capsule Protocol, which is a more general convention for conveying data in HTTP connections. HTTP Datagrams and the Capsule Protocol are intended for use by HTTP extensions, not applications.

Acknowledgments TODO acknowledge.