idnits 2.17.1 draft-lozano-icann-registry-interfaces-12.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 26, 2020) is 1491 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: '1-9' is mentioned on line 1248, but not defined -- Looks like a reference, but probably isn't: '012' on line 1248 -- Looks like a reference, but probably isn't: '12' on line 1248 == Missing Reference: '0-9' is mentioned on line 1248, but not defined -- Looks like a reference, but probably isn't: '01' on line 1248 == Unused Reference: 'RFC3688' is defined on line 1498, but no explicit reference was found in the text == Unused Reference: 'RFC5891' is defined on line 1509, but no explicit reference was found in the text Summary: 0 errors (**), 0 flaws (~~), 5 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force G. Lozano 3 Internet-Draft E. Alvarez 4 Intended status: Informational ICANN 5 Expires: September 27, 2020 March 26, 2020 7 ICANN Registry Interfaces 8 draft-lozano-icann-registry-interfaces-12 10 Abstract 12 This document describes the technical details of the interfaces 13 provided by the Internet Corporation for Assigned Names and Numbers 14 (ICANN) to its contracted parties in order to fulfill reporting 15 requirements. The interfaces provided by ICANN to Data Escrow Agents 16 and Registry Operators to fulfill the requirements of Specifications 17 2 and 3 of the gTLD Base Registry Agreement are also described in 18 this document. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at https://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on September 27, 2020. 37 Copyright Notice 39 Copyright (c) 2020 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 8.13. Version 12 . . . . . . . . . . . . . . . . . . . . . . . 35 96 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 35 97 10. Security Considerations . . . . . . . . . . . . . . . . . . . 35 98 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 35 99 11.1. Normative References . . . . . . . . . . . . . . . . . . 35 100 11.2. Informative References . . . . . . . . . . . . . . . . . 36 101 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 36 103 1. Introduction 105 This document describes the technical details of the interfaces 106 provided by the Internet Corporation for Assigned Names and Numbers 107 (ICANN) to other contracted parties in order to fulfill reporting 108 requirements. The interface provided by ICANN to Registry Operators 109 and Data Escrow Agents in order to fulfill the requirements of 110 Specifications 2 and 3 of the gTLD Base Registry Agreement 111 [ICANN-GTLD-BASE-RA] are also described in this document. 113 1.1. Terminology 115 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 116 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 117 document are to be interpreted as described in RFC 2119 [RFC2119]. 119 XML is case sensitive. Unless stated otherwise, XML specifications 120 and examples provided in this document MUST be interpreted in the 121 character case presented in order to develop a conforming 122 implementation. 124 1.2. Date and Time 126 Numerous fields indicate "date and time", such as the creation and 127 receipt dates for data escrow deposits. These fields SHALL contain 128 timestamps indicating the date and time in UTC as specified in 129 [RFC3339], with no offset from the zero meridian. 131 1.3. Object Description 133 This section describes the base objects supported by this 134 specification. 136 1.3.1. object 138 The ICANN interfaces for registries and data escrow agents (IIRDEA) 139 object is used to provide information on the result 140 of a verification process when interacting with the interfaces. 142 The object contains the following attribute and child 143 elements: 145 o A "code" attribute whose value is a four-digit decimal number that 146 identifies the result of a process. Available result code values 147 MUST be defined for the corresponding process. 149 o An OPTIONAL "domainCount" attribute to indicate the number of 150 domain names related to the reported result. 152 o A element containing a human-readable description of the 153 result code. 155 o An OPTIONAL element that includes additional details 156 on the result conditions. 158 An example of a object is presented below: 160 161 The structure of the report is invalid. 162 163 'XX' could not be parsed as a number (line: 2 column:3) 164 165 167 1.3.2. object 169 The contents of a data escrow deposit are described using a 170 object. The object contains 171 the following child elements: 173 o An element that contains the identifier assigned to this 174 report. The report identifier MUST be the same as the "id" 175 attribute from the . If the data escrow deposit does not 176 include a unique identifer, the Data Escrow Agent MUST generate a 177 unique identifier to reference the data escrow deposit and use it 178 in the element. 180 o A element contains the version of the specification 181 used. This value MUST be 1. 183 o A element contains the version of the Data Escrow 184 Specification (e.g. draft-arias-noguchi-registry-data-escrow-06) 185 used to create the deposit. After the specification is published 186 as an RFC, the value MUST be the RFC number assigned by IANA. 188 o An OPTIONAL element contains the version of the 189 Domain Name Registration Data (DNRD) Objects Mapping (e.g. draft- 190 arias-noguchi-dnrd-objects-mapping-05) used to create the deposit. 191 After the specification is published as an RFC, the value MUST be 192 the RFC number assigned by IANA. The element 193 MUST be included if the deposit was created using any version of 194 the DNRD objects mapping specification (see, 195 [I-D.arias-noguchi-dnrd-objects-mapping]). 197 o A element contains the value of the "resend" attribute of 198 the . 200 o A element contains the date and time that the deposit was 201 created by the Registry Operator. 203 o A element is used to identify the kind of deposit: FULL, 204 INCR (Incremental) or DIFF (Differential). 206 o A element contains the date and time corresponding to 207 the Timeline Watermark ( element) of the . 209 o A element contains the header of the 210 as defined in [I-D.arias-noguchi-dnrd-objects-mapping] 212 An example of a object is available in 213 Section 2.1. 215 1.3.3. object 217 The object is used by Data Escrow 218 Agents to document the result of the data escrow deposit verification 219 process. The object contains the 220 following child elements: 222 o A element contains the name of the Data Escrow Agent. 224 o A element contains the version of the specification 225 used. This value MUST be 1. 227 o A element contains the reported date. In case of a DVPN 228 or DVFN notification this value MUST be the date of the 229 element of the . In case of a DRFN deposit 230 notification, this value MUST be the date for which no deposit was 231 received from the Registrar or Registry Operator. 233 o A element is used to specify the status of . 234 The possible values of status are: DVPN, DVFN and DRFN. The value 235 for the element is determined by the three types of 236 notices: 238 * Deposit Receipt Failure Notice (DRFN): generated by the Data 239 Escrow Agent when no deposit is received pursuant to the data 240 escrow deposit schedule. 242 * Deposit Verification Failure Notice (DVFN): generated by the 243 Data Escrow Agent when a deposit is received, but the final 244 result of the verification process is failure. 246 * Deposit Verification Pass Notice (DVPN): generated by the Data 247 Escrow Agent when a deposit is received and the final result of 248 the verification process is success. 250 o An OPTIONAL element contains the errors detected during 251 the data escrow deposit verification process performed by the Data 252 Escrow Agent. The element includes one or more 253 elements as defined in Section 1.3.1. In case of 254 a DRFN or DVPN deposit notification the element MUST NOT 255 be present. 257 o An OPTIONAL element contains the date and time that the 258 deposit was successfully received by the Data Escrow Agent. In 259 case of a DRFN deposit notification this element MUST NOT be 260 present. 262 o An OPTIONAL element contains the date and time that the 263 deposit was processed for validation by the Data Escrow Agent. In 264 case of a DRFN deposit notification this element MUST NOT be 265 present. 267 o An OPTIONAL element contains the date of the 268 Timeline Watermark ( element) of the most recent FULL 269 deposit that was successfully validated by the Data Escrow Agent. 270 This element MUST NOT be present if a successfully validated full 271 deposit has never been deposited. 273 o An OPTIONAL element is used by the Data Escrow 274 Agent to provide extended information about the deposit. In case 275 of a DRFN deposit notification this element MUST NOT be present. 276 In case of a DVPN or DVFN deposit notification this element MUST 277 be present. When this element is present, the 278 element MUST be generated by the Data Escrow Agent for the 279 Timeline Watermark ( element) of the deposit being 280 processed. If the deposit being processed is a differential or 281 incremental deposit, the Data Escrow Agent MUST process the last 282 full plus all differentials or last full plus last incremental 283 escrow deposits from the same repository (e.g. TLD) to generate 284 the element. 286 o Note: In case of a DVPN or DVFN deposit notification, the is 287 used as unique identifier. 289 An example of a object is available in 290 Section 2.2. 292 1.3.4. Object 294 Interfaces that support monitoring the reporting status for a 295 specific repository, provide a object as 296 defined by the schema in Section 6 in the HTTP Entity-body when a 297 HTTP/200 code is sent by the interface. 299 The element includes the following child 300 elements: 302 o A choice of one of the elements as defined in the 303 "rdeHeader:repositoryTypeGroup" (see 304 [I-D.arias-noguchi-dnrd-objects-mapping]) that indicates the 305 unique identifier for the repository being escrowed. 307 o A element with the date and time in which the 308 queried repository was created in the system. 310 o A OPTIONAL element indicating the current Data 311 Escrow Deposit schedule for the queried repository. Possible 312 values are "None", "Weekly", and "Daily". 314 o An OPTIONAL element indicating the date of the 315 Timeline Watermark ( element) of the most recent FULL 316 deposit that was successfully validated for the queried repository 317 as notified by the Data Escrow Agent. 319 o A element with a element for each 320 report type for the queried repository. Each 321 element includes the following child elements: 323 * : a string value indicating the report type to which the 324 information provided pertains. 326 * : a boolean value indicating if the report type is 327 enabled for the repository. 329 * : a string value indicating the reporting status. A 330 value of "ok" indicates there are no reporting issues in the 331 corresponding report type, otherwise the value of 332 "unsatisfactory" is shown. 334 * An OPTIONAL element included only when the 335 element has a value of "unsatisfactory", and includes an empty 336 element for each date with a reporting problem found in 337 the corresponding report type. Each element includes a 338 REQUIRED "date" attribute in "YYYY-MM-DD" format and a REQUIRED 339 "description" attribute to describe the issue. The possible 340 values to describe each reporting issue are: 342 + "Missing_Deposit_Full": If the latest notification received 343 from the Data Escrow Agent for the date indicates that a 344 scheduled "Full" deposit was not submitted by the repository 345 owner. 347 + "Missing_Deposit_Diff": If the latest notification received 348 from the Data Escrow Agent for the date indicates that a 349 scheduled "Differential" deposit was not submitted by the 350 repository owner. 352 + "Invalid_Deposit_Full": If the latest notification received 353 from the Data Escrow Agent for the date indicates that a 354 "Full" deposit was received by the Data Escrow Agent, but 355 failed the verification process. 357 + "Invalid_Deposit_Diff": If the latest notification received 358 from the Data Escrow Agent for the date indicates that a 359 "Differential" deposit was received by the Data Escrow 360 Agent, but failed the verification process. 362 + "No_Report_Received" If no report has been received for the 363 date. 365 o A element to indicate the date and time in which the 366 reporting status response was created. 368 1.3.5. Object 370 Interfaces that support monitoring and retrieving Data Escrow Reports 371 received, provide a object as defined by the 372 schema in Section 6 in the HTTP Entity-body when a HTTP/200 code is 373 sent by the interface. 375 The element includes a list of 376 objects, one for each 377 successfully received by ICANN. Each 378 object includes the following child elements: 380 o A element to indicate the date and time in which the 381 report was received by ICANN. 383 o A element as defined in Section 1.3.2 as 384 received by ICANN. 386 1.3.6. Object 388 Interfaces that support monitoring and retrieving Data Escrow 389 Notifications received from Data Escrow Agents, provide a 390 object as defined by the schema in 391 Section 6 in the HTTP Entity-body when a HTTP/200 code is sent by the 392 interface. 394 The element includes a list of 395 objects, one for each 396 successfully received by ICANN. Each 397 object includes the following 398 child elements: 400 o A element to indicate the date and time in which the 401 notification was received by ICANN. 403 o A element as defined in 404 Section 1.3.3 as received by ICANN. 406 2. Interfaces for Specification 2 - Data Escrow Reporting 408 This section describes the interfaces provided by ICANN to Registry 409 Operators and Data Escrow Agents in order to fulfill the reporting 410 requirements detailed in Specification 2 of the gTLD Base Registry 411 Agreement [ICANN-GTLD-BASE-RA]. 413 2.1. Registry Operator Reporting 415 The gTLD Base Registry Agreement [ICANN-GTLD-BASE-RA], Specification 416 2, Part A, Section 7 requires Registry Operators to provide ICANN 417 with a written statement that includes a copy of the report generated 418 upon creation of a deposit and a statement that the deposit has been 419 inspected by the Registry Operator and is complete and accurate. 421 In order to satisfy this requirement, the Registry Operator sends to 422 ICANN a object as defined in Section 1.3.2 for 423 each deposit successfully sent to the Data Escrow Agent, using the 424 PUT HTTP verb in the interface provided by ICANN at: 426 https://ry-api.icann.org/report/registry-escrow-report// 428 Where: 430 * MUST be substituted by the TLD for which the report is 431 being provided. In case of an IDN TLD, the A-label (see 432 [RFC5890]) MUST be used. 434 * MUST be substituted by the identifier assigned to this 435 report, which MUST be the same as the "id" attribute from the 436 . 438 Note: the interface supports overwriting the information of a 439 particular report to support asynchronous interfaces between 440 Registry Operators and Data Escrow Agents. 442 Example of a object for a data escrow deposit 443 corresponding to a TLD Registry repository: 445 446 449 20101017001 450 1 451 452 draft-arias-noguchi-registry-data-escrow-06 453 454 455 draft-arias-noguchi-dnrd-objects-mapping-05 456 457 0 458 2010-10-17T00:15:00.0Z 459 FULL 460 2010-10-17T00:00:00Z 461 462 test 463 2 465 1 467 1 469 1 471 472 1 474 1 476 1 478 479 480 482 2.2. Data Escrow Agent Reporting 484 The gTLD Base Registry Agreement [ICANN-GTLD-BASE-RA], Specification 485 2, Part B, Section 7 requires Data Escrow Agents, to deliver ICANN 486 with a notification object every time a successfully processed 487 deposit is received from the Registry Operator regardless of the 488 final status of the verification process. 490 In order to satisfy this requirement, the Data Escrow Agent sends to 491 ICANN a object as defined in 492 Section 1.3.3, using the POST HTTP verb in the interface provided by 493 ICANN at: 495 https://ry-api.icann.org/report/escrow-agent-notification/ 497 Where: 499 * MUST be substituted by the TLD for which the notification 500 is being provided. In case of an IDN TLD, the A-label (see 501 [RFC5890]) MUST be used. 503 If by 23:59:59 UTC, a deposit has not been successfully processed 504 regardless of the final status of the verification process, a 505 object with DRFN status MUST be send 506 to ICANN. 508 Example of a object of a Data Escrow 509 Agent notification corresponding to a Registry repository Data Escrow 510 Deposit: 512 513 517 Escrow Agent Inc. 518 1 519 2010-10-17 520 DVPN 521 522 2010-10-17T03:15:00.0Z 523 524 525 2010-10-17T05:15:00.0Z 526 527 528 2010-10-14 529 530 531 20101017001 532 1 533 534 draft-arias-noguchi-registry-data-escrow-06 535 536 537 draft-arias-noguchi-dnrd-objects-mapping-03 538 539 0 540 2010-10-17T00:15:00.0Z 541 FULL 542 2010-10-17T00:00:00Z 543 544 test 545 1 547 3 549 1 551 3 553 1 555 10 557 0 559 560 561 563 3. Interfaces of Specification 3 - Registry Operator Monthly Reporting 565 Specification 3 of the gTLD Base Registry Agreement 566 [ICANN-GTLD-BASE-RA] requires Registry Operators to provide a set of 567 monthly reports per gTLD. Two type of reports are required to be 568 sent by Registries: Per-Registrar Transactions Report and Registry 569 Functions Activity Report. This section specifies the interfaces 570 provided by ICANN to automate the upload of these reports by Registry 571 Operators. 573 The cut-off date for the reception of the reports specified in 574 specification 3 is defined in the gTLD Base Registry Agreement 575 [ICANN-GTLD-BASE-RA]. Before the cut-off date the Registry Operator 576 could replace a successfully validated report as many times as it 577 needs. 579 3.1. Per-Registrar Transactions Report 581 The Per-Registrar Transactions Report is a CSV report described in 582 Section 1 of Specification 3. 584 In order to satisfy this requirement, the Registry Operator sends a 585 CSV report on a monthly basis as described in the gTLD Base Registry 586 Agreement [ICANN-GTLD-BASE-RA], using the PUT HTTP verb in the 587 interface provided by ICANN at: 589 https://ry-api.icann.org/report/registrar- 590 transactions// 592 Where: 594 * MUST be substituted by the TLD for which the reports is 595 being provided. In case of an IDN TLD, the A-label (see 596 [RFC5890]) MUST be used. 598 * MUST be substituted by the month for which the reports 599 is being provided in the form of YYYY-MM. Where 'YYYY' is the 600 year and 'MM' is the two digit month number. For example: 601 2013-03 603 3.2. Registry Functions Activity Report 605 The Registry Functions Activity Report is a CSV report described in 606 Section 2 of Specification 3 of the gTLD Base Registry Agreement 607 [ICANN-GTLD-BASE-RA]. 609 In order to satisfy this requirement, the Registry Operator sends a 610 CSV report on a monthly basis as described in the gTLD Base Registry 611 Agreement [ICANN-GTLD-BASE-RA], using the PUT HTTP verb in the 612 interface provided by ICANN at: 614 https://ry-api.icann.org/report/registry-functions- 615 activity// 617 Where: 619 * MUST be substituted by the TLD for which the report is 620 being provided. In case of an IDN TLD, the A-label (see 621 [RFC5890]) MUST be used. 623 * MUST be substituted by the month for which the reports 624 is being provided in the form of YYYY-MM. Where 'YYYY' is the 625 year and 'MM' is the two digit month number. For example: 626 2013-03 628 4. Technical details of the interfaces 630 Content-type value in the HTTP header: 632 o The client MUST set "text/xml" in the HTTP header Content-type 633 when using the Data Escrow Agent Reporting and Registry Operator 634 Reporting interfaces described in Section 2. 636 o The client MUST set "text/csv" in the HTTP header Content-type 637 when using the Per-Registrar Transactions Report Registry 638 Functions Activity Report interfaces described in Section 3. 640 The interfaces support HTTP streams only (HTTP multi-part forms are 641 not supported). 643 After successfully receiving an input in any of the interfaces, ICANN 644 validates it and provides a object with an result element 645 in the same HTTP transaction. 647 The following HTTP status codes are standard across all interfaces: 649 o The interface provides a HTTP/200 status code and sets the HTTP 650 header Content-type: text/xml, if the interface was able to 651 receive the input sucessfully, the client MUST review the response 652 object to verify the result code after processing the input. 654 o The interface provides a HTTP/400 status code and sets the HTTP 655 header Content-type: text/xml, if the input is incorrect or the 656 syntax of the input is invalid. A response object is included 657 with the input validation failure details. 659 o The interface provides a HTTP/401 status code and sets the HTTP 660 header Content-type: text/plain, if the credentials provided does 661 not authorize the Registry Operator to upload a report for that 662 . 664 o The interface provides a HTTP/403 status code and sets the HTTP 665 header Content-type: text/plain, if the credentials provided are 666 valid but are being used to access a resource that permission is 667 not granted for or the connecting IP address is not whitelisted 668 for the . 670 o The interface provides a HTTP/405 status code if the interface 671 does not support the request method. 673 o The interface provides a HTTP/500 status code and sets the HTTP 674 header Content-type: text/plain, if the system is experiencing a 675 general failure. The sending party is responsible to send the 676 input again. 678 o The interface provides a HTTP/501 status code and sets the HTTP 679 header Content-type: text/plain, if the functionality has not yet 680 been implemented. 682 After sending the response, the interfaces closes the TCP connection. 684 4.1. Response Object 686 After processing the input provided in any of the interfaces, a 687 response object as defined by the schema in Section 6 is provided in 688 the HTTP Entity-body when an HTTP/200 or HTTP/400 status code is sent 689 by the interface. 691 An example of a response object upon successful input receipt is 692 presented below: 694 HTTP/1.1 200 OK 695 Content-Type: text/xml 696 Content-Length: 248 698 699 700 701 No ERRORs were found and the report has been 702 accepted by ICANN. 703 704 705 707 An example of a response object in the event of input error is 708 presented below: 710 HTTP/1.1 400 Bad Request 711 Content-Type: text/xml 712 Content-Length: 279 714 715 716 717 The structure of the report is invalid. 718 719 'XX' could not be parsed as a number (line: 2 column:3) 720 721 722 724 The following sections provide the IIRDEA Result Codes per interface: 726 4.1.1. Registry Operator Reporting 728 The following table lists the result codes of the interface: 730 +--------+----------------------------------------------------------+ 731 | Result | Message | 732 | Code | | 733 +--------+----------------------------------------------------------+ 734 | 1000 | No ERRORs were found and the report has been accepted by | 735 | | ICANN. | 736 | 2001 | The request did not validate against the schema. | 737 | 2004 | Report for a date in the future. The and | 738 | | date should not be in the future. | 739 | 2005 | Version is not supported. | 740 | 2006 | The in the element and the in the URL | 741 | | path do not match. | 742 | 2007 | Interface is disabled for this TLD. | 743 | 2008 | The and date should not be before | 744 | | the creation date of the TLD in the system. | 745 | 2202 | The in the
and the TLD in the URL path do | 746 | | not match. | 747 | 2205 | Report regarding a differential deposit received for a | 748 | | Sunday (). | 749 | 2206 | csvDomain and rdeDomain count provided in the
. | 750 | 2209 | Missing required element in the
. | 751 | 2210 | The value of the "rcdn" attribute in the element | 752 | | does not match the same or lower level names in the | 753 | | in the URL path. | 754 | 2211 | Multiple count elements with the same "uri", "rcdn", and | 755 | | "registrarId" attribute values provided in the
. | 756 | 2212 | An invalid NR-LDH label or A-label was found or the | 757 | | domain name syntax is invalid in the "rcdn" attribute. | 758 +--------+----------------------------------------------------------+ 760 Data Escrow Reporting Result Codes 762 4.1.2. Data Escrow Agent Reporting 764 The following table lists the result codes of the interface: 766 +--------+----------------------------------------------------------+ 767 | Result | Message | 768 | Code | | 769 +--------+----------------------------------------------------------+ 770 | 1000 | No ERRORs were found and the notification has been | 771 | | accepted by ICANN. | 772 | 2001 | The request did not validate against the schema. | 773 | 2002 | A DVPN notification exists for that date (). | 774 | 2004 | Notification for a date in the future. The and | 775 | | and date should not be in the | 776 | | future. | 777 | 2005 | Version is not supported. | 778 | 2007 | Interface is disabled for this TLD. | 779 | 2008 | The and and date should | 780 | | not be before the creation date of the TLD in the | 781 | | system. | 782 | 2201 | The and in the notification do not | 783 | | match. | 784 | 2202 | The in the
and the TLD in the URL path do | 785 | | not match. | 786 | 2203 | A Deposit Verification Pass Notice (DVPN) notification | 787 | | was received, but the Domain Name count is missing in | 788 | | the
. | 789 | 2204 | The notification for the report "id" already exists. | 790 | 2205 | Notification regarding a differential deposit received | 791 | | for a Sunday (). | 792 | 2206 | csvDomain and rdeDomain count provided in the
. | 793 | 2207 | A DVPN or DVFN was received, but the element is | 794 | | missing in the notification. | 795 | 2208 | A DRFN was received, but a element exists in | 796 | | the notification. | 797 | 2209 | Missing required element in the
. | 798 | 2210 | The value of the "rcdn" attribute in the element | 799 | | does not match the same or lower level names in the | 800 | | in the URL path. | 801 | 2211 | Multiple count elements with the same "uri", "rcdn", and | 802 | | "registrarId" attribute values provided in the
. | 803 | 2212 | An invalid NR-LDH label or A-label was found or the | 804 | | domain name syntax is invalid in the "rcdn" attribute. | 805 +--------+----------------------------------------------------------+ 807 Data Escrow Reporting Result Codes 809 4.1.3. Per-Registrar Transactions Report 811 The following table lists the result codes of the interface: 813 +----------+--------------------------------------------------------+ 814 | Result | Message | 815 | Code | | 816 +----------+--------------------------------------------------------+ 817 | 1000 | No ERRORs were found and the report has been accepted | 818 | | by ICANN. | 819 | 2001 | The structure of the report is invalid. | 820 | 2002 | A report for that month already exists, the cut-off | 821 | | date already passed. | 822 | 2003 | Negative numeric value present in the report. | 823 | 2004 | Report for a month in the future. | 824 | 2007 | Interface is disabled for this TLD. | 825 | 2008 | Reported month before the creation date of the TLD in | 826 | | the system. | 827 | 2101 | Incorrect totals present in the report. | 828 | 2102 | A non ICANN-accredited registrar is present in the | 829 | | report. | 830 | 2103 | Values found in the second field of the totals line. | 831 | 2105 | The report is not encoded in UTF-8. Note: reports | 832 | | encoded in US-ASCII are accepted. | 833 +----------+--------------------------------------------------------+ 835 Per-Registrar Transactions Report Result Codes 837 4.1.4. Registry Functions Activity Report 839 The following table lists the result codes of the interface: 841 +----------+--------------------------------------------------------+ 842 | Result | Message | 843 | Code | | 844 +----------+--------------------------------------------------------+ 845 | 1000 | No ERRORs were found and the report has been accepted | 846 | | by ICANN. | 847 | 2001 | The structure of the report is invalid. | 848 | 2002 | A report for that month already exists, the cut-off | 849 | | date already passed. | 850 | 2003 | Negative numeric value present in the report. | 851 | 2004 | Report for a month in the future. | 852 | 2007 | Interface is disabled for this TLD. | 853 | 2008 | Reported month before the creation date of the TLD in | 854 | | the system. | 855 | 2105 | The report is not encoded in UTF-8. Note: reports | 856 | | encoded in US-ASCII are accepted. | 857 +----------+--------------------------------------------------------+ 859 Registry Functions Activity Report Result Codes 861 5. Monitoring the reporting status 863 Registries MAY monitor the status of the reports described in 864 Specification 2 and Specification 3 of the gTLD Base Registry 865 Agreement [ICANN-GTLD-BASE-RA] using the following interfaces that 866 supports the HEAD HTTP verb: 868 5.1. Monitoring the status of Data Escrow Reports 870 Registries MAY monitor the status of Data Escrow Reports using the 871 following interface: 873 https://ry-api.icann.org/info/report/registry-escrow- 874 report// 876 Where: 878 * MUST be substituted by the TLD being queried. In case of 879 an IDN TLD, the A-label (see [RFC5890]) MUST be used. 881 * MUST be substituted by the day being queried. For 882 example: 2013-03-02 884 Possible results are: 886 * The interface provides a HTTP/200 status code, if a 887 syntactically valid data escrow report was received for the 888 queried date. 890 * The interface provides a HTTP/404 status code, if a 891 syntactically valid data escrow report has not been received 892 for the queried date. 894 5.2. Monitoring the status of Data Escrow Notifications 896 Registries and Data Escrow Agents MAY monitor the status of Data 897 Escrow Notifications using the following interface: 899 https://ry-api.icann.org/info/report/escrow-agent- 900 notification// 902 Where: 904 * MUST be substituted by the TLD being queried. In case of 905 an IDN TLD, the A-label (see [RFC5890]) MUST be used. 907 * MUST be substituted by the day being queried. For 908 example: 2013-03-02 910 Possible results are: 912 * The interface provides a HTTP/200 status code, if a 913 syntactically valid data escrow notification was received for 914 the queried date. 916 * The interface provides a HTTP/404 status code, if a 917 syntactically valid data escrow notification has not been 918 received for the queried date. 920 5.3. Monitoring the status of Registry Functions Activity Report 922 Registries MAY monitor the status of Registry Functions Activity 923 Report using the following interface: 925 https://ry-api.icann.org/info/report/registry-functions- 926 activity// 928 Where: 930 * MUST be substituted by the TLD being queried. In case of 931 an IDN TLD, the A-label (see [RFC5890]) MUST be used. 933 * MUST be substituted by the month being queried. For 934 example: 2013-03 936 Possible results are: 938 * The interface provides a HTTP/200 status code, if a 939 syntactically valid registry functions activity report was 940 received for the queried month. 942 * The interface provides a HTTP/404 status code, if a 943 syntactically valid registry functions activity report has not 944 been received for the queried month. 946 5.4. Monitoring the status of the Per-Registrar Transactions Report 948 Registries MAY monitor the status of Per-Registrar Transactions 949 Report using the following interface: 951 https://ry-api.icann.org/info/report/registrar- 952 transactions// 954 Where: 956 * MUST be substituted by the TLD being queried. In case of 957 an IDN TLD, the A-label (see [RFC5890]) MUST be used. 959 * MUST be substituted by the month being queried. For 960 example: 2013-03 962 Possible results are: 964 * The interface provides a HTTP/200 status code, if a 965 syntactically valid per-registrar transactions report was 966 received for the queried month. 968 * The interface provides a HTTP/404 status code, if a 969 syntactically valid per-registrar transactions report has not 970 been received for the queried month. 972 6. Formal Syntax 974 The schema of the IIRDEA Result, Report, Notification, RRI Reporting, 975 Notifications, and Reports objects described in Section 1.3 are 976 presented here. 978 The BEGIN and END tags are not part of the schema; they are used to 979 note the beginning and ending of the schema for URI registration 980 purposes. 982 6.1. IIRDEA Result Schema 984 Copyright (c) 2017 IETF Trust and the persons identified as authors 985 of the code. All rights reserved. 987 Redistribution and use in source and binary forms, with or without 988 modification, is permitted pursuant to, and subject to the license 989 terms contained in, the Simplified BSD License set forth in 990 Section 4.c of the IETF Trust's Legal Provisions Relating to IETF 991 Documents (http://trustee.ietf.org/license-info). 992 BEGIN 993 994 999 1000 1001 ICANN interfaces for registries and data escrow agents 1002 1003 1005 1006 1008 1009 1010 1011 1012 1014 1015 1016 1017 1019 1020 1022 1023 1025 1026 1027 1028 1029 1030 1032 1033 END 1035 6.2. Report Object 1037 Copyright (c) 2017 IETF Trust and the persons identified as authors 1038 of the code. All rights reserved. 1040 Redistribution and use in source and binary forms, with or without 1041 modification, is permitted pursuant to, and subject to the license 1042 terms contained in, the Simplified BSD License set forth in 1043 Section 4.c of the IETF Trust's Legal Provisions Relating to IETF 1044 Documents (http://trustee.ietf.org/license-info). 1046 BEGIN 1047 1048 1055 1056 1058 1059 1060 Data Escrow Report schema 1061 1062 1064 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 END 1082 6.3. Notification Object 1084 Copyright (c) 2017 IETF Trust and the persons identified as authors 1085 of the code. All rights reserved. 1087 Redistribution and use in source and binary forms, with or without 1088 modification, is permitted pursuant to, and subject to the license 1089 terms contained in, the Simplified BSD License set forth in 1090 Section 4.c of the IETF Trust's Legal Provisions Relating to IETF 1091 Documents (http://trustee.ietf.org/license-info). 1093 BEGIN 1094 1095 1102 1103 1105 1106 1107 Data Escrow Notification schema 1108 1109 1111 1114 1115 1116 1117 1118 1119 1120 1122 1123 1124 1125 1126 1127 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1141 1142 1143 1144 1145 1146 1147 1148 1149 END 1151 6.4. RRI Reporting Summary Object 1153 Copyright (c) 2018 IETF Trust and the persons identified as authors 1154 of the code. All rights reserved. 1156 Redistribution and use in source and binary forms, with or without 1157 modification, is permitted pursuant to, and subject to the license 1158 terms contained in, the Simplified BSD License set forth in 1159 Section 4.c of the IETF Trust's Legal Provisions Relating to IETF 1160 Documents (http://trustee.ietf.org/license-info). 1162 BEGIN 1163 1164 1170 1172 1174 1175 1176 1177 1178 1180 1181 1184 1185 1186 1188 1189 1190 1191 1192 1193 1194 1196 1197 1198 1200 1201 1203 1204 1205 1206 1207 1208 1210 1211 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1225 1226 1227 1228 1229 1230 1231 1232 1233 1235 1236 1238 1239 1241 1243 1245 1246 1247 1249 1250 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 END 1264 6.5. Notifications Object 1266 Copyright (c) 2018 IETF Trust and the persons identified as authors 1267 of the code. All rights reserved. 1269 Redistribution and use in source and binary forms, with or without 1270 modification, is permitted pursuant to, and subject to the license 1271 terms contained in, the Simplified BSD License set forth in 1272 Section 4.c of the IETF Trust's Legal Provisions Relating to IETF 1273 Documents (http://trustee.ietf.org/license-info). 1274 BEGIN 1275 1276 1282 1284 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 END 1302 6.6. Reports Object 1304 Copyright (c) 2018 IETF Trust and the persons identified as authors 1305 of the code. All rights reserved. 1307 Redistribution and use in source and binary forms, with or without 1308 modification, is permitted pursuant to, and subject to the license 1309 terms contained in, the Simplified BSD License set forth in 1310 Section 4.c of the IETF Trust's Legal Provisions Relating to IETF 1311 Documents (http://trustee.ietf.org/license-info). 1312 BEGIN 1313 1314 1320 1322 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 END 1339 7. Acknowledgements 1341 Special suggestions that have been incorporated into this document 1342 were provided by David Kipling, James Gould, Gregory Zaltsman, Brett 1343 Carr and Harel Efraim. 1345 8. Change History 1347 [[RFC Editor: Please remove this section.]] 1349 8.1. Version 00 1351 Initial version. 1353 8.2. Version 01 1355 o and moved from 1356 escrow drafts to this draft 1358 o Added to 1359 o element of is now OPTIONAL 1361 o Added element to 1363 o and added to the draft 1365 o Several report elements are OPTIONAL to support async interfaces 1366 between Registry Operators and Data Escrow Agents 1368 o Added and to registry-escrow-report interface in order 1369 to make the interface idempotent and support async RyO-DEA 1370 interfaces 1372 o Added to escrow-agent-notification interface 1374 o The escrow-agent-notification uses POST and not PUT, this has been 1375 fixed 1377 o Several clarifications 1379 8.3. Version 02 1381 o Added and updated several result codes. 1383 o Added element. 1385 o Added Content-type definition. 1387 8.4. Version 03 1389 o Added several result codes. 1391 o unsignedShort is now used for result code in iirdea schema. 1393 o Enumeration was removed from the iirdea schema. 1395 8.5. Version 04 1397 o Added result codes: 2207 and 2208. 1399 o Removed result codes: 2203. 1401 o Added clarification regarding the support of HTTP streams. 1403 8.6. Version 05 1405 o Added result codes: 2007 and 2008. 1407 8.7. Version 06 1409 o Added clarification of error code HTTP/403 in Section 4. 1411 8.8. Version 07 1413 o Added Section 5: "Monitoring compliance with the New gTLD Base 1414 Agreement". 1416 8.9. Version 08 1418 o Reorganized specification structure to allow easier references 1419 from new specifications expanding functionality in the ICANN 1420 Registry Interfaces. 1422 o Added Section 1.3 to document object definitions, previously 1423 defined in other sections. 1425 o Added , , and object 1426 descriptions to Section 1.3, and schema definitions to Section 6. 1428 o Renamed Section 5 title as "Monitoring the reporting status". 1430 o Updated element as OPTIONAL in the 1431 schema. 1433 o Added OPTIONAL attribute "domainCount" to the 1434 element. 1436 o Added OPTIONAL element to the schema. 1438 o Added result codes: 2105, 2209, 2210 and 2211. 1440 o Added "gTLD Base Registry Agreement" references. 1442 o Added clarifications to Section 4. 1444 8.10. Version 09 1446 o Standardized XSD schema validation error message for notifications 1447 and reports. 1449 o Element made optional in the schema. 1451 o Separated example RRI interface responses for successful and 1452 unsuccessful input. 1454 8.11. Version 10 1456 1. Ping update. 1458 8.12. Version 11 1460 1. Ping update. 1462 8.13. Version 12 1464 1. Ping update. 1466 9. IANA Considerations 1468 TODO 1470 10. Security Considerations 1472 TODO 1474 11. References 1476 11.1. Normative References 1478 [I-D.arias-noguchi-dnrd-objects-mapping] 1479 Lozano, G., Gould, J., and C. Thippeswamy, "Domain Name 1480 Registration Data (DNRD) Objects Mapping", draft-arias- 1481 noguchi-dnrd-objects-mapping-10 (work in progress), 1482 January 2019. 1484 [ICANN-GTLD-BASE-RA] 1485 ICANN, "gTLD Base Registry Agreement", Jan 2014, 1486 . 1489 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1490 Requirement Levels", BCP 14, RFC 2119, 1491 DOI 10.17487/RFC2119, March 1997, 1492 . 1494 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 1495 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 1496 . 1498 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1499 DOI 10.17487/RFC3688, January 2004, 1500 . 1502 11.2. Informative References 1504 [RFC5890] Klensin, J., "Internationalized Domain Names for 1505 Applications (IDNA): Definitions and Document Framework", 1506 RFC 5890, DOI 10.17487/RFC5890, August 2010, 1507 . 1509 [RFC5891] Klensin, J., "Internationalized Domain Names in 1510 Applications (IDNA): Protocol", RFC 5891, 1511 DOI 10.17487/RFC5891, August 2010, 1512 . 1514 Authors' Addresses 1516 Gustavo Lozano 1517 ICANN 1518 12025 Waterfront Drive, Suite 300 1519 Los Angeles 90292 1520 US 1522 Phone: +1.3103015800 1523 Email: gustavo.lozano@icann.org 1525 Eduardo Alvarez 1526 ICANN 1527 12025 Waterfront Drive, Suite 300 1528 Los Angeles 90292 1529 US 1531 Phone: +1.3103015800 1532 Email: eduardo.alvarez@icann.org