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]