Network Working Group P. Hoffman Internet-Draft ICANN Intended status: Standards Track June 05, 2017 Expires: December 7, 2017 Simple DNS Queries and Responses in JSON draft-hoffman-simplednsjson-00 Abstract This document describes a JSON-based format for simple DNS queries and responses. In this case, "simple" means "only useful for getting A and AAAA records". This document also defines the application/ simpledns+json media type. The primary use case of this format is programs that do not want to take on the programmatic overhead needed to use messages in the application/dns-udpwireformat media type. [ This paragraph is to be removed when this document is published as an RFC ] Comments on this draft can be sent to the DNS over HTTP mailing list at https://www.ietf.org/mailman/listinfo/dnsoverhttp . 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 http://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 December 7, 2017. Copyright Notice Copyright (c) 2017 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 (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents Hoffman Expires December 7, 2017 [Page 1] Internet-Draft Simple DNS in JSON June 2017 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 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 2. Using the Simple JSON DNS Query Format in HTTP . . . . . . . 3 3. Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 4. Responses . . . . . . . . . . . . . . . . . . . . . . . . . . 3 5. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 4 6.1. Registration of application/simpledns+json Media Type . . 5 7. Security Considerations . . . . . . . . . . . . . . . . . . . 6 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 6 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 6 9.1. Normative References . . . . . . . . . . . . . . . . . . 6 9.2. Informative References . . . . . . . . . . . . . . . . . 6 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 7 1. Introduction This document also defines the application/simpledns+json media type. The data format in this media type allows clients to ask for the DNS [RFC1035] address records (A and AAAA records) for a domain name, and get back just the basic answer information. The contents of the message are in JSON [RFC7159]. The primary use case of this format is programs that do not want to take on the programmatic overhead needed to use messages in the application/dns-udpwireformat media type. Data in application/ simpledns+json is a JSON object with very few members in the query or in the response, whereas using the application/dns-udpwireformat requires a program to be able to assemble and disassemble full DNS messages. Queries using application/simpledns+json only let the program ask for IP address, while queries using application/dns- udpwireformat allow any asking for any DNS data type, and using any DNS extension. The application/simpledns+json format is expected to be useful in HTTP, such as the protocol described in [I-D.hoffman-dns-over-https]. Hoffman Expires December 7, 2017 [Page 2] Internet-Draft Simple DNS in JSON June 2017 1.1. Terminology In this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in BCP 14, RFC 2119 [RFC2119]. 2. Using the Simple JSON DNS Query Format in HTTP When used in HTTP or similar protocols, the media type for carrying the data described here is "application/simpledns+json". The body of the query, and the contents of the response, are JSON objects. The definition of those objects is given here, but the query and response objects MAY have other elements that are either defined later or are based on local implementation decisions. 3. Queries The structure of a query is: { "name": str, "type": str } The "name" member MUST be present in queries. The "type" member is optional in queries. The name is given as a host name; IDNs [RFC5890] are expressed in Punycode [RFC3492]. The type is given as a string, and one of the following three values MUST be used: "A", "AAAA", and "A-and-AAAA". If the "type" member is not included, a server treats the query as if it was for "A-and- AAAA". 4. Responses The structure of a response is: { "code": int, "v4": [ zero or more addresses as strs ], "v6": [ zero or more addresses as strs ] } The "code" member MUST be present in responses. The "v4" and "v6" members are optional in responses. The value for "code" MUST be one of the following: Hoffman Expires December 7, 2017 [Page 3] Internet-Draft Simple DNS in JSON June 2017 0: The name exists. This does not mean that A or AAAA records exist, just that the name exists. This code can be treated similarly to a NOERROR response in DNS. 1: The name does not exist. This code can be treated similarly to a NXDOMAIN response in DNS. 2: Service failure. This code can be treated similarly to a SERVFAIL response in DNS. If they are included, the "v4" and "v6" members MUST each contain a list of strings, with each string representing a single address. 5. Example For example, assume a DNS API server is following this specification on origin https://dnsserver.example.net/ and the well-known path. The examples uses HTTP/2 formatting from [RFC7540]. A query for the IN A records for "www.example.com" with recursion turned on using the GET method with the wireformat would be: :method = GET :scheme = https :authority = dnsserver.example.net :path = /.well-known/dns-query? content-type=application/simpledns+json& (no CR) { "name": "www.example.com", "type": "A" } accept = application/simpledns+json [[ Does anything in that preceding example need to be escaped or quoted? ]] The response might be: :status = 200 content-type = application/simpledns+json content-length = 34 cache-control = max-age=128 {"code":0, "v4":["93.184.216.34"]} 6. IANA Considerations Hoffman Expires December 7, 2017 [Page 4] Internet-Draft Simple DNS in JSON June 2017 6.1. Registration of application/simpledns+json Media Type To: ietf-types@iana.org Subject: Registration of MIME media type application/simpledns+json MIME media type name: application MIME subtype name: simpledns+json Required parameters: n/a Optional parameters: n/a Encoding considerations: This is a binary format. The contents are JSON {{RFC7159}}. (Note that {{RFC7159}} states that JSON is a binary format.) Security considerations: See {{RFC7159}}, Section 12. Interoperability considerations: None. Published specification: This document. Applications that use this media type: Systems that want to exchange short DNS queries and limited DNS responses. Additional information: Magic number(s): n/a File extension(s): n/a Macintosh file type code(s): n/a Person & email address to contact for further information: Paul Hoffman, paul.hoffman@icann.org Intended usage: COMMON Restrictions on usage: n/a Author: Paul Hoffman, paul.hoffman@icann.org Change controller: IESG Hoffman Expires December 7, 2017 [Page 5] Internet-Draft Simple DNS in JSON June 2017 7. Security Considerations All security considerations from [RFC7159] apply here. 8. Acknowledgments Patrick McManus inspired the creation of this document. 9. References 9.1. Normative References [RFC1035] Mockapetris, P., "Domain names - implementation and specification", STD 13, RFC 1035, DOI 10.17487/RFC1035, November 1987, . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC3492] Costello, A., "Punycode: A Bootstring encoding of Unicode for Internationalized Domain Names in Applications (IDNA)", RFC 3492, DOI 10.17487/RFC3492, March 2003, . [RFC5890] Klensin, J., "Internationalized Domain Names for Applications (IDNA): Definitions and Document Framework", RFC 5890, DOI 10.17487/RFC5890, August 2010, . [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 2014, . 9.2. Informative References [I-D.hoffman-dns-over-https] Hoffman, P. and P. McManus, "DNS Queries over HTTPS", draft-hoffman-dns-over-https-00 (work in progress), May 2017. [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext Transfer Protocol Version 2 (HTTP/2)", RFC 7540, DOI 10.17487/RFC7540, May 2015, . Hoffman Expires December 7, 2017 [Page 6] Internet-Draft Simple DNS in JSON June 2017 Author's Address Paul Hoffman ICANN Email: paul.hoffman@icann.org Hoffman Expires December 7, 2017 [Page 7]