]> Meta Platforms, Inc.

ietf@bemasc.net

art httpbis Internet-Draft HTTP request proxying behaviors have long been part of the core HTTP specification. However, the core request proxying functionality has several important deficiencies in modern HTTP environments. This specification defines an alternative proxy service configuration for HTTP requests. The proxy service is identified by a URI Template, similarly to "connect-tcp" and "connect-udp".

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 defined 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 the request to the origin specified in the URI (). In this specification, we call this behavior a "classic HTTP request proxy". In HTTP/1.1, proxy requests are additionally required to carry a Host header whose value matches the authority in the Request URI (not the name of the proxy server). In HTTP/2 and HTTP/3, the destination host is specified in the :authority pseudo-header field ().

Problems HTTP clients can be configured to use proxies by selecting a proxy host, a port, and whether to use a security protocol. However, requests to the proxy do not carry this configuration information. Instead, they only indicate the URI of the requested resource. This prevents any HTTP server from hosting multiple distinct proxy services, as the server cannot distinguish them by path (as with distinct resources) or by origin (as in "virtual hosting"). The absence of an explicit origin for the proxy also rules out the usual defenses against server port misdirection attacks (see ).

Overview This specification describes an alternative protocol for an HTTP request proxy. Like CONNECT-TCP, CONNECT-UDP, and CONNECT-IP, the proxy is identified by a URI Template.

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.

Requirements

Use of Templates A templated 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 and status codes are processed in the same way as in classic HTTP request proxies. A templated HTTP request proxy is also suitable for use as an Oblivious HTTP relay, if it provides the required privacy guarantees.

Configuration Clients that support both classic HTTP request proxies and template-driven proxies MAY accept both types via a single configuration string. If the configuration string can be parsed as a URI Template containing the "target_uri" variable, it is a template-driven request proxy. Otherwise, it is presumed to represent a classic HTTP request proxy. This specification defines a new Proxy-Status parameter: "use_template" (see registration in ), which conveys a preferred URI Template for the proxy. Upon receipt of this parameter, the client SHOULD update its configuration to use the new template for the remainder of the session if possible, and retry the request using the new template if it also received a Proxy-Status "error" parameter. If the client is configured with a classic HTTP request proxy, and the template string is the special value "default", the client MUST use the following default proxy template:

Registered default template

This allows a virtual-hosted proxy server to learn the proxy's hostname, which is not present in the initial request.

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

A templated 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 templated HTTP request proxy supports HTTP/2 and Extended CONNECT, it is even possible to reach a CONNECT-TCP transport proxy through it:

Use of a TCP transport proxy through an HTTP request proxy

A proxy can use the "use_template" proxy status error to reconfigure existing clients:

Updating the configured template with 'use_template'

If the client's proxy configuration string was "proxy-foo.example.org:54321", the client will start by issuing a classic HTTP proxy request, but the proxy can use the "use_template" parameter to inform the client that it should use templated requests instead:

Using 'use_template' to upgrade from classic to templated proxying

Security Considerations None

Operational Considerations Templated HTTP proxies can make use of standard HTTP gateways and path-routing to ease implementation and allow use of shared infrastructure. To be compatible, a gateway must forward Proxy-* request headers to the origin.

IANA Considerations IF APPROVED, IANA is requested to add the following entry to the "MASQUE URI Suffixes" registry:

Path Segment	Description	Reference
http	HTTP Request Proxying	(This document)

IF APPROVED, IANA is requested to add the following entry to the "HTTP Proxy Status Parameters" registry:

• Name: use_template
• Description: A URI Template that should be used for requests to this proxy server. The special value "default" indicates that the client should use the default template for the configured proxy hostname (which is not known to the proxy).
• 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. 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. This specification describes an optimized expression of the semantics of the Hypertext Transfer Protocol (HTTP), referred to as HTTP version 2 (HTTP/2). HTTP/2 enables a more efficient use of network resources and a reduced latency by introducing field compression and allowing multiple concurrent exchanges on the same connection. This document obsoletes RFCs 7540 and 8740. 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.

Acknowledgments TODO acknowledge.