[Docs] [txt|pdf] [Tracker] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01 02 03 04 05 06 07 08 09 10 11 12 13 14

Internet Engineering Task Force                                G. Lozano
Internet-Draft                                                     ICANN
Intended status: Informational                              Jan 15, 2015
Expires: July 19, 2015


                       ICANN Registry Interfaces
               draft-lozano-icann-registry-interfaces-07

Abstract

   This document describes the interfaces provided by ICANN to Registry
   Operators in order to fulfill the requirements of Specification 2 and
   3 of the New gTLD Base Agreement.  The interface provided by ICANN to
   Data Escrow Agents in order to fulfill the requirements of
   Specification 2 of the New gTLD Base Agreement is also described in
   this document.

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 July 19, 2015.

Copyright Notice

   Copyright (c) 2015 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



Lozano                    Expires July 19, 2015                 [Page 1]


Internet-Draft          ICANN Registry Interfaces               Jan 2015


   described in the Simplified BSD License.


Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
     1.1.  Terminology  . . . . . . . . . . . . . . . . . . . . . . .  3
   2.  Interfaces for Specification 2 - Data Escrow Reporting . . . .  3
     2.1.  Registry Operator Reporting  . . . . . . . . . . . . . . .  3
     2.2.  Data Escrow Agent Reporting  . . . . . . . . . . . . . . .  6
   3.  Interfaces of Specification 3 - Registry Operator Monthly
       Reporting  . . . . . . . . . . . . . . . . . . . . . . . . . .  9
     3.1.  Per-Registrar Transactions Report  . . . . . . . . . . . .  9
     3.2.  Registry Functions Activity Report . . . . . . . . . . . . 10
   4.  Interface details  . . . . . . . . . . . . . . . . . . . . . . 10
     4.1.  IIRDEA Result Object . . . . . . . . . . . . . . . . . . . 11
   5.  Monitoring compliance with the New gTLD Base Agreement . . . . 14
     5.1.  Monitoring compliance with Data Escrow Reports . . . . . . 14
     5.2.  Monitoring compliance with Data Escrow Notifications . . . 15
     5.3.  Monitoring compliance with Registry Functions Activity
           Report . . . . . . . . . . . . . . . . . . . . . . . . . . 15
     5.4.  Monitoring compliance with Per-Registrar Transactions
           Report . . . . . . . . . . . . . . . . . . . . . . . . . . 16
   6.  Formal Syntax  . . . . . . . . . . . . . . . . . . . . . . . . 16
     6.1.  IIRDEA Result Schema . . . . . . . . . . . . . . . . . . . 17
     6.2.  Report Object  . . . . . . . . . . . . . . . . . . . . . . 18
     6.3.  Notification Object  . . . . . . . . . . . . . . . . . . . 20
   7.  Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 22
   8.  Change History . . . . . . . . . . . . . . . . . . . . . . . . 22
     8.1.  Version 00 . . . . . . . . . . . . . . . . . . . . . . . . 22
     8.2.  Version 01 . . . . . . . . . . . . . . . . . . . . . . . . 22
     8.3.  Version 02 . . . . . . . . . . . . . . . . . . . . . . . . 23
     8.4.  Version 03 . . . . . . . . . . . . . . . . . . . . . . . . 23
     8.5.  Version 04 . . . . . . . . . . . . . . . . . . . . . . . . 23
   9.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 24
   10. Security Considerations  . . . . . . . . . . . . . . . . . . . 24
   11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 24
     11.1. Normative References . . . . . . . . . . . . . . . . . . . 24
     11.2. Informative References . . . . . . . . . . . . . . . . . . 24
   Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 24











Lozano                    Expires July 19, 2015                 [Page 2]


Internet-Draft          ICANN Registry Interfaces               Jan 2015


1.  Introduction

   This document describes the interfaces provided by ICANN to Registry
   Operators in order to fulfill the requirements of Specification 2 and
   3 of the New gTLD Base Agreement.  The interface provided by ICANN to
   Data Escrow Agents in order to fulfill the requirements of
   Specification 2 of the New gTLD Base Agreement is also described in
   this document.

   Authentication credentials for the interfaces are provided by ICANN
   to the Registry Operator per TLD.  The Registry Operator receives a
   set of credentials to be used by the Registry Operator and by the
   Data Escrow Agent for authentication to the after-mentioned
   interfaces.

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.


