HTTP API for Updating DNS Records
draft-jennings-app-dns-update-01

Status of this Memo

By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts.

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.”

The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt.

The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html.

This Internet-Draft will expire on May 7, 2009.

Abstract

This specification defines a simple HTTP based scheme for clients to update DNS records.

The draft is being discussed on the apps-discuss@ietf.org list.

1.  Introduction

There are many circumstances in which an application or device would like to have an easy way to update DNS records. While a number of support DNS based protocols exist for updating records[RFC2136] (Vixie, P., Thomson, S., Rekhter, Y., and J. Bound, “Dynamic Updates in the Domain Name System (DNS UPDATE),” April 1997.)[RFC3007] (Wellington, B., “Secure Domain Name System (DNS) Dynamic Update,” November 2000.)[RFC4310] (Hollenbeck, S., “Domain Name System (DNS) Security Extensions Mapping for the Extensible Provisioning Protocol (EPP),” December 2005.), many of these mechanisms are not available in today's scaled down applications and devices. However, many existing application and devices do support the use of HTTP[RFC2616] (Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” June 1999.) and HTTP over TLS to update DNS records. The goal of this specification is to create a generic standard for which applications and devices can update DNS records using HTTP over TLS.

The need for this protocol exists from the use of DHCP and other dynamic IP addressing systems, where a device receives updates to it IP address, and further, there exists a need for the global DNS to be made aware of such a change. Many residential NAT devices support this type of operation today, but do it using hap-hazard and proprietary methods [DynDNS] (, “http://www.dyndns.com/developers/specs/syntax.html,” 2008.)[telnic] (, “http://www.telnic.net/developers-resources.html,” 2008.)[SliceHost] (SliceHost, “http://articles.slicehost.com/assets/2008/5/27/Slicehost_API.pdfl,” May 2008.) .

The approach described in the specification allows a client to make HTTP over TLS requests to a server to update DNS records, using standard and highly available encryption techniques for security, while providing a generic a flexible interface for updating DNS records

2.  Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) [RFC2119].

3.  Update Record Requests

This section describes the semantics of requests to update DNS records. The specification only covers how tell a DNS system what updates are desired. How the DNS system deal with SOA records or DNSSEC if not effected in any way by this specification.

3.1.  HTTPS Request

The client needs to be configured with the base URL for the server, along with a username and password. The request is created by forming an HTTPS[RFC2818] (Rescorla, E., “HTTP Over TLS,” May 2000.) POST request to a URL. The HTTPS POST request is formed by starting with the configured base URL, and then appending all the required parameters. The request MUST be done using HTTPS to protect the password. The client MUST ensure the TLS certificate of the server is appropriately signed.

The HTTP request SHOULD contain a "User-Agent" header that clearly identifies the version of the software making the request, as this facilitates debugging.

3.2.  URL Parameters

The request MUST include exactly one user, password, domain, and type parameter as defined below. Other parameters are optional and can occur at most once. The values of parameters MUST be appropriately escaped as required to be part of a valid HTTP URL.

General Parameters

Some common values for the type parameter field are shown in the following table.

Type Parameters Values

3.2.1.  Entries with multiple records

For many updates, where only one resource record is desired, the match parameter is sent with a value of "*" indicating all existing records are removed and replaced with the new one. Sometimes it is desirable to have multiple records of the same type for the same name. For example, a domain may have multiple MX records. To add a new record, no match value is sent, or the match value is empty, and a new record is appended to the set. To update an existing record, the match parameter is set to the value of the old record that needs to be updated. If the record in the match parameter can not be found, the request returns an 404 error.

3.2.2.  Deleting records

If the value of the parameter that would update a record is empty, the record MUST be removed from DNS.

3.3.  Return Codes and Errors

HTTP response codes are used to indicate success and errors as specified in the following table.

Response Codes

The body of the response MAY have human readable text that allows a network administrator to learn more about why the request failed.

4.  Example

In the examples below, some of the URLs appear broken across multiple lines. This is because of physical width limitations in this document; such URLs need to be read as single URLs with no embedded white space. All of the examples assume that a user called "me@example.net" with password "no" is allowed to update records in the example.com domain. The base URL for the DNS update service of https://dns.example.org/dns/update is used in the examples.

Each example shows the state of the DNS in a precondition before the request, the requests performed using this specification, and then the resulting state of the DNS in the postcondition.

4.1.  Update an A record

This example shows a basic update where all existing A record values are replaced with a new entry.

Precondition:
  www.example.com   A    192.0.2.0
  www.example.com   A    192.0.2.1

