idnits 2.17.1 draft-lozano-icann-registry-interfaces-09.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 (September 18, 2018) is 2018 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: '1-9' is mentioned on line 1245, but not defined -- Looks like a reference, but probably isn't: '012' on line 1245 -- Looks like a reference, but probably isn't: '12' on line 1245 == Missing Reference: '0-9' is mentioned on line 1245, but not defined -- Looks like a reference, but probably isn't: '01' on line 1245 == Unused Reference: 'RFC3688' is defined on line 1483, but no explicit reference was found in the text == Unused Reference: 'RFC5891' is defined on line 1494, but no explicit reference was found in the text == Outdated reference: A later version (-10) exists of draft-arias-noguchi-dnrd-objects-mapping-09 Summary: 0 errors (**), 0 flaws (~~), 6 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: March 22, 2019 September 18, 2018 7 ICANN Registry Interfaces 8 draft-lozano-icann-registry-interfaces-09 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 March 22, 2019. 37 Copyright Notice 39 Copyright (c) 2018 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 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 35 94 10. Security Considerations . . . . . . . . . . . . . . . . . . . 35 95 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 35 96 11.1. Normative References . . . . . . . . . . . . . . . . . . 35 97 11.2. Informative References . . . . . . . . . . . . . . . . . 35 98 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 36 100 1. Introduction 102 This document describes the technical details of the interfaces 103 provided by the Internet Corporation for Assigned Names and Numbers 104 (ICANN) to other contracted parties in order to fulfill reporting 105 requirements. The interface provided by ICANN to Registry Operators 106 and Data Escrow Agents in order to fulfill the requirements of 107 Specifications 2 and 3 of the gTLD Base Registry Agreement 108 [ICANN-GTLD-BASE-RA] are also described in this document. 110 1.1. Terminology 112 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 113 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 114 document are to be interpreted as described in RFC 2119 [RFC2119]. 116 XML is case sensitive. Unless stated otherwise, XML specifications 117 and examples provided in this document MUST be interpreted in the 118 character case presented in order to develop a conforming 119 implementation. 121 1.2. Date and Time 123 Numerous fields indicate "date and time", such as the creation and 124 receipt dates for data escrow deposits. These fields SHALL contain 125 timestamps indicating the date and time in UTC as specified in 126 [RFC3339], with no offset from the zero meridian. 128 1.3. Object Description 130 This section describes the base objects supported by this 131 specification. 133 1.3.1. object 135 The ICANN interfaces for registries and data escrow agents (IIRDEA) 136 object is used to provide information on the result 137 of a verification process when interacting with the interfaces. 139 The object contains the following attribute and child 140 elements: 142 o A "code" attribute whose value is a four-digit decimal number that 143 identifies the result of a process. Available result code values 144 MUST be defined for the corresponding process. 146 o An OPTIONAL "domainCount" attribute to indicate the number of 147 domain names related to the reported result. 149 o A element containing a human-readable description of the 150 result code. 152 o An OPTIONAL element that includes additional details 153 on the result conditions. 155 An example of a object is presented below: 157 158 The structure of the report is invalid. 159 160 'XX' could not be parsed as a number (line: 2 column:3) 161 162 164 1.3.2. object 166 The contents of a data escrow deposit are described using a 167 object. The object contains 168 the following child elements: 170 o An element that contains the identifier assigned to this 171 report. The report identifier MUST be the same as the "id" 172 attribute from the . If the data escrow deposit does not 173 include a unique identifer, the Data Escrow Agent MUST generate a 174 unique identifier to reference the data escrow deposit and use it 175 in the element. 177 o A element contains the version of the specification 178 used. This value MUST be 1. 180 o A element contains the version of the Data Escrow 181 Specification (e.g. draft-arias-noguchi-registry-data-escrow-06) 182 used to create the deposit. After the specification is published 183 as an RFC, the value MUST be the RFC number assigned by IANA. 185 o An OPTIONAL element contains the version of the 186 Domain Name Registration Data (DNRD) Objects Mapping (e.g. draft- 187 arias-noguchi-dnrd-objects-mapping-05) used to create the deposit. 188 After the specification is published as an RFC, the value MUST be 189 the RFC number assigned by IANA. The element 190 MUST be included if the deposit was created using any version of 191 the DNRD objects mapping specification (see, 192 [I-D.arias-noguchi-dnrd-objects-mapping]). 194 o A element contains the value of the "resend" attribute of 195 the . 197 o A element contains the date and time that the deposit was 198 created by the Registry Operator. 200 o A element is used to identify the kind of deposit: FULL, 201 INCR (Incremental) or DIFF (Differential). 203 o A element contains the date and time corresponding to 204 the Timeline Watermark ( element) of the . 206 o A element contains the header of the 207 as defined in [I-D.arias-noguchi-dnrd-objects-mapping] 209 An example of a object is available in 210 Section 2.1. 212 1.3.3. object 214 The object is used by Data Escrow 215 Agents to document the result of the data escrow deposit verification 216 process. The object contains the 217 following child elements: 219 o A element contains the name of the Data Escrow Agent. 221 o A element contains the version of the specification 222 used. This value MUST be 1. 224 o A element contains the reported date. In case of a DVPN 225 or DVFN notification this value MUST be the date of the 226 element of the . In case of a DRFN deposit 227 notification, this value MUST be the date for which no deposit was 228 received from the Registrar or Registry Operator. 230 o A element is used to specify the status of . 231 The possible values of status are: DVPN, DVFN and DRFN. The value 232 for the element is determined by the three types of 233 notices: 235 * Deposit Receipt Failure Notice (DRFN): generated by the Data 236 Escrow Agent when no deposit is received pursuant to the data 237 escrow deposit schedule. 239 * Deposit Verification Failure Notice (DVFN): generated by the 240 Data Escrow Agent when a deposit is received, but the final 241 result of the verification process is failure. 243 * Deposit Verification Pass Notice (DVPN): generated by the Data 244 Escrow Agent when a deposit is received and the final result of 245 the verification process is success. 247 o An OPTIONAL element contains the errors detected during 248 the data escrow deposit verification process performed by the Data 249 Escrow Agent. The element includes one or more 250 elements as defined in Section 1.3.1. In case of 251 a DRFN or DVPN deposit notification the element MUST NOT 252 be present. 254 o An OPTIONAL element contains the date and time that the 255 deposit was successfully received by the Data Escrow Agent. In 256 case of a DRFN deposit notification this element MUST NOT be 257 present. 259 o An OPTIONAL element contains the date and time that the 260 deposit was processed for validation by the Data Escrow Agent. In 261 case of a DRFN deposit notification this element MUST NOT be 262 present. 264 o An OPTIONAL element contains the date of the 265 Timeline Watermark ( element) of the most recent FULL 266 deposit that was successfully validated by the Data Escrow Agent. 267 This element MUST NOT be present if a successfully validated full 268 deposit has never been deposited. 270 o An OPTIONAL element is used by the Data Escrow 271 Agent to provide extended information about the deposit. In case 272 of a DRFN deposit notification this element MUST NOT be present. 273 In case of a DVPN or DVFN deposit notification this element MUST 274 be present. When this element is present, the 275 element MUST be generated by the Data Escrow Agent for the 276 Timeline Watermark ( element) of the deposit being 277 processed. If the deposit being processed is a differential or 278 incremental deposit, the Data Escrow Agent MUST process the last 279 full plus all differentials or last full plus last incremental 280 escrow deposits from the same repository (e.g. TLD) to generate 281 the element. 283 o Note: In case of a DVPN or DVFN deposit notification, the is 284 used as unique identifier. 286 An example of a object is available in 287 Section 2.2. 289 1.3.4. Object 291 Interfaces that support monitoring the reporting status for a 292 specific repository, provide a object as 293 defined by the schema in Section 6 in the HTTP Entity-body when a 294 HTTP/200 code is sent by the interface. 296 The element includes the following child 297 elements: 299 o A choice of one of the elements as defined in the 300 "rdeHeader:repositoryTypeGroup" (see 301 [I-D.arias-noguchi-dnrd-objects-mapping]) that indicates the 302 unique identifier for the repository being escrowed. 304 o A element with the date and time in which the 305 queried repository was created in the system. 307 o A OPTIONAL element indicating the current Data 308 Escrow Deposit schedule for the queried repository. Possible 309 values are "None", "Weekly", and "Daily". 311 o An OPTIONAL element indicating the date of the 312 Timeline Watermark ( element) of the most recent FULL 313 deposit that was successfully validated for the queried repository 314 as notified by the Data Escrow Agent. 316 o A element with a element for each 317 report type for the queried repository. Each 318 element includes the following child elements: 320 * : a string value indicating the report type to which the 321 information provided pertains. 323 * : a boolean value indicating if the report type is 324 enabled for the repository. 326 * : a string value indicating the reporting status. A 327 value of "ok" indicates there are no reporting issues in the 328 corresponding report type, otherwise the value of 329 "unsatisfactory" is shown. 331 * An OPTIONAL element included only when the 332 element has a value of "unsatisfactory", and includes an empty 333 element for each date with a reporting problem found in 334 the corresponding report type. Each element includes a 335 REQUIRED "date" attribute in "YYYY-MM-DD" format and a REQUIRED 336 "description" attribute to describe the issue. The possible 337 values to describe each reporting issue are: 339 + "Missing_Deposit_Full": If the latest notification received 340 from the Data Escrow Agent for the date indicates that a 341 scheduled "Full" deposit was not submitted by the repository 342 owner. 344 + "Missing_Deposit_Diff": If the latest notification received 345 from the Data Escrow Agent for the date indicates that a 346 scheduled "Differential" deposit was not submitted by the 347 repository owner. 349 + "Invalid_Deposit_Full": If the latest notification received 350 from the Data Escrow Agent for the date indicates that a 351 "Full" deposit was received by the Data Escrow Agent, but 352 failed the verification process. 354 + "Invalid_Deposit_Diff": If the latest notification received 355 from the Data Escrow Agent for the date indicates that a 356 "Differential" deposit was received by the Data Escrow 357 Agent, but failed the verification process. 359 + "No_Report_Received" If no report has been received for the 360 date. 362 o A element to indicate the date and time in which the 363 reporting status response was created. 365 1.3.5. Object 367 Interfaces that support monitoring and retrieving Data Escrow Reports 368 received, provide a object as defined by the 369 schema in Section 6 in the HTTP Entity-body when a HTTP/200 code is 370 sent by the interface. 372 The element includes a list of 373 objects, one for each 374 successfully received by ICANN. Each 375 object includes the following child elements: 377 o A element to indicate the date and time in which the 378 report was received by ICANN. 380 o A element as defined in Section 1.3.2 as 381 received by ICANN. 383 1.3.6. Object 385 Interfaces that support monitoring and retrieving Data Escrow 386 Notifications received from Data Escrow Agents, provide a 387 object as defined by the schema in 388 Section 6 in the HTTP Entity-body when a HTTP/200 code is sent by the 389 interface. 391 The element includes a list of 392 objects, one for each 393 successfully received by ICANN. Each 394 object includes the following 395 child elements: 397 o A element to indicate the date and time in which the 398 notification was received by ICANN. 400 o A element as defined in 401 Section 1.3.3 as received by ICANN. 403 2. Interfaces for Specification 2 - Data Escrow Reporting 405 This section describes the interfaces provided by ICANN to Registry 406 Operators and Data Escrow Agents in order to fulfill the reporting 407 requirements detailed in Specification 2 of the gTLD Base Registry 408 Agreement [ICANN-GTLD-BASE-RA]. 410 2.1. Registry Operator Reporting 412 The gTLD Base Registry Agreement [ICANN-GTLD-BASE-RA], Specification 413 2, Part A, Section 7 requires Registry Operators to provide ICANN 414 with a written statement that includes a copy of the report generated 415 upon creation of a deposit and a statement that the deposit has been 416 inspected by the Registry Operator and is complete and accurate. 418 In order to satisfy this requirement, the Registry Operator sends to 419 ICANN a object as defined in Section 1.3.2 for 420 each deposit successfully sent to the Data Escrow Agent, using the 421 PUT HTTP verb in the interface provided by ICANN at: 423 https://ry-api.icann.org/report/registry-escrow-report// 425 Where: 427 * MUST be substituted by the TLD for which the report is 428 being provided. In case of an IDN TLD, the A-label (see 429 [RFC5890]) MUST be used. 431 * MUST be substituted by the identifier assigned to this 432 report, which MUST be the same as the "id" attribute from the 433 . 435 Note: the interface supports overwriting the information of a 436 particular report to support asynchronous interfaces between 437 Registry Operators and Data Escrow Agents. 439 Example of a object for a data escrow deposit 440 corresponding to a TLD Registry repository: 442 443 446 20101017001 447 1 448 449 draft-arias-noguchi-registry-data-escrow-06 450 451 452 draft-arias-noguchi-dnrd-objects-mapping-05 453 454 0 455 2010-10-17T00:15:00.0Z 456 FULL 457 2010-10-17T00:00:00Z 458 459 test 460 2 462 1 464 1 466 1 468 469 1 471 1 473 1 475 476 477 479 2.2. Data Escrow Agent Reporting 481 The gTLD Base Registry Agreement [ICANN-GTLD-BASE-RA], Specification 482 2, Part B, Section 7 requires Data Escrow Agents, to deliver ICANN 483 with a notification object every time a successfully processed 484 deposit is received from the Registry Operator regardless of the 485 final status of the verification process. 487 In order to satisfy this requirement, the Data Escrow Agent sends to 488 ICANN a object as defined in 489 Section 1.3.3, using the POST HTTP verb in the interface provided by 490 ICANN at: 492 https://ry-api.icann.org/report/escrow-agent-notification/ 494 Where: 496 * MUST be substituted by the TLD for which the notification 497 is being provided. In case of an IDN TLD, the A-label (see 498 [RFC5890]) MUST be used. 500 If by 23:59:59 UTC, a deposit has not been successfully processed 501 regardless of the final status of the verification process, a 502 object with DRFN status MUST be send 503 to ICANN. 505 Example of a object of a Data Escrow 506 Agent notification corresponding to a Registry repository Data Escrow 507 Deposit: 509 510 514 Escrow Agent Inc. 515 1 516 2010-10-17 517 DVPN 518 519 2010-10-17T03:15:00.0Z 520 521 522 2010-10-17T05:15:00.0Z 523 524 525 2010-10-14 526 527 528 20101017001 529 1 530 531 draft-arias-noguchi-registry-data-escrow-06 532 533 534 draft-arias-noguchi-dnrd-objects-mapping-03 535 536 0 537 2010-10-17T00:15:00.0Z 538 FULL 539 2010-10-17T00:00:00Z 540 541 test 542 1 544 3 546 1 548 3 550 1 552 10 554 0 556 557 558 560 3. Interfaces of Specification 3 - Registry Operator Monthly Reporting 562 Specification 3 of the gTLD Base Registry Agreement 563 [ICANN-GTLD-BASE-RA] requires Registry Operators to provide a set of 564 monthly reports per gTLD. Two type of reports are required to be 565 sent by Registries: Per-Registrar Transactions Report and Registry 566 Functions Activity Report. This section specifies the interfaces 567 provided by ICANN to automate the upload of these reports by Registry 568 Operators. 570 The cut-off date for the reception of the reports specified in 571 specification 3 is defined in the gTLD Base Registry Agreement 572 [ICANN-GTLD-BASE-RA]. Before the cut-off date the Registry Operator 573 could replace a successfully validated report as many times as it 574 needs. 576 3.1. Per-Registrar Transactions Report 578 The Per-Registrar Transactions Report is a CSV report described in 579 Section 1 of Specification 3. 581 In order to satisfy this requirement, the Registry Operator sends a 582 CSV report on a monthly basis as described in the gTLD Base Registry 583 Agreement [ICANN-GTLD-BASE-RA], using the PUT HTTP verb in the 584 interface provided by ICANN at: 586 https://ry-api.icann.org/report/registrar- 587 transactions// 589 Where: 591 * MUST be substituted by the TLD for which the reports is 592 being provided. In case of an IDN TLD, the A-label (see 593 [RFC5890]) MUST be used. 595 * MUST be substituted by the month for which the reports 596 is being provided in the form of YYYY-MM. Where 'YYYY' is the 597 year and 'MM' is the two digit month number. For example: 598 2013-03 600 3.2. Registry Functions Activity Report 602 The Registry Functions Activity Report is a CSV report described in 603 Section 2 of Specification 3 of the gTLD Base Registry Agreement 604 [ICANN-GTLD-BASE-RA]. 606 In order to satisfy this requirement, the Registry Operator sends a 607 CSV report on a monthly basis as described in the gTLD Base Registry 608 Agreement [ICANN-GTLD-BASE-RA], using the PUT HTTP verb in the 609 interface provided by ICANN at: 611 https://ry-api.icann.org/report/registry-functions- 612 activity// 614 Where: 616 * MUST be substituted by the TLD for which the report is 617 being provided. In case of an IDN TLD, the A-label (see 618 [RFC5890]) MUST be used. 620 * MUST be substituted by the month for which the reports 621 is being provided in the form of YYYY-MM. Where 'YYYY' is the 622 year and 'MM' is the two digit month number. For example: 623 2013-03 625 4. Technical details of the interfaces 627 Content-type value in the HTTP header: 629 o The client MUST set "text/xml" in the HTTP header Content-type 630 when using the Data Escrow Agent Reporting and Registry Operator 631 Reporting interfaces described in Section 2. 633 o The client MUST set "text/csv" in the HTTP header Content-type 634 when using the Per-Registrar Transactions Report Registry 635 Functions Activity Report interfaces described in Section 3. 637 The interfaces support HTTP streams only (HTTP multi-part forms are 638 not supported). 640 After successfully receiving an input in any of the interfaces, ICANN 641 validates it and provides a object with an result element 642 in the same HTTP transaction. 644 The following HTTP status codes are standard across all interfaces: 646 o The interface provides a HTTP/200 status code and sets the HTTP 647 header Content-type: text/xml, if the interface was able to 648 receive the input sucessfully, the client MUST review the response 649 object to verify the result code after processing the input. 651 o The interface provides a HTTP/400 status code and sets the HTTP 652 header Content-type: text/xml, if the input is incorrect or the 653 syntax of the input is invalid. A response object is included 654 with the input validation failure details. 656 o The interface provides a HTTP/401 status code and sets the HTTP 657 header Content-type: text/plain, if the credentials provided does 658 not authorize the Registry Operator to upload a report for that 659 . 661 o The interface provides a HTTP/403 status code and sets the HTTP 662 header Content-type: text/plain, if the credentials provided are 663 valid but are being used to access a resource that permission is 664 not granted for or the connecting IP address is not whitelisted 665 for the . 667 o The interface provides a HTTP/405 status code if the interface 668 does not support the request method. 670 o The interface provides a HTTP/500 status code and sets the HTTP 671 header Content-type: text/plain, if the system is experiencing a 672 general failure. The sending party is responsible to send the 673 input again. 675 o The interface provides a HTTP/501 status code and sets the HTTP 676 header Content-type: text/plain, if the functionality has not yet 677 been implemented. 679 After sending the response, the interfaces closes the TCP connection. 681 4.1. Response Object 683 After processing the input provided in any of the interfaces, a 684 response object as defined by the schema in Section 6 is provided in 685 the HTTP Entity-body when an HTTP/200 or HTTP/400 status code is sent 686 by the interface. 688 An example of a response object upon successful input receipt is 689 presented below: 691 HTTP/1.1 200 OK 692 Content-Type: text/xml 693 Content-Length: 248 695 696 697 698 No ERRORs were found and the report has been 699 accepted by ICANN. 700 701 702 704 An example of a response object in the event of input error is 705 presented below: 707 HTTP/1.1 400 Bad Request 708 Content-Type: text/xml 709 Content-Length: 279 711 712 713 714 The structure of the report is invalid. 715 716 'XX' could not be parsed as a number (line: 2 column:3) 717 718 719 721 The following sections provide the IIRDEA Result Codes per interface: 723 4.1.1. Registry Operator Reporting 725 The following table lists the result codes of the interface: 727 +--------+----------------------------------------------------------+ 728 | Result | Message | 729 | Code | | 730 +--------+----------------------------------------------------------+ 731 | 1000 | No ERRORs were found and the report has been accepted by | 732 | | ICANN. | 733 | 2001 | The request did not validate against the schema. | 734 | 2004 | Report for a date in the future. The and | 735 | | date should not be in the future. | 736 | 2005 | Version is not supported. | 737 | 2006 | The in the element and the in the URL | 738 | | path do not match. | 739 | 2007 | Interface is disabled for this TLD. | 740 | 2008 | The and date should not be before | 741 | | the creation date of the TLD in the system. | 742 | 2202 | The in the
and the TLD in the URL path do | 743 | | not match. | 744 | 2205 | Report regarding a differential deposit received for a | 745 | | Sunday (). | 746 | 2206 | csvDomain and rdeDomain count provided in the
. | 747 | 2209 | Missing required element in the
. | 748 | 2210 | The value of the "rcdn" attribute in the element | 749 | | does not match the same or lower level names in the | 750 | | in the URL path. | 751 | 2211 | Multiple count elements with the same "uri", "rcdn", and | 752 | | "registrarId" attribute values provided in the
. | 753 | 2212 | An invalid NR-LDH label or A-label was found or the | 754 | | domain name syntax is invalid in the "rcdn" attribute. | 755 +--------+----------------------------------------------------------+ 757 Data Escrow Reporting Result Codes 759 4.1.2. Data Escrow Agent Reporting 761 The following table lists the result codes of the interface: 763 +--------+----------------------------------------------------------+ 764 | Result | Message | 765 | Code | | 766 +--------+----------------------------------------------------------+ 767 | 1000 | No ERRORs were found and the notification has been | 768 | | accepted by ICANN. | 769 | 2001 | The request did not validate against the schema. | 770 | 2002 | A DVPN notification exists for that date (). | 771 | 2004 | Notification for a date in the future. The and | 772 | | and date should not be in the | 773 | | future. | 774 | 2005 | Version is not supported. | 775 | 2007 | Interface is disabled for this TLD. | 776 | 2008 | The and and date should | 777 | | not be before the creation date of the TLD in the | 778 | | system. | 779 | 2201 | The and in the notification do not | 780 | | match. | 781 | 2202 | The in the
and the TLD in the URL path do | 782 | | not match. | 783 | 2203 | A Deposit Verification Pass Notice (DVPN) notification | 784 | | was received, but the Domain Name count is missing in | 785 | | the
. | 786 | 2204 | The notification for the report "id" already exists. | 787 | 2205 | Notification regarding a differential deposit received | 788 | | for a Sunday (). | 789 | 2206 | csvDomain and rdeDomain count provided in the
. | 790 | 2207 | A DVPN or DVFN was received, but the element is | 791 | | missing in the notification. | 792 | 2208 | A DRFN was received, but a element exists in | 793 | | the notification. | 794 | 2209 | Missing required element in the
. | 795 | 2210 | The value of the "rcdn" attribute in the element | 796 | | does not match the same or lower level names in the | 797 | | in the URL path. | 798 | 2211 | Multiple count elements with the same "uri", "rcdn", and | 799 | | "registrarId" attribute values provided in the
. | 800 | 2212 | An invalid NR-LDH label or A-label was found or the | 801 | | domain name syntax is invalid in the "rcdn" attribute. | 802 +--------+----------------------------------------------------------+ 804 Data Escrow Reporting Result Codes 806 4.1.3. Per-Registrar Transactions Report 808 The following table lists the result codes of the interface: 810 +----------+--------------------------------------------------------+ 811 | Result | Message | 812 | Code | | 813 +----------+--------------------------------------------------------+ 814 | 1000 | No ERRORs were found and the report has been accepted | 815 | | by ICANN. | 816 | 2001 | The structure of the report is invalid. | 817 | 2002 | A report for that month already exists, the cut-off | 818 | | date already passed. | 819 | 2003 | Negative numeric value present in the report. | 820 | 2004 | Report for a month in the future. | 821 | 2007 | Interface is disabled for this TLD. | 822 | 2008 | Reported month before the creation date of the TLD in | 823 | | the system. | 824 | 2101 | Incorrect totals present in the report. | 825 | 2102 | A non ICANN-accredited registrar is present in the | 826 | | report. | 827 | 2103 | Values found in the second field of the totals line. | 828 | 2105 | The report is not encoded in UTF-8. Note: reports | 829 | | encoded in US-ASCII are accepted. | 830 +----------+--------------------------------------------------------+ 832 Per-Registrar Transactions Report Result Codes 834 4.1.4. Registry Functions Activity Report 836 The following table lists the result codes of the interface: 838 +----------+--------------------------------------------------------+ 839 | Result | Message | 840 | Code | | 841 +----------+--------------------------------------------------------+ 842 | 1000 | No ERRORs were found and the report has been accepted | 843 | | by ICANN. | 844 | 2001 | The structure of the report is invalid. | 845 | 2002 | A report for that month already exists, the cut-off | 846 | | date already passed. | 847 | 2003 | Negative numeric value present in the report. | 848 | 2004 | Report for a month in the future. | 849 | 2007 | Interface is disabled for this TLD. | 850 | 2008 | Reported month before the creation date of the TLD in | 851 | | the system. | 852 | 2105 | The report is not encoded in UTF-8. Note: reports | 853 | | encoded in US-ASCII are accepted. | 854 +----------+--------------------------------------------------------+ 856 Registry Functions Activity Report Result Codes 858 5. Monitoring the reporting status 860 Registries MAY monitor the status of the reports described in 861 Specification 2 and Specification 3 of the gTLD Base Registry 862 Agreement [ICANN-GTLD-BASE-RA] using the following interfaces that 863 supports the HEAD HTTP verb: 865 5.1. Monitoring the status of Data Escrow Reports 867 Registries MAY monitor the status of Data Escrow Reports using the 868 following interface: 870 https://ry-api.icann.org/info/report/registry-escrow- 871 report// 873 Where: 875 * MUST be substituted by the TLD being queried. In case of 876 an IDN TLD, the A-label (see [RFC5890]) MUST be used. 878 * MUST be substituted by the day being queried. For 879 example: 2013-03-02 881 Possible results are: 883 * The interface provides a HTTP/200 status code, if a 884 syntactically valid data escrow report was received for the 885 queried date. 887 * The interface provides a HTTP/404 status code, if a 888 syntactically valid data escrow report has not been received 889 for the queried date. 891 5.2. Monitoring the status of Data Escrow Notifications 893 Registries and Data Escrow Agents MAY monitor the status of Data 894 Escrow Notifications using the following interface: 896 https://ry-api.icann.org/info/report/escrow-agent- 897 notification// 899 Where: 901 * MUST be substituted by the TLD being queried. In case of 902 an IDN TLD, the A-label (see [RFC5890]) MUST be used. 904 * MUST be substituted by the day being queried. For 905 example: 2013-03-02 907 Possible results are: 909 * The interface provides a HTTP/200 status code, if a 910 syntactically valid data escrow notification was received for 911 the queried date. 913 * The interface provides a HTTP/404 status code, if a 914 syntactically valid data escrow notification has not been 915 received for the queried date. 917 5.3. Monitoring the status of Registry Functions Activity Report 919 Registries MAY monitor the status of Registry Functions Activity 920 Report using the following interface: 922 https://ry-api.icann.org/info/report/registry-functions- 923 activity// 925 Where: 927 * MUST be substituted by the TLD being queried. In case of 928 an IDN TLD, the A-label (see [RFC5890]) MUST be used. 930 * MUST be substituted by the month being queried. For 931 example: 2013-03 933 Possible results are: 935 * The interface provides a HTTP/200 status code, if a 936 syntactically valid registry functions activity report was 937 received for the queried month. 939 * The interface provides a HTTP/404 status code, if a 940 syntactically valid registry functions activity report has not 941 been received for the queried month. 943 5.4. Monitoring the status of the Per-Registrar Transactions Report 945 Registries MAY monitor the status of Per-Registrar Transactions 946 Report using the following interface: 948 https://ry-api.icann.org/info/report/registrar- 949 transactions// 951 Where: 953 * MUST be substituted by the TLD being queried. In case of 954 an IDN TLD, the A-label (see [RFC5890]) MUST be used. 956 * MUST be substituted by the month being queried. For 957 example: 2013-03 959 Possible results are: 961 * The interface provides a HTTP/200 status code, if a 962 syntactically valid per-registrar transactions report was 963 received for the queried month. 965 * The interface provides a HTTP/404 status code, if a 966 syntactically valid per-registrar transactions report has not 967 been received for the queried month. 969 6. Formal Syntax 971 The schema of the IIRDEA Result, Report, Notification, RRI Reporting, 972 Notifications, and Reports objects described in Section 1.3 are 973 presented here. 975 The BEGIN and END tags are not part of the schema; they are used to 976 note the beginning and ending of the schema for URI registration 977 purposes. 979 6.1. IIRDEA Result Schema 981 Copyright (c) 2017 IETF Trust and the persons identified as authors 982 of the code. All rights reserved. 984 Redistribution and use in source and binary forms, with or without 985 modification, is permitted pursuant to, and subject to the license 986 terms contained in, the Simplified BSD License set forth in 987 Section 4.c of the IETF Trust's Legal Provisions Relating to IETF 988 Documents (http://trustee.ietf.org/license-info). 989 BEGIN 990 991 996 997 998 ICANN interfaces for registries and data escrow agents 999 1000 1002 1003 1005 1006 1007 1008 1009 1011 1012 1013 1014 1016 1017 1019 1020 1022 1023 1024 1025 1026 1027 1029 1030 END 1032 6.2. Report Object 1034 Copyright (c) 2017 IETF Trust and the persons identified as authors 1035 of the code. All rights reserved. 1037 Redistribution and use in source and binary forms, with or without 1038 modification, is permitted pursuant to, and subject to the license 1039 terms contained in, the Simplified BSD License set forth in 1040 Section 4.c of the IETF Trust's Legal Provisions Relating to IETF 1041 Documents (http://trustee.ietf.org/license-info). 1043 BEGIN 1044 1045 1052 1053 1055 1056 1057 Data Escrow Report schema 1058 1059 1061 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 END 1079 6.3. Notification Object 1081 Copyright (c) 2017 IETF Trust and the persons identified as authors 1082 of the code. All rights reserved. 1084 Redistribution and use in source and binary forms, with or without 1085 modification, is permitted pursuant to, and subject to the license 1086 terms contained in, the Simplified BSD License set forth in 1087 Section 4.c of the IETF Trust's Legal Provisions Relating to IETF 1088 Documents (http://trustee.ietf.org/license-info). 1090 BEGIN 1091 1092 1099 1100 1102 1103 1104 Data Escrow Notification schema 1105 1106 1108 1111 1112 1113 1114 1115 1116 1117 1119 1120 1121 1122 1123 1124 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1138 1139 1140 1141 1142 1143 1144 1145 1146 END 1148 6.4. RRI Reporting Summary Object 1150 Copyright (c) 2018 IETF Trust and the persons identified as authors 1151 of the code. All rights reserved. 1153 Redistribution and use in source and binary forms, with or without 1154 modification, is permitted pursuant to, and subject to the license 1155 terms contained in, the Simplified BSD License set forth in 1156 Section 4.c of the IETF Trust's Legal Provisions Relating to IETF 1157 Documents (http://trustee.ietf.org/license-info). 1159 BEGIN 1160 1161 1167 1169 1171 1172 1173 1174 1175 1177 1178 1181 1182 1183 1185 1186 1187 1188 1189 1190 1191 1193 1194 1195 1197 1198 1200 1201 1202 1203 1204 1205 1207 1208 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1222 1223 1224 1225 1226 1227 1228 1229 1230 1232 1233 1235 1236 1238 1240 1242 1243 1244 1246 1247 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 END 1261 6.5. Notifications Object 1263 Copyright (c) 2018 IETF Trust and the persons identified as authors 1264 of the code. All rights reserved. 1266 Redistribution and use in source and binary forms, with or without 1267 modification, is permitted pursuant to, and subject to the license 1268 terms contained in, the Simplified BSD License set forth in 1269 Section 4.c of the IETF Trust's Legal Provisions Relating to IETF 1270 Documents (http://trustee.ietf.org/license-info). 1271 BEGIN 1272 1273 1279 1281 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 END 1299 6.6. Reports Object 1301 Copyright (c) 2018 IETF Trust and the persons identified as authors 1302 of the code. All rights reserved. 1304 Redistribution and use in source and binary forms, with or without 1305 modification, is permitted pursuant to, and subject to the license 1306 terms contained in, the Simplified BSD License set forth in 1307 Section 4.c of the IETF Trust's Legal Provisions Relating to IETF 1308 Documents (http://trustee.ietf.org/license-info). 1309 BEGIN 1310 1311 1317 1319 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 END 1336 7. Acknowledgements 1338 Special suggestions that have been incorporated into this document 1339 were provided by David Kipling, James Gould, Gregory Zaltsman, Brett 1340 Carr and Harel Efraim. 1342 8. Change History 1344 [[RFC Editor: Please remove this section.]] 1346 8.1. Version 00 1348 Initial version. 1350 8.2. Version 01 1352 o and moved from 1353 escrow drafts to this draft 1355 o Added to 1356 o element of is now OPTIONAL 1358 o Added element to 1360 o and added to the draft 1362 o Several report elements are OPTIONAL to support async interfaces 1363 between Registry Operators and Data Escrow Agents 1365 o Added and to registry-escrow-report interface in order 1366 to make the interface idempotent and support async RyO-DEA 1367 interfaces 1369 o Added to escrow-agent-notification interface 1371 o The escrow-agent-notification uses POST and not PUT, this has been 1372 fixed 1374 o Several clarifications 1376 8.3. Version 02 1378 o Added and updated several result codes. 1380 o Added element. 1382 o Added Content-type definition. 1384 8.4. Version 03 1386 o Added several result codes. 1388 o unsignedShort is now used for result code in iirdea schema. 1390 o Enumeration was removed from the iirdea schema. 1392 8.5. Version 04 1394 o Added result codes: 2207 and 2208. 1396 o Removed result codes: 2203. 1398 o Added clarification regarding the support of HTTP streams. 1400 8.6. Version 05 1402 o Added result codes: 2007 and 2008. 1404 8.7. Version 06 1406 o Added clarification of error code HTTP/403 in Section 4. 1408 8.8. Version 07 1410 o Added Section 5: "Monitoring compliance with the New gTLD Base 1411 Agreement". 1413 8.9. Version 08 1415 o Reorganized specification structure to allow easier references 1416 from new specifications expanding functionality in the ICANN 1417 Registry Interfaces. 1419 o Added Section 1.3 to document object definitions, previously 1420 defined in other sections. 1422 o Added , , and object 1423 descriptions to Section 1.3, and schema definitions to Section 6. 1425 o Renamed Section 5 title as "Monitoring the reporting status". 1427 o Updated element as OPTIONAL in the 1428 schema. 1430 o Added OPTIONAL attribute "domainCount" to the 1431 element. 1433 o Added OPTIONAL element to the schema. 1435 o Added result codes: 2105, 2209, 2210 and 2211. 1437 o Added "gTLD Base Registry Agreement" references. 1439 o Added clarifications to Section 4. 1441 8.10. Version 09 1443 o Standardized XSD schema validation error message for notifications 1444 and reports. 1446 o Element made optional in the schema. 1448 o Separated example RRI interface responses for successful and 1449 unsuccessful input. 1451 9. IANA Considerations 1453 TODO 1455 10. Security Considerations 1457 TODO 1459 11. References 1461 11.1. Normative References 1463 [I-D.arias-noguchi-dnrd-objects-mapping] 1464 Lozano, G., Gould, J., and C. Thippeswamy, "Domain Name 1465 Registration Data (DNRD) Objects Mapping", draft-arias- 1466 noguchi-dnrd-objects-mapping-09 (work in progress), June 1467 2018. 1469 [ICANN-GTLD-BASE-RA] 1470 ICANN, "gTLD Base Registry Agreement", Jan 2014, 1471 . 1474 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1475 Requirement Levels", BCP 14, RFC 2119, 1476 DOI 10.17487/RFC2119, March 1997, 1477 . 1479 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 1480 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 1481 . 1483 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1484 DOI 10.17487/RFC3688, January 2004, 1485 . 1487 11.2. Informative References 1489 [RFC5890] Klensin, J., "Internationalized Domain Names for 1490 Applications (IDNA): Definitions and Document Framework", 1491 RFC 5890, DOI 10.17487/RFC5890, August 2010, 1492 . 1494 [RFC5891] Klensin, J., "Internationalized Domain Names in 1495 Applications (IDNA): Protocol", RFC 5891, 1496 DOI 10.17487/RFC5891, August 2010, 1497 . 1499 Authors' Addresses 1501 Gustavo Lozano 1502 ICANN 1503 12025 Waterfront Drive, Suite 300 1504 Los Angeles 90292 1505 US 1507 Phone: +1.3103015800 1508 Email: gustavo.lozano@icann.org 1510 Eduardo Alvarez 1511 ICANN 1512 12025 Waterfront Drive, Suite 300 1513 Los Angeles 90292 1514 US 1516 Phone: +1.3103015800 1517 Email: eduardo.alvarez@icann.org