Structured Error Data for Filtered DNS

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 31 May 2025.¶

Copyright Notice

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

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. Introduction

DNS filters are deployed for a variety of reasons, e.g., 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 network, DNS filtering is used for the same reasons as above and additionally for parental control. Internet Service Providers (ISPs) 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 that perform filtering may wish to receive more explanatory information about such a filtering to resolve problems with the filter -- for example to contact the administrator to allowlist a DNS domain that was erroneously filtered or to understand the reason a particular domain was filtered. With that information, a user can choose to use another network, open a trouble ticket with the DNS administrator to resolve erroneous filtering, log the information, etc.¶

For the DNS filtering mechanisms described in Section 3, the DNS server can return extended error codes Blocked, 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 filterings.¶

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 the approach described in this document 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 format for computer-parsable data in the EXTRA-TEXT field of [RFC8914]. It updates Section 2 of [RFC8914] which says the information in EXTRA-TEXT field is intended for human consumption (not automated parsing).¶

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

2. Conventions and Definitions

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

"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 [RFC9250].¶

The document refers to an Extended DNS Error (EDE) using its purpose, not its INFO-CODE as per Table 3 of [RFC8914]. "Forged Answer", "Blocked", and "Filtered" are thus used to refer to "Forged Answer (4)", "Blocked (15)", and "Filtered (17)".¶

3. DNS Filtering Techniques and Their Limitations

DNS responses can be filtered by sending, e.g., a bogus (also called "forged") response, NXDOMAIN error, or empty answer. Also, clients can be informed that filtering has occured by sending an Extended DNS Error 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., Customer Premises Equipment (CPE) or 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 stores a copy of the private key. During the TLS handshake, the on-path network security device modifies the certificate provided by the server and (re)signs it using the private key from the local root certificate.¶

   • However, this approach is ineffective when DNSSEC is deployed given that DNSSEC ensures the integrity and authenticity of DNS responses, preventing forged DNS responses from being accepted.¶

   • The HTTPS server will have access to the client's IP address and the hostname being requested. This information will be sensitive, as it will expose the user's identity and the domain name that a user attempted to access.¶

   • Configuring a local root certificate on endpoints is not a viable option in several deployments like home networks, schools, Small Office/Home Office (SOHO), or Small/Medium Enterprise (SME). In these cases, the typical behavior is that the filtered DNS response points to a server that will display the block page. If the client is using HTTPS (via a web browser or another application) this results in a certificate validation error which gives no information to the end-user about the reason for the DNS filtering.¶

   • 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 prevented 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 filtering 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. However, this approach does not work with DNSSEC. In scenarios without DNSSEC, an end user does not know why a domain name cannot be reached and may repeatedly try to reach that domain name but without success. Frustrated, an end user may use insecure connections to reach the domain name, potentially compromising both security and privacy.¶

3. The extended error codes Blocked and Filtered defined in Section 4 of [RFC8914] can be returned by a DNS server to provide additional information about the cause of a DNS 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 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 "Malware" to protect the endpoint from malicious software, "Phishing" to prevent the user from revealing sensitive information to the attacker, etc. A user may need to know the contact details of the IT/InfoSec team to raise a complaint.¶

4. I-JSON in EXTRA-TEXT Field

DNS servers that are compliant with this specification and have received an indication that the client also supports this specification as per Section 5.1 send data in the EXTRA-TEXT field [RFC8914] encoded using the Internet JSON (I-JSON) message format [RFC7493].¶

• Note that [RFC7493] was based on [RFC7159], but [RFC7159] was replaced by [RFC8259].¶

This document defines the following JSON names:¶

c: (contact)

The contact details of the IT/InfoSec team to report mis-classified DNS filtering. This information is important for transparency and also to ease unblocking a legitimate domain name that got blocked due to wrong classification.¶

This field is structured as an array of contact URIs, using 'tel' [RFC3966] or 'sips' [RFC5630] or 'mailto' [RFC3966] schemes. At least one contact URI MUST be included.¶

New contact URI schemes may be added to the IANA registry following the instructions in Section 10.3.¶

This field is mandatory.¶

j: (justification)

'UTF-8'-encoded [RFC5198] textual justification for this particular DNS filtering. The field should be treated only as diagnostic information for IT staff.¶

Whether the information provided in the "j" name is meaningful or considered as garbage data (including empty values) is local to each IT teams. Returning garbage data would indicate that a DNS server is misbehaving. Note also that the provided justification is useful for cross-validation with another DNS server.¶

This field is mandatory.¶

s: (suberror)

The suberror code for this particular DNS filtering.¶

This field is optional.¶

o: (organization)

'UTF-8'-encoded human-friendly name of the organization that filtered this particular DNS query.¶

This field is optional.¶

l: (language)

The "l" field indicates the language used for the JSON-encoded "j" and "o" fields. The value of this field MUST conform to the language tag syntax specified in Section 2.1 of [RFC5646].¶

This field is optional but RECOMMENDED to aid in localization.¶

New JSON names can be defined in the IANA registry introduced in Section 10.2. Such names MUST consist only of lower-case ASCII characters, digits, and hyphen-minus (that is, Unicode characters U+0061 through 007A, U+0030 through U+0039, and U+002D). Also, these names MUST be 63 characters or shorter and it is RECOMMENDED they be as short as possible.¶

The text in the "j" and "o" names can include international characters. The text will be in natural language, chosen by the DNS administrator to match its expected audience.¶

To reduce DNS message size 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.¶