2.  Interfaces for Specification 2 - Data Escrow Reporting

   This section describes the interfaces provided by ICANN to Registry
   Operators and Data Escrow Agents in order to comply with the
   reporting provisions detailed in Specification 2 of the New gTLD Base
   Agreement of the new gTLD Applicant Guidebook
   [ICANN-GTLD-AGB-20120604].

2.1.  Registry Operator Reporting

   The New gTLD Base 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 a
   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
   <rdeReport:report> element to ICANN for each deposit successfully
   sent to the Data Escrow Agent, using the PUT HTTP verb in the
   interface provided by ICANN at:




Lozano                    Expires July 19, 2015                 [Page 3]


Internet-Draft          ICANN Registry Interfaces               Jan 2015


      https://ry-api.icann.org/report/registry-escrow-report/<TLD>/<id>

      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.

      *  <id> MUST be substituted by the identifier assigned to this
         report, which MUST be the same as the "id" attribute from the
         <deposit>.

      Note: The interface supports overwriting the information of a
      particular report "id" to support async interfaces between
      Registry Operators and Data Escrow Agents.

2.1.1.  <report> object

   The <report> element contains the following child elements:

   o  An <id> element contains the identifier assigned to this report.
      The report identifier MUST be the same as the "id" attribute from
      the <deposit>.

   o  A <version> element contains the version of the specification
      used.  This value MUST be 1.

   o  A <rydeSpecEscrow> element contains the version of the Registry
      Data Escrow Specification (e.g.
      draft-arias-noguchi-registry-data-escrow-06) used to create the
      deposit.  After the specification is published as an RFC, the
      value MUST be the RFC number assigned by IANA.

   o  A <rydeSpecMapping> element contains the version of the Domain
      Name Registration Data (DNRD) Objects Mapping (e.g.
      draft-arias-noguchi-dnrd-objects-mapping-05) used to create the
      deposit.  After the specification is published as an RFC, the
      value MUST be the RFC number assigned by IANA.

   o  A <resend> element contains the value of the "resend" attribute of
      the <deposit>.

   o  A <crDate> element contains the date and time that the deposit was
      created by the Registry Operator.

   o  A <kind> element is used to identify the kind of deposit: FULL,
      INCR (Incremental) or DIFF (Differential).




Lozano                    Expires July 19, 2015                 [Page 4]


Internet-Draft          ICANN Registry Interfaces               Jan 2015


   o  A <watermark> element contains the data and time corresponding to
      the Timeline Watermark (<watermark> element) of the <deposit>.

   o  A <header> element contains the header of the <deposit>.

   Example <report> object:


 <?xml version="1.0" encoding="UTF-8"?>
   <rdeReport:report
     xmlns:rdeReport="urn:ietf:params:xml:ns:rdeReport-1.0"
         xmlns:rdeHeader="urn:ietf:params:xml:ns:rdeHeader-1.0">
     <rdeReport:id>20101017001</rdeReport:id>
     <rdeReport:version>1</rdeReport:version>
     <rdeReport:rydeSpecEscrow>
       draft-arias-noguchi-registry-data-escrow-06
     </rdeReport:rydeSpecEscrow>
     <rdeReport:rydeSpecMapping>
       draft-arias-noguchi-dnrd-objects-mapping-05
     </rdeReport:rydeSpecMapping>
     <rdeReport:resend>0</rdeReport:resend>
     <rdeReport:crDate>2010-10-17T00:15:00.0Z</rdeReport:crDate>
     <rdeReport:kind>FULL</rdeReport:kind>
     <rdeReport:watermark>2010-10-17T00:00:00Z</rdeReport:watermark>
     <rdeHeader:header>
       <rdeHeader:tld>test</rdeHeader:tld>
       <rdeHeader:count
         uri="urn:ietf:params:xml:ns:rdeDomain-1.0">2</rdeHeader:count>
       <rdeHeader:count
         uri="urn:ietf:params:xml:ns:rdeHost-1.0">1</rdeHeader:count>
       <rdeHeader:count
         uri="urn:ietf:params:xml:ns:rdeContact-1.0">1</rdeHeader:count>
       <rdeHeader:count
         uri="urn:ietf:params:xml:ns:rdeRegistrar-1.0">1
             </rdeHeader:count>
       <rdeHeader:count
         uri="urn:ietf:params:xml:ns:rdeIDN-1.0">1</rdeHeader:count>
       <rdeHeader:count
         uri="urn:ietf:params:xml:ns:rdeNNDN-1.0">1</rdeHeader:count>
       <rdeHeader:count
         uri="urn:ietf:params:xml:ns:rdeEppParams-1.0">1
             </rdeHeader:count>
     </rdeHeader:header>
   </rdeReport:report>







