Internet-Draft RDAP RIR Search November 2023
Harrison & Singh Expires 25 May 2024 [Page]
Workgroup:
Internet Engineering Task Force
Internet-Draft:
draft-ietf-regext-rdap-rir-search-05
Published:
Intended Status:
Standards Track
Expires:
Authors:
T. Harrison
APNIC
J. Singh
ARIN

RDAP RIR Search

Abstract

The Registration Data Access Protocol (RDAP) is used by Regional Internet Registries (RIRs) and Domain Name Registries (DNRs) to provide access to their resource registration information. The core specifications for RDAP define basic search functionality, but there are various IP and ASN-related search options provided by RIRs via their Whois services for which there is no corresponding RDAP functionality. This document extends RDAP to support those search options.

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.

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

This Internet-Draft will expire on 25 May 2024.

▲

Table of Contents

1. Introduction

The Registration Data Access Protocol (RDAP) [RFC7480] is used by Regional Internet Registries (RIRs) and Domain Name Registries (DNRs) to provide access to their resource registration information. The core specifications for RDAP define basic search functionality, but this is limited to domains, nameservers, and entities. No searches were defined for IP networks or autonomous system numbers. In an effort to have RDAP reach feature parity with the existing RIR Whois services in this respect, this document defines additional search options for IP networks and autonomous system numbers.

While this document is in terms of RIRs and DNRs for the sake of consistency with earlier RDAP documents such as [RFC9082] and [RFC9083], the functionality described here may be used by any RDAP server operator that hosts Internet Number Resource (INR) objects, such as National Internet Registries (NIRs) or Local Internet Registries (LIRs).

1.1. 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 [RFC2119] [RFC8174].

2. Basic Searches

2.1. Path Segments

The new resource type path segments for basic search (similar to the searches defined in [RFC9082] and [RFC9083]) are:

Search path segments are formed using the same logic as in section 3.2 of [RFC9082].

Syntax: ips?handle=<handle search pattern>

Syntax: ips?name=<name search pattern>

Searches for IP network information by handle are specified using the form:

ips?handle=XXXX

XXXX is a search pattern representing an IP network identifier, the syntax for which is specific to the registration provider. The following URL would be used to find information for IP networks with handles matching the "NET-199*" pattern:

https://example.com/rdap/ips?handle=NET-199*

Searches for IP network information by name are specified using the form:

ips?name=XXXX

XXXX is a search pattern representing an IP network identifier that is assigned to the network registration by the registration holder. The following URL would be used to find information for IP networks with names matching the "NET-EXAMPLE-*" pattern:

https://example.com/rdap/ips?name=NET-EXAMPLE-*

2.3. Autonomous System Number Search

Syntax: autnums?handle=<handle search pattern>

Syntax: autnums?name=<name search pattern>

Searches for autonomous system number information by handle are specified using the form:

autnums?handle=XXXX

XXXX is a search pattern representing an autonomous system number identifier, the syntax for which is specific to the registration provider. The following URL would be used to find information for autonomous system numbers with handles matching the "AS1*" pattern:

https://example.com/rdap/autnums?handle=AS1*

Searches for autonomous system number information by name are specified using the form:

autnums?name=XXXX

XXXX is a search pattern representing an autonomous system number identifier that is assigned to the autonomous system number registration by the registration holder. The following URL would be used to find information for autonomous system numbers with names matching the "ASN-EXAMPLE-*" pattern:

https://example.com/rdap/autnums?name=ASN-EXAMPLE-*

3. Relation Searches

[RFC9083] contains example objects that make use of the "up" link relation in order to simplify the process of finding the parent object for a given object. This section defines searches for finding objects and sets of objects with respect to their position within a hierarchy.

3.1. Path Segments

The new resource type path segments for relation search (similar to the searches defined in [RFC9082] and [RFC9083]) are:

Syntax: <object class search path segment>/rirSearch1/<relation>/<object-value>[?status=<status>]

The relation searches defined in this document rely on the syntax described above. Each search works in the same way for each object type.

3.2.1. Definitions

