RFC 9224

Finding the Authoritative Registration Data Access Protocol (RDAP) Service

📅 published March 2022, from ietf

RFC 9224 🦋 Finding the Authoritative Registration Data Access Protocol (RDAP) Service

  • Request for Comments: 9224 📄
  • Written by: M. Blanchet, from Viagenie 💅
  • STD: 95 👑
  • Date: March 2022 🌸
  • Category: Standards Track ✨
  • ISSN: 2070-1721
  • Obsoletes: 7484, so this one replaces RFC 7484 🙈
  • Updates: nothing is listed in the title block 🤷‍♀️

Abstract 💖

Okay so this doc is all about figuring out which RDAP server is the authoritative one for a query 🔍. The scope can be domain names, IP addresses, or Autonomous System numbers, and it's giving main character energy. This document obsoletes RFC 7484 💜.

Status of This Memo 📮

This is an Internet Standards Track document. ✨

It's a product of the Internet Engineering Task Force (IETF), so it represents the consensus of the IETF community 🫶. It got public review and was approved for publication by the Internet Engineering Steering Group (IESG) 💅. If you want more on Internet Standards, check Section 2 of RFC 7841 📚.

For the current status, any errata, and how to send feedback, go to https://www.rfc-editor.org/info/rfc9224 🔗.

