idnits 2.17.1 draft-ietf-weirds-rdap-query-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 14, 2013) is 4061 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '1' on line 469 -- Looks like a reference, but probably isn't: '2' on line 471 -- Looks like a reference, but probably isn't: '3' on line 473 -- Looks like a reference, but probably isn't: '4' on line 474 == Outdated reference: A later version (-14) exists of draft-ietf-weirds-json-response-02 == Outdated reference: A later version (-12) exists of draft-ietf-weirds-rdap-sec-01 -- Possible downref: Normative reference to a draft: ref. 'I-D.ietf-weirds-rdap-sec' == Outdated reference: A later version (-15) exists of draft-ietf-weirds-using-http-01 -- Possible downref: Normative reference to a draft: ref. 'I-D.ietf-weirds-using-http' ** Downref: Normative reference to an Unknown state RFC: RFC 952 ** Downref: Normative reference to an Informational RFC: RFC 1166 ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Downref: Normative reference to an Informational RFC: RFC 4290 -- Obsolete informational reference (is this intentional?): RFC 4627 (Obsoleted by RFC 7158, RFC 7159) Summary: 4 errors (**), 0 flaws (~~), 5 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A.L. Newton 3 Internet-Draft ARIN 4 Intended status: Standards Track S. Hollenbeck 5 Expires: September 15, 2013 Verisign Labs 6 March 14, 2013 8 Registration Data Access Protocol Lookup Format 9 draft-ietf-weirds-rdap-query-03 11 Abstract 13 This document describes uniform patterns to construct HTTP URLs that 14 may be used to retrieve registration information from registries 15 (including both Regional Internet Registries (RIRs) and Domain Name 16 Registries (DNRs)) using "RESTful" web access patterns. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on September 15, 2013. 35 Copyright Notice 37 Copyright (c) 2013 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Conventions Used in This Document . . . . . . . . . . . . . . 2 53 1.1. Acronyms and Abbreviations . . . . . . . . . . . . . . . 2 54 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 55 3. Path Segment Specification . . . . . . . . . . . . . . . . . 4 56 3.1. IP Network Path Segment Specification . . . . . . . . . . 4 57 3.2. Autonomous System Path Segment Specification . . . . . . 5 58 3.3. Domain Path Segment Specification . . . . . . . . . . . . 6 59 3.4. Name Server Path Segment Specification . . . . . . . . . 6 60 3.5. Entity Path Segment Specification . . . . . . . . . . . . 7 61 4. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 7 62 5. Internationalization Considerations . . . . . . . . . . . . . 7 63 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 64 7. Security Considerations . . . . . . . . . . . . . . . . . . . 8 65 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 8 66 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 67 9.1. Normative References . . . . . . . . . . . . . . . . . . 8 68 9.2. Informative References . . . . . . . . . . . . . . . . . 10 69 Appendix A. Path Segment Specification for Search Queries . . . 10 70 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 11 71 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 73 1. Conventions Used in This Document 75 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 76 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 77 document are to be interpreted as described in RFC 2119 [RFC2119]. 79 1.1. Acronyms and Abbreviations 81 IDN: Internationalized Domain Name 82 IDNA: Internationalized Domain Names in Applications 83 DNR: Domain Name Registry 84 RDAP: Registration Data Access Protocol 85 REST: Representational State Transfer State Transfer. The term 86 was first described in a doctoral dissertation [REST]. 87 RESTful: an adjective that describes a service using HTTP and the 88 principles of REST. 89 RIR: Regional Internet Registry 91 2. Introduction 93 This document describes a specification for querying registration 94 data using a RESTful web service and uniform query patterns. The 95 service is implemented using the Hypertext Transfer Protocol (HTTP) 96 [RFC2616]. 98 The protocol described in this specification is intended to address 99 deficiencies with the WHOIS protocol [RFC3912] that have been 100 identified over time, including: 102 o Lack of standardized command structures, 103 o lack of standardized output and error structures, 104 o lack of support for internationalization and localization, and 105 o lack of support for user identification, authentication, and 106 access control. 108 The patterns described in this document purposefully do not encompass 109 all of the methods employed in the WHOIS and RESTful web services of 110 all of the RIRs and DNRs. The intent of the patterns described here 111 are to enable lookups of: 113 o networks by IP address, 114 o autonomous system numbers by number, 115 o reverse DNS meta-data by domain, 116 o name servers by name, 117 o registrars by name, and 118 o entities (such as contacts) by identifier. 120 It is envisioned that each registry will continue to maintain NICNAME 121 /WHOIS and/or RESTful web services specific to their needs and those 122 of their constituencies, and the information retrieved through the 123 patterns described here may reference such services. 125 Likewise, future IETF standards may add additional patterns for 126 additional query types (for example, "/domains" for a domain search 127 query). And Section 4 defines a simple pattern namespacing scheme to 128 accomodate custom extensions that will not interfere with the 129 patterns defined in this document or patterns defined in future IETF 130 standards. 132 WHOIS services, in general, are read-only services. Therefore URL 133 [RFC3986] patterns specified in this document are only applicable to 134 the HTTP [RFC2616] GET and HEAD methods. 136 This document does not describe the results or entities returned from 137 issuing the described URLs with an HTTP GET. It is envisioned that 138 other documents will describe these entities in various serialization 139 formats, such as JavaScript Object Notation (JSON, [RFC4627]). 141 Additionally, resource management, provisioning and update functions 142 are out of scope for this document. Registries have various and 143 divergent methods covering these functions, and it is unlikely a 144 uniform approach for these functions will ever be possible. 146 HTTP contains mechanisms for servers to authenticate clients and for 147 clients to authenticate servers (from which authorization schemes may 148 be built) so such mechanisms are not described in this document. 149 Policy, provisioning, and processing of authentication and 150 authorization are out-of-scope for this document as deployments will 151 have to make choices based on local criteria. Specified 152 authentication mechanisms MUST use HTTP. 154 3. Path Segment Specification 156 The uniform patterns start with a base URL [RFC3986] specified by 157 each registry or any other service provider offering this service. 158 The base URL is followed by a resource-type-specific path segment. 159 The base URL may contain its own path segments (e.g. http:// 160 example.com/... or http://example.com/restful-WHOIS/... ). The 161 characters used to form a path segment are limited to those that can 162 be used to form a URI as specified in RFC 3986 [RFC3986]. 164 The resource type path segments are: 166 o 'ip': IP networks and associated data referenced using either an 167 IPv4 or IPv6 address. 168 o 'autnum': Autonomous system registrations and associated data 169 referenced using an AS Plain autonomous system number. 170 o 'domain': Reverse DNS (RIR) or domain name (DNR) information and 171 associated data referenced using a fully-qualified domain name. 172 o 'nameserver': Used to identify a name server information query. 173 o 'entity': Used to identify an entity information query. 175 3.1. IP Network Path Segment Specification 177 Syntax: ip/ or ip// 179 Queries for information about IP networks are of the form /ip/XXX/... 180 or /ip/XXX/YY/... where the path segment following 'ip' is either an 181 IPv4 [RFC1166] or IPv6 [RFC5952] address (i.e. XXX) or an IPv4 or 182 IPv6 CIDR [RFC4632] notation address block (i.e. XXX/YY). 183 Semantically, the simpler form using the address can be thought of as 184 a CIDR block with a bitmask length of 32 for IPv4 and a bitmask 185 length of 128 for IPv6. A given specific address or CIDR may fall 186 within multiple IP networks in a hierarchy of networks, therefore 187 this query targets the "most-specific" or smallest IP network which 188 completely encompasses it in a hierarchy of IP networks. 190 The IPv4 and IPv6 address formats supported in this query are 191 described in section 3.2.2 of [RFC3986], as IPv4address and 192 IPv6address ABNF definitions. Any valid IPv6 text address format 193 [RFC4291] can be used, compressed or not compressed. The restricted 194 rules to write a text representation of an IPv6 address [RFC5952] are 195 not mandatory. However, the zone id [RFC4007] is not appropriate in 196 this context and therefore prohibited. 198 This is an example URL for the most specific network containing 199 192.0.2.0: 201 /ip/192.0.2.0 203 This is an example of a URL the most specific network containing 204 192.0.2.0/24: 206 /ip/192.0.2.0/24 208 This is an example URL for the most specific network containing 209 2001:db8:1:1::1: 211 /ip/2001:db8:1:1::1 213 3.2. Autonomous System Path Segment Specification 215 Syntax: autnum/ 217 Queries for information regarding autonomous system number 218 registrations are of the form /autnum/XXX/... where XXX is an asplain 219 autonomous system number [RFC5396]. In some registries, registration 220 of autonomous system numbers is done on an individual number basis, 221 while other registries may register blocks of autonomous system 222 numbers. The semantics of this query are such that if a number falls 223 within a range of registered blocks, the target of the query is the 224 block registration, and that individual number registrations are 225 considered a block of numbers with a size of 1. 227 For example, to find information on autonomous system number 65551, 228 the following path would be used: 230 /autnum/65551 232 The following path would be used to find information on 4-byte 233 autonomous system number 65538: 235 /autnum/65538 237 3.3. Domain Path Segment Specification 239 Syntax: domain/ 241 Queries for domain information are of the form /domain/XXXX/..., 242 where XXXX is a fully-qualified domain name [RFC4343] in either the 243 in-addr.arpa or ip6.arpa zones (for RIRs) or a fully-qualified domain 244 name in a zone administered by the server operator (for DNRs). 245 Internationalized domain names represented in either A-label or 246 U-label format [RFC5890] are also valid domain names. 248 If the client sends the server an IDN U-label, servers that support 249 IDNs MUST convert the IDN into A-label format and perform IDNA 250 processing as specified in RFC 5891 [RFC5891]. The server should 251 perform an exact match lookup using the A-label. 253 The following path would be used to find information describing the 254 zone serving the network 192.0.2/24: 256 /domain/2.0.192.in-addr.arpa 258 The following path would be used to find information describing the 259 zone serving the network 2001:db8:1::/48: 261 /domain/1.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa 263 The following path would be used to find information for the 264 example.com domain name: 266 /domain/example.com 268 3.4. Name Server Path Segment Specification 270 Syntax: nameserver/ 272 The parameter represents a fully qualified name as 273 specified in RFC 952 [RFC0952] and RFC 1123 [RFC1123]. 274 Internationalized names represented in either A-label or U-label 275 format [RFC5890] are also valid name server names. 277 If the client sends the server an IDN U-label, servers that support 278 IDNs MUST convert the IDN into A-label format and perform IDNA 279 processing as specified in RFC 5891 [RFC5891]. The server should 280 perform an exact match lookup using the A-label. 282 The following path would be used to find information for the 283 ns1.example.com name server: 285 /nameserver/ns1.example.com 287 The following path would be used to find information for the IDN 288 ns1.xn--xemple-9ua.com name server: 290 /nameserver/ns1.xn--xemple-9ua.com 292 3.5. Entity Path Segment Specification 294 Syntax: entity/ 296 The parameter represents an entity (such as a contact, 297 registrant, or registrar) identifier. For example, for some DNRs 298 contact identifiers are specified in RFC 5730 [RFC5730] and RFC 5733 299 [RFC5733]. 301 The following path would be used to find information for the entity 302 associated with handle CID-4005: 304 /entity/CID-4005 306 4. Extensibility 308 This document describes path segment specifications for a limited 309 number of objects commonly registered in both RIRs and DNRs. It does 310 not attempt to describe path segments for all of the objects 311 registered in all registries. Custom path segments can be created 312 for objects not specified here using the process described in 313 Section TBD of "Using HTTP for RESTful Whois Services by Internet 314 Registries" [I-D.ietf-weirds-using-http]. 316 Custom path segments can be created by prefixing the segment with a 317 unique identifier followed by an underscore character (0x5F). For 318 example, a custom entity path segment could be created by prefixing 319 "entity" with "custom_", producing "custom_entity". Servers MUST 320 return an appropriate failure status code for a request with an 321 unrecognized path segment. 323 5. Internationalization Considerations 325 There is value in supporting the ability to submit either a U-label 326 (Unicode form of an IDN label) or an A-label (ASCII form of an IDN 327 label) as a query argument to an RDAP service. Clients capable of 328 processing non-ASCII characters may prefer a U-label since this is 329 more visually recognizable and familiar than A-label strings, but 330 clients of programmatic interfaces may wish to submit and display 331 A-labels or may not be able to input U-labels with their keyboard 332 configuration. . 334 Internationalized domain and name server names can contain character 335 variants and variant labels as described in RFC 4290 [RFC4290]. 336 Clients that support queries for internationalized domain and name 337 server names MUST accept service provider responses that describe 338 variants as specified in "JSON Responses for the Registration Data 339 Access Protocol" [I-D.ietf-weirds-json-response]. 341 6. IANA Considerations 343 This document does not specify any IANA actions. 345 7. Security Considerations 347 Security services for the operations specified in this document are 348 described in "Security Services for the Registration Data Access 349 Protocol" [I-D.ietf-weirds-rdap-sec]. As we identify specific use 350 cases for which security services are needed they will be described 351 here. 353 8. Acknowledgements 355 This document is derived from original work on RIR query formats 356 developed by Byron J. Ellacott of APNIC, Arturo L. Servin of 357 LACNIC, Kaveh Ranjbar of the RIPE NCC, and Andrew L. Newton of ARIN. 358 Additionally, this document incorporates DNR query formats originally 359 described by Francisco Arias and Steve Sheng of ICANN and Scott 360 Hollenbeck of Verisign. 362 The authors would like to acknowledge the following individuals for 363 their contributions to this document: Francisco Arias, Marc Blanchet, 364 Jean-Philippe Dionne, Edward Lewis, and John Levine. 366 9. References 368 9.1. Normative References 370 [I-D.ietf-weirds-json-response] 371 Newton, A. and S. Hollenbeck, "JSON Responses for the 372 Registration Data Access Protocol (RDAP)", draft-ietf- 373 weirds-json-response-02 (work in progress), January 2013. 375 [I-D.ietf-weirds-rdap-sec] 376 Hollenbeck, S. and N. Kong, "Security Services for the 377 Registration Data Access Protocol", draft-ietf-weirds- 378 rdap-sec-01 (work in progress), November 2012. 380 [I-D.ietf-weirds-using-http] 381 Newton, A., Ellacott, B., and N. Kong, "Using the 382 Registration Data Access Protocol (RDAP) with HTTP", 383 draft-ietf-weirds-using-http-01 (work in progress), 384 December 2012. 386 [RFC0952] Harrenstien, K., Stahl, M., and E. Feinler, "DoD Internet 387 host table specification", RFC 952, October 1985. 389 [RFC1123] Braden, R., "Requirements for Internet Hosts - Application 390 and Support", STD 3, RFC 1123, October 1989. 392 [RFC1166] Kirkpatrick, S., Stahl, M., and M. Recker, "Internet 393 numbers", RFC 1166, July 1990. 395 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 396 Requirement Levels", BCP 14, RFC 2119, March 1997. 398 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 399 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 400 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 402 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 403 Resource Identifier (URI): Generic Syntax", STD 66, RFC 404 3986, January 2005. 406 [RFC4290] Klensin, J., "Suggested Practices for Registration of 407 Internationalized Domain Names (IDN)", RFC 4290, December 408 2005. 410 [RFC4291] Hinden, R. and S. Deering, "IP Version 6 Addressing 411 Architecture", RFC 4291, February 2006. 413 [RFC4343] Eastlake, D., "Domain Name System (DNS) Case Insensitivity 414 Clarification", RFC 4343, January 2006. 416 [RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing 417 (CIDR): The Internet Address Assignment and Aggregation 418 Plan", BCP 122, RFC 4632, August 2006. 420 [RFC5396] Huston, G. and G. Michaelson, "Textual Representation of 421 Autonomous System (AS) Numbers", RFC 5396, December 2008. 423 [RFC5730] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)", 424 STD 69, RFC 5730, August 2009. 426 [RFC5733] Hollenbeck, S., "Extensible Provisioning Protocol (EPP) 427 Contact Mapping", STD 69, RFC 5733, August 2009. 429 [RFC5890] Klensin, J., "Internationalized Domain Names for 430 Applications (IDNA): Definitions and Document Framework", 431 RFC 5890, August 2010. 433 [RFC5891] Klensin, J., "Internationalized Domain Names in 434 Applications (IDNA): Protocol", RFC 5891, August 2010. 436 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 437 Address Text Representation", RFC 5952, August 2010. 439 9.2. Informative References 441 [REST] Fielding, R. and R. Taylor, "Principled Design of the 442 Modern Web Architecture", ACM Transactions on Internet 443 Technology Vol. 2, No. 2, May 2002. 445 [RFC3912] Daigle, L., "WHOIS Protocol Specification", RFC 3912, 446 September 2004. 448 [RFC4007] Deering, S., Haberman, B., Jinmei, T., Nordmark, E., and 449 B. Zill, "IPv6 Scoped Address Architecture", RFC 4007, 450 March 2005. 452 [RFC4627] Crockford, D., "The application/json Media Type for 453 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 455 Appendix A. Path Segment Specification for Search Queries 457 All of the path segments described in this document identify patterns 458 for exact-match lookups of data elements. We have explicitly omitted 459 specifications for search queries in the interest of first focusing 460 on more basic protocol operations. Once we understand how exact- 461 match queries will work we will attempt to define specifications for 462 search queries. 464 It is important to note that there are already multiple 465 implementations of RESTful RDAP-like prototypes that provide search 466 capabilities. For example: 468 ARIN: The American Registry for Internet Numbers (ARIN) has 469 published an API [1] (see Section 4.4.2) that describes using 470 plural forms of path segment identifiers (e.g. "domains") and 471 Matrix URIs [2] to indicate that a client is requesting a list of 472 values when searching for RIR registration data. A prototype 473 service [3] that implements this API is up and running. 474 Verisign: Verisign has deployed a prototype service [4] that 475 implements searches for DNR registration data using HTML query 476 strings (e.g. "?_PRE") to identify search parameters. For 477 example, "http://dnrd.verisignlabs.com/dnrd-ap/domain/ 478 verisign?_PRE" performs a search for domain names with a 479 "verisign" prefix. 481 Appendix B. Change Log 483 Initial -00: Adopted as working group document. 484 -01: Added "Conventions Used in This Document" section. Added 485 normative reference to draft-ietf-weirds-rdap-sec and some 486 wrapping text in the Security Considerations section. 487 -02: Removed "unified" from the title. Rewrote the last paragraph 488 of section 2. Edited the first paragraph of section 3 to more 489 clearly note that only one path segement is provided. Added 490 "bitmask" to "length" in section 3.1. Changed "lowest IP network" 491 to "smallest IP network" in section 3.1. Added "asplain" to the 492 description of autonomous system numbers in section 3.2. Minor 493 change from "semantics is" to "semantics are" in section 3.2. 494 Changed the last sentence in section 4 to more clearly specify 495 error response behavior. Added acknowledgements. Added a 496 paragraph in the introduction regarding future IETF standards and 497 extensibility. 498 -03: Changed 'query' to 'lookup' in document title to better 499 describe the 'exact match lookup' purpose of this document. 500 Included a multitude of minor additions and clarifications 501 provided by Marc Blanchet and Jean-Philippe Dionne. Modified the 502 domain and name server sections to include support for IDN 503 U-labels. 505 Authors' Addresses 507 Andrew Lee Newton 508 American Registry for Internet Numbers 509 3635 Concorde Parkway 510 Chantilly, VA 20151 511 US 513 Email: andy@arin.net 514 URI: http://www.arin.net 516 Scott Hollenbeck 517 Verisign Labs 518 12061 Bluemont Way 519 Reston, VA 20190 520 US 522 Email: shollenbeck@verisign.com 523 URI: http://www.verisignlabs.com/