Network Working Group S. Hollenbeck Internet-Draft Verisign Labs Intended status: Standards Track A. Newton Expires: August 18, 2013 ARIN February 14, 2013 Registration Data Access Protocol Search Processing draft-hollenbeck-weirds-rdap-search-01 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 August 18, 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 August 18, 2013 [Page 1] Internet-Draft RDAP Search February 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 . . . . . . . . . . . . . . . 3 1.1. Acronyms and Abbreviations . . . . . . . . . . . . . . . . 3 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Query and Search Parameters . . . . . . . . . . . . . . . . . . 3 3.1. Domain Search . . . . . . . . . . . . . . . . . . . . . . . 4 3.2. Entity Search . . . . . . . . . . . . . . . . . . . . . . . 4 4. Search Processing . . . . . . . . . . . . . . . . . . . . . . . 4 5. Search Results . . . . . . . . . . . . . . . . . . . . . . . . 5 6. Internationalization Considerations . . . . . . . . . . . . . . 6 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 6 8. Security Considerations . . . . . . . . . . . . . . . . . . . . 6 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 7 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7 10.1. Normative References . . . . . . . . . . . . . . . . . . . 7 10.2. Informative References . . . . . . . . . . . . . . . . . . 8 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . . 8 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 8 Hollenbeck & Newton Expires August 18, 2013 [Page 2] Internet-Draft RDAP Search February 2013 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 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 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. Hollenbeck & Newton Expires August 18, 2013 [Page 3] Internet-Draft RDAP Search February 2013 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. (Open question: how do we do IDNs?) The following path would be used to find DNR information for domain names matching the "example*.com" pattern: /domains/?name=example*.com 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* 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 occurances 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 Hollenbeck & Newton Expires August 18, 2013 [Page 4] Internet-Draft RDAP Search February 2013 [I-D.ietf-weirds-using-http]. The search patterns described in this document MAY include non-ASCII Unicode characters. This document does not specify partial matching processing rules for Unicode or DNS u-label matching. Partial string matching criteria for Unicode and DNS u-label characters is a matter of local server policy. See Section 6 for guidelines that may be used to develop local policies. 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. Hollenbeck & Newton Expires August 18, 2013 [Page 5] Internet-Draft RDAP Search February 2013 { "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", ... } ] } 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]. As we identify specific use cases for which security services are needed they will be described here. Hollenbeck & Newton Expires August 18, 2013 [Page 6] Internet-Draft RDAP Search February 2013 9. Acknowledgements The authors would like to acknowledge the following individuals for their contributions to this document: TBD. 10. References 10.1. Normative References [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-02 (work in progress), January 2013. [I-D.ietf-weirds-rdap-query] Newton, A. and S. Hollenbeck, "Registration Data Access Protocol Query Format", draft-ietf-weirds-rdap-query-02 (work in progress), December 2012. [I-D.ietf-weirds-rdap-sec] Hollenbeck, S. and N. Kong, "Security Services for the Registration Data Access Protocol", draft-ietf-weirds-rdap-sec-01 (work in progress), November 2012. [I-D.ietf-weirds-using-http] Newton, A., Ellacott, B., and N. Kong, "Using the Registration Data Access Protocol (RDAP) with HTTP", draft-ietf-weirds-using-http-01 (work in progress), December 2012. [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 Hollenbeck & Newton Expires August 18, 2013 [Page 7] Internet-Draft RDAP Search February 2013 Authoring and Versioning (WebDAV)", RFC 4918, June 2007. 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. 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 August 18, 2013 [Page 8]