idnits 2.17.1 draft-hollenbeck-dnrd-ap-query-01.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 (May 7, 2012) is 4370 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) -- Possible downref: Non-RFC (?) normative reference: ref. 'REST' ** Downref: Normative reference to an Unknown state RFC: RFC 952 ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Downref: Normative reference to an Informational RFC: RFC 3707 ** Downref: Normative reference to an Informational RFC: RFC 4290 ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) Summary: 7 errors (**), 0 flaws (~~), 1 warning (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force S. Hollenbeck 3 Internet-Draft Verisign Labs 4 Intended status: Standards Track S. Sheng 5 Expires: November 8, 2012 F. Arias 6 ICANN 7 May 7, 2012 9 Domain Name Registration Data Access Protocol Query Format 10 draft-hollenbeck-dnrd-ap-query-01 12 Abstract 14 This document describes a RESTful query format proposal for the 15 Domain Name Registration Data Access Protocol. 17 Status of this Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at http://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on November 8, 2012. 34 Copyright Notice 36 Copyright (c) 2012 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (http://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 52 2. Conventions Used in This Document . . . . . . . . . . . . . . 3 53 2.1. Acronyms and Abbreviations . . . . . . . . . . . . . . . . 3 54 3. Design Considerations . . . . . . . . . . . . . . . . . . . . 4 55 3.1. Why RESTful? . . . . . . . . . . . . . . . . . . . . . . . 4 56 4. Protocol Specification . . . . . . . . . . . . . . . . . . . . 5 57 4.1. Base URL Specification . . . . . . . . . . . . . . . . . . 6 58 4.2. Domain Path Segment Specification . . . . . . . . . . . . 6 59 4.3. Name Server Path Segment Specification . . . . . . . . . . 7 60 4.4. Contact Path Segment Specification . . . . . . . . . . . . 7 61 4.5. Registrar Name Path Segment Specification . . . . . . . . 8 62 4.6. Response Preference Specification . . . . . . . . . . . . 8 63 5. Query Parameters . . . . . . . . . . . . . . . . . . . . . . . 9 64 6. Client Identification . . . . . . . . . . . . . . . . . . . . 10 65 7. Internationalization Considerations . . . . . . . . . . . . . 10 66 7.1. Label Considerations . . . . . . . . . . . . . . . . . . . 10 67 7.2. Label Encoding . . . . . . . . . . . . . . . . . . . . . . 10 68 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 69 9. Security Considerations . . . . . . . . . . . . . . . . . . . 11 70 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 11 71 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 72 11.1. Normative References . . . . . . . . . . . . . . . . . . . 11 73 11.2. Informative References . . . . . . . . . . . . . . . . . . 12 74 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 13 76 1. Introduction 78 This document describes a specification for querying domain name 79 registration data using a RESTful web service and uniform query 80 patterns. The service is implemented using the Hypertext Transfer 81 Protocol (HTTP) [RFC2616] and conforms to the architectural 82 constraints of Representational State Transfer (REST) [REST]. 84 The protocol described in this specification is intended to address 85 deficiencies with the WHOIS protocol [RFC3912] that have been 86 identified over time, including: 88 Lack of standardized command structures, 90 lack of standardized output and error structures, 92 lack of support for internationalization and localization, and 94 lack of support for user identification, authentication, and 95 access control. 97 2. Conventions Used in This Document 99 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 100 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 101 document are to be interpreted as described in RFC 2119 [RFC2119]. 103 The terms "registry", "registrar", and "registrant" are to be 104 interpreted as described in RFC 3707 [RFC3707]. 106 2.1. Acronyms and Abbreviations 108 DNRD: Domain Name Registration Data 110 HTTP: Hypertext Transfer Protocol, specified in RFC 2616 [RFC2616] 112 HTTP/TLS: HTTP over TLS, specified in RFC 2818 [RFC2818] 114 IDN: Internationalized Domain Name, specified in RFC 5890 115 [RFC5890] 117 JSON: JavaScript Object Notation, based on a subset of the 118 JavaScript Programming Language standard [ECMA] 119 REST: Representational State Transfer [REST] 121 RWS: RESTful Web Service 123 TLS: Transport Layer Security, specified in RFC 5246 [RFC5246] 125 URI: Uniform Resource Identifier, specified in RFC 3986 [RFC3986] 127 URL: Uniform Resource Locator, specified in RFC 3986 [RFC3986] 129 XML: Extensible Markup Language, specified in W3C Recommendation 130 REC-xml-20081126 [W3C.REC-xml-20081126] 132 3. Design Considerations 134 Representational State Transfer (REST) is a style of software 135 architecture for distributed systems. The style describes six 136 constraints: client-server, stateless, cacheable, layered system, 137 code on demand (optional), and uniform interface. Systems that 138 comply with these constraints are designed to have the properties of 139 performance, scalability, simplicity, modifiability, visibility, 140 portability, and reliability. The principles of REST have been used 141 to design other protocols such as the ATOM publishing protocol 142 [RFC5023]. 144 A RESTful web service is a web service implemented using HTTP and the 145 principles of REST. It is a collection of resources, with three 146 defined aspects: 148 o The "verbs" of the service are those strictly defined by the HTTP 149 methods GET, PUT, POST, and DELETE, 151 o the "verbs" are used to act upon resources, and 153 o resources are addressable using URLs. 155 3.1. Why RESTful? 157 A RESTful approach to querying domain registration data offers 158 several advantages when compared to the WHOIS protocol, including: 160 Standardized output and error structures: outputs can be 161 structured using encoding technologies like JSON and XML, which 162 when paired with a well-defined specification will allow for 163 automated processing. 165 Support for internationalization: RWS structured data formats 166 include complete support for both internationalized registration 167 data and Internationalized Domain Names (IDNs) with U-labels. 169 Authentication and access control: HTTP, the transport for RWS, 170 supports multiple native user identification and authentication 171 schemes, and by using these capabilities RWS makes it possible to 172 implement registration data access control mechanisms. 174 Addressable service: RWS requires the use of a URI/URL standard 175 structure for each object/resource. This provides a way to 176 unambiguously refer to objects. 178 Increased usability: The inherent capabilities of the HTTP 179 protocol (such as redirects) can be used to provide additional 180 functionality, such as automatic referrals to more specific data 181 sources without requiring specialized parsing by the client. 183 Authenticity of origin: RWS provided over HTTP/TLS provides 184 confidence in the origin of the information. 186 Leverage existing infrastructure and expertise: RWS is HTTP-based 187 and is supported using popular, commonly deployed web server 188 infrastructures. 190 4. Protocol Specification 192 This section describes the DNRD-AP URL structure and methods used to 193 create the uniform patterns needed to submit queries over HTTP. Each 194 query is sent to the server in the form of an HTTP "GET" or HTTP 195 "HEAD" request. A "GET" request will return both response headers 196 and a response body. A "HEAD" request will return only response 197 headers. A "HEAD" request can be used to verify URL syntax or 198 resource availability without actually retrieving the requested 199 resource. 201 General specifications for using HTTP in a system to provide a 202 RESTful DNRD query service are described in X (the design team HTTP 203 draft). 205 Client-supplied parameters MUST be interpreted in a case-insensitive, 206 exact match manner in order to produce no more than one matching 207 result. Client parameters that can be used to match multiple 208 registry or registrar data elements are described in (the domain 209 search draft). 211 4.1. Base URL Specification 213 The uniform patterns start with a base URL [RFC3986] specified by the 214 service provider offering this service. Resource-type specific path 215 segments are then appended to the end of the base URL. The base URL 216 may contain its own path segments (e.g. http://example.com/... or 217 http://example.com/dnrd-ap/... ). 219 The resource types that can be used to construct path segments 220 include: 222 'domain': Used to identify a domain name query. 224 'nameserver': Used to identify a name server query. 226 'contact': Used to identify a contact query. 228 'registrar': Used to identify a registrar name query. 230 The resource type MAY be omitted from the path segment. If the 231 resource type is omitted, the path segment MUST be interpreted as a 232 domain path segment. 234 4.2. Domain Path Segment Specification 236 Syntax: domain/ or 238 The parameter represents a domain name as specified in 239 RFC 4343 [RFC4343]. Internationalized domain names represented in 240 both A-label and U-label formats [RFC5890] are also valid domain 241 names. The following URLs are example queries for domain name 242 registration information: 244 http://example.com/dnrd-ap/domain/example.com/ 245 http://example.com/dnrd-ap/example.com/ 247 HTTP GET Request Format: 249 GET /dnrd-ap/domain/example.com HTTP/1.1 250 Host: example.com 252 HTTP HEAD Request Format: 254 HEAD /dnrd-ap/domain/example.com HTTP/1.1 255 Host: example.com 257 4.3. Name Server Path Segment Specification 259 Syntax: nameserver/ 261 The parameter represents a host name as specified 262 in RFC 952 [RFC0952] and RFC 1123 [RFC1123]. Internationalized host 263 names represented in A-label format [RFC5890] are also valid host 264 names. The following URLs are example queries for name server 265 registration information: 267 http://example.com/dnrd-ap/nameserver/ns1.example.com/ 269 HTTP GET Request Format: 271 GET /dnrd-ap/nameserver/ns1.example.com/ HTTP/1.1 272 Host: example.com 274 HTTP HEAD Request Format: 276 HEAD /dnrd-ap/nameserver/ns1.example.com/ HTTP/1.1 277 Host: example.com 279 4.4. Contact Path Segment Specification 281 Syntax: contact/ 283 The parameter represents a contact identifier as 284 specified in RFC 5730 [RFC5730] and RFC 5733 [RFC5733]. The 285 following URL is an example query for contact registration 286 information: 288 http://example.com/dnrd-ap/contact/CID-4005/ 290 HTTP GET Request Format: 292 GET /dnrd-ap/contact/CID-4005/ HTTP/1.1 293 Host: example.com 295 HTTP HEAD Request Format: 297 HEAD /dnrd-ap/contact/CID-4005/ HTTP/1.1 298 Host: example.com 300 4.5. Registrar Name Path Segment Specification 302 Syntax: registrar/ 304 The parameter represents a Unicode text string as 305 specified in RFC 5198 [RFC5198]. The following URL is an example 306 query for registrar information: 308 http://example.com/dnrd-ap/registrar/Example Registrar, Inc./ 310 HTTP GET Request Format: 312 GET /dnrd-ap/registrar/Example Registrar, Inc./ HTTP/1.1 313 Host: example.com 315 HTTP HEAD Request Format: 317 HEAD /dnrd-ap/registrar/Example Registrar, Inc./ HTTP/1.1 318 Host: example.com 320 4.6. Response Preference Specification 322 DNRD-AP servers return responses encoded using one of multiple 323 algorithms. The client MAY signal the preferred format using an HTTP 324 "Accept:" header. The client can also signal the preferred format by 325 adding a DOS-file-style extension to the resource. For example, 326 "/domain/example.com.xml/". If the client specifies no preferred 327 format the server MUST encode the response using a default format. 328 If the client signals multiple formats with the HTTP "Accept:" 329 header, or one format with the HTTP "Accept:" header and another with 330 the extension style, the response will be encoded as described in 331 Section X of (the draft DNRD-AP response document). 333 The following media type values can be specified with the "Accept:" 334 header: 336 application/xml (for an XML-encoded response) 338 application/json (for a JSON-encoded response) 340 text/html (for an HTML-encoded response) 342 text/plain (for a plain text response) 344 HTTP GET Request Format for an XML-encoded Response: 346 GET /dnrd-ap/domain/example.com HTTP/1.1 347 Host: example.com 348 Accept: application/xml 350 HTTP HEAD Request Format for an XML-encoded Response: 352 HEAD /dnrd-ap/domain/example.com HTTP/1.1 353 Host: example.com 354 Accept: application/xml 356 Alternate HTTP GET Request Format for an XML-encoded Response: 358 GET /dnrd-ap/domain/example.com.xml HTTP/1.1 359 Host: example.com 361 Alternate HTTP HEAD Request Format for an XML-encoded Response: 363 HEAD /dnrd-ap/domain/example.com.xml HTTP/1.1 364 Host: example.com 366 HTTP GET Request Format for an XML- or JSON-encoded Response: 368 GET /dnrd-ap/domain/example.com HTTP/1.1 369 Host: example.com 370 Accept: application/xml,application/json 372 HTTP HEAD Request Format for an XML- or JSON-encoded Response: 374 HEAD /dnrd-ap/domain/example.com HTTP/1.1 375 Host: example.com 376 Accept: application/xml,application/json 378 5. Query Parameters 380 To overcome issues with misbehaving HTTP cache infrastructure, 381 clients may use the '__dnrd__cachebust' query parameter with a random 382 value of their choosing. Servers MUST ignore this query parameter. 384 The following is an example use of this parameter to retrieve the 385 domain registration data for the example.com domain: 387 http://example.com/dnrd-ap/domain/example.com?__dnrd_cachebust=xyz123 389 Clients SHOULD NOT send any other query parameters. 391 6. Client Identification 393 Access to resources can be restricted to clients that possess 394 identification credentials negotiated using an out-of-band mechanism. 395 For example, a service provider can provide clients with user names 396 and passwords as part of a service agreement to gain access to 397 restricted resources. If available, clients MAY provide user name 398 and password identification information to a server using the HTTP 399 "basic" authentication scheme described in RFC 2617 [RFC2617]. 400 Considerations for making authorization and access control decisions 401 based on client-provided identification information are described in 402 Section X of (the draft DNRD-AP response document). 404 Client user names and passwords MUST be protected using a facility 405 that provides privacy and integrity services to protect against 406 unintended disclosure and modification while in transit. At a 407 minimum, support for HTTP/TLS as described in RFC 2818 [RFC2818] MUST 408 be provided. Service providers can optionally specify and deploy 409 additional security services. 411 7. Internationalization Considerations 413 7.1. Label Considerations 415 There is value in supporting the ability to submit either a U-label 416 (Unicode form of an IDN label) or an A-label (ASCII form of an IDN 417 label) as a query argument to a DNRD service. Users may most often 418 prefer a U-label since this is more visually recognizable and 419 familiar than A-label strings, but users of programmatic interfaces 420 may wish to submit and display A-labels or may not be able to input 421 U-labels with their keyboard configuration. 423 Internationalized domain and host names can contain character 424 variants and variant labels as described in RFC 4290 [RFC4290]. 425 Clients that support queries for internationalized domain and host 426 names MUST accept service provider responses that describe variants 427 as specified in (the draft DNRD-AP response document). 429 7.2. Label Encoding 431 Internationalized labels can be encoded in any of three different 432 ways: 434 U-label only: A U-label is entered as part of a path segment. For 435 example, /domain/"U+82F1""U+96C4".example. 437 A-label only: A U-label is first converted to its corresponding 438 A-label before being submitted to the server. In the example 439 above, the U-label would be converted to "xn--dj1az91b", and the 440 path segment would be /domain/xn--dj1az91b.example. 442 IRI -> URI conversion: An IRI (which contains the U-label) is 443 converted to a URI using the algorithm described in RFC 3987 444 [RFC3987] before being submitted to the server. In the example 445 above, the label would be converted to "%E8%8B%B1%E9%9B%84" and 446 the path segment becomes /domain/%E8%8B%B1%E9%9B%84.example. 448 8. IANA Considerations 450 This document does not specify any IANA actions. 452 9. Security Considerations 454 All of the security considerations described for HTTP in RFC 2616 455 [RFC2616], HTTP Basic Authentication in RFC 2617 [RFC2617], HTTP Over 456 TLS in RFC 2818 [RFC2818], and their successors are applicable. 457 There are no additional considerations introduced by this 458 specification. 460 10. Acknowledgements 462 The authors would like to acknowledge the following individuals for 463 their contributions to this document: Andrew Newton. 465 11. References 467 11.1. Normative References 469 [REST] Fielding, R. and R. Taylor, "Principled Design of the 470 Modern Web Architecture", ACM Transactions on Internet 471 Technology Vol. 2, No. 2 , May 2002. 473 [RFC0952] Harrenstien, K., Stahl, M., and E. Feinler, "DoD Internet 474 host table specification", RFC 952, October 1985. 476 [RFC1123] Braden, R., "Requirements for Internet Hosts - Application 477 and Support", STD 3, RFC 1123, October 1989. 479 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 480 Requirement Levels", BCP 14, RFC 2119, March 1997. 482 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 483 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 484 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 486 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 487 Leach, P., Luotonen, A., and L. Stewart, "HTTP 488 Authentication: Basic and Digest Access Authentication", 489 RFC 2617, June 1999. 491 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 493 [RFC3707] Newton, A., "Cross Registry Internet Service Protocol 494 (CRISP) Requirements", RFC 3707, February 2004. 496 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 497 Resource Identifier (URI): Generic Syntax", STD 66, 498 RFC 3986, January 2005. 500 [RFC4290] Klensin, J., "Suggested Practices for Registration of 501 Internationalized Domain Names (IDN)", RFC 4290, 502 December 2005. 504 [RFC4343] Eastlake, D., "Domain Name System (DNS) Case Insensitivity 505 Clarification", RFC 4343, January 2006. 507 [RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network 508 Interchange", RFC 5198, March 2008. 510 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 511 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 513 [RFC5730] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)", 514 STD 69, RFC 5730, August 2009. 516 [RFC5733] Hollenbeck, S., "Extensible Provisioning Protocol (EPP) 517 Contact Mapping", STD 69, RFC 5733, August 2009. 519 [RFC5890] Klensin, J., "Internationalized Domain Names for 520 Applications (IDNA): Definitions and Document Framework", 521 RFC 5890, August 2010. 523 11.2. Informative References 525 [ECMA] European Computer Manufacturers Association, "ECMAScript 526 Language Specification 3rd Edition", December 1999, . 531 [RFC3912] Daigle, L., "WHOIS Protocol Specification", RFC 3912, 532 September 2004. 534 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 535 Identifiers (IRIs)", RFC 3987, January 2005. 537 [RFC5023] Gregorio, J. and B. de hOra, "The Atom Publishing 538 Protocol", RFC 5023, October 2007. 540 [W3C.REC-xml-20081126] 541 Sperberg-McQueen, C., Yergeau, F., Bray, T., Maler, E., 542 and J. Paoli, "Extensible Markup Language (XML) 1.0 (Fifth 543 Edition)", World Wide Web Consortium Recommendation REC- 544 xml-20081126, November 2008, 545 . 547 Authors' Addresses 549 Scott Hollenbeck 550 Verisign Labs 551 12061 Bluemont Way 552 Reston, VA 20190 553 US 555 Email: shollenbeck@verisign.com 556 URI: http://www.verisignlabs.com/ 558 Steve Sheng 559 Internet Corporation for Assigned Names and Numbers 560 4676 Admiralty Way, Suite 330 561 Marina del Rey, CA 90292 562 US 564 Phone: +1.310.823.9358 565 Email: steve.sheng@icann.org 566 Francisco Arias 567 Internet Corporation for Assigned Names and Numbers 568 4676 Admiralty Way, Suite 330 569 Marina del Rey, CA 90292 570 US 572 Phone: +1.310.823.9358 573 Email: francisco.arias@icann.org