Internet Engineering Task Force L. Zhou Internet-Draft N. Kong Intended status: Informational D. Deng Expires: August 5, 2013 S. Shen CNNIC Feb 2013 Registration Data Access Protocol RESTful Searching draft-zhou-weirds-rdap-restful-search-00 Abstract This document describes the searchability details of the Registration Data Access Protocol (RDAP). It specifies basic and extended searching parameters, defines the JSON (JavaScript Object Notation) formats of searching and responding data structure and also proposes the specification of boolean search functionality. 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 5, 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 Zhou, et al. Expires August 5, 2013 [Page 1] Internet-Draft RDAP RESTful search Feb 2013 the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. This document may contain material from IETF Documents or IETF Contributions published or made publicly available before November 10, 2008. The person(s) controlling the copyright in some of this material may not have granted the IETF Trust the right to allow modifications of such material outside the IETF Standards Process. Without obtaining an adequate license from the person(s) controlling the copyright in such materials, this document may not be modified outside the IETF Standards Process, and derivative works of it may not be created outside the IETF Standards Process, except to format it for publication as an RFC or to translate it into languages other than English. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Searching Parameters . . . . . . . . . . . . . . . . . . . . . 3 2.1. Basic Search . . . . . . . . . . . . . . . . . . . . . . . 3 2.1.1. IP Search . . . . . . . . . . . . . . . . . . . . . . . 3 2.1.2. AS Number Search . . . . . . . . . . . . . . . . . . . 4 2.1.3. Domain Search . . . . . . . . . . . . . . . . . . . . . 4 2.1.4. Name Server Search . . . . . . . . . . . . . . . . . . 4 2.1.5. Entity Search . . . . . . . . . . . . . . . . . . . . . 5 2.2. Extended Search . . . . . . . . . . . . . . . . . . . . . . 5 3. Boolean Search . . . . . . . . . . . . . . . . . . . . . . . . 6 4. Search Response Format . . . . . . . . . . . . . . . . . . . . 6 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 7 6. Security considerations . . . . . . . . . . . . . . . . . . . . 7 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 8 8. Normative References . . . . . . . . . . . . . . . . . . . . . 8 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 9 Zhou, et al. Expires August 5, 2013 [Page 2] Internet-Draft RDAP RESTful search Feb 2013 1. Introduction A searchable RDAP service is a HTTP (Hypertext Transfer Protocol) based function which supports multiple searching parameters and boolean search capabilities. This document describes the specifications for searching parameters, searching response formats, boolean search function and some security consideration about RDAP searchability. First the RESTful query URI formats for searching specific information are defined. There are 5 basic searching types and some extended searching parameters that may be used according to the New gTLD Applicant Guide Book. The basic searching types, including search of IP, AS (Autonomous System) number, domain, name server and entity, that are consistent with the query types defined in draft-ietf-weirds-rdap-query [I-D.ietf-weirds-rdap-query]. The second section of this document describes the boolean search function that supports a set of search criteria like AND, OR, NOT. The third part of this document gives some response data format specified in JSON and proposes some consideration on ordering and paging. Finally, this document talks about some security issues that should be considerated to avoid abuses of this searchability feature. 2. Searching Parameters In this section, basic and extended searching parameters are mainly presented. The combination of following parameters can also be used as searching parameters. 2.1. Basic Search Basic search means 5 types of searching parameters which includes IP, AS number, domain, name server and entity. 2.1.1. IP Search Syntax: /search/?ip= or ip/?address= IP search parameter is either an IPv4 RFC 1166 [RFC1166] or IPv6 RFC 5952 [RFC5952] address (i.e. XXX) or an IPv4 or IPv6 CIDR RFC 4632 [RFC4632] notation address block (i.e. XXX/YY). This is an example URL for the most specific network containing Zhou, et al. Expires August 5, 2013 [Page 3] Internet-Draft RDAP RESTful search Feb 2013 192.0.2.0: /search/?ip=192.0.2.0 This is an example URL for the most specific network containing 192.0.2.0/24: /search/?ip=192.0.2.0%2f24 2.1.2. AS Number Search Syntax: /search/?as= Searches for information regarding autonomous system number registrations are of the form /autnum/?as=XXX where XXX is an autonomous system number RFC 5396 [RFC5396]. The following is an example URL for the AS number search. /search/?as=65551 2.1.3. Domain Search Syntax: /search/?domain= Searches for domain information are of the form /?domain=XXXX, where XXXX is a fully-qualified domain name RFC 4343 [RFC4343] in either the in-addr.arpa or ip6.arpa zones (for Regional Internet Registries (RIRs)) or a fully-qualified domain name in a zone administered by the server operator (for Domain Name Registries (DNRs)). The example URL for searching domain name like example.com is defined below. /search/?domain=example.com 2.1.4. Name Server Search Syntax: /search/?ns= This parameter represents a fully qualified name as specified in RFC 952 [RFC0952] and RFC 1123 [RFC1123]. Internationalized names represented in A-label format RFC 5890 [RFC5890] are also valid name server names. This is an example URL for the specific name server searching cotaining ns.example.com. Zhou, et al. Expires August 5, 2013 [Page 4] Internet-Draft RDAP RESTful search Feb 2013 /search/?ns=ns.example.com 2.1.5. Entity Search Syntax: /search/?entityID= This parameter represents an entity (such as a contact, registrant, or registrar) identifier. The example URL for searching entity handle such as CID0193 is defined below. /search/?entityID=CID0193 2.2. Extended Search This seachable function defined in New gTLD Applicant Guide Book should offer partial or exact match capabilities on some fields, such as contact name, city, street, postal code etc.. So besides the basic search parameters, other extended search parameters are also specified. Syntax: /search/?keyword= Followings are some search examples that this functionality that would support. 1. The "entityname" field represents the names of a specified contact, registrant or registrar. This an example URL for the entity names search: /search/?entityname=James%20Blunt 2. The "street" parameter contains the entity's street address defined in RFC 5733 [RFC5733]. A street search example: /search/ ?street=123%20Example%20Dr 3. The "city" parameter contains the entity's city defined in RFC 5733 [RFC5733]. A city search example: /search/?city=Beijing 4. The "sp" parameter contains the entity's state or province defined in RFC 5733 [RFC5733]. A state or province search example: /search/?sp=VA 5. The "pc" parameter contains the entity's postal code defined in RFC 5733 [RFC5733]. A postal code search example: /search/ ?pc=100190 6. The "cc" parameter contains the entity's country code defined in RFC 5733 [RFC5733]. A country code search example: /search/ Zhou, et al. Expires August 5, 2013 [Page 5] Internet-Draft RDAP RESTful search Feb 2013 ?cc=CN 3. Boolean Search RIRs and DNRs shall offer Boolean search capabilities supporting, at least, the following logical operators to join a set of search criteria: AND, OR, NOT. Any fields described above can be combined together by the boolean criteria to be the search input parameters. Partial-match and exact- match capabilities would also be offered by RIRs and DNRs. "*" is the replace mark for partial-match function. "&" mark represents AND, "+" mark means OR and "-" mark means that none of the input text is inlcuded in the response results. An example is given below searching for entity name called James *** or Tom ***, registered domain name is xyz.com and country code is not CN. /search/?entityname=James*+Tom*&domain=xyz.com&cc=-CN 4. Search Response Format The search results will be returned in a JSON object, the format of which is discussed in the section 5 of draft-hollenbeck-weirds-rdap-search [I-D.hollenbeck-weirds-rdap-search]. Ordering and paging are taken into consideration in this document. Three JSON objects, which are "page", "total" and "orderby" are defined as below. The server could specifiy the number of display results per page according to different registries' requirements. The search response will include the page number and total page number information in the results. "orderby" is the field using for ordering all the results. Zhou, et al. Expires August 5, 2013 [Page 6] Internet-Draft RDAP RESTful search Feb 2013 { "results" : [ { "handle" : "1-XXXX", "name" : "1.example.com", "objectClass" : "domain", ... "page" : "1", "total" : "10", "orderby" : "domain" }, { "handle" : "2-XXXX", "name" : "2.example.com", "objectClass" : "domain", ... "page" : "1", "total" : "10", "orderby" : "domain" } ] } This response format is a preliminary design for future disscussion. If the idea is adopted by the working group, the search URI including paging and ordering information should also be specified, such as /search/?domain=example.com&page=1&orderby=domain. 5. IANA Considerations This document does not specify any IANA actions. 6. Security considerations The service shall include appropriate precautions to avoid abuse of this feature. A registrar or registrant may only login the searchable Whois system using their own ID and password, and may only search information related to their own domain names. If a registrar, registrant or a third-party user wants to search others' information, they need to explain the reasonable purposes, commit to protect privacy and security, and sign an agreement at Zhou, et al. Expires August 5, 2013 [Page 7] Internet-Draft RDAP RESTful search Feb 2013 first. 7. Acknowledgements The authors especially thank the following individuals who gave their suggestions and contributions to this document: Kevin Tse. 8. Normative References [I-D.hollenbeck-weirds-rdap-search] Hollenbeck, S. and A. Newton, "Registration Data Access Protocol Search Processing", draft-hollenbeck-weirds-rdap-search-00 (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. [RFC0952] Harrenstien, K., Stahl, M., and E. Feinler, "DoD Internet host table specification", RFC 952, October 1985. [RFC1123] Braden, R., "Requirements for Internet Hosts - Application and Support", STD 3, RFC 1123, October 1989. [RFC1166] Kirkpatrick, S., Stahl, M., and M. Recker, "Internet numbers", RFC 1166, July 1990. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2629] Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629, June 1999. [RFC4343] Eastlake, D., "Domain Name System (DNS) Case Insensitivity Clarification", RFC 4343, January 2006. [RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing (CIDR): The Internet Address Assignment and Aggregation Plan", BCP 122, RFC 4632, August 2006. [RFC5396] Huston, G. and G. Michaelson, "Textual Representation of Autonomous System (AS) Numbers", RFC 5396, December 2008. [RFC5733] Hollenbeck, S., "Extensible Provisioning Protocol (EPP) Zhou, et al. Expires August 5, 2013 [Page 8] Internet-Draft RDAP RESTful search Feb 2013 Contact Mapping", STD 69, RFC 5733, August 2009. [RFC5890] Klensin, J., "Internationalized Domain Names for Applications (IDNA): Definitions and Document Framework", RFC 5890, August 2010. [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 Address Text Representation", RFC 5952, August 2010. Authors' Addresses Linlin Zhou CNNIC 4 South 4th Street, Zhongguancun, Haidian District Beijing, Beijing 100190 China Phone: +86 10 5881 2677 Email: zhoulinlin@cnnic.cn Ning Kong CNNIC 4 South 4th Street, Zhongguancun, Haidian District Beijing, Beijing 100190 China Phone: +86 10 5881 3147 Email: nkong@cnnic.cn Guangqing Deng CNNIC 4 South 4th Street, Zhongguancun, Haidian District Beijing, Beijing 100190 China Phone: +86 10 5881 3430 Email: dengguangqing@cnnic.cn Zhou, et al. Expires August 5, 2013 [Page 9] Internet-Draft RDAP RESTful search Feb 2013 Sean Shen CNNIC 4 South 4th Street, Zhongguancun, Haidian District Beijing, Beijing 100190 China Phone: +86 10 5881 3038 Email: shenshuo@cnnic.cn Zhou, et al. Expires August 5, 2013 [Page 10]