Internet-Draft | Structured DNS Access Denied Error Page | July 2021 |
Wing, et al. | Expires 10 January 2022 | [Page] |
It can be valuable to communicate computer-parsable details about DNS filtering to assist troubleshooting and problem resolution. This document describes structured data to provide these details.¶
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 10 January 2022.¶
Copyright (c) 2021 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 Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.¶
DNS clients using services which perform filtering may wish to receive more information about such filtering and the reason for that filtering. To this end, Extended DNS Error Codes [RFC8914] provide information about when different types of filtering have occurred, and DNS Access Denied Error Page [I-D.reddy-dnsop-error-page] provides a URI to give further information to the end-user about the reasons for the filtering. However, the latter draft assumes a client with a user-interface that can display a web page to the end-user, whereas many clients may in fact be "headless", i.e., acting on behalf of other network elements; such clients can include DNS forwarders and proxies. Such clients cannot make use of a web-page designed for presentation to an end-user, but may instead be able to make use of structured data. This draft provides a mechanism for such clients to request and receive structured data from the URI returned by the DNS Access Denied Error Page mechanism.¶
When a third party provides DNS filtering, there are deployments where disclosing that third party to the host (which originated the DNS query) is desirable but other deployments where such disclosure is not desired. For example, the IT organization might contract filtering to a third party but want trouble-tickets from employees to be handled by IT, rather than having employees interact directly with the third party. As another example, all the employees at a small business or all the members of a household might be informed of the third party so they can troubleshoot filtering with that third party directly.¶
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 makes use of the terms defined in [RFC8499].¶
'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].¶
To receive structured DNS error page data, the client MUST query the Error Page URI returned in [I-D.reddy-dnsop-error-page] with Content-Type set to "application/json+structured-dns-error". The JSON has one top-level name, "responsible", containing an array of dictionaries for each party responsible for this particular DNS filter. An array of responsible parties are possible in deployment scenarios where two or more entities are involved in a DNS filtering (the filtering may be for the same or distinct reasons by each involved DNS filter service). The content of the array is structured are as follows:¶
The JSON data can be displayed 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.¶
The examples use the folding defined in [RFC8792] for long lines.¶
An example with one entity, "example.net", that has filtered a DNS query is shown in Figure 1, below.¶
{ "responsible": [ { "complaint": [ "mailto:helpdesk@example.net?subject=\"incorrect filtering\ of example.org at 1621902483\"", "https://mistakes.example.net?domain=example.org?\ time=1621902483", "tel:+18305551212" ], "justification": "malware present for 23 days", "name": "example.net Filtering Service", "regulation": "https://laws.example.net?country=atlantis" } ] }
An example with two entities, "example.com" and "example.net", that have filtered a DNS query is shown in Figure 2, below.¶
{ "responsible": [ { "complaint": [ "mailto:helpdesk@example.net?subject=\"incorrect filtering\ of example.org at 1621902483\"", "https://mistake.example.net?domain=example.org?\ time=1621902483", "tel:+18305551212" ], "justification": "malware present for 23 days", "name": "Example.net Filtering Service", "regulation": "https://laws.example.net?country=atlantis" }, { "complaint": [ "mailto:abuse@example.com?subject=\"false positive filtering\ example.org on 24-May-2021 5:03 GMT\"", "https://example.net/report?d=example.org?t=38233", "tel:+5305551212" ], "justification": "command and control malware", "name": "Example.com IT department", "regulation": "https://hr.example.com?state=CA" } ] }}
Over time a domain name may be considered risky, then safe, then risky again, and later can elapse between the DNS EDNS0 error and the user reporting a false positive and the DNS filtering service receiving the user's complaint. Thus the URI is RECOMMENDED to include sufficient detail to determine the state when the DNS EDNS0 response was generated. How this is encoded into the URI is an implementation decision.¶
As discussed in the Introduction, some deployment models allow the DNS filter provider to be conveyed to the end-user. In such a deployment, state can be avoided in the DNS forwarder by conveying the DNS filter provider's URL in the URL sent to the user. For example, if the upstream DNS filter provider (example.net) indicates their structured DNS error page for a query to example.org is https://example.net?f=example.org&s=38, that URL can be conveyed to the user as the URL-encoded parameter https%3A%2F%2Fexample.net%3Ff%3Dexample.org%26s%3D38229 appended to the DNS forwarder's DNS error page URL.¶
An array allows multiple DNS filters to be provided by specialized services. For example, one service might filter access to malicious domains and another filters domains due to an internal security policy or court order.¶
The JSON values returned SHOULD be returned in the user's preferred language as expressed by the Accept-Language HTTP header.¶
Security considerations inherent to the use of DNS Error Page URI are discussed in Section 7 of [I-D.reddy-dnsop-error-page].¶
The structure data includes URLs that may be misused to return infected or compromised websites. Means to detect and avoid such URL are recommended. Likewise, contact URIs and telephone numbers may be misused to return third-party contact points and thus lead to spam these contacts.¶
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 3 of [RFCXXXX]. Security considerations: See Section 7 of [RFCXXXX]. Interoperability considerations: N/A Published specification: [RFCXXXX] Applications that use this media type: Section 3 of [RFCXXXX]. Fragment identifier considerations: N/A Additional information: N/A Person & email address to contact for further information: IETF, iesg@ietf.org Intended usage: COMMON Restrictions on usage: none Author: See Authors' Addresses section. Change controller: IESG Provisional registration? No¶