RFC 7871

Client Subnet in DNS Queries

📅 published May 2016, from ietf

RFC 7871: Client Subnet in DNS Queries 💖

Okay bestie, here's the big picture 🦋

  • Who wrote it: C. Contavalli, W. van der Gaast, D. Lawrence, and W. Kumari (the author list is spelled out in the Authors' Addresses section near the end)
  • Organisations: Google (Contavalli, van der Gaast, Kumari) and Akamai Technologies (Lawrence)
  • Category: Informational 🧚
  • Date: May 2016
  • Series: Request for Comments 7871, from the Internet Engineering Task Force (IETF), ISSN 2070-1721
  • Obsoletes / Updates: The header doesn't list anything this RFC obsoletes or updates 🙈

Abstract

okay so this doc describes an EDNS0 option (Extension Mechanisms for DNS) that's already being used in the wild 🔥 It carries info about the network that a DNS query came from, and about the network that the answer can be cached for. Because it has some known operational and privacy problems, the IETF is going to work on a revision to make it better 💅

Status of This Memo

ngl this one is not a standards track spec. It's published just for information 📚

It is a product of the IETF, and it reflects consensus from the IETF community. It got public review and was approved by the Internet Engineering Steering Group (IESG). Not every IESG-approved doc is eligible for any level of Internet Standard, see Section 2 of RFC 5741 for that.

If you want the current status, errata, or a way to send feedback, check out this link: http://www.rfc-editor.org/info/rfc7871 🎀

Copyright (c) 2016 IETF Trust and the persons identified as the document authors. All rights reserved. ✨

This doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as they were in effect when it was published. Please actually read these, because they spell out your rights and restrictions for this document 🙈 Any code pulled out of this document has to include Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions, and it comes with no warranty, as the Simplified BSD License describes.

Table of Contents

   1. Introduction ....................................................4
   2. Privacy Note ....................................................5
   3. Requirements Notation ...........................................5
   4. Terminology .....................................................6
   5. Overview ........................................................7
   6. Option Format ...................................................8
   7. Protocol Description ............................................9
      7.1. Originating the Option .....................................9
           7.1.1. Recursive Resolvers .................................9
           7.1.2. Stub Resolvers .....................................10
           7.1.3. Forwarding Resolvers ...............................11
      7.2. Generating a Response .....................................11
           7.2.1. Authoritative Nameserver ...........................11
           7.2.2. Intermediate Nameserver ............................13
      7.3. Handling ECS Responses and Caching ........................14
           7.3.1. Caching the Response ...............................15
           7.3.2. Answering from Cache ...............................16
      7.4. Delegations and Negative Answers ..........................17
      7.5. Transitivity ..............................................18
   8. IANA Considerations ............................................18
   9. DNSSEC Considerations ..........................................19
   10. NAT Considerations ............................................19
   11. Security Considerations .......................................20
      11.1. Privacy ..................................................20
      11.2. Birthday Attacks .........................................21
      11.3. Cache Pollution ..........................................22
   12. Sending the Option ............................................23
      12.1. Probing ..................................................23
      12.2. Whitelist ................................................24
   13. Example .......................................................24
   14. References ....................................................26
      14.1. Normative References .....................................26
      14.2. Informative References ...................................27
   Acknowledgements ..................................................28
   Contributors ......................................................29
   Authors' Addresses ................................................30

1. Introduction 🌸

A lot of Authoritative Nameservers today send back different answers depending on where they think the user is topologically. To figure out where that is, they look at the IP address of the incoming query 👀

Here's the catch: most queries come from Intermediate Recursive Resolvers, so the source address is the Recursive Resolver's, not the address of whoever started the query.

Traditionally (and probably still in most cases), Recursive Resolvers sit reasonably close, topologically, to the Stub Resolvers or Forwarding Resolvers that send them queries. For those setups, the resolver's own IP address is good enough for Authoritative Nameservers that tailor answers by where the asker is 💅

But now there's a growing class of Recursive Resolvers that handle queries from sources that are often nowhere near them topologically. Why would anyone do that? Usually for a better experience, like stronger cache security or enforcing policies about where users are allowed to connect. (Yes, political censorship is the first thing that comes to mind, but a parent can use the same moves to control where a minor connects 🙈) ISPs and other orgs also run Centralized Resolver setups that can be far away from the clients they serve. All of this leads to less-than-ideal answers from topology-sensitive Authoritative Nameservers 😭

So this document defines an EDNS0 option [RFC6891] that carries network info relevant to the DNS message. It gives the Authoritative Nameserver enough network info about the originator to tailor the response. It also lets the Authoritative Nameserver say which range of network addresses the tailored answer is meant for ✨ This option is meant for Recursive Resolvers and Authoritative Nameservers that would actually benefit from it, not for general purpose deployment. It's completely optional, and servers that choose not to implement or enable it can safely ignore it 🫶

This document also covers how to cache those results well, and gives recommendations on when to use this extension.

At least a dozen client and server implementations were written from earlier draft versions of this spec, and it's in active production use today 🔥 The implementations do interoperate, but they behave differently in edge cases that were poorly specified. This document lists the known incompatibilities. The authors think it's better to describe the system as it actually works today, even if not everyone agrees with the details of the original spec ([VANDERGAAST]). The alternative is an undocumented, proprietary system, and nobody wants that 💀

A revised proposal to fix the minor flaws in this protocol will be coming to the IETF.

2. Privacy Note 🙈

Real talk: if we were starting to design this mechanism from scratch, it's unlikely we'd do it exactly this way.

The IETF is actively working on DNS privacy [DPRIVE_Working_Group], and reinjecting metadata [METADATA] has been flagged as a problematic design pattern 😬

That said, this document mainly describes how a deployed method already works, so the wider Internet community can understand it 📚

We recommend turning this feature off by default in all nameserver software. Operators should only switch it on explicitly when it clearly benefits their clients. We also encourage making it possible for users to use the opt-out this spec provides. Last thing: we recommend that others avoid techniques that add extra metadata in future work, because it can damage user trust 💜

Sadly, support for the opt-out parts of this spec is pretty limited right now. Only one stub resolver, getdns, is known to send queries with anonymity requested, and no applications are yet known to tell the stub resolver what the user prefers 😭

3. Requirements Notation ✨

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].

