RDAP RIR Search

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 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 and , the functionality described here may be used by any RDAP server operator that hosts Internet Number Resource (INR) objects.

Conventions Used in This Document The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here. Indentation and whitespace in examples are provided only to illustrate element relationships, and are not a REQUIRED feature of this protocol. "..." in examples is used as shorthand for elements defined outside of this document.

The new resource type path segments for basic search (similar to the searches defined in and ) are: 'ips': Used to identify an IP network search using a pattern to match one of a set of IP network attributes. 'autnums': Used to identify an autonomous system number search using a pattern to match one of a set of autonomous system number attributes. A search pattern matches a value where it equals the string representation of the value, or where it is a match for the value in accordance with the use of the asterisk ('*', US-ASCII value 0x2A) character for partial string matching as defined in section 4.1 of . For most searches, '*' may be used to match trailing characters only, and may appear in a search only once: please see the previously-mentioned section for a complete definition of the relevant behaviour.

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 whose syntax is specific to the registration provider (see section 5.4 of ). 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 (see section 5.4 of ). 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-*

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 whose syntax is specific to the registration provider (see section 5.5 of ). 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 (see section 5.5 of ). 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-*

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.

The variables used in the path segments include: <relation>: A relation type, as defined in Section 3.2.2 of this document. <IP address>: An IP address, as defined in Section 3.1.1 of . <CIDR prefix>: The first address of a CIDR block, as defined in Section 3.1.1 of . <CIDR length>: The prefix length for a CIDR block, as defined in Section 3.1.1 of . <domain name>: A fully-qualified domain name, as defined in Section 3.1.3 of . <autonomous system number or range>: An autonomous system number, as defined in Section 3.1.2 of , or two such numbers separated by a single hyphen ('-', US-ASCII value 0x2D), where the second number is greater than the first. <resource type search path segment>: A search path segment corresponding to an Internet Number Resource (INR) object class (i.e. an IP network address or range, autonomous system number or number range, or reverse domain name). <object value>: a value used to identify an object for the purposes of a relation search relative to that object. One of <IP address>, <CIDR prefix> and <CIDR length> pair, <domain name>, or <autonomous system number or range>, depending on the type of search that is being performed. <status>: an object status value, as defined in Section 4.6 of . The new resource type path segments for relation search (similar to the searches defined in and ) are: 'ips/rirSearch1/<relation>/<IP address>': Used to identify an IP network search using a relation and an address to match a set of IP networks. 'ips/rirSearch1/<relation>/<CIDR prefix>/<CIDR length>': Used to identify an IP network search using a relation and a range to match a set of IP networks. 'autnums/rirSearch1/<relation>/<autonomous system number or range>': Used to identify an autonomous system number search using a relation and a single ASN or an ASN range to match a set of ASN objects. 'domains/rirSearch1/<relation>/<domain name>': Used to identify a reverse domain search using a relation and a reverse domain name to match a set of reverse domains.

Syntax: <resource type 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 class.

An INR object value 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:

Example registry objects the INR object value to parent/child object relationships are: 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.0/25	192.0.2.0/24
192.0.2.128/25	192.0.2.0/24
192.0.2.0/24	N/A

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

(INR object values do not necessarily correspond to registry objects, because users can provide arbitrary object values as input to the searches defined in this document.) Similarly to the parent/child object relationships, 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: 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.0/25	192.0.2.0/24
192.0.2.128/25	192.0.2.0/24
192.0.2.0/24	N/A

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 one of the most-specific objects (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.

If the server receives a search containing the relation value "up", it will return the parent object for the specified INR object value as though that object had been requested directly. If no such object exists, it will respond with a HTTP 404 (Not Found) search response.

If the server receives a search containing the relation value "top", it will return the top object for the specified INR object value as though that object had been requested directly. If no such object exists, it will respond with an HTTP 404 (Not Found) search response.

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.

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.

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: 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 "down" search request 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. By default, any valid status value may be used for status filtering. Server operators MAY opt not to support "status" filtering for the "down" and "bottom" link relations, in which case the server should respond with an HTTP 501 (Not Implemented) response code if it receives such a request. Server operators MAY also opt not to support "status" filtering for values other than "active" for the "up" and "top" link relations, in which case the server should respond with an HTTP 501 (Not Implemented) response code if it receives 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. When constructing these link objects, the server MUST use the corresponding search URL for the link target, or a URL that yields the same response as for the corresponding search as at the time of the request. The following is an elided example of a response that makes use of those link relations:

Example links Two additional link relations are defined that correspond to relation searches with a "status" of "active": "up-active" and "top-active". No other status-specific link relations are defined, because the only known use cases for status filtering involve the "up" and "top" relations and the "active" status. The following is an elided example of a response that makes use of those link relations:

Example status links Since the "top" and "up" link relations resolve either to a single object or to an HTTP 404 (Not Found) response, it is possible for a server to use a lookup URL (see section 3.1 of ) in the "href" attribute in the link object. The following is an elided example of a response that uses this approach:

Example single-result links This section mandates specific behaviour for the "up" link relation, but does not define that link relation (see ). This is acceptable, because this behaviour: does not conflict with the current description of the link relation; and is not generally applicable, but instead limited to the context of RDAP INR objects only. 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 search will return no results.

The "up" and "top" relations are single-result searches. When processing these searches, if there is a result for the search, the server returns that object as though it were requested directly via a lookup URL (see section 3.1 of ). If there is no result for the search, the server returns an HTTP 404 (Not Found) response code.

The "down" and "bottom" relations are multiple-result searches. As with , responses for these searches 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). The IP network object and autonomous system number object classes are defined in sections 5.4 and 5.5 of . The object instance arrays are contained within the response object. The names of the arrays are as follows: for /ips searches, the array is "ipSearchResults"; and for /autnums searches, the array is "autnumSearchResults". The following is an elided example of a response to an IP network search:

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