Requests:
  https://dns.example.org/dns/update?user=me%40example.net
        &password=6E6F&match=*&domain=www.example.com&type=A
        &rdata=192.0.2.2

Postcondition:
  www.example.com   A    192.0.2.2

4.2.  Create two MX records

This example shows how to create entries where there are multiple records.

Precondition:

Requests:
  https://dns.example.org/dns/update?user=me%40example.net
       &password=6E6F&domain=example.com&match=&type=MX
       &rdata=10%20mail1.example.com
  https://dns.example.org/dns/update?user=me%40example.net
       &password=6E6F&domain=example.com&match=&type=MX
       &rdata=20%20mail2.example.com

Postcondition:
  example.com   MX    10 mail1.example.com
  example.com   MX    20 mail2.example.com

4.3.  Delete an A record

This example shows a simple removal of a record.

Precondition:
  www.example.com   A    192.0.2.1

Requests:
  https://dns.example.org/dns/update?user=me%40example.net
        &password=6E6F&domain=www.example.com&type=A&match=192.0.2.1

Postcondition:

4.4.  Add a new SRV record

This example shows how to append a record to a list of existing records.

Precondition:
  _sip._tcp.example.com   SRV 10 1 5060 sip1.example.com
  _sip._tcp.example.com   SRV 10 1 5060 sip2.example.com

Requests:
  https://dns.example.org/dns/update?user=me%40example.net
         &password=6E6F&domain=_sip._tcp.example.com
         &match=&type=SRV&rdata=10%201%205060%20sip3.example.com

Postcondition:
  _sip._tcp.example.com   SRV 10 1 5060 sip1.example.com
  _sip._tcp.example.com   SRV 10 1 5060 sip2.example.com
  _sip._tcp.example.com   SRV 10 1 5060 sip3.example.com

4.5.  Update an existing SRV record

This example is similar to the previous one, in that an entry is being changed.

Precondition:
  _sip._tcp.example.com   SRV 10 1 5060 sip1.example.com
  _sip._tcp.example.com   SRV 10 1 5060 sip2.example.com
  _sip._tcp.example.com   SRV 10 1 5060 sip3.example.com

Requests:
  https://dns.example.org/dns/update?user=me%40example.net
        &password=6E6F&domain=_sip._tcp.example.com&type=SRV
        &match=10%201%205060%20sip2.example.com
        &rdata=10%201%205060%20sip22.example.com

Postcondition:
  _sip._tcp.example.com   SRV 10 1 5060 sip1.example.com
  _sip._tcp.example.com   SRV 10 1 5060 sip22.example.com
  _sip._tcp.example.com   SRV 10 1 5060 sip3.example.com

5.  IANA Considerations

This document makes no requests of IANA.

6.  Security Considerations

TODO

If a user publishes the IP of their notebook computer, PDA, or smart phone as the move, it is likely that the IP address can be correlated to locations. By looking at the location over time for a specific user, it may be further possible to correlate that to an actual person. These attacks and implications to privacy are discussed in [dns‑track] (Guha, S. and P. Francis, “Identity Trail: Covert Surveillance Using DNS,” January 2007.).

7.  Open Issues

The index in previous draft would likely not work because the clients view of the records may not match the servers as pointed out by Frank Ellermann.

Issues around using mDNS or NAPTR to get base URL.

Do we need an operation=add,del,update parameter? And how to keep it RESTful.

Using HTTP Digest vs URL parameters

Way to set the resource record to the IP address that the server got the request from.

8.  Why not use DNS Dynamic Update?

TODO - lots of work is needed here.

RFC 2136 and the security for this provided by 3007 and later DNSSEC RFCs provide a robust system for updating DNS that supports static shared secrets and asymmetric key. Security working with asymmetric keys not easy. Doing with static keys vulnerable to offline attacks. Hard to do from Java script. Questions, any issues punching through NATs that have DNS ALGs with this? Hard to integrate with fine web security systems like openid. Trivial to implement this most web environments.

Questions about deployment success. When were things defined, what is the market choosing? Does it work?

Is the problem that we just need a simple open source library that does Dynamic Update?

9.  Acknowledgements

Thanks to Frank Ellermann, Peter Koch, Stephane Bortzmeyer, Mark Baker, Patrik Faltstrom, Julian Reschke, and ...

10.  References

10.1. Normative References

10.2. Informative References

Authors' Addresses

Full Copyright Statement

Copyright © The IETF Trust (2008).

This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights.

This document and the information contained herein are provided on an “AS IS” basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Intellectual Property

The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79.

Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr.

The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org.