Internet DRAFT - draft-hollenbeck-weirds-rdap-search
draft-hollenbeck-weirds-rdap-search
Network Working Group S. Hollenbeck
Internet-Draft Verisign Labs
Intended status: Standards Track A. Newton
Expires: December 20, 2013 ARIN
June 18, 2013
Registration Data Access Protocol Basic Search Processing
draft-hollenbeck-weirds-rdap-search-02
Abstract
This document describes path segments and query parameters needed to
construct HTTP URLs that may be used to search for and retrieve
registration information from registries (including both Regional
Internet Registries (RIRs) and Domain Name Registries (DNRs)) using
"RESTful" web access patterns. It also describes a method of
encoding responses using Javascript Object Notation (JSON).
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 http://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 December 20, 2013.
Copyright Notice
Copyright (c) 2013 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
(http://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 extracted from this document must
include Simplified BSD License text as described in Section 4.e of
Hollenbeck & Newton Expires December 20, 2013 [Page 1]
Internet-Draft RDAP Search June 2013
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Conventions Used in This Document . . . . . . . . . . . . . . 2
1.1. Acronyms and Abbreviations . . . . . . . . . . . . . . . 2
2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
3. Query and Search Parameters . . . . . . . . . . . . . . . . . 3
3.1. Domain Search . . . . . . . . . . . . . . . . . . . . . . 3
3.2. Entity Search . . . . . . . . . . . . . . . . . . . . . . 3
4. Search Processing . . . . . . . . . . . . . . . . . . . . . . 4
5. Search Results . . . . . . . . . . . . . . . . . . . . . . . 5
6. Internationalization Considerations . . . . . . . . . . . . . 6
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6
8. Security Considerations . . . . . . . . . . . . . . . . . . . 6
9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 6
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 6
10.1. Normative References . . . . . . . . . . . . . . . . . . 6
10.2. Informative References . . . . . . . . . . . . . . . . . 8
Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 8
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8
1. Conventions Used in This Document
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 RFC 2119 [RFC2119].
1.1. Acronyms and Abbreviations
DNR: Domain Name Registry
IDN: Internationalized Domain Name
RDAP: Registration Data Access Protocol
RIR: Regional Internet Registry
2. Introduction
This document describes a specification for registration data search
functions using a RESTful web service. The search functions are
implemented using the Hypertext Transfer Protocol (HTTP) [RFC2616].
Lookup processing as specified in [I-D.ietf-weirds-rdap-query] is
used when a client wishes to retrieve information associated with a
data object represented by a character string that exactly matches a
particular key. There is no provision for partial string pattern
matching to represent unknown characters or multiple result
possibilities. Experience with WHOIS [RFC3912] implementation and
Hollenbeck & Newton Expires December 20, 2013 [Page 2]
Internet-Draft RDAP Search June 2013
operation has shown that people are often unsure of exact spellings
and they often want to receive multiple results that match a
particular pattern. This specification is intended to meet that need
for the Registration Data Access Protocol (RDAP).
3. Query and Search Parameters
RDAP search path segments are formed using a concatenation of the
plural form of the object being searched for, a forward slash
character ('/', ASCII value 0x002F), and an HTTP query string. The
HTTP query string is formed using a concatenation of the question
mark character ('?', ASCII value 0x003F), the JSON object value
associated with the object being searched for, the equal sign
character ('=', ASCII value 0x003D), and the search pattern. For the
domain and entity objects described in this document the plural
objects forms are "domains" and "entities". The JSON object value is
"name". One could construct a query string for an entity email
address using the "email" object name, but that is beyond the scope
of this specification.
3.1. Domain Search
Syntax: domains/?name=<domain search pattern>
Searches for domain information are of the form /domains/?name=XXXX,
where XXXX is a search pattern representing a fully-qualified domain
name [RFC4343] in a zone administered by the server operator of a
DNR. The following path would be used to find DNR information for
domain names matching the "example*.com" pattern:
/domains/?name=example*.com
Internationalized Domain Names (IDNs) in U-label format [RFC5890] can
also be used as search patterns (see Section 4).
Note that this search is relevant to DNRs, not RIRs.
3.2. Entity Search
Syntax: entities/?name=<entity search pattern>
Searches for entity information are of the form /entities/?name=XXXX,
where XXXX is a search pattern representing an entity name as
specified in Section 7.1 of [I-D.ietf-weirds-json-response]. The
following path would be used to find DNR information for DNR entity
names matching the "Bobby Joe*" pattern.
/entities/?name=Bobby%20Joe*
Hollenbeck & Newton Expires December 20, 2013 [Page 3]
Internet-Draft RDAP Search June 2013
URLs MUST be properly encoded according to the rules of [RFC3986].
In the example above, "Bobby Joe*" is encoded to "Bobby%20Joe*".
4. Search Processing
Searching occurs either on whole strings or on partial strings.
Partial string searching uses the asterisk ('*', ASCII value 0x002A)
character to match zero or more characters. The location or number
of occurrences of the asterisk character is not dictated by this
specification. Some servers might support the asterisk in a trailing
location only (e.g. "/domains/example*.com") while others may allow
it a leading location (e.g. "/domains/*example.com"), or within
strings, or even in multiple locations.
If a server receives a search request but cannot process the request
because it does not support a particular style of partial match
searching, it SHOULD return an HTTP 422 [RFC4918] error. When
returning a 422 error, the server MAY also return an error response
body as specified in Section 12 of [I-D.ietf-weirds-json-response] if
the requested media type is one that is specified in
[I-D.ietf-weirds-using-http].
Because Unicode characters may be combined with another Unicode
character or characters, partial matching is not feasible across
combinations of Unicode characters. Servers SHOULD NOT partially
match combinations of Unicode characters where a Unicode character
may be legally combined with another Unicode character or characters.
Clients MUST NOT issue a partial match search of Unicode characters
where a Unicode character may be legally combined with another
Unicode character or characters. Partial match searches with
incomplete combinations of characters where a character must be
combined with another character or characters are invalid. Partial
match searches with characters that may be combined with another
character or characters are to be considered non-combined characters
(that is, if character x maybe combined with character y but
character y is not submitted in the search string then character x is
a complete character and no combinations of character x are to
searched).
Because Unicode characters may be combined with another Unicode
character or characters, partial matching requires that a server
maintain a list of valid character combinations to be considered a
match. When comparing DNS U-labels, servers SHOULD use the code
points specified in [RFC5892] to determine partial matches. When
comparing entity names, servers SHOULD use the normalization rules
and code points specified by [I-D.ietf-precis-nickname] to determine
partial matches.
Hollenbeck & Newton Expires December 20, 2013 [Page 4]
Internet-Draft RDAP Search June 2013
Clients SHOULD NOT submit search requests with partial matching for
DNS A-labels. A-labels represent an encoding that can only be
reconstructed properly when the label is complete.
5. Search Results
The method to return search results described here is not limited to
the /domains or /entities searches defined in this document. It can
also be used by future specifications to define search results for
other types of registration data.
Search results are returned in a JSON object. This object contains
data structures as outlined in Section 5 of
[I-D.ietf-weirds-json-response] (e.g. "rdapConformance", "notices",
etc...) and an array called "results" containing the objects that are
a result of the search. For the /domains (Section 3.1) and /entities
(Section 3.2) searches, the entity object class and the domain object
class are defined in [I-D.ietf-weirds-json-response].
To identify the type of object returned in the "results" array, each
object SHOULD contain a JSON string named "objectClass" (see
Section 4.2 of [I-D.ietf-weirds-json-response] regarding the
inclusion of new JSON data in object classes). For domains, the
string MUST be "domain" and for entities the string MUST be "entity".
Servers SHOULD signify their compliance with this specification by
including the string "domain_entity_search_level_0" in the
"rdapConformance" array.
{
"rdapConformance" :
[
"rdap_level_0",
"domain_entity_search_level_0"
],
...
"results" :
[
{
"handle" : "1-XXXX",
"name" : "1.example.com",
"objectClass" : "domain",
...
},
{
"handle" : "2-XXXX",
"name" : "2.example.com",
"objectClass" : "domain",
Hollenbeck & Newton Expires December 20, 2013 [Page 5]
Internet-Draft RDAP Search June 2013
...
}
]
}
Figure 1
6. Internationalization Considerations
TBD. Give guidelines for how a local policy could work for
searching.
7. IANA Considerations
This document does not specify any IANA actions.
8. Security Considerations
Security services for the operations specified in this document are
described in "Security Services for the Registration Data Access
Protocol" [I-D.ietf-weirds-rdap-sec]. Additional considerations that
are specific to search functionality are described here.
Search functionality typically requires more server resources (such
as memory, CPU cycles, and network bandwidth) when compared to basic
lookup functionality. This increases the risk of server resource
exhaustion and subsequent denial of service due to abuse. This risk
can be mitigated by developing and implementing controls to restrict
search functionality to identified and authorized clients. If those
clients behave badly, their search privileges can be suspended or
revoked. Rate limiting as described in Section 5.5 of "Using the
Registration Data Access Protocol (RDAP) with HTTP"
[I-D.ietf-weirds-using-http] can also be used to control the rate of
received search requests. Server operators can also reduce their
risk by restricting the amount of information returned in response to
a search request.
9. Acknowledgements
The authors would like to acknowledge the following individuals for
their contributions to this document: Ning Kong, Linlin Zhou.
10. References
10.1. Normative References
[I-D.ietf-precis-nickname]
Hollenbeck & Newton Expires December 20, 2013 [Page 6]
Internet-Draft RDAP Search June 2013
Saint-Andre, P., "Preparation and Comparison of
Nicknames", draft-ietf-precis-nickname-05 (work in
progress), November 2012.
[I-D.ietf-weirds-json-response]
Newton, A. and S. Hollenbeck, "JSON Responses for the
Registration Data Access Protocol (RDAP)", draft-ietf-
weirds-json-response-04 (work in progress), June 2013.
[I-D.ietf-weirds-rdap-query]
Newton, A. and S. Hollenbeck, "Registration Data Access
Protocol Lookup Format", draft-ietf-weirds-rdap-query-05
(work in progress), June 2013.
[I-D.ietf-weirds-rdap-sec]
Hollenbeck, S. and N. Kong, "Security Services for the
Registration Data Access Protocol", draft-ietf-weirds-
rdap-sec-04 (work in progress), June 2013.
[I-D.ietf-weirds-using-http]
Newton, A., Ellacott, B., and N. Kong, "HTTP usage in the
Registration Data Access Protocol (RDAP)", draft-ietf-
weirds-using-http-05 (work in progress), May 2013.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, RFC
3986, January 2005.
[RFC4343] Eastlake, D., "Domain Name System (DNS) Case Insensitivity
Clarification", RFC 4343, January 2006.
[RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed
Authoring and Versioning (WebDAV)", RFC 4918, June 2007.
[RFC5890] Klensin, J., "Internationalized Domain Names for
Applications (IDNA): Definitions and Document Framework",
RFC 5890, August 2010.
[RFC5892] Faltstrom, P., "The Unicode Code Points and
Internationalized Domain Names for Applications (IDNA)",
RFC 5892, August 2010.
Hollenbeck & Newton Expires December 20, 2013 [Page 7]
Internet-Draft RDAP Search June 2013
10.2. Informative References
[RFC3912] Daigle, L., "WHOIS Protocol Specification", RFC 3912,
September 2004.
Appendix A. Change Log
Initial -00: First draft individual submission.
-01: Changed HTTP error code from 500 to 422 in Section 4. Added a
normative reference to RFC 4918.
-02: Updated Security Considerations. Added IDN processing text in
Section 3.1.
Authors' Addresses
Scott Hollenbeck
Verisign Labs
12061 Bluemont Way
Reston, VA 20190
US
Email: shollenbeck@verisign.com
URI: http://www.verisignlabs.com/
Andrew Lee Newton
American Registry for Internet Numbers
3635 Concorde Parkway
Chantilly, VA 20151
US
Email: andy@arin.net
URI: http://www.arin.net
Hollenbeck & Newton Expires December 20, 2013 [Page 8]
