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 <rdeReport:report> object as defined in
   [I-D.arias-noguchi-dnrd-objects-mapping].

   After successfully receiving a <rdeReport:report> 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 <rdeReport:report> 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 <rdeNotification:notification> 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 <rdeNotification:notification>, 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 <rdeNotification:
   notification> 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/<TLD>/
      <date>

      Where:

      *  <TLD> 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.

      *  <date> 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/<TLD>/
      <date>

      Where:

      *  <TLD> 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.

      *  <date> 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:

   <?xml version="1.0" encoding="UTF-8"?>
   <response xmlns="urn:ietf:params:xml:ns:iirdea-1.0">
     <result code="1000">
       <msg>No error</msg>
       <description>
          The report has been accepted by ICANN.
          Processing of the report will take place at 23:59 UTC.
       </description>
     </result>
   </response>


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
   <?xml version="1.0" encoding="UTF-8"?>
   <schema targetNamespace="urn:ietf:params:xml:ns:iirdea-1.0"
     xmlns:iirdea="urn:ietf:params:xml:ns:iirdea-1.0"
     xmlns="http://www.w3.org/2001/XMLSchema"
     elementFormDefault="qualified">

     <annotation>
       <documentation>
         ICANN interfaces for registries and data escrow agents
       </documentation>
     </annotation>

     <element name="response" type="iirdea:responseType"/>

     <complexType name="responseType">
       <sequence>
         <element name="result" type="iirdea:resultType"/>
       </sequence>
     </complexType>

     <complexType name="resultType">
       <sequence>
         <element name="msg" type="token"/>
         <element name="description" type="string" minOccurs="0"/>
       </sequence>
       <attribute name="code" type="iirdea:codeType" use="required"/>
     </complexType>

     <simpleType name="codeType">
       <restriction base="integer">
         <enumeration value="1000"/>
         <enumeration value="2001"/>
         <enumeration value="2002"/>
         <enumeration value="2003"/>
         <enumeration value="2101"/>
         <enumeration value="2102"/>
         <enumeration value="2103"/>
       </restriction>
     </simpleType>
   </schema>
   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, <http://newgtlds.icann.org/en/applicants/agb/
              guidebook-full-04jun12-en.pdf>.














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]