idnits 2.17.1 draft-hoffman-dns-in-json-13.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 (October 21, 2017) is 2371 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-03 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 October 21, 2017 5 Expires: April 24, 2018 7 Representing DNS Messages in JSON 8 draft-hoffman-dns-in-json-13 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. Specific 18 profiles of this document can be described in other documents for 19 specific applications and usage scenarios. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on April 24, 2018. 38 Copyright Notice 40 Copyright (c) 2017 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 56 1.1. Design of the Format . . . . . . . . . . . . . . . . . . 3 57 2. JSON Format for DNS Messages . . . . . . . . . . . . . . . . 4 58 2.1. Message Object Members . . . . . . . . . . . . . . . . . 4 59 2.2. Resource Record Object Members . . . . . . . . . . . . . 6 60 2.3. Specific RDATA Field Members . . . . . . . . . . . . . . 6 61 2.4. The Message and Its Parts as Octets . . . . . . . . . . . 7 62 2.5. Additional Message Object Members . . . . . . . . . . . . 8 63 2.6. Name Fields . . . . . . . . . . . . . . . . . . . . . . . 8 64 3. JSON Format for a Paired DNS Query and Response . . . . . . . 8 65 4. Streaming DNS Objects . . . . . . . . . . . . . . . . . . . . 9 66 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 9 67 5.1. Example of the Format of a DNS Query . . . . . . . . . . 9 68 5.2. Example of the Format of a Paired DNS Query and Response 9 69 6. Local Format Policy . . . . . . . . . . . . . . . . . . . . . 10 70 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 71 7.1. MIME Type Registration of application/dns+json . . . . . 11 72 8. Security Considerations . . . . . . . . . . . . . . . . . . . 13 73 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 13 74 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 75 10.1. Normative References . . . . . . . . . . . . . . . . . . 13 76 10.2. Informative References . . . . . . . . . . . . . . . . . 14 77 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 14 79 1. Introduction 81 The DNS message format is defined in [RFC1035]. DNS queries and DNS 82 responses have exactly the same structure. Many of the field names 83 and data type names given in [RFC1035] are commonly used in 84 discussions of DNS. For example, it is common to hear things like 85 "the query had a QNAME of 'example.com'" or "the RDATA has a simple 86 structure". 88 There are hundreds of data interchange formats for serializing 89 structured data. Currently, JSON [RFC7159] is quite popular for many 90 types of data, particularly data that has named sub-fields and 91 optional parts. 93 This document uses JSON to describe DNS messages. It also defines 94 how to describe a paired DNS query and response, and how to stream 95 DNS objects. 97 1.1. Design of the Format 99 There are many ways to design a data format. This document uses a 100 specific design methodology based on the DNS format. 102 o The format is based on JSON objects in order to allow a writer to 103 include or exclude parts of the format at will. No object members 104 are ever required. 106 o This format is purposely overly-general. A protocol or 107 application that uses this format is expected to use only a subset 108 of the items defined here, and is expected to define its own 109 profile from this format. 111 o The format allows that transform through JSON would permit 112 recreation of the wire content of the message. 114 o All members whose values that are always 16 bits or shorter are 115 represented by JSON integers. One-bit values are represented as 116 JSON booleans. 118 o The encoding for the DNS object is ASCII as described in 119 [RFC0020]. This is done to prevent an attempt to use a different 120 encoding such as UTF-8 for octets in names or data. 122 o Names of items that have string values can have "HEX" appended to 123 them to indicate a non-ASCII encoding of the value. Names that 124 end in "HEX" have values stored in base16 encoding (hex with 125 uppercase letters) defined in [RFC4648]. This is particularly 126 useful for RDATA that is binary. 128 o All field names used in [RFC1035] are used in this format as-is, 129 including their capitalization. Names not defined in [RFC1035] 130 generally use "camel case". 132 o The same data may be represented in multiple object members 133 multiple times. For example, there is a member for the octets of 134 the DNS message header, and there are members for each named part 135 of the header. A message object can thus inadvertently have 136 inconsistent data, such as a header member whose value does not 137 match the value of the first bits in the entire message member. 139 o It is acceptable that there are multiple ways to represent the 140 same data. This is done to allow application designers to choose 141 what fields are best for them, and to even allow them to allow 142 multiple representations. That is, there is no "better" way to 143 represent DNS data, so this design doesn't prefer specific 144 representations. 146 o The design explicitly allows for the description of malformed DNS 147 messages. This is important for systems that are logging messages 148 seen on the wire, particularly messages that might be used as part 149 of an attack. A few examples of malformed DNS messages include: 151 * an RR that has an RDLENGTH of 4 but an RDATA whose length is 152 longer than 4 (if it is the last RR in a message) 154 * a DNS message whose QDCOUNT is 0 156 * a DNS message whose ANCOUNT is large but there are insufficient 157 bytes after the header 159 * a DNS message whose length is less than 12 octets, meaning it 160 doesn't even have a full header 162 o An object in this format can have zero or more of the members 163 defined here; that is, no members are required by the format 164 itself. Instead, profiles that use this format might have 165 requirements for mandatory members, optional members, and 166 prohibited members from the format. Also, this format does not 167 prohibit members that are not defined in this format; profiles of 168 the format are free to add new members in the profile. 170 o This document defines DNS messages, not the zone files described 171 in [RFC1035]. A different specification could be written to 172 extend it to represent zone files. Note that DNS zone files allow 173 escaping of octet values using "\DDD" notation, but this 174 specification does not allow that; when encoding from a zone file 175 to this JSON format, you need to do a conversion for many types of 176 values. 178 2. JSON Format for DNS Messages 180 The following gives all of the members defined for a DNS message. It 181 is organized approximately by levels of the DNS message. 183 2.1. Message Object Members 185 o ID - Integer whose value is 0 to 65535 187 o QR - Boolean 189 o Opcode - Integer whose value is 0 to 15 191 o AA - Boolean 193 o TC - Boolean 194 o RD - Boolean 196 o RA - Boolean 198 o AD - Boolean 200 o CD - Boolean 202 o RCODE - Integer whose value is 0 to 15 204 o QDCOUNT - Integer whose value is 0 to 65535 206 o ANCOUNT - Integer whose value is 0 to 65535 208 o NSCOUNT - Integer whose value is 0 to 65535 210 o ARCOUNT - Integer whose value is 0 to 65535 212 o QNAME - String of the name of the first Question section of the 213 message; see Section 2.6 for a desciption of the contents 215 o compressedQNAME - Object that describes the name with two optional 216 values: "isCompressed" (with a value of 0 for no and 1 for yes) 217 and "length" (with an integer giving the length in the message) 219 o QTYPE - Integer whose value is 0 to 65535, of the QTYPE of the 220 first Question section of the message 222 o QTYPEname - String whose value is from the IANA RR TYPEs registry, 223 or that has the format in [RFC3597]; this is case-sensitive, so 224 "AAAA" not "aaaa" 226 o QCLASS - Integer whose value is 0 to 65535, of the QCLASS of the 227 first Question section of the message 229 o QCLASSname - String whose value is "IN", "CH", "HS", or has the 230 format in [RFC3597] 232 o questionRRs - Array of zero or more resource records or rrSet 233 obects in the Question section 235 o answerRRs - Array of zero or more resource records or rrSet obects 236 in the Answer section 238 o authorityRRs - Array of zero or more resource records or rrSet 239 obects in the Authority section 241 o additionalRRs - Array of zero or more resource records or rrSet 242 obects in the Additional section 244 2.2. Resource Record Object Members 246 A resource record is represented as an object with the following 247 members. 249 o NAME - String of the NAME field of the resource record; see 250 Section 2.6 for a description of the contents 252 o compressedNAME - Object that describes the name with two optional 253 values: "isCompressed" (with a value of 0 for no and 1 for yes) 254 and "length" (with an integer giving the length in the message) 256 o TYPE - Integer whose value is 0 to 65535 258 o TYPEname - String whose value is from the IANA RR TYPEs registry, 259 or that has the format in [RFC3597]; this is case-sensitive, so 260 "AAAA" not "aaaa" 262 o CLASS - Integer whose value is 0 to 65535 264 o CLASSname - String whose value is "IN", "CH", "HS", or has the 265 format in [RFC3597] 267 o TTL - Integer whose value is 0 to 4294967295 269 o RDLENGTH - Integer whose value is 0 to 65535. Applications using 270 this format are unlikely to use this value directly, and instead 271 calculate the value from the RDATA. 273 o RDATAHEX - Hex-encoded string (base16 encoding described in 274 [RFC4648]) of the octets of the RDATA field of the resource 275 record. The data in some common RDATA fields are also described 276 in their own members; see Section 2.3. 278 o rrSet - List of objects which have RDLENGTH and RDATA members. 280 A Question section can be expressed as a resource record. When doing 281 so, the TTL, RDLENGTH, and RDATA members make no sense. 283 2.3. Specific RDATA Field Members 285 The following are common RDATA types and how to specify them as JSON 286 members. The name of the member contains the name of the RDATA type. 287 The data type for each of these members is a string. Each name is 288 prefaced with "rdata" to prevent a name collision with fields that 289 might later be defined that have the same name as the raw type name. 291 o rdataA - IPv4 address, such as "192.168.33.44" 293 o rdataAAAA - IPv6 address, such as "fe80::a65e:60ff:fed6:8aaf" 295 o rdataCNAME - A domain name 297 o rdataDNAME - A domain name 299 o rdataNS - A domain name 301 o rdataPTR - A domain name 303 o rdataTXT - A text value 305 In addition, the following members each has a value that is a space- 306 separated string that matches the display format definition in the 307 RFC that defines that RDATA type. It is not expected that every 308 receiving application will know how to parse these values. 310 rdataCDNSKEY, rdataCDS, rdataCSYNC, rdataDNSKEY, rdataHIP, 311 rdataIPSECKEY, rdataKEY, rdataMX, rdataNSEC, rdataNSEC3, 312 rdataNSEC3PARAM, rdataOPENPGPKEY, rdataRRSIG, rdataSMIMEA, rdataSPF, 313 rdataSRV, rdataSSHFP, rdataTLSA 315 2.4. The Message and Its Parts as Octets 317 The following can be members of a message object. These members are 318 all encoded in base16 encoding described in [RFC4648]. All these 319 items are strings. 321 o messageOctetsHEX - The octets of the message 323 o headerOctetsHEX - The first 12 octets of the message (or fewer, if 324 the message is truncated) 326 o questionOctetsHEX - The octets of the Question section 328 o answerOctetsHEX - The octets of the Answer section 330 o authorityOctetsHEX - The octets of the Authority section 332 o additionalOctetsHEX - The octets of the Additional section 334 The following can be a member of a resource record object. 336 o rrOctetsHEX - The octets of a particular resource record 338 The items in this section are useful in applications to canonically 339 reproduce what appeared on the wire. For example, an application 340 that is converting wire-format requests and responses might do 341 decompression of names, but the system reading the converted data may 342 want to be sure the decompression was done correctly. Such a system 343 would need to see the part of the message where the decompressed 344 labels resided, such as in one of the items in this section. 346 2.5. Additional Message Object Members 348 The following are members that might appear in a message object: 350 o dateString - The date that the message was sent or received, given 351 as a string in the standard format described in [RFC3339], as 352 refined by Section 3.3 of [RFC4287] 354 o dateSeconds - The date that the message was sent or received, 355 given as the number of seconds since 1970-01-01T00:00Z in UTC 356 time; this number can be fractional 358 o comment - An unstructured comment as a string 360 2.6. Name Fields 362 Names are represented by JSON strings. The rules for how names are 363 encoded are described in Section 1.1. The contents of these fields 364 are always uncompressed, that is after [RFC1035] name compression has 365 been removed. 367 There are two encodings for names: 369 o If the member name does not end in "HEX", the value is a domain 370 name encoded as ASCII. Non-ASCII octets in the domain name are 371 expressed using JSON's escaping rules. Periods indicate 372 separation between labels. 374 o If the member name ends in "HEX", the value is the wire format for 375 an entire domain name stored in base16 encoding described in 376 [RFC4648]. 378 3. JSON Format for a Paired DNS Query and Response 380 A paired DNS query and response is represented as an object. Two 381 optional members of this object are names "queryMessage" and 382 "responseMessage", and each has a value that is a message object. 383 This design was chosen (as compared to the more obvious array of two 384 values) so that a paired DNS query and response could be 385 differentiated from a stream of DNS messages whose length happens to 386 be two. 388 4. Streaming DNS Objects 390 Streaming DNS objects is performed using [RFC7464]. 392 5. Examples 394 5.1. Example of the Format of a DNS Query 396 The following is an example of a query for the A record of 397 example.com. 399 { "ID": 19678, "QR": 0, "Opcode": 0, 400 "AA": 0, "TC": 0, "RD": 0, "RA": 0, "AD": 0, "CD": 0, "RCODE": 0, 401 "QDCOUNT": 1, "ANCOUNT": 0, "NSCOUNT": 0, "ARCOUNT": 0, 402 "QNAME": "example.com", "QTYPE": 1, "QCLASS": 1 403 } 405 As stated earlier, all members of an object are optional. This 406 example object could have one or more of the following members as 407 well: 409 "answerRRs": [] 410 "authorityOctetsHEX": "" 411 "comment": "Something pithy goes here" 412 "dateSeconds": 1408504748.657783 413 "headerOctetsHEX": "4CDE00000001000000000000" 414 "QNAMEHEX": "076578616D706C6503636F6D00", 415 "compressedQNAME": { "isCompressed": 0 }, 416 "messageOctetsHEX": 417 "4CDE00000001000000000000076578616D706C6503636F6D0000010001" 418 "questionOctetsHEX": "076578616D706C6503636F6D0000010001" 419 "questionRRs": [ { "NAMEHEX": "076578616D706C6503636F6D00", 420 "TYPE": 1, "CLASS": 1, "hostNAME" : "example.com." } ] 421 "questionRRs": [ { "NAME": "example.com.", "TYPE": 1, 422 "CLASS": 1, } ] 424 (Note that this is an incomplete list of what else could be in the 425 object.) 427 5.2. Example of the Format of a Paired DNS Query and Response 429 The following is a paired DNS query and response for a query for the 430 A record of example.com. 432 { 433 "queryMessage": { "ID": 32784, "QR": 0, "Opcode": 0, "AA": 0, 434 "TC": 0, "RD": 0, "RA": 0, "AD": 0, "CD": 0, 435 "RCODE": 0, "QDCOUNT": 1, "ANCOUNT": 0, 436 "NSCOUNT": 0, "ARCOUNT": 0, 437 "QNAME": "example.com.", 438 "QTYPE": 1, "QCLASS": 1 }, 439 "responseMessage": { "ID": 32784, "QR": 1, "AA": 1, "RCODE": 0, 440 "QDCOUNT": 1, "ANCOUNT": 1, "NSCOUNT": 1, 441 "ARCOUNT": 0, 442 "answerRRs": [ { "NAME": "example.com.", 443 "TYPE": 1, "CLASS": 1, 444 "TTL": 3600, 445 "RDATAHEX": "C0000201" }, 446 { "NAME": "example.com.", 447 "TYPE": 1, "CLASS": 1, 448 "TTL": 3600, 449 "RDATAHEX": "C000AA01" } ], 450 "authorityRRs": [ { "NAME": "ns.example.com.", 451 "TYPE": 1, "CLASS": 1, 452 "TTL": 28800, 453 "RDATAHEX": "CB007181" } ] 454 } 455 } 457 The Answer section could instead be given with an rrSet: 459 "answerRRs": [ { "NAME": "example.com.", 460 "TYPE": 1, "CLASS": 1, 461 "TTL": 3600, 462 "rrSet": [ { "RDATAHEX": "C0000201" }, 463 { "RDATAHEX": "C000AA01" } ] } ], 465 (Note that this is an incomplete list of what else could be in the 466 Answer section.) 468 6. Local Format Policy 470 Systems using this format in this document will likely have policy 471 about what must be in the objects. Those policies are outside the 472 scope of this document. 474 For example, private DNS systems such as those described in 475 [I-D.dulaunoy-dnsop-passive-dns-cof] covers just DNS responses. Such 476 a system might have a policy that makes QNAME, QTYPE, and answerRRs 477 mandatory. That document also describes two mandatory times that are 478 not in this format, so the policy would possibly also define those 479 members and make them mandatory. The policy could also define 480 additional members that might appear in a record. 482 As another example, a program that uses this format for configuring 483 what a test client sends on the wire might have a policy of "each 484 record object can have as few members as it wants; all unstated 485 members are filled in from previous records". 487 7. IANA Considerations 489 7.1. MIME Type Registration of application/dns+json 490 To: ietf-types@iana.org 491 Subject: Registration of MIME media type application/dns+json 493 MIME media type name: application 495 MIME subtype name: dns+json 497 Required parameters: n/a 499 Optional parameters: n/a 501 Encoding considerations: Encoding considerations are identical to 502 those specified for the "application/json" media type. 504 Security considerations: This document specifies the security 505 considerations for the format. 507 Interoperability considerations: This document specifies format of 508 conforming messages and the interpretation thereof. 510 Published specification: This document. 512 Applications that use this media type: Systems that want to exchange 513 DNS messages. 515 Additional information: 517 Magic number(s): n/a 519 File extension(s): This document uses the mime type to refer to 520 protocol messages and thus does not require a file extension. 522 Macintosh file type code(s): n/a 524 Person & email address to contact for further information: 525 Paul Hoffman, paul.hoffman@icann.org 527 Intended usage: COMMON 529 Restrictions on usage: n/a 531 Author: Paul Hoffman, paul.hoffman@icann.org 533 Change controller: Paul Hoffman, paul.hoffman@icann.org 535 8. Security Considerations 537 As described in Section 1.1, a message object can have inconsistent 538 data, such as a message with an ANCOUNT of 1 but that has either an 539 empty answerRRs array or an answerRRs array that has 2 or more RRs. 540 Other examples of inconsistent data would be resource records whose 541 RDLENGTH does not match the length of the decoded value in the 542 RDATAHEX member, or a record whose various header fields do not match 543 the value in headerOctetsHEX, and so on. A reader of this format 544 must never assume that all of the data in an object are all 545 consistent with each other. 547 Numbers in JSON do not have any bounds checking. Thus, integer 548 values in a record might have invalid values, such as an ID value 549 that is negative, or greater than or equal to 2^16, or has a 550 fractional part. 552 9. Acknowledgements 554 Some of the ideas in this document were inspired by earlier, 555 abandoned work such as ([I-D.daley-dnsxml], 556 [I-D.mohan-dns-query-xml], and [I-D.dulaunoy-dnsop-passive-dns-cof]. 557 The document was also inspired by early ideas from Stephane 558 Bortzmeyer. Many people on the DNSOP WG mailing list contributed 559 very useful ideas (even though this was not a WG work item). Many 560 people on the dnsoverhttp mailing list also contributed very useful 561 ideas (even though this list is not a WG and this work might not even 562 be used by the eventual DNS-over-HTTPS work). 564 10. References 566 10.1. Normative References 568 [RFC1035] Mockapetris, P., "Domain names - implementation and 569 specification", STD 13, RFC 1035, DOI 10.17487/RFC1035, 570 November 1987, . 572 [RFC3597] Gustafsson, A., "Handling of Unknown DNS Resource Record 573 (RR) Types", RFC 3597, DOI 10.17487/RFC3597, September 574 2003, . 576 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 577 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 578 2014, . 580 [RFC7464] Williams, N., "JavaScript Object Notation (JSON) Text 581 Sequences", RFC 7464, DOI 10.17487/RFC7464, February 2015, 582 . 584 10.2. Informative References 586 [I-D.daley-dnsxml] 587 Daley, J., Morris, S., and J. Dickinson, "dnsxml - A 588 standard XML representation of DNS data", draft-daley- 589 dnsxml-00 (work in progress), July 2013. 591 [I-D.dulaunoy-dnsop-passive-dns-cof] 592 Dulaunoy, A., Kaplan, A., Vixie, P., and H. Stern, 593 "Passive DNS - Common Output Format", draft-dulaunoy- 594 dnsop-passive-dns-cof-03 (work in progress), June 2017. 596 [I-D.mohan-dns-query-xml] 597 Parthasarathy, M. and P. Vixie, "Representing DNS messages 598 using XML", draft-mohan-dns-query-xml-00 (work in 599 progress), September 2011. 601 [RFC0020] Cerf, V., "ASCII format for network interchange", STD 80, 602 RFC 20, DOI 10.17487/RFC0020, October 1969, 603 . 605 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 606 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 607 . 609 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 610 Syndication Format", RFC 4287, DOI 10.17487/RFC4287, 611 December 2005, . 613 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 614 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 615 . 617 Author's Address 619 Paul Hoffman 620 ICANN 622 Email: paul.hoffman@icann.org