ASN search response Responses for relation searches for reverse domain objects have the same form as for a standard domain search response, per . If the search can be processed by the server, but there are no results for the search, then the server returns an HTTP 200 (OK) response code, with the body of the response containing an empty results array.

RDAP reverse search is defined by . 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 ) 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, 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.

A server that supports the functionality specified in this document MUST include additional string literals in the rdapConformance array of its responses, in accordance with the following: any response that includes an IP network basic search link, an IP network relation search link, or an IP network reverse search link, includes the "rirSearch1" and "ips" literals; any response for an IP network basic search request, an IP network relation search request, or an IP network reverse search request includes the "rirSearch1", "ips", and "ipSearchResults" literals; any response that includes an ASN basic search link, an ASN relation search link, or an ASN reverse search link includes the "rirSearch1" and "autnums" literals; any response for an ASN basic search request, an ASN relation search request, or an ASN reverse search request includes the "rirSearch1", "autnums", and "autnumSearchResults" literals; any response that includes a domain relation search link includes the "rirSearch1" literal; any response for a domain relation search request includes the "rirSearch1" literal; and a response to a "/help" request includes the "rirSearch1", "ips", "ipSearchResults", "autnums", and "autnumSearchResults" literals. Although responses will generally not include all of the rdapConformance string literals defined in this document, that is not meant to imply that a server can support only a portion of the functionality defined in this document. The "ips", "autnums", "ipSearchResults", and "autnumSearchResults" extension identifiers are included here due to the requirements set out in , , and . These requirements are 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 classes. 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.

When using a link object for a single-result search, a server may replace a search URL with a lookup URL, because the behaviour of the lookup URL is the same as for the search URL as at the time when the response is generated. One difference between these approaches is that when using the lookup URL, the server is effectively performing the search on behalf of the client as at the time of response generation. If there is no change to the relevant database state between the time when the original response is generated and the time when the client resolves the link relation target, then the search URL and the lookup URL will lead to the same result. However, if there is a change to the relevant database state, then the lookup URL may lead to a different result from that of the search URL. Server operators should consider which type of URL will be more effective for their clients when implementing this specification.

The search functionality defined in this document may affect the privacy of entities in the registry (and elsewhere) in various ways: see 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 . Given that, server operators should ascertain whether the regulatory environment in which they operate permits implementation of the functionality defined in this document.

describes security requirements and considerations for RDAP generally. includes security considerations relating to object retrieval in RDAP. Those considerations are relevant here as well.

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]

IANA is requested to register the following entries in the "RDAP Reverse Search" registry: ips, autnums entity fn The server supports the IP/autnum search based on the full name (a.k.a formatted name) of an associated entity. IETF iesg@ietf.org This document. ips, autnums entity handle The server supports the IP/autnum search based on the handle of an associated entity. IETF iesg@ietf.org This document. ips, autnums entity email The server supports the IP/autnum search based on the email address of an associated entity. IETF iesg@ietf.org This document. ips, autnums entity role The server supports the IP/autnum search based on the role of an associated entity. IETF iesg@ietf.org This document.

IANA is requested to register the following entries in the "RDAP Reverse Search Mapping" registry: ips, autnums entity fn $..entities[*].vcardArray[1][?(@[0]=='fn')][3] IETF iesg@ietf.org This document. ips, autnums entity handle $..entities[*].handle IETF iesg@ietf.org This document. ips, autnums entity email $..entities[*].vcardArray[1][?(@[0]=='email')][3] IETF iesg@ietf.org This document. ips, autnums entity role $..entities[*].roles IETF iesg@ietf.org This document.

Implementation Status This section records the status of known implementations of the protocol defined by this specification at the time of posting of this Internet-Draft, and is based on a proposal described in . The description of implementations in this section is intended to assist the IETF in its decision processes in progressing drafts to RFCs. Please note that the listing of any individual implementation here does not imply endorsement by the IETF. Furthermore, no effort has been spent to verify the information presented here that was supplied by IETF contributors. This is not intended as, and must not be construed to be, a catalogue of available implementations or their features. Readers are advised to note that other implementations may exist. According to , "this will allow reviewers and working groups to assign due consideration to documents that have the benefit of running code, which may serve as evidence of valuable experimentation and feedback that have made the implemented protocols more mature. It is up to the individual working groups to use this information as they see fit".

Responsible Organization: Asia-Pacific Network Information Centre (APNIC) Location: https://github.com/APNIC-net/rdap-rmp-demo/tree/rir-search Description: This implementation includes support for the various searches and responses described in this document. Level of Maturity: This is a proof-of-concept implementation. Coverage: This implementation includes all of the features described in this specification. Contact Information: Tom Harrison, tomh@apnic.net

Responsible Organization: RIPE NCC Location: https://github.com/RIPE-NCC/whois Description: This implementation includes support for basic searches for IP networks and ASNs. Level of Maturity: This is a production implementation. Coverage: This implementation includes the new basic searches only. Contact Information: Ed Shryane, eshryane@ripe.net

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