Copyright (c) 2022 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 (https://trustee.ietf.org/license-info) as they stand on the publication date. Please read these carefully, because they describe your rights and restrictions for this document 🙏. Code Components pulled out of this document must include Revised BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come without warranty, as described in the Revised BSD License ⚠️.

Table of Contents 🗂️

1.  Introduction
2.  Conventions Used in This Document
3.  Structure of the RDAP Bootstrap Service Registries
4.  Bootstrap Service Registry for Domain Name Space
5.  Bootstrap Service Registries for Internet Numbers
  5.1.  Bootstrap Service Registry for IPv4 Address Space
  5.2.  Bootstrap Service Registry for IPv6 Address Space
  5.3.  Bootstrap Service Registry for AS Number Space
6.  Entity
7.  Non-existent Entries or RDAP URL Values
8.  Deployment and Implementation Considerations
9.  Limitations
10. Formal Definition
  10.1.  Imported JSON Terms
  10.2.  Registry Syntax
11. Security Considerations
12. IANA Considerations
  12.1.  Bootstrap Service Registry for IPv4 Address Space
  12.2.  Bootstrap Service Registry for IPv6 Address Space
  12.3.  Bootstrap Service Registry for AS Number Space
  12.4.  Bootstrap Service Registry for Domain Name Space
13. References
  13.1.  Normative References
  13.2.  Informative References
Appendix A.  Changes since RFC 7484
Acknowledgements
Author's Address

1. Introduction 🌈

So RDAP is the protocol for asking registries for registration data, and it's defined in [RFC7480] [RFC7481] [RFC9082] [RFC9083] ✨. Those documents don't say where the queries get sent, though 🥺. This document fills that gap by specifying a method to find which server is authoritative to answer queries for the requested scope 🎯.

Top-Level Domains (TLDs), Autonomous System (AS) numbers, and network blocks get delegated by IANA to Internet registries, like TLD registries and Regional Internet Registries (RIRs). Those registries then make further delegations and keep track of them 🗺️. So the bootstrap info RDAP clients need is best generated from data and processes IANA already maintains 💅. The relevant registries already exist at [ipv4reg], [ipv6reg], [asreg], and [domainreg] 📚. This document obsoletes [RFC7484] 💜.

This document creates new IANA registries based on a JSON format, called RDAP Bootstrap Service Registries 🍓. They're built from the existing entries in those registries listed above. An RDAP client fetches the RDAP Bootstrap Service Registries, pulls out the data, and then matches it against the query data to find the authoritative registration data server and the right query base URL 🦋.

2. Conventions Used in This Document 🎀

Here's the vibe check on keywords 🫶. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are read as described in BCP 14 [RFC2119] [RFC8174], but only when, and only when, they show up in all capitals, exactly like that 🔥.

3. Structure of the RDAP Bootstrap Service Registries ✨

The RDAP Bootstrap Service Registries, which are defined in Section 12 below, are JSON [RFC8259] objects. You can grab them over HTTP from IANA-specified locations 🌐. Each registry's JSON object has a bunch of members with metadata, like a version identifier, a timestamp for when the registry was published, and a description 📝. There's also a "services" member, and it holds the actual registry items as an array. Each item in that array is a second-level array with two elements, and each of those elements is a third-level array 🧩.

Each element of the Services Array is a second-level array with two elements, in order: an Entry Array and a Service URL Array 💜. The Entry Array holds all the entries that share the same set of base RDAP URLs. The Service URL Array holds the list of base RDAP URLs you can use for the entries in the Entry Array. Nothing inside these two arrays is ordered in any way 🙃.

Here's an example of what the JSON output of an RDAP Bootstrap Service Registry looks like 👀:

{
    "version": "1.0",
    "publication": "YYYY-MM-DDTHH:MM:SSZ",
    "description": "Some text",
    "services": [
      [
        ["entry1", "entry2", "entry3"],
        [
          "https://registry.example.com/myrdap/",
          "http://registry.example.com/myrdap/"
        ]
      ],
      [
        ["entry4"],
        [
          "https://example.org/"
        ]
      ]
    ]
}

The formal syntax is in Section 10 🎀.

The "version" is the format version of the registry, and this spec defines version "1.0" 🔢.

The "publication" value follows the Internet date/time format [RFC3339] 🕰️. It's the latest update date of the registry from IANA.

The optional "description" string can hold a comment about what's in the bootstrap object 📝.

Per [RFC7258], the secure versions of the transport protocol SHOULD be preferred and tried first in each array of base RDAP URLs 🔐. So if the base RDAP URLs array has both HTTPS and HTTP URLs, the bootstrap client SHOULD try the HTTPS version first 💖.

Base RDAP URLs MUST have a trailing "/" character, because they get concatenated with the various segments defined in [RFC9082] 🧵.

JSON names MUST follow the format recommendations in Section 6 of [RFC7480] 🎀. Any unrecognized JSON object properties or values MUST be ignored by implementations 🙈.

Internationalized Domain Name labels used as entries or base RDAP URLs in the registries defined here MUST only be represented in their A-label form, as defined in [RFC5890] 🌸.

Every Domain Name label used as an entry or base RDAP URL in the registries defined here MUST only be represented in lowercase 🔡.

4. Bootstrap Service Registry for Domain Name Space 🌍

The JSON output of this registry holds domain label entries attached to the root, grouped by base RDAP URLs. Here's an example 💅:

{
    "version": "1.0",
    "publication": "2024-01-07T10:11:12Z",
    "description": "Some text",
    "services": [
      [
        ["net", "com"],
        [
          "https://registry.example.com/myrdap/"
        ]
      ],
      [
        ["org", "mytld"],
        [
          "https://example.org/"
        ]
      ],
      [
        ["xn--zckzah"],
        [
          "https://example.net/rdap/xn--zckzah/",
          "http://example.net/rdap/xn--zckzah/"
        ]
      ]
    ]
}

To find a domain name's authoritative registration data service, you do a label-wise longest match of the target domain name against the domain values in the Entry Arrays of the IANA "Bootstrap Service Registry for Domain Name Space" 🔍. The matching goes label by label, from right to left 👉. If the longest match gives you multiple entries, those entries count as equivalent ⚖️. The values in the Service URL Array of the matching second-level array are the valid base RDAP URLs, as described in [RFC9082] ✨.

For example, a domain RDAP query for a.b.example.com matches the com entry in one of the arrays of the registry 💜. The base RDAP URL then comes from the second element of that array, which is a list of base RDAP URLs valid for this entry. The client picks one of those base URLs. In this example there's only one, https://registry.example.com/myrdap/, so that's the one it uses 🫶. The segment from [RFC9082] gets appended to the base URL to finish the query, so the complete query is https://registry.example.com/myrdap/domain/a.b.example.com 🎯.

If a domain RDAP query for a.b.example.com matches both the com and example.com entries in the registry, the longest match applies and the client uses the example.com entry 🏆.

If the registry has entries like com and goodexample.com, then a domain RDAP query for example.com only matches the com entry, because matching happens per label 🙅‍♀️.

The entry for the root of the domain name space is written as "" 🌳.

5. Bootstrap Service Registries for Internet Numbers 🌐

This section covers IPv4 and IPv6 address space, plus Autonomous System numbers 🦋.

For IP address space, you find the authoritative registration data service by doing a longest match of the target address against the values of the arrays in the corresponding RDAP Bootstrap Service Registry for Address Space 🔍. The longest match works the same way as in packet forwarding: the addresses are converted to binary form, and then the binary strings are compared to find the longest match up to the specified prefix length 🧠. The values in the second element of the array are the base RDAP URLs, as described in [RFC9082] 💜. This longest match method lets a covering prefix from a larger address space point to one base RDAP URL, while more specific prefixes inside that covering prefix are served by a different base RDAP URL 🌸.

5.1. Bootstrap Service Registry for IPv4 Address Space ✨

okay so the IPv4 registry's JSON output has IPv4 prefix entries written in Classless Inter-domain Routing (CIDR) format [RFC4632], grouped by RDAP URLs 💅 here's what it looks like:

{
    "version": "1.0",
    "publication": "2024-01-07T10:11:12Z",
    "description": "RDAP Bootstrap file for example registries.",
    "services": [
      [
        ["198.51.100.0/24", "192.0.0.0/8"],
        [
          "https://rir1.example.com/myrdap/"
        ]
      ],
      [
        ["203.0.113.0/24", "192.0.2.0/24"],
        [
          "https://example.org/"
        ]
      ],
      [
        ["203.0.113.0/28"],
        [
          "https://example.net/rdaprir2/",
          "http://example.net/rdaprir2/"
        ]
      ]
    ]
}

ok this part is my favourite 🫶 say you query "192.0.2.1/25". It matches BOTH the "192.0.0.0/8" entry and the "192.0.2.0/24" entry in that example registry. The client picks the "192.0.2.0/24" one because it's the longest match, and that's the main character here 👑 Then the base RDAP URL gets pulled from the second element of the array, which is a list of base RDAP URLs that work for that entry. The client picks one of them. In this example there's only one option, "https://example.org/", so no decisions to make 💀 Next, the {resource} specified in [RFC9082] gets tacked onto the base URL, and boom, the complete query is "https://example.org/ip/192.0.2.1/25" ✨

5.2. Bootstrap Service Registry for IPv6 Address Space 🦋

the IPv6 registry's JSON output contains IPv6 prefix entries, written in the [RFC5952] text representation of address prefixes, grouped by base RDAP URLs. Here's the example:

{
    "version": "1.0",
    "publication": "2024-01-07T10:11:12Z",
    "description": "RDAP Bootstrap file for example registries.",
    "services": [
      [
        ["2001:db8::/34"],
        [
          "https://rir2.example.com/myrdap/"
        ]
      ],
      [
        ["2001:db8:4000::/36", "2001:db8:ffff::/48"],
        [
          "https://example.org/"
        ]
      ],
      [
        ["2001:db8:1000::/36"],
        [
          "https://example.net/rdaprir2/",
          "http://example.net/rdaprir2/"
        ]
      ]
    ]
}

so a query for "2001:db8:1000::/48" matches the "2001:db8::/34" entry AND the "2001:db8:1000::/36" entry. The client goes with the "2001:db8:1000::/36" one because it's the longest match, which is so iconic 🌸 The base RDAP URL comes from the second element of the array, the list of base RDAP URLs valid for that entry. This time the client chooses "https://example.net/rdaprir2/" because it's the secure version of the protocol 🔒 The segment specified in [RFC9082] is then appended to that base URL, so the complete query is "https://example.net/rdaprir2/ip/2001:db8:1000::/48". And if the target RDAP server doesn't answer? No stress 🫶 The client can just try another URL prefix from the array.

5.3. Bootstrap Service Registry for AS Number Space 🌈

the AS number registry's JSON output has entries for AS number ranges, grouped by base RDAP URLs. The Entry Array is the list of AS number ranges served by the base RDAP URLs in the second element. Each element holds two AS numbers in decimal format, separated by a hyphen. Together they describe the range between them (inclusive), and the values go in increasing order, so it's "100-200", never "200-100" 🙅‍♀️ A single AS number is written as a range of two identical AS numbers. AS numbers are written as 'asplain' as defined in [RFC5396]. And the big rule: Ranges MUST NOT overlap. No cap, that one is non-negotiable 💅

{
    "version": "1.0",
    "publication": "2024-01-07T10:11:12Z",
    "description": "RDAP Bootstrap file for example registries.",
    "services": [
      [
        ["64496-64496"],
        [
          "https://rir3.example.com/myrdap/"
        ]
      ],
      [
        ["64497-64510", "65536-65551"],
        [
          "https://example.org/"
        ]
      ],
      [
        ["64512-65534"],
        [
          "http://example.net/rdaprir2/",
          "https://example.net/rdaprir2/"
        ]
      ]
    ]
}

so a query for AS 65411 matches the 64512-65534 entry in that example registry 🎀 The base RDAP URL is taken from the second element of the array, the list of base RDAP URLs valid for that entry. The client chooses "https://example.net/rdaprir2/". The segment specified in [RFC9082] is then appended to the base URL, and the complete query is, therefore, "https://example.net/rdaprir2/autnum/65411". If the server doesn't answer, the client can try another URL prefix from the array 🧚

6. Entity ✨

entities (like contacts, registrants, or registrars) can be queried by handle, as described in [RFC9082]. Since there is no global name space for entities, this document doesn't explain how to find the authoritative RDAP server for them. BUT, it's possible that if the entity identifier came from a previous query, you could query that same RDAP server for the entity. Or the entity identifier itself might be a fully qualified URL that you can query directly 🔍 The mechanism described in [RFC8521] MAY also be used, if you want to go that route 💜

7. Non-existent Entries or RDAP URL Values 🙈

the registries may not contain the value you asked for. In that case there's no known RDAP server for that value, and the client SHOULD provide an appropriate error message to the user. Not a vibe, but a clear error message is the move 💅

8. Deployment and Implementation Considerations 🍓

this method relies on the fact that RDAP clients fetch the IANA registries and then find the servers locally. Clients SHOULD NOT fetch the registry on every RDAP request, bestie, that's way too much 💀 Clients SHOULD cache the registry instead, and use underlying protocol signaling, like the HTTP Expires header field [RFC7234], to figure out when it's time to refresh the cached copy ⏰

some authorities of registration data may team up to share their information for a common service, including mutual redirection [REDIRECT-RDAP] 🤝 it's giving collab era.

when a new object gets allocated, like a new AS range, a new TLD, or a new IP address range, there's NO guarantee that it will have an entry in the matching bootstrap RDAP registry. The RDAP server for that new entry might go live and get registered later, so it's not guaranteed. So clients should expect that even if an object such as a TLD, IP address range, or AS range is allocated, the entry may not exist in the corresponding bootstrap registry 🥲

9. Limitations 🙅‍♀️

this method doesn't give you a direct way to find authoritative RDAP servers for any objects other than the ones in this document. Specifically, these objects are NOT bootstrapped with this method:

  • entities
  • queries using search patterns that do not contain a terminating string that matches some entries in the registries
  • nameservers
  • help

10. Formal Definition 🎀

this section is the formal definition of the registries. The structure of JSON objects and arrays, built from a set of primitive elements, is defined in [RFC8259]. Those elements are then used to describe the JSON structure of the registries ✨

10.1. Imported JSON Terms 🧾

OBJECT:  a JSON object, defined in Section 4 of [RFC8259]

MEMBER:  a member of a JSON object, defined in Section 4 of [RFC8259]

MEMBER-NAME:  the name of a MEMBER, defined as a "string" in
   Section 4 of [RFC8259]

MEMBER-VALUE:  the value of a MEMBER, defined as a "value" in
   Section 4 of [RFC8259]

ARRAY:  an array, defined in Section 5 of [RFC8259]

ARRAY-VALUE:  an element of an ARRAY, defined in Section 5 of
   [RFC8259]

STRING:  a "string", as defined in Section 7 of [RFC8259]

10.2. Registry Syntax 🦋

using the terms above for the JSON structures, the syntax of a registry is defined like this 👇

rdap-bootstrap-registry:  an OBJECT containing a MEMBER version and a
   MEMBER publication, an optional MEMBER description, and a MEMBER
   services-list

version:  a MEMBER with MEMBER-NAME "version" and MEMBER-VALUE a
   STRING

publication:  a MEMBER with MEMBER-NAME "publication" and MEMBER-
   VALUE a STRING

description:  a MEMBER with MEMBER-NAME "description" and MEMBER-
   VALUE a STRING

services-list:  a MEMBER with MEMBER-NAME "services" and MEMBER-VALUE
   a services-array

services-array:  an ARRAY, where each ARRAY-VALUE is a service

service:  an ARRAY of 2 elements, where the first ARRAY-VALUE is an
   entry-list and the second ARRAY-VALUE is a service-uri-list

entry-list:  an ARRAY, where each ARRAY-VALUE is an entry

entry:  a STRING

service-uri-list:  an ARRAY, where each ARRAY-VALUE is a service-uri

service-uri:  a STRING

11. Security Considerations 🚨

this part is SERIOUS, bestie, so read it carefully 😭

by providing a bootstrap method to find RDAP servers, this document helps make sure end users get RDAP data from an authoritative source instead of rogue sources 🕵️‍♀️ The method has the same security properties as the RDAP protocols themselves. And the transport used to access the registries uses TLS [RFC8446] 🔐

additional considerations on using RDAP are described in [RFC7481] 💜

12. IANA Considerations ✨

okay so IANA made the RDAP Bootstrap Services Registries, which are basically the lookup lists everyone uses to find the right RDAP server 💖. They're listed below and posted as JSON objects 🎀. Sections 3, 4, and 5 explain what goes in them, and the formal syntax lives in Section 10 🧚. These registries MUST be accessible only through HTTPS (TLS [RFC8446]) transport 🔒. No plain HTTP, bestie.

The way these get updated is totally different from normal IANA registries 🙃. They're generated from the data, processes, and policies IANA already keeps in their allocation registries ([ipv4reg], [ipv6reg], [asreg], and [domainreg]), with the new RDAP server info added on top. IANA refreshes them whenever those allocation registries change ✨.

This document doesn't change any policies for the allocation registries 🙅‍♀️. IANA just built a mechanism for collecting the RDAP server info, and that's the whole glow-up.

IANA created a new top-level category on the Protocol Registries page at <https://www.iana.org/protocols> 🌈. It's called "Registration Data Access Protocol (RDAP)". Each RDAP Bootstrap Services Registry can be downloaded on demand as JSON by the general public, and each one's URI is listed right on that page 🍓.

Other normal registries will join this group later through other documents 🧁. The reason the URIs are listed clearly on the main page is so implementers can spot them easily. These are registries that software will access, but humans look at them for reference info too 🤖💜.

Because software is going to hit these hard, the download demand might be unusually high compared to normal IANA registries 😭. IANA put the technical infrastructure in place to handle the load. Since the publication of [RFC7484], no issues have been reported about the load or the service 💅.

As Section 8 explains, software that reads these registries leans on the HTTP Expires header field to limit how often it queries 🦋. So that header really matters. It has to be set properly to give timely updates as the registries change, while still keeping the load on IANA's servers reasonable 🫶.

The HTTP Content-Type returned to clients reading these JSON-formatted registries MUST be "application/json", as defined in [RFC8259] 📋.

Since the info is grouped and formatted the way it is, the registry entries might not be sortable 🙈. So it's not required or expected that the entries be ordered in any way. Vibes only, no sorting drama 💜.

12.1. Bootstrap Service Registry for IPv4 Address Space

Entries in this registry contain at least the following 🌸:

  • a CIDR [RFC4632] specification of the network block being registered
  • one or more URLs that provide the RDAP service regarding this registration

12.2. Bootstrap Service Registry for IPv6 Address Space

Entries in this registry contain at least the following 🌊:

  • an IPv6 prefix [RFC5952] specification of the network block being registered
  • one or more URLs that provide the RDAP service regarding this registration

12.3. Bootstrap Service Registry for AS Number Space

Entries in this registry contain at least the following 🔢:

  • a range of Autonomous System numbers being registered
  • one or more URLs that provide the RDAP service regarding this registration

12.4. Bootstrap Service Registry for Domain Name Space

Entries in this registry contain at least the following 🌐:

  • a domain name attached to the root being registered
  • one or more URLs that provide the RDAP service regarding this registration

13. References

13.1. Normative References

13.2. Informative References

Appendix A. Changes since RFC 7484

No big changes here, bestie! There are no substantive changes, just some minor clarifications 🧸. This update is mainly about meeting the requirements for moving to an Internet Standard 🏆.

Acknowledgements

The WEIRDS Working Group had lots of discussions on this topic, including a session during IETF 84, where people debated methods like in-DNS and others 🗣️. The idea of using IANA registries was discovered by the author while chatting with his colleagues, plus a comment from Andy Newton 💡. Everyone involved in these chats is acknowledged here 🫶.

Linlin Zhou, Jean-Philippe Dionne, John Levine, Kim Davies, Ernie Dainow, Scott Hollenbeck, Arturo Servin, Andy Newton, Murray Kucherawy, Tom Harrison, Naoki Kambe, Alexander Mayrhofer, Edward Lewis, Pete Resnick, Alessandro Vesely, Bert Greevenbosch, Barry Leiba, Jari Arkko, Kathleen Moriaty, Stephen Farrell, Richard Barnes, and Jean-Francois Tremblay gave input and suggestions to the first version of this document 🌟.

Guillaume Leclanche was a coauthor of this document for some revisions, and his support is acknowledged and greatly appreciated 💜. The section on formal definition was inspired by Section 6.2 of [RFC7071] 🧠. This new version [This document] got comments and suggestions from Gavin Brown, Patrick Mevzek, John Levine, Jasdip Singh, George Michaelson, Scott Hollenbeck, Russ Housley, Joel Halpern, Lars Eggert, Benjamin Kaduk, Scott Kelly, Éric Vyncke, John Scudder, Erik Kline, and Robert Wilton 🎀. Errata for RFC 7484 were submitted by Pieter Vandepitte and applied to this document ✨.

Author's Address

Marc Blanchet
Viagenie
246 Aberdeen
Quebec QC G1R 2E1
Canada
Email: Marc.Blanchet@viagenie.ca
URI:   https://viagenie.ca

That's a wrap on RFC 9224! 🌈💖

📦 where this page comes from