HTTP API for Updating DNS Records

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

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.

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.

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

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. Open Issue: there is some discussion going on around if it is better to use HTTP basic auth or form style parameters. TODO Resolve this. General Parameters Parameter Name Value 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 . 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. Type Parameters Values Type Name Value A DNS A record . AAAA DNS AAAA record . CNAME DNS CNAME record . NS DNS NS record . PTR DNS PTR record . SRV DNS SRV record . TXT DNS TXT record . HIP DNS HIP record . MX DNS MX record. SPF DNS SPF record.

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.

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

HTTP response codes are used to indicate success and errors as specified in the following table. 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.

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.

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

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

This example shows a simple removal of a record.

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

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

This section is non normative. The WADL description for the examples is:

]]>

This document makes no requests of IANA.

The request includes a clear text password and MUST be done over HTTPS or the password may be seen by an attacker and used to hijack the services. 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 .

Using HTTP Digest vs URL parameters. Way to set the resource record to the IP address that the server got the request from.

TODO - lots of work is needed here. RFC 2136 and the security for this provided by 3007, and the later DNSSEC RFCs provide a robust system for updating DNS that supports static shared secrets and asymmetric keys. Security working with asymmetric keys not easy but doing with static keys is 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?

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