idnits 2.17.1 draft-lozano-icann-registry-interfaces-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 : ---------------------------------------------------------------------------- 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 (March 31, 2013) is 4044 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Unused Reference: 'RFC3688' is defined on line 444, but no explicit reference was found in the text == Outdated reference: A later version (-10) exists of draft-arias-noguchi-dnrd-objects-mapping-02 Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force G. Lozano 3 Internet-Draft ICANN 4 Intended status: Informational March 31, 2013 5 Expires: October 2, 2013 7 ICANN Registry Interfaces 8 draft-lozano-icann-registry-interfaces-00 10 Abstract 12 This document describes the interfaces between ICANN and Registries 13 and Data Escrow Agents. These interfaces allow Registries and Data 14 Escrow Agents upload the reports described in the Base Agreement of 15 the new gTLD Applicant Guidebook. 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 October 2, 2013. 34 Copyright Notice 36 Copyright (c) 2013 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 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 53 2. Specification 2 - Data Escrow Reporting . . . . . . . . . . . 3 54 2.1. Registry Operator Reporting . . . . . . . . . . . . . . . 3 55 2.2. Data Escrow Agent Reporting . . . . . . . . . . . . . . . 4 56 3. Specification 3 - Registry Operator Monthly Reporting . . . . 5 57 3.1. Per-Registrar Transactions Report . . . . . . . . . . . . 5 58 3.2. Registry Functions Activity Report . . . . . . . . . . . . 7 59 4. IIRDEA Result Object . . . . . . . . . . . . . . . . . . . . . 8 60 5. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 8 61 5.1. IIRDEA Result Schema . . . . . . . . . . . . . . . . . . . 8 62 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 10 63 7. Change History . . . . . . . . . . . . . . . . . . . . . . . . 11 64 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 65 9. Security Considerations . . . . . . . . . . . . . . . . . . . 11 66 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 67 10.1. Normative References . . . . . . . . . . . . . . . . . . . 11 68 10.2. Informative References . . . . . . . . . . . . . . . . . . 11 69 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 11 71 1. Introduction 73 This document describes the interfaces between ICANN and Registries 74 and Data Escrow Agents. These interfaces allow Registries and Data 75 Escrow Agents upload the reports described in the Base Agreement of 76 the new gTLD Applicant Guidebook. 78 Authentication credentials for the interfaces described above are 79 provided per TLD. 81 1.1. Terminology 83 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 84 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 85 document are to be interpreted as described in RFC 2119 [RFC2119]. 87 XML is case sensitive. Unless stated otherwise, XML specifications 88 and examples provided in this document MUST be interpreted in the 89 character case presented in order to develop a conforming 90 implementation. 92 "iirdea-1.0" is used as an abbreviation for 93 "urn:ietf:params:xml:ns:iirdea-1.0". The XML namespace prefix 94 "iirdea" is used, but implementations MUST NOT depend on it and 95 instead employ a proper namespace-aware XML parser and serializer to 96 interpret and output the XML documents. 98 2. Specification 2 - Data Escrow Reporting 100 This section describes the interfaces provided by ICANN for Registry 101 Operators and Data Escrow Agents to comply with the reporting 102 provisions detailed in Specification 2 of the Base Agreement of the 103 new gTLD Applicant Guidebook [ICANN-GTLD-AGB-20120604]. 105 2.1. Registry Operator Reporting 107 The new gTLD base Registry Agreement, Specification 2, Part A, 108 Section 7 requires Registry Operators to provide ICANN with a written 109 statement that includes a copy of the report generated upon creation 110 of an escrow deposit and a statement that the deposit has been 111 inspected by the Registry Operator and is complete and accurate. 113 In order to comply with this provision, the Registry Operator sends a 114 report to ICANN for each escrow deposit successfully received by the 115 Data Escrow Agent, using the PUT HTTP verb in the interface provided 116 by ICANN at: 118 https://ry-api.icann.org/report/registry-escrow-report 120 Registries MUST send a object as defined in 121 [I-D.arias-noguchi-dnrd-objects-mapping]. 123 After successfully receiving a object, ICANN 124 validates it and provides a result code in the same HTTP transaction. 126 After sending the result code, the interface closes the TCP 127 connection. 129 At 23:59 UTC, the last successful validated object 130 is stored and used by ICANN. 132 2.1.1. Result codes 134 The following table lists the result codes of the interface: 136 +-----------+-------------------------------------------------------+ 137 | Result | Description | 138 | Code | | 139 +-----------+-------------------------------------------------------+ 140 | 1000 | No ERRORs were found and the report has been accepted | 141 | | by ICANN. | 142 | 2001 | The report did not validate against the schema. | 143 | 2002 | A report for that day already exists, the cut-off | 144 | | date already passed. | 145 +-----------+-------------------------------------------------------+ 147 Data Escrow Reporting Result Codes 149 2.2. Data Escrow Agent Reporting 151 The new gTLD base Registry Agreement, Specification 2, Part B, 152 Section 7 requires Data Escrow Agents to deliver ICANN, a data escrow 153 notification when a escrow deposit is successfully received from the 154 Registry Operator regardless of the final status of the verification 155 process. 157 In order to comply with this provision, the Data Escrow Agent sends a 158 notification to ICANN for each escrow deposit received from the 159 Registry Operator, using the PUT HTTP verb in the interface provided 160 by ICANN at: 162 https://ry-api.icann.org/report/escrow-agent-notification 164 Data Escrow Agents MUST send a object 165 as defined in [I-D.arias-noguchi-dnrd-objects-mapping]. 167 After successfully receiving a , ICANN 168 validates it and provides a result code in the same HTTP transaction. 170 After sending the result code, the interface closes the TCP 171 connection. 173 At 23:59 UTC, the last successful validated object is stored and used by ICANN. 176 2.2.1. Interface result code 178 The following table lists the result codes of the interface: 180 +----------+--------------------------------------------------------+ 181 | Result | Description | 182 | Code | | 183 +----------+--------------------------------------------------------+ 184 | 1000 | No ERRORs were found and the notification has been | 185 | | accepted by ICANN. | 186 | 2001 | The notification did not validate against the schema. | 187 | 2002 | A notification for that day already exists, the | 188 | | cut-off date already passed. | 189 +----------+--------------------------------------------------------+ 191 Data Escrow Reporting Result Codes 193 3. Specification 3 - Registry Operator Monthly Reporting 195 Specification 3 of the new gTLD base Registry Agreement requires 196 Registry Operators to provide a set of monthly reports per gTLD. Two 197 type of reports are required to be sent by Registries: Per-Registrar 198 Transactions Report and Registry Functions Activity Report. This 199 section specifies the interface provided by ICANN to automate the 200 upload of these reports by Registry Operators. 202 The cut-off date for the reception of the previous month report is 203 the day 20 (23:59 UTC) of the current month, as described in the new 204 gTLD Applicant Guidebook [ICANN-GTLD-AGB-20120604]. Before the cut- 205 off date the Registry Operator could replace a successfully validated 206 report as many times as it needs. 208 3.1. Per-Registrar Transactions Report 210 The Per-Registrar Transactions Report is a CSV report described in 211 Section 1 of Specification 3. 213 In order to comply with this provision, the Registry Operator sends a 214 CSV report on a monthly basis as described in the Agreement, using 215 the PUT HTTP verb in the interface provided by ICANN at: 217 https://ry-api.icann.org/report/registrar-transactions// 218 220 Where: 222 * MUST be substituted by the TLD for which the reports is 223 being provided. In case of an IDN TLD, the A-label MUST be 224 used. 226 * MUST be substituted by the month for which the reports 227 is being provided in the form of YYYY-MM. Where 'YYYY' is the 228 year and 'MM' is the two digit month number. For example: 229 2013-03 231 After successfully receiving a report, ICANN validates it and 232 provides a result code in the same HTTP transaction. 234 After sending the result code, the interface closes the TCP 235 connection. 237 3.1.1. Interface result codes 239 The following table lists the result codes of the interface: 241 +-----------+-------------------------------------------------------+ 242 | Result | Description | 243 | Code | | 244 +-----------+-------------------------------------------------------+ 245 | 1000 | No ERRORs were found and the report has been accepted | 246 | | by ICANN. | 247 | 2001 | The structure of the report is invalid. | 248 | 2002 | A report for that month already exists, the cut-off | 249 | | date already passed. | 250 | 2003 | Negative numeric value present in the report. | 251 | 2101 | Incorrect totals present in the report. | 252 | 2102 | Non ICANN accredited registrar present in the report. | 253 | 2103 | Values found in the second field of the totals line. | 254 +-----------+-------------------------------------------------------+ 256 Per-Registrar Transactions Report Result Codes 258 3.2. Registry Functions Activity Report 260 The Registry Functions Activity Report is a CSV report described in 261 Specification 3, 2 of the new gTLD Applicant Guidebook 262 [ICANN-GTLD-AGB-20120604]. 264 In order to comply with this provision, the Registry Operator sends a 265 CSV report on a montly basis as described in the Agreement, using the 266 PUT HTTP verb in the interface provided by ICANN at: 268 https://ry-api.icann.org/report/registry-functions-activity// 269 271 Where: 273 * MUST be substituted by the TLD for which the report is 274 being provided. In case of an IDN TLD, the A-label MUST be 275 used. 277 * MUST be substituted by the month for which the reports 278 is being provided in the form of YYYY-MM. Where 'YYYY' is the 279 year and 'MM' is the two digit month number. For example: 280 2013-03 282 After sucessfuly receiving a report, ICANN validates it and provides 283 a result code in the same HTTP transaction. 285 After sending the result code, the interface closes the TCP 286 connection. 288 3.2.1. Interface result codes 290 The following table lists the result codes of the interface: 292 +-----------+-------------------------------------------------------+ 293 | Result | Description | 294 | Code | | 295 +-----------+-------------------------------------------------------+ 296 | 1000 | No ERRORs were found and the report has been accepted | 297 | | by ICANN. | 298 | 2001 | The structure of the report is invalid. | 299 | 2002 | A report for that month already exists, the cut-off | 300 | | date already passed. | 301 | 2003 | Negative numeric value present in the report. | 302 +-----------+-------------------------------------------------------+ 304 Registry Functions Activity Report Result Codes 306 4. IIRDEA Result Object 308 After processing the input provided in the interface, a response 309 object as defined by the schema in Section 5 is provided. 311 The interface provides a HTTP/200 status code when the interface was 312 able to receive the input and sent a response. 314 The interface provides a HTTP/500 status code when the system is 315 experiencing a general failure. 317 An example of a response object is presented below: 319 320 321 322 No error 323 324 The report has been accepted by ICANN. 325 Processing of the report will take place at 23:59 UTC. 326 327 328 330 5. Formal Syntax 332 The schema of the IIRDEA result code is presented here. 334 The BEGIN and END tags are not part of the schema; they are used to 335 note the beginning and ending of the schema for URI registration 336 purposes. 338 5.1. IIRDEA Result Schema 340 Copyright (c) 2012 IETF Trust and the persons identified as authors 341 of the code. All rights reserved. 343 Redistribution and use in source and binary forms, with or without 344 modification, are permitted provided that the following conditions 345 are met: 347 o Redistributions of source code must retain the above copyright 348 notice, this list of conditions and the following disclaimer. 350 o Redistributions in binary form must reproduce the above copyright 351 notice, this list of conditions and the following disclaimer in 352 the documentation and/or other materials provided with the 353 distribution. 355 o Neither the name of Internet Society, IETF or IETF Trust, nor the 356 names of specific contributors, may be used to endorse or promote 357 products derived from this software without specific prior written 358 permission. 360 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 361 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 362 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 363 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 364 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 365 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 366 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 367 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 368 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 369 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 370 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 372 BEGIN 373 374 379 380 381 ICANN interfaces for registries and data escrow agents 382 383 385 387 388 389 390 391 393 394 395 396 397 398 399 401 402 403 404 405 406 407 408 409 410 411 412 413 END 415 6. Acknowledgements 417 TBD. 419 7. Change History 421 Version 00. 423 8. IANA Considerations 425 TODO 427 9. Security Considerations 429 TODO 431 10. References 433 10.1. Normative References 435 [I-D.arias-noguchi-dnrd-objects-mapping] 436 Arias, F., Lozano, G., Noguchi, S., Gould, J., and C. 437 Thippeswamy, "Domain Name Registration Data (DNRD) Objects 438 Mapping", draft-arias-noguchi-dnrd-objects-mapping-02 439 (work in progress), March 2013. 441 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 442 Requirement Levels", BCP 14, RFC 2119, March 1997. 444 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 445 January 2004. 447 10.2. Informative References 449 [ICANN-GTLD-AGB-20120604] 450 ICANN, "gTLD Applicant Guidebook Version 2012-06-04", 451 June 2012, . 454 Author's Address 456 Gustavo Lozano 457 ICANN 458 12025 Waterfront Drive, Suite 300 459 Los Angeles 90292 460 US 462 Phone: +1.3103015800 463 Email: gustavo.lozano@icann.org