An INR object value (i.e. an IP network address or range, autonomous system number or number range, or reverse domain name) may have a "parent" object and one or more "child" objects. The "parent" object is the next-least-specific object that exists in the relevant registry, while the "child" objects are the next-most-specific objects that exist in the relevant registry. For example, for a registry with the following seven IP network objects:

                        +--------------+
                        | 192.0.2.0/24 |
                        +--------------+
                           /        \
              +--------------+    +----------------+
              | 192.0.2.0/25 |    | 192.0.2.128/25 |
              +--------------+    +----------------+
                 /                   /          \
     +--------------+   +----------------+  +----------------+
     | 192.0.2.0/28 |   | 192.0.2.128/26 |  | 192.0.2.192/26 |
     +--------------+   +----------------+  +----------------+
        /
 +--------------+
 | 192.0.2.0/32 |
 +--------------+
Figure 1: Example Registry Objects

the INR object value to parent/child object relationships are:

Table 1: Parent objects
INR object value Parent object
192.0.2.0/32 192.0.2.0/28
192.0.2.0/28 192.0.2.0/25
192.0.2.64/26 192.0.2.0/25
192.0.2.128/26 192.0.2.128/25
192.0.2.192/26 192.0.2.128/25
192.0.2.128/25 192.0.2.0/24
192.0.2.0/25 192.0.2.0/24
192.0.2.0/24 N/A
Table 2: Child objects
INR object value Child objects
192.0.2.0/24 192.0.2.0/25, 192.0.2.128/25
192.0.2.0/25 192.0.2.0/28
192.0.2.128/25 192.0.2.128/26, 192.0.2.192/26
192.0.2.64/26 N/A
192.0.2.128/26 N/A
192.0.2.192/26 N/A
192.0.2.0/28 192.0.2.0/32
192.0.2.0/32 N/A

Along similar lines, each INR object value may have a "top" object, being the least-specific covering object that exists in the registry, and one or more "bottom" objects, being the most-specific objects that entirely cover the INR object value when taken together. Given the registry defined in the previous paragraph, the top and bottom object relationships are:

Table 3: Top objects
INR object value Top object
192.0.2.0/32 192.0.2.0/24
192.0.2.0/28 192.0.2.0/24
192.0.2.64/26 192.0.2.0/24
192.0.2.128/26 192.0.2.0/24
192.0.2.192/26 192.0.2.0/24
192.0.2.128/25 192.0.2.0/24
192.0.2.0/25 192.0.2.0/24
192.0.2.0/24 N/A
Table 4: Bottom objects
INR object value Bottom objects
192.0.2.0/24 192.0.2.0/25, 192.0.2.0/28, 192.0.2.0/32, 192.0.2.128/26, 192.0.2.192/26
192.0.2.0/25 192.0.2.0/25, 192.0.2.0/28, 192.0.2.0/32
192.0.2.128/25 192.0.2.128/26, 192.0.2.192/26
192.0.2.64/26 N/A
192.0.2.128/26 N/A
192.0.2.192/26 N/A
192.0.2.0/28 192.0.2.0/28, 192.0.2.0/32
192.0.2.0/31 192.0.2.0/28, 192.0.2.0/32
192.0.2.0/32 N/A

If there are no more-specific objects for a given INR object value, then the set of bottom objects for that INR object value will be empty. 192.0.2.0/32 is an example of such an INR object value.

It is not necessarily the case that the bottom objects for a given INR object value will be disjoint. For example, 192.0.2.0/28's bottom objects are 192.0.2.0/28 and 192.0.2.0/32. 192.0.2.0/32 is included because it is a most-specific object (i.e. an object at the bottom of the object hierarchy) for 192.0.2.0/28, while 192.0.2.0/28 itself is included because it is the most-specific object for the other addresses within the range (i.e. those aside from 192.0.2.0/32).

The bottom objects for a given INR object value may include an object that is less-specific than that INR object value. For example, 192.0.2.0/31 is an INR object value that has a more-specific object, being 192.0.2.0/32, so the set of bottom objects must include at least that object. The most-specific object that covers the residual (i.e. 192.0.2.1/32) is 192.0.2.0/28, so it is included in the results as well.

3.2.2. Relations

3.2.2.1. up

If the server receives a search containing the relation value "up", it will return the parent object for the specified INR object value. If no such object exists, it will return an empty search response.

3.2.2.2. down

If the server receives a search containing the relation value "down", it will return the child objects for the specified INR object value. If no such objects exist, it will return an empty search response. Per the definitions section, this includes only immediate child objects.

3.2.2.3. top

If the server receives a search containing the relation value "top", it will return the top object for the specified INR object value. If no such object exists, it will return an empty search response.