4. Terminology 📖

Here's the vocab you need, bestie 🧚

  • ECS: EDNS Client Subnet.
  • Client: A Stub Resolver, Forwarding Resolver, or Recursive Resolver. It's a client of a Recursive Resolver or a Forwarding Resolver.
  • Server: A Forwarding Resolver, Recursive Resolver, or Authoritative Nameserver.
  • Stub Resolver: A simple DNS protocol implementation on the client side, as described in [RFC1034], Section 5.3.1. It's a client of a Recursive Resolver or a Forwarding Resolver.
  • Authoritative Nameserver: A nameserver with authority over one or more DNS zones. Stub Resolvers and end-user clients don't normally contact these directly. Recursive Resolvers do. Described in [RFC1035], Section 6.
  • Recursive Resolver: A nameserver that's responsible for resolving domain names for clients by following the domain's delegation chain. Recursive Resolvers often use caches so they can answer client queries quickly. Described in [RFC1035], Section 7.
  • Forwarding Resolver: A nameserver that doesn't do iterative resolution itself. It hands that job off to another Recursive Resolver, which [RFC2308], Section 1 calls a "Forwarder" 🍓
  • Intermediate Nameserver: Any nameserver between the Stub Resolver and the Authoritative Nameserver, such as a Recursive Resolver or a Forwarding Resolver.
  • Centralized Resolvers: Intermediate Nameservers that serve a topologically diverse network address space 🌈
  • Tailored Response: A response from a nameserver that's customized for the node that sent the query, often based on performance (for example, lowest latency, fewest hops, topological distance, and so on) 💅
  • Topologically Close: Two hosts are topologically close when it takes few hops, or little time, for a packet to get from one to the other. Topological distance is only loosely related to geographical distance. Two geographically close hosts can still be very far apart topologically, and two geographically distant hosts can be quite close on the network 🦋

For a more thorough look at DNS terms, check out [RFC7719] 🫶

5. Overview ✨

