Internet-Draft Data for Filtered DNS October 2021
Wing, et al. Expires 16 April 2022 [Page]
Intended Status:
Standards Track
D. Wing
T. Reddy
N. Cook
M. Boucadair

Structured Data for Filtered DNS


DNS filtering is widely deployed for network security, but filtered DNS responses lack information for the end user to understand the reason for the filtering. Existing mechanisms to provide detail to end users cause harm especially if the blocked DNS response is to an HTTPS website.

This document defines a mechanism to explain the reason for the DNS filtering and provides HTTPS URIs to get more detail. This information can be parsed by the client and displayed, logged, or used for other purposes.

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

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 16 April 2022.

1. Introduction

DNS filters are deployed for a variety of reasons including endpoint security, parental filtering, and filtering required by law enforcement. Network-based security solutions such as firewalls and Intrusion Prevention Systems (IPS) rely upon network traffic inspection to implement perimeter-based security policies and operate by filtering DNS responses. In a home, DNS filtering is used for the same reasons as above and additionally for parental control. Internet Service Providers typically block access to some DNS domains due to a requirement imposed by an external entity (e.g., law enforcement agency) also performed using DNS-based content filtering.

Users of DNS services which perform filtering may wish to receive more information about such filtering to resolve problems with the filter -- for example to contact the administrator to whitelist a domain that was erroneously filtered or to understand the reason a particular domain was filtered. With that information, the user can choose another network, open a trouble ticket with the DNS administrator to resolve erroneous filtering, log the information, or other uses.

