Network Working Group C. Jennings
Internet-Draft Cisco Systems
Intended status: Standards Track July 6, 2008
Expires: January 7, 2009
HTTP API for Updating DNS Records
draft-jennings-app-dns-update-00
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 January 7, 2009.
Copyright Notice
Copyright (C) The IETF Trust (2008).
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.
Jennings Expires January 7, 2009 [Page 1]
Internet-Draft DNS Update July 2008
1. Introduction
There are many circumstances in which an application would like to
have an easy way to update DNS records. The DynDNS service[5],
supported on many residential NATs, is one example: it updates a DNS
record to point at the NAT after the NAT receives a dynamically
assigned IP address. Another common use case is dynamically created
servers in elastic computing environments. When new servers are
created, they often need to update DNS records.
The approach described in this specification allows a client to make
a simple HTTP[1] request to a server. The client is authenticated
using a shared secret. The server is authenticated with TLS, which
provides both integrity for the transaction and confidentiality for
the shared secret. The request contains information that instructs
the server to update a particular DNS record. The specification is
limited to updating a simple subset of DNS records and does not
support more complex operations such as the multiple changes that
need to happen as an atomic transactions.
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 [2].
3. Update Record Requests
This section describes the semantics of requests to update DNS
records.
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[3] GET request to a URL. The HTTPS GET request is
formed by starting with the configured base URL, appending "/dns/
update", and then appending all the required parameters. The request
MUST be done using HTTPS to protect the password. The client MUST
ensure the certificate 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.
Jennings Expires January 7, 2009 [Page 2]
Internet-Draft DNS Update July 2008
3.2. URL Parameters
The request MUST include exactly one user, password, and domain
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 become parts of valid HTTP URLs.
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 [4]. |
| domain | The fully qualified domain name for the record to |
| | update. |
| ttl | Requested time to live for the DNS records in |
| | seconds. If omitted, this will be set to default |
| | chosen by the server. |
| index | A numeric counter that indicates which record to |
| | update when there is more than one record of the |
| | given type. This is explained in Section 3.2.1. |
+-----------+-------------------------------------------------------+
The request MUST also have exactly one Record Parameter from the
following table.
Record Parameters
+----------------+----------------------------------------------+
| Parameter Name | Value |
+----------------+----------------------------------------------+
| a | The value to set for a DNS A record [6]. |
| aaaa | The value to set for a DNS AAAA record [7]. |
| cname | The value to set for a DNS CNAME record [6]. |
| ns | The value to set for a DNS NS record [6]. |
| ptr | The value to set for a DNS PTR record [6]. |
| srv | The value to set for a DNS SRV record [8]. |
| txt | The value to set for a DNS TXT record [9]. |
| hip | The value to set for a DNS HIP record [10]. |
+----------------+----------------------------------------------+
Jennings Expires January 7, 2009 [Page 3]
Internet-Draft DNS Update July 2008
3.2.1. Entries with multiple records
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. The index parameter provides a number value, call it i,
that can be used to indicate that the i'th record MUST be updated.
The first record has an index value of 1, not 0. Two special values
are defined 0 and -1.
The value 0 indicates that there should only be the single record and
all others MUST be removed. If a request does not have any index
parameters, it is processed as if the index parameter were 0.
The index value -1 indicates that, unless the exact value already
exists in an existing record, the index MUST be added to the list of
existing records. When a record with an index value of -1 is updated
and the exact value already exists, a success response is returned,
exactly as if the value had not existed and had been appended.
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
+-----------------------------------------------------------+-------+
| Error Condition | Value |
+-----------------------------------------------------------+-------+
| No Error, requested succeeded | 200 |
| Unknown username and Bad username/password combination. | 401 |
| Trying to update a record or domain for which this users | 403 |
| is not authorized to change. | |
| Some problem with the request or parameters. | 406 |
| Trying to update a record type which the server does not | 501 |
| support. | |
+-----------------------------------------------------------+-------+
The body of the response MAY have human readable text that allows a
network administrator to learn more about why the request failed.
Jennings Expires January 7, 2009 [Page 4]
Internet-Draft DNS Update July 2008
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 of the DNS update service is
https://dns.example.org 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.
Precondition:
www.example.com A 192.0.2.0
Requests:
https://dns.example.org/dns/update?user=me%40example.net?password=6E6F
?domain=www.example.com?a=192.0.2.1
Postcondition:
www.example.com A 192.0.2.1
4.2. Update two MX records
This example shows how to update entries where there are multiple
records.
Precondition:
Requests:
https://dns.example.org/dns/update?user=me%40example.net?password=6E6F
?domain=example.com?index=1?mx=10%20mail1.example.com
https://dns.example.org/dns/update?user=me%40example.net?password=6E6F
?domain=example.com?index=2?mx=20%20mail2.example.com
Postcondition:
example.com MX 10 mail1.example.com
example.com MX 20 mail2.example.com
Jennings Expires January 7, 2009 [Page 5]
Internet-Draft DNS Update July 2008
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?a=
Postcondition:
4.4. Add one more 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 192.0.2.1
_sip._tcp.example.com SRV 10 1 5060 192.0.2.2
Requests:
https://dns.example.org/dns/update?user=me%40example.net?password=6E6F
?domain=_sip._tcp.example.com
?index=-1?srv=10%201%205060%20192.0.2.3
Postcondition:
_sip._tcp.example.com SRV 10 1 5060 192.0.2.1
_sip._tcp.example.com SRV 10 1 5060 192.0.2.2
_sip._tcp.example.com SRV 10 1 5060 192.0.2.3
4.5. Add existing SRV record
This example is similar to the previous one, in that an entry is
being appended to a list; but in this case, the entry already exists
so no change is made to the list. The request returns the same 200
success response.
Jennings Expires January 7, 2009 [Page 6]
Internet-Draft DNS Update July 2008
Precondition:
_sip._tcp.example.com SRV 10 1 5060 192.0.2.1
_sip._tcp.example.com SRV 10 1 5060 192.0.2.2
_sip._tcp.example.com SRV 10 1 5060 192.0.2.3
Requests:
https://dns.example.org/dns/update?user=me%40example.net?password=6E6F
?domain=_sip._tcp.example.com
?index=-1?srv=10%201%205060%20192.0.2.2
Postcondition:
_sip._tcp.example.com SRV 10 1 5060 192.0.2.1
_sip._tcp.example.com SRV 10 1 5060 192.0.2.2
_sip._tcp.example.com SRV 10 1 5060 192.0.2.3
5. IANA Considerations
This document makes no requests of IANA.
6. Security Considerations
TODO
7. Acknowledgements
Thanks to TBD.
8. References
8.1. Normative References
[1] 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.
[2] Bradner, S., "Key words for use in RFCs to Indicate Requirement
Levels", BCP 14, RFC 2119, March 1997.
[3] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000.
[4] Josefsson, S., "The Base16, Base32, and Base64 Data Encodings",
RFC 4648, October 2006.
Jennings Expires January 7, 2009 [Page 7]
Internet-Draft DNS Update July 2008
8.2. Informative References
[5] "http://www.dyndns.com/developers/specs/syntax.html", 2008.
[6] Mockapetris, P., "Domain names - implementation and
specification", STD 13, RFC 1035, November 1987.
[7] Thomson, S., Huitema, C., Ksinant, V., and M. Souissi, "DNS
Extensions to Support IP Version 6", RFC 3596, October 2003.
[8] Gulbrandsen, A., Vixie, P., and L. Esibov, "A DNS RR for
specifying the location of services (DNS SRV)", RFC 2782,
February 2000.
[9] Rosenbaum, R., "Using the Domain Name System To Store Arbitrary
String Attributes", RFC 1464, May 1993.
[10] Nikander, P. and J. Laganier, "Host Identity Protocol (HIP)
Domain Name System (DNS) Extensions", RFC 5205, April 2008.
Author's Address
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
Jennings Expires January 7, 2009 [Page 8]
Internet-Draft DNS Update July 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.
Acknowledgment
Funding for the RFC Editor function is provided by the IETF
Administrative Support Activity (IASA).
Jennings Expires January 7, 2009 [Page 9]