Lozano                    Expires July 19, 2015                 [Page 5]


Internet-Draft          ICANN Registry Interfaces               Jan 2015


2.2.  Data Escrow Agent Reporting

   The New gTLD Base Agreement, Specification 2, Part B, Section 7
   requires Data Escrow Agents, to deliver to ICANN a notification every
   time a successfully processed deposit is received from the Registry
   Operator regardless of the final status of the verification process.

   There are three types of notices:

      Deposit Receipt Failure Notice (DRFN): generated by the Escrow
      Agent when no deposit is received pursuant to the schedule
      specified in Specification 2.

      Deposit Verification Failure Notice (DVFN): generated by the
      Escrow Agent when a deposit is received, but the final result of
      the verification process is failure.

      Deposit Verification Pass Notice (DVPN): generated by the Escrow
      Agent when a deposit is received and the final result of the
      verification process is success.

   In order to comply with this provision, the Data Escrow Agent sends a
   <rdeNotification:notification> element to ICANN, using the POST HTTP
   verb in the interface provided by ICANN at:

      https://ry-api.icann.org/report/escrow-agent-notification/<TLD>

      Where:

      *  <TLD> MUST be substituted by the TLD for which the notification
         is being provided.  In case of an IDN TLD, the A-label MUST be
         used.

   If by 23:59 UTC, a deposit has not been successfully processed
   regardless of the final status of the verification process, a
   <rdeNotification:notification> with DRFN status MUST be send to
   ICANN.

2.2.1.  <notification> object

   The <notification> element contains the following child elements:

   o  A <deaName> element contains the name of the Data Escrow Agent.

   o  A <version> element contains the version of the specification
      used.  This value MUST be 1.





Lozano                    Expires July 19, 2015                 [Page 6]


Internet-Draft          ICANN Registry Interfaces               Jan 2015


   o  A <repDate> element contains the reported date.  In case of a DVPN
      or DVFN notification this value MUST be the date of the
      <watermark> element of the <deposit>.  In case of a DRFN deposit
      notification, this value MUST be the date for which no deposit was
      received from the Registry Operator.

   o  A <status> element is used to specify the status of <repDate>.
      The possible values of status are: DVPN, DVFN and DRFN.

      *  DVPN

      *  DVFN

      *  DRFN

   o  An OPTIONAL <reDate> element contains the date and time that the
      deposit was successful received by the Data Escrow Agent.  In case
      of a DRFN deposit notification this element MUST NOT be present.

   o  An OPTIONAL <vaDate> element contains the date and time that the
      deposit was successfully validated by the Data Escrow Agent.  In
      case of a DRFN deposit notification this element MUST NOT be
      present.

   o  An OPTIONAL <lastFullDate> element contains the date of the
      Timeline Watermark (<watermark> element) of the most recent FULL
      deposit that was successfully validated by the Data Escrow Agent.
      This element MUST NOT be present if a successfully validated full
      deposit has never been deposited.

   o  An OPTIONAL <report> element is used by the Data Escrow Agent to
      provide extended information about the deposit.  In case of a DRFN
      deposit notification this element MUST NOT be present.  In case of
      a DVPN or DVFN deposit notification this element MUST be present.
      When this element is present, the <rdeHeader:header> element MUST
      be generated by the Data Escrow Agent for the Timeline Watermark
      (<watermark> element) of the deposit being processed.  If the
      deposit being processed is a differential or incremental deposit,
      the Data Escrow Agent MUST process the last full plus all
      differentials or last full plus last incremental escrow deposits
      to generate the <rdeHeader:header> element.

   o  Note: In case of a DPVN or DVFN deposit notification, the
      <rdeReport:id> is used as unique identifier.

   Example <notification> object:





