DNS Filtering Details for Applications

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 6 February 2026.¶

Copyright Notice

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.¶

Table of Contents

1. Introduction

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.¶

Some organizations, such as Lumen [lumen], monitor legally-mandated filtering as a public service, tracking specific filtering incidents in publicly accessible databases. Public resolvers themselves may also choose to track filtering requests over time and make them available.¶

This draft defines a mechanism for DNS resolvers to convey identifiers for entries in such databases, based upon the structured error data for DNS responses introduced by [I-D.ietf-dnsop-structured-dns-error].¶

A consuming party (e.g., a Web browser) can use this information to construct a link to the specific entry in the provider's database of filtering incidents. This enables user agents to direct users to additional context about the filtering incident they encountered.¶

The information conveyed is a DNS Filtering Database Entry, specified in Section 2.1. This abstraction is necessary because allowing DNS resolvers to inject links or user-visible messages would bring unique challenges. DNS resolvers are often automatically configured by unknown networks and DNS responses are unauthenticated, so 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.¶

This draft attempts to mitigate these risks by minimising the information carried in the DNS response to abstract, publicly registered identifiers associated with databases of filtering incidents -- the DNS Filtering Database Entry -- rather than arbitrary URLs. A consuming party can choose which database identifiers they support are are willing to direct their users to, without enabling every DNS server to surface arbitrary links and text, and without requiring every consuming party to independently track which URLs are in use.¶

{
  "fdbs": [
    {"db": "example",
    "id": "abc123"},
    {"db": "lumen",
    "id": "def456"}
  ]
}

https://resolver.example.com/filtering-incidents/{id}

https://resolver.example.com/filtering-incidents/abc123

2. Data Types

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.¶

{
  "db": "example",
  "id": "abc123"
}

{
  "fdbs": [ { ... }, { ... }, ... ]
}

3. Database Entry Resolution Templates

An Incident Resolution Template is a URI Template [RFC6570] contained in the DNS Filtering Database 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 from the Filtering Database Entry (see Section 2.1) available to it:¶

db:

the Filtering Database Operator ID¶

id:

the Filtering Incident ID¶

For example:¶

https://resolver.example.com/filtering-incidents/{inc}

Applications MUST store a local copy of the DNS Filtering Database Registry (Section 4.2) for purposes of template lookup; they MUST NOT query the IANA registry upon each use. The registry is keyed by the Filtering Database Operator ID.¶

4. IANA Considerations

5. Security Considerations

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 Filtering Database 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 database operators' error messages they display to users. This decision might be influenced by the identity of the resolver producing the error message, the database operator, or local configuration.¶

6. References

Appendix A. Acknowledgements

Thanks to Lars Eggert, Tommy Pauly, Emily Stark, and Martin Thomson for their input to this specification.¶

Authors' Addresses