3.2.2.4. bottom

If the server receives a search containing the relation value "bottom", it will return the bottom objects for the specified INR object value. If no such objects exist, it will return an empty search response.

3.3. Status

If the "status" argument is provided, then response processing will proceed as though all objects without the specified status had first been removed from the database. For example, if the registry objects from section 3.2.1 had the following statuses:

Table 5: Statuses
Object Status
192.0.2.0/25 active
192.0.2.128/25 inactive
192.0.2.128/26 active
192.0.2.192/26 active

then a server receiving a "child" object query with the INR object value 192.0.2.0/24 and a "status" argument of "active" would return the objects 192.0.2.0/25, 192.0.2.128/26, and 192.0.2.192/26.

Status filtering is useful, for example, where the client is trying to find the delegation from an RIR to an RIR account holder: by using the "top" relation with a "status" of "active", the delegation from IANA to the RIR will be ignored, and the client will receive the delegation from the RIR to the account holder in the response instead.

Server operators MAY opt not to support "status" processing for the "down" and "bottom" link relations, in which case the server should respond with a HTTP 501 (Not Implemented) [RFC9110] response code if they receive such a request.

Each of the relations defined in section 3.2.2 has a corresponding link relation that can be used for a link object contained within another RDAP object. The response returned by a server when fetching the link target for a link within an RDAP object with one of those link relations MUST be the same response that would be returned for the corresponding search. For example:

Two additional link relations are defined that correspond to relation searches with a "status" of "active": "top-active" and "up-active". The equivalent link relations for "down" and "bottom" are not defined, because it is not expected that they will be used.

Since the "top" and "up" link relations resolve to a single object, it is possible to simply include that object's link in the "href" attribute in the link object. For example:

This section mandates specific behaviour for the "up" link relation, but does not define that link relation (see [RFC8288]). The specific behaviour is for the RDAP INR context only, though, and in that context it does not conflict with the current description of that link relation.

Use of these link relations in responses is OPTIONAL. The absence in a response of a link for a specific relation does not necessarily mean that the corresponding object does not exist or that the corresponding search will return no results.

4. Responding To Searches

As with [RFC9083], responses to the IP network and autonomous system number searches defined in the previous sections take the form of an array of object instances, where each instance is an appropriate object class for the search (i.e., a search beginning with /ips yields an array of IP network object instances, and a search beginning with /autnums yields an array of autonomous system number object instances). These arrays are contained within the response object.

The names of the arrays are as follows:

The following is an elided example of a response to an IP network search:

{
  "rdapConformance": [ "rdap_level_0", "rirSearch1",
                       "ips", "autnums",
                       "ipSearchResults",
                       "autnumSearchResults", ... ],
  ...
  "ipSearchResults": [
    {
      "objectClassName": "ip network",
      "handle": "XXXX-RIR",
      "startAddress": "192.0.2.0",
      "endAddress": "192.0.2.127",
      ...
    },
    {
      "objectClassName": "ip network",
      "handle": "YYYY-RIR",
      "startAddress": "192.0.2.0",
      "endAddress": "192.0.2.255",
      ...
    }
  ]
}

The following is an elided example of a response to an autonomous system number search:

{
  "rdapConformance": [ "rdap_level_0", "rirSearch1",
                       "ips", "autnums",
                       "ipSearchResults",
                       "autnumSearchResults", ... ],
  ...
  "autnumSearchResults": [
    {
      "objectClassName": "autnum",
      "handle": "XXXX-RIR",
      "startAutnum": 64496,
      "endAutnum": 64496,
      ...
    },
    {
      "objectClassName": "autnum",
      "handle": "YYYY-RIR",
      "startAddress": "64497",
      "endAddress": "64497",
      ...
    }
  ]
}

Responses for relation searches for reverse domain objects have the same form as for a standard domain search response, per [RFC9083].

If the search is able to be processed by the server, but there are no results for the search, then the server returns a HTTP 200 (OK) response code, with the body of the response containing an empty results array.

RDAP reverse search is defined by [I-D.ietf-regext-rdap-reverse-search]. That document limits reverse search to domains, nameservers, and entities. This document extends reverse search to cover IP networks and autonomous system numbers as well.

If a server receives a reverse search query with a searchable resource type (per the definition of that term in [I-D.ietf-regext-rdap-reverse-search]) of "ips", then the reverse search will be performed on the IP network objects from its data store. Similarly, if a server receives a reverse search query with a searchable resource type of "autnums", then the reverse search will be performed on the autonomous system number objects from its data store.

