idnits 2.17.1 draft-hoffman-dns-in-json-12.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 (May 08, 2017) is 2544 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-02 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 May 08, 2017 5 Expires: November 9, 2017 7 Representing DNS Messages in JSON 8 draft-hoffman-dns-in-json-12 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 general 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 November 9, 2017. 36 Copyright Notice 38 Copyright (c) 2017 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 . . . . . . . . . . . . . 6 58 2.3. Specific RDATA Field Members . . . . . . . . . . . . . . 6 59 2.4. The Message and Its Parts as Octets . . . . . . . . . . . 7 60 2.5. Additional Message Object Members . . . . . . . . . . . . 8 61 2.6. Name Fields . . . . . . . . . . . . . . . . . . . . . . . 8 62 3. JSON Format for a Paired DNS Query and Response . . . . . . . 8 63 4. Streaming DNS Objects . . . . . . . . . . . . . . . . . . . . 9 64 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 9 65 5.1. Example of the Format of a DNS Query . . . . . . . . . . 9 66 5.2. Example of the Format of a Paired DNS Query and Response 9 67 6. Local Format Policy . . . . . . . . . . . . . . . . . . . . . 10 68 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 69 7.1. MIME Type Registration of application/dns+json . . . . . 11 70 8. Security Considerations . . . . . . . . . . . . . . . . . . . 13 71 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 13 72 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 73 10.1. Normative References . . . . . . . . . . . . . . . . . . 13 74 10.2. Informative References . . . . . . . . . . . . . . . . . 14 75 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 14 77 1. Introduction 79 The DNS message format is defined in [RFC1035]. DNS queries and DNS 80 responses have exactly the same structure. Many of the field names 81 and data type names given in [RFC1035] are commonly used in 82 discussions of DNS. For example, it is common to hear things like 83 "the query had a QNAME of 'example.com'" or "the RDATA has a simple 84 structure". 86 There are hundreds of data interchange formats for serializing 87 structured data. Currently, JSON [RFC7159] is quite popular for many 88 types of data, particularly data that has named sub-fields and 89 optional parts. 91 This document uses JSON to describe DNS messages. It also defines 92 how to describe a paired DNS query and response, and how to stream 93 DNS objects. 95 1.1. Design of the Format 97 There are many ways to design a data format. This document uses a 98 specific design methodology based on the DNS format. 100 o The format is based on JSON objects in order to allow a writer to 101 include or exclude parts of the format at will. No object members 102 are ever required. 104 o This format is purposely overly-general. A protocols or 105 application that uses this format is expected to use only a subset 106 of the items defined here, and is expected to define its own 107 profile from this format. 109 o The format allows that transform through JSON would permit 110 recreation of the wire content of the message. 112 o All members whose values that are always 16 bits or shorter are 113 represented by JSON integers. One-bit values are represented as 114 JSON booleans. 116 o The encoding for the DNS object is ASCII as described in 117 [RFC0020]. This is done to prevent an attempt to use a different 118 encoding such as UTF-8 for octets in names or data. 120 o Names of items that have string values can have "HEX" appended to 121 them to indicate a non-ASCII encoding of the value. Names that 122 end in "HEX" have values stored in base16 encoding (hex with 123 uppercase letters) defined in [RFC4648]. This is particularly 124 useful for RDATA that is binary. 126 o All field names used in [RFC1035] are used in this format as-is, 127 including their capitalization. Names not defined in [RFC1035] 128 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 It is acceptable that there are multiple ways to represent the 138 same data. This is done to allow application designers to choose 139 what fields are best for them, and to even allow them to allow 140 multiple representations. That is, there is no "better" way to 141 represent DNS data, so this design doesn't prefer specific 142 representations. 144 o The design explicitly allows for the description of malformed DNS 145 messages. This is important for systems that are logging messages 146 seen on the wire, particularly messages that might be used as part 147 of an attack. A few examples of malformed DNS messages include: 149 * an RR that has an RDLENGTH of 4 but an RDATA whose length is 150 longer than 4 (if it is the last RR in a message) 152 * a DNS message whose QDCOUNT is 0 154 * a DNS message whose ANCOUNT is large but there are insufficient 155 bytes after the header 157 * a DNS message whose length is less than 12 octets, meaning it 158 doesn't even have a full header 160 o An object in this format can have zero or more of the members 161 defined here; that is, no members are required by the format 162 itself. Instead, profiles that use this format might have 163 requirements for mandatory members, optional members, and 164 prohibited members from the format. Also, this format does not 165 prohibit members that are not defined in this format; profiles of 166 the format are free to add new members in the profile. 168 o This document defines DNS messages, not the zone files described 169 in [RFC1035]. A different specification could be written to 170 extend it to represent zone files. Note that DNS zone files allow 171 escaping of octet values using "\DDD" notation, but this 172 specification does not allow that; when encoding from a zone file 173 to this JSON format, you need to do a conversion for many types of 174 values. 176 2. JSON Format for DNS Messages 178 The following gives all of the members defined for a DNS message. It 179 is organized approximately by levels of the DNS message. 181 2.1. Message Object Members 183 o ID - Integer whose value is 0 to 65535 185 o QR - Boolean 187 o Opcode - Integer whose value is 0 to 15 189 o AA - Boolean 191 o TC - Boolean 192 o RD - Boolean 194 o RA - Boolean 196 o AD - Boolean 198 o CD - Boolean 200 o RCODE - Integer whose value is 0 to 15 202 o QDCOUNT - Integer whose value is 0 to 65535 204 o ANCOUNT - Integer whose value is 0 to 65535 206 o NSCOUNT - Integer whose value is 0 to 65535 208 o ARCOUNT - Integer whose value is 0 to 65535 210 o QNAME - String of the name of the first Question section of the 211 message; see Section 2.6 for a desciption of the contents 213 o compressedQNAME - Object that describes the name with two optional 214 values: "isCompressed" (with a value of 0 for no and 1 for yes) 215 and "length" (with an integer giving the length in the message) 217 o QTYPE - Integer whose value is 0 to 65535, of the QTYPE of the 218 first Question section of the message 220 o QTYPEname - String whose value is from the IANA RR TYPEs registry, 221 or that has the format in [RFC3597]; this is case-sensitive, so 222 "AAAA" not "aaaa" 224 o QCLASS - Integer whose value is 0 to 65535, of the QCLASS of the 225 first Question section of the message 227 o QCLASSname - String whose value is "IN", "CH", "HS", or has the 228 format in [RFC3597] 230 o questionRRs - Array of zero or more resource records or rrSet 231 obects in the Question section 233 o answerRRs - Array of zero or more resource records or rrSet obects 234 in the Answer section 236 o authorityRRs - Array of zero or more resource records or rrSet 237 obects in the Authority section 239 o additionalRRs - Array of zero or more resource records or rrSet 240 obects in the Additional section 242 2.2. Resource Record Object Members 244 A resource record is represented as an object with the following 245 members. 247 o NAME - String of the NAME field of the resource record; see 248 Section 2.6 for a description of the contents 250 o compressedNAME - Object that describes the name with two optional 251 values: "isCompressed" (with a value of 0 for no and 1 for yes) 252 and "length" (with an integer giving the length in the message) 254 o TYPE - Integer whose value is 0 to 65535 256 o TYPEname - String whose value is from the IANA RR TYPEs registry, 257 or that has the format in [RFC3597]; this is case-sensitive, so 258 "AAAA" not "aaaa" 260 o CLASS - Integer whose value is 0 to 65535 262 o CLASSname - String whose value is "IN", "CH", "HS", or has the 263 format in [RFC3597] 265 o TTL - Integer whose value is 0 to 4294967295 267 o RDLENGTH - Integer whose value is 0 to 65535. Applications using 268 this format are unlikely to use this value directly, and instead 269 calculate the value from the RDATA. 271 o RDATAHEX - Hex-encoded string (base16 encoding described in 272 [RFC4648]) of the octets of the RDATA field of the resource 273 record. The data in some common RDATA fields are also described 274 in their own members; see Section 2.3. 276 o rrSet - List of objects which have RDLENGTH and RDATA members. 278 A Question section can be expressed as a resource record. When doing 279 so, the TTL, RDLENGTH, and RDATA members make no sense. 281 2.3. Specific RDATA Field Members 283 The following are common RDATA types and how to specify them as JSON 284 members. The name of the member contains the name of the RDATA type. 285 The data type for each of these members is a string. Each name is 286 prefaced with "rdata" to prevent a name collision with fields that 287 might later be defined that have the same name as the raw type name. 289 o rdataA - IPv4 address, such as "192.168.33.44" 291 o rdataAAAA - IPv6 address, such as "fe80::a65e:60ff:fed6:8aaf" 293 o rdataCNAME - A domain name 295 o rdataDNAME - A domain name 297 o rdataNS - A domain name 299 o rdataPTR - A domain name 301 o rdataTXT - A text value 303 In addition, the following members each has a value that is a space- 304 separated string that matches the display format definition in the 305 RFC that defines that RDATA type. It is not expected that every 306 receiving application will know how to parse these values. 308 rdataCDNSKEY, rdataCDS, rdataCSYNC, rdataDNSKEY, rdataHIP, 309 rdataIPSECKEY, rdataKEY, rdataMX, rdataNSEC, rdataNSEC3, 310 rdataNSEC3PARAM, rdataOPENPGPKEY, rdataRRSIG, rdataSMIMEA, rdataSPF, 311 rdataSRV, rdataSSHFP, rdataTLSA 313 2.4. The Message and Its Parts as Octets 315 The following can be members of a message object. These members are 316 all encoded in base16 encoding described in [RFC4648]. All these 317 items are strings. 319 o messageOctetsHEX - The octets of the message 321 o headerOctetsHEX - The first 12 octets of the message (or fewer, if 322 the message is truncated) 324 o questionOctetsHEX - The octets of the Question section 326 o answerOctetsHEX - The octets of the Answer section 328 o authorityOctetsHEX - The octets of the Authority section 330 o additionalOctetsHEX - The octets of the Additional section 332 The following can be a member of a resource record object. 334 o rrOctetsHEX - The octets of a particular resource record 336 The items in this section are useful in applications to canonically 337 reproduce what appeared on the wire. For example, an application 338 that is converting wire-format requests and responses might do 339 decompression of names, but the system reading the converted data may 340 want to be sure the decompression was done correctly. Such a system 341 would need to see the part of the message where the decompressed 342 labels resided, such as in one of the items in this section. 344 2.5. Additional Message Object Members 346 The following are members that might appear in a message object: 348 o dateString - The date that the message was sent or received, given 349 as a string in the standard format described in [RFC3339], as 350 refined by Section 3.3 of [RFC4287] 352 o dateSeconds - The date that the message was sent or received, 353 given as the number of seconds since 1970-01-01T00:00Z in UTC 354 time; this number can be fractional 356 o comment - An unstructured comment as a string 358 2.6. Name Fields 360 Names are represented by JSON strings. The rules for how names are 361 encoded are described in Section 1.1. The contents of these fields 362 are always uncompressed, that is after [RFC1035] name compression has 363 been removed. 365 There are two encodings for names: 367 o If the member name does not end in "HEX", the value is a domain 368 name encoded as ASCII. Non-ASCII octets in the domain name are 369 expressed using JSON's escaping rules. Periods indicate 370 separation between labels. 372 o If the member name ends in "HEX", the value is the wire format for 373 an entire domain name stored in base16 encoding described in 374 [RFC4648]. 376 3. JSON Format for a Paired DNS Query and Response 378 A paired DNS query and response is represented as an object. Two 379 optional members of this object are names "queryMessage" and 380 "responseMessage", and each has a value that is a message object. 381 This design was chosen (as compared to the more obvious array of two 382 values) so that a paired DNS query and response could be 383 differentiated from a stream of DNS messages whose length happens to 384 be two. 386 4. Streaming DNS Objects 388 Streaming DNS objects is performed using [RFC7464]. 390 5. Examples 392 5.1. Example of the Format of a DNS Query 394 The following is an example of a query for the A record of 395 example.com. 397 { "ID": 19678, "QR": 0, "Opcode": 0, 398 "AA": 0, "TC": 0, "RD": 0, "RA": 0, "AD": 0, "CD": 0, "RCODE": 0, 399 "QDCOUNT": 1, "ANCOUNT": 0, "NSCOUNT": 0, "ARCOUNT": 0, 400 "QNAME": "example.com", "QTYPE": 1, "QCLASS": 1 401 } 403 As stated earlier, all members of an object are optional. This 404 example object could have one or more of the following members as 405 well: 407 "answerRRs": [] 408 "authorityOctetsHEX": "" 409 "comment": "Something pithy goes here" 410 "dateSeconds": 1408504748.657783 411 "headerOctetsHEX": "4CDE00000001000000000000" 412 "QNAMEHEX": "076578616D706C6503636F6D00", 413 "compressedQNAME": { "isCompressed": 0 }, 414 "messageOctetsHEX": 415 "4CDE00000001000000000000076578616D706C6503636F6D0000010001" 416 "questionOctetsHEX": "076578616D706C6503636F6D0000010001" 417 "questionRRs": [ { "NAMEHEX": "076578616D706C6503636F6D00", 418 "TYPE": 1, "CLASS": 1, "hostNAME" : "example.com." } ] 419 "questionRRs": [ { "NAME": "example.com.", "TYPE": 1, 420 "CLASS": 1, } ] 422 (Note that this is an incomplete list of what else could be in the 423 object.) 425 5.2. Example of the Format of a Paired DNS Query and Response 427 The following is a paired DNS query and response for a query for the 428 A record of example.com. 430 { 431 "queryMessage": { "ID": 32784, "QR": 0, "Opcode": 0, "AA": 0, 432 "TC": 0, "RD": 0, "RA": 0, "AD": 0, "CD": 0, 433 "RCODE": 0, "QDCOUNT": 1, "ANCOUNT": 0, 434 "NSCOUNT": 0, "ARCOUNT": 0, 435 "QNAME": "example.com.", 436 "QTYPE": 1, "QCLASS": 1 }, 437 "responseMessage": { "ID": 32784, "QR": 1, "AA": 1, "RCODE": 0, 438 "QDCOUNT": 1, "ANCOUNT": 1, "NSCOUNT": 1, 439 "ARCOUNT": 0, 440 "answerRRs": [ { "NAME": "example.com.", 441 "TYPE": 1, "CLASS": 1, 442 "TTL": 3600, 443 "RDATAHEX": "C0000201" }, 444 { "NAME": "example.com.", 445 "TYPE": 1, "CLASS": 1, 446 "TTL": 3600, 447 "RDATAHEX": "C000AA01" } ], 448 "authorityRRs": [ { "NAME": "ns.example.com.", 449 "TYPE": 1, "CLASS": 1, 450 "TTL": 28800, 451 "RDATAHEX": "CB007181" } ] 452 } 453 } 455 The Answer section could instead be given with an rrSet: 457 "answerRRs": [ { "NAME": "example.com.", 458 "TYPE": 1, "CLASS": 1, 459 "TTL": 3600, 460 "rrSet": [ { "RDATAHEX": "C0000201" }, 461 { "RDATAHEX": "C000AA01" } ] ], 463 (Note that this is an incomplete list of what else could be in the 464 Answer section.) 466 6. Local Format Policy 468 Systems using this format in this document will likely have policy 469 about what must be in the objects. Those policies are outside the 470 scope of this document. 472 For example, private DNS systems such as those described in 473 [I-D.dulaunoy-dnsop-passive-dns-cof] covers just DNS responses. Such 474 a system might have a policy that makes QNAME, QTYPE, and answerRRs 475 mandatory. That document also describes two mandatory times that are 476 not in this format, so the policy would possibly also define those 477 members and make them mandatory. The policy could also define 478 additional members that might appear in a record. 480 As another example, a program that uses this format for configuring 481 what a test client sends on the wire might have a policy of "each 482 record object can have as few members as it wants; all unstated 483 members are filled in from previous records". 485 7. IANA Considerations 487 7.1. MIME Type Registration of application/dns+json 488 To: ietf-types@iana.org 489 Subject: Registration of MIME media type application/dns+json 491 MIME media type name: application 493 MIME subtype name: dns+json 495 Required parameters: n/a 497 Optional parameters: n/a 499 Encoding considerations: Encoding considerations are identical to 500 those specified for the "application/json" media type. 502 Security considerations: This document specifies the security 503 considerations for the format. 505 Interoperability considerations: This document specifies format of 506 conforming messages and the interpretation thereof. 508 Published specification: This document. 510 Applications that use this media type: Systems that want to exchange 511 DNS messages. 513 Additional information: 515 Magic number(s): n/a 517 File extension(s): This document uses the mime type to refer to 518 protocol messages and thus does not require a file extension. 520 Macintosh file type code(s): n/a 522 Person & email address to contact for further information: 523 Paul Hoffman, paul.hoffman@icann.org 525 Intended usage: COMMON 527 Restrictions on usage: n/a 529 Author: Paul Hoffman, paul.hoffman@icann.org 531 Change controller: Paul Hoffman, paul.hoffman@icann.org 533 8. Security Considerations 535 As described in Section 1.1, a message object can have inconsistent 536 data, such as a message with an ANCOUNT of 1 but that has either an 537 empty answerRRs array or an answerRRs array that has 2 or more RRs. 538 Other examples of inconsistent data would be resource records whose 539 RDLENGTH does not match the length of the decoded value in the 540 RDATAHEX member, or a record whose various header fields do not match 541 the value in headerOctetsHEX, and so on. A reader of this format 542 must never assume that all of the data in an object are all 543 consistent with each other. 545 Numbers in JSON do not have any bounds checking. Thus, integer 546 values in a record might have invalid values, such as an ID value 547 that is negative, or greater than or equal to 2^16, or has a 548 fractional part. 550 9. Acknowledgements 552 Some of the ideas in this document were inspired by earlier, 553 abandoned work such as ([I-D.daley-dnsxml], 554 [I-D.mohan-dns-query-xml], and [I-D.dulaunoy-dnsop-passive-dns-cof]. 555 The document was also inspired by early ideas from Stephane 556 Bortzmeyer. Many people on the DNSOP WG mailing list contributed 557 very useful ideas (even though this was not a WG work item). Many 558 people on the dnsoverhttp mailing list contributed very useful ideas 559 (even though this list is not a WG). 561 10. References 563 10.1. Normative References 565 [RFC1035] Mockapetris, P., "Domain names - implementation and 566 specification", STD 13, RFC 1035, DOI 10.17487/RFC1035, 567 November 1987, . 569 [RFC3597] Gustafsson, A., "Handling of Unknown DNS Resource Record 570 (RR) Types", RFC 3597, DOI 10.17487/RFC3597, September 571 2003, . 573 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 574 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 575 2014, . 577 [RFC7464] Williams, N., "JavaScript Object Notation (JSON) Text 578 Sequences", RFC 7464, DOI 10.17487/RFC7464, February 2015, 579 . 581 10.2. Informative References 583 [I-D.daley-dnsxml] 584 Daley, J., Morris, S., and J. Dickinson, "dnsxml - A 585 standard XML representation of DNS data", draft-daley- 586 dnsxml-00 (work in progress), July 2013. 588 [I-D.dulaunoy-dnsop-passive-dns-cof] 589 Dulaunoy, A., Kaplan, A., Vixie, P., and H. Stern, 590 "Passive DNS - Common Output Format", draft-dulaunoy- 591 dnsop-passive-dns-cof-02 (work in progress), October 2016. 593 [I-D.mohan-dns-query-xml] 594 Parthasarathy, M. and P. Vixie, "Representing DNS messages 595 using XML", draft-mohan-dns-query-xml-00 (work in 596 progress), September 2011. 598 [RFC0020] Cerf, V., "ASCII format for network interchange", STD 80, 599 RFC 20, DOI 10.17487/RFC0020, October 1969, 600 . 602 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 603 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 604 . 606 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 607 Syndication Format", RFC 4287, DOI 10.17487/RFC4287, 608 December 2005, . 610 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 611 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 612 . 614 Author's Address 616 Paul Hoffman 617 ICANN 619 Email: paul.hoffman@icann.org