RFC 7745
XML Schemas for Reverse DNS Management
RFC 7745: XML Schemas for Reverse DNS Management 🎀
okay bestie, RFC 7745 🌸 is an Informational doc, not a Standards Track one. It was written by T. Manderson at ICANN and published in January 2016. It's an Independent Submission, so the RFC Editor published it at their discretion, and it's not a candidate for any level of Internet Standard. It doesn't list anything it obsoletes or updates. ISSN 2070-1721.
Abstract ✨
This doc defines an Extensible Markup Language (XML) schema for reverse DNS management in a tightly controlled Representational State Transfer (REST) environment. ICANN has been running this schema in a "RESTful" system since 2011, and the registries that handle reverse DNS (rDNS) delegations underneath IN-ADDR.ARPA and IP6.ARPA use it through an HTTPS transaction that's mediated by an X.509 certificate. 🔐
Status of This Memo 📝
This doc is not an Internet Standards Track specification. It's published for informational purposes. 🌈
This is a contribution to the RFC Series, independently of any other RFC stream. The RFC Editor chose to publish it at their discretion and makes no statement about its value for implementation or deployment. Documents approved for publication by the RFC Editor are not a candidate for any level of Internet Standard; see Section 2 of RFC 5741.
Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/info/rfc7745.
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.
Table of Contents 🗂️
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Requirements Language . . . . . . . . . . . . . . . . . . . . 3
3. Implementation . . . . . . . . . . . . . . . . . . . . . . . 3
4. Security Considerations . . . . . . . . . . . . . . . . . . . 5
5. References . . . . . . . . . . . . . . . . . . . . . . . . . 5
5.1. Normative References . . . . . . . . . . . . . . . . . . 5
5.2. Informative References . . . . . . . . . . . . . . . . . 6
Appendix A. Schema Definition for rDNS Updates . . . . . . . . . 7
Appendix B. Schema Definition for rDNS Queue Entries . . . . . . 8
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 10
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 101. Introduction 🦋
This doc defines an XML schema for reverse DNS management in a tightly controlled Representational State Transfer (REST) [REST] environment. ICANN developed and deployed this schema in a "RESTful" system back in 2011, and it's being used by the registries responsible for reverse DNS (rDNS) delegations underneath IN-ADDR.ARPA [RFC1034] and IP6.ARPA [RFC3596] through an HTTPS [RFC2818] transaction that's mediated by an X.509 [RFC5280] certificate. 💖
As DNSSEC [RFC4033] adoption progresses, you have to interact with a delegation in the IN-ADDR.ARPA and IP6.APRA zones more often, because updates to DS records in the parent zone for child delegations follow the key rollover and expiry of the child zone. Changing these critical areas at a relatively high frequency needs a system that lets the administrative holders of those delegations make changes in a secure and trustworthy way. The chain of trust for submitting the necessary information has to stay unbroken between the IN-ADDR.ARPA and IP6.APRA zone maintainers and the zone customers. 🔥
At the request of the Regional Internet Registries (RIRs), who wanted to automate reverse DNS updates with ICANN, a REST-based HTTPS service was deployed that:
- Provides for a secure, authenticated mechanism to update zone data (NS and DS records)
- Provides a well-formed data structure for both the IN-ADDR.ARPA and IP6.ARPA zones
- Allows for "out-of-band" acknowledgement and notification of updates
2. Requirements Language 📜
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. Implementation 💅
The implemented system lets the entity responsible for its rDNS delegations make changes in the reverse DNS zones IN-ADDR.ARPA and IP6.ARPA by submitting an XML document to an atomic RESTful service over an HTTPS [RFC2818] connection. In this service, HTTPS provides the end-to-end security of the transaction. It also handles authentication through mandatory X.509 [RFC5280] client certificates, with a known server certificate issued by a Certification Authority administered by the service operator. 🔐✨
Certificates for use in this system, issued by the system operator, are specific to the entity responsible for the delegations in the zone. 🎀
Updates are made using the HTTP GET, PUT, and DELETE operations over HTTP 1.1 [RFC7231] via HTTPS [RFC2818] only. These operations are sent to a resource Uniform Resource Identifier (URI) in this form:
https://host.example.org/<ipversion>/<zone>A synthetic example of an XML document submitted to the deployed system might look like this (including all optional attributes), following the schema in Appendix A. 🧚
<zone xmlns="http://download.research.icann.org/rdns/1.1"
name="10.in-addr.arpa" cust="IANA" ipversion="ipv4"
version="1.1" modified="2012-01-18T01:00:06"
state="active" href="https://host.example.org/ipv4/10">
<nserver>
<fqdn>BLACKHOLE-1.IANA.ORG.</fqdn>
</nserver>
<nserver>
<fqdn>BLACKHOLE-2.IANA.ORG.</fqdn>
</nserver>
<ds>
<rdata>33682 5 1 ea8afb5fce7caf381ab101039</rdata>
</ds>
<ds>
<rdata>33682 5 2 7d44874f1d93aaceb793a88001739a</rdata>
</ds>
</zone>When PUT and DELETE operations are used, the well-formed XML is required to be sent with the appropriate content-length headers. The GET operation requires only the URI. 🍓
The whole vibe here is that PUT and DELETE carry the XML body with content-length headers, while GET just needs the URI. Don't mix those up, bestie. 💀
One requirement of the system was to allow the separation of update and approval with an out-of-band notification mechanism. When such options are configured for a customer of the service, submitted updates may be queued for later approval. When a customer has queued updates pending approval, the customer may submit a GET request to retrieve either an individual entry or a full listing of all queued entries. 🌸
To fetch a listing of the customer's queue, the customer would GET a URI in this form:
https://host.example.org/queuelistTo fetch an individual queue entry, the customer would GET the canonical URL (as per the schema) for this queue record:
https://host.example.org/queue/<identifier>Where <identifier> is a system-generated and system-specific value that identifies this particular queue entry. All XML returned from queue-based operations ('queue' and 'queuelist') would return an XML document following the specification in Appendix B. A synthetic example from a GET of 'queuelist' would be: 👑
<queuelist xmlns="http://download.research.icann.org/rq/1.0"
version="1.0">
<queue xmlns="http://download.research.icann.org/rq/1.0"
name="10.in-addr.arpa" cust="IANA" ipversion="ipv4"
version="1.0" submitted="2013-01-11T05:22:15"
state="pending" method="PUT"
ack="https://host.example.org/ack/25a531f50e5ba45"
href="https://host.example.org/queue/25a531f50e5ba45">
<nserver>
<fqdn>BLACKHOLE-1.IANA.ORG.</fqdn>
</nserver>
<nserver>
<fqdn>BLACKHOLE-2.IANA.ORG.</fqdn>
</nserver>
<ds>
<rdata>33682 5 1 ea8afb5fce7caf381ab101039</rdata>
</ds>
<ds>
<rdata>33682 5 2 7d44874f1d93aaceb793a88001739a</rdata>
</ds>
</queue>
</queuelist>Appendix A. Schema Definition for rDNS Updates ✨
okay so this schema is what you use for PUT, GET, and DELETE operations 💅 it's an XML document written in RelaxNG Compact [RELAXNG] and it is giving precise 🤓
default namespace = "http://download.research.icann.org/rdns/1.1"
# A document may either be a single zone (update) or
# a collection of zones (view)
start = zone | zonelist | zonereflist
# A list of zone names for view only.
zonereflist = element zonereflist {
attribute version {
xsd:decimal { minInclusive="1.1" fractionDigits="1" }
},
zoneref*
}
# A bulk list of zones for view only.
zonelist = element zonelist {
attribute version {
xsd:decimal { minInclusive="1.1" fractionDigits="1" }
},
zone*
}
# A zone reference (accepted by REST engine for query)
zoneref = element zoneref {
attribute name { text },
attribute href { xsd:anyURI }
}
# A single zone record
zone = element zone {
# The zone record's name, e.g., 10.in-addr.arpa
attribute name { text },
# The customer (optional); derived from known state.
attribute cust { text }?,
# The canonical URL for this zone record (optional)
attribute href { xsd:anyURI }?,
# The IP version of the address for the zone record (optional)
attribute ipversion { "ipv4" | "ipv6" }?,
# The administrative state of the zone (optional)
attribute state { "active" | "pending" | "error" }?,
# The last modified timestamp in UTC (optional)
attribute modified { xsd:dateTime }?,
# The schema version (optional)
attribute version {
xsd:decimal { minInclusive="1.1" fractionDigits="1" }
}?,
# A zone NS RRset MUST have at least two NS records
nserver,
nserver+,
# It MAY contain some DS records
ds*
}
# DNS-SEC records
ds = element ds {
# rdata MUST contain
# <Keytag> | <Algorithm> | <Digest type> | <Digest>
# as per RFC 4034
#
element rdata { text }
}
# A single name server
nserver = element nserver {
# An nserver entry MUST contain a DNS FQDN
# for a NS RR (RFC 1035)
element fqdn { text }
}Appendix B. Schema Definition for rDNS Queue Entries 🎀
this one is the RelaxNG Compact [RELAXNG] schema for the queue interaction operations, so it's the queue's own little rulebook 📋
default namespace = "http://download.research.icann.org/rq/1.0"
# A document MAY either be a single queue entry
# or a collection of queued entries
start = queue | queuelist
# A list of zone names for view only.
queuelist = element queuelist {
attribute version {
xsd:decimal { minInclusive="1.0" fractionDigits="0" }
},
queue*
}
# A single queued zone record
queue = element queue {
# The zone record's name, e.g., 10.in-addr.arpa
attribute name { text },
# The customer (optional); derived from known state.
attribute cust { text }?,
# The canonical URL for this queue record (optional)
attribute href { xsd:anyURI }?,
# The acknowledgement URL for this queue record (optional)
attribute ack { xsd:anyURI }?,
# The IP version of the address for the zone record (optional)
attribute ipversion { "ipv4" | "ipv6" }?,
# The state of the zone (optional); for a queue, it
# SHOULD always be pending
attribute state { "pending" }?,
# The submitted timestamp (optional)
attribute submitted { xsd:dateTime }?,
# The HTTP method used to update
attribute method { "PUT" | "DELETE" },
# The schema version (1.0) (optional)
attribute version {
xsd:decimal { minInclusive="1.0" fractionDigits="1" }
}?,
# A zone NS RRset must have at least two NS records
nserver,
nserver+,
# It MAY contain some DS records
ds*
}
# DNS-SEC records
ds = element ds {
# rdata MUST contain Flags | Protocol | Algorithm | Public Key
# as per RFC 4034
#
element rdata { text }
}
# A single name server
nserver = element nserver {
# An nserver entry MUST contain a DNS FQDN
# for a NS RR (RFC 1035)
element fqdn { text }
}Acknowledgements 🫶
an XML schema was first cooked up by APNIC 💜 but then the project needed its own branch, so a brand new namespace and schema got created. huge respect to APNIC for the early work that made this possible 👑
the author also says thank you to a whole collective of RIR technical folks 🌸 but the biggest shoutouts go to Anand Buddhdev of the RIPE-NCC and Robert Loomans of APNIC, who were the alpha and beta testers and gave super valuable feedback 😭🙌
Author's Address 🦋
Terry Manderson ICANN
Email: terry.manderson@icann.org
📦 where this page comes from
- ietf: rfc7745 2016-01
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms