Internet DRAFT - draft-ietf-regext-rdap-rir-search
draft-ietf-regext-rdap-rir-search
Internet Engineering Task Force T. Harrison
Internet-Draft APNIC
Updates: RFC7480, RFC9082, RFC9083 (if approved) J. Singh
Intended status: Standards Track ARIN
Expires: 7 September 2023 6 March 2023
RDAP RIR Search
draft-ietf-regext-rdap-rir-search-01
Abstract
The Registration Data Access Protocol (RDAP) is used by Internet
Number Resource (INR) registries and domain name registries 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 INR
registries 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 7 September 2023.
Copyright Notice
Copyright (c) 2023 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) 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. Code Components
Harrison & Singh Expires 7 September 2023 [Page 1]
Internet-Draft RDAP RIR Search March 2023
extracted from this document must include Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Requirements Language . . . . . . . . . . . . . . . . . . 2
2. Search Path Segment Specification . . . . . . . . . . . . . . 2
2.1. IP Network Search . . . . . . . . . . . . . . . . . . . . 3
2.2. Autonomous System Number Search . . . . . . . . . . . . . 3
3. Responding To Searches . . . . . . . . . . . . . . . . . . . 4
4. Link Relations . . . . . . . . . . . . . . . . . . . . . . . 4
5. Reverse Search . . . . . . . . . . . . . . . . . . . . . . . 6
6. RDAP Conformance . . . . . . . . . . . . . . . . . . . . . . 6
7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 7
8. Security Considerations . . . . . . . . . . . . . . . . . . . 7
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7
10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 10
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 10
11.1. Normative References . . . . . . . . . . . . . . . . . . 10
11.2. Informative References . . . . . . . . . . . . . . . . . 11
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11
1. Introduction
The Registration Data Access Protocol (RDAP) [RFC7480] is used by
Internet Number Resource (INR) registries and domain name registries
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 INR
Whois services in this respect, this document defines additional
search options for IP networks and autonomous system numbers, along
with an additional link relation for finding more-specific resources.
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. Search Path Segment Specification
The new resource type path segments for search are:
Harrison & Singh Expires 7 September 2023 [Page 2]
Internet-Draft RDAP RIR Search March 2023
'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.
Search path segments are formed using the same logic as in section
3.2 of [RFC9082].
2.1. IP Network Search
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.2. 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:
Harrison & Singh Expires 7 September 2023 [Page 3]
Internet-Draft RDAP RIR Search March 2023
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. Responding To Searches
As with [RFC9083], responses to the IP network and autonomous system
number searches defined in the previous section take the form of an
array of object instances, where each instance is an appropriate
object class for the search (i.e., a search for /ips yields an array
of IP network object instances, and a search for /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:
for /ips searches, the array is "ipSearchResults"; and
for /autnums searches, the array is "autnumSearchResults".
4. Link Relations
An IP network, autonomous system number, or reverse domain object 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 four IP network objects:
192.0.2.0/24
Harrison & Singh Expires 7 September 2023 [Page 4]
Internet-Draft RDAP RIR Search March 2023
192.0.2.0/25
192.0.2.128/25
192.0.2.0/32
the parent object of 192.0.2.0/32 would be 192.0.2.0/25, the parent
object of 192.0.2.128/25 would be 192.0.2.0/24, the parent object of
192.0.2.0/25 would be 192.0.2.0/24, and 192.0.2.0/24 would have no
parent object. Conversely, the child objects for 192.0.2.0/24 would
be 192.0.2.0/25 and 192.0.2.128/25, for 192.0.2.0/25 192.0.2.0/32,
and for 192.0.2.128/25 and 192.0.2.0/32 there would be no child
objects.
In order to permit clients to locate the parent object for a given
object, an operator includes a link using the "up" link relation that
links to the parent object. Similarly, in order to permit clients to
locate the child objects for a given object, an operator includes a
link using the "down" link relation that when resolved, returns a
response that has the same format as a search for the relevant object
type containing all of the child objects for that object. For
example:
{
...
"links": [
...,
{
"value": "http://rdap.example.com/ip/192.0.2.0/25",
"rel": "up",
"href": "http://rdap.example.com/ip/192.0.2.0/24",
"type": "application/rdap+json"
},
{
"value": "http://rdap.example.com/ip/192.0.2.0/25",
"rel": "down",
"href": "http://rdap.example.com/ip-down/192.0.2.0/25",
"type": "application/rdap+json"
}
]
}
In the example above, the link target for the link with the "down"
relation is "http://rdap.example.com/ip-down/192.0.2.0/25". However,
the link structure used by a server for these links is not defined by
this specification, and clients MUST NOT make inferences about
supported behaviour by inspecting the structure of these links.
Harrison & Singh Expires 7 September 2023 [Page 5]
Internet-Draft RDAP RIR Search March 2023
An operator MUST NOT include a link with an "up" link relation in an
object if that object has no parent object. Similarly, an operator
MUST NOT include a link with a "down" link relation in an object if
that object has no child objects. This permits clients to rely on
the absence of a given link relation as determinative of the question
whether the object has any related objects of that type.
5. Reverse Search
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 all of the functionality specified in this
document MUST include the string literal "inr_search" in the
rdapConformance array in their response objects.
[RFC7480], [RFC9082] and [RFC9083] collectively require that an RDAP
extension identifier be used as a prefix in new path segments and
response object members that are introduced by the extension.
Because IP network objects and autonomous system number objects are
part of the original set of object types defined for use in RDAP, it
may be unintuitive or confusing for users if the searches and
associated responses defined here include the "inr_search" extension
prefix, since the searches and associated responses for the other
original object types do not include a prefix. Therefore, the
extension identifier is not used as a prefix in this document. Since
this is not in keeping with the requirements of those earlier
documents, this document is marked as updating those documents.
Harrison & Singh Expires 7 September 2023 [Page 6]
Internet-Draft RDAP RIR Search March 2023
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. Registry 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,
registry 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
IANA is requested to register the following value in the RDAP
Extensions Registry:
* Extension identifier: inr_search
* 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 also requested to register the following value in the Link
Relations Registry:
* Relation Name: down
* Description: Refers to a set of child documents in a hierarchy of
documents.
* Reference: [this document]
IANA is also requested to register the following entries in the "RDAP
Reverse Search" registry:
Harrison & Singh Expires 7 September 2023 [Page 7]
Internet-Draft RDAP RIR Search March 2023
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: IESG
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: IESG
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: IESG
Registrant Contact Information: iesg@ietf.org
Reference: This document.
Searchable Resource Type: ips, autnums
Related Resource Type: entity
Harrison & Singh Expires 7 September 2023 [Page 8]
Internet-Draft RDAP RIR Search March 2023
Property: role
Description: The server supports the IP/autnum search based on the
role of an associated entity.
Registrant Name: IESG
Registrant Contact Information: iesg@ietf.org
Reference: This document.
IANA is also 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: IESG
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: IESG
Registrant Contact Information: iesg@ietf.org
Reference: This document.
Searchable Resource Type: ips, autnums
Related Resource Type: entity
Property: email
Harrison & Singh Expires 7 September 2023 [Page 9]
Internet-Draft RDAP RIR Search March 2023
Property Path: $..entities[*].vcardArray[1][?(@[0]=='email')][3]
Registrant Name: IESG
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: IESG
Registrant Contact Information: iesg@ietf.org
Reference: This document.
10. Acknowledgements
TBD
11. References
11.1. Normative References
[I-D.ietf-regext-rdap-reverse-search]
Loffredo, M. and M. Martinelli, "Registration Data Access
Protocol (RDAP) Reverse search capabilities", Work in
Progress, Internet-Draft, draft-ietf-regext-rdap-reverse-
search-14, 3 October 2022,
<https://datatracker.ietf.org/doc/html/draft-ietf-regext-
rdap-reverse-search-14>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<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, March 2015,
<https://www.rfc-editor.org/info/rfc7481>.
Harrison & Singh Expires 7 September 2023 [Page 10]
Internet-Draft RDAP RIR Search March 2023
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <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, June 2021,
<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, June 2021,
<https://www.rfc-editor.org/info/rfc9083>.
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, July 2013,
<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, March 2015,
<https://www.rfc-editor.org/info/rfc7480>.
Authors' Addresses
Tom Harrison
Asia Pacific Network Information Centre
6 Cordelia St
South Brisbane QLD 4101
Australia
Email: tomh@apnic.net
Jasdip Singh
American Registry for Internet Numbers
PO Box 232290
Centreville, VA 20120
United States of America
Email: jasdips@arin.net
Harrison & Singh Expires 7 September 2023 [Page 11]
