[Docs] [txt|pdf] [Tracker] [Email] [Nits]

Versions: 00

Network Working Group                                      J. Hildebrand
Internet-Draft                                             Cisco Systems
Intended status: Informational                                P. Hoffman
Expires: September 22, 2016                                        ICANN
                                                          March 21, 2016

                    DNS Editing Through HTTPS (DETH)


   There is a strong desire in many communities for service operators to
   be able to dynamically update DNS records in an easy-to-deploy,
   standardized method.  For example, operating SIP requires DNS records
   to be added and updated as the SIP service starts and is moved among
   different servers.  This document describes an HTTPS-based mechanism
   for service operators who are authorized by their DNS administrator
   to add, change, and delete DNS records.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at http://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on September 22, 2016.

Copyright Notice

   Copyright (c) 2016 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must

Hildebrand & Hoffman   Expires September 22, 2016               [Page 1]

Internet-Draft                     I-D                        March 2016

   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

1.  Introduction

   This document describes a standardized mechanism called DNS Editing
   Through HTTPS (DETH) for developer-friendly dynamic DNS updates over
   HTTPS [RFC7230].  Such a mechanism allows a DNS administrator to
   authorize particular users to update the records in their zones
   without any manual intervention on the part of the DNS administrator.

   All transactions described here are authorized.  Two types of
   authorization are specified: authenticated by HTTP Digest [RFC7235]
   and OAUTH [RFC6749].  The DNS administrator can create policies to
   allow different users different capabilities for updating zones; such
   policies are outside the scope of this document.

   A client determines the DETH server for a zone using a DNS lookup.
   It then sends HTTPS queries to that server to get information about
   what the client can change, as well as requests for changes.

   The DETH protocol is meant for users who do not currently have a way
   to update a zone using the DNS protocol itself.  Although there
   already is a protocol for dynamic update of DNS records, [RFC3007],
   it is rarely used in practice for more anything more complicated than
   inserting a single A or AAAA record.  In many scenarios, using DETH
   is a simpler way to allow users to update a zone than provisioning
   DNS dynamic update.

   Some large DNS operators have implemented their own non-standard
   mechanisms for allowing users to update their DNS records, often
   using HTTP.  This indicates that HTTP-based update is desired in the
   industry, and a standardized mechanism could be valuable in many

1.1.  Goals of this Protocol

   o  Authorized additions of a new record to a zone

   o  Authorized changes to the RDATA and TTL of a record in a zone

   o  Authorized deletions of a record from a zone

   o  Discovery of a URI used for editing a zone, such that the client
      doing the editing can tell that the server they are contacting is
      authorized for the record being edited

Hildebrand & Hoffman   Expires September 22, 2016               [Page 2]

Internet-Draft                     I-D                        March 2016

   o  Discovery of what actions can be taken by an authorized user

   o  Responses can give useful information about why a request was

   o  Ease of writing an implementation for a wide variety of languages
      and platforms is of paramount importance

1.2.  Non-Goals for this Protocol

   o  Updating the contents of any type of configuration other than DNS

   o  Managing DNS servers for anything other than the contents of zones
      for which they are authoritative, such as causing them to reload a
      zone after update or to clear cache entries

   o  Pluggable authorization modules

   o  Editing records in DNS Classes other than IN

1.3.  Possible Deployment Architectures

   There are many ways that the DETH protocol could be deployed.  This
   section gives some sample architectures.

   Native:  An authoritative DNS server system also speaks DETH and uses
      the results of updates directly in the zones it serves.  The DETH
      protocol could be built into DNS server software.

   Bridge:  A DETH server is deployed in front of the management
      interface for an authoritative DNS server.  The DETH server
      receives authorized updates from users, and uses DNS dynamic
      update [RFC3007] to update the zones on the authoritative DNS

   Data store front end:  A DETH server receives authorized updates from
      users, modifies a DNS data store, tells DNS server to reload.