• An alternate design for conveying the suberror would be to define new EDE codes for these errors. However, such design is suboptimal because it requires replicating an error code for each EDE code to which the suberror applies (e.g., "Malware" suberror in Table 3 would consume three EDE codes).¶

5. Protocol Operation

6. New Sub-Error Codes Definition

The document defines the following new IANA-registered Sub-Error codes.¶

7. Extended DNS Error Code TBA1 - Blocked by Upstream DNS Server

The DNS server (e.g., a DNS forwarder) is unable to respond to the request because the domain is on a blocklist due to an internal security policy imposed by an upstream DNS server. This error code is useful in deployments where a network-provided DNS forwarder is configured to use an external resolver that filters malicious domains. Typically, when the DNS forwarder receives a Blocked (15) error code from the upstream DNS server, it will replace it with "Blocked by Upstream DNS Server" (TBA1) before forwarding the reply to the DNS client.¶

8. Examples

An example showing the nameserver at 'ns.example.net' that filtered a DNS "A" record query for 'example.org' is provided in Figure 1.¶

{
  "c": [
    "tel:+358-555-1234567",
    "sips:[email protected]"
  ],
  "j": "malware present for 23 days",
  "s": 1,
  "o": "example.net Filtering Service"
  "l": "tzm",
}

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

{::include-fold68left0 ./examples/minified.json}

9. Security Considerations

Security considerations in Section 6 of [RFC8914] apply to this document, except the guard against using EDE content to alter DNS protocol processing. The guard is relaxed in the current specification as it mandates encryption and recommends the use of an authenticated connection to the DNS server, while [RFC8914] assumes that EDE information is unauthenticated and sent over clear text.¶

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

A client might choose to display the information in the "c", "j", and "o" fields if and only if the encrypted resolver has sufficient reputation, according to some local policy (e.g., user configuration, administrative configuration, or a built-in list of respectable resolvers). This limits the ability of a malicious encrypted resolver to cause harm. For example, an end user can use the details in the "c" field to contact an attacker to solve the problem of being unable to reach a domain. The attacker can mislead the end user to install malware or spyware to compromise the device security posture or mislead the end user to reveal personal data. If the client decides not to display all of the information in the EXTRA-TEXT field, it can be logged for diagnostics purpose and the client can only display the resolver hostname that blocked the domain, error description for the EDE code and the suberror description for the "s" field to the end-user.¶

When displaying the free-form text of "j" and "o", the browser MUST NOT make any of those elements into actionable (clickable) links and these fields need to be rendered as text, not as HTML. The contact details of "c" can be made into clickable links to provide a convenient way for users to initiate, e.g., voice calls. The client might choose to display the contact details only when the identity of the DNS server is verified.¶

An attacker might inject (or modify) the EDE EXTRA-TEXT field with a DNS proxy or DNS forwarder that is unaware of EDE. Such a DNS proxy or DNS forwarder will forward that attacker-controlled EDE option. To prevent such an attack, clients can be configured to process EDE from explicitly configured DNS servers or utilize RESINFO [I-D.ietf-add-resolver-info].¶

10. IANA Considerations

This document requests four IANA actions as described in the following subsections.¶

• Note to the RFC Editor: Please replace RFCXXXX with the RFC number assigned to this document and "TBA1" with the value assigned by IANA.¶

   Type name: application

   Subtype name: json+structured-dns-error

   Required parameters: N/A

   Optional parameters: N/A

   Encoding considerations: as defined in Section 4 of RFCXXXX.

   Security considerations: See Section 10 of RFCXXXX.

   Interoperability considerations: N/A

   Published specification: RFCXXXX

   Applications that use this media type: Section 4 of RFCXXXX.

   Fragment identifier considerations: N/A

   Additional information: N/A

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

   Intended usage: COMMON

   Restrictions on usage: none

   Author: See Authors' Addresses section.

   Change controller: IESG

   Provisional registration?  No

11. References

Appendix A. Interoperation with RPZ Servers

This appendix provides a non-normative guidance for operation with an Response Policy Zones (RPZ) server [RPZ] that indicates filtering with a NXDOMAIN response with the Recursion Available bit cleared (RA=0). This guidance is provided to ease interoperation with RPZ.¶

When a DNS client supports this specification, it includes the EDE option in its DNS query.¶

If the server does not support this specification and is performing RPZ filtering, the server ignores the EDE option in the DNS query and replies with NXDOMAIN and RA=0. The DNS client can continue to accept such responses.¶

If the server does support this specification and is performing RPZ filtering, the server can use the EDE option in the query to identify an EDE-aware client and respond appropriately (that is, by generating a response described in Section 5.2) as NXDOMAIN and RA=0 are not necessary when generating a response to such a client.¶

Appendix B. Implementation Status

• Note to the RFC Editor: please remove this appendix prior publication.¶

At IETF#116, Gianpaolo Scalone (Vodafone) and Ralf Weber (Akamai) presented an implementation of this specification. More details can be found at [Impl-1].¶

Acknowledgements

Thanks to Vittorio Bertola, Wes Hardaker, Ben Schwartz, Erid Orth, Viktor Dukhovni, Warren Kumari, Paul Wouters, John Levine, Bob Harold, Mukund Sivaraman, Stephane Bortzmeyer, Gianpaolo Angelo Scalone, and Daniel Migault for the comments.¶

Thanks to Ralf Weber and Gianpaolo Scalone for sharing details about their implementation.¶

Thanks Di Ma and Matt Brown for the DNS directorate reviews, and Joseph Salowey for the Security directorate review.¶

Authors' Addresses