| Internet-Draft | DNS Filtering Details for Applications | February 2025 |
| Nottingham | Expires 26 August 2025 | [Page] |
[I-D.ietf-dnsop-structured-dns-error] introduces structured error data for DNS responses that have been filtered. This draft suggests additions to that mechanism that enable applications to convey the details of some filtering incidents to their users.¶
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/mnot/public-resolver-errors.¶
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 26 August 2025.¶
Copyright (c) 2025 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
Internet DNS resolvers are increasingly subject to legal orders that require blocking or filtering of specific names. Because such filtering happens during DNS resolution, there is not an effective way to communicate what is happening to end users, often resulting in misattribution of the issue as a technical problem, rather than a policy intervention.¶
This draft defines a mechanism to communicate such details when DNS resolver filtering of a name is legally mandated, based upon the structured error data for DNS responses introduced by [I-D.ietf-dnsop-structured-dns-error].¶
Allowing DNS resolvers to inject user-visible messages brings unique challenges. Because DNS resolvers are often automatically configured by unknown networks and DNS responses are unauthenticated, these messages can come from untrusted parties -- including attackers (e.g., the so-called "coffee shop" attack) that leverage many users' lack of a nuanced model of the trust relationships between all of the parties that are involved in the service they are using.¶
Furthermore, lowering the barrier to the presentation of messages explaining why access has been denied by the DNS resolver risks encouraging the wider deployment of DNS-based censorship on the Internet.¶
This draft attempts to mitigate these risks by minimising the information carried in the DNS response to abstract, publicly registered identifiers -- the DNS Resolver Operator ID and the Filtering Incident ID. A consuming party (e.g., a Web browser) can selectively present messages from those operators that they believe to be using this mechanism for its stated goal -- in particular, those who using it to surface policy-driven filtering, rather than enact discretionary censorship or attack end users.¶
In typical use, a DNS query that is filtered might contain an Extended DNS Error Code 17 (see [RFC8914]) and an EXTRA-TEXT field containing:¶
{
"ro": "exampleResolver",
"inc": "abc123"
}
¶
This indicates that the "exampleResolver" resolver has generated the error, and the incident identifier is "abc123".¶
An application that decides to present errors from "exampleResolver" to its users would look up "exampleResolver" in a local copy of the IANA DNS Resolver Identifier Registry (see Section 4.2) and obtain the corresponding template (see Section 3). For purposes of this example, assume that the registry entry for that value contains:¶
https://resolver.example.com/filtering-incidents/{inc}
¶
That template can be expanded using the value of "inc" to:¶
https://resolver.example.com/filtering-incidents/abc123¶
The application could (but might not) then decide to convey some or all of this information to its user; for example, with a statement that conveys:¶
The webpage at www.example.net was blocked due to a legal request. Your DNS resolver may have more information about the legal request here:¶
https://resolver.example.com/filtering-incidents/abc123¶
Note that there is no requirement for the template to expand to a URL on any particular hostname; for example, it could be hosted by a party other than the resolver's server.¶
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.¶
This section defines the data types used to look up the details of a filtering incident from a DNS error response. Note that these identifiers are not for presentation to end users.¶
A DNS Resolver Operator ID is a short, textual string that uniquely identifies the operator of a DNS resolver. It is carried in the EXTRA-TEXT field of the Extended DNS Error with the JSON field name "ro". For example:¶
{
"ro": "exampleResolver"
}
¶
Generators MUST only use values that are registered in the DNS Resolver Operator registry; see Section 4.2. Consumers MUST ignore unregistered values, and MAY ignore registered values.¶
A Filtering Incident ID is an opaque, string identifier for a particular filtering incident. It might be specific to a particular request, but need not be. It is carried in the EXTRA-TEXT field of the Extended DNS Error with the JSON field name "inc". For example:¶
{
"inc": "abc123"
}
¶
An Incident Resolution Template is a URI Template [RFC6570] contained in the DNS Resolver Identifier Registry (Section 4.2) that, upon expansion, provides a URI that can be dereferenced to obtain details about the filtering incident.¶
It MUST be a Level 1 or Level 2 template (see Section 1.2 of [RFC6570]). It has the following variables available to it:¶
the DNS Resolver Operator ID (see Section 2.1)¶
the Filtering Incident ID (see Section 2.2)¶
For example:¶
https://resolver.example.com/filtering-incidents/{inc}
¶
Applications MUST store a local copy of the DNS Resolver Identifier Registry for purposes of template lookup; they MUST NOT query the IANA registry upon each use.¶
IANA will register the following fields in the "EXTRA-TEXT JSON Names" sub-registry established by [I-D.ietf-dnsop-structured-dns-error]:¶
IANA will establish a new registry, the "DNS Resolver Identifier Registry." Its registration policy is first-come, first-served (FCFS), although IANA may refuse registrations that it deems to be deceptive or spurious.¶
It contains the following fields:¶
The name of the DNS resolver operator¶
an e-mail address or other appropriate contact mechanism¶
see Section 2.1¶
The Incident Resolution Template can be updated by the contact at any time. However, operators SHOULD accommodate potentially long lag times for applications to update their copies of the registry.¶
This specification does not provide a way to authenticate that a particular filtering incident as experienced by an application was actually associated with the information presented. This means that an attacker (for example, one controlling a DNS resolver) can claim that a particular filtering incident is occurring when in fact it is not. However, a successful attack would need to reuse an existing DNS Resolver Operator ID and Filtering Incident ID that combine to expand to a URL that can be successfully dereferenced. Doing so is not currently thought to be particularly advantageous to an attacker to do so. Future iterations of this specification may introduce more robust protections.¶
The details of DNS responses are not available to all applications, depending on how they are architected and the information made available to them by their host. As a result, this mechanism is not reliable; some applications will not be able to display this error information.¶
Because the registry is first-come, first-served, Applications (such as Web browsers) will need to exercise judgement regarding which operators' error messages they display to users. This decision might be influenced by the identity of the resolver (e.g., so-called "public resolvers" are likely to use this mechanism responsibly), its history (e.g., a well-known Internet Service Provider that has been subject to legal filtering orders), or local configuration (e.g., application or operating system settings that indicate that a particular resolver is to be trusted).¶
Thanks to David Adrian, Tommy Pauly, Emily Stark, and Martin Thomson for their input to this specification.¶