1.4.  Actors

   The following actors are used in this document:

   DETH Server:  A server that speaks HTTPS, and provides an
      implementation of the server side of the DETH API, rooted at a
      discoverable HTTPS URI.  The DETH Server is authorized by the
      associated DNS infrastructure for a set of domains to make policy

Hildebrand & Hoffman   Expires September 22, 2016               [Page 3]

Internet-Draft                     I-D                        March 2016

      decisions about DNS edits.  The DETH server is responsible for
      enforcing authorization in conformance with this policy.

   DETH Client:  A piece of authorized software that would like to make
      changes to one or more DNS records.  In order to make man-in-the-
      middle attacks more difficult, the DETH client is responsible for
      ensuring that it is communicating with the correct DETH Server for
      the domain it wants to modify.

   Parent Domain:  The thing that you want to add records to.  (Paul:
      need DNS terminology here)

1.5.  Terminology

   In this document, the key words "MUST", "MUST NOT", "REQUIRED",
   and "OPTIONAL" are to be interpreted as described in BCP 14, RFC 2119

2.  Protocol

   The DETH protocol uses a simple client-server interactions.  The
   client determines the location of the server either through a DNS
   lookup or local configuration.  After that, all protocol interactions
   are over HTTPS.

   In the following sections, the client wants to edit records in the
   "example.com" zone.  The HTTPS examples use the "dig" program [dig]
   and "curl" program [curl] to get URLs, but clients will most likely
   use internal calls to get this information.

2.1.  Determining the DETH Server for a Zone

   A client uses a DNS query with the TXT RTYPE using the name of the
   parent zone, prefixed with the "_deth" label, for the QNAME.  The
   answer is the base URI for the HTTPS server running the DETH
   protocol.  This URI returned MUST use the HTTPS scheme.

   For example, to find the DETH server for the "example.com" zone, the
   query would have a QNAME of "_deth.example.com" and a QTYPE of TXT.
   A command-line equivalent would be:

   $ dig +short TXT _deth.example.com

   If no TXT record is found for a name, the client can assume that the
   parent does not implement the DETH protocol.  However, explicit
   configuration might still allow a client to find a DETH server.

Hildebrand & Hoffman   Expires September 22, 2016               [Page 4]

Internet-Draft                     I-D                        March 2016

   If the DETH server is found using the DNS lookup described here, the
   client MUST perform the following checks before using the result:

   o  Ensure that the string is a valid HTTPS URI (see [RFC7230],
      section 2.7.2).

   o  Ensure that the TXT record has a valid DNSSEC [RFC4035] signature
      OR that the host portion of the URI matches the parent domain,
      with no port specified.

   o  Ensure that the certificate offered when the URI is accessed using
      HTTPS matches the domain name using the rules in [RFC6125].

   o  Ensure that the DETH server's certificate is signed by a trusted
      Certificate Authority.

