Network Working Group C. Jennings
Internet-Draft Cisco Systems
Intended status: Standards Track T. Daly
Expires: May 7, 2009 J. Hitchcock
Dynamic Network Services, Inc.
November 3, 2008
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
Jennings, et al. Expires May 7, 2009 [Page 1]
Internet-Draft DNS Update November 2008
support DNS based protocols exist for updating
records[RFC2136][RFC3007][RFC4310], 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] 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][telnic][SliceHost] .
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 [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] 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
Jennings, et al. Expires May 7, 2009 [Page 2]
Internet-Draft DNS Update November 2008
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
+-----------+-------------------------------------------------------+
| Parameter | Value |
| Name | |
+-----------+-------------------------------------------------------+
| user | The configured user name for the user making the |
| | request. |
| password | The configured password for the user making the |
| | request base16 encoded as defined in [RFC4648]. |
| domain | The fully qualified domain name for the record to |
| | update. |
| type | The ASCII encoded version of they type of DNS record |
| | to update. |
| rdata | The value that should be stored in the DNS resource |
| | record. |
| match | The value that matches an existing resource record |
| | that is to be updated by this request. A special |
| | value of "*" means that all existing records are |
| | replaced by the new record in this request. |
| ttl | Requested time to live for the DNS records in |
| | seconds. If omitted, this will be set to default |
| | chosen by the server. |
+-----------+-------------------------------------------------------+
Some common values for the type parameter field are shown in the
following table.
Jennings, et al. Expires May 7, 2009 [Page 3]
Internet-Draft DNS Update November 2008
Type Parameters Values
+-----------+-----------------------------+
| Type Name | Value |
+-----------+-----------------------------+
| A | DNS A record [RFC1035]. |
| AAAA | DNS AAAA record [RFC3596]. |
| CNAME | DNS CNAME record [RFC1035]. |
| NS | DNS NS record [RFC1035]. |
| PTR | DNS PTR record [RFC1035]. |
| SRV | DNS SRV record [RFC2782]. |
| TXT | DNS TXT record [RFC1464]. |
| HIP | DNS HIP record [RFC5205]. |
| MX | DNS MX record. |
| SPF | DNS SPF record. |
+-----------+-----------------------------+
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.
Jennings, et al. Expires May 7, 2009 [Page 4]
Internet-Draft DNS Update November 2008
Response Codes
+-------+-----------------------------------------------------------+
| Value | Error Condition |
+-------+-----------------------------------------------------------+
| 200 | No error, operation successful |
| 400 | The update parameters passed are invalid or would |
| | otherwise result in an ambiguous update |
| 401 | Bad authentication credentials |
| 403 | Trying to update a record for which the given credentials |
| | are not authorized. |
| 404 | No records were found that match the value in the match |
| | parameter of the request. |
| 406 | A valid update was passed, however, it was not accepted |
| | for reasons of update abuse, whereby excessive numbers of |
| | duplicate updates have been sent. |
| 409 | A valid update was passed, however, no change was made as |
| | the requested change was preexisting |
| 501 | The server does not support the specified operation |
| 503 | The server is too busy to service the request or is |
| | otherwise unavailable and the client should wait at least |
| | 5 minutes before trying to update again |
+-------+-----------------------------------------------------------+
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.
Jennings, et al. Expires May 7, 2009 [Page 5]
Internet-Draft DNS Update November 2008
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:
Jennings, et al. Expires May 7, 2009 [Page 6]
Internet-Draft DNS Update November 2008
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.
Jennings, et al. Expires May 7, 2009 [Page 7]
Internet-Draft DNS Update November 2008
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].
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?
Jennings, et al. Expires May 7, 2009 [Page 8]
Internet-Draft DNS Update November 2008
9. Acknowledgements
Thanks to Frank Ellermann, Peter Koch, Stephane Bortzmeyer, Mark
Baker, Patrik Faltstrom, Julian Reschke, and ...
10. References
10.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
[RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, October 2006.
10.2. Informative References
[DynDNS] "http://www.dyndns.com/developers/specs/syntax.html",
2008.
[RFC1035] Mockapetris, P., "Domain names - implementation and
specification", STD 13, RFC 1035, November 1987.
[RFC1464] Rosenbaum, R., "Using the Domain Name System To Store
Arbitrary String Attributes", RFC 1464, May 1993.
[RFC2136] Vixie, P., Thomson, S., Rekhter, Y., and J. Bound,
"Dynamic Updates in the Domain Name System (DNS UPDATE)",
RFC 2136, April 1997.
[RFC2782] Gulbrandsen, A., Vixie, P., and L. Esibov, "A DNS RR for
specifying the location of services (DNS SRV)", RFC 2782,
February 2000.
[RFC3007] Wellington, B., "Secure Domain Name System (DNS) Dynamic
Update", RFC 3007, November 2000.
[RFC3596] Thomson, S., Huitema, C., Ksinant, V., and M. Souissi,
"DNS Extensions to Support IP Version 6", RFC 3596,
October 2003.
Jennings, et al. Expires May 7, 2009 [Page 9]
Internet-Draft DNS Update November 2008
[RFC4310] Hollenbeck, S., "Domain Name System (DNS) Security
Extensions Mapping for the Extensible Provisioning
Protocol (EPP)", RFC 4310, December 2005.
[RFC5205] Nikander, P. and J. Laganier, "Host Identity Protocol
(HIP) Domain Name System (DNS) Extensions", RFC 5205,
April 2008.
[SliceHost]
SliceHost, "http://articles.slicehost.com/assets/2008/5/
27/Slicehost_API.pdfl", May 2008.
[dns-track]
Guha, S. and P. Francis, "Identity Trail: Covert
Surveillance Using DNS", RFC 4310, January 2007.
[telnic] "http://www.telnic.net/developers-resources.html", 2008.
Authors' Addresses
Cullen Jennings
Cisco Systems
170 West Tasman Drive
Mailstop SJC-21/2
San Jose, CA 95134
USA
Phone: +1 408 902-3341
Email: fluffy@cisco.com
Tom Daly
Dynamic Network Services, Inc.
Email: tom@dyn-inc.com
Jeremy Hitchcock
Dynamic Network Services, Inc.
Email: jeremy@dyndns.com
Jennings, et al. Expires May 7, 2009 [Page 10]
Internet-Draft DNS Update November 2008
Full Copyright Statement
Copyright (C) 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.
Jennings, et al. Expires May 7, 2009 [Page 11]