Internet DRAFT - draft-zhou-weirds-rdap-restful-search
draft-zhou-weirds-rdap-restful-search
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=<IP address> or ip/?address=<CIDR format>
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=<autonomous system number>
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=<domain names>
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=<name server names>
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=<Entity Handle>
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=<value>
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]