Lozano                    Expires July 19, 2015                 [Page 7]


Internet-Draft          ICANN Registry Interfaces               Jan 2015


 <?xml version="1.0" encoding="UTF-8"?>
 <rdeNotification:notification
   xmlns:rdeNotification="urn:ietf:params:xml:ns:rdeNotification-1.0"
   xmlns:rdeReport="urn:ietf:params:xml:ns:rdeReport-1.0"
   xmlns:rdeHeader="urn:ietf:params:xml:ns:rdeHeader-1.0">
   <rdeNotification:deaName>Escrow Agent Inc.</rdeNotification:deaName>
   <rdeNotification:version>1</rdeNotification:version>
   <rdeNotification:repDate>2010-10-17</rdeNotification:repDate>
   <rdeNotification:status>DVPN</rdeNotification:status>
   <rdeNotification:reDate>
      2010-10-17T03:15:00.0Z
   </rdeNotification:reDate>
   <rdeNotification:vaDate>
      2010-10-17T05:15:00.0Z
   </rdeNotification:vaDate>
   <rdeNotification:lastFullDate>
      2010-10-14
   </rdeNotification:lastFullDate>
   <rdeReport:report>
     <rdeReport:id>20101017001</rdeReport:id>
     <rdeReport:version>1</rdeReport:version>
     <rdeReport:rydeSpecEscrow>
       draft-arias-noguchi-registry-data-escrow-06
     </rdeReport:rydeSpecEscrow>
     <rdeReport:rydeSpecMapping>
       draft-arias-noguchi-dnrd-objects-mapping-05
     </rdeReport:rydeSpecMapping>
     <rdeReport:resend>0</rdeReport:resend>
     <rdeReport:crDate>2010-10-17T00:15:00.0Z</rdeReport:crDate>
     <rdeReport:kind>FULL</rdeReport:kind>
     <rdeReport:watermark>2010-10-17T00:00:00Z</rdeReport:watermark>
     <rdeHeader:header>
       <rdeHeader:tld>test</rdeHeader:tld>
       <rdeHeader:count
         uri="urn:ietf:params:xml:ns:rdeDomain-1.0">2</rdeHeader:count>
       <rdeHeader:count
         uri="urn:ietf:params:xml:ns:rdeHost-1.0">1</rdeHeader:count>
       <rdeHeader:count
         uri="urn:ietf:params:xml:ns:rdeContact-1.0">1</rdeHeader:count>
       <rdeHeader:count
         uri="urn:ietf:params:xml:ns:rdeRegistrar-1.0">1
             </rdeHeader:count>
       <rdeHeader:count
         uri="urn:ietf:params:xml:ns:rdeIDN-1.0">1</rdeHeader:count>
       <rdeHeader:count
         uri="urn:ietf:params:xml:ns:rdeNNDN-1.0">1</rdeHeader:count>
       <rdeHeader:count
         uri="urn:ietf:params:xml:ns:rdeEppParams-1.0">1



Lozano                    Expires July 19, 2015                 [Page 8]


Internet-Draft          ICANN Registry Interfaces               Jan 2015


             </rdeHeader:count>
     </rdeHeader:header>
   </rdeReport:report>
 </rdeNotification:notification>



3.  Interfaces of Specification 3 - Registry Operator Monthly Reporting

   Specification 3 of the New gTLD Base 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 interfaces provided by ICANN to automate the
   upload of these reports by Registry Operators.

   The cut-off date for the reception of the reports specified in
   specification 3 is defined in the New gTLD Base Agreement of 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
   CSV report on a monthly basis as described in the New gTLD Base
   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






Lozano                    Expires July 19, 2015                 [Page 9]


Internet-Draft          ICANN Registry Interfaces               Jan 2015