Additionally, Section 9 includes requests to register new entries for IP network and autonomous system number searches in the RDAP Reverse Search and RDAP Reverse Search Mapping IANA registries.

6. RDAP Conformance

A server that supports the functionality specified in this document MUST include the string literals "rirSearch1", "ips", "autnums", "ipSearchResults", and "autnumSearchResults" in the rdapConformance array in their response objects.

The "ips", "autnums", "ipSearchResults", and "autnumSearchResults" extension identifiers are included here due to the requirements set out in [RFC7480], [RFC9082], and [RFC9083] that an RDAP extension identifier be used as a prefix in new path segments and JSON members introduced by the extension, and those strings are used as such as part of the basic searches defined in this document. Furthermore, using these strings as path segments helps to increase consistency among the basic searches for the core RDAP object types.

As with the other core object classes (entity, domain, and nameserver), other documents may define additional reverse searches with IP networks and ASNs as the searchable resource type by registering those in the IANA RDAP reverse search registries. Because a given extension identifier must correspond to a single extension, though, any document making use of IP networks or ASNs as the searchable resource type must also implement the functionality described in this document.

7. Privacy Considerations

The search functionality defined in this document may affect the privacy of entities in the registry (and elsewhere) in various ways: see [RFC6973] for a general treatment of privacy in protocol specifications. Server operators should be aware of the tradeoffs that result from implementation of this functionality.

Many jurisdictions have laws or regulations that restrict the use of "Personal Data", per the definition in [RFC6973]. Given that, server operators should ascertain whether the regulatory environment in which they operate permits implementation of the functionality defined in this document.

8. Security Considerations

[RFC7481] describes security requirements and considerations for RDAP generally.

9. IANA Considerations

9.1. RDAP Extensions Registry

IANA is requested to register the following values in the RDAP Extensions Registry:

  • Extension identifier: rirSearch1

  • Registry operator: Any

  • Published specification: [this document]

  • Contact: IETF <iesg@ietf.org>

  • Intended usage: This extension identifier is used for INR-specific search operations.

  • Extension identifier: ips

  • Registry operator: Any

  • Published specification: [this document]

  • Contact: IETF <iesg@ietf.org>

  • Intended usage: This extension identifier is used for INR-specific search operations.

  • Extension identifier: autnums

  • Registry operator: Any

  • Published specification: [this document]

  • Contact: IETF <iesg@ietf.org>

  • Intended usage: This extension identifier is used for INR-specific search operations.

  • Extension identifier: ipSearchResults

  • Registry operator: Any

  • Published specification: [this document]

  • Contact: IETF <iesg@ietf.org>

  • Intended usage: This extension identifier is used for INR-specific search operations.

  • Extension identifier: autnumSearchResults

  • Registry operator: Any

  • Published specification: [this document]

  • Contact: IETF <iesg@ietf.org>

  • Intended usage: This extension identifier is used for INR-specific search operations.

IANA is requested to register the following values in the Link Relations Registry:

  • Relation Name: up-active

  • Description: Refers to an RDAP parent document that has a status of "active" in a hierarchy of documents.

  • Reference: [this document]

  • Relation Name: down

  • Description: Refers to a set of child documents in a hierarchy of documents.

  • Reference: [this document]

  • Relation Name: top

  • Description: Refers to the topmost parent document in a hierarchy of documents.

  • Reference: [this document]

  • Relation Name: top-active

  • Description: Refers to the topmost RDAP parent document that has a status of "active" in a hierarchy of documents.

  • Reference: [this document]

  • Relation Name: bottom

  • Description: Refers to the set of child documents that do not themselves have child documents, in a hierarchy of documents.

  • Reference: [this document]

9.3. RDAP Reverse Search Registry

IANA is requested to register the following entries in the "RDAP Reverse Search" registry:

Searchable Resource Type:
ips, autnums
Related Resource Type:
entity
Property:
fn
Description:
The server supports the IP/autnum search based on the full name (a.k.a formatted name) of an associated entity.
Registrant Name:
IETF
Registrant Contact Information:
iesg@ietf.org
Reference:
This document.
Searchable Resource Type:
ips, autnums
Related Resource Type:
entity
Property:
handle
Description:
The server supports the IP/autnum search based on the handle of an associated entity.
Registrant Name:
IETF
Registrant Contact Information:
iesg@ietf.org
Reference:
This document.
Searchable Resource Type:
ips, autnums
Related Resource Type:
entity
Property:
email
Description:
The server supports the IP/autnum search based on the email address of an associated entity.
Registrant Name:
IETF
Registrant Contact Information:
iesg@ietf.org
Reference:
This document.
Searchable Resource Type:
ips, autnums
Related Resource Type:
entity
Property:
role
Description:
The server supports the IP/autnum search based on the role of an associated entity.
Registrant Name:
IETF
Registrant Contact Information:
iesg@ietf.org
Reference:
This document.

9.4. RDAP Reverse Search Mapping Registry

IANA is requested to register the following entries in the "RDAP Reverse Search Mapping" registry:

Searchable Resource Type:
ips, autnums
Related Resource Type:
entity
Property:
fn
Property Path:
$..entities[*].vcardArray[1][?(@[0]=='fn')][3]
Registrant Name:
IETF
Registrant Contact Information:
iesg@ietf.org
Reference:
This document.
Searchable Resource Type:
ips, autnums
Related Resource Type:
entity
Property:
handle
Property Path:
$..entities[*].handle
Registrant Name:
IETF
Registrant Contact Information:
iesg@ietf.org
Reference:
This document.
Searchable Resource Type:
ips, autnums
Related Resource Type:
entity
Property:
email
Property Path:
$..entities[*].vcardArray[1][?(@[0]=='email')][3]
Registrant Name:
IETF
Registrant Contact Information:
iesg@ietf.org
Reference:
This document.
Searchable Resource Type:
ips, autnums
Related Resource Type:
entity
Property:
role
Property Path:
$..entities[*].roles
Registrant Name:
IETF
Registrant Contact Information:
iesg@ietf.org
Reference:
This document.

10. Acknowledgements

The authors wish to thank Mario Loffredo, Andy Newton, Antoin Verschuren, and James Gould for document review and associated comments.

11. References

11.1. Normative References

Loffredo, M. and M. Martinelli, "Registration Data Access Protocol (RDAP) Reverse Search", Work in Progress, Internet-Draft, draft-ietf-regext-rdap-reverse-search-26, , <https://datatracker.ietf.org/doc/html/draft-ietf-regext-rdap-reverse-search-26>.
[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/info/rfc2119>.
[RFC7481]
Hollenbeck, S. and N. Kong, "Security Services for the Registration Data Access Protocol (RDAP)", STD 95, RFC 7481, DOI 10.17487/RFC7481, , <https://www.rfc-editor.org/info/rfc7481>.
[RFC8174]
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/info/rfc8174>.
[RFC9082]
Hollenbeck, S. and A. Newton, "Registration Data Access Protocol (RDAP) Query Format", STD 95, RFC 9082, DOI 10.17487/RFC9082, , <https://www.rfc-editor.org/info/rfc9082>.
[RFC9083]
Hollenbeck, S. and A. Newton, "JSON Responses for the Registration Data Access Protocol (RDAP)", STD 95, RFC 9083, DOI 10.17487/RFC9083, , <https://www.rfc-editor.org/info/rfc9083>.
[RFC9110]
Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110, , <https://www.rfc-editor.org/info/rfc9110>.

11.2. Informative References

[RFC6973]
Cooper, A., Tschofenig, H., Aboba, B., Peterson, J., Morris, J., Hansen, M., and R. Smith, "Privacy Considerations for Internet Protocols", RFC 6973, DOI 10.17487/RFC6973, , <https://www.rfc-editor.org/info/rfc6973>.
[RFC7480]
Newton, A., Ellacott, B., and N. Kong, "HTTP Usage in the Registration Data Access Protocol (RDAP)", STD 95, RFC 7480, DOI 10.17487/RFC7480, , <https://www.rfc-editor.org/info/rfc7480>.
[RFC8288]
Nottingham, M., "Web Linking", RFC 8288, DOI 10.17487/RFC8288, , <https://www.rfc-editor.org/info/rfc8288>.

Authors' Addresses

Tom Harrison
Asia Pacific Network Information Centre
6 Cordelia St
South Brisbane QLD 4101
Australia
Jasdip Singh
American Registry for Internet Numbers
PO Box 232290
Centreville, VA 20120
United States of America