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, <http://www.rfc-editor.org/info/rfc1035>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>.
[RFC3492] Costello, A., "Punycode: A Bootstring encoding of Unicode
for Internationalized Domain Names in Applications
(IDNA)", RFC 3492, DOI 10.17487/RFC3492, March 2003,
<http://www.rfc-editor.org/info/rfc3492>.
[RFC5890] Klensin, J., "Internationalized Domain Names for
Applications (IDNA): Definitions and Document Framework",
RFC 5890, DOI 10.17487/RFC5890, August 2010,
<http://www.rfc-editor.org/info/rfc5890>.
[RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March
2014, <http://www.rfc-editor.org/info/rfc7159>.
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,
<http://www.rfc-editor.org/info/rfc7540>.
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]