3.2.  Registry Functions Activity Report

   The Registry Functions Activity Report is a CSV report described in
   Section 2 of Specification 3 of the New gTLD Base Agreement 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 monthly basis as described in the New gTLD Base
   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


4.  Interface details

   The client MUST set "text/xml" in the HTTP header Content-type when
   using the Data Escrow Agent Reporting and Registry Operator Reporting
   interfaces.  The client MUST set "text/csv" in the HTTP header
   Content-type when using the Per-Registrar Transactions Report
   Registry Functions Activity Report interfaces.

   The Data Escrow Agent Reporting and Registry Operator Reporting
   interfaces support HTTP streams only (HTTP multi-part forms are not
   supported).

   After successfully receiving an input in any of the interfaces
   described above, ICANN validates it and provides a result code in the
   same HTTP transaction.  The interface set the HTTP header Content-
   type: text/xml, when sending the IIRDEA result.

   o  The interface provides a HTTP/200 status code if the interface was
      able to receive the input and no problem was found in the input.

   o  The interface provides a HTTP/400 if the input is incorrect or the
      syntax of the input is invalid.



Lozano                    Expires July 19, 2015                [Page 10]


Internet-Draft          ICANN Registry Interfaces               Jan 2015


   o  The interface provides a HTTP/401 status code if the credentials
      provided does not authorize the Registry Operator to upload a
      report for that <TLD>.

   o  The interface provides a HTTP/403 status code if the credentials
      provided are valid but are being used to access a resource that
      permission is not granted for or the connecting IP address is not
      whitelisted for the <TLD>.

   o  The interface provides a HTTP/500 status code if the system is
      experiencing a general failure.  The sending party is responsible
      to send the input again.

   After sending the result code, the interface closes the TCP
   connection.

4.1.  IIRDEA Result Object

   After processing the input provided in any of the interfaces
   described in this document, a response object as defined by the
   schema in Section 6 is provided in the HTTP Entity-body when an HTTP/
   200 and HTTP/400 status code is sent by the interface.

   An example of a response object is presented below:

   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <response xmlns="urn:ietf:params:xml:ns:iirdea-1.0">
       <result code="2001">
           <msg>The structure of the report is invalid.</msg>
           <description>
              'XX' could not be parsed as a number (line: 2 column:3)
           </description>
       </result>
   </response>

   The following sections provide the IIRDEA Result Codes per interface:

4.1.1.  Registry Operator Reporting

   The following table lists the result codes of the interface:











Lozano                    Expires July 19, 2015                [Page 11]


Internet-Draft          ICANN Registry Interfaces               Jan 2015


   +---------+---------------------------------------------------------+
   | Result  | Message                                                 |
   | Code    |                                                         |
   +---------+---------------------------------------------------------+
   | 1000    | No ERRORs were found and the report has been accepted   |
   |         | by ICANN.                                               |
   | 2001    | The report did not validate against the schema.         |
   | 2004    | Report for a date in the future.  The <crDate> and      |
   |         | <watermark> date should not be in the future.           |
   | 2005    | Version is not supported.                               |
   | 2006    | The <id> in the <report> element and the <id> in the    |
   |         | URL path do not match.                                  |
   | 2007    | Interface is disabled for this TLD.                     |
   | 2008    | The <crDate> and <watermark> date should not be before  |
   |         | the creation date of the TLD in the system.             |
   | 2202    | The <TLD> in the <header> and the <TLD> in the URL path |
   |         | do not match.                                           |
   | 2205    | Report regarding a differential deposit received for a  |
   |         | Sunday (<watermark>).                                   |
   | 2206    | csvDomain and rdeDomain count provided in the <header>. |
   +---------+---------------------------------------------------------+

                    Data Escrow Reporting Result Codes

4.1.2.  Data Escrow Agent Reporting

   The following table lists the result codes of the interface:

   +--------+----------------------------------------------------------+
   | Result | Message                                                  |
   | 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 DVPN notification exists for that date (<repDate>).    |
   | 2004   | Notification for a date in the future.  The <crDate> and |
   |        | <watermark> and <repDate> date should not be in the      |
   |        | future.                                                  |
   | 2005   | Version is not supported.                                |
   | 2007   | Interface is disabled for this TLD.                      |
   | 2008   | The <crDate> and <watermark> and <repDate> date should   |
   |        | not be before the creation date of the TLD in the        |
   |        | system.                                                  |
   | 2201   | The <repDate> and <watermark> in the notification do not |
   |        | match.                                                   |
   | 2202   | The <TLD> in the <header> and the <TLD> in the URL path  |
   |        | do not match.                                            |



