idnits 2.17.1 draft-hoffman-dns-in-json-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (September 21, 2016) is 2773 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) == Outdated reference: A later version (-10) exists of draft-dulaunoy-dnsop-passive-dns-cof-01 Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group P. Hoffman 3 Internet-Draft ICANN 4 Intended status: Experimental September 21, 2016 5 Expires: March 25, 2017 7 Representing DNS Messages in JSON 8 draft-hoffman-dns-in-json-08 10 Abstract 12 Some applications use DNS messages, or parts of DNS messages, as 13 data. For example, a system that captures DNS queries and responses 14 might want to be able to easily search those without having to decode 15 the messages each time. Another example is a system that puts 16 together DNS queries and responses from message parts. This document 17 describes a standardized format for DNS message data in JSON. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at http://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on March 25, 2017. 36 Copyright Notice 38 Copyright (c) 2016 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 54 1.1. Design of the Format . . . . . . . . . . . . . . . . . . 3 55 2. JSON Format for DNS Messages . . . . . . . . . . . . . . . . 4 56 2.1. Message Object Members . . . . . . . . . . . . . . . . . 4 57 2.2. Resource Record Object Members . . . . . . . . . . . . . 5 58 2.3. The Message and Its Parts as Octets . . . . . . . . . . . 6 59 2.4. Additional Message Object Members . . . . . . . . . . . . 7 60 2.5. Name Fields . . . . . . . . . . . . . . . . . . . . . . . 7 61 3. JSON Format for a Paired DNS Query and Response . . . . . . . 8 62 4. Streaming DNS Objects . . . . . . . . . . . . . . . . . . . . 8 63 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 8 64 5.1. Example of the Format of a DNS Query . . . . . . . . . . 8 65 5.2. Example of the Format of a Paired DNS Query and Response 9 66 6. Local Format Policy . . . . . . . . . . . . . . . . . . . . . 10 67 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 68 7.1. MIME Type Registration of application/dns+json . . . . . 10 69 8. Security Considerations . . . . . . . . . . . . . . . . . . . 12 70 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 12 71 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 72 10.1. Normative References . . . . . . . . . . . . . . . . . . 12 73 10.2. Informative References . . . . . . . . . . . . . . . . . 13 74 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 13 76 1. Introduction 78 The DNS message format is defined in [RFC1035]. DNS queries and DNS 79 responses have exactly the same structure. Many of the field names 80 and data type names given in [RFC1035] are commonly used in 81 discussions of DNS. For example, it is common to hear things like 82 "the query had a QNAME of 'example.com'" or "the RDATA has a simple 83 structure". 85 There are hundreds of data interchange formats for serializing 86 structured data. Currently, JSON [RFC7159] is quite popular for many 87 types of data, particularly data that has named sub-fields and 88 optional parts. 90 This document uses JSON to describe DNS messages. It also defines 91 how to describe a paired DNS query and response, and how to stream 92 DNS objects. 94 1.1. Design of the Format 96 There are many ways to design a data format. This document uses a 97 specific design methodology based on the DNS format. 99 o The format is based on JSON objects in order to allow a writer to 100 include or exclude parts of the format at will. No object members 101 are ever required. 103 o This format is purposely overly-general. Protocols and 104 applications that use this format are expected to use only a 105 subset of the items defined here. 107 o All members whose values that are always 16 bits or shorter (even 108 booleans) are represented by JSON integers. 110 o The encoding for the DNS object is ASCII as described in 111 [RFC0020]. This is done to prevent an attempt to use a different 112 encoding such as UTF-8 for octets in names or data. 114 o Values for domain names and RDATA can be expressed using the 115 decimal escaping ("\DDD") defined in [RFC1035], although this can 116 lead to processing problems due to the escaping rules for JSON. 118 o Names of items that have string values can have an "HEX" or "B64" 119 appended to them to indicate a non-ASCII encoding of the value. 120 Names that end in "HEX" have values stored in base16 encoding (hex 121 with uppercase letters) defined in [RFC4648]. This is 122 particularly useful for RDATA that is binary. Names that end in 123 "B64" have values stored in base64url encoding defined in 124 [RFC4648]. This is particularly useful for RDATA that very long 125 (such as cryptographic keys) or entire records. 127 o All field names used in [RFC1035] are used in this format as-is. 128 Names not defined in [RFC1035] generally use "camel case". 130 o The same data may be represented in multiple object members 131 multiple times. For example, there is a member for the octets of 132 the DNS message header, and there are members for each named part 133 of the header. A message object can thus inadvertently have 134 inconsistent data, such as a header member whose value does not 135 match the value of the first bits in the entire message member. 137 o The design explicitly allows for the description of malformed DNS 138 messages. This is important for systems that are logging messages 139 seen on the wire, particularly messages that might be used as part 140 of an attack. A few examples of malformed DNS messages include: 142 * an RR that has an RDLENGTH of 4 but an RDATA whose length is 143 longer than 4 (if it is the last RR in a message) 145 * a DNS message whose QDCOUNT is 0 147 * a DNS message whose QDCOUNT is large but there are insufficient 148 bytes after the header 150 * a DNS message whose length is less than 12 octets, meaning it 151 doesn't even have a full header 153 o An object in this format can have zero or more of the members 154 defined here; that is, no members are required by the format 155 itself. Instead, profiles that use this format might have 156 requirements for mandatory members, optional members, and 157 prohibited members from the format. Also, this format does not 158 prohibit members that are not defined in this format; profiles of 159 the format are free to add new members in the profile. 161 This document defines DNS messages, not zone files. A later 162 specification could be written to extend it to represent zone files. 164 2. JSON Format for DNS Messages 166 The following gives all of the members defined for a DNS message. It 167 is organized approximately by levels of the DNS message. 169 2.1. Message Object Members 171 o ID - Integer whose value is 0 to 65535 173 o QR - Integer whose value is 0 or 1 175 o Opcode - Integer whose value is 0 to 15 177 o AA - Integer whose value is 0 or 1 179 o TC - Integer whose value is 0 or 1 181 o RD - Integer whose value is 0 or 1 183 o RA - Integer whose value is 0 or 1 185 o AD - Integer whose value is 0 or 1 187 o CD - Integer whose value is 0 or 1 189 o RCODE - Integer whose value is 0 to 15 190 o QDCOUNT - Integer whose value is 0 to 65535 192 o ANCOUNT - Integer whose value is 0 to 65535 194 o NSCOUNT - Integer whose value is 0 to 65535 196 o ARCOUNT - Integer whose value is 0 to 65535 198 o QNAME - String of the name of the first Question section of the 199 message; see Section 2.5 for a desciption of the contents 201 o compressedQNAME - Object that describes the name with two optional 202 values: "isCompressed" (with a value of 0 for no and 1 for yes) 203 and "length" (with an integer giving the length in the message) 205 o QTYPE - Integer whose value is 0 to 65535, of the QTYPE of the 206 first Question section of the message 208 o QTYPEname - String whose value is from the IANA RR TYPEs registry, 209 or that has the format in [RFC3597]; this is case-sensitive, so 210 "AAAA" not "aaaa" 212 o QCLASS - Integer whose value is 0 to 65535, of the QCLASS of the 213 first Question section of the message 215 o QCLASSname - String whose value is "IN", "CH", "HS", or has the 216 format in [RFC3597] 218 o questionRRs - Array of zero or more resource records or rrSet 219 obects in the Question section 221 o answerRRs - Array of zero or more resource records or rrSet obects 222 in the Answer section 224 o authorityRRs - Array of zero or more resource records or rrSet 225 obects in the Authority section 227 o additionalRRs - Array of zero or more resource records or rrSet 228 obects in the Additional section 230 2.2. Resource Record Object Members 232 A resource record is represented as an object with the following 233 members. 235 o NAME - String of the NAME field of the resource record; see 236 Section 2.5 for a description of the contents 238 o compressedNAME - Object that describes the name with two optional 239 values: "isCompressed" (with a value of 0 for no and 1 for yes) 240 and "length" (with an integer giving the length in the message) 242 o TYPE - Integer whose value is 0 to 65535 244 o TYPEname - String whose value is from the IANA RR TYPEs registry, 245 or that has the format in [RFC3597]; this is case-sensitive, so 246 "AAAA" not "aaaa" 248 o CLASS - Integer whose value is 0 to 65535 250 o CLASSname - String whose value is "IN", "CH", "HS", or has the 251 format in [RFC3597] 253 o TTL - Integer whose value is 0 to 4294967295 255 o RDLENGTH - Integer whose value is 0 to 65535. Applications using 256 this format are unlikely to use this value directly, and instead 257 calculate the value from the RDATA. 259 o RDATA - String of the octets of the RDATA field of the resource 260 record. This will most likely be given as RDATAHEX or RDATAB64, 261 not as an ASCII string with \DDD encoding. (This format does not 262 have a way of expressing RDATA by the fields for each DNS record 263 type. Instead, it assumes that a processor of these records 264 probably already knows how to split up an RDATA using master file 265 format.) 267 o rrSet - List of objects which have RDLENGTH and RDATA members. 269 A Question section can be expressed as a resource record. When doing 270 so, the TTL, RDLENGTH, and RDATA members make no sense. 272 2.3. The Message and Its Parts as Octets 274 The following can be members of a message object. These names will 275 most likely be given as "HEX" or "B64" to indicate encoding that is 276 not plain ASCII. All these items are strings. 278 o messageOctets - The octets of the message 280 o headerOctets - The first 12 octets of the message (or fewer, if 281 the message is truncated) 283 o questionOctets - The octets of the Question section 285 o answerOctets - The octets of the Answer section 286 o authorityOctets - The octets of the Authority section 288 o additionalOctets - The octets of the Additional section 290 The following can be a member of a resource record object. 292 o rrOctets - The octets of a particular resource record 294 The items in this section are useful in applications to canonically 295 reproduce what appeared on the wire. For example, an application 296 that is converting wire-format requests and responses might do 297 decompression of names, but the system reading the converted data may 298 want to be sure the decompression was done correctly. Such a system 299 would need to see the part of the message where the decompressed 300 labels resided, such as in one of the items in this section. 302 2.4. Additional Message Object Members 304 The following are members that might appear in a message object: 306 o dateString - The date that the message was sent or received, given 307 as a string in the standard format described in [RFC3339], as 308 refined by Section 3.3 of [RFC4287] 310 o dateSeconds - The date that the message was sent or received, 311 given as the number of seconds since 1970-01-01T00:00Z in UTC 312 time; this number can be fractional 314 o comment - An unstructured comment as a string 316 2.5. Name Fields 318 Names are represented by JSON strings. The rules for how names are 319 encoded are described in Section 1.1. The contents of these fields 320 are always uncompressed, that is after [RFC1035] name compression has 321 been removed. 323 There are three encodings for names: 325 o If the member name does not end in "HEX" or "B64", the value is a 326 domain name encoded as ASCII. Non-ASCII octets in the domain name 327 can be expressed using the decimal escaping ("\DDD"). Periods 328 indicate separation between labels. 330 o If the member name ends in "HEX", the value is the wire format for 331 an entire domain name stored in base16 encoding. 333 o If the member name ends in "B64", the value is the wire format for 334 an entire domain name stored in base64url encoding. 336 3. JSON Format for a Paired DNS Query and Response 338 A paired DNS query and response is represented as an object. Two 339 optional members of this object are names "queryMessage" and 340 "responseMessage", and each has a value that is an message object. 341 This design was chosen (as compared to the more obvious array of two 342 values) so that a paired DNS query and response could be 343 differentiated from a stream of DNS messages whose length happens to 344 be two. 346 4. Streaming DNS Objects 348 Streaming DNS objects is performed using [RFC7464]. 350 5. Examples 352 5.1. Example of the Format of a DNS Query 354 The following is an example of a query for the A record of 355 example.com. 357 { "ID": 19678, "QR": 0, "Opcode": 0, 358 "AA": 0, "TC": 0, "RD": 0, "RA": 0, "AD": 0, "CD": 0, "RCODE": 0, 359 "QDCOUNT": 1, "ANCOUNT": 0, "NSCOUNT": 0, "ARCOUNT": 0, 360 "QNAME": "example.com", "QTYPE": 1, "QCLASS": 1 361 } 363 As stated earlier, all members of an object are optional. This 364 example object could have one or more of the following members as 365 well: 367 "answerRRs": [] 368 "authorityOctetsHEX": "" 369 "comment": "Something pithy goes here" 370 "dateSeconds": 1408504748.657783 371 "headerOctetsHEX": "4CDE00000001000000000000" 372 "QNAMEHEX": "076578616D706C6503636F6D00", 373 "compressedQNAME": { "isCompressed": 0 }, 374 "messageOctetsHEX": 375 "4CDE00000001000000000000076578616D706C6503636F6D0000010001" 376 "messageOctetsB64": "TN4AAAABAAAAAAAAB2V4YW1wbGUDY29tAAABAAE=" 377 "questionOctetsHEX": "076578616D706C6503636F6D0000010001" 378 "questionRRs": [ { "NAMEHEX": "076578616D706C6503636F6D00", 379 "TYPE": 1, "CLASS": 1, "hostNAME" : "example.com." } ] 380 "questionRRs": [ { "NAME": "example.com.", "TYPE": 1, 381 "CLASS": 1, } ] 383 5.2. Example of the Format of a Paired DNS Query and Response 385 The following is a paired DNS query and response for a query for the 386 A record of example.com. 388 { 389 "queryMessage": { "ID": 32784, "QR": 0, "Opcode": 0, "AA": 0, 390 "TC": 0, "RD": 0, "RA": 0, "AD": 0, "CD": 0, 391 "RCODE": 0, "QDCOUNT": 1, "ANCOUNT": 0, 392 "NSCOUNT": 0, "ARCOUNT": 0, 393 "QNAME": "example.com.", 394 "QTYPE": 1, "QCLASS": 1 }, 395 "responseMessage": { "ID": 32784, "QR": 1, "AA": 1, "RCODE": 0, 396 "QDCOUNT": 1, "ANCOUNT": 1, "NSCOUNT": 1, 397 "ARCOUNT": 0, 398 "answerRRs": [ { "NAME": "example.com.", 399 "TYPE": 1, "CLASS": 1, 400 "TTL": 3600, 401 "RDATAHEX": "C0000201" }, 402 { "NAME": "example.com.", 403 "TYPE": 1, "CLASS": 1, 404 "TTL": 3600, 405 "RDATAHEX": "C000AA01" } ], 406 "authorityRRs": [ { "NAME": "ns.example.com.", 407 "TYPE": 1, "CLASS": 1, 408 "TTL": 28800, 409 "RDATAHEX": "CB007181" } ] 410 } 411 } 413 The Answer section could instead be given with an rrSet: 415 "answerRRs": [ { "NAME": "example.com.", 416 "TYPE": 1, "CLASS": 1, 417 "TTL": 3600, 418 "rrSet": [ { "RDATAHEX": "C0000201" }, 419 { "RDATAHEX": "C000AA01" } ] ], 421 6. Local Format Policy 423 Systems using this format in this document will likely have policy 424 about what must be in the objects. Those policies are outside the 425 scope of this document. 427 For example, private DNS systems such as those described in 428 [I-D.dulaunoy-dnsop-passive-dns-cof] covers just DNS responses. Such 429 a system might have a policy that makes QNAME, QTYPE, and answerRRs 430 mandatory. That document also describes two mandatory times that are 431 not in this format, so the policy would possibly also define those 432 members and make them mandatory. The policy could also define 433 additional members that might appear in a record. 435 As another example, a program that uses this format for configuring 436 what a test client sends on the wire might have a policy of "each 437 record object can have as few members as it wants; all unstated 438 members are filled in from previous records". 440 7. IANA Considerations 442 7.1. MIME Type Registration of application/dns+json 443 To: ietf-types@iana.org 444 Subject: Registration of MIME media type application/dns+json 446 MIME media type name: application 448 MIME subtype name: dns+json 450 Required parameters: n/a 452 Optional parameters: n/a 454 Encoding considerations: Encoding considerations are identical to 455 those specified for the "application/json" media type. 457 Security considerations: This document specifies the security 458 considerations for the format. 460 Interoperability considerations: This document specifies format of 461 conforming messages and the interpretation thereof. 463 Published specification: This document. 465 Applications that use this media type: Systems that want to exchange 466 DNS messages. 468 Additional information: 470 Magic number(s): n/a 472 File extension(s): This document uses the mime type to refer to 473 protocol messages and thus does not require a file extension. 475 Macintosh file type code(s): n/a 477 Person & email address to contact for further information: 478 Paul Hoffman, paul.hoffman@icann.org 480 Intended usage: COMMON 482 Restrictions on usage: n/a 484 Author: Paul Hoffman, paul.hoffman@icann.org 486 Change controller: Paul Hoffman, paul.hoffman@icann.org 488 8. Security Considerations 490 As described in Section 1.1, a message object can have inconsistent 491 data, such as a message with an ANCOUNT of 1 but that has either an 492 empty answerRRs array or an answerRRs array that has 2 or more RRs. 493 Other examples of inconsistent data would be resource records whose 494 RDLENGTH does not match the length of the decoded value in the 495 RDATAHEX member, or a record whose various header fields do not match 496 the value in headerOctetsHEX, and so on. A reader of this format 497 must never assume that all of the data in an object are all 498 consistent with each other. 500 Numbers in JSON do not have any bounds checking. Thus, integer 501 values in a record might have invalid values, such as an ID value 502 that is negative, or greater than or equal to 2^16, or has a 503 fractional part. 505 DNS has its own escaping mechanism for non-ASCII octets using "\DDD". 506 Using DNS escaping in this JSON format could lead to security issues 507 if the receiver does not correctly handle the double-escaping. 509 9. Acknowledgements 511 Some of the ideas in this document were inspired by earlier, 512 abandoned work such as ([I-D.daley-dnsxml], 513 [I-D.mohan-dns-query-xml], and [I-D.dulaunoy-dnsop-passive-dns-cof]. 514 The document was also inspired by early ideas from Stephane 515 Bortzmeyer. Many people on the DNSOP WG mailing list contributed 516 very useful ideas (even though this was not a WG work item.) 518 10. References 520 10.1. Normative References 522 [RFC1035] Mockapetris, P., "Domain names - implementation and 523 specification", STD 13, RFC 1035, DOI 10.17487/RFC1035, 524 November 1987, . 526 [RFC3597] Gustafsson, A., "Handling of Unknown DNS Resource Record 527 (RR) Types", RFC 3597, DOI 10.17487/RFC3597, September 528 2003, . 530 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 531 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 532 2014, . 534 [RFC7464] Williams, N., "JavaScript Object Notation (JSON) Text 535 Sequences", RFC 7464, DOI 10.17487/RFC7464, February 2015, 536 . 538 10.2. Informative References 540 [I-D.daley-dnsxml] 541 Daley, J., Morris, S., and J. Dickinson, "dnsxml - A 542 standard XML representation of DNS data", draft-daley- 543 dnsxml-00 (work in progress), July 2013. 545 [I-D.dulaunoy-dnsop-passive-dns-cof] 546 Dulaunoy, A., Kaplan, A., Vixie, P., and H. Stern, 547 "Passive DNS - Common Output Format", draft-dulaunoy- 548 dnsop-passive-dns-cof-01 (work in progress), November 549 2015. 551 [I-D.mohan-dns-query-xml] 552 Parthasarathy, M. and P. Vixie, "Representing DNS messages 553 using XML", draft-mohan-dns-query-xml-00 (work in 554 progress), September 2011. 556 [RFC0020] Cerf, V., "ASCII format for network interchange", STD 80, 557 RFC 20, DOI 10.17487/RFC0020, October 1969, 558 . 560 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 561 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 562 . 564 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 565 Syndication Format", RFC 4287, DOI 10.17487/RFC4287, 566 December 2005, . 568 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 569 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 570 . 572 Author's Address 574 Paul Hoffman 575 ICANN 577 Email: paul.hoffman@icann.org