idnits 2.17.1 draft-lozano-icann-registry-interfaces-11.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 23, 2019) is 1677 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: '1-9' is mentioned on line 1247, but not defined -- Looks like a reference, but probably isn't: '012' on line 1247 -- Looks like a reference, but probably isn't: '12' on line 1247 == Missing Reference: '0-9' is mentioned on line 1247, but not defined -- Looks like a reference, but probably isn't: '01' on line 1247 == Unused Reference: 'RFC3688' is defined on line 1493, but no explicit reference was found in the text == Unused Reference: 'RFC5891' is defined on line 1504, 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: March 26, 2020 September 23, 2019 7 ICANN Registry Interfaces 8 draft-lozano-icann-registry-interfaces-11 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 26, 2020. 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 8.12. Version 11 . . . . . . . . . . . . . . . . . . . . . . . 35 95 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 35 96 10. Security Considerations . . . . . . . . . . . . . . . . . . . 35 97 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 35 98 11.1. Normative References . . . . . . . . . . . . . . . . . . 35 99 11.2. Informative References . . . . . . . . . . . . . . . . . 36 100 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 36 102 1. Introduction 104 This document describes the technical details of the interfaces 105 provided by the Internet Corporation for Assigned Names and Numbers 106 (ICANN) to other contracted parties in order to fulfill reporting 107 requirements. The interface provided by ICANN to Registry Operators 108 and Data Escrow Agents in order to fulfill the requirements of 109 Specifications 2 and 3 of the gTLD Base Registry Agreement 110 [ICANN-GTLD-BASE-RA] are also described in this document. 112 1.1. Terminology 114 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 115 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 116 document are to be interpreted as described in RFC 2119 [RFC2119]. 118 XML is case sensitive. Unless stated otherwise, XML specifications 119 and examples provided in this document MUST be interpreted in the 120 character case presented in order to develop a conforming 121 implementation. 123 1.2. Date and Time 125 Numerous fields indicate "date and time", such as the creation and 126 receipt dates for data escrow deposits. These fields SHALL contain 127 timestamps indicating the date and time in UTC as specified in 128 [RFC3339], with no offset from the zero meridian. 130 1.3. Object Description 132 This section describes the base objects supported by this 133 specification. 135 1.3.1. object 137 The ICANN interfaces for registries and data escrow agents (IIRDEA) 138 object is used to provide information on the result 139 of a verification process when interacting with the interfaces. 141 The object contains the following attribute and child 142 elements: 144 o A "code" attribute whose value is a four-digit decimal number that 145 identifies the result of a process. Available result code values 146 MUST be defined for the corresponding process. 148 o An OPTIONAL "domainCount" attribute to indicate the number of 149 domain names related to the reported result. 151 o A element containing a human-readable description of the 152 result code. 154 o An OPTIONAL element that includes additional details 155 on the result conditions. 157 An example of a object is presented below: 159 160 The structure of the report is invalid. 161 162 'XX' could not be parsed as a number (line: 2 column:3) 163 164 166 1.3.2. object 168 The contents of a data escrow deposit are described using a 169 object. The object contains 170 the following child elements: 172 o An element that contains the identifier assigned to this 173 report. The report identifier MUST be the same as the "id" 174 attribute from the . If the data escrow deposit does not 175 include a unique identifer, the Data Escrow Agent MUST generate a 176 unique identifier to reference the data escrow deposit and use it 177 in the element. 179 o A element contains the version of the specification 180 used. This value MUST be 1. 182 o A element contains the version of the Data Escrow 183 Specification (e.g. draft-arias-noguchi-registry-data-escrow-06) 184 used to create the deposit. After the specification is published 185 as an RFC, the value MUST be the RFC number assigned by IANA. 187 o An OPTIONAL element contains the version of the 188 Domain Name Registration Data (DNRD) Objects Mapping (e.g. draft- 189 arias-noguchi-dnrd-objects-mapping-05) used to create the deposit. 190 After the specification is published as an RFC, the value MUST be 191 the RFC number assigned by IANA. The element 192 MUST be included if the deposit was created using any version of 193 the DNRD objects mapping specification (see, 194 [I-D.arias-noguchi-dnrd-objects-mapping]). 196 o A element contains the value of the "resend" attribute of 197 the . 199 o A element contains the date and time that the deposit was 200 created by the Registry Operator. 202 o A element is used to identify the kind of deposit: FULL, 203 INCR (Incremental) or DIFF (Differential). 205 o A element contains the date and time corresponding to 206 the Timeline Watermark ( element) of the . 208 o A element contains the header of the 209 as defined in [I-D.arias-noguchi-dnrd-objects-mapping] 211 An example of a object is available in 212 Section 2.1. 214 1.3.3. object 216 The object is used by Data Escrow 217 Agents to document the result of the data escrow deposit verification 218 process. The object contains the 219 following child elements: 221 o A element contains the name of the Data Escrow Agent. 223 o A element contains the version of the specification 224 used. This value MUST be 1. 226 o A element contains the reported date. In case of a DVPN 227 or DVFN notification this value MUST be the date of the 228 element of the . In case of a DRFN deposit 229 notification, this value MUST be the date for which no deposit was 230 received from the Registrar or Registry Operator. 232 o A element is used to specify the status of . 233 The possible values of status are: DVPN, DVFN and DRFN. The value 234 for the element is determined by the three types of 235 notices: 237 * Deposit Receipt Failure Notice (DRFN): generated by the Data 238 Escrow Agent when no deposit is received pursuant to the data 239 escrow deposit schedule. 241 * Deposit Verification Failure Notice (DVFN): generated by the 242 Data Escrow Agent when a deposit is received, but the final 243 result of the verification process is failure. 245 * Deposit Verification Pass Notice (DVPN): generated by the Data 246 Escrow Agent when a deposit is received and the final result of 247 the verification process is success. 249 o An OPTIONAL element contains the errors detected during 250 the data escrow deposit verification process performed by the Data 251 Escrow Agent. The element includes one or more 252 elements as defined in Section 1.3.1. In case of 253 a DRFN or DVPN deposit notification the element MUST NOT 254 be present. 256 o An OPTIONAL element contains the date and time that the 257 deposit was successfully received by the Data Escrow Agent. In 258 case of a DRFN deposit notification this element MUST NOT be 259 present. 261 o An OPTIONAL element contains the date and time that the 262 deposit was processed for validation by the Data Escrow Agent. In 263 case of a DRFN deposit notification this element MUST NOT be 264 present. 266 o An OPTIONAL element contains the date of the 267 Timeline Watermark ( element) of the most recent FULL 268 deposit that was successfully validated by the Data Escrow Agent. 269 This element MUST NOT be present if a successfully validated full 270 deposit has never been deposited. 272 o An OPTIONAL element is used by the Data Escrow 273 Agent to provide extended information about the deposit. In case 274 of a DRFN deposit notification this element MUST NOT be present. 275 In case of a DVPN or DVFN deposit notification this element MUST 276 be present. When this element is present, the 277 element MUST be generated by the Data Escrow Agent for the 278 Timeline Watermark ( element) of the deposit being 279 processed. If the deposit being processed is a differential or 280 incremental deposit, the Data Escrow Agent MUST process the last 281 full plus all differentials or last full plus last incremental 282 escrow deposits from the same repository (e.g. TLD) to generate 283 the element. 285 o Note: In case of a DVPN or DVFN deposit notification, the is 286 used as unique identifier. 288 An example of a object is available in 289 Section 2.2. 291 1.3.4. Object 293 Interfaces that support monitoring the reporting status for a 294 specific repository, provide a object as 295 defined by the schema in Section 6 in the HTTP Entity-body when a 296 HTTP/200 code is sent by the interface. 298 The element includes the following child 299 elements: 301 o A choice of one of the elements as defined in the 302 "rdeHeader:repositoryTypeGroup" (see 303 [I-D.arias-noguchi-dnrd-objects-mapping]) that indicates the 304 unique identifier for the repository being escrowed. 306 o A element with the date and time in which the 307 queried repository was created in the system. 309 o A OPTIONAL element indicating the current Data 310 Escrow Deposit schedule for the queried repository. Possible 311 values are "None", "Weekly", and "Daily". 313 o An OPTIONAL element indicating the date of the 314 Timeline Watermark ( element) of the most recent FULL 315 deposit that was successfully validated for the queried repository 316 as notified by the Data Escrow Agent. 318 o A element with a element for each 319 report type for the queried repository. Each 320 element includes the following child elements: 322 * : a string value indicating the report type to which the 323 information provided pertains. 325 * : a boolean value indicating if the report type is 326 enabled for the repository. 328 * : a string value indicating the reporting status. A 329 value of "ok" indicates there are no reporting issues in the 330 corresponding report type, otherwise the value of 331 "unsatisfactory" is shown. 333 * An OPTIONAL element included only when the 334 element has a value of "unsatisfactory", and includes an empty 335 element for each date with a reporting problem found in 336 the corresponding report type. Each element includes a 337 REQUIRED "date" attribute in "YYYY-MM-DD" format and a REQUIRED 338 "description" attribute to describe the issue. The possible 339 values to describe each reporting issue are: 341 + "Missing_Deposit_Full": If the latest notification received 342 from the Data Escrow Agent for the date indicates that a 343 scheduled "Full" deposit was not submitted by the repository 344 owner. 346 + "Missing_Deposit_Diff": If the latest notification received 347 from the Data Escrow Agent for the date indicates that a 348 scheduled "Differential" deposit was not submitted by the 349 repository owner. 351 + "Invalid_Deposit_Full": If the latest notification received 352 from the Data Escrow Agent for the date indicates that a 353 "Full" deposit was received by the Data Escrow Agent, but 354 failed the verification process. 356 + "Invalid_Deposit_Diff": If the latest notification received 357 from the Data Escrow Agent for the date indicates that a 358 "Differential" deposit was received by the Data Escrow 359 Agent, but failed the verification process. 361 + "No_Report_Received" If no report has been received for the 362 date. 364 o A element to indicate the date and time in which the 365 reporting status response was created. 367 1.3.5. Object 369 Interfaces that support monitoring and retrieving Data Escrow Reports 370 received, provide a object as defined by the 371 schema in Section 6 in the HTTP Entity-body when a HTTP/200 code is 372 sent by the interface. 374 The element includes a list of 375 objects, one for each 376 successfully received by ICANN. Each 377 object includes the following child elements: 379 o A element to indicate the date and time in which the 380 report was received by ICANN. 382 o A element as defined in Section 1.3.2 as 383 received by ICANN. 385 1.3.6. Object 387 Interfaces that support monitoring and retrieving Data Escrow 388 Notifications received from Data Escrow Agents, provide a 389 object as defined by the schema in 390 Section 6 in the HTTP Entity-body when a HTTP/200 code is sent by the 391 interface. 393 The element includes a list of 394 objects, one for each 395 successfully received by ICANN. Each 396 object includes the following 397 child elements: 399 o A element to indicate the date and time in which the 400 notification was received by ICANN. 402 o A element as defined in 403 Section 1.3.3 as received by ICANN. 405 2. Interfaces for Specification 2 - Data Escrow Reporting 407 This section describes the interfaces provided by ICANN to Registry 408 Operators and Data Escrow Agents in order to fulfill the reporting 409 requirements detailed in Specification 2 of the gTLD Base Registry 410 Agreement [ICANN-GTLD-BASE-RA]. 412 2.1. Registry Operator Reporting 414 The gTLD Base Registry Agreement [ICANN-GTLD-BASE-RA], Specification 415 2, Part A, Section 7 requires Registry Operators to provide ICANN 416 with a written statement that includes a copy of the report generated 417 upon creation of a deposit and a statement that the deposit has been 418 inspected by the Registry Operator and is complete and accurate. 420 In order to satisfy this requirement, the Registry Operator sends to 421 ICANN a object as defined in Section 1.3.2 for 422 each deposit successfully sent to the Data Escrow Agent, using the 423 PUT HTTP verb in the interface provided by ICANN at: 425 https://ry-api.icann.org/report/registry-escrow-report// 427 Where: 429 * MUST be substituted by the TLD for which the report is 430 being provided. In case of an IDN TLD, the A-label (see 431 [RFC5890]) MUST be used. 433 * MUST be substituted by the identifier assigned to this 434 report, which MUST be the same as the "id" attribute from the 435 . 437 Note: the interface supports overwriting the information of a 438 particular report to support asynchronous interfaces between 439 Registry Operators and Data Escrow Agents. 441 Example of a object for a data escrow deposit 442 corresponding to a TLD Registry repository: 444 445 448 20101017001 449 1 450 451 draft-arias-noguchi-registry-data-escrow-06 452 453 454 draft-arias-noguchi-dnrd-objects-mapping-05 455 456 0 457 2010-10-17T00:15:00.0Z 458 FULL 459 2010-10-17T00:00:00Z 460 461 test 462 2 464 1 466 1 468 1 470 471 1 473 1 475 1 477 478 479 481 2.2. Data Escrow Agent Reporting 483 The gTLD Base Registry Agreement [ICANN-GTLD-BASE-RA], Specification 484 2, Part B, Section 7 requires Data Escrow Agents, to deliver ICANN 485 with a notification object every time a successfully processed 486 deposit is received from the Registry Operator regardless of the 487 final status of the verification process. 489 In order to satisfy this requirement, the Data Escrow Agent sends to 490 ICANN a object as defined in 491 Section 1.3.3, using the POST HTTP verb in the interface provided by 492 ICANN at: 494 https://ry-api.icann.org/report/escrow-agent-notification/ 496 Where: 498 * MUST be substituted by the TLD for which the notification 499 is being provided. In case of an IDN TLD, the A-label (see 500 [RFC5890]) MUST be used. 502 If by 23:59:59 UTC, a deposit has not been successfully processed 503 regardless of the final status of the verification process, a 504 object with DRFN status MUST be send 505 to ICANN. 507 Example of a object of a Data Escrow 508 Agent notification corresponding to a Registry repository Data Escrow 509 Deposit: 511 512 516 Escrow Agent Inc. 517 1 518 2010-10-17 519 DVPN 520 521 2010-10-17T03:15:00.0Z 522 523 524 2010-10-17T05:15:00.0Z 525 526 527 2010-10-14 528 529 530 20101017001 531 1 532 533 draft-arias-noguchi-registry-data-escrow-06 534 535 536 draft-arias-noguchi-dnrd-objects-mapping-03 537 538 0 539 2010-10-17T00:15:00.0Z 540 FULL 541 2010-10-17T00:00:00Z 542 543 test 544 1 546 3 548 1 550 3 552 1 554 10 556 0 558 559 560 562 3. Interfaces of Specification 3 - Registry Operator Monthly Reporting 564 Specification 3 of the gTLD Base Registry Agreement 565 [ICANN-GTLD-BASE-RA] requires Registry Operators to provide a set of 566 monthly reports per gTLD. Two type of reports are required to be 567 sent by Registries: Per-Registrar Transactions Report and Registry 568 Functions Activity Report. This section specifies the interfaces 569 provided by ICANN to automate the upload of these reports by Registry 570 Operators. 572 The cut-off date for the reception of the reports specified in 573 specification 3 is defined in the gTLD Base Registry Agreement 574 [ICANN-GTLD-BASE-RA]. Before the cut-off date the Registry Operator 575 could replace a successfully validated report as many times as it 576 needs. 578 3.1. Per-Registrar Transactions Report 580 The Per-Registrar Transactions Report is a CSV report described in 581 Section 1 of Specification 3. 583 In order to satisfy this requirement, the Registry Operator sends a 584 CSV report on a monthly basis as described in the gTLD Base Registry 585 Agreement [ICANN-GTLD-BASE-RA], using the PUT HTTP verb in the 586 interface provided by ICANN at: 588 https://ry-api.icann.org/report/registrar- 589 transactions// 591 Where: 593 * MUST be substituted by the TLD for which the reports is 594 being provided. In case of an IDN TLD, the A-label (see 595 [RFC5890]) MUST be used. 597 * MUST be substituted by the month for which the reports 598 is being provided in the form of YYYY-MM. Where 'YYYY' is the 599 year and 'MM' is the two digit month number. For example: 600 2013-03 602 3.2. Registry Functions Activity Report 604 The Registry Functions Activity Report is a CSV report described in 605 Section 2 of Specification 3 of the gTLD Base Registry Agreement 606 [ICANN-GTLD-BASE-RA]. 608 In order to satisfy this requirement, the Registry Operator sends a 609 CSV report on a monthly basis as described in the gTLD Base Registry 610 Agreement [ICANN-GTLD-BASE-RA], using the PUT HTTP verb in the 611 interface provided by ICANN at: 613 https://ry-api.icann.org/report/registry-functions- 614 activity// 616 Where: 618 * MUST be substituted by the TLD for which the report is 619 being provided. In case of an IDN TLD, the A-label (see 620 [RFC5890]) MUST be used. 622 * MUST be substituted by the month for which the reports 623 is being provided in the form of YYYY-MM. Where 'YYYY' is the 624 year and 'MM' is the two digit month number. For example: 625 2013-03 627 4. Technical details of the interfaces 629 Content-type value in the HTTP header: 631 o The client MUST set "text/xml" in the HTTP header Content-type 632 when using the Data Escrow Agent Reporting and Registry Operator 633 Reporting interfaces described in Section 2. 635 o The client MUST set "text/csv" in the HTTP header Content-type 636 when using the Per-Registrar Transactions Report Registry 637 Functions Activity Report interfaces described in Section 3. 639 The interfaces support HTTP streams only (HTTP multi-part forms are 640 not supported). 642 After successfully receiving an input in any of the interfaces, ICANN 643 validates it and provides a object with an result element 644 in the same HTTP transaction. 646 The following HTTP status codes are standard across all interfaces: 648 o The interface provides a HTTP/200 status code and sets the HTTP 649 header Content-type: text/xml, if the interface was able to 650 receive the input sucessfully, the client MUST review the response 651 object to verify the result code after processing the input. 653 o The interface provides a HTTP/400 status code and sets the HTTP 654 header Content-type: text/xml, if the input is incorrect or the 655 syntax of the input is invalid. A response object is included 656 with the input validation failure details. 658 o The interface provides a HTTP/401 status code and sets the HTTP 659 header Content-type: text/plain, if the credentials provided does 660 not authorize the Registry Operator to upload a report for that 661 . 663 o The interface provides a HTTP/403 status code and sets the HTTP 664 header Content-type: text/plain, if the credentials provided are 665 valid but are being used to access a resource that permission is 666 not granted for or the connecting IP address is not whitelisted 667 for the . 669 o The interface provides a HTTP/405 status code if the interface 670 does not support the request method. 672 o The interface provides a HTTP/500 status code and sets the HTTP 673 header Content-type: text/plain, if the system is experiencing a 674 general failure. The sending party is responsible to send the 675 input again. 677 o The interface provides a HTTP/501 status code and sets the HTTP 678 header Content-type: text/plain, if the functionality has not yet 679 been implemented. 681 After sending the response, the interfaces closes the TCP connection. 683 4.1. Response Object 685 After processing the input provided in any of the interfaces, a 686 response object as defined by the schema in Section 6 is provided in 687 the HTTP Entity-body when an HTTP/200 or HTTP/400 status code is sent 688 by the interface. 690 An example of a response object upon successful input receipt is 691 presented below: 693 HTTP/1.1 200 OK 694 Content-Type: text/xml 695 Content-Length: 248 697 698 699 700 No ERRORs were found and the report has been 701 accepted by ICANN. 702 703 704 706 An example of a response object in the event of input error is 707 presented below: 709 HTTP/1.1 400 Bad Request 710 Content-Type: text/xml 711 Content-Length: 279 713 714 715 716 The structure of the report is invalid. 717 718 'XX' could not be parsed as a number (line: 2 column:3) 719 720 721 723 The following sections provide the IIRDEA Result Codes per interface: 725 4.1.1. Registry Operator Reporting 727 The following table lists the result codes of the interface: 729 +--------+----------------------------------------------------------+ 730 | Result | Message | 731 | Code | | 732 +--------+----------------------------------------------------------+ 733 | 1000 | No ERRORs were found and the report has been accepted by | 734 | | ICANN. | 735 | 2001 | The request did not validate against the schema. | 736 | 2004 | Report for a date in the future. The and | 737 | | date should not be in the future. | 738 | 2005 | Version is not supported. | 739 | 2006 | The in the element and the in the URL | 740 | | path do not match. | 741 | 2007 | Interface is disabled for this TLD. | 742 | 2008 | The and date should not be before | 743 | | the creation date of the TLD in the system. | 744 | 2202 | The in the
and the TLD in the URL path do | 745 | | not match. | 746 | 2205 | Report regarding a differential deposit received for a | 747 | | Sunday (). | 748 | 2206 | csvDomain and rdeDomain count provided in the
. | 749 | 2209 | Missing required element in the
. | 750 | 2210 | The value of the "rcdn" attribute in the element | 751 | | does not match the same or lower level names in the | 752 | | in the URL path. | 753 | 2211 | Multiple count elements with the same "uri", "rcdn", and | 754 | | "registrarId" attribute values provided in the
. | 755 | 2212 | An invalid NR-LDH label or A-label was found or the | 756 | | domain name syntax is invalid in the "rcdn" attribute. | 757 +--------+----------------------------------------------------------+ 759 Data Escrow Reporting Result Codes 761 4.1.2. Data Escrow Agent Reporting 763 The following table lists the result codes of the interface: 765 +--------+----------------------------------------------------------+ 766 | Result | Message | 767 | Code | | 768 +--------+----------------------------------------------------------+ 769 | 1000 | No ERRORs were found and the notification has been | 770 | | accepted by ICANN. | 771 | 2001 | The request did not validate against the schema. | 772 | 2002 | A DVPN notification exists for that date (). | 773 | 2004 | Notification for a date in the future. The and | 774 | | and date should not be in the | 775 | | future. | 776 | 2005 | Version is not supported. | 777 | 2007 | Interface is disabled for this TLD. | 778 | 2008 | The and and date should | 779 | | not be before the creation date of the TLD in the | 780 | | system. | 781 | 2201 | The and in the notification do not | 782 | | match. | 783 | 2202 | The in the
and the TLD in the URL path do | 784 | | not match. | 785 | 2203 | A Deposit Verification Pass Notice (DVPN) notification | 786 | | was received, but the Domain Name count is missing in | 787 | | the
. | 788 | 2204 | The notification for the report "id" already exists. | 789 | 2205 | Notification regarding a differential deposit received | 790 | | for a Sunday (). | 791 | 2206 | csvDomain and rdeDomain count provided in the
. | 792 | 2207 | A DVPN or DVFN was received, but the element is | 793 | | missing in the notification. | 794 | 2208 | A DRFN was received, but a element exists in | 795 | | the notification. | 796 | 2209 | Missing required element in the
. | 797 | 2210 | The value of the "rcdn" attribute in the element | 798 | | does not match the same or lower level names in the | 799 | | in the URL path. | 800 | 2211 | Multiple count elements with the same "uri", "rcdn", and | 801 | | "registrarId" attribute values provided in the
. | 802 | 2212 | An invalid NR-LDH label or A-label was found or the | 803 | | domain name syntax is invalid in the "rcdn" attribute. | 804 +--------+----------------------------------------------------------+ 806 Data Escrow Reporting Result Codes 808 4.1.3. Per-Registrar Transactions Report 810 The following table lists the result codes of the interface: 812 +----------+--------------------------------------------------------+ 813 | Result | Message | 814 | Code | | 815 +----------+--------------------------------------------------------+ 816 | 1000 | No ERRORs were found and the report has been accepted | 817 | | by ICANN. | 818 | 2001 | The structure of the report is invalid. | 819 | 2002 | A report for that month already exists, the cut-off | 820 | | date already passed. | 821 | 2003 | Negative numeric value present in the report. | 822 | 2004 | Report for a month in the future. | 823 | 2007 | Interface is disabled for this TLD. | 824 | 2008 | Reported month before the creation date of the TLD in | 825 | | the system. | 826 | 2101 | Incorrect totals present in the report. | 827 | 2102 | A non ICANN-accredited registrar is present in the | 828 | | report. | 829 | 2103 | Values found in the second field of the totals line. | 830 | 2105 | The report is not encoded in UTF-8. Note: reports | 831 | | encoded in US-ASCII are accepted. | 832 +----------+--------------------------------------------------------+ 834 Per-Registrar Transactions Report Result Codes 836 4.1.4. Registry Functions Activity Report 838 The following table lists the result codes of the interface: 840 +----------+--------------------------------------------------------+ 841 | Result | Message | 842 | Code | | 843 +----------+--------------------------------------------------------+ 844 | 1000 | No ERRORs were found and the report has been accepted | 845 | | by ICANN. | 846 | 2001 | The structure of the report is invalid. | 847 | 2002 | A report for that month already exists, the cut-off | 848 | | date already passed. | 849 | 2003 | Negative numeric value present in the report. | 850 | 2004 | Report for a month in the future. | 851 | 2007 | Interface is disabled for this TLD. | 852 | 2008 | Reported month before the creation date of the TLD in | 853 | | the system. | 854 | 2105 | The report is not encoded in UTF-8. Note: reports | 855 | | encoded in US-ASCII are accepted. | 856 +----------+--------------------------------------------------------+ 858 Registry Functions Activity Report Result Codes 860 5. Monitoring the reporting status 862 Registries MAY monitor the status of the reports described in 863 Specification 2 and Specification 3 of the gTLD Base Registry 864 Agreement [ICANN-GTLD-BASE-RA] using the following interfaces that 865 supports the HEAD HTTP verb: 867 5.1. Monitoring the status of Data Escrow Reports 869 Registries MAY monitor the status of Data Escrow Reports using the 870 following interface: 872 https://ry-api.icann.org/info/report/registry-escrow- 873 report// 875 Where: 877 * MUST be substituted by the TLD being queried. In case of 878 an IDN TLD, the A-label (see [RFC5890]) MUST be used. 880 * MUST be substituted by the day being queried. For 881 example: 2013-03-02 883 Possible results are: 885 * The interface provides a HTTP/200 status code, if a 886 syntactically valid data escrow report was received for the 887 queried date. 889 * The interface provides a HTTP/404 status code, if a 890 syntactically valid data escrow report has not been received 891 for the queried date. 893 5.2. Monitoring the status of Data Escrow Notifications 895 Registries and Data Escrow Agents MAY monitor the status of Data 896 Escrow Notifications using the following interface: 898 https://ry-api.icann.org/info/report/escrow-agent- 899 notification// 901 Where: 903 * MUST be substituted by the TLD being queried. In case of 904 an IDN TLD, the A-label (see [RFC5890]) MUST be used. 906 * MUST be substituted by the day being queried. For 907 example: 2013-03-02 909 Possible results are: 911 * The interface provides a HTTP/200 status code, if a 912 syntactically valid data escrow notification was received for 913 the queried date. 915 * The interface provides a HTTP/404 status code, if a 916 syntactically valid data escrow notification has not been 917 received for the queried date. 919 5.3. Monitoring the status of Registry Functions Activity Report 921 Registries MAY monitor the status of Registry Functions Activity 922 Report using the following interface: 924 https://ry-api.icann.org/info/report/registry-functions- 925 activity// 927 Where: 929 * MUST be substituted by the TLD being queried. In case of 930 an IDN TLD, the A-label (see [RFC5890]) MUST be used. 932 * MUST be substituted by the month being queried. For 933 example: 2013-03 935 Possible results are: 937 * The interface provides a HTTP/200 status code, if a 938 syntactically valid registry functions activity report was 939 received for the queried month. 941 * The interface provides a HTTP/404 status code, if a 942 syntactically valid registry functions activity report has not 943 been received for the queried month. 945 5.4. Monitoring the status of the Per-Registrar Transactions Report 947 Registries MAY monitor the status of Per-Registrar Transactions 948 Report using the following interface: 950 https://ry-api.icann.org/info/report/registrar- 951 transactions// 953 Where: 955 * MUST be substituted by the TLD being queried. In case of 956 an IDN TLD, the A-label (see [RFC5890]) MUST be used. 958 * MUST be substituted by the month being queried. For 959 example: 2013-03 961 Possible results are: 963 * The interface provides a HTTP/200 status code, if a 964 syntactically valid per-registrar transactions report was 965 received for the queried month. 967 * The interface provides a HTTP/404 status code, if a 968 syntactically valid per-registrar transactions report has not 969 been received for the queried month. 971 6. Formal Syntax 973 The schema of the IIRDEA Result, Report, Notification, RRI Reporting, 974 Notifications, and Reports objects described in Section 1.3 are 975 presented here. 977 The BEGIN and END tags are not part of the schema; they are used to 978 note the beginning and ending of the schema for URI registration 979 purposes. 981 6.1. IIRDEA Result Schema 983 Copyright (c) 2017 IETF Trust and the persons identified as authors 984 of the code. All rights reserved. 986 Redistribution and use in source and binary forms, with or without 987 modification, is permitted pursuant to, and subject to the license 988 terms contained in, the Simplified BSD License set forth in 989 Section 4.c of the IETF Trust's Legal Provisions Relating to IETF 990 Documents (http://trustee.ietf.org/license-info). 991 BEGIN 992 993 998 999 1000 ICANN interfaces for registries and data escrow agents 1001 1002 1004 1005 1007 1008 1009 1010 1011 1013 1014 1015 1016 1018 1019 1021 1022 1024 1025 1026 1027 1028 1029 1031 1032 END 1034 6.2. Report Object 1036 Copyright (c) 2017 IETF Trust and the persons identified as authors 1037 of the code. All rights reserved. 1039 Redistribution and use in source and binary forms, with or without 1040 modification, is permitted pursuant to, and subject to the license 1041 terms contained in, the Simplified BSD License set forth in 1042 Section 4.c of the IETF Trust's Legal Provisions Relating to IETF 1043 Documents (http://trustee.ietf.org/license-info). 1045 BEGIN 1046 1047 1054 1055 1057 1058 1059 Data Escrow Report schema 1060 1061 1063 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 END 1081 6.3. Notification Object 1083 Copyright (c) 2017 IETF Trust and the persons identified as authors 1084 of the code. All rights reserved. 1086 Redistribution and use in source and binary forms, with or without 1087 modification, is permitted pursuant to, and subject to the license 1088 terms contained in, the Simplified BSD License set forth in 1089 Section 4.c of the IETF Trust's Legal Provisions Relating to IETF 1090 Documents (http://trustee.ietf.org/license-info). 1092 BEGIN 1093 1094 1101 1102 1104 1105 1106 Data Escrow Notification schema 1107 1108 1110 1113 1114 1115 1116 1117 1118 1119 1121 1122 1123 1124 1125 1126 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1140 1141 1142 1143 1144 1145 1146 1147 1148 END 1150 6.4. RRI Reporting Summary Object 1152 Copyright (c) 2018 IETF Trust and the persons identified as authors 1153 of the code. All rights reserved. 1155 Redistribution and use in source and binary forms, with or without 1156 modification, is permitted pursuant to, and subject to the license 1157 terms contained in, the Simplified BSD License set forth in 1158 Section 4.c of the IETF Trust's Legal Provisions Relating to IETF 1159 Documents (http://trustee.ietf.org/license-info). 1161 BEGIN 1162 1163 1169 1171 1173 1174 1175 1176 1177 1179 1180 1183 1184 1185 1187 1188 1189 1190 1191 1192 1193 1195 1196 1197 1199 1200 1202 1203 1204 1205 1206 1207 1209 1210 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1224 1225 1226 1227 1228 1229 1230 1231 1232 1234 1235 1237 1238 1240 1242 1244 1245 1246 1248 1249 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 END 1263 6.5. Notifications Object 1265 Copyright (c) 2018 IETF Trust and the persons identified as authors 1266 of the code. All rights reserved. 1268 Redistribution and use in source and binary forms, with or without 1269 modification, is permitted pursuant to, and subject to the license 1270 terms contained in, the Simplified BSD License set forth in 1271 Section 4.c of the IETF Trust's Legal Provisions Relating to IETF 1272 Documents (http://trustee.ietf.org/license-info). 1273 BEGIN 1274 1275 1281 1283 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 END 1301 6.6. Reports Object 1303 Copyright (c) 2018 IETF Trust and the persons identified as authors 1304 of the code. All rights reserved. 1306 Redistribution and use in source and binary forms, with or without 1307 modification, is permitted pursuant to, and subject to the license 1308 terms contained in, the Simplified BSD License set forth in 1309 Section 4.c of the IETF Trust's Legal Provisions Relating to IETF 1310 Documents (http://trustee.ietf.org/license-info). 1311 BEGIN 1312 1313 1319 1321 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 END 1338 7. Acknowledgements 1340 Special suggestions that have been incorporated into this document 1341 were provided by David Kipling, James Gould, Gregory Zaltsman, Brett 1342 Carr and Harel Efraim. 1344 8. Change History 1346 [[RFC Editor: Please remove this section.]] 1348 8.1. Version 00 1350 Initial version. 1352 8.2. Version 01 1354 o and moved from 1355 escrow drafts to this draft 1357 o Added to 1358 o element of is now OPTIONAL 1360 o Added element to 1362 o and added to the draft 1364 o Several report elements are OPTIONAL to support async interfaces 1365 between Registry Operators and Data Escrow Agents 1367 o Added and to registry-escrow-report interface in order 1368 to make the interface idempotent and support async RyO-DEA 1369 interfaces 1371 o Added to escrow-agent-notification interface 1373 o The escrow-agent-notification uses POST and not PUT, this has been 1374 fixed 1376 o Several clarifications 1378 8.3. Version 02 1380 o Added and updated several result codes. 1382 o Added element. 1384 o Added Content-type definition. 1386 8.4. Version 03 1388 o Added several result codes. 1390 o unsignedShort is now used for result code in iirdea schema. 1392 o Enumeration was removed from the iirdea schema. 1394 8.5. Version 04 1396 o Added result codes: 2207 and 2208. 1398 o Removed result codes: 2203. 1400 o Added clarification regarding the support of HTTP streams. 1402 8.6. Version 05 1404 o Added result codes: 2007 and 2008. 1406 8.7. Version 06 1408 o Added clarification of error code HTTP/403 in Section 4. 1410 8.8. Version 07 1412 o Added Section 5: "Monitoring compliance with the New gTLD Base 1413 Agreement". 1415 8.9. Version 08 1417 o Reorganized specification structure to allow easier references 1418 from new specifications expanding functionality in the ICANN 1419 Registry Interfaces. 1421 o Added Section 1.3 to document object definitions, previously 1422 defined in other sections. 1424 o Added , , and object 1425 descriptions to Section 1.3, and schema definitions to Section 6. 1427 o Renamed Section 5 title as "Monitoring the reporting status". 1429 o Updated element as OPTIONAL in the 1430 schema. 1432 o Added OPTIONAL attribute "domainCount" to the 1433 element. 1435 o Added OPTIONAL element to the schema. 1437 o Added result codes: 2105, 2209, 2210 and 2211. 1439 o Added "gTLD Base Registry Agreement" references. 1441 o Added clarifications to Section 4. 1443 8.10. Version 09 1445 o Standardized XSD schema validation error message for notifications 1446 and reports. 1448 o Element made optional in the schema. 1450 o Separated example RRI interface responses for successful and 1451 unsuccessful input. 1453 8.11. Version 10 1455 1. Ping update. 1457 8.12. Version 11 1459 1. Ping update. 1461 9. IANA Considerations 1463 TODO 1465 10. Security Considerations 1467 TODO 1469 11. References 1471 11.1. Normative References 1473 [I-D.arias-noguchi-dnrd-objects-mapping] 1474 Lozano, G., Gould, J., and C. Thippeswamy, "Domain Name 1475 Registration Data (DNRD) Objects Mapping", draft-arias- 1476 noguchi-dnrd-objects-mapping-10 (work in progress), 1477 January 2019. 1479 [ICANN-GTLD-BASE-RA] 1480 ICANN, "gTLD Base Registry Agreement", Jan 2014, 1481 . 1484 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1485 Requirement Levels", BCP 14, RFC 2119, 1486 DOI 10.17487/RFC2119, March 1997, 1487 . 1489 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 1490 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 1491 . 1493 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1494 DOI 10.17487/RFC3688, January 2004, 1495 . 1497 11.2. Informative References 1499 [RFC5890] Klensin, J., "Internationalized Domain Names for 1500 Applications (IDNA): Definitions and Document Framework", 1501 RFC 5890, DOI 10.17487/RFC5890, August 2010, 1502 . 1504 [RFC5891] Klensin, J., "Internationalized Domain Names in 1505 Applications (IDNA): Protocol", RFC 5891, 1506 DOI 10.17487/RFC5891, August 2010, 1507 . 1509 Authors' Addresses 1511 Gustavo Lozano 1512 ICANN 1513 12025 Waterfront Drive, Suite 300 1514 Los Angeles 90292 1515 US 1517 Phone: +1.3103015800 1518 Email: gustavo.lozano@icann.org 1520 Eduardo Alvarez 1521 ICANN 1522 12025 Waterfront Drive, Suite 300 1523 Los Angeles 90292 1524 US 1526 Phone: +1.3103015800 1527 Email: eduardo.alvarez@icann.org