Structured Data for DNS Access Denied Error Page

Document Type Active Internet-Draft (individual)
Authors Dan Wing  , Tirumaleswar Reddy.K  , Neil Cook  , Mohamed Boucadair 
Last updated 2021-07-09
Stream (None)
Intended RFC status (None)
Formats pdf htmlized bibtex
Stream Stream state (No stream defined)
Consensus Boilerplate Unknown
RFC Editor Note (None)
IESG IESG state I-D Exists
Telechat date
Responsible AD (None)
Send notices to (None)
DNSOP WG                                                         D. Wing
Internet-Draft                                                    Citrix
Intended status: Standards Track                                T. Reddy
Expires: 10 January 2022                                          McAfee
                                                                 N. Cook
                                                            M. Boucadair
                                                             9 July 2021

            Structured Data for DNS Access Denied Error 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.

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 10 January 2022.

Copyright Notice

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

Wing, et al.             Expires 10 January 2022                [Page 1]
Internet-Draft   Structured DNS Access Denied Error Page       July 2021

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents (
   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.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   3
   3.  Structured Data . . . . . . . . . . . . . . . . . . . . . . .   3
   4.  Examples  . . . . . . . . . . . . . . . . . . . . . . . . . .   4
   5.  Deployment Considerations . . . . . . . . . . . . . . . . . .   5
   6.  Usability Considerations  . . . . . . . . . . . . . . . . . .   6
   7.  Security Considerations . . . . . . . . . . . . . . . . . . .   6
   8.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   6
   9.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   7
     9.1.  Normative References  . . . . . . . . . . . . . . . . . .   7
     9.2.  Informative References  . . . . . . . . . . . . . . . . .   8
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .   9

1.  Introduction

   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

Wing, et al.             Expires 10 January 2022                [Page 2]
Internet-Draft   Structured DNS Access Denied Error Page       July 2021

   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

2.  Terminology

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "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].

3.  Structured Data

   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:

   complaint:  Is an array of URIs for the user to report mis-classified
      DNS filtering.  This is likely to solely contain an "https" URI,
      but an array is provided in case telephone numbers or email or
      other URIs are necessary.  This field is mandatory and MUST
      contain at least one URI.

   justification:  Includes the textual justification for this
      particular DNS filtering.  This field is optional.

   name:  is the human-friendly name of the organization that filtered
      this particular DNS query.  This field is optional.

   regulation:  the URI of the regulation authority for this DNS query

Wing, et al.             Expires 10 January 2022                [Page 3]
Internet-Draft   Structured DNS Access Denied Error Page       July 2021

      being filtered.  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

   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.

4.  Examples

   The examples use the folding defined in [RFC8792] for long lines.

   An example with one entity, "", that has filtered a DNS
   query is shown in Figure 1, below.

     "responsible": [
         "complaint": [
           "\"incorrect filtering\
            of at 1621902483\"",
         "justification": "malware present for 23 days",
         "name": " Filtering Service",
         "regulation": ""

               Figure 1: Example of Filtering with One Entity

   An example with two entities, "" and "", that
   have filtered a DNS query is shown in Figure 2, below.

Wing, et al.             Expires 10 January 2022                [Page 4]
Internet-Draft   Structured DNS Access Denied Error Page       July 2021

     "responsible": [
         "complaint": [
           "\"incorrect filtering\
            of at 1621902483\"",
         "justification": "malware present for 23 days",
         "name": " Filtering Service",
         "regulation": ""
         "complaint": [
           "\"false positive filtering\
   on 24-May-2021 5:03 GMT\"",
         "justification": "command and control malware",
         "name": " IT department",
         "regulation": ""

              Figure 2: Example of Filtering with Two Entities

5.  Deployment Considerations

   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.

Wing, et al.             Expires 10 January 2022                [Page 5]
Internet-Draft   Structured DNS Access Denied Error Page       July 2021

   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 ( indicates
   their structured DNS error page for a query to is, that URL can be conveyed to
   the user as the URL-encoded parameter 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.

6.  Usability Considerations

   The JSON values returned SHOULD be returned in the user's preferred
   language as expressed by the Accept-Language HTTP header.

7.  Security Considerations

   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.

8.  IANA Considerations

   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]:

Wing, et al.             Expires 10 January 2022                [Page 6]
Internet-Draft   Structured DNS Access Denied Error Page       July 2021

      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,

      Intended usage: COMMON

      Restrictions on usage: none

      Author: See Authors' Addresses section.

      Change controller: IESG

      Provisional registration?  No

9.  References

9.1.  Normative References

              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, 4 June 2021,

Wing, et al.             Expires 10 January 2022                [Page 7]
Internet-Draft   Structured DNS Access Denied Error Page       July 2021

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,

   [RFC6838]  Freed, N., Klensin, J., and T. Hansen, "Media Type
              Specifications and Registration Procedures", BCP 13,
              RFC 6838, DOI 10.17487/RFC6838, January 2013,

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <>.

9.2.  Informative References

              Huitema, C., Mankin, A., and S. Dickinson, "Specification
              of DNS over Dedicated QUIC Connections", Work in Progress,
              Internet-Draft, draft-ietf-dprive-dnsoquic-02, 22 February
              2021, <

              IANA, "Media Types",

   [RFC7858]  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, May
              2016, <>.

   [RFC8484]  Hoffman, P. and P. McManus, "DNS Queries over HTTPS
              (DoH)", RFC 8484, DOI 10.17487/RFC8484, October 2018,

   [RFC8499]  Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS
              Terminology", BCP 219, RFC 8499, DOI 10.17487/RFC8499,
              January 2019, <>.

   [RFC8792]  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, June 2020,

Wing, et al.             Expires 10 January 2022                [Page 8]
Internet-Draft   Structured DNS Access Denied Error Page       July 2021

   [RFC8914]  Kumari, W., Hunt, E., Arends, R., Hardaker, W., and D.
              Lawrence, "Extended DNS Errors", RFC 8914,
              DOI 10.17487/RFC8914, October 2020,

Authors' Addresses

   Dan Wing
   Citrix Systems, Inc.
   United States of America


   Tirumaleswar Reddy
   McAfee, Inc.
   Embassy Golf Link Business Park
   Bangalore 560071


   Neil Cook
   United Kingdom


   Mohamed Boucadair
   35000 Rennes


Wing, et al.             Expires 10 January 2022                [Page 9]