idnits 2.17.1 draft-hildebrand-deth-00.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 seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (March 21, 2016) is 2950 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7235 (Obsoleted by RFC 9110) == Outdated reference: A later version (-11) exists of draft-greevenbosch-appsawg-cbor-cddl-08 Summary: 3 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Hildebrand 3 Internet-Draft Cisco Systems 4 Intended status: Informational P. Hoffman 5 Expires: September 22, 2016 ICANN 6 March 21, 2016 8 DNS Editing Through HTTPS (DETH) 9 draft-hildebrand-deth-00 11 Abstract 13 There is a strong desire in many communities for service operators to 14 be able to dynamically update DNS records in an easy-to-deploy, 15 standardized method. For example, operating SIP requires DNS records 16 to be added and updated as the SIP service starts and is moved among 17 different servers. This document describes an HTTPS-based mechanism 18 for service operators who are authorized by their DNS administrator 19 to add, change, and delete DNS records. 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 September 22, 2016. 38 Copyright Notice 40 Copyright (c) 2016 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 1. Introduction 55 This document describes a standardized mechanism called DNS Editing 56 Through HTTPS (DETH) for developer-friendly dynamic DNS updates over 57 HTTPS [RFC7230]. Such a mechanism allows a DNS administrator to 58 authorize particular users to update the records in their zones 59 without any manual intervention on the part of the DNS administrator. 61 All transactions described here are authorized. Two types of 62 authorization are specified: authenticated by HTTP Digest [RFC7235] 63 and OAUTH [RFC6749]. The DNS administrator can create policies to 64 allow different users different capabilities for updating zones; such 65 policies are outside the scope of this document. 67 A client determines the DETH server for a zone using a DNS lookup. 68 It then sends HTTPS queries to that server to get information about 69 what the client can change, as well as requests for changes. 71 The DETH protocol is meant for users who do not currently have a way 72 to update a zone using the DNS protocol itself. Although there 73 already is a protocol for dynamic update of DNS records, [RFC3007], 74 it is rarely used in practice for more anything more complicated than 75 inserting a single A or AAAA record. In many scenarios, using DETH 76 is a simpler way to allow users to update a zone than provisioning 77 DNS dynamic update. 79 Some large DNS operators have implemented their own non-standard 80 mechanisms for allowing users to update their DNS records, often 81 using HTTP. This indicates that HTTP-based update is desired in the 82 industry, and a standardized mechanism could be valuable in many 83 environments. 85 1.1. Goals of this Protocol 87 o Authorized additions of a new record to a zone 89 o Authorized changes to the RDATA and TTL of a record in a zone 91 o Authorized deletions of a record from a zone 93 o Discovery of a URI used for editing a zone, such that the client 94 doing the editing can tell that the server they are contacting is 95 authorized for the record being edited 97 o Discovery of what actions can be taken by an authorized user 99 o Responses can give useful information about why a request was 100 rejected 102 o Ease of writing an implementation for a wide variety of languages 103 and platforms is of paramount importance 105 1.2. Non-Goals for this Protocol 107 o Updating the contents of any type of configuration other than DNS 108 zones 110 o Managing DNS servers for anything other than the contents of zones 111 for which they are authoritative, such as causing them to reload a 112 zone after update or to clear cache entries 114 o Pluggable authorization modules 116 o Editing records in DNS Classes other than IN 118 1.3. Possible Deployment Architectures 120 There are many ways that the DETH protocol could be deployed. This 121 section gives some sample architectures. 123 Native: An authoritative DNS server system also speaks DETH and uses 124 the results of updates directly in the zones it serves. The DETH 125 protocol could be built into DNS server software. 127 Bridge: A DETH server is deployed in front of the management 128 interface for an authoritative DNS server. The DETH server 129 receives authorized updates from users, and uses DNS dynamic 130 update [RFC3007] to update the zones on the authoritative DNS 131 server. 133 Data store front end: A DETH server receives authorized updates from 134 users, modifies a DNS data store, tells DNS server to reload. 136 1.4. Actors 138 The following actors are used in this document: 140 DETH Server: A server that speaks HTTPS, and provides an 141 implementation of the server side of the DETH API, rooted at a 142 discoverable HTTPS URI. The DETH Server is authorized by the 143 associated DNS infrastructure for a set of domains to make policy 144 decisions about DNS edits. The DETH server is responsible for 145 enforcing authorization in conformance with this policy. 147 DETH Client: A piece of authorized software that would like to make 148 changes to one or more DNS records. In order to make man-in-the- 149 middle attacks more difficult, the DETH client is responsible for 150 ensuring that it is communicating with the correct DETH Server for 151 the domain it wants to modify. 153 Parent Domain: The thing that you want to add records to. (Paul: 154 need DNS terminology here) 156 1.5. Terminology 158 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 159 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 160 and "OPTIONAL" are to be interpreted as described in BCP 14, RFC 2119 161 [RFC2119]. 163 2. Protocol 165 The DETH protocol uses a simple client-server interactions. The 166 client determines the location of the server either through a DNS 167 lookup or local configuration. After that, all protocol interactions 168 are over HTTPS. 170 In the following sections, the client wants to edit records in the 171 "example.com" zone. The HTTPS examples use the "dig" program [dig] 172 and "curl" program [curl] to get URLs, but clients will most likely 173 use internal calls to get this information. 175 2.1. Determining the DETH Server for a Zone 177 A client uses a DNS query with the TXT RTYPE using the name of the 178 parent zone, prefixed with the "_deth" label, for the QNAME. The 179 answer is the base URI for the HTTPS server running the DETH 180 protocol. This URI returned MUST use the HTTPS scheme. 182 For example, to find the DETH server for the "example.com" zone, the 183 query would have a QNAME of "_deth.example.com" and a QTYPE of TXT. 184 A command-line equivalent would be: 186 $ dig +short TXT _deth.example.com 187 https://example.com/deth/v1/ 189 If no TXT record is found for a name, the client can assume that the 190 parent does not implement the DETH protocol. However, explicit 191 configuration might still allow a client to find a DETH server. 193 If the DETH server is found using the DNS lookup described here, the 194 client MUST perform the following checks before using the result: 196 o Ensure that the string is a valid HTTPS URI (see [RFC7230], 197 section 2.7.2). 199 o Ensure that the TXT record has a valid DNSSEC [RFC4035] signature 200 OR that the host portion of the URI matches the parent domain, 201 with no port specified. 203 o Ensure that the certificate offered when the URI is accessed using 204 HTTPS matches the domain name using the rules in [RFC6125]. 206 o Ensure that the DETH server's certificate is signed by a trusted 207 Certificate Authority. 209 2.2. Determining Authorized Edits 211 The DETH client does an HTTPS GET request to the DETH server go get a 212 list of edits that the client is authorized to perform. For example: 214 curl -X GET https://example.com/deth/v1/ 216 Might return: 218 { 219 "A": { 220 "URI": "https://example.com/deth/v1/A/", 221 "methods": ["PUT", "DELETE"] 222 }, 223 "AAAA": { 224 "URI": "https://example.com/deth/v1/AAAA/", 225 "methods": ["PUT"] 226 }, 227 "SRV": { 228 "URI": "https://example.com/deth/v1/example.com/SRV/", 229 "methods": ["PUT", "DELETE"] 230 }, 231 "TYPE255": { 232 "URI": "https://example.com/deth/v1/example.com/TYPE255/", 233 "methods": ["PUT", "DELETE"] 234 } 235 } 237 Figure 1: Directory Example 239 The valid keys for the top level JSON object are a popular subset of 240 [IANA-rrtypes], plus a mechanism for supporting all other RDATA. The 241 response is formally described in CDDL 242 [I-D.greevenbosch-appsawg-cbor-cddl] as: 244 directory = { 245 * rrtype => edit_details 246 } 248 rrtype = "A" / "AAAA" / "CNAME" / "NS" / "PTR" / "MX" / 249 "TXT" / "SPF" / "SRV" / 250 rrtype_num 252 rrtype_num = tstr .regexp "TYPE\\d+" 254 edit_details = { 255 URI: tstr, 256 methods: [+ method_name] 257 } 259 method_name = "GET" / "PUT" / "DELETE" 261 Figure 2: DETH Directory CDDL 263 3. Authentication and Authorization 265 All requests are authenticated either by by HTTP Digest [RFC7235] and 266 OAUTH [RFC6749]. Parameters supported for either of these mechanisms 267 are determined by the DETH Server. This document makes no 268 recommendations for best authentication practices beyond what have 269 already been described in other documents published by the IETF. 271 After the DETH server authenticates a user, it determines which 272 actions that user is authorized to make. If using HTTP Digest, the 273 authorization policy probably comes from a database. If using OAUTH, 274 that determination might be part of the OAUTH interaction. 276 4. Forming Request URIs 278 When a client wants to edit a particular DNS record, it appends the 279 full name of the record to the URI for the RTYPE found in the 280 directory JSON (see Section 2.2). For example, if the directory JSON 281 was that specified in Figure 1, and the client wanted to edit a 282 "AAAA" record for "foo.example.com", the URL would be 284 https://example.com/deth/v1/AAAA/foo.example.com 286 TODO: specify more rules about URL combination to avoid attacks. 288 5. Record Editing 290 This section describes the semantics of requests to edit DNS records. 291 The specification covers how to specify which edits are desired, but 292 does not yet cover how the DNS server deals with updating SOA 293 records, nor how any DNSSEC records would need to be updated. 295 5.1. Encoding in JSON 297 The JSON sent to the URIs formed according to the rules in Section 4 298 looks like: 300 { 301 "RTYPE": "AAAA", 302 "v6address": "::1", 303 "TTL": 3600, 304 "comment": "This is my home" 305 } 307 Figure 3: Update Example 309 All of the potential updates are specified by the following CDDL: 311 update = A_update / AAAA_update / CNAME_update / NS_update / 312 PTR_update / MX_update / SRV_update / TXT_update / 313 rrtype_update 315 A_update = { 316 RTYPE: "A", 317 v4address: tstr, 318 common 319 } 321 AAAA_update = { 322 RTYPE: "AAAA", 323 v6address: tstr, 324 common 325 } 327 CNAME_update = { 328 RTYPE: "CNAME", 329 cname: tstr, 330 common 331 } 333 NS_update = { 334 RTYPE: "NS", 335 nsdname: tstr, 336 common 337 } 339 PTR_update = { 340 RTYPE: "PTR", 341 ptrdname: tstr, 342 common 343 } 345 MX_update = { 346 RTYPE: "MX", 347 preference: uint, 348 exchange: tstr, 349 common 350 } 352 SRV_update = { 353 RTYPE: "SRV", 354 priority: uint, 355 weight: uint, 356 target: tstr, 357 common 358 } 360 TXT_update = { 361 RTYPE: "TXT", 362 data: tstr, 363 common 364 } 366 rrtype_update = { 367 RTYPE: tstr .regexp "TYPE\\d+", 368 RDATA: tstr, 369 common 370 } 372 common = ( 373 ? TTL: uint, 374 ? comment: tstr 375 ) 377 Figure 4: DETH Update CDDL 379 For updates that match the rrtype_update syntax, the rules for 380 encoding RDATA from [RFC3597] are used. 382 5.2. Getting Records 384 Sending "GET" requests to the URIs formed in Section 4 is supported 385 in order to allow clients more easily edit records. 387 TODO: The response types for "GET" responses will be specified in a 388 future version of this document. 390 5.3. Creating Records 392 A new record is created by sending the desired JSON document that 393 matches Figure 4 to the URI formed by the rules in Section 4, using 394 the "POST" HTTP verb. 396 If a TTL is not sent with the request, a system default will be used. 397 The response from this "PUT" will be the JSON form of the record, as 398 inserted. This response MUST have the TTL included. 400 5.4. Deleting Records 402 A new record is created by sending the desired JSON document that 403 matches Figure 4 to the URI formed by the rules in Section 4, using 404 the "DELETE" HTTP verb. 406 Currently, this will delete all matching records. TODO: Once 407 matching rules have been defined in a later version of this document, 408 individual record deleting may be allowed. 410 5.5. Updating Records 412 Updating records in place is not yet specified. A prerequisite for 413 this feature will be a way to match existing records, so that only 414 one of several existing records with the same name and RTYPE will be 415 modified. 417 For now, a combination of request as specified in Section 5.4 and 418 Section 5.3 may be used. 420 TODO: Add matching feature or change this section. 422 5.6. Return Codes and Errors 424 Errors use the approach from [I-D.ietf-appsawg-http-problem]. 426 TODO: Error information will be specified in a future revision of 427 this document. 429 6. IANA Considerations 431 No new IANA registries are expected. 433 7. Security Considerations 435 Careful authorization of all edits is very important. All changes 436 that are allowed by this specification MUST be authorized using the 437 model described. 439 8. References 441 8.1. Normative References 443 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 444 Requirement Levels", BCP 14, RFC 2119, 445 DOI 10.17487/RFC2119, March 1997, 446 . 448 [RFC3597] Gustafsson, A., "Handling of Unknown DNS Resource Record 449 (RR) Types", RFC 3597, DOI 10.17487/RFC3597, September 450 2003, . 452 [RFC4035] Arends, R., Austein, R., Larson, M., Massey, D., and S. 453 Rose, "Protocol Modifications for the DNS Security 454 Extensions", RFC 4035, DOI 10.17487/RFC4035, March 2005, 455 . 457 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 458 Verification of Domain-Based Application Service Identity 459 within Internet Public Key Infrastructure Using X.509 460 (PKIX) Certificates in the Context of Transport Layer 461 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 462 2011, . 464 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 465 RFC 6749, DOI 10.17487/RFC6749, October 2012, 466 . 468 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 469 Protocol (HTTP/1.1): Message Syntax and Routing", 470 RFC 7230, DOI 10.17487/RFC7230, June 2014, 471 . 473 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 474 Protocol (HTTP/1.1): Authentication", RFC 7235, 475 DOI 10.17487/RFC7235, June 2014, 476 . 478 8.2. Informative References 480 [I-D.greevenbosch-appsawg-cbor-cddl] 481 Vigano, C. and H. Birkholz, "CBOR data definition language 482 (CDDL): a notational convention to express CBOR data 483 structures", draft-greevenbosch-appsawg-cbor-cddl-08 (work 484 in progress), March 2016. 486 [I-D.ietf-appsawg-http-problem] 487 mnot, m. and E. Wilde, "Problem Details for HTTP APIs", 488 draft-ietf-appsawg-http-problem-03 (work in progress), 489 January 2016. 491 [draft-jennings-app-dns-update] 492 Jennings, C., Daly, T., and J. Hitchcock, "HTTP API for 493 Updating DNS Records", 2009, . 496 [RFC3007] Wellington, B., "Secure Domain Name System (DNS) Dynamic 497 Update", RFC 3007, DOI 10.17487/RFC3007, November 2000, 498 . 500 [dig] ISC, "dig utility", 2016, . 503 [curl] Stenberg, D., "curl program", 2016, 504 . 506 [IANA-rrtypes] 507 IANA, "Resource Record TYPEs", February 2016, 508 . 511 Appendix A. Acknowledgements 513 This document borrows heavily from many earlier protocols. Some of 514 the text of this document is liberally lifted from the long-expired 515 [draft-jennings-app-dns-update]. 517 Authors' Addresses 519 Joe Hildebrand 520 Cisco Systems 522 Email: jhildebr@cisco.com 523 Paul Hoffman 524 ICANN 526 Email: paul.hoffman@icann.org