From 4bfd864f10b68b71482b35c818559068ef8d5797 Mon Sep 17 00:00:00 2001 From: Thomas Voss Date: Wed, 27 Nov 2024 20:54:24 +0100 Subject: doc: Add RFC documents --- doc/rfc/rfc9532.txt | 327 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 327 insertions(+) create mode 100644 doc/rfc/rfc9532.txt (limited to 'doc/rfc/rfc9532.txt') diff --git a/doc/rfc/rfc9532.txt b/doc/rfc/rfc9532.txt new file mode 100644 index 0000000..6575fa2 --- /dev/null +++ b/doc/rfc/rfc9532.txt @@ -0,0 +1,327 @@ + + + + +Internet Engineering Task Force (IETF) T. Pauly +Request for Comments: 9532 Apple, Inc. +Category: Standards Track January 2024 +ISSN: 2070-1721 + + + HTTP Proxy-Status Parameter for Next-Hop Aliases + +Abstract + + This document defines the next-hop-aliases HTTP Proxy-Status + Parameter. This parameter carries the list of aliases and canonical + names an intermediary received during DNS resolution as part of + establishing a connection to the next hop. + +Status of This Memo + + This is an Internet Standards Track document. + + This document is a product of the Internet Engineering Task Force + (IETF). It represents the consensus of the IETF community. It has + received public review and has been approved for publication by the + Internet Engineering Steering Group (IESG). Further information on + Internet Standards is available in Section 2 of RFC 7841. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + https://www.rfc-editor.org/info/rfc9532. + +Copyright Notice + + Copyright (c) 2024 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. + +Table of Contents + + 1. Introduction + 1.1. Requirements + 2. next-hop-aliases Parameter + 2.1. Encoding Special Characters + 3. Implementation Considerations + 4. Security Considerations + 5. IANA Considerations + 6. References + 6.1. Normative References + 6.2. Informative References + Author's Address + +1. Introduction + + The Proxy-Status HTTP response field [PROXY-STATUS] allows + intermediaries to convey information about how they handled the + request in HTTP responses sent to clients. It defines a set of + parameters that provide information, such as the name of the next + hop. + + [PROXY-STATUS] defines a next-hop parameter, which can contain a + hostname, IP address, or alias of the next hop. This parameter can + contain only one such item, so it cannot be used to communicate a + chain of aliases encountered during DNS resolution when connecting to + the next hop. + + Knowing the full chain of names that were used during DNS resolution + via CNAME records [DNS] is particularly useful for clients of forward + proxies, in which the client is requesting to connect to a specific + target hostname using the CONNECT method [HTTP] or UDP proxying + [CONNECT-UDP]. CNAME records can be used to "cloak" hosts that + perform tracking or malicious activity behind more innocuous + hostnames, and clients such as web browsers use the chain of DNS + names to influence behavior like cookie usage policies [COOKIES] or + the blocking of malicious hosts. + + This document allows clients to receive the CNAME chain of DNS names + for the next hop by including the list of names in a new next-hop- + aliases Proxy-Status parameter. + +1.1. 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. next-hop-aliases Parameter + + The value of the next-hop-aliases parameter is a String + [STRUCTURED-FIELDS] that contains one or more DNS names in a comma- + separated list. The items in the list include all alias names and + canonical names received in CNAME records [DNS] during the course of + resolving the next hop's hostname using DNS and MAY include the + original requested hostname itself. The names ought to appear in the + order in which they were received in DNS, for the sake of + consistency. If there are multiple CNAME records in the chain, the + first name in the next-hop-aliases list would be the value in the + CNAME record for the original hostname, and the final name in the + next-hop-aliases list would be the name that ultimately resolved to + one or more addresses. + + The list of DNS names in next-hop-aliases parameter uses a comma + (",") as a separator between names. Note that if a comma is included + in a name itself, the comma must be encoded as described in + Section 2.1. + + For example, consider a proxy "proxy.example.net" that receives the + following records when performing DNS resolution for the next hop + "host.example.com": + + host.example.com. CNAME tracker.example.com. + tracker.example.com. CNAME service1.example.com. + service1.example.com. AAAA 2001:db8::1 + + The proxy could include the following proxy status in its response: + + Proxy-Status: proxy.example.net; next-hop="2001:db8::1"; + next-hop-aliases="tracker.example.com,service1.example.com" + + This indicates that "proxy.example.net", which used the IP address + "2001:db8::1" as the next hop for this request, encountered the names + "tracker.example.com" and "service1.example.com" in the DNS + resolution chain. Note that while this example includes both the + next-hop and next-hop-aliases parameters, next-hop-aliases can be + included without including next-hop. + + The proxy can also include the name of the next hop as the first item + in the list. This is particularly useful for reverse proxies when + clients would not otherwise know the name of the next hop, and the + next-hop header is used to convey an IP address. + + For example, consider a proxy "reverseproxy.example.net" that + receives the following records when performing DNS resolution for the + next hop "host.example.com": + + host2.example.com. CNAME service2.example.com. + service2.example.com. AAAA 2001:db8::2 + + The proxy could include the following proxy status in its response: + + Proxy-Status: reverseproxy.example.net; next-hop="2001:db8::2"; + next-hop-aliases="host2.example.com,service2.example.com" + + The next-hop-aliases parameter only applies when DNS was used to + resolve the next hop's name, and it does not apply in all situations. + Clients can use the information in this parameter to determine how to + use the connection established through the proxy, but they need to + gracefully handle situations in which this parameter is not present. + + The proxy MAY send the empty string ("") as the value of next-hop- + aliases parameter to indicate that no CNAME records were encountered + when resolving the next hop's name. + +2.1. Encoding Special Characters + + DNS names commonly contain just alphanumeric characters and hyphens + ("-"), although they are allowed to contain any character ([RFC1035], + Section 3.1), including a comma. To prevent commas or other special + characters in names leading to incorrect parsing, any characters that + appear in names in this list that do not belong to the set of URI + unreserved characters ([RFC3986], Section 2.3) MUST be percent- + encoded as defined in [RFC3986], Section 2.1. + + For example, consider the DNS name "comma,name.example.com". This + name would be encoded within a next-hop-aliases parameter as follows: + + Proxy-Status: proxy.example.net; next-hop="2001:db8::1"; + next-hop-aliases="comma%2Cname.example.com,service1.example.com" + + It is also possible for a DNS name to include a period character + (".") within a label instead of as a label separator. In this case, + the period character MUST first be escaped as "\.". Since the "\" + character itself will be percent-encoded, the name + "dot\.label.example.com" would be encoded within a next-hop-aliases + parameter as follows: + + Proxy-Status: proxy.example.net; next-hop="2001:db8::1"; + next-hop-aliases="dot%5C.label.example.com,service1.example.com" + + Upon parsing this name, "dot%5C.label" MUST be treated as a single + label. + + Similarly, the "\" character in a label MUST be escaped as "\\" and + then percent-encoded. Other uses of "\" MUST NOT appear in the label + after percent-decoding. For example, if there is a DNS name + "backslash\name.example.com", it would first be escaped as + "backslash\\name.example.com" and then percent-encoded as follows: + + Proxy-Status: proxy.example.net; next-hop="2001:db8::1"; + next-hop-aliases="backslash%5C%5Cname.example.com,s1.example.com" + +3. Implementation Considerations + + In order to include the next-hop-aliases parameter, a proxy needs to + have access to the chain of alias names and canonical names received + in CNAME records. + + Implementations ought to note that the full chain of names might not + be available in common DNS resolution APIs, such as getaddrinfo + [POSIX]. getaddrinfo does have an option for AI_CANONNAME ([RFC3493], + Section 6.1), but this will only return the last name in the chain + (the canonical name), not the alias names. + + An implementation MAY include incomplete information in the next-hop- + aliases parameter to accommodate cases where it is unable to include + the full chain, such as only including the canonical name if the + implementation can only use getaddrinfo as described above. + +4. Security Considerations + + The next-hop-aliases parameter does not include any DNSSEC + information or imply that DNSSEC was used. The information included + in the parameter can only be trusted to be valid insofar as the + client trusts the proxy to provide accurate information. This + information is intended to be used as a hint and SHOULD NOT be used + for making security decisions about the identity of a resource + accessed through the proxy. + + Inspecting CNAME chains can be used to detect cloaking of trackers or + malicious hosts. However, the CNAME records could be omitted by a + recursive or authoritative resolver that is trying to hide this form + of cloaking. In particular, recursive or authoritative resolvers can + omit these records for both clients directly performing DNS name + resolution and proxies performing DNS name resolution on behalf of a + client. A malicious proxy could also choose to not report these + CNAME chains in order to hide the cloaking. In general, clients can + trust information included (or not included) in the next-hop-aliases + parameter to the degree that the proxy and any resolvers used by the + proxy are trusted. + +5. IANA Considerations + + This document registers the next-hop-aliases parameter in the "HTTP + Proxy-Status Parameters" registry as shown in Table 1. + + +==================+=================================+===========+ + | Name | Description | Reference | + +==================+=================================+===========+ + | next-hop-aliases | A string containing one or more | RFC 9532 | + | | DNS aliases or canonical names | | + | | used to establish a proxied | | + | | connection to the next hop. | | + +------------------+---------------------------------+-----------+ + + Table 1: HTTP Proxy-Status Parameters Registry + +6. References + +6.1. Normative References + + [CONNECT-UDP] + Schinazi, D., "Proxying UDP in HTTP", RFC 9298, + DOI 10.17487/RFC9298, August 2022, + . + + [DNS] Mockapetris, P., "Domain names - concepts and facilities", + STD 13, RFC 1034, DOI 10.17487/RFC1034, November 1987, + . + + [HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, + Ed., "HTTP Semantics", STD 97, RFC 9110, + DOI 10.17487/RFC9110, June 2022, + . + + [PROXY-STATUS] + Nottingham, M. and P. Sikora, "The Proxy-Status HTTP + Response Header Field", RFC 9209, DOI 10.17487/RFC9209, + June 2022, . + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, + DOI 10.17487/RFC2119, March 1997, + . + + [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform + Resource Identifier (URI): Generic Syntax", STD 66, + RFC 3986, DOI 10.17487/RFC3986, January 2005, + . + + [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC + 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, + May 2017, . + + [STRUCTURED-FIELDS] + Nottingham, M. and P. Kamp, "Structured Field Values for + HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021, + . + +6.2. Informative References + + [COOKIES] Barth, A., "HTTP State Management Mechanism", RFC 6265, + DOI 10.17487/RFC6265, April 2011, + . + + [POSIX] IEEE, "IEEE Standard for Information Technology--Portable + Operating System Interface (POSIX(TM)) Base + Specifications, Issue 7", IEEE Std 1003.1-2017, + DOI 10.1109/IEEESTD.2018.8277153, January 2018, + . + + [RFC1035] Mockapetris, P., "Domain names - implementation and + specification", STD 13, RFC 1035, DOI 10.17487/RFC1035, + November 1987, . + + [RFC3493] Gilligan, R., Thomson, S., Bound, J., McCann, J., and W. + Stevens, "Basic Socket Interface Extensions for IPv6", + RFC 3493, DOI 10.17487/RFC3493, February 2003, + . + +Author's Address + + Tommy Pauly + Apple, Inc. + Email: tpauly@apple.com -- cgit v1.2.3