idnits 2.17.1 draft-ietf-weirds-rdap-query-05.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (June 12, 2013) is 3971 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 488 -- Looks like a reference, but probably isn't: '2' on line 490 -- Looks like a reference, but probably isn't: '3' on line 492 -- Looks like a reference, but probably isn't: '4' on line 493 == Outdated reference: A later version (-14) exists of draft-ietf-weirds-json-response-04 == Outdated reference: A later version (-12) exists of draft-ietf-weirds-rdap-sec-04 -- 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-05 -- 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 (~~), 4 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Newton 3 Internet-Draft ARIN 4 Intended status: Standards Track S. Hollenbeck 5 Expires: December 14, 2013 Verisign Labs 6 June 12, 2013 8 Registration Data Access Protocol Lookup Format 9 draft-ietf-weirds-rdap-query-05 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 December 14, 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 3.6. Help Path Segment Specification . . . . . . . . . . . . . 7 62 4. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 8 63 5. Internationalization Considerations . . . . . . . . . . . . . 8 64 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 65 7. Security Considerations . . . . . . . . . . . . . . . . . . . 8 66 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 8 67 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 68 9.1. Normative References . . . . . . . . . . . . . . . . . . 9 69 9.2. Informative References . . . . . . . . . . . . . . . . . 10 70 Appendix A. Path Segment Specification for Search Queries . . . 11 71 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 11 72 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 12 74 1. Conventions Used in This Document 76 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 77 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 78 document are to be interpreted as described in RFC 2119 [RFC2119]. 80 1.1. Acronyms and Abbreviations 82 IDN: Internationalized Domain Name 83 IDNA: Internationalized Domain Names in Applications 84 DNR: Domain Name Registry 85 RDAP: Registration Data Access Protocol 86 REST: Representational State Transfer State Transfer. The term 87 was first described in a doctoral dissertation [REST]. 88 RESTful: an adjective that describes a service using HTTP and the 89 principles of REST. 90 RIR: Regional Internet Registry 92 2. Introduction 94 This document describes a specification for querying registration 95 data using a RESTful web service and uniform query patterns. The 96 service is implemented using the Hypertext Transfer Protocol (HTTP) 97 [RFC2616]. 99 The protocol described in this specification is intended to address 100 deficiencies with the WHOIS protocol [RFC3912] that have been 101 identified over time, including: 103 o Lack of standardized command structures, 104 o lack of standardized output and error structures, 105 o lack of support for internationalization and localization, and 106 o lack of support for user identification, authentication, and 107 access control. 109 The patterns described in this document purposefully do not encompass 110 all of the methods employed in the WHOIS and RESTful web services of 111 all of the RIRs and DNRs. The intent of the patterns described here 112 are to enable lookups of: 114 o networks by IP address, 115 o autonomous system numbers by number, 116 o reverse DNS meta-data by domain, 117 o name servers by name, 118 o registrars by name, and 119 o entities (such as contacts) by identifier. 121 It is envisioned that each registry will continue to maintain NICNAME 122 /WHOIS and/or RESTful web services specific to their needs and those 123 of their constituencies, and the information retrieved through the 124 patterns described here may reference such services. 126 Likewise, future IETF standards may add additional patterns for 127 additional query types (for example, "/domains" for a domain search 128 query). And Section 4 defines a simple pattern namespacing scheme to 129 accomodate custom extensions that will not interfere with the 130 patterns defined in this document or patterns defined in future IETF 131 standards. 133 WHOIS services, in general, are read-only services. Therefore URL 134 [RFC3986] patterns specified in this document are only applicable to 135 the HTTP [RFC2616] GET and HEAD methods. 137 This document does not describe the results or entities returned from 138 issuing the described URLs with an HTTP GET. It is envisioned that 139 other documents will describe these entities in various serialization 140 formats, such as JavaScript Object Notation (JSON, [RFC4627]). 142 Additionally, resource management, provisioning and update functions 143 are out of scope for this document. Registries have various and 144 divergent methods covering these functions, and it is unlikely a 145 uniform approach for these functions will ever be possible. 147 HTTP contains mechanisms for servers to authenticate clients and for 148 clients to authenticate servers (from which authorization schemes may 149 be built) so such mechanisms are not described in this document. 150 Policy, provisioning, and processing of authentication and 151 authorization are out-of-scope for this document as deployments will 152 have to make choices based on local criteria. Specified 153 authentication mechanisms MUST use HTTP. 155 3. Path Segment Specification 157 The uniform patterns start with a base URL [RFC3986] specified by 158 each registry or any other service provider offering this service. 159 The base URL is followed by a resource-type-specific path segment. 160 The base URL may contain its own path segments (e.g. http:// 161 example.com/... or http://example.com/restful-WHOIS/... ). The 162 characters used to form a path segment are limited to those that can 163 be used to form a URI as specified in RFC 3986 [RFC3986]. 165 The resource type path segments are: 167 o 'ip': IP networks and associated data referenced using either an 168 IPv4 or IPv6 address. 169 o 'autnum': Autonomous system registrations and associated data 170 referenced using an AS Plain autonomous system number. 171 o 'domain': Reverse DNS (RIR) or domain name (DNR) information and 172 associated data referenced using a fully-qualified domain name. 173 o 'nameserver': Used to identify a name server information query. 174 o 'entity': Used to identify an entity information query. 176 3.1. IP Network Path Segment Specification 178 Syntax: ip/ or ip// 180 Queries for information about IP networks are of the form /ip/XXX/... 181 or /ip/XXX/YY/... where the path segment following 'ip' is either an 182 IPv4 [RFC1166] or IPv6 [RFC5952] address (i.e. XXX) or an IPv4 or 183 IPv6 CIDR [RFC4632] notation address block (i.e. XXX/YY). 184 Semantically, the simpler form using the address can be thought of as 185 a CIDR block with a bitmask length of 32 for IPv4 and a bitmask 186 length of 128 for IPv6. A given specific address or CIDR may fall 187 within multiple IP networks in a hierarchy of networks, therefore 188 this query targets the "most-specific" or smallest IP network which 189 completely encompasses it in a hierarchy of IP networks. 191 The IPv4 and IPv6 address formats supported in this query are 192 described in section 3.2.2 of [RFC3986], as IPv4address and 193 IPv6address ABNF definitions. Any valid IPv6 text address format 194 [RFC4291] can be used, compressed or not compressed. The restricted 195 rules to write a text representation of an IPv6 address [RFC5952] are 196 not mandatory. However, the zone id [RFC4007] is not appropriate in 197 this context and therefore prohibited. 199 This is an example URL for the most specific network containing 200 192.0.2.0: 202 /ip/192.0.2.0 204 This is an example of a URL the most specific network containing 205 192.0.2.0/24: 207 /ip/192.0.2.0/24 209 This is an example URL for the most specific network containing 210 2001:db8:1:1::1: 212 /ip/2001:db8:1:1::1 214 3.2. Autonomous System Path Segment Specification 216 Syntax: autnum/ 218 Queries for information regarding autonomous system number 219 registrations are of the form /autnum/XXX/... where XXX is an asplain 220 autonomous system number [RFC5396]. In some registries, registration 221 of autonomous system numbers is done on an individual number basis, 222 while other registries may register blocks of autonomous system 223 numbers. The semantics of this query are such that if a number falls 224 within a range of registered blocks, the target of the query is the 225 block registration, and that individual number registrations are 226 considered a block of numbers with a size of 1. 228 For example, to find information on autonomous system number 65551, 229 the following path would be used: 231 /autnum/65551 233 The following path would be used to find information on 4-byte 234 autonomous system number 65538: 236 /autnum/65538 238 3.3. Domain Path Segment Specification 240 Syntax: domain/ 242 Queries for domain information are of the form /domain/XXXX/..., 243 where XXXX is a fully-qualified domain name [RFC4343] in either the 244 in-addr.arpa or ip6.arpa zones (for RIRs) or a fully-qualified domain 245 name in a zone administered by the server operator (for DNRs). 246 Internationalized domain names represented in either A-label or 247 U-label format [RFC5890] are also valid domain names. IDN labels 248 SHOULD NOT be represented as a mixture of A-labels and U-labels. 250 If the client sends the server an IDN in U-label format, servers that 251 support IDNs MUST convert the IDN into A-label format and perform 252 IDNA processing as specified in RFC 5891 [RFC5891]. The server 253 should perform an exact match lookup using the A-label. 255 The following path would be used to find information describing the 256 zone serving the network 192.0.2/24: 258 /domain/2.0.192.in-addr.arpa 260 The following path would be used to find information describing the 261 zone serving the network 2001:db8:1::/48: 263 /domain/1.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa 265 The following path would be used to find information for the 266 example.com domain name: 268 /domain/example.com 270 The following path would be used to find information for the 271 xn--xemple-9ua.example IDN: 273 /domain/xn--xemple-9ua.example 275 3.4. Name Server Path Segment Specification 277 Syntax: nameserver/ 279 The parameter represents a fully qualified name as 280 specified in RFC 952 [RFC0952] and RFC 1123 [RFC1123]. 281 Internationalized names represented in either A-label or U-label 282 format [RFC5890] are also valid name server names. IDN labels SHOULD 283 NOT be represented as a mixture of A-labels and U-labels. 285 If the client sends the server an IDN in U-label format, servers that 286 support IDNs MUST convert the IDN into A-label format and perform 287 IDNA processing as specified in RFC 5891 [RFC5891]. The server 288 should perform an exact match lookup using the A-label. 290 The following path would be used to find information for the 291 ns1.example.com name server: 293 /nameserver/ns1.example.com 295 The following path would be used to find information for the 296 ns1.xn--xemple-9ua.example name server: 298 /nameserver/ns1.xn--xemple-9ua.example 300 3.5. Entity Path Segment Specification 302 Syntax: entity/ 304 The parameter represents an entity (such as a contact, 305 registrant, or registrar) identifier. For example, for some DNRs 306 contact identifiers are specified in RFC 5730 [RFC5730] and RFC 5733 307 [RFC5733]. 309 The following path would be used to find information for the entity 310 associated with handle CID-4005: 312 /entity/CID-4005 314 3.6. Help Path Segment Specification 316 Syntax: help 318 The help path segment can be used to request helpful information 319 (command syntax, terms of service, privacy policy, rate limiting 320 policy, supported authentication methods, supported extensions, 321 technical support contact, etc.) from an RDAP server. The response 322 to "help" should provide basic information that a client needs to 323 successfully use the service. The following path would be used to 324 return "help" information: 326 /help 328 4. Extensibility 330 This document describes path segment specifications for a limited 331 number of objects commonly registered in both RIRs and DNRs. It does 332 not attempt to describe path segments for all of the objects 333 registered in all registries. Custom path segments can be created 334 for objects not specified here using the process described in 335 Section TBD of "Using HTTP for RESTful Whois Services by Internet 336 Registries" [I-D.ietf-weirds-using-http]. 338 Custom path segments can be created by prefixing the segment with a 339 unique identifier followed by an underscore character (0x5F). For 340 example, a custom entity path segment could be created by prefixing 341 "entity" with "custom_", producing "custom_entity". Servers MUST 342 return an appropriate failure status code for a request with an 343 unrecognized path segment. 345 5. Internationalization Considerations 347 There is value in supporting the ability to submit either a U-label 348 (Unicode form of an IDN label) or an A-label (ASCII form of an IDN 349 label) as a query argument to an RDAP service. Clients capable of 350 processing non-ASCII characters may prefer a U-label since this is 351 more visually recognizable and familiar than A-label strings, but 352 clients using programmatic interfaces might find it easier to submit 353 and display A-labels if they are unable to input U-labels with their 354 keyboard configuration. Both query forms are acceptable. 356 Internationalized domain and name server names can contain character 357 variants and variant labels as described in RFC 4290 [RFC4290]. 358 Clients that support queries for internationalized domain and name 359 server names MUST accept service provider responses that describe 360 variants as specified in "JSON Responses for the Registration Data 361 Access Protocol" [I-D.ietf-weirds-json-response]. 363 6. IANA Considerations 365 This document does not specify any IANA actions. 367 7. Security Considerations 369 Security services for the operations specified in this document are 370 described in "Security Services for the Registration Data Access 371 Protocol" [I-D.ietf-weirds-rdap-sec]. 373 8. Acknowledgements 374 This document is derived from original work on RIR query formats 375 developed by Byron J. Ellacott of APNIC, Arturo L. Servin of LACNIC, 376 Kaveh Ranjbar of the RIPE NCC, and Andrew L. Newton of ARIN. 377 Additionally, this document incorporates DNR query formats originally 378 described by Francisco Arias and Steve Sheng of ICANN and Scott 379 Hollenbeck of Verisign. 381 The authors would like to acknowledge the following individuals for 382 their contributions to this document: Francisco Arias, Marc Blanchet, 383 Ernie Dainow, Jean-Philippe Dionne, Behnam Esfahbod, Edward Lewis, 384 and John Levine. 386 9. References 388 9.1. Normative References 390 [I-D.ietf-weirds-json-response] 391 Newton, A. and S. Hollenbeck, "JSON Responses for the 392 Registration Data Access Protocol (RDAP)", draft-ietf- 393 weirds-json-response-04 (work in progress), June 2013. 395 [I-D.ietf-weirds-rdap-sec] 396 Hollenbeck, S. and N. Kong, "Security Services for the 397 Registration Data Access Protocol", draft-ietf-weirds- 398 rdap-sec-04 (work in progress), June 2013. 400 [I-D.ietf-weirds-using-http] 401 Newton, A., Ellacott, B., and N. Kong, "HTTP usage in the 402 Registration Data Access Protocol (RDAP)", draft-ietf- 403 weirds-using-http-05 (work in progress), May 2013. 405 [RFC0952] Harrenstien, K., Stahl, M., and E. Feinler, "DoD Internet 406 host table specification", RFC 952, October 1985. 408 [RFC1123] Braden, R., "Requirements for Internet Hosts - Application 409 and Support", STD 3, RFC 1123, October 1989. 411 [RFC1166] Kirkpatrick, S., Stahl, M., and M. Recker, "Internet 412 numbers", RFC 1166, July 1990. 414 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 415 Requirement Levels", BCP 14, RFC 2119, March 1997. 417 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 418 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 419 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 421 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 422 Resource Identifier (URI): Generic Syntax", STD 66, RFC 423 3986, January 2005. 425 [RFC4290] Klensin, J., "Suggested Practices for Registration of 426 Internationalized Domain Names (IDN)", RFC 4290, December 427 2005. 429 [RFC4291] Hinden, R. and S. Deering, "IP Version 6 Addressing 430 Architecture", RFC 4291, February 2006. 432 [RFC4343] Eastlake, D., "Domain Name System (DNS) Case Insensitivity 433 Clarification", RFC 4343, January 2006. 435 [RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing 436 (CIDR): The Internet Address Assignment and Aggregation 437 Plan", BCP 122, RFC 4632, August 2006. 439 [RFC5396] Huston, G. and G. Michaelson, "Textual Representation of 440 Autonomous System (AS) Numbers", RFC 5396, December 2008. 442 [RFC5730] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)", 443 STD 69, RFC 5730, August 2009. 445 [RFC5733] Hollenbeck, S., "Extensible Provisioning Protocol (EPP) 446 Contact Mapping", STD 69, RFC 5733, August 2009. 448 [RFC5890] Klensin, J., "Internationalized Domain Names for 449 Applications (IDNA): Definitions and Document Framework", 450 RFC 5890, August 2010. 452 [RFC5891] Klensin, J., "Internationalized Domain Names in 453 Applications (IDNA): Protocol", RFC 5891, August 2010. 455 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 456 Address Text Representation", RFC 5952, August 2010. 458 9.2. Informative References 460 [REST] Fielding, R. and R. Taylor, "Principled Design of the 461 Modern Web Architecture", ACM Transactions on Internet 462 Technology Vol. 2, No. 2, May 2002. 464 [RFC3912] Daigle, L., "WHOIS Protocol Specification", RFC 3912, 465 September 2004. 467 [RFC4007] Deering, S., Haberman, B., Jinmei, T., Nordmark, E., and 468 B. Zill, "IPv6 Scoped Address Architecture", RFC 4007, 469 March 2005. 471 [RFC4627] Crockford, D., "The application/json Media Type for 472 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 474 Appendix A. Path Segment Specification for Search Queries 476 All of the path segments described in this document identify patterns 477 for exact-match lookups of data elements. We have explicitly omitted 478 specifications for search queries in the interest of first focusing 479 on more basic protocol operations. Once we understand how exact- 480 match queries will work we will attempt to define specifications for 481 search queries in other documents. 483 It is important to note that there are already multiple 484 implementations of RESTful RDAP-like prototypes that provide search 485 capabilities. For example: 487 ARIN: The American Registry for Internet Numbers (ARIN) has 488 published an API [1] (see Section 4.4.2) that describes using 489 plural forms of path segment identifiers (e.g. "domains") and 490 Matrix URIs [2] to indicate that a client is requesting a list of 491 values when searching for RIR registration data. A prototype 492 service [3] that implements this API is up and running. 493 Verisign: Verisign has deployed a prototype service [4] that 494 implements searches for DNR registration data using HTML query 495 strings (e.g. "?_PRE") to identify search parameters. For 496 example, "http://dnrd.verisignlabs.com/dnrd-ap/domain/ 497 verisign?_PRE" performs a search for domain names with a 498 "verisign" prefix. 500 Appendix B. Change Log 502 Initial -00: Adopted as working group document. 503 -01: Added "Conventions Used in This Document" section. Added 504 normative reference to draft-ietf-weirds-rdap-sec and some 505 wrapping text in the Security Considerations section. 506 -02: Removed "unified" from the title. Rewrote the last paragraph 507 of section 2. Edited the first paragraph of section 3 to more 508 clearly note that only one path segement is provided. Added 509 "bitmask" to "length" in section 3.1. Changed "lowest IP network" 510 to "smallest IP network" in section 3.1. Added "asplain" to the 511 description of autonomous system numbers in section 3.2. Minor 512 change from "semantics is" to "semantics are" in section 3.2. 513 Changed the last sentence in section 4 to more clearly specify 514 error response behavior. Added acknowledgements. Added a 515 paragraph in the introduction regarding future IETF standards and 516 extensibility. 517 -03: Changed 'query' to 'lookup' in document title to better 518 describe the 'exact match lookup' purpose of this document. 519 Included a multitude of minor additions and clarifications 520 provided by Marc Blanchet and Jean-Philippe Dionne. Modified the 521 domain and name server sections to include support for IDN 522 U-labels. 523 -04: Updated the domain and name server sections to use .example IDN 524 U-labels. Added text to note that mixed IDN labels SHOULD NOT be 525 used. Fixed broken sentences in Section 5. 526 -05: Added "help" path segment. 528 Authors' Addresses 530 Andrew Lee Newton 531 American Registry for Internet Numbers 532 3635 Concorde Parkway 533 Chantilly, VA 20151 534 US 536 Email: andy@arin.net 537 URI: http://www.arin.net 539 Scott Hollenbeck 540 Verisign Labs 541 12061 Bluemont Way 542 Reston, VA 20190 543 US 545 Email: shollenbeck@verisign.com 546 URI: http://www.verisignlabs.com/