Internet Engineering Task Force G. Lozano Internet-Draft ICANN Intended status: Informational March 31, 2013 Expires: October 2, 2013 ICANN Registry Interfaces draft-lozano-icann-registry-interfaces-00 Abstract This document describes the interfaces between ICANN and Registries and Data Escrow Agents. These interfaces allow Registries and Data Escrow Agents upload the reports described in the Base Agreement of the new gTLD Applicant Guidebook. Status of this Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on October 2, 2013. Copyright Notice Copyright (c) 2013 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Lozano Expires October 2, 2013 [Page 1] Internet-Draft ICANN Registry Interfaces March 2013 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 2. Specification 2 - Data Escrow Reporting . . . . . . . . . . . 3 2.1. Registry Operator Reporting . . . . . . . . . . . . . . . 3 2.2. Data Escrow Agent Reporting . . . . . . . . . . . . . . . 4 3. Specification 3 - Registry Operator Monthly Reporting . . . . 5 3.1. Per-Registrar Transactions Report . . . . . . . . . . . . 5 3.2. Registry Functions Activity Report . . . . . . . . . . . . 7 4. IIRDEA Result Object . . . . . . . . . . . . . . . . . . . . . 8 5. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 8 5.1. IIRDEA Result Schema . . . . . . . . . . . . . . . . . . . 8 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 10 7. Change History . . . . . . . . . . . . . . . . . . . . . . . . 11 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 9. Security Considerations . . . . . . . . . . . . . . . . . . . 11 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 10.1. Normative References . . . . . . . . . . . . . . . . . . . 11 10.2. Informative References . . . . . . . . . . . . . . . . . . 11 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 11 Lozano Expires October 2, 2013 [Page 2] Internet-Draft ICANN Registry Interfaces March 2013 1. Introduction This document describes the interfaces between ICANN and Registries and Data Escrow Agents. These interfaces allow Registries and Data Escrow Agents upload the reports described in the Base Agreement of the new gTLD Applicant Guidebook. Authentication credentials for the interfaces described above are provided per TLD. 1.1. Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119]. XML is case sensitive. Unless stated otherwise, XML specifications and examples provided in this document MUST be interpreted in the character case presented in order to develop a conforming implementation. "iirdea-1.0" is used as an abbreviation for "urn:ietf:params:xml:ns:iirdea-1.0". The XML namespace prefix "iirdea" is used, but implementations MUST NOT depend on it and instead employ a proper namespace-aware XML parser and serializer to interpret and output the XML documents. 2. Specification 2 - Data Escrow Reporting This section describes the interfaces provided by ICANN for Registry Operators and Data Escrow Agents to comply with the reporting provisions detailed in Specification 2 of the Base Agreement of the new gTLD Applicant Guidebook [ICANN-GTLD-AGB-20120604]. 2.1. Registry Operator Reporting The new gTLD base Registry Agreement, Specification 2, Part A, Section 7 requires Registry Operators to provide ICANN with a written statement that includes a copy of the report generated upon creation of an escrow deposit and a statement that the deposit has been inspected by the Registry Operator and is complete and accurate. In order to comply with this provision, the Registry Operator sends a report to ICANN for each escrow deposit successfully received by the Data Escrow Agent, using the PUT HTTP verb in the interface provided by ICANN at: Lozano Expires October 2, 2013 [Page 3] Internet-Draft ICANN Registry Interfaces March 2013 https://ry-api.icann.org/report/registry-escrow-report Registries MUST send a object as defined in [I-D.arias-noguchi-dnrd-objects-mapping]. After successfully receiving a object, ICANN validates it and provides a result code in the same HTTP transaction. After sending the result code, the interface closes the TCP connection. At 23:59 UTC, the last successful validated object is stored and used by ICANN. 2.1.1. Result codes The following table lists the result codes of the interface: +-----------+-------------------------------------------------------+ | Result | Description | | Code | | +-----------+-------------------------------------------------------+ | 1000 | No ERRORs were found and the report has been accepted | | | by ICANN. | | 2001 | The report did not validate against the schema. | | 2002 | A report for that day already exists, the cut-off | | | date already passed. | +-----------+-------------------------------------------------------+ Data Escrow Reporting Result Codes 2.2. Data Escrow Agent Reporting The new gTLD base Registry Agreement, Specification 2, Part B, Section 7 requires Data Escrow Agents to deliver ICANN, a data escrow notification when a escrow deposit is successfully received from the Registry Operator regardless of the final status of the verification process. In order to comply with this provision, the Data Escrow Agent sends a notification to ICANN for each escrow deposit received from the Registry Operator, using the PUT HTTP verb in the interface provided by ICANN at: https://ry-api.icann.org/report/escrow-agent-notification Data Escrow Agents MUST send a object as defined in [I-D.arias-noguchi-dnrd-objects-mapping]. Lozano Expires October 2, 2013 [Page 4] Internet-Draft ICANN Registry Interfaces March 2013 After successfully receiving a , ICANN validates it and provides a result code in the same HTTP transaction. After sending the result code, the interface closes the TCP connection. At 23:59 UTC, the last successful validated object is stored and used by ICANN. 2.2.1. Interface result code The following table lists the result codes of the interface: +----------+--------------------------------------------------------+ | Result | Description | | Code | | +----------+--------------------------------------------------------+ | 1000 | No ERRORs were found and the notification has been | | | accepted by ICANN. | | 2001 | The notification did not validate against the schema. | | 2002 | A notification for that day already exists, the | | | cut-off date already passed. | +----------+--------------------------------------------------------+ Data Escrow Reporting Result Codes 3. Specification 3 - Registry Operator Monthly Reporting Specification 3 of the new gTLD base Registry Agreement requires Registry Operators to provide a set of monthly reports per gTLD. Two type of reports are required to be sent by Registries: Per-Registrar Transactions Report and Registry Functions Activity Report. This section specifies the interface provided by ICANN to automate the upload of these reports by Registry Operators. The cut-off date for the reception of the previous month report is the day 20 (23:59 UTC) of the current month, as described in the new gTLD Applicant Guidebook [ICANN-GTLD-AGB-20120604]. Before the cut- off date the Registry Operator could replace a successfully validated report as many times as it needs. 3.1. Per-Registrar Transactions Report The Per-Registrar Transactions Report is a CSV report described in Section 1 of Specification 3. In order to comply with this provision, the Registry Operator sends a Lozano Expires October 2, 2013 [Page 5] Internet-Draft ICANN Registry Interfaces March 2013 CSV report on a monthly basis as described in the Agreement, using the PUT HTTP verb in the interface provided by ICANN at: https://ry-api.icann.org/report/registrar-transactions// Where: * MUST be substituted by the TLD for which the reports is being provided. In case of an IDN TLD, the A-label MUST be used. * MUST be substituted by the month for which the reports is being provided in the form of YYYY-MM. Where 'YYYY' is the year and 'MM' is the two digit month number. For example: 2013-03 After successfully receiving a report, ICANN validates it and provides a result code in the same HTTP transaction. After sending the result code, the interface closes the TCP connection. 3.1.1. Interface result codes The following table lists the result codes of the interface: +-----------+-------------------------------------------------------+ | Result | Description | | Code | | +-----------+-------------------------------------------------------+ | 1000 | No ERRORs were found and the report has been accepted | | | by ICANN. | | 2001 | The structure of the report is invalid. | | 2002 | A report for that month already exists, the cut-off | | | date already passed. | | 2003 | Negative numeric value present in the report. | | 2101 | Incorrect totals present in the report. | | 2102 | Non ICANN accredited registrar present in the report. | | 2103 | Values found in the second field of the totals line. | +-----------+-------------------------------------------------------+ Per-Registrar Transactions Report Result Codes Lozano Expires October 2, 2013 [Page 6] Internet-Draft ICANN Registry Interfaces March 2013 3.2. Registry Functions Activity Report The Registry Functions Activity Report is a CSV report described in Specification 3, 2 of the new gTLD Applicant Guidebook [ICANN-GTLD-AGB-20120604]. In order to comply with this provision, the Registry Operator sends a CSV report on a montly basis as described in the Agreement, using the PUT HTTP verb in the interface provided by ICANN at: https://ry-api.icann.org/report/registry-functions-activity// Where: * MUST be substituted by the TLD for which the report is being provided. In case of an IDN TLD, the A-label MUST be used. * MUST be substituted by the month for which the reports is being provided in the form of YYYY-MM. Where 'YYYY' is the year and 'MM' is the two digit month number. For example: 2013-03 After sucessfuly receiving a report, ICANN validates it and provides a result code in the same HTTP transaction. After sending the result code, the interface closes the TCP connection. 3.2.1. Interface result codes The following table lists the result codes of the interface: +-----------+-------------------------------------------------------+ | Result | Description | | Code | | +-----------+-------------------------------------------------------+ | 1000 | No ERRORs were found and the report has been accepted | | | by ICANN. | | 2001 | The structure of the report is invalid. | | 2002 | A report for that month already exists, the cut-off | | | date already passed. | | 2003 | Negative numeric value present in the report. | +-----------+-------------------------------------------------------+ Registry Functions Activity Report Result Codes Lozano Expires October 2, 2013 [Page 7] Internet-Draft ICANN Registry Interfaces March 2013 4. IIRDEA Result Object After processing the input provided in the interface, a response object as defined by the schema in Section 5 is provided. The interface provides a HTTP/200 status code when the interface was able to receive the input and sent a response. The interface provides a HTTP/500 status code when the system is experiencing a general failure. An example of a response object is presented below: No error The report has been accepted by ICANN. Processing of the report will take place at 23:59 UTC. 5. Formal Syntax The schema of the IIRDEA result code is presented here. The BEGIN and END tags are not part of the schema; they are used to note the beginning and ending of the schema for URI registration purposes. 5.1. IIRDEA Result Schema Copyright (c) 2012 IETF Trust and the persons identified as authors of the code. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: o Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. o Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the Lozano Expires October 2, 2013 [Page 8] Internet-Draft ICANN Registry Interfaces March 2013 distribution. o Neither the name of Internet Society, IETF or IETF Trust, nor the names of specific contributors, may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. Lozano Expires October 2, 2013 [Page 9] Internet-Draft ICANN Registry Interfaces March 2013 BEGIN ICANN interfaces for registries and data escrow agents END 6. Acknowledgements TBD. Lozano Expires October 2, 2013 [Page 10] Internet-Draft ICANN Registry Interfaces March 2013 7. Change History Version 00. 8. IANA Considerations TODO 9. Security Considerations TODO 10. References 10.1. Normative References [I-D.arias-noguchi-dnrd-objects-mapping] Arias, F., Lozano, G., Noguchi, S., Gould, J., and C. Thippeswamy, "Domain Name Registration Data (DNRD) Objects Mapping", draft-arias-noguchi-dnrd-objects-mapping-02 (work in progress), March 2013. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, January 2004. 10.2. Informative References [ICANN-GTLD-AGB-20120604] ICANN, "gTLD Applicant Guidebook Version 2012-06-04", June 2012, . Lozano Expires October 2, 2013 [Page 11] Internet-Draft ICANN Registry Interfaces March 2013 Author's Address Gustavo Lozano ICANN 12025 Waterfront Drive, Suite 300 Los Angeles 90292 US Phone: +1.3103015800 Email: gustavo.lozano@icann.org Lozano Expires October 2, 2013 [Page 12]