Communicating Proxy Configurations in Provisioning Domains
draft-ietf-intarea-proxy-config-08
| Document | Type | Active Internet-Draft (intarea WG) | |
|---|---|---|---|
| Authors | Tommy Pauly , Dragana Damjanovic , Yaroslav Rosomakho | ||
| Last updated | 2025-10-15 (Latest revision 2025-10-14) | ||
| Replaces | draft-pauly-intarea-proxy-config-pvd | ||
| RFC stream | Internet Engineering Task Force (IETF) | ||
| Intended RFC status | (None) | ||
| Formats | |||
| Additional resources | Mailing list discussion | ||
| Stream | WG state | In WG Last Call | |
| Document shepherd | (None) | ||
| IESG | IESG state | I-D Exists | |
| Consensus boilerplate | Unknown | ||
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-ietf-intarea-proxy-config-08
Network Working Group T. Pauly
Internet-Draft Apple, Inc.
Intended status: Standards Track D. Damjanovic
Expires: 18 April 2026 Microsoft
Y. Rosomakho
Zscaler
15 October 2025
Communicating Proxy Configurations in Provisioning Domains
draft-ietf-intarea-proxy-config-08
Abstract
This document defines a mechanism for accessing provisioning domain
information associated with a proxy, such as other proxy URIs that
support different protocols and information about which destinations
are accessible using a proxy.
Discussion Venues
This note is to be removed before publishing as an RFC.
Source for this draft and an issue tracker can be found at
https://github.com/tfpauly/privacy-proxy.
Status of This Memo
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 18 April 2026.
Copyright Notice
Copyright (c) 2025 IETF Trust and the persons identified as the
document authors. All rights reserved.
Pauly, et al. Expires 18 April 2026 [Page 1]
Internet-Draft Proxy Configuration PvDs October 2025
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.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Background . . . . . . . . . . . . . . . . . . . . . . . 3
1.2. Requirements . . . . . . . . . . . . . . . . . . . . . . 4
2. Fetching PvD Additional Information for proxies . . . . . . . 4
2.1. Discovery via HTTPS/SVCB Records . . . . . . . . . . . . 5
3. Enumerating proxies within a PvD . . . . . . . . . . . . . . 6
3.1. Proxy definition keys . . . . . . . . . . . . . . . . . . 6
3.2. Proprietary keys in proxy configurations . . . . . . . . 9
3.3. Example . . . . . . . . . . . . . . . . . . . . . . . . . 9
4. Destination accessibility information for proxies . . . . . . 10
4.1. Destination Rule Keys . . . . . . . . . . . . . . . . . . 11
4.2. Using Destination Rules . . . . . . . . . . . . . . . . . 13
4.3. Proprietary Keys in Destination Rules . . . . . . . . . . 14
4.4. Examples . . . . . . . . . . . . . . . . . . . . . . . . 14
5. Discovering proxies from network PvDs . . . . . . . . . . . . 18
6. Security Considerations . . . . . . . . . . . . . . . . . . . 19
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19
7.1. New PvD Additional Information key . . . . . . . . . . . 19
7.1.1. proxies Key . . . . . . . . . . . . . . . . . . . . . 19
7.1.2. proxy-match Key . . . . . . . . . . . . . . . . . . . 20
7.2. New PvD Proxy Information Registry . . . . . . . . . . . 20
7.3. New PvD Proxy Protocol Registry . . . . . . . . . . . . . 20
7.4. New PvD Proxy Destination Rule Registry . . . . . . . . . 21
7.5. New DNS SVCB Service Parameter Key (SvcParamKey) . . . . 21
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 21
8.1. Normative References . . . . . . . . . . . . . . . . . . 21
8.2. Informative References . . . . . . . . . . . . . . . . . 23
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23
1. Introduction
HTTP proxies that use the CONNECT method defined in Section 9.3.6 of
[HTTP] (often referred to as "forward" proxies) allow clients to open
connections to hosts via a proxy. These typically allow for TCP
stream proxying, but can also support UDP proxying [CONNECT-UDP] and
IP packet proxying [CONNECT-IP]. The locations of these proxies are
not just defined as hostnames and ports, but can use URI templates
Pauly, et al. Expires 18 April 2026 [Page 2]
Internet-Draft Proxy Configuration PvDs October 2025
[URITEMPLATE].
In order to make use of multiple related proxies, clients need a way
to understand which proxies are associated with one another, and
which protocols can be used to communicate with the proxies.
Client can also benefit from learning about additional information
associated with the proxy to optimize their proxy usage, such knowing
that a proxy is configured to only allow access to a limited set of
destinations.
These improvements to client behavior can be achieved through the use
of Provisioning Domains. Provisioning Domains (PvDs) are defined in
[PVD] as consistent sets of network configuration information, which
can include proxy configuration details Section 2 of [PVD].
Section 4.3 of [PVDDATA] defines a JSON [JSON] format for describing
Provisioning Domain Additional Information, which is an extensible
dictionary of properties of the Provisioning Domain.
This document defines several mechanisms to use PvDs to help clients
understand how to use proxies:
1. A way to fetch PvD Additional Information associated with a known
proxy URI (Section 2)
2. A way to list one or more proxy URIs in a PvD, allowing clients
to learn about other proxy options given a known proxy
(Section 3).
3. A way to define the set of destinations that are accessible
through the proxy (Section 4).
Additionally, this document partly describes how these mechanisms
might be used to discover proxies associated with a network
(Section 5).
Using this mechanism a client can learn that a legacy insecure HTTP
proxy that the client is configured with is also accessible using
HTTPS. In this way, clients can upgrade to a more secure connection
to the proxy.
1.1. Background
Other non-standard mechanisms for proxy configuration and discovery
have been used historically, some of which are described in
[RFC3040].
Pauly, et al. Expires 18 April 2026 [Page 3]
Internet-Draft Proxy Configuration PvDs October 2025
Proxy Auto Configuration (PAC) files Section 6.2 of [RFC3040] are
Javascript scripts that take URLs as input and provide an output of a
proxy configuration to use.
Web Proxy Auto-Discovery Protocol (WPAD) Section 6.4 of [RFC3040]
allows networks to advertise proxies to use by advertising a PAC
file. This solution squats on DHCP option 252.
These common (but non-standard) mechanisms only support defining
proxies by hostname and port, and do not support configuring a full
URI template [URITEMPLATE].
The mechanisms defined in this document are intended to offer a
standard alternative that works for URI-based proxies and avoids
dependencies on executing Javascript scripts, which are prone to
implementation-specific inconsistencies and can open up security
vulnerabilities.
1.2. Requirements
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.
2. Fetching PvD Additional Information for proxies
This document defines a way to fetch PvD Additional Information
associated with a proxy. This PvD describes the properties of the
network accessible through the proxy.
In order to fetch PvD Additional Information associated with a proxy,
a client issues an HTTP GET request for the well-known PvD URI
(".well-known/pvd") as defined in Section 4.1 of [PVDDATA] and the
host authority of the proxy. This is applicable for both proxies
that are identified by a host and port only (such as SOCKS proxies
and HTTP CONNECT proxies) and proxies that are identified by a URI or
URI template. The fetch MUST use the "https" scheme and the default
port for HTTP over TLS, 443.
It is not necessary for the client to re-fetch PvD Additional
Information unless one of the following conditions occurs:
* The current time is beyond the "expires" value defined in
Section 4.3 of [PVDDATA]
Pauly, et al. Expires 18 April 2026 [Page 4]
Internet-Draft Proxy Configuration PvDs October 2025
* A new Sequence Number for that PvD is received in a Router
Advertisement (RA)
To avoid synchronized queries toward the server hosting the PvD
Additional Information when an object expires, clients MUST apply a
randomized backoff as specified in Section 4.1 of [PVDDATA].
For example, a client would issue the following request for the PvD
associated with "https://proxy.example.org/
masque{?target_host,target_port}":
:method = GET
:scheme = https
:authority = proxy.example.org
:path = /.well-known/pvd
accept = application/pvd+json
A client would send the same request as above for the PvD assocated
with an HTTP CONNECT proxy on "proxy.example.org:8080". Note that
the client will not make a request to port 8080, but to port 443.
Note that all proxies that are co-located on the same host share the
same PvD Additional Information. Proxy deployments that need
separate PvD configuration properties SHOULD use different hosts.
PvD Additional Information is required to contain the "identifier",
"expires", and "prefixes" keys. For proxy PvDs as defined in this
document, the "identifier" MUST match the hostname of the HTTP proxy.
The "prefixes" array SHOULD be empty by default.
2.1. Discovery via HTTPS/SVCB Records
To allow clients to determine whether PvD Additional Information is
available for a given proxy, this document defines a new SvcParamKey
in HTTPS and SVCB DNS records defined in [SVCB-DNS].
Presence of this SvcParamKey, named pvd indicates that the proxy host
supports PvD discovery via the well-known PvD URI ".well-known/pvd"
defined in Section 4.1 of [PVDDATA]. The presence of this key in an
HTTPS or SVCB record signals that the proxy's PvD Additional
Information can be fetched using the "https" scheme from the proxy
host on port 443 using the well-known path. The presentation and
wire-format values for pvd SvcParamKey MUST be empty.
A client receiving a DNS record like the following:
proxy.example.org. 3600 IN HTTPS 1 . alpn="h3,h2" pvd
Pauly, et al. Expires 18 April 2026 [Page 5]
Internet-Draft Proxy Configuration PvDs October 2025
can interpret the presence of the pvd key as an indication that it
MAY perform a PvD fetch from "https://proxy.example.org/.well-known/
pvd" using HTTP GET method.
While this key is particularly useful for detecting proxy
configurations when looking up a DNS record for a known proxy name,
this key generically provides a hint that PvD Additional Information
is available, and can be used for use cases unrelated to proxies.
This marker is advisory; clients MAY still attempt to fetch PvD
Additional Information even if pvd SvcParamKey is not present.
The pvd SvcParamKey is registered with IANA as described in
Section 7.5.
3. Enumerating proxies within a PvD
This document defines a new PvD Additional Information key, proxies,
that is an array of dictionaries, where each dictionary in the array
defines a single proxy that is available as part of the PvD (see
Section 7.1). Each proxy is defined by a proxy protocol and a proxy
location (i.e., a hostname and port or a URI template [URITEMPLATE]),
along with other optional keys.
When a PvD that contains the proxies key is fetched from a known
proxy using the method described in Section 2, the proxies list
describes equivalent proxies (potentially supporting other protocols)
that can be used in addition to the known proxy.
Such cases are useful for informing clients of related proxies as a
discovery method, with the assumption that the client already is
aware of one proxy. Many historical methods of configuring a proxy
only allow configuring a single FQDN hostname for the proxy. A
client can attempt to fetch the PvD information from the well-known
URI to learn the list of complete URIs that support non-default
protocols, such as [CONNECT-UDP] and [CONNECT-IP].
3.1. Proxy definition keys
This document defines two required keys for the sub-dictionaries in
the proxies array: protocol and proxy. There are also optional keys,
including mandatory, alpn, and identifier. Other optional keys can
be added to the dictionary to further define or restrict the use of a
proxy. The keys are registered with IANA as described in
Section 7.2, with the initial content provided below.
Pauly, et al. Expires 18 April 2026 [Page 6]
Internet-Draft Proxy Configuration PvDs October 2025
+==========+========+=============+=======+=================================+
|JSON Key |Optional|Description |Type |Example |
+==========+========+=============+=======+=================================+
|protocol |No |The protocol |String |"connect-udp" |
| | |used to | | |
| | |communicate | | |
| | |with the | | |
| | |proxy | | |
+----------+--------+-------------+-------+---------------------------------+
|proxy |No |String |String |"https://proxy.example.org:4443/ |
| | |containing | |masque{?target_host,target_port}"|
| | |the URI | | |
| | |template or | | |
| | |host and port| | |
| | |of the proxy,| | |
| | |depending on | | |
| | |the format | | |
| | |defined by | | |
| | |the protocol | | |
+----------+--------+-------------+-------+---------------------------------+
|mandatory |Yes |An array of |Array |["example_key"] |
| | |optional keys|of | |
| | |that client |Strings| |
| | |must | | |
| | |understand | | |
| | |and process | | |
| | |to use this | | |
| | |proxy | | |
+----------+--------+-------------+-------+---------------------------------+
|alpn |Yes |An array of |Array |["h3","h2"] |
| | |Application- |of | |
| | |Layer |Strings| |
| | |Protocol | | |
| | |Negotiation | | |
| | |protocol | | |
| | |identifiers | | |
+----------+--------+-------------+-------+---------------------------------+
|identifier|Yes |A string used|String |"udp-proxy" |
| | |to refer to | | |
| | |the proxy, | | |
| | |which can be | | |
| | |referenced by| | |
| | |other | | |
| | |dictionaries,| | |
| | |such as | | |
| | |entries in | | |
| | |proxy-match | | |
+----------+--------+-------------+-------+---------------------------------+
Pauly, et al. Expires 18 April 2026 [Page 7]
Internet-Draft Proxy Configuration PvDs October 2025
Table 1: Initial Proxy Information PvD Keys Registry Contents
The values for the protocol key are defined in the proxy protocol
registry (Section 7.3), with the initial contents provided below.
For consistency, any new proxy types that use HTTP Upgrade Tokens
(and use the :protocol pseudo-header) SHOULD define the protocol
value to match the Upgrade Token / :protocol value.
+===============+===========+===============+===================+
| Proxy | Proxy | Reference | Notes |
| Protocol | Location | | |
| | Format | | |
+===============+===========+===============+===================+
| socks5 | host:port | [SOCKSv5] | |
+---------------+-----------+---------------+-------------------+
| http-connect | host:port | Section 9.3.6 | Standard CONNECT |
| | | of [HTTP] | method, using |
| | | | unencrypted HTTP |
| | | | to the proxy |
+---------------+-----------+---------------+-------------------+
| https-connect | host:port | Section 9.3.6 | Standard CONNECT |
| | | of [HTTP] | method, using |
| | | | TLS-protected |
| | | | HTTP to the proxy |
+---------------+-----------+---------------+-------------------+
| connect-udp | URI | [CONNECT-UDP] | |
| | template | | |
+---------------+-----------+---------------+-------------------+
| connect-ip | URI | [CONNECT-IP] | |
| | template | | |
+---------------+-----------+---------------+-------------------+
| connect-tcp | URI | [CONNECT-TCP] | |
| | template | | |
+---------------+-----------+---------------+-------------------+
Table 2: Initial PvD Proxy Protocol Registry Contents
The value of proxy depends on the Proxy Location Format defined by
proxy protocol. The types defined here either use a host as defined
in Section 3.2.2 of [URI] and port, or a full URI template.
The value of the mandatory key is a list of keys that the client must
understand and process to be able to use the proxy. A client that
does not understand a key from the list or cannot fully process the
value of a key from the list MUST ignore the entire proxy definition.
The mandatory list can contain keys that are either:
Pauly, et al. Expires 18 April 2026 [Page 8]
Internet-Draft Proxy Configuration PvDs October 2025
* registered in an IANA registry, defined in Section 7.2 and marked
as optional;
* or proprietary, as defined in Section 3.2
The mandatory list MUST NOT include any entries that are not present
in the sub-dictionary.
If the alpn key is present, it provides a hint for the Application-
Layer Protocol Negotiation (ALPN) [ALPN] protocol identifiers
associated with this server. For HTTP proxies, this can indicate if
the proxy supports HTTP/3, HTTP/2, etc.
The value of identifier key is a string that can be used to refer to
a particular proxy from other dictionaries, specifically those
defined in Section 4. The string value is an arbitrary JSON string.
Identifier values MAY be duplicated across different proxy
dictionaries in the proxies array, which indicates that all
references from other dictionaries to a particular identifier value
apply to all matching proxies. Proxies without the identifier key
are expected to accept any traffic since their destinations cannot be
contained in proxy-match array defined in Section 4. Proxies with
identifier keys are expected to accept only traffic matching rules in
the proxy-match array and SHOULD NOT be used if they are not included
in the proxy-match array.
3.2. Proprietary keys in proxy configurations
Implementations MAY include proprietary or vendor-specific keys in
the sub-dictionaries of the proxies array to convey additional proxy
configuration information not defined in this specification.
A proprietary key MUST contain at least one underscore character
("_"). This character serves as a separator between a vendor-
specific namespace and the key name. For example, "acme_authmode"
could be a proprietary key indicating an authentication mode defined
by a vendor named "acme".
When combined with mandatory list, this mechanism allows
implementations to extend proxy metadata while maintaining
interoperability and ensuring safe fallback behavior for clients that
do not support a given extension.
3.3. Example
Given a known HTTP CONNECT proxy FQDN, "proxy.example.org", a client
could request PvD Additional Information with the following request:
Pauly, et al. Expires 18 April 2026 [Page 9]
Internet-Draft Proxy Configuration PvDs October 2025
:method = GET
:scheme = https
:authority = proxy.example.org
:path = /.well-known/pvd
accept = application/pvd+json
If the proxy has a PvD definition for this FQDN, it would return the
following response to indicate a PvD that has two related proxy URIs.
:status = 200
content-type = application/pvd+json
content-length = 322
{
"identifier": "proxy.example.org.",
"expires": "2023-06-23T06:00:00Z",
"prefixes": [],
"proxies": [
{
"protocol": "http-connect",
"proxy": "proxy.example.org:80"
},
{
"protocol": "connect-udp",
"proxy": "https://proxy.example.org/masque{?target_host,target_port}"
}
]
}
From this response, the client would learn the URI template of the
proxy that supports UDP using [CONNECT-UDP], at
"https://proxy.example.org/masque{?target_host,target_port}".
4. Destination accessibility information for proxies
Destination accessibility information is used when only a subset of
destinations is reachable through a proxy. Destination restrictions
are often used in VPN tunnel configurations such as split DNS in
IKEv2 [IKEV2SPLIT], and in other proxy configuration mechanisms like
PAC files (see Section 1.1).
PvD Additional Information can be used to indicate that a set of
proxies only allows access to a limited set of destinations.
To support determining which traffic is supported by different
proxies, this document defines a new PvD Additional Information key
proxy-match. This key has a value that is an array of dictionaries,
where each subdictionary describes a rule for matching traffic to one
Pauly, et al. Expires 18 April 2026 [Page 10]
Internet-Draft Proxy Configuration PvDs October 2025
or more proxies, or excluding the traffic from all proxies described
in the PvD. These subdictionaries are referred to as "destination
rules", since they define rules about which destinations can be
accessed for a particular proxy or set of proxies.
4.1. Destination Rule Keys
This document defines four keys for destination rules. Any
destination rule MUST contain the proxies key. Values corresponding
to the proxies key may be either an empty array, which implies that
no proxy defined in this PvD can process matching traffic, or an
array of strings with at least one proxy identifier string. All
destination rules MUST also contain at least one other key use to
describe the destination properties. Each key MUST correspond to an
array with at least one entry.
Extensions or proprietary deployments can define new keys to describe
destination properties. Any destination rules that include keys not
known to the client, or values that cannot be parsed, MUST be ignored
in their entirety.
Destination rule keys are registered with IANA as defined in
Section 7.4, with the initial content provided below.
Pauly, et al. Expires 18 April 2026 [Page 11]
Internet-Draft Proxy Configuration PvDs October 2025
+=======+========+=============+=======+===========================+
|JSON |Optional| Description |Type | Example |
|Key | | | | |
+=======+========+=============+=======+===========================+
|proxies|No | An array of |Array | ["tcp-proxy", "udp- |
| | | strings |of | proxy"] |
| | | that match |Strings| |
| | | identifier | | |
| | | values from | | |
| | | the top- | | |
| | | level | | |
| | | proxies | | |
| | | array | | |
+-------+--------+-------------+-------+---------------------------+
|domains|Yes | An array of |Array | ["www.example.com", |
| | | FQDNs and |of | "*.internal.example.com"] |
| | | wildcard |Strings| |
| | | DNS domains | | |
+-------+--------+-------------+-------+---------------------------+
|subnets|Yes | An array of |Array | ["2001:DB8::1", |
| | | IPv4 and |of | "192.0.2.0/24"] |
| | | IPv6 |Strings| |
| | | addresses | | |
| | | and subnets | | |
+-------+--------+-------------+-------+---------------------------+
|ports |Yes | An array of |Array | ["80", "443", |
| | | TCP and UDP |of | "1024-65535"] |
| | | port ranges |Strings| |
+-------+--------+-------------+-------+---------------------------+
Table 3: Initial PvD Proxy Destination Rule Registry Contents
The domains array includes specific FQDNs and zones that are either
accessible using specific proxy (for rules with non-empty proxies
array) or non-accessible through any proxies (for rules with empty
proxies array). A wildcard prefix (*.) is used to indicate matching
entire domains or subdomains instead of specific hostnames. Note
that this can be used to match multiple levels of subdomains. For
example "*.example.com" matches "internal.example.com" as well as
"www.public.example.com". Entries that include the wildcard prefix
also MUST be treated as if they match an FQDN that only contains the
string after the prefix, with no subdomain. So, an entry
"*.example.com" in the domains array of a proxy-match rule would
match the FQDN "example.com". This is done to prevent commonly
needing to include both "*.example.com" and "example.com" in the
domains array of a proxy-match rule. Matches are performed against
absolute domain names, independent of the client's configured DNS
search suffixes. Clients MUST NOT apply local DNS suffix search
Pauly, et al. Expires 18 April 2026 [Page 12]
Internet-Draft Proxy Configuration PvDs October 2025
rules when interpreting domains entries. A trailing dot (".") at the
end of a domain name is not required; the matching logic is the same
regardless of its presence or absence.
The subnets array includes IPv4 and IPv6 address literals, as well as
IPv4 and IPv6 address subnets written using CIDR notation. Subnet-
based destination information can apply to cases where applications
are communicating directly with an IP address (without having
resolved a DNS name) as well as cases where an application resolved a
DNS name to a set of IP addresses. Note that if destination rules
includes an empty proxies list (indicating that no proxy is
applicable for this subnet), an application can only reliably follow
this destination rule if it resolves DNS names prior to proxying.
The ports array includes specific ports (used for matching TCP and/or
UDP ports), as well as ranges of ports written with a low port value
and a high port value, with a - in between. For example, "1024-2048"
matches all ports from 1024 to 2048, including the 1024 and 2048. If
ports key is not present, all ports are assumed to match. The list
may contain individual port numbers (such as "80") or inclusive
ranges of ports. For example "1024-2048" matches all ports from 1024
to 2048, including the 1024 and 2048.
4.2. Using Destination Rules
The destination rules can be used to determine which traffic can be
sent through proxies, and which specific set of proxies to use for
any particular connection. By evaluating the rules in order, a
consistent behavior for usage can be achieved.
Rules in the proxy-match list are provided in order of priority, such
that a client can evaluate the list of rules from the first in the
array to the last in the array, and attempt using the matching proxy
or proxies from the earliest matching rule first. If earliest
matching rule has empty list of proxies client SHOULD NOT send
matching traffic to any proxy defined in this PvD.
In order to match a destination rule in the proxy-match list, all
properties MUST apply. For example, if a destination rule includes a
domains array and a ports array, traffic that matches the rule needs
to match at least one of the entries in the domains array and one of
the entries in the ports array. In addition, a destination rule is
considered a match only if at least one of the associated proxy
identifiers supports the protocol required by the connection attempt
(for example, connect-udp for UDP traffic). If no listed proxy
identifier is applicable to the protocol, the rule MUST be treated as
not matching, and the client continues evaluation of subsequent
rules.
Pauly, et al. Expires 18 April 2026 [Page 13]
Internet-Draft Proxy Configuration PvDs October 2025
A matched rule will then either point to one or more proxy identifier
values, which correspond to proxies defined in the list from
Section 3, or instructs the client to not send the matching traffic
to any proxy. If a matching rule contains more then one identifier
the client should treat the list as an ordered list, where the first
identifier is the most preferred. Multiple proxy dictionaries can
contain the same identifier value. In this case, the client can
choose any of the proxies; however, the client ought to prefer using
the same proxy for the consecutive requests to the same proxy
identifier to increase connection reuse.
Entries listed in a proxy-match object MUST NOT expand the set of
destinations that a client is willing to send to a particular proxy.
The list can only narrow the list of destinations that the client is
willing to send through the proxy. For example, if the client has a
local policy to only send requests for "*.example.com" to a proxy
"proxy.example.com", and domains array of a match object contains
"internal.example.com" and "other.company.com", the client would end
up only proxying "internal.example.com" through the proxy.
4.3. Proprietary Keys in Destination Rules
Implementations MAY include proprietary or vendor-specific keys in
destination rules to define custom matching logic not specified in
this document.
Similar to proprietary keys in proxy definitions (Section 3.2), a
proprietary key in destination rule MUST contain at least one
underscore character ("_"), which separates a vendor-specific
namespace from the key name. For example, "acme_processid" could be
a key used to apply rules only to traffic of a specific process
identifier as defined by a vendor named "acme".
Clients that encounter a proprietary key they do not recognize MUST
ignore the entire destination rule in which the key appears. This
ensures that unknown or unsupported matching logic does not
inadvertently influence proxy selection or bypass security controls.
This handling applies uniformly across all match rules, including
fallback rules.
4.4. Examples
In the following example, two proxies are defined with a common
identifier ("default_proxy"), with a single destination rule for
"*.internal.example.org".
Pauly, et al. Expires 18 April 2026 [Page 14]
Internet-Draft Proxy Configuration PvDs October 2025
{
"identifier": "proxy.example.org.",
"expires": "2023-06-23T06:00:00Z",
"prefixes": [],
"proxies": [
{
"protocol": "http-connect",
"proxy": "proxy.example.org:80",
"identifier": "default_proxy"
},
{
"protocol": "http-connect",
"proxy": "proxy2.example.org:80",
"identifier": "default_proxy"
}
],
"proxy-match": [
{
"domains": [ "*.internal.example.org" ],
"proxies": [ "default_proxy" ]
}
]
}
The client could then choose to use either proxy associated with the
"default_proxy" identifier for accessing TCP hosts that fall within
the "*.internal.example.org" zone. This would include the hostnames
"internal.example.org", "foo.internal.example.org",
"www.bar.internal.example.org" and all other hosts within
"internal.example.org". The client will use the same proxy for the
following requests to hosts falling into the "*.internal.example.org"
zone to increase connection reuse and make use of the connection
resumption. The client will not use the proxies defined in this
configuration to hosts outside of the "*.internal.example.org" zone.
In the next example, two proxies are defined with a separate
identifiers, and there are three destination rules:
Pauly, et al. Expires 18 April 2026 [Page 15]
Internet-Draft Proxy Configuration PvDs October 2025
{
"identifier": "proxy.example.org.",
"expires": "2023-06-23T06:00:00Z",
"prefixes": [],
"proxies": [
{
"protocol": "http-connect",
"proxy": "proxy.example.org:80",
"identifier": "default_proxy"
},
{
"protocol": "http-connect",
"proxy": "special-proxy.example.org:80",
"identifier": "special_proxy"
}
],
"proxy-match": [
{
"domains": [ "*.special.example.org" ],
"ports": [ "80", "443", "49152-65535" ],
"proxies": [ "special_proxy" ]
},
{
"domains": [ "no-proxy.internal.example.org" ],
"proxies": [ ]
},
{
"domains": [ "*.internal.example.org" ],
"proxies": [ "default_proxy" ]
}
]
}
In this case, the client would use "special-proxy.example.org:80" for
any TCP traffic that matches "*.special.example.org" destined to
ports 80, 443 or any port between 49152 and 65535. The client would
not use any of the defined proxies for access to "no-
proxy.internal.example.org". And finally, the client would use
"proxy.example.org:80" to access any other TCP traffic that matches
"*.internal.example.org".
In the following example, three proxies are sharing a common
identifier ("default-proxy"), but use separate protocols constraining
the traffic that they can process.
Pauly, et al. Expires 18 April 2026 [Page 16]
Internet-Draft Proxy Configuration PvDs October 2025
{
"identifier": "proxy.example.org.",
"expires": "2023-06-23T06:00:00Z",
"prefixes": [],
"proxies": [
{
"protocol": "http-connect",
"proxy": "proxy.example.org:80",
"identifier": "default_proxy"
},
{
"protocol": "connect-udp",
"proxy": "https://proxy.example.org/masque/udp/{target_host},{target_port}",
"identifier": "default_proxy"
},
{
"protocol": "connect-ip",
"proxy": "https://proxy.example.org/masque/ip{?target,ipproto}",
"identifier": "default_proxy"
}
],
"proxy-match": [
{
"domains": [ "*.internal.example.org" ],
"proxies": [ "default_proxy" ]
}
]
}
The client would use proxies in the following way:
* Traffic not destined to hosts within the "*.internal.example.org"
zone is not sent to any proxy defined in this configuration
* TCP traffic destined to hosts within the "*.internal.example.org"
zone is sent either to the proxy with "http-connect" protocol or
to the proxy with "connect-ip" protocol
* UDP traffic destined to hosts within the "*.internal.example.org"
zone is sent either to the proxy with "connect-udp" protocol or to
the proxy with "connect-ip" protocol
* Traffic other than TCP and UDP destined to hosts within the
"*.internal.example.org" zone is sent to the proxy with "connect-
ip" protocol
The following example provides a configuration of proxies to be used
by default with a set with exceptions to bypass:
Pauly, et al. Expires 18 April 2026 [Page 17]
Internet-Draft Proxy Configuration PvDs October 2025
{
"identifier": "proxy.example.org.",
"expires": "2023-06-23T06:00:00Z",
"prefixes": [],
"proxies": [
{
"protocol": "http-connect",
"proxy": "proxy.example.org:80",
"identifier": "default_proxy"
},
{
"protocol": "http-connect",
"proxy": "backup.example.org:80",
"identifier": "secondary_proxy"
}
],
"proxy-match": [
{
"domains": [ "*.intranet.example.org" ],
"proxies": [ ]
},
{
"subnets": [ "192.168.0.0/16", "2001:DB8::/32" ],
"proxies": [ ]
},
{
"proxies": [ "default_proxy", "secondary_proxy" ]
}
]
}
In this case, the client will not forward TCP traffic that is
destined to hosts matching "*.intranet.example.org", 192.168.0.0/16
or 2001:DB8::/32, through the proxies. Due to the order in "proxies"
list in the last rule of "proxy-match", the client would prefer
"proxy.example.org:80" over "backup.example.org:80"
5. Discovering proxies from network PvDs
[PVDDATA] defines how PvD Additional Information is discovered based
on network advertisements using Router Advertisements [RFC4861]. A
network defining its configuration via PvD information can include
the proxies key (Section 3) to inform clients of a list of proxies
available on the network.
This association of proxies with the network's PvD can be used as a
mechanism to discover proxies, as an alternative to PAC files.
However, client systems MUST NOT automatically send traffic over
Pauly, et al. Expires 18 April 2026 [Page 18]
Internet-Draft Proxy Configuration PvDs October 2025
proxies advertised in this way without explicit configuration,
policy, or user permission. For example, a client can use this
mechanism to choose between known proxies, such as if the client was
already proxying traffic and has multiple options to choose between.
Further security and experience considerations are needed for these
cases.
6. Security Considerations
The mechanisms in this document allow clients using a proxy to
"upgrade" a configuration for a cleartext HTTP/1.1 or SOCKS proxy
into a configuration that uses TLS to communication to the proxy.
This upgrade can add protection to the proxied traffic so it is less
observable by entities along the network path; however it does not
prevent the proxy itself from observing the traffic being proxied.
Configuration advertised via PvD Additional Information, such DNS
zones or associated proxies, can only be safely used when fetched
over a secure TLS-protected connection, and the client has validated
that that the hostname of the proxy, the identifier of the PvD, and
the validated hostname identity on the certificate all match.
When using information in destination rules (Section 4), clients MUST
only allow the PvD configuration to narrow the scope of traffic that
they will send through a proxy. Clients that are configured by
policy to only send a particular set of traffic through a particular
proxy can learn about rules that will cause them to send more
narrowly-scoped traffic, but MUST NOT send traffic that would go
beyond what is allowed by local policy.
7. IANA Considerations
7.1. New PvD Additional Information key
This document registers two new keys in the "Additional Information
PvD Keys" registry.
7.1.1. proxies Key
JSON Key: proxies
Description: Array of proxy dictionaries associated with this PvD
Type: Array of dictionaries
Example:
Pauly, et al. Expires 18 April 2026 [Page 19]
Internet-Draft Proxy Configuration PvDs October 2025
[
{
"protocol": "connect-udp",
"proxy": "https://proxy.example.org/masque{?target_host,target_port}"
}
]
7.1.2. proxy-match Key
JSON Key: proxy-match
Description: Array of proxy match rules, as dictionaries, associated
with entries in the proxies list.
Type: Array of dictionaries
Example:
[
{
"domains": [ "*.internal.example.org" ],
"proxies": [ "default_proxy" ]
}
]
7.2. New PvD Proxy Information Registry
IANA is requested to create a new registry "Proxy Information PvD
Keys", within the "Provisioning Domains (PvDs)" registry page. This
new registry reserves JSON keys for use in sub-dictionaries under the
proxies key. The initial contents of this registry are given in
Table 1.
New assignments in the "Proxy Information PvD Keys" registry will be
administered by IANA through Expert Review [RFC8126]. Experts are
requested to ensure that defined keys do not overlap in names or
semantics.
7.3. New PvD Proxy Protocol Registry
IANA is requested to create a new registry "Proxy Protocol PvD
Values", within the "Provisioning Domains (PvDs)" registry page.
This new registry reserves JSON values for the protocol key in
proxies sub-dictionaries. The initial contents of this registry are
given in Table 2.
Pauly, et al. Expires 18 April 2026 [Page 20]
Internet-Draft Proxy Configuration PvDs October 2025
New assignments in the "Proxy Protocol PvD Values" registry will be
administered by IANA through Expert Review [RFC8126]. Experts are
requested to ensure that defined keys do not overlap in names or
semantics, do not contain an underscore character ("_") in the names
(since underscores are reserved for vendor-specific keys), and have
clear format definitions. The reference and notes fields MAY be
empty.
7.4. New PvD Proxy Destination Rule Registry
IANA is requested to create a new registry "Proxy Destination Rule
PvD Keys", within the "Provisioning Domains (PvDs)" registry page.
This new registry reserves JSON keys for use in sub-dictionaries
under the proxy-match key. The initial contents of this registry are
given in Table 3.
New assignments in the "Proxy Destination Rule PvD Keys" registry
will be administered by IANA through Expert Review [RFC8126].
Experts are requested to ensure that defined keys do not overlap in
names or semantics, and do not contain an underscore character ("_")
in the names (since underscores are reserved for vendor-specific
keys).
7.5. New DNS SVCB Service Parameter Key (SvcParamKey)
IANA is requested to add a new entry to the "DNS SVCB Service
Parameter Keys (SvcParamKeys)" registry:
* Number: TBD
* Name: pvd
* Meaning: PvD configuration is available at the well-known path
* Change Controller: IETF
* Reference: this document, Section 2.1
8. References
8.1. Normative References
[ALPN] Friedl, S., Popov, A., Langley, A., and E. Stephan,
"Transport Layer Security (TLS) Application-Layer Protocol
Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301,
July 2014, <https://www.rfc-editor.org/rfc/rfc7301>.
Pauly, et al. Expires 18 April 2026 [Page 21]
Internet-Draft Proxy Configuration PvDs October 2025
[CONNECT-IP]
Pauly, T., Ed., Schinazi, D., Chernyakhovsky, A.,
Kühlewind, M., and M. Westerlund, "Proxying IP in HTTP",
RFC 9484, DOI 10.17487/RFC9484, October 2023,
<https://www.rfc-editor.org/rfc/rfc9484>.
[CONNECT-TCP]
Schwartz, B. M., "Template-Driven HTTP CONNECT Proxying
for TCP", Work in Progress, Internet-Draft, draft-ietf-
httpbis-connect-tcp-09, 30 June 2025,
<https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-
connect-tcp-09>.
[CONNECT-UDP]
Schinazi, D., "Proxying UDP in HTTP", RFC 9298,
DOI 10.17487/RFC9298, August 2022,
<https://www.rfc-editor.org/rfc/rfc9298>.
[HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP Semantics", STD 97, RFC 9110,
DOI 10.17487/RFC9110, June 2022,
<https://www.rfc-editor.org/rfc/rfc9110>.
[JSON] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", STD 90, RFC 8259,
DOI 10.17487/RFC8259, December 2017,
<https://www.rfc-editor.org/rfc/rfc8259>.
[PVDDATA] Pfister, P., Vyncke, É., Pauly, T., Schinazi, D., and W.
Shao, "Discovering Provisioning Domain Names and Data",
RFC 8801, DOI 10.17487/RFC8801, July 2020,
<https://www.rfc-editor.org/rfc/rfc8801>.
[RFC2119] Bradner, S., "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/rfc/rfc2119>.
[RFC8126] Cotton, M., Leiba, B., 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/rfc/rfc8126>.
[RFC8174] Leiba, B., "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/rfc/rfc8174>.
Pauly, et al. Expires 18 April 2026 [Page 22]
Internet-Draft Proxy Configuration PvDs October 2025
[SOCKSv5] Leech, M., Ganis, M., Lee, Y., Kuris, R., Koblas, D., and
L. Jones, "SOCKS Protocol Version 5", RFC 1928,
DOI 10.17487/RFC1928, March 1996,
<https://www.rfc-editor.org/rfc/rfc1928>.
[SVCB-DNS] Schwartz, B., Bishop, M., and E. Nygren, "Service Binding
and Parameter Specification via the DNS (SVCB and HTTPS
Resource Records)", RFC 9460, DOI 10.17487/RFC9460,
November 2023, <https://www.rfc-editor.org/rfc/rfc9460>.
[URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005,
<https://www.rfc-editor.org/rfc/rfc3986>.
[URITEMPLATE]
Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
and D. Orchard, "URI Template", RFC 6570,
DOI 10.17487/RFC6570, March 2012,
<https://www.rfc-editor.org/rfc/rfc6570>.
8.2. Informative References
[IKEV2SPLIT]
Pauly, T. and P. Wouters, "Split DNS Configuration for the
Internet Key Exchange Protocol Version 2 (IKEv2)",
RFC 8598, DOI 10.17487/RFC8598, May 2019,
<https://www.rfc-editor.org/rfc/rfc8598>.
[PVD] Anipko, D., Ed., "Multiple Provisioning Domain
Architecture", RFC 7556, DOI 10.17487/RFC7556, June 2015,
<https://www.rfc-editor.org/rfc/rfc7556>.
[RFC3040] Cooper, I., Melve, I., and G. Tomlinson, "Internet Web
Replication and Caching Taxonomy", RFC 3040,
DOI 10.17487/RFC3040, January 2001,
<https://www.rfc-editor.org/rfc/rfc3040>.
[RFC4861] Narten, T., Nordmark, E., Simpson, W., and H. Soliman,
"Neighbor Discovery for IP version 6 (IPv6)", RFC 4861,
DOI 10.17487/RFC4861, September 2007,
<https://www.rfc-editor.org/rfc/rfc4861>.
Authors' Addresses
Tommy Pauly
Apple, Inc.
Email: tpauly@apple.com
Pauly, et al. Expires 18 April 2026 [Page 23]
Internet-Draft Proxy Configuration PvDs October 2025
Dragana Damjanovic
Microsoft
Email: ddamjanovic@microsoft.com
Yaroslav Rosomakho
Zscaler
Email: yrosomakho@zscaler.com
Pauly, et al. Expires 18 April 2026 [Page 24]