Lozano                    Expires July 19, 2015                [Page 12]


Internet-Draft          ICANN Registry Interfaces               Jan 2015


   | 2203   | A Deposit Verification Pass Notice (DVPN) notification   |
   |        | was received, but the Domain Name count is missing in    |
   |        | the <header>.                                            |
   | 2204   | The notification for the report "id" already exists.     |
   | 2205   | Notification regarding a differential deposit received   |
   |        | for a Sunday (<repDate>).                                |
   | 2206   | csvDomain and rdeDomain count provided in the <header>.  |
   | 2207   | A DVPN or DVFN was received, but the <report> element is |
   |        | missing in the notification.                             |
   | 2208   | A DRFN was received, but a <report> element exists in    |
   |        | the notification.                                        |
   +--------+----------------------------------------------------------+

                    Data Escrow Reporting Result Codes

4.1.3.  Per-Registrar Transactions Report

   The following table lists the result codes of the interface:

   +-----------+-------------------------------------------------------+
   | Result    | Message                                               |
   | 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.         |
   | 2004      | Report for a month in the future.                     |
   | 2007      | Interface is disabled for this TLD.                   |
   | 2008      | Reported month before the creation date of the TLD in |
   |           | the system.                                           |
   | 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

4.1.4.  Registry Functions Activity Report

   The following table lists the result codes of the interface:








Lozano                    Expires July 19, 2015                [Page 13]


Internet-Draft          ICANN Registry Interfaces               Jan 2015


   +-----------+-------------------------------------------------------+
   | Result    | Message                                               |
   | 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.         |
   | 2004      | Report for a month in the future.                     |
   | 2007      | Interface is disabled for this TLD.                   |
   | 2008      | Reported month before the creation date of the TLD in |
   |           | the system.                                           |
   +-----------+-------------------------------------------------------+

              Registry Functions Activity Report Result Codes


5.  Monitoring compliance with the New gTLD Base Agreement

   Registries MAY monitor compliance with Specification 2 and 3 of the
   New gTLD Base Agreement using the following interfaces that supports
   the HEAD HTTP verb:

5.1.  Monitoring compliance with Data Escrow Reports

   Registries MAY monitor compliance with Specification 2 (Data Escrow
   Reports) using the following interface:

      https://ry-api.icann.org/info/report/registry-escrow-report/<TLD>/
      <date>

      Where:

      *  <TLD> MUST be substituted by the TLD being queried.  In case of
         an IDN TLD, the A-label MUST be used.

      *  <date> MUST be substituted by the day being queried.  For
         example: 2013-03-02

      Possible results are:

      *  The interface provides a HTTP/200 status code, if a
         syntactically valid data escrow report was received for the
         queried date.





Lozano                    Expires July 19, 2015                [Page 14]


Internet-Draft          ICANN Registry Interfaces               Jan 2015


      *  The interface provides a HTTP/404 status code, if a
         syntactically valid data escrow report has not been received
         for the queried date.

5.2.  Monitoring compliance with Data Escrow Notifications

   Registries and Data Escrow Agents MAY monitor compliance with
   Specification 2 (Data Escrow Notifications) using the following
   interface:

      https://ry-api.icann.org/info/report/escrow-agent-notification/
      <TLD>/<date>

      Where:

      *  <TLD> MUST be substituted by the TLD being queried.  In case of
         an IDN TLD, the A-label MUST be used.

      *  <date> MUST be substituted by the day being queried.  For
         example: 2013-03-02

      Possible results are:

      *  The interface provides a HTTP/200 status code, if a
         syntactically valid data escrow notification was received for
         the queried date.

      *  The interface provides a HTTP/404 status code, if a
         syntactically valid data escrow notification has not been
         received for the queried date.

