Registration Data Access Protocol (RDAP) Reverse Search
Extracted elements (28)
Reverse WHOIS was objected to historically on privacy and performance grounds, but RDAP's HTTP-based authentication/authorization infrastructure addresses the privacy concern, and the core RDAP specs already define search queries with similar processing requirements, negating the performance objection.
The "reverse_search_properties_mapping" member is included in the search response rather than the help response because the mapping may differ depending on the specific query sent; this per-query disclosure also remains valid even if new mappings are registered after the help response was cached.
Two separate IANA registries ("RDAP Reverse Search" and "RDAP Reverse Search Mapping") are used because a single type of reverse search may rely on different members depending on the server's configuration, allowing multiple mappings for the same reverse search property.
Servers are RECOMMENDED to use indexes or similar techniques to speed up data retrieval for reverse searches. Performance risks can also be mitigated by restricting search functionality, rate-limiting by user authorization, truncating/paging results (RFC 8977), and returning partial responses (RFC 8982).
All mappings for a reverse search property MUST point to response fields with the same meaning; registrants SHOULD NOT map a registered reverse search property to a response field with a meaning other than that of the fields already referenced by existing mappings for that property.
Documents that deprecate or restructure RDAP responses such that a registered reverse search is no longer usable MUST either note that the reverse search is no longer available or describe how to continue supporting it by adding another mapping.
Servers complying with this specification MUST extend the help response (RFC 9083) with a "reverse_search_properties" member containing an array of objects, each with mandatory child members: "searchableResourceType", "relatedResourceType", and "property".
Servers complying with this specification MUST include the value "reverse_search" in the rdapConformance property of the help response and any other response that includes the "reverse_search_properties_mapping" member.
Servers MUST add the "reverse_search_properties_mapping" member to the topmost object of a reverse search response, detailing the JSONPath mapping used for each property in the query. This member MUST be included for all properties used in the search.
Servers MUST NOT provide or implement reverse searches or reverse search mappings that are not registered with IANA. A reverse search is defined as the triple <searchable resource type, related resource type, property> mapped to an RDAP object member via a JSONPath expression.
Servers MUST return an HTTP 501 (Not Implemented) response to inform clients of unsupported reverse searches. Servers MAY restrict how predicates are used by returning a 400 (Bad Request) response when a problematic request is received.
The related-resource-type path segment MUST be one of the resource types for lookup defined in RFC 9082 ("domain", "nameserver", "entity", "ip", "autnum") or a resource type extension.
The searchable-resource-type path segment MUST be one of the resource types for search defined in RFC 9082 ("domains", "nameservers", "entities") or a resource type extension.
When a predicate on the reverse search property "role" is present, the RDAP response property "roles" MUST contain at least the specified role.
When applied to an object, the JSONPath expression in a reverse search mapping MUST produce a list of values each of which is a JSON number or string. Each generated value MUST be a JSON number or string when determining whether an object matches a predicate.
Providing reverse search in RDAP introduces threats of Correlation, Disclosure, and Misuse of data (per RFC 6973). RDAP providers must mitigate these through appropriate access control measures including RBAC, PBAC, ABAC, or TBAC paradigms.
Reverse search requests and responses may contain Personally Identifiable Information (PII), so reverse search functionality MUST be available over HTTPS only.
Where reverse search makes use of sensitive information, the information MUST only be accessible to authorized users under a lawful basis. Registry operators must ascertain whether their regulatory environment permits implementation of this functionality.
Four reverse search properties are defined for entity-related searches across domain, nameserver, and entity searchable resource types: "role" ($.entities[*].roles), "handle" ($.entities[*].handle), "fn" ($.entities[*].vcardArray[1][?(@[0]=='fn')][3]), and "email" ($.entities[*].vcardArray[1][?(@[0]=='email')][3]).
Reverse search query processing: the server applies the property mapping to each candidate object to generate a list of values, then checks whether the search pattern matches one or more values (exact match or partial string per RFC 9082 Section 4.1). Objects are included only if they satisfy all predicates, including multiple predicates on the same property.
The generic reverse search path syntax is: {searchable-resource-type}/reverse_search/{related-resource-type}?<search-condition>, where search-condition is a sequence of "property=search pattern" predicates separated by ampersand ('&', 0x0026).
The "reverse_search_properties_mapping" member contains an array of objects with mandatory child members "property" (the search property used) and "propertyPath" (the JSONPath expression mapping to the corresponding RDAP object member or members).
The "reverse_search_properties" member in the RDAP help response advertises supported reverse searches; each entry contains "searchableResourceType", "relatedResourceType", and "property" child members.
IANA has created the "RDAP Reverse Search Mapping" registry using the Specification Required policy. Entries are keyed by the 4-tuple (Searchable Resource Type, Related Resource Type, Property, Property Path), which MUST be unique. Initial entries map fn, handle, email, and role to their JSONPath expressions.
IANA has created the "RDAP Reverse Search" registry using the Specification Required policy. Entries are keyed by the triple (Searchable Resource Type, Related Resource Type, Property), which MUST be unique. Initial entries cover fn, handle, email, and role properties for domains/nameservers/entities with related resource type entity.
IANA has registered the extension identifier "reverse_search" in the "RDAP Extensions" registry, applicable to any registry operator, intended for URI path segments and response extensions related to RDAP reverse search.
Security services for controlled access to reverse search operations are described in RFC 7481. RDAP providers may also physically separate reverse search endpoints from other endpoints via a proxy routing to a dedicated backend, with additional controls such as digital certificates and IP allow-listing.
The specification of the relationship within the reverse search path allows RDAP servers to implement different authorization policies on a per-relationship basis, enabling fine-grained access control.