okay so the big idea here is giving Recursive Resolvers 💖 the option (if they're down for it 🫶) to tell other nameservers roughly where a query is coming from, like which origin network it's from 🌸

The edns-client-subnet (ECS) EDNS0 option format is in Section 6. It's meant to get added to queries sent by Intermediate Nameservers in a way that's totally transparent to Stub Resolvers and end users, see Section 7.1. ECS is only defined for the Internet (IN) DNS class 🦋

Per Section 7.2, an Authoritative Nameserver could use ECS as a hint about the end user's network location and give a better answer ✨ Its response would also include an ECS option, which clearly shows the server used that info and that the answer is tied to the client's network. main character energy 👑

As described in Section 7.3, Intermediate Nameservers would use this info to cache the response 🧚

Some Intermediate Nameservers may also need to forward ECS queries they get, as described in Section 7.5 💅

ECS brings some security-related stuff along for the ride: cache growth, the ability to spoof EDNS0 options, and privacy 😭 Section 11 goes through the mitigation techniques, so don't skip it bestie 🔥

The expectation, though, is that this option will mostly get used between Recursive Resolvers and Authoritative Nameservers that care about network location issues. Most Recursive Resolvers, Authoritative Nameservers, and Stub Resolvers will never need to know this option exists and will keep working just like they always did 🌈

Not supporting this option, or handling it badly, will at worst cause suboptimal identification of client network location. Honestly that's already a common thing in current Content Delivery Network (CDN) setups, so it's not the end of the world 🙈

Section 7.1 also gives Stub Resolvers a way to tell Recursive Resolvers that they don't want ECS treatment for specific queries 🫶

Also, operators of Intermediate Nameservers with ECS enabled get to choose how many bits of the address in received queries get forwarded. They can also reduce the number of bits forwarded for queries that already include an ECS option 🍓

6. Option Format 🎀

This protocol uses an EDNS0 [RFC6891] option to include client address information in DNS messages. The option is laid out like this 💜

              +0 (MSB)                            +1 (LSB)
    +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 0: |                          OPTION-CODE                          |
    +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 2: |                         OPTION-LENGTH                         |
    +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 4: |                            FAMILY                             |
    +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 6: |     SOURCE PREFIX-LENGTH      |     SCOPE PREFIX-LENGTH       |
    +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
 8: |                           ADDRESS...                          /
    +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
  • (Defined in [RFC6891]) OPTION-CODE, 2 octets, is 8 for ECS (0x00 0x08) 🌸
  • (Defined in [RFC6891]) OPTION-LENGTH, 2 octets, holds the length of the payload (everything after OPTION-LENGTH) in octets 🧁
  • FAMILY, 2 octets, shows the family of the address in the option, using address family codes assigned by IANA in Address Family Numbers [Address_Family_Numbers] 🦋

The format of the address part depends on the value of FAMILY. This document only defines the format for FAMILY 1 (IPv4) and FAMILY 2 (IPv6), which go like this ✨

  • SOURCE PREFIX-LENGTH, an unsigned octet for the leftmost number of significant bits of ADDRESS used for the lookup. In responses it mirrors the same value as in the queries 💅
  • SCOPE PREFIX-LENGTH, an unsigned octet for the leftmost number of significant bits of ADDRESS that the response covers. In queries it MUST be set to 0 🙈
  • ADDRESS, a variable number of octets, holds either an IPv4 or IPv6 address depending on FAMILY. It MUST be truncated to the number of bits in the SOURCE PREFIX-LENGTH field, padded with 0 bits out to the end of the last octet needed 🌈
  • A server that gets an ECS option with either too few or too many ADDRESS octets, or with non-zero ADDRESS bits set beyond SOURCE PREFIX-LENGTH, SHOULD return FORMERR to reject the packet. It's basically a signal to the software developer making the request to fix their implementation 😭

All fields are in network byte order ("big-endian", per [RFC1700], Data Notation) 🫶

7. Protocol Description 🦋

7.1. Originating the Option ✨

The ECS option should generally be added by Recursive Resolvers when querying Authoritative Nameservers, as described in Section 12. The option can also be initialized by a Stub Resolver or Forwarding Resolver 💖

7.1.1. Recursive Resolvers 👑

The setup of the ECS option in a Recursive Resolver depends on the client query that triggered the resolution process 🧚

In the usual case, where the client query had no ECS option, the Recursive Resolver initializes the option by setting FAMILY to the client's address family. Then it uses its maximum cacheable prefix length to set SOURCE PREFIX-LENGTH. For privacy reasons, and because the whole IP address is rarely needed to figure out a tailored response, this length SHOULD be shorter than the full address, as described in Section 11 🔥

If the triggering query included an ECS option itself, it MUST be examined for its SOURCE PREFIX-LENGTH. The Recursive Resolver's outgoing query MUST then set SOURCE PREFIX-LENGTH to the shorter of the incoming query's SOURCE PREFIX-LENGTH or the server's maximum cacheable prefix length 🍓

Finally, in both cases, SCOPE PREFIX-LENGTH is set to 0, and ADDRESS is then filled in up to SOURCE PREFIX-LENGTH bits, with trailing 0 bits added if needed to fill the final octet. The total number of octets used MUST only be enough to cover SOURCE PREFIX-LENGTH bits, not the full width that addresses in FAMILY would normally use 💅

FAMILY and ADDRESS info MAY be used from the ECS option in the incoming query. Passing the existing address data is helpful when the Recursive Resolver is the target of a Forwarding Resolver, but it could run into policy problems around usage agreements between the Recursive Resolver and the Authoritative Nameserver. See Section 12.2 for more on this 🫶 If the Recursive Resolver won't forward FAMILY and ADDRESS data from the incoming ECS option, it SHOULD return a REFUSED response 🙈

Subsequent queries to refresh the data MUST, if not restricted by an incoming SOURCE PREFIX-LENGTH, specify the longest SOURCE PREFIX-LENGTH the Recursive Resolver is willing to cache. This applies even if a previous response showed a shorter prefix length was enough 🌸

7.1.2. Stub Resolvers 🎀

A Stub Resolver MAY generate DNS queries with an ECS option that sets SOURCE PREFIX-LENGTH to limit how much network information gets revealed 🦋 An Intermediate Nameserver that receives such a query MUST NOT make queries that include more bits of client address than the originating query did 🙈

A SOURCE PREFIX-LENGTH value of 0 means the Recursive Resolver MUST NOT add the client's address information to its queries. The Recursive Resolver's later query to the Authoritative Nameserver will then either not include an ECS option or MAY optionally include its own address information. That's what the Authoritative Nameserver will almost certainly use to generate any Tailored Response in place of an option 🧚 This lets the answer be handled by the same caching mechanism as other queries, with an explicit indicator of the applicable scope. Later Stub Resolver queries for /0 can then be answered from this cached response 💖

A Stub Resolver MUST set SCOPE PREFIX-LENGTH to 0. It MAY include FAMILY and ADDRESS data, but should be prepared to handle a REFUSED response if the Intermediate Nameserver it queries has a policy that denies forwarding of ADDRESS. If there is no ADDRESS set, i.e., SOURCE PREFIX-LENGTH is set to 0, then FAMILY SHOULD be set to the transport over which the query is sent. This is for interoperability: at least one major authoritative server will ignore the option if FAMILY is not 1 or 2, even though it doesn't matter if there are no ADDRESS bits 🌈

7.1.3. Forwarding Resolvers 💅

Forwarding Resolvers basically look like Stub Resolvers to whatever Recursive Resolver is ultimately handling the query, but they look like a Recursive Resolver to their client 👑 A Forwarding Resolver using this option MUST prepare it as described in Section 7.1.1, "Recursive Resolvers". In particular, a Forwarding Resolver that implements this protocol MUST honor SOURCE PREFIX-LENGTH restrictions indicated in the incoming query from its client 🫶 See also Section 7.5 ✨

Since the Recursive Resolver it contacts will treat the Forwarding Resolver like a Stub Resolver, the Recursive Resolver's policies on incoming ADDRESS information apply in the same way 🦋 If the Forwarding Resolver gets a REFUSED response when it sends a query that includes a non-zero ADDRESS, it MUST retry with no ADDRESS 😭

7.2. Generating a Response 🧚

7.2.1. Authoritative Nameserver ✨

Okay so when a query with an ECS option shows up, an Authoritative Nameserver that supports ECS MAY use the address info in that option to whip up a tailored response 💅

Authoritative Nameservers that haven't implemented or enabled ECS support ought to safely ignore it in incoming queries, per [RFC6891], Section 6.1.2 🙈 Such a server MUST NOT include an ECS option in replies to say it doesn't support it. Implementers of Intermediate Nameservers should be aware, though 👀, that some nameservers incorrectly echo back unknown EDNS0 options. In this protocol that's mostly harmless 🌸, since the SCOPE PREFIX-LENGTH should come back as 0, which marks the response as covering all networks.

A query with a wrongly formatted option (e.g., an unknown FAMILY) MUST be rejected, and a FORMERR response MUST be returned to the sender, as described in [RFC6891], "Transport Considerations" 😭

An Authoritative Nameserver that implements this protocol and receives an ECS option MUST include an ECS option in its response to indicate that it SHOULD be cached accordingly, regardless of whether the client information was needed to formulate an answer. (Note that the requirement in [RFC6891] to reserve space for the OPT record could mean that the Answer section of the response will be truncated and fall back to TCP indicated accordingly.) If an ECS option was not included in a query, one MUST NOT be included in the response, even if the server is providing a Tailored Response -- presumably based on the address from which it received the query. It's giving "don't add stuff nobody asked for" 💀

FAMILY, SOURCE PREFIX-LENGTH, and ADDRESS in the response MUST match those in the query. Echoing these values back helps mitigate certain attack vectors, as described in Section 11 🛡️

SCOPE PREFIX-LENGTH in the response indicates the network the answer is intended for 🎯

A SCOPE PREFIX-LENGTH value longer than SOURCE PREFIX-LENGTH indicates that the provided prefix length wasn't specific enough to select the most appropriate Tailored Response. Future queries for the name within the specified network SHOULD use the longer SCOPE PREFIX-LENGTH. Whether the Recursive Resolver goes with the longer length depends on how much privacy masking the operator wants to give their users, plus the extra resource implications for the cache 🧠

Conversely, a shorter SCOPE PREFIX-LENGTH means more bits than necessary were provided, and the answer works for a broader range of addresses. It could be as short as 0, meaning the answer suits all addresses in FAMILY 🌈

The logical topology of any part of the network with regard to the Tailored Response can vary, so an Authoritative Nameserver may return different values of SCOPE PREFIX-LENGTH for different networks 🦋

Some queries can result in multiple RRsets being added to the response, which creates an unfortunate ambiguity from the original specification about how SCOPE PREFIX-LENGTH applies to each individual RRset. For example, multiple types returned for an ANY metaquery could all have different applicable SCOPE PREFIX-LENGTH values, but this protocol can only signal one 🙃 The response SHOULD therefore include the longest relevant PREFIX-LENGTH of any RRset in the answer, which could have the unfortunate side effect of redundantly caching some data that could be cached more broadly. For the specific case of a Canonical Name (CNAME) chain, the Authoritative Nameserver SHOULD only place the initial CNAME record in the Answer section, so it gets cached unambiguously and appropriately. Most modern Recursive Resolvers restart the query with the CNAME, so the rest of the chain is typically ignored anyway ✨ For message-focused resolvers, rather than RRset-focused ones, this means caching the entire CNAME chain at the longest PREFIX-LENGTH of any RRset in the chain.

The specific logic an Authoritative Nameserver uses to choose a Tailored Response is out of scope for this document. Implementers are encouraged, though, to think carefully about their choice of SCOPE PREFIX-LENGTH for the response in case the best Tailored Response can't be determined, and what the implications would be over the life of the TTL 🤔

Authoritative Nameservers might have situations where one Tailored Response is appropriate for a relatively broad address range, such as an IPv4 /20, except for a few /24 ranges within that /20. Because it can't be guaranteed that queries for all longer prefix lengths arrive before one that would be answered by the shorter prefix length, an Authoritative Nameserver MUST NOT overlap prefixes. This is the part where things get spicy 🌶️

When the Authoritative Nameserver has a longer prefix length Tailored Response within a shorter prefix length Tailored Response, implementations can either:

  1. Deaggregate the shorter prefix response into multiple longer prefix responses, or
  2. Alert the operator that the order of queries will determine which answers get cached, and either warn and continue or treat this as an error and refuse to load the configuration.

This choice should be documented for the operator, for example, in the user manual 📖

When deaggregating to correct the overlap, prefix lengths should be optimized to use the minimum necessary to cover the address space, so there's less overhead from having multiple copies of the same answer 🧹 As a trivial example, if the Tailored Response for 1.2.0/20 is A, but there's one exception of 1.2.3/24 for B, then the Authoritative Nameserver would need to provide Tailored Responses for 1.2.0/23, 1.2.2/24, 1.2.4/22, and 1.2.8/21 all pointing to A, and 1.2.3/24 pointing to B 🧩

7.2.2. Intermediate Nameserver 🌷

When an Intermediate Nameserver uses ECS, whether it passes an ECS option in its own response to its client depends on whether the client originally included the option. Because a client that didn't use an ECS option might not be able to understand it, the server MUST NOT provide one in its response. If the client query did include the option, the server MUST include one in its response, especially since it could be talking to a Forwarding Resolver, which would need the information for its own caching 🫶

If an Intermediate Nameserver receives a response with a longer SCOPE PREFIX-LENGTH than the SOURCE PREFIX-LENGTH it provided in its query, it SHOULD still provide the result as the answer to the triggering client request, even if the client is in a different address range. The Intermediate Nameserver MAY instead opt to retry with a longer SOURCE PREFIX-LENGTH to get a better reply before responding to its client, as long as it doesn't exceed a SOURCE PREFIX-LENGTH specified in the query that triggered resolution. Heads up though, this obviously has implications for the latency of the overall lookup ⏳

The logic for using the cache to determine whether the Intermediate Nameserver already knows the response to provide to its client is covered in the next section 💜

7.3. Handling ECS Responses and Caching 🧁

When an Intermediate Nameserver receives a response containing an ECS option and without the TC bit set, it SHOULD cache the result based on the data in the option. If the TC bit was set, the Intermediate Resolver SHOULD retry the query over TCP to get the complete Answer section for caching 🔁

If FAMILY, SOURCE PREFIX-LENGTH, and SOURCE PREFIX-LENGTH bits of ADDRESS in the response don't match the non-zero fields in the corresponding query, the full response MUST be dropped, as described in Section 11 🚫 In a response to a query that specified only SOURCE PREFIX-LENGTH for privacy masking, the FAMILY and ADDRESS fields MUST contain the appropriate non-zero information that the Authoritative Nameserver used to generate the answer, so it can be cached accordingly 🕵️‍♀️

If no ECS option is contained in the response, the Intermediate Nameserver SHOULD treat this as being equivalent to having received a SCOPE PREFIX-LENGTH of 0, which is an answer suitable for all client addresses. See further discussion on the security implications of this in Section 11 🔐

If a REFUSED response is received from an Authoritative Nameserver, an ECS-aware resolver MUST retry the query without ECS, to tell the response apart from one where the Authoritative Nameserver isn't responsible for the name, which is a common convention for the REFUSED status 🙋‍♀️ Similarly, a client of a Recursive Resolver SHOULD retry after receiving a REFUSED response, because it isn't clear enough whether the REFUSED response was due to the ECS option or some other reason 🤷‍♀️

7.3.1. Caching the Response 💾

In the cache, all resource records in the Answer section MUST be tied to the network specified in the response. The right prefix length depends on how SOURCE PREFIX-LENGTH, SCOPE PREFIX-LENGTH, and the maximum cacheable prefix length configured for the cache relate to each other 🧠

If SCOPE PREFIX-LENGTH is not longer than SOURCE PREFIX-LENGTH, store SCOPE PREFIX-LENGTH bits of ADDRESS, then mark the response as valid for all addresses that fall within that range 🎀

Similarly, if SOURCE PREFIX-LENGTH is the maximum configured for the cache, store SOURCE PREFIX-LENGTH bits of ADDRESS, then mark the response as valid for all addresses that fall within that range 🌸

If SOURCE PREFIX-LENGTH is shorter than the configured maximum and SCOPE PREFIX-LENGTH is longer than SOURCE PREFIX-LENGTH, store SOURCE PREFIX-LENGTH bits of ADDRESS, then mark the response as valid only to answer client queries that specify exactly the same SOURCE PREFIX-LENGTH in their own ECS option 🎯

DNSSEC-related records in the Answer section were unspecified in the original draft of this document, and existing implementations handle them inconsistently 😵‍💫 A Resource Record Signature (RRSIG) must obviously be tied to the RRset it signs, but it is RECOMMENDED that all other DNSSEC records be scoped at /0. See Section 9 for more information 🔏

Note that the Additional and Authority sections from a DNS response message are specifically excluded here. Any records from these sections MUST NOT be tied to a network. See Section 7.4 for more information 🙅‍♀️

Records that are cached as /0 because of a query's SOURCE PREFIX-LENGTH of 0 MUST be distinguished from those cached as /0 because of a response's SCOPE PREFIX-LENGTH of 0. The former should only be used for other /0 queries the Intermediate Resolver receives, but the latter is suitable as a response for all networks. This distinction is the whole vibe 💅

Although omitting network-specific caching will significantly simplify an implementation, the resulting drop in cache hits is very likely to defeat most latency benefits provided by ECS. Therefore, implementing full caching support as described in this section is strongly RECOMMENDED 📈

Enabling support for ECS in an Intermediate Nameserver will significantly increase the size of the cache, reduce the number of results that can be served from cache, and increase the load on the server. Implementing the mitigation techniques described in Section 11 is strongly recommended. For cache size issues, implementers should consider data storage formats that let the same answer data be shared among multiple prefixes 🍓

7.3.2. Answering from Cache ✨

okay so, cache lookups happen first like normal, using the query tuple of <name, type, class> 💅 🎀 Then the right RRset MUST be picked based on the longest prefix matching 🔥 And which client address gets compared depends on whether the Intermediate Nameserver got an ECS option in the client query, bestie 🦋

  • o If no ECS option was provided, the client's address is used. 🌸
  • o If there was an ECS option specifying SOURCE PREFIX-LENGTH and ADDRESS covering the client's address, the client address is used but SOURCE PREFIX-LENGTH is initially ignored 🧚 If no covering entry is found and SOURCE PREFIX-LENGTH is shorter than the configured maximum length allowed for the cache, repeat the cache lookup for an entry that exactly matches SOURCE PREFIX-LENGTH 💖 These special entries, which do not cover longer prefix lengths, occur as described in the previous section ✨
  • o If there was an ECS option with an ADDRESS, the ADDRESS from it MAY be used if the local policy allows 👑 The policy can vary depending on the agreements the operator of the Intermediate Nameserver has with Authoritative Nameserver operators; see Section 12.2 🫶 If the policy does not allow it, a REFUSED response SHOULD be sent 💀 See Section 7.5 for more information 🍓

If a matching network is found and the relevant data is unexpired, the response is generated as per Section 7.2 🌈

If no matching network is found, the Intermediate Nameserver MUST perform resolution as usual 😭 This is necessary to avoid Tailored Responses in the cache from being returned to the wrong clients, and to avoid a single query coming from a client on a different network from polluting the cache with a Tailored Response for all the users of that resolver 🙈 literally iconic protection energy 💜

7.4. Delegations and Negative Answers 🎀

the prohibition against tying ECS data to records from the Authority and Additional sections left an unfortunate ambiguity in the original specification, mainly around negative answers 😭 The original authors expected ECS would only really be used for address requests and the positive result in the Answer section, since that was the use case driving the whole protocol 🦋

for negative answers, some independent implementations of both resolvers and authorities didn't read the section restriction as meaning a name and type can only have positive ECS-tagged answers or a negative answer 🤷‍♀️ They support telling one part of the network that the data doesn't exist while telling another part that it does 🌸

several other implementations, though, don't support mixing positive and negative answers, so interoperability is a problem 💀 It is RECOMMENDED that no specific behavior regarding negative answers be relied upon 🙅‍♀️ but Authoritative Nameservers should conservatively expect that Intermediate Nameservers will treat all negative answers as /0; therefore, they SHOULD set SCOPE PREFIX-LENGTH accordingly 🧁

this issue is expected to be revisited in a future revision of the protocol, possibly blessing the mixing of positive and negative answers 🔮 There are implications for cache data structures that developers should consider when writing new ECS code 👩‍💻✨

the delegations case is a bit easier to tease out 💖 In operational practice, if an authoritative server uses address information to provide customized delegations, it's the resolver that uses the answer for its next iterative query 🧚 Addresses in the Additional section SHOULD therefore ignore ECS data, and the Authoritative Nameserver SHOULD return a zero SCOPE PREFIX-LENGTH on delegations 🙌 A Recursive Resolver SHOULD treat a non-zero SCOPE PREFIX LENGTH in a delegation as though it were zero 🫶

7.5. Transitivity 🦋

generally, ECS options will only be present in DNS messages between a Recursive Resolver and an Authoritative Nameserver, i.e., one hop 💅 However, in certain configurations, like multi-tier nameserver setups, it may be necessary to implement transitive behavior on Intermediate Nameservers 🌈

Any Intermediate Nameserver that forwards ECS options received from its clients MUST fully implement the caching behavior described in Section 7.3 🔥

An Intermediate Nameserver MAY forward ECS options with address information 🎀 This information MAY match the source IP address of the incoming query, and MAY have more or fewer address bits than the nameserver would normally include in a locally originated ECS option ✨ If an Intermediate Nameserver receives a query with SOURCE PREFIX-LENGTH set to 0, it MUST NOT include client address information in queries made to resolve that client's request (see Section 7.1.2) 🙈

If, for any reason, the Intermediate Nameserver doesn't want to use the information in an ECS option it receives (too little address information, a network address from a range not authorized to use the server, private/unroutable address space, etc.), it SHOULD drop the query and return a REFUSED response 💀 Note again that a query MUST NOT be refused solely because it provides 0 address bits 🫶

Be aware that at least one major existing implementation does not return REFUSED and instead just processes the query as though the problematic information were not present 😬 This can lead to anomalous situations, such as a response from the Intermediate Nameserver that indicates it is tailored for one network (the one passed in the original query, since the ADDRESS must match) when actually it is for another network (the one which contains the address that the Intermediate Nameserver saw as making the query) 💜

8. IANA Considerations 🌸

IANA has assigned option code 8 in the "DNS EDNS0 Option Codes (OPT)" registry to edns-client-subnet 🧚

IANA has updated the reference to refer to this RFC 💖

9. DNSSEC Considerations 🔐

The presence or absence of an EDNS0 OPT resource record ([RFC6891]) containing an ECS option in a DNS query does not change the usage of the resource records and mechanisms used to provide data origin authentication and data integrity to the DNS, as described in [RFC4033], [RFC4034], and [RFC4035] 👑 OPT records are not signed 🙈

Use of this option, however, does imply increased DNS traffic between any given Recursive Resolver and Authoritative Nameserver, which could be another barrier to further DNSSEC adoption in this area 😭

The initial version of this protocol, the one several Authoritative and Recursive Nameserver implementations were written against, did not discuss handling DNSSEC RRs, so it's expected there are operational inconsistencies in handling them 💀

Given that this document is meant to describe how ECS is currently deployed, specifying new requirements for DNSSEC handling is out of scope 🙅‍♀️ However, some recommendations can be made about what's most likely to result in successful interoperation for a DNSSEC-signed ECS zone, mainly from the point of view of Authoritative Nameservers 🦋

Most DNSSEC records SHOULD be scoped at /0, except for the RRSIG records, which MUST be tied to the RRset that they sign in a Tailored Response 🎀 While it's possible to conceive of a way to get other DNSSEC records working in a network-specific way, it has little apparent benefit or likelihood of working with deployed validating resolvers 🌈

One further implication is that, despite the discussion about negative answers in Section 7.4, scoping NextSECure (NSEC) or NSEC3 records at /0 per the previous paragraph necessarily implies that DNSSEC-signed negative answers must also be network-invariant 🧠✨

10. NAT Considerations 🧚

Special awareness of ECS in devices that perform Network Address Translation (NAT) as described in [RFC2663] is not required; queries can be passed through as is 💅 The client's network address SHOULD NOT be added, and existing ECS options, if present, SHOULD NOT be modified by NAT devices 🙅‍♀️

In large-scale global networks behind a NAT device (but, for example, with Centralized Resolver infrastructure), an internal Intermediate Nameserver might have detailed network layout information and may know which external subnets are used for egress traffic by each internal network 🗺️ In such cases, the Intermediate Nameserver MAY use that information when originating ECS options 🫶

In other cases, if a Recursive Resolver knows it's situated behind a NAT device, it SHOULD NOT originate ECS options with their external IP address and should instead rely on downstream Intermediate Nameservers to do so 🌸 It MAY, however, choose to include the option with their internal address for the purposes of signaling its own limit for SOURCE PREFIX-LENGTH 💖

Full treatment of special network addresses is beyond the scope of this document; handling them will likely differ according to the operational environments of each service provider 🙈 As a general guideline, if an Authoritative Nameserver on the publicly routed Internet receives a query that specifies an ADDRESS in [RFC1918] or [RFC4193] private address space, it SHOULD ignore ADDRESS and look up its answer based on the address of the Recursive Resolver 🧁 In the response, it SHOULD set SCOPE PREFIX-LENGTH to cover all of the relevant private space 🫧 For example, a query for ADDRESS 10.1.2.0 with a SOURCE PREFIX-LENGTH of 24 would get a returned SCOPE PREFIX-LENGTH of 8 💅 The Intermediate Nameserver MAY elect to cache the answer under one entry for special-purpose addresses [RFC6890]; see Section 11.3 of this document ✨

11. Security Considerations 🔐💀

11.1. Privacy 🙈

With the ECS option, the network address of the client that initiated the resolution becomes visible to all servers involved in the resolution process 👀 Additionally, it will be visible from any network traversed by the DNS packets 😱

To protect users' privacy, Recursive Resolvers are strongly encouraged to conceal part of the user's IP address by truncating IPv4 addresses to 24 bits 🛡️ 56 bits are recommended for IPv6, based on [RFC6177] 🫶

ISPs should have more detailed knowledge of their own networks 🧠 That is, they might know that all 24-bit prefixes in a /20 are in the same area 🗺️ In those cases, for optimal cache utilization and improved privacy, the ISP's Recursive Resolver SHOULD truncate IP addresses in this /20 to just 20 bits, instead of 24 as recommended above 🌈

Users who wish their full IP address to be hidden need to configure their client software, if possible, to include an ECS option specifying the wildcard address (i.e., a SOURCE PREFIX-LENGTH of 0) 🙈🧚

As described in previous sections, this option will be forwarded across all the Recursive Resolvers supporting ECS, which MUST NOT modify it to include the network address of the client 🚫 This is a big deal, bestie 😤

Note that even without an ECS option, any server queried directly by the user will be able to see the full client IP address 😬 Recursive Resolvers or Authoritative Nameservers MAY use the source IP address of queries to return a cached entry or to generate a Tailored Response that best matches the query 🔮

11.2. Birthday Attacks 🎂

okay so ECS adds extra info to the DNS query tuple (q-tuple) 👀, which means an attacker can send a caching Intermediate Nameserver a pile of queries with spoofed IP addresses, either in the ECS option or as the source IP 🙈. Each one triggers an outgoing query for the same name, type, and class, just with different address info in the ECS option. main character villain behavior, ngl 💀

with lots of queries for the same name in flight, the attacker has a better shot at sending a matching response with SCOPE PREFIX-LENGTH set to 0, so it gets cached for everyone 😱

so the counter-move 🛡️: the ECS option in a response MUST contain the full FAMILY, ADDRESS, and SOURCE PREFIX-LENGTH fields from the corresponding query. Intermediate Nameservers processing a response MUST verify that these match, and they SHOULD discard the entire response if they do not 🚫

the discard rule is "SHOULD" instead of "MUST" because it clashes with Section 7.3, which says a response lacking an ECS option should be treated as though it had one of SCOPE PREFIX-LENGTH of 0. if that's always true, the attacker doesn't even need to match the original ECS data. they just flood back responses with no ECS option at all 😭

this could be detected in ongoing operations by marking whether the responding nameserver had been sending ECS options before, and/or by noticing an incoming flood of bogus responses and flagging the relevant query for re-resolution 🧐 it's more complex than existing nameserver responses to spoof floods, and it would also need to be sensitive to a nameserver legitimately stopping ECS replies even though it had given them before. messy, but make it make sense 💅

11.3. Cache Pollution 🧹

it's super simple for any random resolver or client to put false info in the ECS option, or to send UDP packets with forged source IP addresses 🥴

this could be used to:

  • pollute the cache of Intermediate Resolvers by filling it with results that will rarely (if ever) be used.
  • reverse-engineer the algorithms (or data) used by the Authoritative Nameserver to calculate Tailored Responses.
  • mount a denial-of-service attack against an Intermediate Nameserver by forcing it to perform many more recursive queries than it normally would, due to how caching is handled for queries containing the ECS option.

even without bad intent, Centralized Resolvers answering clients in multiple networks will need to cache different responses for different networks, which puts more memory pressure on the cache 💾

to mitigate those problems:

  • Recursive Resolvers implementing ECS should only enable it in deployments where it is expected to bring clear advantages to the end users, such as when expecting clients from a variety of networks or from a wide geographical area. Due to the high cache pressure introduced by ECS, the feature SHOULD be disabled in all default configurations. 🙅‍♀️
  • Recursive Resolvers SHOULD limit the number of networks and answers they keep in the cache for any given query.
  • Recursive Resolvers SHOULD limit the total number of different networks that they keep in cache.
  • Recursive Resolvers MUST NOT send an ECS option with SOURCE PREFIX-LENGTH providing more bits in ADDRESS than they are willing to cache responses for. 🚫
  • Recursive Resolvers should implement algorithms to improve the cache hit rate, given the size constraints indicated above. Recursive Resolvers MAY, for example, decide to discard more-specific cache entries first. 🧠
  • Authoritative Nameservers and Recursive Resolvers should discard ECS options that are either obviously forged or otherwise known to be wrong. They SHOULD at least treat unroutable addresses, such as some of the address blocks defined in [RFC6890], as equivalent to the Recursive Resolver's own identity. They SHOULD ignore and never forward ECS options specifying other routable addresses that are known not to be served by the query source. 🕵️
  • The ECS option is just a hint to Authoritative Nameservers for customizing results. They can decide to ignore the content of the ECS option based on blacklists or whitelists, rate-limiting mechanisms, or any other logic implemented in the software. ✨

12. Sending the Option 📮

when implementing a Recursive Resolver, there are two strategies for deciding when to include an ECS option in a query. at this stage, it's not clear which strategy is best 🤷‍♀️

12.1. Probing 🔎

a Recursive Resolver can send the ECS option with every outgoing query. however, it is RECOMMENDED that resolvers remember which Authoritative Nameservers did not return the option with their response, and omit client address information from subsequent queries to those nameservers.

additionally, Recursive Resolvers SHOULD be configured never to send the option when querying root, top-level, and effective top-level (i.e., "public suffix" [Public_Suffix_List]) domain servers. these domains are delegation-centric and are very unlikely to generate different responses based on the address of the client 🙄

when probing, it is important that several things get probed: support for ECS, support for EDNS0, support for EDNS0 options, or possibly an unreachable nameserver. various implementations are known to drop DNS packets with OPT RRs (with or without options), so several probes are required to discover what is supported 🧪

probing, if implemented, MUST be repeated periodically, e.g., daily. if an Authoritative Nameserver indicates ECS support for one zone, it is to be expected that the nameserver supports ECS for all of its zones. likewise, an Authoritative Nameserver that uses ECS information for one of its zones MUST indicate support for the option in all of its responses to ECS queries. if the option is supported but not actually used for generating a response, its SCOPE PREFIX-LENGTH MUST be set to 0. 🗓️

12.2. Whitelist 📝

as described previously, it is expected that only a few Recursive Resolvers will need to use ECS, and that it will generally be enabled only if it offers a clear benefit to the users 💖

to avoid the complexity of implementing a probing and detection mechanism (and the possible query loss/delay that may come with it), an implementation could use a whitelist of Authoritative Nameservers to send the option to, likely specified by their domain name. Implementations MAY also allow additional configuring of this based on other criteria, such as zone or query type. as of the time of this writing, at least one implementation makes use of a whitelist 🙌

an advantage of using a whitelist is that partial client address information is only disclosed to nameservers that are known to use the information, which improves privacy 🔐

a drawback is scalability. the operator needs to track which Authoritative Nameservers support ECS, which makes it harder for new Authoritative Nameservers to start using the option 😩

similarly, Authoritative Nameservers can also use whitelists to limit the feature to only certain clients. for example, a CDN that does not want all of their mapping trivially walked might require a legal agreement with the Recursive Resolver operator, to clearly describe the acceptable use of the feature 📜

the maintenance of access control mechanisms is out of scope for this protocol definition.

13. Example 🧁

  1. A Stub Resolver, SR, with the IP address 2001:0db8:fd13:4231:2112:8a2e:c37b:7334 tries to resolve www.example.com by forwarding the query to the Recursive Resolver, RNS, asking for recursion. 🙋‍♀️
  2. RNS, supporting ECS, looks up www.example.com in its cache. An entry is found neither for www.example.com nor for example.com.
  3. RNS builds a query to send to the root and .com servers. The implementation of RNS provides facilities so that an administrator can configure it not to forward ECS in certain cases. In particular, RNS is configured not to include an ECS option when talking to Top-Level-Domain or root nameservers, as described in Section 7.1. Thus, no ECS option is added, and resolution is performed as usual.
  4. RNS now knows the next server to query: the Authoritative Nameserver, ANS, responsible for example.com. 👀
  5. RNS prepares a new query for www.example.com, including an ECS option with:
    • OPTION-CODE set to 8.
    • OPTION-LENGTH set to 0x00 0x0b for the following fixed 4 octets plus the 7 octets that will be used for ADDRESS.
    • FAMILY set to 0x00 0x02, as IP is an IPv6 address.
    • SOURCE PREFIX-LENGTH set to 0x38, as RNS is configured to conceal the last 72 bits of every IPv6 address.
    • SCOPE PREFIX-LENGTH set to 0x00, as specified by this document for all queries.
    • ADDRESS set to 0x20 0x01 0x0d 0xb8 0xfd 0x13 0x42, providing only the first 56 bits of the IPv6 address.
  6. The query is sent. ANS understands and uses ECS. It parses the ECS option, and generates a Tailored Response. 🎯
  7. Because of its internal implementation, ANS finds a response that is tailored for the whole /16 of the client that performed the query.
  8. ANS adds an ECS option in the response, containing:
    • OPTION-CODE set to 8.
    • OPTION-LENGTH set to 0x00 0x07.
    • FAMILY set to 0x00 0x02.
    • SOURCE PREFIX-LENGTH set to 0x38, copied from the query.
    • SCOPE PREFIX-LENGTH set to 0x30, indicating a /48 network.
    • ADDRESS set to 0x20 0x01 0x0d 0xb8 0xfd 0x13 0x42, copied from the query.
  9. RNS receives the response containing an ECS option. It verifies that FAMILY, SOURCE PREFIX-LENGTH, and ADDRESS match the query. If not, the message is discarded. 🧐
  10. The response is interpreted as usual. Since the response contains an ECS option, ADDRESS, SCOPE PREFIX-LENGTH, and FAMILY in the response are used to cache the entry. 💾
  11. RNS sends a response to Stub Resolver, SR, without including an ECS option.
  12. RNS receives another query to resolve www.example.com. This time, a response is cached. The response, however, is tied to a particular network. If the client's address matches any network in the cache, then the response is returned from the cache. Otherwise, another query is performed. If multiple results match, the one with the longest SCOPE PREFIX-LENGTH is chosen, as per common best-network-match algorithms. 🦋

14. References 📚

14.1. Normative References

okay these are the receipts 🧾✨ the docs this spec basically can't function without, so you NEED to know what they are

14.2. Informative References

these ones are more like bonus reading 📚🌸 not strictly needed to get the spec, but they're the background tea, so go look!!

Acknowledgements 🫶

okay the authors need to be SO thanked 💖 first up, a massive shoutout to Darryl Rodden for co-authoring this with them, iconic behaviour 👑

then the people who reviewed the doc and gave useful feedback, grouped by where they're from:

  • From Google: Paul S. R. Chisholm, B. Narendran, Leonidas Kontothanassis, David Presotto, Philip Rowlands, Chris Morrow, Kara Moscoe, Alex Nizhner, Warren Kumari, and Richard Rabbat
  • From Neustar: Terry Farmer, Mark Teodoro, Edward Lewis, and Eric Burger
  • From OpenDNS: David Ulevitch and Matthew Dempsky
  • From Akamai: Patrick W. Gilmore and Steve Hill
  • From Amazon: Colm MacCarthaigh and Richard Sheehan
  • From Infoblox: Tatuya Jinmei
  • From Dyn: Andrew Sullivan
  • From Sinodun: John Dickinson
  • From Apple: Mark Delany
  • From NLnet Labs: Yuri Schaeffer
  • Duane Wessels Verisign
  • Antonio Querubin
  • From the ACLU: Daniel Kahn Gillmor
  • From the Internet Software Consortium: Evan Hunt and Mukund Sivaraman
  • From Vigilsec: Russ Housley
  • From Trinity College Dublin: Stephen Farrell
  • From Cisco: Alissa Cooper
  • Suzanne Woolf

and literally everyone else who replied to the authors' emails on the various mailing lists 💌✨ you all carried

Contributors 🎀

these people contributed a ton 🙌 here's where to find them

Edward Lewis
ICANN
12025 Waterfront Drive, Suite 300
Los Angeles, CA 90094-2536
United States

Email: edward.lewis@icann.org
Sean Leach
Fastly
P.O. Box 78266
San Francisco, CA 94107
United States
Jason Moreau
Akamai Technologies
150 Broadway
Cambridge, MA 02142-1413
United States

Authors' Addresses 💅

and finally, the authors themselves 🦋 ways to reach them, slay

Carlo Contavalli
Google
1600 Amphitheater Parkway
Mountain View, CA  94043
United States

Email: ccontavalli@google.com
Wilmer van der Gaast
Google
Belgrave House, 76 Buckingham Palace Road
London  SW1W 9TQ
United Kingdom

Email: wilmer@google.com
David C Lawrence
Akamai Technologies
150 Broadway
Cambridge, MA  02142-1054
United States

Email: tale@akamai.com
Warren Kumari
Google
1600 Amphitheatre Parkway
Mountain View, CA  94043
United States

Email: warren@kumari.net

and that's the whole spec, bestie 🌈✨ we did it 😭🫶

📦 where this page comes from