5.3.  Monitoring compliance with Registry Functions Activity Report

   Registries MAY monitor compliance with Specification 3 (Registry
   Functions Activity Report) using the following interface:

      https://ry-api.icann.org/info/report/registry-functions-activity/
      <TLD>/<date>

      Where:

      *  <TLD> MUST be substituted by the TLD being queried.  In case of
         an IDN TLD, the A-label MUST be used.

      *  <date> MUST be substituted by the month being queried.  For
         example: 2013-03





Lozano                    Expires July 19, 2015                [Page 15]


Internet-Draft          ICANN Registry Interfaces               Jan 2015


      Possible results are:

      *  The interface provides a HTTP/200 status code, if a
         syntactically valid registry functions activity report was
         received for the queried month.

      *  The interface provides a HTTP/404 status code, if a
         syntactically valid registry functions activity report has not
         been received for the queried month.

5.4.  Monitoring compliance with Per-Registrar Transactions Report

   Registries MAY monitor compliance with Specification 3 (Per-Registrar
   Transactions Report) using the following interface:

      https://ry-api.icann.org/info/report/registrar-transactions/<TLD>/
      <date>

      Where:

      *  <TLD> MUST be substituted by the TLD being queried.  In case of
         an IDN TLD, the A-label MUST be used.

      *  <date> MUST be substituted by the month being queried.  For
         example: 2013-03

      Possible results are:

      *  The interface provides a HTTP/200 status code, if a
         syntactically valid per-registrar transactions report was
         received for the queried month.

      *  The interface provides a HTTP/404 status code, if a
         syntactically valid per-registrar transactions report has not
         been received for the queried month.


6.  Formal Syntax

   The schema of the IIRDEA, Reports and Notifications are 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.






Lozano                    Expires July 19, 2015                [Page 16]


Internet-Draft          ICANN Registry Interfaces               Jan 2015


6.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
      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 July 19, 2015                [Page 17]


Internet-Draft          ICANN Registry Interfaces               Jan 2015


   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="unsignedShort">
         <minInclusive value="1000"/>
         <maxInclusive value="9999"/>
       </restriction>
     </simpleType>
   </schema>
   END

6.2.  Report Object

   Copyright (c) 2011 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:





Lozano                    Expires July 19, 2015                [Page 18]


Internet-Draft          ICANN Registry Interfaces               Jan 2015


   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
      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 July 19, 2015                [Page 19]


Internet-Draft          ICANN Registry Interfaces               Jan 2015


   BEGIN
   <?xml version="1.0" encoding="UTF-8"?>
   <schema targetNamespace="urn:ietf:params:xml:ns:rdeReport-1.0"
     xmlns:rdeReport="urn:ietf:params:xml:ns:rdeReport-1.0"
     xmlns:rdeHeader="urn:ietf:params:xml:ns:rdeHeader-1.0"
     xmlns:rde="urn:ietf:params:xml:ns:rde-1.0"
     xmlns="http://www.w3.org/2001/XMLSchema"
     elementFormDefault="qualified">

     <import namespace="urn:ietf:params:xml:ns:rde-1.0"
       schemaLocation="rde-1.0.xsd"/>
     <import namespace="urn:ietf:params:xml:ns:rdeHeader-1.0"
       schemaLocation="rde-header-1.0.xsd" />

     <annotation>
       <documentation>
         Registry Data Escrow Report schema
       </documentation>
     </annotation>

     <!-- Root Element -->
     <element name="report" type="rdeReport:reportType"/>

     <!-- Report Type -->
     <complexType name="reportType">
       <sequence>
         <element name="id" type="rde:depositIdType"/>
         <element name="version" type="unsignedShort"/>
         <element name="rydeSpecEscrow" type="token"/>
         <element name="rydeSpecMapping" type="token"/>
         <element name="resend" type="unsignedShort"/>
         <element name="crDate" type="dateTime"/>
         <element name="kind" type="rde:depositTypeType"/>
         <element name="watermark" type="dateTime"/>
         <element ref="rdeHeader:header"/>
       </sequence>
     </complexType>
   </schema>
   END

6.3.  Notification Object

   Copyright (c) 2011 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:



