| Internet-Draft | Detecting Outdated Proxy Configuration | June 2025 |
| Rosomakho | Expires 21 December 2025 | [Page] |
This document defines a lightweight mechanism that allows explicit HTTP proxies to inform clients when their proxy configuration, such as a Proxy Auto-Configuration (PAC) file or Provisioning Domain (PvD) proxy configuration, is outdated. Clients signal to the proxy the configuration URL and the timestamp of when it was last fetched. In response, the proxy may indicate that a newer version of the configuration is available. This enables clients to refresh their configuration without relying on frequent polling or short expiration intervals. The mechanism is designed to be compatible with existing proxy deployment models and supports both PAC-based and PvD-based configurations.¶
This note is to be removed before publishing as an RFC.¶
The latest revision of this draft can be found at https://yaroslavros.github.io/httpbis-outdated-proxy-config/draft-rosomakho-httpbis-outdated-proxy-config.html. Status information for this document may be found at https://datatracker.ietf.org/doc/draft-rosomakho-httpbis-outdated-proxy-config/.¶
Discussion of this document takes place on the HTTP Working Group mailing list (mailto:ietf-http-wg@w3.org), which is archived at https://lists.w3.org/Archives/Public/ietf-http-wg/.¶
Source for this draft and an issue tracker can be found at https://github.com/yaroslavros/httpbis-outdated-proxy-config.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 21 December 2025.¶
Copyright (c) 2025 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.¶
Explicit HTTP proxies are widely deployed in enterprise and managed network environments to enforce routing policies, enable traffic inspection, or implement access control. Clients relying on such proxies typically obtain configuration through a Proxy Auto-Configuration (PAC) file [PAC-FILE] or a Provisioning Domain (PvD) [PROXY-PVD]. In many deployments, it is necessary to update these configurations in response to operational changes such as service onboarding, emergency routing adjustments, or policy corrections.¶
Currently, clients have limited mechanisms to detect whether the proxy configuration they are using is stale. As a result, PAC files are often polled at short intervals, and PvD expiration times are configured with low values to accelerate refreshes. These approaches are inefficient and may introduce unnecessary network traffic or delay the application of important updates.¶
This document defines a simple mechanism that enables a proxy to inform a client that its current configuration is outdated. The client includes in its request a structured field indicating the URL of the PAC file or PvD and the timestamp of when it last fetched the configuration. If the proxy recognizes the configuration and determines that a newer version is available, it may respond with a boolean indicator prompting the client to refresh the configuration.¶
This mechanism applies to all forms of explicit proxying over HTTP, including:¶
HTTP CONNECT as defined Section 9.3.6 of [HTTP]¶
Templated [CONNECT-TCP]¶
The mechanism is optional, compatible with existing protocols, and requires no persistent state. It allows clients to discover configuration updates proactively while preserving the existing operational model.¶
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.¶
To enable detection of stale proxy configuration, clients may include a Proxy-Config HTTP header field in requests sent to an explicit proxy. This header communicates the URL of the proxy configuration (such as a PAC file or PvD) and the timestamp of when the client last fetched it.¶
Upon receiving a request containing the Proxy-Config header, a proxy that supports this mechanism compares the provided timestamp with the most recent update time of the corresponding configuration. If the proxy determines that the client configuration is outdated, it can signal this condition using the Proxy-Config-Stale response header.¶
This mechanism is optional and advisory. Proxies are not required to track or respond to client configuration metadata, and clients are not required to act immediately upon receiving a staleness indication. The mechanism is designed to supplement, not replace, existing configuration refresh behaviors.¶
The Proxy-Config request header field is used by a client to inform an explicit proxy about the proxy configuration it is currently using. The field conveys a dictionary structured field as defined in Section 3.2 of [STRUCTURED-FIELD] with the following keys:¶
url (optional): A string identifying the URL from which the client fetched the configuration. This may point to a PAC file or a PvD configuration. If omitted, the proxy is expected to infer the default PvD URI based on its own hostname and ".well-known/pvd" path as defined in Section 4.1 of [PVDDATA].¶
fetched (required): A date value indicating when the client last fetched the configuration. The value MUST use the Date format defined in Section 3.3.7 of [STRUCTURED-FIELD].¶
Clients MUST NOT include URLs that expose local system information (e.g., file:// URLs). Clients SHOULD limit use of the Proxy-Config header to contexts where it does not introduce privacy or security risks, such as trusted or encrypted proxy connections.¶
A client using a PAC file retrieved from https://config.example.net/proxy.pac at 2025-06-01T00:00:00Z MAY include the following header:¶
Proxy-Config: url="https://config.example.net/proxy.pac", fetched=@1748736000
If the client is using the default PvD URI associated with the proxy hostname, it may omit the url key:¶
Proxy-Config: fetched=@1748736000
Proxy-Config-Stale Header
The Proxy-Config-Stale response header field is used by a proxy to inform the client whether its current proxy configuration is considered outdated. This allows the client to make informed decisions about whether to refresh the configuration.¶
The field is a boolean as defined in Section 3.3.6 of [STRUCTURED-FIELD], where:¶
?1 indicates that the configuration used by the client is stale and a newer version is available.¶
?0 indicates that the configuration used by the client is current.¶
The proxy MUST only include this header if it has received a valid Proxy-Config header from the client and is able to recognize and evaluate the configuration URL. If the proxy does not recognize the provided configuration URL, does not track updates for it, or does not support this mechanism, it MUST omit the Proxy-Config-Stale header.¶
The Proxy-Config-Stale header MAY appear in both successful and error responses, except for responses related to client authentication (e.g., 407 Proxy Authentication Required). Including the header in such authentication-related responses could result in unintended exposure of configuration metadata and may interfere with authentication workflows.¶
The Proxy-Config-Stale field is advisory. Its presence does not affect the processing of the current request or response. Clients MAY choose how and when to act upon the information, including deferring configuration refresh until convenient.¶
Clients using the Proxy-Config header field must take care to avoid disclosing sensitive information in the URL or metadata they send to the proxy.¶
Clients MUST NOT include configuration URLs that reveal local system details, such as file:// URIs or paths containing user-specific or internal directory structures. To reduce exposure, clients SHOULD only use this mechanism when proxy configuration is relevant to the proxy (e.g., hosted on the proxy or a part of the same enterprise domain).¶
The Proxy-Config header is intended for use over secure and trusted communication channels. Clients SHOULD send this header only when using TLS or when otherwise confident that the request is not observable or modifiable by unauthorized intermediaries.¶
A misconfigured or malicious proxy could include Proxy-Config-Stale: ?1 in every response, causing the client to repeatedly refetch proxy configuration. This behavior can lead to excessive network traffic, CPU usage, or degraded performance on the client, particularly in environments where configuration retrieval is resource-intensive.¶
To mitigate this risk, clients MUST implement appropriate rate limiting or throttling mechanisms when acting on stale configuration indications. For example, a client may choose to ignore repeated ?1 responses within a minimum refresh interval or apply exponential backoff when encountering multiple stale signals in quick succession.¶
Clients SHOULD validate the authenticity and integrity of any fetched configuration before applying it, and ensure that configuration refreshes do not interfere with ongoing connection or session state.¶
This document registers the following HTTP header fields in the "Hypertext Transfer Protocol (HTTP) Field Name Registry":¶
Proxy-Config¶
Proxy-Config-Stale¶
TODO acknowledge.¶