2.2.  Determining Authorized Edits

   The DETH client does an HTTPS GET request to the DETH server go get a
   list of edits that the client is authorized to perform.  For example:

   curl -X GET https://example.com/deth/v1/

   Might return:

     "A": {
       "URI": "https://example.com/deth/v1/A/",
       "methods": ["PUT", "DELETE"]
     "AAAA": {
       "URI": "https://example.com/deth/v1/AAAA/",
       "methods": ["PUT"]
     "SRV": {
       "URI": "https://example.com/deth/v1/example.com/SRV/",
       "methods": ["PUT", "DELETE"]
     "TYPE255": {
       "URI": "https://example.com/deth/v1/example.com/TYPE255/",
       "methods": ["PUT", "DELETE"]

                        Figure 1: Directory Example

   The valid keys for the top level JSON object are a popular subset of
   [IANA-rrtypes], plus a mechanism for supporting all other RDATA.  The

Hildebrand & Hoffman   Expires September 22, 2016               [Page 5]

Internet-Draft                     I-D                        March 2016

   response is formally described in CDDL
   [I-D.greevenbosch-appsawg-cbor-cddl] as:

   directory = {
     * rrtype => edit_details

   rrtype =  "A" / "AAAA" / "CNAME" / "NS" / "PTR" / "MX" /
             "TXT" / "SPF" / "SRV" /

   rrtype_num = tstr .regexp "TYPE\\d+"

   edit_details = {
     URI: tstr,
     methods: [+ method_name]

   method_name = "GET" / "PUT" / "DELETE"

                       Figure 2: DETH Directory CDDL

3.  Authentication and Authorization

   All requests are authenticated either by by HTTP Digest [RFC7235] and
   OAUTH [RFC6749].  Parameters supported for either of these mechanisms
   are determined by the DETH Server.  This document makes no
   recommendations for best authentication practices beyond what have
   already been described in other documents published by the IETF.

   After the DETH server authenticates a user, it determines which
   actions that user is authorized to make.  If using HTTP Digest, the
   authorization policy probably comes from a database.  If using OAUTH,
   that determination might be part of the OAUTH interaction.

4.  Forming Request URIs

   When a client wants to edit a particular DNS record, it appends the
   full name of the record to the URI for the RTYPE found in the
   directory JSON (see Section 2.2).  For example, if the directory JSON
   was that specified in Figure 1, and the client wanted to edit a
   "AAAA" record for "foo.example.com", the URL would be


   TODO: specify more rules about URL combination to avoid attacks.

Hildebrand & Hoffman   Expires September 22, 2016               [Page 6]

Internet-Draft                     I-D                        March 2016

5.  Record Editing

   This section describes the semantics of requests to edit DNS records.
   The specification covers how to specify which edits are desired, but
   does not yet cover how the DNS server deals with updating SOA
   records, nor how any DNSSEC records would need to be updated.

5.1.  Encoding in JSON

   The JSON sent to the URIs formed according to the rules in Section 4
   looks like:

     "RTYPE": "AAAA",
     "v6address": "::1",
     "TTL": 3600,
     "comment": "This is my home"

                         Figure 3: Update Example

   All of the potential updates are specified by the following CDDL:

   update = A_update / AAAA_update / CNAME_update / NS_update /
            PTR_update / MX_update / SRV_update / TXT_update /

   A_update = {
     RTYPE: "A",
     v4address: tstr,

   AAAA_update = {
     RTYPE: "AAAA",
     v6address: tstr,

   CNAME_update = {
     RTYPE: "CNAME",
     cname: tstr,

   NS_update = {
     RTYPE: "NS",
     nsdname: tstr,

Hildebrand & Hoffman   Expires September 22, 2016               [Page 7]

Internet-Draft                     I-D                        March 2016


   PTR_update = {
     RTYPE: "PTR",
     ptrdname: tstr,

   MX_update = {
     RTYPE: "MX",
     preference: uint,
     exchange: tstr,

   SRV_update = {
     RTYPE: "SRV",
     priority: uint,
     weight: uint,
     target: tstr,

   TXT_update = {
     RTYPE: "TXT",
     data: tstr,

   rrtype_update = {
     RTYPE: tstr .regexp "TYPE\\d+",
     RDATA: tstr,

   common = (
     ? TTL: uint,
     ? comment: tstr

                        Figure 4: DETH Update CDDL

   For updates that match the rrtype_update syntax, the rules for
   encoding RDATA from [RFC3597] are used.

Hildebrand & Hoffman   Expires September 22, 2016               [Page 8]

Internet-Draft                     I-D                        March 2016

5.2.  Getting Records

   Sending "GET" requests to the URIs formed in Section 4 is supported
   in order to allow clients more easily edit records.

   TODO: The response types for "GET" responses will be specified in a
   future version of this document.

5.3.  Creating Records

   A new record is created by sending the desired JSON document that
   matches Figure 4 to the URI formed by the rules in Section 4, using
   the "POST" HTTP verb.

   If a TTL is not sent with the request, a system default will be used.
   The response from this "PUT" will be the JSON form of the record, as
   inserted.  This response MUST have the TTL included.

5.4.  Deleting Records

   A new record is created by sending the desired JSON document that
   matches Figure 4 to the URI formed by the rules in Section 4, using
   the "DELETE" HTTP verb.

   Currently, this will delete all matching records.  TODO: Once
   matching rules have been defined in a later version of this document,
   individual record deleting may be allowed.

5.5.  Updating Records

   Updating records in place is not yet specified.  A prerequisite for
   this feature will be a way to match existing records, so that only
   one of several existing records with the same name and RTYPE will be

   For now, a combination of request as specified in Section 5.4 and
   Section 5.3 may be used.

   TODO: Add matching feature or change this section.

5.6.  Return Codes and Errors

   Errors use the approach from [I-D.ietf-appsawg-http-problem].

   TODO: Error information will be specified in a future revision of
   this document.

Hildebrand & Hoffman   Expires September 22, 2016               [Page 9]

Internet-Draft                     I-D                        March 2016

6.  IANA Considerations

   No new IANA registries are expected.

7.  Security Considerations

   Careful authorization of all edits is very important.  All changes
   that are allowed by this specification MUST be authorized using the
   model described.

8.  References

8.1.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,

   [RFC3597]  Gustafsson, A., "Handling of Unknown DNS Resource Record
              (RR) Types", RFC 3597, DOI 10.17487/RFC3597, September
              2003, <http://www.rfc-editor.org/info/rfc3597>.

   [RFC4035]  Arends, R., Austein, R., Larson, M., Massey, D., and S.
              Rose, "Protocol Modifications for the DNS Security
              Extensions", RFC 4035, DOI 10.17487/RFC4035, March 2005,

   [RFC6125]  Saint-Andre, P. and J. Hodges, "Representation and
              Verification of Domain-Based Application Service Identity
              within Internet Public Key Infrastructure Using X.509
              (PKIX) Certificates in the Context of Transport Layer
              Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March
              2011, <http://www.rfc-editor.org/info/rfc6125>.

   [RFC6749]  Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
              RFC 6749, DOI 10.17487/RFC6749, October 2012,

   [RFC7230]  Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
              Protocol (HTTP/1.1): Message Syntax and Routing",
              RFC 7230, DOI 10.17487/RFC7230, June 2014,

   [RFC7235]  Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
              Protocol (HTTP/1.1): Authentication", RFC 7235,
              DOI 10.17487/RFC7235, June 2014,

Hildebrand & Hoffman   Expires September 22, 2016              [Page 10]

Internet-Draft                     I-D                        March 2016

8.2.  Informative References

              Vigano, C. and H. Birkholz, "CBOR data definition language
              (CDDL): a notational convention to express CBOR data
              structures", draft-greevenbosch-appsawg-cbor-cddl-08 (work
              in progress), March 2016.

              mnot, m. and E. Wilde, "Problem Details for HTTP APIs",
              draft-ietf-appsawg-http-problem-03 (work in progress),
              January 2016.

              Jennings, C., Daly, T., and J. Hitchcock, "HTTP API for
              Updating DNS Records", 2009, <https://tools.ietf.org/html/

   [RFC3007]  Wellington, B., "Secure Domain Name System (DNS) Dynamic
              Update", RFC 3007, DOI 10.17487/RFC3007, November 2000,

   [dig]      ISC, "dig utility", 2016, <https://www.isc.org/downloads/

   [curl]     Stenberg, D., "curl program", 2016,

              IANA, "Resource Record TYPEs", February 2016,

Appendix A.  Acknowledgements

   This document borrows heavily from many earlier protocols.  Some of
   the text of this document is liberally lifted from the long-expired

Authors' Addresses

   Joe Hildebrand
   Cisco Systems

   Email: jhildebr@cisco.com

Hildebrand & Hoffman   Expires September 22, 2016              [Page 11]

Internet-Draft                     I-D                        March 2016

   Paul Hoffman

   Email: paul.hoffman@icann.org

Hildebrand & Hoffman   Expires September 22, 2016              [Page 12]

Html markup produced by rfcmarkup 1.129d, available from https://tools.ietf.org/tools/rfcmarkup/