idnits 2.17.1 draft-lozano-icann-registry-interfaces-10.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 22, 2019) is 1855 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: '1-9' is mentioned on line 1246, but not defined -- Looks like a reference, but probably isn't: '012' on line 1246 -- Looks like a reference, but probably isn't: '12' on line 1246 == Missing Reference: '0-9' is mentioned on line 1246, but not defined -- Looks like a reference, but probably isn't: '01' on line 1246 == Unused Reference: 'RFC3688' is defined on line 1488, but no explicit reference was found in the text == Unused Reference: 'RFC5891' is defined on line 1499, but no explicit reference was found in the text Summary: 0 errors (**), 0 flaws (~~), 5 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force G. Lozano 3 Internet-Draft E. Alvarez 4 Intended status: Informational ICANN 5 Expires: September 23, 2019 March 22, 2019 7 ICANN Registry Interfaces 8 draft-lozano-icann-registry-interfaces-10 10 Abstract 12 This document describes the technical details of the interfaces 13 provided by the Internet Corporation for Assigned Names and Numbers 14 (ICANN) to its contracted parties in order to fulfill reporting 15 requirements. The interfaces provided by ICANN to Data Escrow Agents 16 and Registry Operators to fulfill the requirements of Specifications 17 2 and 3 of the gTLD Base Registry Agreement are also described in 18 this document. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at https://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on September 23, 2019. 37 Copyright Notice 39 Copyright (c) 2019 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (https://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 55 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 56 1.2. Date and Time . . . . . . . . . . . . . . . . . . . . . . 3 57 1.3. Object Description . . . . . . . . . . . . . . . . . . . 3 58 2. Interfaces for Specification 2 - Data Escrow Reporting . . . 9 59 2.1. Registry Operator Reporting . . . . . . . . . . . . . . . 9 60 2.2. Data Escrow Agent Reporting . . . . . . . . . . . . . . . 11 61 3. Interfaces of Specification 3 - Registry Operator Monthly 62 Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . 12 63 3.1. Per-Registrar Transactions Report . . . . . . . . . . . . 13 64 3.2. Registry Functions Activity Report . . . . . . . . . . . 13 65 4. Technical details of the interfaces . . . . . . . . . . . . . 14 66 4.1. Response Object . . . . . . . . . . . . . . . . . . . . . 15 67 5. Monitoring the reporting status . . . . . . . . . . . . . . . 21 68 5.1. Monitoring the status of Data Escrow Reports . . . . . . 21 69 5.2. Monitoring the status of Data Escrow Notifications . . . 21 70 5.3. Monitoring the status of Registry Functions Activity 71 Report . . . . . . . . . . . . . . . . . . . . . . . . . 22 72 5.4. Monitoring the status of the Per-Registrar Transactions 73 Report . . . . . . . . . . . . . . . . . . . . . . . . . 22 74 6. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 24 75 6.1. IIRDEA Result Schema . . . . . . . . . . . . . . . . . . 24 76 6.2. Report Object . . . . . . . . . . . . . . . . . . . . . . 25 77 6.3. Notification Object . . . . . . . . . . . . . . . . . . . 26 78 6.4. RRI Reporting Summary Object . . . . . . . . . . . . . . 28 79 6.5. Notifications Object . . . . . . . . . . . . . . . . . . 30 80 6.6. Reports Object . . . . . . . . . . . . . . . . . . . . . 31 81 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 32 82 8. Change History . . . . . . . . . . . . . . . . . . . . . . . 32 83 8.1. Version 00 . . . . . . . . . . . . . . . . . . . . . . . 32 84 8.2. Version 01 . . . . . . . . . . . . . . . . . . . . . . . 32 85 8.3. Version 02 . . . . . . . . . . . . . . . . . . . . . . . 33 86 8.4. Version 03 . . . . . . . . . . . . . . . . . . . . . . . 33 87 8.5. Version 04 . . . . . . . . . . . . . . . . . . . . . . . 33 88 8.6. Version 05 . . . . . . . . . . . . . . . . . . . . . . . 34 89 8.7. Version 06 . . . . . . . . . . . . . . . . . . . . . . . 34 90 8.8. Version 07 . . . . . . . . . . . . . . . . . . . . . . . 34 91 8.9. Version 08 . . . . . . . . . . . . . . . . . . . . . . . 34 92 8.10. Version 09 . . . . . . . . . . . . . . . . . . . . . . . 34 93 8.11. Version 10 . . . . . . . . . . . . . . . . . . . . . . . 35 94 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 35 95 10. Security Considerations . . . . . . . . . . . . . . . . . . . 35 96 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 35 97 11.1. Normative References . . . . . . . . . . . . . . . . . . 35 98 11.2. Informative References . . . . . . . . . . . . . . . . . 35 99 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 36 101 1. Introduction 103 This document describes the technical details of the interfaces 104 provided by the Internet Corporation for Assigned Names and Numbers 105 (ICANN) to other contracted parties in order to fulfill reporting 106 requirements. The interface provided by ICANN to Registry Operators 107 and Data Escrow Agents in order to fulfill the requirements of 108 Specifications 2 and 3 of the gTLD Base Registry Agreement 109 [ICANN-GTLD-BASE-RA] are also described in this document. 111 1.1. Terminology 113 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 114 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 115 document are to be interpreted as described in RFC 2119 [RFC2119]. 117 XML is case sensitive. Unless stated otherwise, XML specifications 118 and examples provided in this document MUST be interpreted in the 119 character case presented in order to develop a conforming 120 implementation. 122 1.2. Date and Time 124 Numerous fields indicate "date and time", such as the creation and 125 receipt dates for data escrow deposits. These fields SHALL contain 126 timestamps indicating the date and time in UTC as specified in 127 [RFC3339], with no offset from the zero meridian. 129 1.3. Object Description 131 This section describes the base objects supported by this 132 specification. 134 1.3.1. object 136 The ICANN interfaces for registries and data escrow agents (IIRDEA) 137 object is used to provide information on the result 138 of a verification process when interacting with the interfaces. 140 The object contains the following attribute and child 141 elements: 143 o A "code" attribute whose value is a four-digit decimal number that 144 identifies the result of a process. Available result code values 145 MUST be defined for the corresponding process. 147 o An OPTIONAL "domainCount" attribute to indicate the number of 148 domain names related to the reported result. 150 o A element containing a human-readable description of the 151 result code. 153 o An OPTIONAL element that includes additional details 154 on the result conditions. 156 An example of a object is presented below: 158 159 The structure of the report is invalid. 160 161 'XX' could not be parsed as a number (line: 2 column:3) 162 163 165 1.3.2. object 167 The contents of a data escrow deposit are described using a 168 object. The object contains 169 the following child elements: 171 o An element that contains the identifier assigned to this 172 report. The report identifier MUST be the same as the "id" 173 attribute from the . If the data escrow deposit does not 174 include a unique identifer, the Data Escrow Agent MUST generate a 175 unique identifier to reference the data escrow deposit and use it 176 in the element. 178 o A element contains the version of the specification 179 used. This value MUST be 1. 181 o A element contains the version of the Data Escrow 182 Specification (e.g. draft-arias-noguchi-registry-data-escrow-06) 183 used to create the deposit. After the specification is published 184 as an RFC, the value MUST be the RFC number assigned by IANA. 186 o An OPTIONAL element contains the version of the 187 Domain Name Registration Data (DNRD) Objects Mapping (e.g. draft- 188 arias-noguchi-dnrd-objects-mapping-05) used to create the deposit. 189 After the specification is published as an RFC, the value MUST be 190 the RFC number assigned by IANA. The element 191 MUST be included if the deposit was created using any version of 192 the DNRD objects mapping specification (see, 193 [I-D.arias-noguchi-dnrd-objects-mapping]). 195 o A element contains the value of the "resend" attribute of 196 the . 198 o A element contains the date and time that the deposit was 199 created by the Registry Operator. 201 o A element is used to identify the kind of deposit: FULL, 202 INCR (Incremental) or DIFF (Differential). 204 o A element contains the date and time corresponding to 205 the Timeline Watermark ( element) of the . 207 o A element contains the header of the 208 as defined in [I-D.arias-noguchi-dnrd-objects-mapping] 210 An example of a object is available in 211 Section 2.1. 213 1.3.3. object 215 The object is used by Data Escrow 216 Agents to document the result of the data escrow deposit verification 217 process. The object contains the 218 following child elements: 220 o A element contains the name of the Data Escrow Agent. 222 o A element contains the version of the specification 223 used. This value MUST be 1. 225 o A element contains the reported date. In case of a DVPN 226 or DVFN notification this value MUST be the date of the 227 element of the . In case of a DRFN deposit 228 notification, this value MUST be the date for which no deposit was 229 received from the Registrar or Registry Operator. 231 o A element is used to specify the status of . 232 The possible values of status are: DVPN, DVFN and DRFN. The value 233 for the element is determined by the three types of 234 notices: 236 * Deposit Receipt Failure Notice (DRFN): generated by the Data 237 Escrow Agent when no deposit is received pursuant to the data 238 escrow deposit schedule. 240 * Deposit Verification Failure Notice (DVFN): generated by the 241 Data Escrow Agent when a deposit is received, but the final 242 result of the verification process is failure. 244 * Deposit Verification Pass Notice (DVPN): generated by the Data 245 Escrow Agent when a deposit is received and the final result of 246 the verification process is success. 248 o An OPTIONAL element contains the errors detected during 249 the data escrow deposit verification process performed by the Data 250 Escrow Agent. The element includes one or more 251 elements as defined in Section 1.3.1. In case of 252 a DRFN or DVPN deposit notification the element MUST NOT 253 be present. 255 o An OPTIONAL element contains the date and time that the 256 deposit was successfully received by the Data Escrow Agent. In 257 case of a DRFN deposit notification this element MUST NOT be 258 present. 260 o An OPTIONAL element contains the date and time that the 261 deposit was processed for validation by the Data Escrow Agent. In 262 case of a DRFN deposit notification this element MUST NOT be 263 present. 265 o An OPTIONAL element contains the date of the 266 Timeline Watermark ( element) of the most recent FULL 267 deposit that was successfully validated by the Data Escrow Agent. 268 This element MUST NOT be present if a successfully validated full 269 deposit has never been deposited. 271 o An OPTIONAL element is used by the Data Escrow 272 Agent to provide extended information about the deposit. In case 273 of a DRFN deposit notification this element MUST NOT be present. 274 In case of a DVPN or DVFN deposit notification this element MUST 275 be present. When this element is present, the 276 element MUST be generated by the Data Escrow Agent for the 277 Timeline Watermark ( element) of the deposit being 278 processed. If the deposit being processed is a differential or 279 incremental deposit, the Data Escrow Agent MUST process the last 280 full plus all differentials or last full plus last incremental 281 escrow deposits from the same repository (e.g. TLD) to generate 282 the element. 284 o Note: In case of a DVPN or DVFN deposit notification, the is 285 used as unique identifier. 287 An example of a object is available in 288 Section 2.2. 290 1.3.4. Object 292 Interfaces that support monitoring the reporting status for a 293 specific repository, provide a object as 294 defined by the schema in Section 6 in the HTTP Entity-body when a 295 HTTP/200 code is sent by the interface. 297 The element includes the following child 298 elements: 300 o A choice of one of the elements as defined in the 301 "rdeHeader:repositoryTypeGroup" (see 302 [I-D.arias-noguchi-dnrd-objects-mapping]) that indicates the 303 unique identifier for the repository being escrowed. 305 o A element with the date and time in which the 306 queried repository was created in the system. 308 o A OPTIONAL element indicating the current Data 309 Escrow Deposit schedule for the queried repository. Possible 310 values are "None", "Weekly", and "Daily". 312 o An OPTIONAL element indicating the date of the 313 Timeline Watermark ( element) of the most recent FULL 314 deposit that was successfully validated for the queried repository 315 as notified by the Data Escrow Agent. 317 o A element with a element for each 318 report type for the queried repository. Each 319 element includes the following child elements: 321 * : a string value indicating the report type to which the 322 information provided pertains. 324 * : a boolean value indicating if the report type is 325 enabled for the repository. 327 * : a string value indicating the reporting status. A 328 value of "ok" indicates there are no reporting issues in the 329 corresponding report type, otherwise the value of 330 "unsatisfactory" is shown. 332 * An OPTIONAL element included only when the 333 element has a value of "unsatisfactory", and includes an empty 334 element for each date with a reporting problem found in 335 the corresponding report type. Each element includes a 336 REQUIRED "date" attribute in "YYYY-MM-DD" format and a REQUIRED 337 "description" attribute to describe the issue. The possible 338 values to describe each reporting issue are: 340 + "Missing_Deposit_Full": If the latest notification received 341 from the Data Escrow Agent for the date indicates that a 342 scheduled "Full" deposit was not submitted by the repository 343 owner. 345 + "Missing_Deposit_Diff": If the latest notification received 346 from the Data Escrow Agent for the date indicates that a 347 scheduled "Differential" deposit was not submitted by the 348 repository owner. 350 + "Invalid_Deposit_Full": If the latest notification received 351 from the Data Escrow Agent for the date indicates that a 352 "Full" deposit was received by the Data Escrow Agent, but 353 failed the verification process. 355 + "Invalid_Deposit_Diff": If the latest notification received 356 from the Data Escrow Agent for the date indicates that a 357 "Differential" deposit was received by the Data Escrow 358 Agent, but failed the verification process. 360 + "No_Report_Received" If no report has been received for the 361 date. 363 o A element to indicate the date and time in which the 364 reporting status response was created. 366 1.3.5. Object 368 Interfaces that support monitoring and retrieving Data Escrow Reports 369 received, provide a object as defined by the 370 schema in Section 6 in the HTTP Entity-body when a HTTP/200 code is 371 sent by the interface. 373 The element includes a list of 374 objects, one for each 375 successfully received by ICANN. Each 376 object includes the following child elements: 378 o A element to indicate the date and time in which the 379 report was received by ICANN. 381 o A element as defined in Section 1.3.2 as 382 received by ICANN. 384 1.3.6. Object 386 Interfaces that support monitoring and retrieving Data Escrow 387 Notifications received from Data Escrow Agents, provide a 388 object as defined by the schema in 389 Section 6 in the HTTP Entity-body when a HTTP/200 code is sent by the 390 interface. 392 The element includes a list of 393 objects, one for each 394 successfully received by ICANN. Each 395 object includes the following 396 child elements: 398 o A element to indicate the date and time in which the 399 notification was received by ICANN. 401 o A element as defined in 402 Section 1.3.3 as received by ICANN. 404 2. Interfaces for Specification 2 - Data Escrow Reporting 406 This section describes the interfaces provided by ICANN to Registry 407 Operators and Data Escrow Agents in order to fulfill the reporting 408 requirements detailed in Specification 2 of the gTLD Base Registry 409 Agreement [ICANN-GTLD-BASE-RA]. 411 2.1. Registry Operator Reporting 413 The gTLD Base Registry Agreement [ICANN-GTLD-BASE-RA], Specification 414 2, Part A, Section 7 requires Registry Operators to provide ICANN 415 with a written statement that includes a copy of the report generated 416 upon creation of a deposit and a statement that the deposit has been 417 inspected by the Registry Operator and is complete and accurate. 419 In order to satisfy this requirement, the Registry Operator sends to 420 ICANN a object as defined in Section 1.3.2 for 421 each deposit successfully sent to the Data Escrow Agent, using the 422 PUT HTTP verb in the interface provided by ICANN at: 424 https://ry-api.icann.org/report/registry-escrow-report// 426 Where: 428 * MUST be substituted by the TLD for which the report is 429 being provided. In case of an IDN TLD, the A-label (see 430 [RFC5890]) MUST be used. 432 * MUST be substituted by the identifier assigned to this 433 report, which MUST be the same as the "id" attribute from the 434 . 436 Note: the interface supports overwriting the information of a 437 particular report to support asynchronous interfaces between 438 Registry Operators and Data Escrow Agents. 440 Example of a object for a data escrow deposit 441 corresponding to a TLD Registry repository: 443 444 447 20101017001 448 1 449 450 draft-arias-noguchi-registry-data-escrow-06 451 452 453 draft-arias-noguchi-dnrd-objects-mapping-05 454 455 0 456 2010-10-17T00:15:00.0Z 457 FULL 458 2010-10-17T00:00:00Z 459 460 test 461 2 463 1 465 1 467 1 469 470 1 472 1 474 1 476 477 478 480 2.2. Data Escrow Agent Reporting 482 The gTLD Base Registry Agreement [ICANN-GTLD-BASE-RA], Specification 483 2, Part B, Section 7 requires Data Escrow Agents, to deliver ICANN 484 with a notification object every time a successfully processed 485 deposit is received from the Registry Operator regardless of the 486 final status of the verification process. 488 In order to satisfy this requirement, the Data Escrow Agent sends to 489 ICANN a object as defined in 490 Section 1.3.3, using the POST HTTP verb in the interface provided by 491 ICANN at: 493 https://ry-api.icann.org/report/escrow-agent-notification/ 495 Where: 497 * MUST be substituted by the TLD for which the notification 498 is being provided. In case of an IDN TLD, the A-label (see 499 [RFC5890]) MUST be used. 501 If by 23:59:59 UTC, a deposit has not been successfully processed 502 regardless of the final status of the verification process, a 503 object with DRFN status MUST be send 504 to ICANN. 506 Example of a object of a Data Escrow 507 Agent notification corresponding to a Registry repository Data Escrow 508 Deposit: 510 511 515 Escrow Agent Inc. 516 1 517 2010-10-17 518 DVPN 519 520 2010-10-17T03:15:00.0Z 521 522 523 2010-10-17T05:15:00.0Z 524 525 526 2010-10-14 527 528 529 20101017001 530 1 531 532 draft-arias-noguchi-registry-data-escrow-06 533 534 535 draft-arias-noguchi-dnrd-objects-mapping-03 536 537 0 538 2010-10-17T00:15:00.0Z 539 FULL 540 2010-10-17T00:00:00Z 541 542 test 543 1 545 3 547 1 549 3 551 1 553 10 555 0 557 558 559 561 3. Interfaces of Specification 3 - Registry Operator Monthly Reporting 563 Specification 3 of the gTLD Base Registry Agreement 564 [ICANN-GTLD-BASE-RA] requires Registry Operators to provide a set of 565 monthly reports per gTLD. Two type of reports are required to be 566 sent by Registries: Per-Registrar Transactions Report and Registry 567 Functions Activity Report. This section specifies the interfaces 568 provided by ICANN to automate the upload of these reports by Registry 569 Operators. 571 The cut-off date for the reception of the reports specified in 572 specification 3 is defined in the gTLD Base Registry Agreement 573 [ICANN-GTLD-BASE-RA]. Before the cut-off date the Registry Operator 574 could replace a successfully validated report as many times as it 575 needs. 577 3.1. Per-Registrar Transactions Report 579 The Per-Registrar Transactions Report is a CSV report described in 580 Section 1 of Specification 3. 582 In order to satisfy this requirement, the Registry Operator sends a 583 CSV report on a monthly basis as described in the gTLD Base Registry 584 Agreement [ICANN-GTLD-BASE-RA], using the PUT HTTP verb in the 585 interface provided by ICANN at: 587 https://ry-api.icann.org/report/registrar- 588 transactions// 590 Where: 592 * MUST be substituted by the TLD for which the reports is 593 being provided. In case of an IDN TLD, the A-label (see 594 [RFC5890]) MUST be used. 596 * MUST be substituted by the month for which the reports 597 is being provided in the form of YYYY-MM. Where 'YYYY' is the 598 year and 'MM' is the two digit month number. For example: 599 2013-03 601 3.2. Registry Functions Activity Report 603 The Registry Functions Activity Report is a CSV report described in 604 Section 2 of Specification 3 of the gTLD Base Registry Agreement 605 [ICANN-GTLD-BASE-RA]. 607 In order to satisfy this requirement, the Registry Operator sends a 608 CSV report on a monthly basis as described in the gTLD Base Registry 609 Agreement [ICANN-GTLD-BASE-RA], using the PUT HTTP verb in the 610 interface provided by ICANN at: 612 https://ry-api.icann.org/report/registry-functions- 613 activity// 615 Where: 617 * MUST be substituted by the TLD for which the report is 618 being provided. In case of an IDN TLD, the A-label (see 619 [RFC5890]) MUST be used. 621 * MUST be substituted by the month for which the reports 622 is being provided in the form of YYYY-MM. Where 'YYYY' is the 623 year and 'MM' is the two digit month number. For example: 624 2013-03 626 4. Technical details of the interfaces 628 Content-type value in the HTTP header: 630 o The client MUST set "text/xml" in the HTTP header Content-type 631 when using the Data Escrow Agent Reporting and Registry Operator 632 Reporting interfaces described in Section 2. 634 o The client MUST set "text/csv" in the HTTP header Content-type 635 when using the Per-Registrar Transactions Report Registry 636 Functions Activity Report interfaces described in Section 3. 638 The interfaces support HTTP streams only (HTTP multi-part forms are 639 not supported). 641 After successfully receiving an input in any of the interfaces, ICANN 642 validates it and provides a object with an result element 643 in the same HTTP transaction. 645 The following HTTP status codes are standard across all interfaces: 647 o The interface provides a HTTP/200 status code and sets the HTTP 648 header Content-type: text/xml, if the interface was able to 649 receive the input sucessfully, the client MUST review the response 650 object to verify the result code after processing the input. 652 o The interface provides a HTTP/400 status code and sets the HTTP 653 header Content-type: text/xml, if the input is incorrect or the 654 syntax of the input is invalid. A response object is included 655 with the input validation failure details. 657 o The interface provides a HTTP/401 status code and sets the HTTP 658 header Content-type: text/plain, if the credentials provided does 659 not authorize the Registry Operator to upload a report for that 660 . 662 o The interface provides a HTTP/403 status code and sets the HTTP 663 header Content-type: text/plain, if the credentials provided are 664 valid but are being used to access a resource that permission is 665 not granted for or the connecting IP address is not whitelisted 666 for the . 668 o The interface provides a HTTP/405 status code if the interface 669 does not support the request method. 671 o The interface provides a HTTP/500 status code and sets the HTTP 672 header Content-type: text/plain, if the system is experiencing a 673 general failure. The sending party is responsible to send the 674 input again. 676 o The interface provides a HTTP/501 status code and sets the HTTP 677 header Content-type: text/plain, if the functionality has not yet 678 been implemented. 680 After sending the response, the interfaces closes the TCP connection. 682 4.1. Response Object 684 After processing the input provided in any of the interfaces, a 685 response object as defined by the schema in Section 6 is provided in 686 the HTTP Entity-body when an HTTP/200 or HTTP/400 status code is sent 687 by the interface. 689 An example of a response object upon successful input receipt is 690 presented below: 692 HTTP/1.1 200 OK 693 Content-Type: text/xml 694 Content-Length: 248 696 697 698 699 No ERRORs were found and the report has been 700 accepted by ICANN. 701 702 703 705 An example of a response object in the event of input error is 706 presented below: 708 HTTP/1.1 400 Bad Request 709 Content-Type: text/xml 710 Content-Length: 279 712 713 714 715 The structure of the report is invalid. 716 717 'XX' could not be parsed as a number (line: 2 column:3) 718 719 720 722 The following sections provide the IIRDEA Result Codes per interface: 724 4.1.1. Registry Operator Reporting 726 The following table lists the result codes of the interface: 728 +--------+----------------------------------------------------------+ 729 | Result | Message | 730 | Code | | 731 +--------+----------------------------------------------------------+ 732 | 1000 | No ERRORs were found and the report has been accepted by | 733 | | ICANN. | 734 | 2001 | The request did not validate against the schema. | 735 | 2004 | Report for a date in the future. The and | 736 | | date should not be in the future. | 737 | 2005 | Version is not supported. | 738 | 2006 | The in the element and the in the URL | 739 | | path do not match. | 740 | 2007 | Interface is disabled for this TLD. | 741 | 2008 | The and date should not be before | 742 | | the creation date of the TLD in the system. | 743 | 2202 | The in the
and the TLD in the URL path do | 744 | | not match. | 745 | 2205 | Report regarding a differential deposit received for a | 746 | | Sunday (). | 747 | 2206 | csvDomain and rdeDomain count provided in the
. | 748 | 2209 | Missing required element in the
. | 749 | 2210 | The value of the "rcdn" attribute in the element | 750 | | does not match the same or lower level names in the | 751 | | in the URL path. | 752 | 2211 | Multiple count elements with the same "uri", "rcdn", and | 753 | | "registrarId" attribute values provided in the
. | 754 | 2212 | An invalid NR-LDH label or A-label was found or the | 755 | | domain name syntax is invalid in the "rcdn" attribute. | 756 +--------+----------------------------------------------------------+ 758 Data Escrow Reporting Result Codes 760 4.1.2. Data Escrow Agent Reporting 762 The following table lists the result codes of the interface: 764 +--------+----------------------------------------------------------+ 765 | Result | Message | 766 | Code | | 767 +--------+----------------------------------------------------------+ 768 | 1000 | No ERRORs were found and the notification has been | 769 | | accepted by ICANN. | 770 | 2001 | The request did not validate against the schema. | 771 | 2002 | A DVPN notification exists for that date (). | 772 | 2004 | Notification for a date in the future. The and | 773 | | and date should not be in the | 774 | | future. | 775 | 2005 | Version is not supported. | 776 | 2007 | Interface is disabled for this TLD. | 777 | 2008 | The and and date should | 778 | | not be before the creation date of the TLD in the | 779 | | system. | 780 | 2201 | The and in the notification do not | 781 | | match. | 782 | 2202 | The in the
and the TLD in the URL path do | 783 | | not match. | 784 | 2203 | A Deposit Verification Pass Notice (DVPN) notification | 785 | | was received, but the Domain Name count is missing in | 786 | | the
. | 787 | 2204 | The notification for the report "id" already exists. | 788 | 2205 | Notification regarding a differential deposit received | 789 | | for a Sunday (). | 790 | 2206 | csvDomain and rdeDomain count provided in the
. | 791 | 2207 | A DVPN or DVFN was received, but the element is | 792 | | missing in the notification. | 793 | 2208 | A DRFN was received, but a element exists in | 794 | | the notification. | 795 | 2209 | Missing required element in the
. | 796 | 2210 | The value of the "rcdn" attribute in the element | 797 | | does not match the same or lower level names in the | 798 | | in the URL path. | 799 | 2211 | Multiple count elements with the same "uri", "rcdn", and | 800 | | "registrarId" attribute values provided in the
. | 801 | 2212 | An invalid NR-LDH label or A-label was found or the | 802 | | domain name syntax is invalid in the "rcdn" attribute. | 803 +--------+----------------------------------------------------------+ 805 Data Escrow Reporting Result Codes 807 4.1.3. Per-Registrar Transactions Report 809 The following table lists the result codes of the interface: 811 +----------+--------------------------------------------------------+ 812 | Result | Message | 813 | Code | | 814 +----------+--------------------------------------------------------+ 815 | 1000 | No ERRORs were found and the report has been accepted | 816 | | by ICANN. | 817 | 2001 | The structure of the report is invalid. | 818 | 2002 | A report for that month already exists, the cut-off | 819 | | date already passed. | 820 | 2003 | Negative numeric value present in the report. | 821 | 2004 | Report for a month in the future. | 822 | 2007 | Interface is disabled for this TLD. | 823 | 2008 | Reported month before the creation date of the TLD in | 824 | | the system. | 825 | 2101 | Incorrect totals present in the report. | 826 | 2102 | A non ICANN-accredited registrar is present in the | 827 | | report. | 828 | 2103 | Values found in the second field of the totals line. | 829 | 2105 | The report is not encoded in UTF-8. Note: reports | 830 | | encoded in US-ASCII are accepted. | 831 +----------+--------------------------------------------------------+ 833 Per-Registrar Transactions Report Result Codes 835 4.1.4. Registry Functions Activity Report 837 The following table lists the result codes of the interface: 839 +----------+--------------------------------------------------------+ 840 | Result | Message | 841 | Code | | 842 +----------+--------------------------------------------------------+ 843 | 1000 | No ERRORs were found and the report has been accepted | 844 | | by ICANN. | 845 | 2001 | The structure of the report is invalid. | 846 | 2002 | A report for that month already exists, the cut-off | 847 | | date already passed. | 848 | 2003 | Negative numeric value present in the report. | 849 | 2004 | Report for a month in the future. | 850 | 2007 | Interface is disabled for this TLD. | 851 | 2008 | Reported month before the creation date of the TLD in | 852 | | the system. | 853 | 2105 | The report is not encoded in UTF-8. Note: reports | 854 | | encoded in US-ASCII are accepted. | 855 +----------+--------------------------------------------------------+ 857 Registry Functions Activity Report Result Codes 859 5. Monitoring the reporting status 861 Registries MAY monitor the status of the reports described in 862 Specification 2 and Specification 3 of the gTLD Base Registry 863 Agreement [ICANN-GTLD-BASE-RA] using the following interfaces that 864 supports the HEAD HTTP verb: 866 5.1. Monitoring the status of Data Escrow Reports 868 Registries MAY monitor the status of Data Escrow Reports using the 869 following interface: 871 https://ry-api.icann.org/info/report/registry-escrow- 872 report// 874 Where: 876 * MUST be substituted by the TLD being queried. In case of 877 an IDN TLD, the A-label (see [RFC5890]) MUST be used. 879 * MUST be substituted by the day being queried. For 880 example: 2013-03-02 882 Possible results are: 884 * The interface provides a HTTP/200 status code, if a 885 syntactically valid data escrow report was received for the 886 queried date. 888 * The interface provides a HTTP/404 status code, if a 889 syntactically valid data escrow report has not been received 890 for the queried date. 892 5.2. Monitoring the status of Data Escrow Notifications 894 Registries and Data Escrow Agents MAY monitor the status of Data 895 Escrow Notifications using the following interface: 897 https://ry-api.icann.org/info/report/escrow-agent- 898 notification// 900 Where: 902 * MUST be substituted by the TLD being queried. In case of 903 an IDN TLD, the A-label (see [RFC5890]) MUST be used. 905 * MUST be substituted by the day being queried. For 906 example: 2013-03-02 908 Possible results are: 910 * The interface provides a HTTP/200 status code, if a 911 syntactically valid data escrow notification was received for 912 the queried date. 914 * The interface provides a HTTP/404 status code, if a 915 syntactically valid data escrow notification has not been 916 received for the queried date. 918 5.3. Monitoring the status of Registry Functions Activity Report 920 Registries MAY monitor the status of Registry Functions Activity 921 Report using the following interface: 923 https://ry-api.icann.org/info/report/registry-functions- 924 activity// 926 Where: 928 * MUST be substituted by the TLD being queried. In case of 929 an IDN TLD, the A-label (see [RFC5890]) MUST be used. 931 * MUST be substituted by the month being queried. For 932 example: 2013-03 934 Possible results are: 936 * The interface provides a HTTP/200 status code, if a 937 syntactically valid registry functions activity report was 938 received for the queried month. 940 * The interface provides a HTTP/404 status code, if a 941 syntactically valid registry functions activity report has not 942 been received for the queried month. 944 5.4. Monitoring the status of the Per-Registrar Transactions Report 946 Registries MAY monitor the status of Per-Registrar Transactions 947 Report using the following interface: 949 https://ry-api.icann.org/info/report/registrar- 950 transactions// 952 Where: 954 * MUST be substituted by the TLD being queried. In case of 955 an IDN TLD, the A-label (see [RFC5890]) MUST be used. 957 * MUST be substituted by the month being queried. For 958 example: 2013-03 960 Possible results are: 962 * The interface provides a HTTP/200 status code, if a 963 syntactically valid per-registrar transactions report was 964 received for the queried month. 966 * The interface provides a HTTP/404 status code, if a 967 syntactically valid per-registrar transactions report has not 968 been received for the queried month. 970 6. Formal Syntax 972 The schema of the IIRDEA Result, Report, Notification, RRI Reporting, 973 Notifications, and Reports objects described in Section 1.3 are 974 presented here. 976 The BEGIN and END tags are not part of the schema; they are used to 977 note the beginning and ending of the schema for URI registration 978 purposes. 980 6.1. IIRDEA Result Schema 982 Copyright (c) 2017 IETF Trust and the persons identified as authors 983 of the code. All rights reserved. 985 Redistribution and use in source and binary forms, with or without 986 modification, is permitted pursuant to, and subject to the license 987 terms contained in, the Simplified BSD License set forth in 988 Section 4.c of the IETF Trust's Legal Provisions Relating to IETF 989 Documents (http://trustee.ietf.org/license-info). 990 BEGIN 991 992 997 998 999 ICANN interfaces for registries and data escrow agents 1000 1001 1003 1004 1006 1007 1008 1009 1010 1012 1013 1014 1015 1017 1018 1020 1021 1023 1024 1025 1026 1027 1028 1030 1031 END 1033 6.2. Report Object 1035 Copyright (c) 2017 IETF Trust and the persons identified as authors 1036 of the code. All rights reserved. 1038 Redistribution and use in source and binary forms, with or without 1039 modification, is permitted pursuant to, and subject to the license 1040 terms contained in, the Simplified BSD License set forth in 1041 Section 4.c of the IETF Trust's Legal Provisions Relating to IETF 1042 Documents (http://trustee.ietf.org/license-info). 1044 BEGIN 1045 1046 1053 1054 1056 1057 1058 Data Escrow Report schema 1059 1060 1062 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 END 1080 6.3. Notification Object 1082 Copyright (c) 2017 IETF Trust and the persons identified as authors 1083 of the code. All rights reserved. 1085 Redistribution and use in source and binary forms, with or without 1086 modification, is permitted pursuant to, and subject to the license 1087 terms contained in, the Simplified BSD License set forth in 1088 Section 4.c of the IETF Trust's Legal Provisions Relating to IETF 1089 Documents (http://trustee.ietf.org/license-info). 1091 BEGIN 1092 1093 1100 1101 1103 1104 1105 Data Escrow Notification schema 1106 1107 1109 1112 1113 1114 1115 1116 1117 1118 1120 1121 1122 1123 1124 1125 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1139 1140 1141 1142 1143 1144 1145 1146 1147 END 1149 6.4. RRI Reporting Summary Object 1151 Copyright (c) 2018 IETF Trust and the persons identified as authors 1152 of the code. All rights reserved. 1154 Redistribution and use in source and binary forms, with or without 1155 modification, is permitted pursuant to, and subject to the license 1156 terms contained in, the Simplified BSD License set forth in 1157 Section 4.c of the IETF Trust's Legal Provisions Relating to IETF 1158 Documents (http://trustee.ietf.org/license-info). 1160 BEGIN 1161 1162 1168 1170 1172 1173 1174 1175 1176 1178 1179 1182 1183 1184 1186 1187 1188 1189 1190 1191 1192 1194 1195 1196 1198 1199 1201 1202 1203 1204 1205 1206 1208 1209 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1223 1224 1225 1226 1227 1228 1229 1230 1231 1233 1234 1236 1237 1239 1241 1243 1244 1245 1247 1248 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 END 1262 6.5. Notifications Object 1264 Copyright (c) 2018 IETF Trust and the persons identified as authors 1265 of the code. All rights reserved. 1267 Redistribution and use in source and binary forms, with or without 1268 modification, is permitted pursuant to, and subject to the license 1269 terms contained in, the Simplified BSD License set forth in 1270 Section 4.c of the IETF Trust's Legal Provisions Relating to IETF 1271 Documents (http://trustee.ietf.org/license-info). 1272 BEGIN 1273 1274 1280 1282 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 END 1300 6.6. Reports Object 1302 Copyright (c) 2018 IETF Trust and the persons identified as authors 1303 of the code. All rights reserved. 1305 Redistribution and use in source and binary forms, with or without 1306 modification, is permitted pursuant to, and subject to the license 1307 terms contained in, the Simplified BSD License set forth in 1308 Section 4.c of the IETF Trust's Legal Provisions Relating to IETF 1309 Documents (http://trustee.ietf.org/license-info). 1310 BEGIN 1311 1312 1318 1320 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 END 1337 7. Acknowledgements 1339 Special suggestions that have been incorporated into this document 1340 were provided by David Kipling, James Gould, Gregory Zaltsman, Brett 1341 Carr and Harel Efraim. 1343 8. Change History 1345 [[RFC Editor: Please remove this section.]] 1347 8.1. Version 00 1349 Initial version. 1351 8.2. Version 01 1353 o and moved from 1354 escrow drafts to this draft 1356 o Added to 1357 o element of is now OPTIONAL 1359 o Added element to 1361 o and added to the draft 1363 o Several report elements are OPTIONAL to support async interfaces 1364 between Registry Operators and Data Escrow Agents 1366 o Added and to registry-escrow-report interface in order 1367 to make the interface idempotent and support async RyO-DEA 1368 interfaces 1370 o Added to escrow-agent-notification interface 1372 o The escrow-agent-notification uses POST and not PUT, this has been 1373 fixed 1375 o Several clarifications 1377 8.3. Version 02 1379 o Added and updated several result codes. 1381 o Added element. 1383 o Added Content-type definition. 1385 8.4. Version 03 1387 o Added several result codes. 1389 o unsignedShort is now used for result code in iirdea schema. 1391 o Enumeration was removed from the iirdea schema. 1393 8.5. Version 04 1395 o Added result codes: 2207 and 2208. 1397 o Removed result codes: 2203. 1399 o Added clarification regarding the support of HTTP streams. 1401 8.6. Version 05 1403 o Added result codes: 2007 and 2008. 1405 8.7. Version 06 1407 o Added clarification of error code HTTP/403 in Section 4. 1409 8.8. Version 07 1411 o Added Section 5: "Monitoring compliance with the New gTLD Base 1412 Agreement". 1414 8.9. Version 08 1416 o Reorganized specification structure to allow easier references 1417 from new specifications expanding functionality in the ICANN 1418 Registry Interfaces. 1420 o Added Section 1.3 to document object definitions, previously 1421 defined in other sections. 1423 o Added , , and object 1424 descriptions to Section 1.3, and schema definitions to Section 6. 1426 o Renamed Section 5 title as "Monitoring the reporting status". 1428 o Updated element as OPTIONAL in the 1429 schema. 1431 o Added OPTIONAL attribute "domainCount" to the 1432 element. 1434 o Added OPTIONAL element to the schema. 1436 o Added result codes: 2105, 2209, 2210 and 2211. 1438 o Added "gTLD Base Registry Agreement" references. 1440 o Added clarifications to Section 4. 1442 8.10. Version 09 1444 o Standardized XSD schema validation error message for notifications 1445 and reports. 1447 o Element made optional in the schema. 1449 o Separated example RRI interface responses for successful and 1450 unsuccessful input. 1452 8.11. Version 10 1454 1. Ping update. 1456 9. IANA Considerations 1458 TODO 1460 10. Security Considerations 1462 TODO 1464 11. References 1466 11.1. Normative References 1468 [I-D.arias-noguchi-dnrd-objects-mapping] 1469 Lozano, G., Gould, J., and C. Thippeswamy, "Domain Name 1470 Registration Data (DNRD) Objects Mapping", draft-arias- 1471 noguchi-dnrd-objects-mapping-10 (work in progress), 1472 January 2019. 1474 [ICANN-GTLD-BASE-RA] 1475 ICANN, "gTLD Base Registry Agreement", Jan 2014, 1476 . 1479 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1480 Requirement Levels", BCP 14, RFC 2119, 1481 DOI 10.17487/RFC2119, March 1997, 1482 . 1484 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 1485 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 1486 . 1488 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1489 DOI 10.17487/RFC3688, January 2004, 1490 . 1492 11.2. Informative References 1494 [RFC5890] Klensin, J., "Internationalized Domain Names for 1495 Applications (IDNA): Definitions and Document Framework", 1496 RFC 5890, DOI 10.17487/RFC5890, August 2010, 1497 . 1499 [RFC5891] Klensin, J., "Internationalized Domain Names in 1500 Applications (IDNA): Protocol", RFC 5891, 1501 DOI 10.17487/RFC5891, August 2010, 1502 . 1504 Authors' Addresses 1506 Gustavo Lozano 1507 ICANN 1508 12025 Waterfront Drive, Suite 300 1509 Los Angeles 90292 1510 US 1512 Phone: +1.3103015800 1513 Email: gustavo.lozano@icann.org 1515 Eduardo Alvarez 1516 ICANN 1517 12025 Waterfront Drive, Suite 300 1518 Los Angeles 90292 1519 US 1521 Phone: +1.3103015800 1522 Email: eduardo.alvarez@icann.org