DNS responses can be filtered by sending a bogus (also called, "forged") A or AAAA response, NXDOMAIN error or empty answer, or an extended DNS error (EDE) code defined in [RFC8914]. Each of these methods have advantages and disadvantages that are discussed below:

  1. The DNS response is forged to provide a list of IP addresses that points to an HTTP(S) server alerting the end user about the reason for blocking access to the requested domain (e.g., malware). When an HTTP(S) enabled domain name is blocked, the network security device (e.g., CPE, firewall) presents a block page instead of the HTTP response from the content provider hosting that domain. If an HTTP enabled domain name is blocked, the network security device intercepts the HTTP request and returns a block page over HTTP. If an HTTPS enabled domain is blocked, the block page is also served over HTTPS. In order to return a block page over HTTPS, man in the middle (MITM) is enabled on endpoints by generating a local root certificate and an accompanying (local) public/private key pair. The local root certificate is installed on the endpoint while the network security device(s) stores a copy of the private key. During the TLS handshake, the network security device modifies the certificate provided by the server and (re)signs it using the private key from the local root certificate.

    • However, configuring the local root certificate on endpoints is not a viable option in several deployments like home networks, schools, Small Office/Home Office (SOHO), and Small/ Medium Enterprise (SME). In these cases, the typical behavior is that the forged DNS response directs the user towards a server hosted to display the block page which breaks the TLS connection. For web-browsing this then results in an HTTPS certificate error message indicating that a secure connection could not be established, which gives no information to the end-user about the reason for the error. The typical errors are "The security certificate presented by this website was not issued by a trusted certificate authority" (Internet Explorer/Edge"), "The site's security certificate is not trusted" (Chrome), "This Connection is Untrusted" (Firefox), "Safari can't verify the identity of the website..." (Safari on MacOS)".

    • Enterprise networks do not assume that all the connected devices are managed by the IT team or Mobile Device Management (MDM) devices, especially in the quite common Bring Your Own Device (BYOD) scenario. In addition, the local root certificate cannot be installed on IoT devices without a device management tool.
    • An end user does not know why the connection was reset and, consequently, may repeatedly try to reach the domain but with no success. Frustrated, the end user may switch to an alternate network that offers no DNS-level protection against malware and phishing, potentially compromising both security and privacy. Furthermore, certificate errors train users to click through certificate errors, which is a bad security practice. To eliminate the need for an end user to click through certificate errors, an end user may manually install a local root certificate on a host device. Doing so, however, is also a bad security practice as it creates a security vulnerability that may be exploited by a MITM attack. When a manually installed local root certificate expires, the user has to (again) manually install the new local root certificate.
  2. The DNS response is forged to provide a NXDOMAIN response to cause the DNS lookup to terminate in failure. In this case, an end user does not know why the domain cannot be reached and may repeatedly try to reach the domain but with no success. Frustrated, the end user may use insecure connections to reach the domain, potentially compromising both security and privacy.
  3. The extended error codes Blocked, Censored, and Filtered defined in Section 4 of [RFC8914] can be returned by a DNS server to provide additional information about the cause of an DNS error. If the extended error code "Forged Answer" defined in Section 4.5 of [RFC8914] is returned by the DNS server, the client can identify the DNS response is forged together with the reason for HTTPS certificate error.
  4. These extended error codes do not suffer from the limitations discussed in bullets (1) and (2), but the user still does not know the exact reason nor he/she is aware of the exact entity blocking the access to the domain. For example, a DNS server may block access to a domain based on the content category such as "Adult Content" to enforce parental control, "Violence & Terrorism" due to an external requirement imposed by an external entity (e.g., Law Enforcement Agency), etc. These content categories cannot be standardized because the classification of domains into content categories is vendor specific, typically ranges from 40 to 100 types of categories depending on the vendor and the categories keep evolving. Furthermore, the threat data used to categorize domains may sometimes misclassify domains (e.g., domains wrongly classified as Domain Generation Algorithm (DGA) by deep learning techniques, domain wrongly classified as phishing due to crowd sourcing, new domains not categorized by the threat data). A user needs to know the contact details of the IT/InfoSec team to raise a complaint.
  5. When a resolver or forwarder forwards the received EDE option, the EXTRA-TEXT field only conveys the source of the error (Section 3 of [RFC8914]) and does not provide additional textual information about the cause of the error.

For both DNS filtering mechanisms described above, the DNS server can return extended error codes Blocked, Censored, Filtered, or Forged Answer defined in Section 4 of [RFC8914]. However, these codes only explain that filtering occurred but lack detail for the user to diagnose erroneous filtering.

No matter which type of response is generated (forged IP address(es), NXDOMAIN or empty answer, even with an extended error code), the user who triggered the DNS query has little chance to understand which entity filtered the query, how to report a mistake in the filter, or why the entity filtered it at all. This document describes a mechanism to provide such detail.

One of the other benefits of this approach is to eliminate the need to "spoof" block pages for HTTPS resources. This is achieved since clients implementing this approach would be able to display a meaningful error message, and would not need to connect to such a block page. This approach thus avoids the need to install a local root certificate authority on those IT-managed devices.

This document describes a protocol containing parsable data in a new EDNS(0) [RFC6891] option code.

Clients indicate their support of this specification in their DNS query so the DNS server can tailor its DNS response accordingly. The information returned in a DNS response allows combinations of headless devices (i.e., those lacking a display or other means to communicate with a human), operating systems, and web browsers to be informed of the filtering. This information returned can be logged and/or displayed to the user, as appropriate for the user interface capabilities of the client hardware and software.

This document does not recomment DNS filtering, but provides a mechanism for better transparency to explain to the users why some DNS queries are filtered.

2. Terminology

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 document uses terms defined in DNS Terminology [RFC8499].

"Requestor" refers to the side that sends a request. "Responder" refers to an authoritative, recursive resolver or other DNS component that responds to questions. Other terminology is used here as defined in the RFCs cited by this document.

"Encrypted DNS" refers to any encrypted scheme to convey DNS messages, for example, DNS-over-HTTPS [RFC8484], DNS-over-TLS [RFC7858], or DNS-over-QUIC [I-D.ietf-dprive-dnsoquic].

3. Structured Error EDNS(0) Option Code

This document defines a new EDNS(0) [RFC6891] option code (OPT) to include JSON providing information in the DNS response describing filtering that occurred for this query, defined in Figure 1.

The value of this EDNS(0) option code (OPT) is TBA-BY-IANA.

                                             1   1   1   1   1   1
     0   1   2   3   4   5   6   7   8   9   0   1   2   3   4   5
   |           STRUCTURED-ERROR-LENGTH (fixed, two octets)         |
   /              STRUCTURED-ERROR-JSON (variable size)            /
Figure 1: Structured Error EDNS(0) Option Code

The description of the fields is as follows:

Two octets containing the length of STRUCTURED-ERROR-JSON, in octets. It MUST NOT be set to 0.
JSON containing DNS filtering information encoded in JSON, defined in Section 4.

4. Structured JSON

STRUCTURED-ERROR-JSON contains the following JSON names:

c: (complaint)
a partial URI for the user to further diagnose and possibly report mis-classified DNS filtering. The value is converted to an expanded absolute URI. This field is optional, but note its absence still allows a URI to be formed.
d: (domain)
Contains the domain-name of the encrypted DNS server. This is used to create the expanded URIs for both the "c" and "r" fields, and also detect undesired forwarding of EDNS(0) options. This field is mandatory.
j: (justification)
the textual justification for this particular DNS filtering. This field is mandatory.
o: (organization)
human-friendly name of the organization that filtered this particular DNS query. This field is optional.
r: (regulation)
a partial URI to retrieve the public or private rule, law, or regulation describing the reason for this DNS filter. This might point at an employment agreement (for an enterprise performing filtering) or a national government regulation (for an ISP performing filtering). This field is optional, but note its absence still allows a URI to be formed.

To reduce packet overhead the generated JSON SHOULD be as short as possible: short domain names, concise text in the values for the "j" and "o" names, and minified JSON (that is, without spaces or line breaks between JSON elements).

The JSON data can be parsed to display to the user, logged, or otherwise used to assist the end-user or IT staff with troubleshooting and diagnosing the cause of the DNS filtering.

5. Protocol Operation

5.1. Client Generating Request

When generating a DNS query, the client MUST include the Structured Error EDNS(0) option when encrypted DNS is used so the DNS server knows that the client is compliant with this specification.

5.2. Server Generating Response

When the DNS server filters its DNS response to an A or AAAA record query, the DNS response MAY contain an empty answer, NXDOMAIN, or a forged A or AAAA response, as desired by the DNS server. In addition, if the query contained the Structured Error EDNS(0) option, the DNS server MAY return more detail in the STRUCTURED-ERROR-JSON, as described below.

Over time a domain name might be filtered, then not filtered, then filtered again. Additionally, the user might take minutes or even days before investigating a filtered DNS query. Thus the complaint URI is RECOMMENDED to include sufficient detail to determine the filtering state when the DNS filtering occurred. If and how this is encoded into the complaint URI is an implementation decision.

5.3. Client Processing Response

On receipt of the DNS response, the following actions are performed specific to Structured Error EDNS(0) option, in no particular order:

  • The requestor MUST check that the response was received over an encrypted DNS channel. If not, the requestor MUST discard any returned Structured Error EDNS(0) option.
  • If the DNS response contains more than one Structured Error EDNS(0) option, the requestor MUST discard all Structured Error ENDS(0) options.
  • The DNS response MUST also contain an extended error code of "Censored", "Blocked", "Filtered" or "Forged", otherwise the Structured Error EDNS(0) option is discarded.
  • If either of the mandatory JSON names "d" and "j" are missing or have empty values in the Structured Error EDNS(0) option, the option is discarded.
  • The Requestor expands the values in "c" and "r" by prefixing the two values with "https://" and the value of the "d" name. Then the Requestor further expands each of the "c" and "r" URIs by appending two URL query parameters: "type" indicating the name of the DNS resource record type queried and "name" indicating the name of the DNS resource record queried.
  • If a DNS client has enabled opportunistic privacy profile (Section 5 of [RFC8310]) for DoT, the DNS client will either fallback to an encrypted connection without authenticating the DNS server provided by the local network or fallback to clear text DNS, and cannot exchange encrypted DNS messages. Both of these fallback mechanisms adversely impacts security and privacy. If the DNS client has enabled opportunistic privacy profile for DoT, the DNS client MUST ignore the Structured DNS Error EDNS(0) option responses, but SHOULD process other parts of the response.
  • If a DNS client has enabled strict privacy profile (Section 5 of [RFC8310]) for DoT, the DNS client requires an encrypted connection and successful authentication of the DNS server; this mitigates both passive eavesdropping and client redirection (at the expense of providing no DNS service if an encrypted, authenticated connection is not available). If the DNS client has enabled strict privacy profile for DoT, the client MAY process the Structured DNS Error EDNS(0) option of the DNS response. Note that the strict and opportunistic privacy profiles as defined in [RFC8310] only apply to DoT; there has been no such distinction made for DoH.
  • If the DNS client determines that the encrypted DNS server does not offer DNS filtering service, it MUST reject the Structured Error EDNS(0) option. For example, the DNS client can learn whether the encrypted DNS resolver performs DNS-based content filtering or not by retrieving resolver information using the method defined in [I-D.reddy-add-resolver-info].
  • DNS forwarders (or DNS proxies) are supposed to propagate unknown EDNS(0) options (Sections 4.1 and 4.4.1 of [RFC5625]), which means the Structured Error EDNS(0) option may get propagated by such a DNS server. To detect this scenario, the DNS client MUST verify the domain name in the Structured Error "d" value matches the domain name of the encrypted DNS resolver. If this match fails, the DNS client MUST ignore the Structured Error EDNS(0) option in the response.

6. Examples

An example showing the nameserver at '' that filtered a DNS "A" record query for '' is shown in Figure 2.

    "c": "?time=1621902483",
    "d": "",
    "j": "malware present for 23 days",
    "o": " Filtering Service",
    "r": "?country=atlantis"
Figure 2: JSON returned in EDNS(0) Structured Error response

In Figure 3 the same content is shown with minified JSON (no whitespace, no blank lines) with '\' line wrapping per [RFC8792].

  ============== NOTE: '\' line wrapping per RFC 8792 ===============

  {"c":"?time=1621902483","d":"","j":"malware present \
  for 23 days","o":" Filtering Service","r":\
Figure 3: Minified response

Upon receipt, the two partial URIs ("c" and "r") are expanded to become fully-formed URIs. The class, type, and name are pulled from the DNS response (that matches the associated query) so that the fully-formed "c" URI becomes "" and the "r" URI becomes "".

7. Security Considerations

Security considerations in Section 6 of [RFC8914] apply to this document.

To minimize impact of active on-path attacks on the DNS channel, the client validates the response as described in Section 5.3.

If the browser visits either of the URIs in the response ("c" or "r"), the browser SHOULD reduce the attack surface of the client by using an isolated environment precautions such as clearly labeling the page as untrusted or prevent user interaction with the page. Such isolation should prevent transmitting cookies, block JavaScript, block auto-fill of credentials or personal information, and be isolated from the user's normal environment.

When displaying the free-form text of "o" and "j", the browser SHOULD NOT make any of those elements into actionable (clickable) links.

Although the "d" value is validated, an attacker who is able to inject the Structured Error EDNS(0) option so that a DNS proxy or DNS forwarder, unaware of the option, will forward it and pass the validation checks described in Section 5.3. This means the other JSON fields can be controlled by the attacker. The "j" and "o" fields are, perhaps, the most interesting for an attacker to modify for nefarious purposes, because the "d" field has to match the encrypted DNS server's name and the expanded URIs from the "c" and "r" will point at the DNS resolver not under the attacker's control.

8. IANA Considerations

This document requests IANA assign a DNS EDNS0 Option Code (OPT) value in the Expert Review range named "Structured DNS Error".

This document requests IANA to register the "application/json+structured-dns-error" media type in the "Media Types" registry [IANA-MediaTypes]. This registration follows the procedures specified in [RFC6838]:

   Type name: application

   Subtype name: json+structured-dns-error

   Required parameters: N/A

   Optional parameters: N/A

   Encoding considerations: as defined in Section NN of [RFCXXXX].

   Security considerations: See Section NNN of [RFCXXXX].

   Interoperability considerations: N/A

   Published specification: [RFCXXXX]

   Applications that use this media type: Section NNNN of [RFCXXXX].

   Fragment identifier considerations: N/A

   Additional information: N/A

   Person & email address to contact for further information: IETF,

   Intended usage: COMMON

   Restrictions on usage: none

   Author: See Authors' Addresses section.

   Change controller: IESG

   Provisional registration?  No

9. Changes

This section is to be removed before publishing as an RFC.

9.1. Changes from 00 to 01

  • removed support for multiple responsible parties
  • one-character JSON names to minimize JSON length
  • partial URI sent in "c" and "r" names, combined with "d" name sent in JSON to minimize attack surface and minimize JSON length
  • moved EDNS(0) forgery-mitigation text, some Security Considerations text, and some other text from [I-D.reddy-dnsop-error-page] to this document

10. References

10.1. Normative References

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <>.
Freed, N., Klensin, J., and T. Hansen, "Media Type Specifications and Registration Procedures", BCP 13, RFC 6838, DOI 10.17487/RFC6838, , <>.
Damas, J., Graff, M., and P. Vixie, "Extension Mechanisms for DNS (EDNS(0))", STD 75, RFC 6891, DOI 10.17487/RFC6891, , <>.
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <>.
Dickinson, S., Gillmor, D., and T. Reddy, "Usage Profiles for DNS over TLS and DNS over DTLS", RFC 8310, DOI 10.17487/RFC8310, , <>.

10.2. Informative References

Huitema, C., Dickinson, S., and A. Mankin, "DNS over Dedicated QUIC Connections", Work in Progress, Internet-Draft, draft-ietf-dprive-dnsoquic-05, , <>.
Reddy, T. and M. Boucadair, "DNS Resolver Information", Work in Progress, Internet-Draft, draft-reddy-add-resolver-info-03, , <>.
Reddy, T., Cook, N., Wing, D., and M. Boucadair, "DNS Access Denied Error Page", Work in Progress, Internet-Draft, draft-reddy-dnsop-error-page-08, , <>.
IANA, "Media Types", <>.
Bellis, R., "DNS Proxy Implementation Guidelines", BCP 152, RFC 5625, DOI 10.17487/RFC5625, , <>.
Hu, Z., Zhu, L., Heidemann, J., Mankin, A., Wessels, D., and P. Hoffman, "Specification for DNS over Transport Layer Security (TLS)", RFC 7858, DOI 10.17487/RFC7858, , <>.
Hoffman, P. and P. McManus, "DNS Queries over HTTPS (DoH)", RFC 8484, DOI 10.17487/RFC8484, , <>.
Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS Terminology", BCP 219, RFC 8499, DOI 10.17487/RFC8499, , <>.
Watsen, K., Auerswald, E., Farrel, A., and Q. Wu, "Handling Long Lines in Content of Internet-Drafts and RFCs", RFC 8792, DOI 10.17487/RFC8792, , <>.
Kumari, W., Hunt, E., Arends, R., Hardaker, W., and D. Lawrence, "Extended DNS Errors", RFC 8914, DOI 10.17487/RFC8914, , <>.

Authors' Addresses

Dan Wing
Citrix Systems, Inc.
United States of America
Tirumaleswar Reddy
Neil Cook
United Kingdom
Mohamed Boucadair
35000 Rennes