Lozano                    Expires July 19, 2015                [Page 20]


Internet-Draft          ICANN Registry Interfaces               Jan 2015


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

BEGIN
<?xml version="1.0" encoding="UTF-8"?>
<schema targetNamespace="urn:ietf:params:xml:ns:rdeNotification-1.0"
  xmlns:rdeNotification="urn:ietf:params:xml:ns:rdeNotification-1.0"
  xmlns:rdeReport="urn:ietf:params:xml:ns:rdeReport-1.0"
  xmlns="http://www.w3.org/2001/XMLSchema"
  elementFormDefault="qualified">

  <import namespace="urn:ietf:params:xml:ns:rdeReport-1.0"
    schemaLocation="rde-report-1.0.xsd"/>

  <annotation>
    <documentation>
      Registry Data Escrow Notification schema
    </documentation>
  </annotation>

  <!-- Root Element -->
  <element name="notification" type="rdeNotification:notificationType"/>

  <!-- Notification -->
  <complexType name="notificationType">
    <sequence>



Lozano                    Expires July 19, 2015                [Page 21]


Internet-Draft          ICANN Registry Interfaces               Jan 2015


      <element name="deaName" type="rdeNotification:nameType"/>
      <element name="version" type="unsignedShort"/>
      <element name="repDate" type="date"/>
      <element name="status" type="rdeNotification:statusType"/>
      <element name="reDate" type="dateTime" minOccurs="0"/>
      <element name="vaDate" type="dateTime" minOccurs="0"/>
      <element name="lastFullDate" type="date" minOccurs="0"/>
      <element ref="rdeReport:report" minOccurs="0"/>
    </sequence>
  </complexType>

  <simpleType name="nameType">
    <restriction base="normalizedString">
      <minLength value="1" />
      <maxLength value="255" />
    </restriction>
  </simpleType>

  <simpleType name="statusType">
    <restriction base="token">
      <enumeration value="DVPN"/>
      <enumeration value="DVFN"/>
      <enumeration value="DRFN"/>
    </restriction>
  </simpleType>
</schema>
END


7.  Acknowledgements

   Special suggestions that have been incorporated into this document
   were provided by David Kipling, James Gould, Gregory Zaltsman, Brett
   Carr and Harel Efraim.


8.  Change History

8.1.  Version 00

   Initial version.

8.2.  Version 01

   o  <rdeReport:report> and <rdeNotification:notification> moved from
      escrow drafts to this draft





Lozano                    Expires July 19, 2015                [Page 22]


Internet-Draft          ICANN Registry Interfaces               Jan 2015


   o  Added <crDate> to <rdeReport:report>

   o  <reDate> element of <rdeReport:report> is now OPTIONAL

   o  Added <deaName> element to <rdeNotification:notification>

   o  <rydeSpecEscrow> and <rydeSpecMapping> added to the draft

   o  Several report elements are OPTIONAL to support async interfaces
      between Registry Operators and Data Escrow Agents

   o  Added <TLD> and <id> to registry-escrow-report interface in order
      to make the interface idempotent and support async RyO-DEA
      interfaces

   o  Added <TLD> to escrow-agent-notification interface

   o  The escrow-agent-notification uses POST and not PUT, this has been
      fixed

   o  Several clarifications

8.3.  Version 02

   o  Added and updated several result codes.

   o  Added <version> element.

   o  Added Content-type definition.

8.4.  Version 03

   o  Added several result codes.

   o  unsignedShort is now used for result code in iirdea schema.

   o  Enumeration was removed from the iirdea schema.

8.5.  Version 04

   o  Added result codes: 2207 and 2208.

   o  Removed result codes: 2203.

   o  Added clarification regarding the support of HTTP streams.






Lozano                    Expires July 19, 2015                [Page 23]


Internet-Draft          ICANN Registry Interfaces               Jan 2015


9.  IANA Considerations

   TODO


10.  Security Considerations

   TODO


11.  References

11.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-05
              (work in progress), September 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.

11.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>.


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 July 19, 2015                [Page 24]


Html markup produced by rfcmarkup 1.129d, available from https://tools.ietf.org/tools/rfcmarkup/