idnits 2.17.1 draft-wullink-restful-epp-00.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 : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([RFC5730], [RFC5731], [RFC5732], [RFC5733]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (April 23, 2012) is 4385 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' ** 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 5246 (Obsoleted by RFC 8446) -- Obsolete informational reference (is this intentional?): RFC 5849 (Obsoleted by RFC 6749) Summary: 4 errors (**), 0 flaws (~~), 1 warning (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Wullink 3 Internet-Draft SIDN 4 Intended status: Standards Track M. Davids 5 Expires: October 25, 2012 R. Gieben 6 SIDN Labs 7 April 23, 2012 9 RESTful interface for the Extensible Provisioning Protocol 10 draft-wullink-restful-epp-00 12 Abstract 14 This document specifies a 'RESTful interface for EPP' (REPP) with the 15 aim to improve efficiency and interoperability of EPP systems. 17 This document includes a new EPP Protocol Extension as well as a 18 mapping of [RFC5730] XML-commands to an HTTP based (RESTful) 19 interface. Existing semantics and mappings as defined in [RFC5731], 20 [RFC5732] and [RFC5733] are largely retained and reusable in RESTful 21 EPP. 23 With REPP, no session is created on the EPP server. Each request 24 from client to server will contain all of the information necessary 25 to understand the request. The server will close the connection 26 after each HTTP request. 28 Status of this Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at http://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on October 25, 2012. 45 Copyright Notice 47 Copyright (c) 2012 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (http://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 63 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 64 3. Conventions Used in This Document . . . . . . . . . . . . . . 5 65 4. Stateless EPP or REPP . . . . . . . . . . . . . . . . . . . . 5 66 5. Drawbacks Associated with Stateful EPP . . . . . . . . . . . . 6 67 6. EPP Extension Framework . . . . . . . . . . . . . . . . . . . 6 68 7. Resource Naming Convention . . . . . . . . . . . . . . . . . . 7 69 8. Message Exchange . . . . . . . . . . . . . . . . . . . . . . . 8 70 8.1. HTTP Method Definitions . . . . . . . . . . . . . . . . . 8 71 8.2. REPP Request . . . . . . . . . . . . . . . . . . . . . . . 8 72 8.2.1. Payload Data . . . . . . . . . . . . . . . . . . . . . 8 73 8.2.2. Request Headers . . . . . . . . . . . . . . . . . . . 9 74 8.2.3. General Headers . . . . . . . . . . . . . . . . . . . 9 75 8.3. REPP Response . . . . . . . . . . . . . . . . . . . . . . 9 76 8.3.1. Response Headers . . . . . . . . . . . . . . . . . . . 9 77 8.3.2. General Headers . . . . . . . . . . . . . . . . . . . 10 78 8.4. Error Handling . . . . . . . . . . . . . . . . . . . . . . 10 79 9. Interface Mapping . . . . . . . . . . . . . . . . . . . . . . 11 80 9.1. Hello . . . . . . . . . . . . . . . . . . . . . . . . . . 12 81 9.2. Password . . . . . . . . . . . . . . . . . . . . . . . . . 13 82 9.3. Session Management Resources . . . . . . . . . . . . . . . 13 83 9.3.1. Login . . . . . . . . . . . . . . . . . . . . . . . . 13 84 9.3.2. Logout . . . . . . . . . . . . . . . . . . . . . . . . 13 85 9.4. Query Resources . . . . . . . . . . . . . . . . . . . . . 13 86 9.4.1. Check . . . . . . . . . . . . . . . . . . . . . . . . 14 87 9.4.2. Info . . . . . . . . . . . . . . . . . . . . . . . . . 14 88 9.4.2.1. Domain Name . . . . . . . . . . . . . . . . . . . 14 89 9.4.3. Poll . . . . . . . . . . . . . . . . . . . . . . . . . 15 90 9.4.3.1. Poll Request . . . . . . . . . . . . . . . . . . . 15 91 9.4.3.2. Poll Ack . . . . . . . . . . . . . . . . . . . . . 15 92 9.4.4. Transfer Query Op . . . . . . . . . . . . . . . . . . 15 93 9.5. Object Transform Resources . . . . . . . . . . . . . . . . 16 94 9.5.1. Create . . . . . . . . . . . . . . . . . . . . . . . . 16 95 9.5.2. Delete . . . . . . . . . . . . . . . . . . . . . . . . 16 96 9.5.3. Renew . . . . . . . . . . . . . . . . . . . . . . . . 16 97 9.5.4. Update . . . . . . . . . . . . . . . . . . . . . . . . 16 98 9.5.5. Transfer . . . . . . . . . . . . . . . . . . . . . . . 17 99 9.5.5.1. Create Op . . . . . . . . . . . . . . . . . . . . 17 100 9.5.5.2. Cancel Op . . . . . . . . . . . . . . . . . . . . 17 101 9.5.5.3. Approve Op . . . . . . . . . . . . . . . . . . . . 17 102 9.5.5.4. Reject Op . . . . . . . . . . . . . . . . . . . . 18 103 10. Transport Considerations . . . . . . . . . . . . . . . . . . . 18 104 11. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 19 105 11.1. RESTful EPP XML Schema . . . . . . . . . . . . . . . . . . 20 106 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 107 13. Internationalization Considerations . . . . . . . . . . . . . 21 108 14. Security Considerations . . . . . . . . . . . . . . . . . . . 21 109 15. Obsolete EPP Result Codes . . . . . . . . . . . . . . . . . . 21 110 16. References . . . . . . . . . . . . . . . . . . . . . . . . . . 22 111 16.1. Normative References . . . . . . . . . . . . . . . . . . . 22 112 16.2. Informative References . . . . . . . . . . . . . . . . . . 22 113 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 23 114 A.1. X-REPP-authinfo . . . . . . . . . . . . . . . . . . . . . 23 115 A.1.1. Domain Info with Authorization Data . . . . . . . . . 23 116 A.2. Hello Example . . . . . . . . . . . . . . . . . . . . . . 24 117 A.2.1. RESTful Request: . . . . . . . . . . . . . . . 24 118 A.2.2. RESTful Response: . . . . . . . . . . . . . . 24 119 A.3. Password Example . . . . . . . . . . . . . . . . . . . . . 24 120 A.3.1. RESTful Change Password Request: . . . . . . . . . . . 24 121 A.3.2. RESTful Change Password Response: . . . . . . . . . . 25 122 A.4. Domain Create Example . . . . . . . . . . . . . . . . . . 25 123 A.4.1. RESTful Domain Create Request: . . . . . . . . . . . . 25 124 A.4.2. RESTful Domain Create Response: . . . . . . . . . . . 26 125 A.5. Domain Delete Example . . . . . . . . . . . . . . . . . . 26 126 A.5.1. RESTful Domain Delete Request: . . . . . . . . . . . . 26 127 A.5.2. RESTful Domain Delete Response: . . . . . . . . . . . 27 128 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 27 130 1. Introduction 132 This document describes a new EPP Protocol Extension and a mapping of 133 [RFC5730] XML-commands to a [REST] interface which, in contrast to 134 the current EPP specification, is stateless. It aims to provide a 135 mechanism that is more suitable for complex, high availability 136 environments, as well as for environments where TCP connections can 137 be unreliable. 139 The newly defined protocol extensions described in this memo leverage 140 the HTTP protocol [RFC2616] and the principles of [REST]. Conforming 141 to the REST constraints is generally referred to as being "RESTful". 142 Hence we dubbed the new protocol extension: "RESTful EPP" or "REPP" 143 for short. 145 RFC 5730 [RFC5730] Section 2.1 describes that EPP can be layered over 146 multiple transport protocols. Currently, the EPP transport over TCP 147 [RFC5734] is the only widely deployed transport mapping for EPP. 148 This same section defines that newly defined transport mappings must 149 preserve the stateful nature of EPP. 151 With REPP, no session is created on the EPP server. Each request 152 from client to server will contain all of the information necessary 153 to understand the request. The server will close the connection 154 after each HTTP request. 156 With a stateless mechanism, some drawbacks of EPP (as mentioned in 157 Section 5) are circumvented. 159 A good understanding of the EPP base protocol specification [RFC5730] 160 is advised, to grasp the extension and mapping described in this 161 document. 163 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 164 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 165 document are to be interpreted as described in [RFC2119]. 167 2. Terminology 169 In this document the following terminology is used. 171 REST - Representational State Transfer ([REST]). An architectural 172 style. 174 RESTful - A RESTful web service is a web service implemented using 175 HTTP and the principles of [REST]. 177 EPP RFCs - This is a reference to the EPP version 1.0 178 specifications [RFC5730], [RFC5731], [RFC5732] and [RFC5733]. 180 Stateful EPP - The definition according to Section 2 of [RFC5730]. 182 Stateless EPP or REPP - The RESTful EPP interface described in 183 this document. 185 URL - A Uniform Resource Locator as defined in [RFC3986]. 187 Resource - A network data object or service that can be identified 188 by a URL. 190 Interface mapping - The mapping of [RFC5730] XML commands to 191 Stateless EPP. 193 3. Conventions Used in This Document 195 XML is case sensitive. Unless stated otherwise, XML specifications 196 and examples provided in this document MUST be interpreted in the 197 character case presented to develop a conforming implementation. 199 4. Stateless EPP or REPP 201 REPP is designed to solve, in the spirit of [RFC3375], the drawbacks 202 as mentioned in the next paragraph and yet maintain compatibility 203 with existing object mapping definitions. 205 The design intent is to provide a clear, clean and self-explanatory 206 interface that can easily be integrated with existing software 207 systems. On the basis of these principles a [REST] architectural 208 style was chosen. A client interacts with a REPP server via HTTP 209 requests. 211 A server implementing REPP, MUST NOT keep any client state and is not 212 compatible with [RFC5730], Section 2, which explicitly states that 213 EPP is stateful. 215 REPP cannot be classified as an EPP transport mapping as defined in 216 [RFC5730], Section 2.1. With REPP, the EPP [RFC5730] XML commands 217 are mapped to a REST interface and as such, RESTful EPP is regarded 218 as an interface mapping. Since REPP relies on a newly defined XSD 219 schema with protocol elements, RESTful EPP can also be referred to as 220 an [RFC5730], Section 2.7.1 protocol extension. 222 5. Drawbacks Associated with Stateful EPP 224 [RFC5734] requires a stateful TCP session between a client and the 225 EPP server. Often this is accomplished by setting up a session with 226 a and keeping it alive for some time before issuing a 227 . This may pose challenges in load-balanced environments, 228 when a running session for whatever reason suddenly has to be 229 switched from one EPP server to another and state is kept on a per 230 server basis. 232 [RFC5734] EPP sessions can wind up in a state where they are no 233 longer linked to an active TCP connection, especially in an 234 environment where TCP connectivity is flaky. This may raise problems 235 in situations where session limits are enforced. 237 REPP is designed to avoid these drawbacks, hence making the 238 interaction between an EPP client and an EPP server more robust and 239 efficient. 241 6. EPP Extension Framework 243 According to [RFC3735], Section 2, EPP provides an extension 244 framework that allows features to be added at the protocol, object, 245 and command-response levels. RESTful EPP (REPP) affects the 246 following levels: 248 Protocol extension: RESTful EPP defines a new namespace 249 "urn:ietf:params:xml:ns:restful-epp-1.0". It declares new 250 elements, which MUST be used for RESTful EPP. The root element 251 for the new namespace is the element. This element MUST 252 contain an object mapping defined by the object mapping schemas. 254 Object extension: RESTful EPP does not define any new object level 255 extensions. The existing object level extensions can be reused. 256 However, any existing object mapping element, including any added 257 extension elements it might contain, SHALL be added as a child to 258 the new element. 260 Command-Response extension: RESTful EPP does not use the "command" 261 concept, because the 'command' concept is part of a RPC style and 262 not a RESTful style. A REST URL and HTTP method combination have 263 replaced the command structure. All command extensions can be 264 reused as a rest extension. 266 RESTful EPP reuses the existing response messages defined in the 267 EPP RFCs. The EPP response MUST be added to the standard 268 element and SHALL NOT be part of any element. 270 The DNSSEC [RFC5910], E.164 number [RFC4114] and ENUM validation 271 information [RFC5076] extension mapping elements can be added as 272 children of the element. 274 7. Resource Naming Convention 276 A resource can be a single unique object identifier e.g. a domain 277 name, or a collection of objects. The complete set of objects a 278 client can use in registry operations MUST be identified by {context- 279 root}/{version}/{collection} 281 o {context-root} is the base URL which MUST be specified by each 282 registry. 284 o {version} is a label which identifies the interface version. This 285 is the equivalent of the element in the EPP RFCs. 287 o {collection} MUST be substituted by "domains", "hosts" or 288 "contacts", referring to either [RFC5731], [RFC5732] or [RFC5733]. 290 o A trailing slash MAY be added to each request. Implementations 291 MUST consider requests which only differ with respect to this 292 trailing slash as identical. 294 A specific object instance MUST be identified by {context-root}/ 295 {version}/{collection}/{id} where {id} is a unique object identifier 296 described in EPP RFCs. 298 An example domain name resource following this naming convention, 299 would look like this: 301 /rest/v1/domains/example.com 303 The level below a collection MUST be used to identify a object 304 instance, the level below an object instance MUST be used to identify 305 attributes of the object instance. 307 With RESTful EPP the object identifiers are embedded in URLs. This 308 makes any object identifier in the request messages superfluous. 309 However, since the goal of RESTful EPP is to stay compatible with the 310 existing EPP object mapping schemas, this redundancy is accepted as a 311 trade off. Removing the object identifier from the request message 312 would require new object mapping schemas. 314 The server MUST return HTTP Status-Code 412 when the object 315 identifier (for example , or ) 316 in the HTTP message-body does not match the {id} object identifier in 317 the URL. 319 8. Message Exchange 321 A [RFC5730] request includes a command- and object mapping to which a 322 command must be applied. With RESTful EPP, some of the request 323 messages are expressed by a combination of a resource and an HTTP 324 method. 326 Data (payload) belonging to a request is put into the HTTP message- 327 body or into an HTTP request-header, depending on the nature of the 328 request as defined in Section 9. 330 An HTTP request MUST contain no more than one EPP message. HTTP 331 requests MUST be processed independently of each other and in the 332 same order as the server receives them. 334 8.1. HTTP Method Definitions 336 The operations on resources MUST be performed by an HTTP method. The 337 server MUST support the following "verbs" ([REST]). 339 GET: Request a representation of a resource or a collection of 340 resources. 342 PUT: Update an existing resource. 344 POST: Create a new resource. 346 DELETE: Delete an existing resource. 348 HEAD: Check for the existence of a resource. 350 OPTIONS: Request a greeting. 352 8.2. REPP Request 354 8.2.1. Payload Data 356 The payload data of a RESTful EPP request can be transmitted to the 357 server using the POST, PUT and GET HTTP methods. 359 POST and PUT: Payload data, when required, MUST be added to the 360 message-body. 362 GET: When payload data is required, it concerns . This 363 SHALL be put in the "X-REPP-authinfo" HTTP request-header. 365 8.2.2. Request Headers 367 HTTP request-headers are used to transmit additional or optional 368 request data to the server. All RESTful EPP HTTP headers must have 369 the "X-REPP-" prefix. 371 X-REPP-cltrid: The client transaction identifier is the equivalent 372 of the element in the EPP RFCs and MUST be used 373 accordingly. When this header is present in a client request, an 374 equivalent element in the message-body MAY also be present, but 375 MUST than be consistent with the header. 377 X-REPP-authinfo: The X-REPP-authinfo request-header is the 378 alternative of the element in the EPP RFCs and MUST be 379 used accordingly. It MUST contain the entire authorization 380 information element as mentioned in Section 11.1. 382 8.2.3. General Headers 384 General-headers MAY be used as defined in HTTP/1.1 [RFC2616]. For 385 REPP, the following general-headers are REQUIRED in HTTP requests. 387 Accept-Language: This request-header is equivalent to the 388 element in the EPP command, expect that the usage of this 389 header by the client is OPTIONAL. The server MUST support the use 390 of HTTP Accept-Language header in client requests. The client MAY 391 issue a to discover the languages known by the server. 392 Multiple servers in a load-balanced environment SHOULD reply with 393 consistent elements in a . Clients SHOULD NOT 394 expect that obtained information remains consistent between 395 different requests. Languages not supported by the server default 396 to "en". 398 8.3. REPP Response 400 The server response is made up out of a HTTP Status-Code, HTTP 401 response-headers and it MAY contain an EPP XML message in the HTTP 402 message-body. 404 8.3.1. Response Headers 406 HTTP response-headers are used to transmit additional response data 407 to the client. All RESTful EPP HTTP headers must have the "X-REPP-" 408 prefix. 410 X-REPP-svtrid: This header is the equivalent of the element 411 in the EPP RFCs and MUST be used accordingly. If an HTTP message- 412 body with the EPP XML equivalent exists, both values MUST 413 be consistent. 415 X-REPP-cltrid: This header is the equivalent of the element 416 in the EPP RFCs and MUST be used accordingly. If an HTTP message- 417 body with the EPP XML equivalent exists, both values MUST 418 be consistent. 420 X-REPP-eppcode: This header is the equivalent of the 421 element in te EPP RFCs and MUST be used accordingly.If an HTTP 422 message-body with The EPP XML equivalent exists, 423 both values MUST be consistent. 425 X-REPP-avail: The EPP avail header is the alternative of the "avail" 426 attribute of the element in a check response and 427 MUST be used accordingly. 429 8.3.2. General Headers 431 General-headers MAY be used as defined in HTTP/1.1 [RFC2616]. For 432 REPP, the following general-headers are REQUIRED in HTTP responses. 434 Cache-Control: This general-header... [TBD: the idea is to prohibit 435 caching. Even though it will probably work and be useful in some 436 scenario's, it also complicates matters.] 438 Connection: The server MUST add the "Connection: close" general- 439 header to each HTTP response. 441 8.4. Error Handling 443 RESTful EPP is designed atop of the HTTP protocol, both are an 444 application layer protocol with their own status- and result codes. 445 The value of an EPP result code and HTTP Status-Code MUST remain 446 independent of each other. E.g. an EPP result code indicating an 447 error can be combined with an HTTP request with Status-Code 200. 449 HTTP Status-Code: MUST only return status information related to the 450 HTTP protocol, When there is a mismatch between the object 451 identifier in the HTTP message-body and the resource URL HTTP 452 Status-Code 412 MUST be returned. 454 The following EPP result codes specify an interface-, 455 authorization-, authentication- or an internal server error and 456 MUST NOT be used in RESTful EPP. Instead, when the related error 457 occurs, an HTTP Status-Code MUST be returned in accordance to the 458 mapping shown in Table 1. 460 EPP result code: MUST only return EPP result information relating to 461 the EPP protocol. The HTTP header "X-REPP-eppcode" MUST be used 462 for EPP result code information. 464 EPP result code and HTTP Status-Code mapping. 466 +----------------------------------------+------------------+ 467 | EPP result code | HTTP Status-Code | 468 +----------------------------------------+------------------+ 469 | 2000 unknown command | 400 | 470 | 2201 authorization error | 401 | 471 | 2202 Invalid authorization information | 401 | 472 | 2101 unimplemented command | 501 | 473 +----------------------------------------+------------------+ 475 Table 1 477 9. Interface Mapping 479 This section describes the details of the REST interface by referring 480 to the [RFC5730] Section 2.9 Protocol Commands and defining how these 481 are mapped to a REST request. 483 Each RESTful operation consists of four parts: 1) the resource, 2) 484 the HTTP method 3) the request payload, which is the HTTP message- 485 body of the request, 4) the response payload, being the HTTP message- 486 body of the response. 488 The following table lists them all and the subsequent sections 489 provide details for each request. Each URL in the table is prefixed 490 with "/rest/v1/". To make the table fit we use the following 491 abbreviations: 493 {c}: An abbreviation for {collection}: this MUST be substituted with 494 "domains", "hosts", "contacts" or "messages". 496 {i}: An abbreviation for {id}: a domain name, host name, contact id 497 or a message id. 499 (opt): The item is optional. 501 Command mapping from Stateful EPP to Stateless EPP. 503 +---------------+-------------------+----------------+--------------+ 504 | EPP command | RESTful EPP | Request | Response | 505 | | resource | payload | payload | 506 +---------------+-------------------+----------------+--------------+ 507 | Hello | OPTIONS / | N/A | | 508 | Login | N/A | N/A | N/A | 509 | Logout | N/A | N/A | N/A | 510 | Check | HEAD {c}/{i} | N/A | N/A | 511 | Info | GET {c}/{i} | AUTH(opt) | | 512 | Poll request | GET messages | N/A | | 513 | Poll ack | DELETE | N/A | ack | 514 | | messages/{i} | | | 515 | Transfer | GET | AUTH(opt) | | 516 | (query) | {c}/{i}/transfer | | | 517 | New password | PUT password | password | N/A | 518 | Create | POST {c} | | | 519 | Delete | DELETE {c}/{i} | N/A | | 520 | Renew | PUT | | | 521 | | {c}/{i}/validity | | | 522 | Transfer | POST | | | 523 | (create) | {c}/{i}/transfer | | | 524 | Transfer | DELETE | N/A | | 525 | (cancel) | {c}/{i}/transfer | | | 526 | Transfer | PUT | N/A | | 527 | (approve) | {c}/{i}/transfer | | | 528 | Transfer | DELETE | N/A | | 529 | (reject) | {c}/{i}/transfer | | | 530 | Update | PUT {c}/{i} | | | 531 +---------------+-------------------+----------------+--------------+ 533 Table 2 535 9.1. Hello 537 o Request: OPTIONS / 539 o Request payload: N/A 541 o Response payload: 543 The (Section 2.4 RFC 5730) MUST NOT be automatically 544 transmitted by the server with each new HTTP connection. The server 545 MUST send a element in response to a OPTIONS method on the 546 root "/" resource. 548 A stateless EPP client MUST NOT use a XML payload. 550 9.2. Password 552 o Request: PUT password/ 554 o Request payload: New password 556 o Response payload: N/A 558 The client MUST use the HTTP PUT method on the password resource. 559 This is the equivalent of the element in the command 560 described in [RFC5730]. The request message-body MUST contain the 561 new password which MUST be encoded using Base64 [RFC4648]. 563 After a successful password change, the HTTP header "X-REPP-eppcode" 564 must contain EPP result code 1000, otherwise an appropriate 2xxx 565 range EPP result code. 567 9.3. Session Management Resources 569 The server MUST NOT create a client session. Login credentials MUST 570 be added to each client request. This SHOULD be done with any of the 571 well known HTTP authentication mechanisms. Basic authentication MAY 572 be used but MUST be combined with TLS [RFC5246] for added security. 574 To protect information exchanged between an EPP client and an EPP 575 server [RFC5734] Section 9 level of security is REQUIRED. 577 9.3.1. Login 579 The command MUST NOT be implemented by a server. The 580 element has been replaced by the Password resource. The 581 element has been replaced by the Accept-Language HTTP request-header. 582 The element has no equivalent in RESTful EPP, the client can 583 use a to discover the server supported namespace URIs. The 584 server MUST check every XML namespace used in client XML requests. 585 An unsupported namespace MUST result in the appropriate EPP result 586 code. 588 9.3.2. Logout 590 The command MUST NOT be implemented by the server. The 591 server MUST add the "Connection: close" HTTP general-header to each 592 response. 594 9.4. Query Resources 595 9.4.1. Check 597 o Request: HEAD {collection}/{id} 599 o Request payload: N/A 601 o Response payload: N/A 603 The HTTP header X-REPP-avail with a value of "1" or "0" is returned, 604 depending on whether the object can be provisioned or not. 606 A request MUST be limited to checking only one resource {id} 607 at a time. This may seem a step backwards when compared to the check 608 command defined in the object mapping of the EPP RFCs where multiple 609 object-ids are allowed inside a check command. The RESTful version 610 of the check is however more efficient. 612 The server MUST NOT support any elements described in 613 the EPP object mapping RFCs. 615 9.4.2. Info 617 o Request: GET {collection}/{id} 619 o Request payload: OPTIONAL X-REPP-authinfo HTTP header with 620 . 622 o Response payload: Object response. 624 A object request MUST be performed with the HTTP GET method on 625 a resource identifying an object instance. The response MUST be a 626 response message as described in object mapping of the EPP RFCs, 627 possibly extended with an [RFC3915] extension element (). 630 9.4.2.1. Domain Name 632 A domain name differs from a contact- and host in the 633 sense that EPP Domain Name Mapping [RFC5731], Section 3.1.2 describes 634 an OPTIONAL "hosts" attribute for the element. This 635 attribute is mapped to additional REST resources to be used in a 636 domain name info request. 638 The specified default value is "all". This default is mapped to a 639 shortcut, the resource object instance URL without any additional 640 labels. 642 o default: GET domains/{id} 644 o Hosts=all: GET domains/{id}/all 646 o Hosts=del: GET domains/{id}/del 648 o Hosts=sub: GET domains/{id}/sub 650 o Hosts=none: GET domains/{id}/none 652 The server MAY require the client to include additional authorization 653 information. The authorization data MUST be sent with the "X-REPP- 654 authinfo" HTTP request-header. 656 9.4.3. Poll 658 9.4.3.1. Poll Request 660 o Request: GET messages/ 662 o Request payload: N/A 664 o Response payload: Poll request response message. 666 A client MUST use the HTTP GET method on the messages collection to 667 request the message at the head of the queue. 669 9.4.3.2. Poll Ack 671 o Request: DELETE messages/{id} 673 o Request payload: N/A 675 o Response payload: Poll ack response message 677 A client MUST use the HTTP DELETE method on a message instance to 678 remove the message from the message queue. 680 9.4.4. Transfer Query Op 682 o Request: GET {collection}/{id}/transfer 684 o Request payload: Optional X-REPP-authinfo HTTP header with 685 687 o Response payload: Transfer query response message. 689 A query MUST be performed with the HTTP GET method on the 690 transfer resource of a specific object instance. 692 9.5. Object Transform Resources 694 9.5.1. Create 696 o Request: POST {collection}/ 698 o Request payload: Object . 700 o Response payload: Object response. 702 A client MUST create a new object with the HTTP POST method in 703 combination with an object collection. 705 9.5.2. Delete 707 o Request: DELETE {collection}/{id} 709 o Request payload: N/A 711 o Response payload: Object response. 713 Deleting an object from the registry database MUST be performed with 714 the HTTP DELETE method on a REST resource specifying a specific 715 object instance. 717 9.5.3. Renew 719 o Request: PUT {collection}/{id}/validity 721 o Request payload: Object . 723 o Response payload: Object response. 725 Renewing an object is only specified by [RFC5731], the 726 command has been mapped to a validity resource. 728 9.5.4. Update 730 o Request: PUT {collection}/{id} 732 o Request payload: Object:update. 734 o Response payload: Update response message 736 An object request MUST be performed with the HTTP PUT method 737 on a specific object resource. The payload MUST contain an described in the EPP RFCs, possibly extended with [RFC3915] 740 extension elements. 742 9.5.5. Transfer 744 Transferring an object from one sponsoring client to another is only 745 specified in [RFC5731] and [RFC5733]. The command has 746 been mapped to a transfer resource. 748 The semantics of the HTTP DELETE method are determined by the role of 749 the client executing the method. For the current sponsoring 750 registrar the DELETE method is defined as "reject transfer". For the 751 new sponsoring registrar the DELETE method is defined as "cancel 752 transfer". 754 9.5.5.1. Create Op 756 o Request: POST {collection}/{id}/transfer 758 o Request payload: . 760 o Response Payload: Transfer start response. 762 Initiating a transfer MUST be done by creating a new "transfer" 763 resource with the HTTP POST method on a specific domain name or 764 contact object instance. The server MAY require authorization 765 information to validate the transfer request. 767 9.5.5.2. Cancel Op 769 o Request: DELETE {collection}/{id}/transfer 771 o Request payload: N/A 773 o Response payload: Transfer cancel response message. 775 The new sponsoring client MUST use the HTTP DELETE method to cancel a 776 requested transfer. 778 9.5.5.3. Approve Op 780 o Request: PUT {collection}/{id}/transfer 782 o Request payload: N/A 784 o Response payload: Transfer approve response message. 786 The current sponsoring client MUST use the HTTP PUT method to approve 787 a transfer requested by the new sponsoring client. 789 9.5.5.4. Reject Op 791 o Request: DELETE {collection}/{id}/transfer 793 o Request payload: N/A 795 o Response payload: Transfer reject response message 797 The current sponsoring client MUST use the HTTP DELETE method to 798 reject a transfer requested by the new sponsoring client. 800 10. Transport Considerations 802 Section 2.1 of the EPP core protocol specification [RFC5730] 803 describes considerations to be addressed by protocol transport 804 mappings. This document addresses each of the considerations using a 805 combination of features described in this document and features 806 provided by HTTP as follows: 808 o HTTP is an application layer protocol which uses TCP as a 809 transport protocol. TCP includes features to provide reliability, 810 flow control, ordered delivery, and congestion control. Section 811 1.5 of RFC 793 describes these features in detail; congestion 812 control principles are described further in RFC 2581 and RFC 2914. 813 HTTP is a stateless protocol and as such it does not maintain any 814 client state or session. 816 o The stateful nature of EPP is no longer preserved through managed 817 sessions. There still is a controlled message exchanges because 818 HTTP uses TCP as transport layer protocol. 820 o HTTP 1.1 allows persistent connections which can be used to send 821 multiple HTTP requests to the server using the same connection. 822 The server MUST NOT allow persistent connections. 824 o The server MUST NOT allow pipelining and return EPP result code 825 2002 if pipelining is detected. 827 o Batch-oriented processing (combining multiple EPP commands in a 828 single HTTP request) MUST NOT be permitted. 830 o Section 8 of this document describes features to frame EPP request 831 data by adding the data to an HTTP request message-body or 832 request-header. 834 o A request processing failure has no influence on the processing of 835 other requests. The stateless nature of the server allows a 836 client to retry a failed request or send another request. 838 11. Formal Syntax 840 The extension used by RESTful EPP is specified in XML Schema 841 notation. The formal syntax presented here is a complete schema 842 representation of RESTful EPP suitable for automated validation of 843 EPP XML instances. The schema is based on the XML schemas defined in 844 [RFC5730]. [RFC3735] Section 2.3 states that it MUST be announced in 845 the element. 847 11.1. RESTful EPP XML Schema 849 The RESTful EPP Schema. 851 852 859 860 862 865 866 867 RESTful EPP schema. 868 869 871 872 874 877 879 881 882 883 884 885 886 888 890 Figure 1 892 12. IANA Considerations 894 [TBD: This draft defines three resource collections; domains, 895 contacts, hosts. This may require an IANA RESTful EPP collection 896 protocol registry. RFC3688 defines an IANA XML Registry and 897 'restful-epp-1.0' defined here would have to be added to that: 898 http://www.iana.org/assignments/xml-registry-index.html ] 900 13. Internationalization Considerations 902 [TBD: Do we need them? ] 904 14. Security Considerations 906 RFC 5730 describes a command for transmitting client 907 credentials. This command MUST NOT be used for RESTful EPP. Due to 908 the stateless nature of REST clients MUST transmit their credentials 909 with each request. The validation of the user credentials must be 910 performed by an out-of-band mechanism. This could be done with Basic 911 and Digest access authentication [RFC2617] or with the use of OAuth 912 [RFC5849]. 914 EPP does not use XML encryption to protect messages. Furthermore, 915 RESTful EPP HTTP servers are vulnerable to common denial-of-service 916 attacks. Therefore, the security considerations of [RFC5734] also 917 apply to RESTful EPP. 919 15. Obsolete EPP Result Codes 921 The following result codes specified in [RFC5730] are no longer 922 meaningful in RESTful EPP and MUST NOT be used. 924 +------+------------------------------------------------------------+ 925 | Code | Reason | 926 +------+------------------------------------------------------------+ 927 | 1500 | The logout command is not used anymore. | 928 | 2002 | Commands can now be sent in any order. | 929 | 2100 | The protocol version is embedded in the base URL of the | 930 | | interface. | 931 | 2200 | The login command is not used anymore. | 932 +------+------------------------------------------------------------+ 934 16. References 935 16.1. Normative References 937 [REST] Fielding, R., "Architectural Styles and the Design of 938 Network-based Software Architectures", 2000. 940 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 941 Requirement Levels", BCP 14, RFC 2119, March 1997. 943 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 944 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 945 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 947 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 948 Leach, P., Luotonen, A., and L. Stewart, "HTTP 949 Authentication: Basic and Digest Access Authentication", 950 RFC 2617, June 1999. 952 [RFC3915] Hollenbeck, S., "Domain Registry Grace Period Mapping for 953 the Extensible Provisioning Protocol (EPP)", RFC 3915, 954 September 2004. 956 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 957 Encodings", RFC 4648, October 2006. 959 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 960 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 962 [RFC5730] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)", 963 STD 69, RFC 5730, August 2009. 965 [RFC5731] Hollenbeck, S., "Extensible Provisioning Protocol (EPP) 966 Domain Name Mapping", STD 69, RFC 5731, August 2009. 968 [RFC5732] Hollenbeck, S., "Extensible Provisioning Protocol (EPP) 969 Host Mapping", STD 69, RFC 5732, August 2009. 971 [RFC5733] Hollenbeck, S., "Extensible Provisioning Protocol (EPP) 972 Contact Mapping", STD 69, RFC 5733, August 2009. 974 [RFC5734] Hollenbeck, S., "Extensible Provisioning Protocol (EPP) 975 Transport over TCP", STD 69, RFC 5734, August 2009. 977 16.2. Informative References 979 [RFC3375] Hollenbeck, S., "Generic Registry-Registrar Protocol 980 Requirements", RFC 3375, September 2002. 982 [RFC3735] Hollenbeck, S., "Guidelines for Extending the Extensible 983 Provisioning Protocol (EPP)", RFC 3735, March 2004. 985 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 986 Resource Identifier (URI): Generic Syntax", STD 66, 987 RFC 3986, January 2005. 989 [RFC4114] Hollenbeck, S., "E.164 Number Mapping for the Extensible 990 Provisioning Protocol (EPP)", RFC 4114, June 2005. 992 [RFC5076] Hoeneisen, B., "ENUM Validation Information Mapping for 993 the Extensible Provisioning Protocol", RFC 5076, 994 December 2007. 996 [RFC5849] Hammer-Lahav, E., "The OAuth 1.0 Protocol", RFC 5849, 997 April 2010. 999 [RFC5910] Gould, J. and S. Hollenbeck, "Domain Name System (DNS) 1000 Security Extensions Mapping for the Extensible 1001 Provisioning Protocol (EPP)", RFC 5910, May 2010. 1003 Appendix A. Examples 1005 In these examples, lines starting with "C:" represent data sent by a 1006 protocol client and lines starting with "S:" represent data returned 1007 by a REPP protocol server. Indentation and white space in examples 1008 are provided only to illustrate element relationships and are not 1009 REQUIRED features of this protocol. 1011 A.1. X-REPP-authinfo 1013 A.1.1. Domain Info with Authorization Data 1015 The X-REPP-authinfo header in a Domain Info Request might look like 1016 this: 1018 1019 1020 1021 1022 1023 passwordfordomain 1024 1025 1026 1027 1029 So this HTTP header MUST contain the entire authorization information 1030 element as mentioned in Section 11.1. 1032 A.2. Hello Example 1034 A.2.1. RESTful Request: 1036 C: OPTIONS /rest/v1/ HTTP/1.1 1037 C: Host: repp.example.com 1038 C: Cache-Control: no-cache 1039 C: Authorization: Basic amRvZTp0ZXN0 1040 C: Pragma: no-cache 1041 C: Accept: application/epp+xml 1042 C: Accept-Encoding: gzip,deflate 1043 C: Accept-Language: en 1044 C: Accept-Charset: utf-8 1046 A.2.2. RESTful Response: 1048 S: HTTP/1.1 200 OK 1049 S: Date: Sun, 10 Apr 2012 12:00:00 UTC 1050 S: Server: Acme REPP server v1.0 1051 S: Content-Length: 799 1052 S: Content-Type: application/epp+xml 1053 S: Connection: close 1054 S: 1055 S: 1056 S: 1057 S: 1058 S: 1059 S: 1060 S: 1062 A.3. Password Example 1064 A.3.1. RESTful Change Password Request: 1066 C: PUT /rest/v1/password/ HTTP/1.1 1067 C: Host: repp.example.com 1068 C: Cache-Control: no-cache 1069 C: Authorization: Basic amRvZTp0ZXN0 1070 C: Pragma: no-cache 1071 C: Accept-Language: en 1072 C: Accept-Charset: utf-8 1073 C: X-REPP-cltrid: ABC-12345 1074 C: Content-Type: text/plain 1075 C: Content-Length: 44 1076 C: 1077 C: bWFpbG1lYXQ6bWFhcnRlbi53dWxsaW5rQHNpZG4ubmw= 1079 A.3.2. RESTful Change Password Response: 1081 S: HTTP/1.1 200 OK 1082 S: Date: Sun, 10 Apr 2012 12:00:00 UTC 1083 S: Server: Acme REPP server v1.0 1084 S: Content-Language: en 1085 S: Content-Length: 0 1086 S: X-REPP-cltrid: ABC-12345 1087 S: X-REPP-svtrid: 54321-XYZ 1088 S: X-REPP-eppcode: 1000 1089 S: Connection: close 1091 A.4. Domain Create Example 1093 A.4.1. RESTful Domain Create Request: 1095 C: POST /rest/v1/domains/ HTTP/1.1 1096 C: Host: repp.example.com 1097 C: Cache-Control: no-cache 1098 C: Authorization: Basic amRvZTp0ZXN0 1099 C: Pragma: no-cache 1100 C: Accept-Language: en 1101 C: Accept-Charset: utf-8 1102 C: Accept: application/epp+xml 1103 C: X-REPP-cltrid: ABC-12345 1104 C: Content-Type: text/plain 1105 C: Content-Length: 543 1107 C: 1108 C: 1110 C: 1111 C: 1112 C: 1113 C: 1114 C: 1115 C: 1116 C: 1117 C: 1119 A.4.2. RESTful Domain Create Response: 1121 S: HTTP/1.1 200 OK 1122 S: Date: Sun, 10 Apr 2012 12:00:00 UTC 1123 S: Server: Acme REPP server v1.0 1124 S: Content-Language: en 1125 S: Content-Length: 642 1126 S: X-REPP-cltrid: ABC-12345 1127 S: X-REPP-svtrid: 54321-XYZ 1128 S: X-REPP-eppcode: 1000 1129 S: Content-Type: application/epp+xml 1130 S: Connection: close 1132 S: 1133 S: 1135 S: 1136 S: 1137 S: Command completed successfully 1138 S: 1139 S: 1140 S: 1142 S: 1143 S: 1144 S: 1145 S: ABC-12345 1146 S: 54321-XYZ 1147 S: 1148 S: 1149 S: 1151 A.5. Domain Delete Example 1153 A.5.1. RESTful Domain Delete Request: 1155 C: DELETE /rest/v1/domains/example.com HTTP/1.1 1156 C: Host: repp.example.com 1157 C: Cache-Control: no-cache 1158 C: Authorization: Basic amRvZTp0ZXN0 1159 C: Pragma: no-cache 1160 C: Accept-Language: en 1161 C: Accept-Charset: utf-8 1162 C: X-REPP-cltrid: ABC-12345 1164 A.5.2. RESTful Domain Delete Response: 1166 S: HTTP/1.1 200 OK 1167 S: Date: Sun, 10 Apr 2012 12:00:00 UTC 1168 S: Server: Acme REPP server v1.0 1169 S: Content-Language: en 1170 S: Content-Length: 505 1171 S: X-REPP-cltrid: ABC-12345 1172 S: X-REPP-svtrid: 54321-XYZ 1173 S: X-REPP-eppcode: 1000 1174 S: Content-Type: application/epp+xml 1175 S: Connection: close 1177 S: 1178 S: 1180 S: 1181 S: 1182 S: Command completed successfully 1183 S: 1184 S: 1185 S: ABC-12345 1186 S: 54321-XYZ 1187 S: 1188 S: 1189 S: 1191 Authors' Addresses 1193 Maarten Wullink 1194 SIDN 1195 Meander 501 1196 Arnhem, 6825 MD 1197 NL 1199 Phone: +31 26 3525555 1200 Email: maarten.wullink@sidn.nl 1201 URI: https://sidn.nl/ 1202 Marco Davids 1203 SIDN Labs 1204 Meander 501 1205 Arnhem, 6825 MD 1206 NL 1208 Phone: +31 26 3525555 1209 Email: marco.davids@sidn.nl 1210 URI: https://sidn.nl/ 1212 R. (Miek) Gieben 1213 SIDN Labs 1214 Meander 501 1215 Arnhem, 6825 MD 1216 NL 1218 Phone: +31 26 3525555 1219 Email: miek.gieben@sidn.nl 1220 URI: https://sidn.nl/