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= 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= 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]