idnits 2.17.1 draft-sattler-epp-registry-maintenance-03.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 18, 2018) is 2225 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) No issues found here. Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Internet Engineering Task Force T. Sattler 2 Internet-Draft March 18, 2018 3 Intended status: Standard Track 4 Expires: September 17, 2018 6 Registry Maintenance Notifications for the 7 Extensible Provisioning Protocol (EPP) 8 draft-sattler-epp-registry-maintenance-03 10 Abstract 11 This document describes an Extensible Provision Protocol (EPP) 12 mapping for the Registry Maintenance Notifications used when Domain 13 Name Registries will conduct a maintenance, and for retrieving these 14 information. 16 Status of This Memo 17 This Internet-Draft is submitted in full conformance with the 18 provisions of BCP 78 and BCP 79. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF). Note that other groups may also distribute 22 working documents as Internet-Drafts. The list of current Internet- 23 Drafts is at https://datatracker.ietf.org/drafts/current/. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference 28 material or to cite them other than as "work in progress". 30 This Internet-Draft will expire on September 17, 2018. 32 Copyright Notice 33 Copyright (c) 2018 IETF Trust and the persons identified as the 34 document authors. All rights reserved. 36 This document is subject to BCP 78 and the IETF Trust's Legal 37 Provisions Relating to IETF Documents 38 (https://trustee.ietf.org/license-info) in effect on the date of 39 publication of this document. Please review these documents 40 carefully, as they describe your rights and restrictions with respect 41 to this document. Code Components extracted from this document must 42 include Simplified BSD License text as described in Section 4.e of 43 the Trust Legal Provisions and are provided without warranty as 44 described in the Simplified BSD License. 46 Table of Contents 47 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 48 1.1. Terminology and Definitions . . . . . . . . . . . . . . . 3 49 2. Object Attributes . . . . . . . . . . . . . . . . . . . . . . 3 50 2.1. Internationalized Domain Names . . . . . . . . . . . . . 3 51 2.2. Dates and Times . . . . . . . . . . . . . . . . . . . . . 3 52 2.3. Maintenance Elements . . . . . . . . . . . . . . . . . . 4 53 3. EPP Command Mapping . . . . . . . . . . . . . . . . . . . . . 6 54 3.1. EPP Query Commands . . . . . . . . . . . . . . . . . . . 6 55 3.1.1. EPP Command . . . . . . . . . . . . . . . . . 6 56 3.1.2. EPP Command . . . . . . . . . . . . . . . 6 57 3.1.3. EPP Command . . . . . . . . . . . . . . . . . 6 58 3.1.4. EPP Command . . . . . . . . . . . . . . . . . 9 59 3.2. EPP Transform Commands . . . . . . . . . . . . . . . . . 11 60 3.2.1. EPP Command . . . . . . . . . . . . . . . . 11 61 3.2.2. EPP Command . . . . . . . . . . . . . . . . 11 62 3.2.3. EPP Command . . . . . . . . . . . . . . . . . 11 63 3.2.4. EPP Command . . . . . . . . . . . . . . . 11 64 3.2.5. EPP Command . . . . . . . . . . . . . . . . 11 65 4. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 12 66 4.1. Registry Maintenance EPP Mapping Schema . . . . . . . . . 12 67 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 68 6. Security Considerations . . . . . . . . . . . . . . . . . . . 16 69 7. Implementation Status . . . . . . . . . . . . . . . . . . . . 17 70 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 17 71 8.1. Normative References . . . . . . . . . . . . . . . . . . . 17 72 8.2. Informative References . . . . . . . . . . . . . . . . . . 18 73 Appendix A. Change History . . . . . . . . . . . . . . . . . . . 18 74 A.1. Change from 00 to 01 . . . . . . . . . . . . . . . . . . 18 75 A.2. Change from 01 to 02 . . . . . . . . . . . . . . . . . . 18 76 A.3. Change from 02 to 03 . . . . . . . . . . . . . . . . . . 18 77 A.4. Change from 03 to 04 . . . . . . . . . . . . . . . . . . 18 78 A.5. Change from 04 to 05 . . . . . . . . . . . . . . . . . . 18 79 A.6. Change from 05 to 06 . . . . . . . . . . . . . . . . . . 19 80 A.7. Change from 06 to 07 . . . . . . . . . . . . . . . . . . 19 81 A.8. Change from 07 to EPPMAINT 00 . . . . . . . . . . . . . . 19 82 A.9. Change from EPPMAINT 00 to EPPMAINT 01 . . . . . . . . . 19 83 A.10. Change from EPPMAINT 01 to EPPMAINT 02 . . . . . . . . . 19 84 A.11. Change from EPPMAINT 02 to EPPMAINT 03 . . . . . . . . . 19 85 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 20 86 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 20 88 1. Introduction 90 This document describes an Extensible Provision Protocol (EPP) 91 [RFC5730] mapping for the Registry Maintenance Notifications used 92 when Domain Name Registries will conduct a maintenance, and for 93 retrieving these information. 95 1.1. Terminology and Definitions 97 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 98 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 99 document are to be interpreted as described in [RFC2119] when 100 specified in their uppercase forms. 102 XML is case sensitive. Unless stated otherwise, XML specifications 103 and examples provided in this document MUST be interpreted in the 104 character case presented in order to develop a conforming 105 implementation. 107 In examples, "C:" represents lines sent by a protocol client and 108 "S:" represents lines returned by a protocol server. Indentation and 109 white space in examples are provided only to illustrate element 110 relationships and are not a REQUIRED feature of this protocol. 112 2. Object Attributes 114 2.1. Internationalized Domain Names 116 Names of affected hosts MUST be provided in Punycode according to 117 [RFC5891]. 119 2.2. Dates and Times 121 All dates and times attribute values MUST be expressed in Universal 122 Coordinated Time (UTC) using the Gregorian calendar. The extended 123 date-time form using upper case "T" and "Z" characters defined in ISO 124 8601 [RFC3339] MUST be used to represent date-time values. 126 2.3. Maintenance Elements 128 The element describes a single domain name registry 129 maintenance event during a specific time period. This element will 130 be used at EPP messages and to extend the EPP command. 132 For creating a new maintenance the attribute MUST be 133 'active', the attribute MUST be set and the attribute 134 SHALL NOT be present. 136 For updating a maintenance the attribute MUST be 137 'active', the attributes and MUST be 138 set. 140 For deleting a maintenance the attribute MUST be 141 'inactive' the attributes and MUST be 142 set. 144 145 MUST be present and an UUID according [RFC4122], SHALL NOT be 146 changed if maintenance got updated or deleted. A human-readable 147 description of the maintenance is identified via an OPTIONAL 148 "msg" attribute. 150 151 MUST be present and contains one or more elements. 152 The server SHOULD NOT list systems which are not affected by the 153 maintenance. 155 156 MUST be present at least once and is an element of , 157 and 159 160 MUST be present and indicates the name of the affected system, 161 such as 'EPP', 'WHOIS', 'DNS', 'Portal', etc. 163 164 MUST be present and indicates the affected maintained system 165 (host or IP address). 166 Hostname SHALL be Punycode according [RFC5891]. 167 IPv4 addresses SHALL be dotted-decimal notation. 168 An example of this textual representation is "192.0.2.0". 169 IPv6 addresses SHALL be according [RFC5952]. 170 An example of this textual representation is 171 "2001:db8::1:0:0:1". 173 174 MUST be present and contains the impact level; values SHOULD 175 either be 'blackout' or 'partial' 177 178 MUST be present and indicates the type of the affected system; 179 values SHOULD either be 'production', 'ote', 'staging' or 'dev' 181 182 MUST be present and indicates the start of the maintenance 183 according ISO 8601 [RFC3339] 184 Format: YYYY-MM-DDThh:mm:ssTZ 186 187 MUST be present and indicates the end of the maintenance 188 according ISO 8601 [RFC3339] 189 Format: YYYY-MM-DDThh:mm:ssTZ 191 192 MUST be present and contains the reason behind the maintenance; 193 values SHOULD either be 'planned' or 'emergency' 195 196 MAY be present and contains URI to detailed maintenance 197 description 199 200 MAY be present and provides a freeform description of the 201 maintenance without having to create and traverse an external 202 resource. The maximum length SHOULD NOT exceed 1024 bit. 204 205 MUST be present and contains elements 207 208 MUST be present and contains the affected top-level domain. 209 Punycode encoded according [RFC5891] 211 212 MUST be present and contains and 213 215 216 MUST be present and indicates if a client needs to do something 217 that is connection related, such as a reconnect. The value 218 SHALL boolean. 220 221 MUST be present and indicates if a client needs to do something 222 that is implementation related, such as a code changes. The 223 value SHALL be boolean. 225 226 MUST be present and indicates the status of the maintenance. 227 The value SHALL be either 'active' or 'inactive' 229 230 MUST be present and contains the creation date of the maintenance 231 according ISO 8601 [RFC3339] 232 Format: YYYY-MM-DDThh:mm:ssTZ 234 235 MAY be present and contains the updated date of the maintenance 236 according ISO 8601 [RFC3339]. 237 Format: YYYY-MM-DDThh:mm:ssTZ 239 3. EPP Command Mapping 241 A detailed description of the EPP syntax and semantics can be found 242 in the EPP core protocol specification [RFC5730]. The command 243 mappings described here are specifically for the use to notify of 244 Registry Maintenances and Registry Maintenance object mapping. 246 3.1. EPP Query Commands 248 EPP [RFC5730] provides three commands to retrieve object information: 249 to determine if an object is known to the server, to 250 retrieve detailed information associated with an object, and 251 to retrieve object transfer status information. 253 3.1.1. EPP Command 255 Available check semantics do not apply to maintenance objects, so 256 there is no mapping defined for the EPP command. 258 3.1.2. EPP Command 260 Transfer semantics do not apply to maintenance objects, so there is 261 no mapping defined for the EPP command. 263 3.1.3. EPP Command 265 EPP provides the command that is used to retrieve registry 266 maintenance information. In addition to the standard EPP command 267 elements, the command MUST contain a 268 element that identifies the maintenance namespace. The 269 element MUST contain a child element. It is either to 270 retrieve a specific maintenance notification or to 271 query all maintenance notifications. 273 Example command with to get one specific 274 maintenance: 276 C: 277 C: 278 C: 279 C: 280 C: 282 C: 2e6df9b0-4092-4491-bcc8-9fb2166dcee6 283 C: 284 C: 285 C: ABC-12345 286 C: 287 C: 289 Example response for one specific maintenance notification: 291 S: 292 S: 293 S: 294 S: 295 S: Command completed successfully 296 S: 297 S: 298 S: 300 S: 301 S: 2e6df9b0-4092-4491-bcc8-9fb2166dcee6 302 S: 303 S: 304 S: 305 S: EPP 306 S: epp.registry.example 307 S: blackout 308 S: 309 S: 310 S: 311 S: 2017-04-30T06:00:00Z 312 S: 2013-10-22T14:25:57Z 313 S: planned 314 S: 315 S: https://www.registry.example/notice?123 316 S: 317 S: free text 318 S: 319 S: example 320 S: test 321 S: 322 S: 323 S: false 324 S: false 325 S: 326 S: active 327 S: 2017-02-08T22:10:00Z 328 S: 329 S: 330 S: 331 S: 332 S: ABC-12345 333 S: 54321-XYZ 334 S: 335 S: 336 S: 338 Example command with to query all maintenances: 340 C: 341 C: 342 C: 343 C: 344 C: 346 C: 347 C: 348 C: 349 C: ABC-12345 350 C: 351 C: 353 Example response querying all maintenances: 355 S: 356 S: 357 S: 358 S: 359 S: Command completed successfully 360 S: 361 S: 362 S: 364 S: 365 S: 366 S: 2e6df9b0-4092-4491-bcc8-9fb2166dcee6 367 S: 368 S: 2017-04-30T06:00:00Z 369 S: 2017-04-30T07:00:00Z 370 S: 2017-02-08T22:10:00Z 371 S: 372 S: 373 S: 91e9dabf-c4e9-4c19-a56c-78e3e89c2e2f 374 S: 375 S: 2017-06-15T04:30:00Z 376 S: 2017-06-15T05:30:00Z 377 S: 2017-02-08T22:10:00Z 378 S: 2017-03-08T20:11:00Z 379 S: 380 S: 381 S: 382 S: 383 S: 384 S: ABC-12345 385 S: 54321-XYZ 386 S: 387 S: 388 S: 390 3.1.4. EPP Command 392 The EPP command and response is defined in Section 2.9.2.3 of 393 [RFC5730]. The Registry Maintenance Notification is included in the 394 EPP response of [RFC5730]. 396 For the Registry Maintenance Notification, there are three types of 397 poll messages. The poll messages apply whenever the domain name 398 registry creates, updates or deletes a maintenance. In the case of 399 a Registry Maintenance specific message, a element 400 will be included within the element of the standard 401 response. 403 The element will include a reference to the 404 Registry Maintenance namespace. EPP data contained within the 405 element is formatted according to the 406 maintenance-poll schema. 408 Example command: 410 C: 411 C: 412 C: 413 C: 414 C: ABC-12345 415 C: 416 C: 418 Example response with the Registry Maintenance poll message: 420 S: 421 S: 422 S: 423 S: 424 S: Command completed successfully; ack to dequeue 425 S: 426 S: 427 S: 2017-02-08T22:10:00Z 428 S: Registry Maintenance Notification 429 S: 430 S: 431 S: 433 S: 434 S: 2e6df9b0-4092-4491-bcc8-9fb2166dcee6 435 S: 436 S: 437 S: EPP 438 S: epp.registry.example 439 S: blackout 440 S: 441 S: 442 S: 443 S: 2017-04-30T06:00:00Z 444 S: 2013-10-22T14:25:57Z 445 S: planned 446 S: 447 S: https://www.registry.example/notice?123 448 S: 449 S: 450 S: example 451 S: test 452 S: 453 S: 454 S: false 455 S: false 456 S: 457 S: active 458 S: 2017-02-08T22:10:00Z 459 S: 460 S: 461 S: 462 S: 463 S: ABC-12345 464 S: 54321-XYZ 465 S: 466 S: 467 S: 469 3.2. EPP Transform Commands 471 EPP provides five commands to transform objects: to create 472 an instance of an object, to delete an instance of an 473 object, to extend the validity period of an object, 474 to manage object sponsorship changes, and to 475 change information associated with an object. 477 3.2.1. EPP Command 479 Create semantics do not apply to maintenance objects, so there is no 480 mapping defined for the EPP command. 482 3.2.2. EPP Command 484 Delete semantics do not apply to maintenance objects, so there is no 485 mapping defined for the EPP command. 487 3.2.3. EPP Command 489 Renew semantics do not apply to maintenance objects, so there is no 490 mapping defined for the EPP command. 492 3.2.4. EPP Command 494 Transfer semantics do not apply to maintenance objects, so there is 495 no mapping defined for the EPP command. 497 3.2.5. EPP Command 499 Update semantics do not apply to maintenance objects, so there is no 500 mapping defined for the EPP command. 502 4. Formal Syntax 504 One schema is presented here that is the EPP Registry Maintenance 505 schema. 507 The formal syntax presented here is a complete schema representation 508 of the object mapping suitable for automated validation of EPP XML 509 instances. The BEGIN and END tags are not part of the schema; they 510 are used to note the beginning and ending of the schema for URI 511 registration purposes. 513 4.1. Registry Maintenance EPP Mapping Schema 515 BEGIN 516 517 524 527 528 530 531 532 Extensible Provisioning Protocol v1.0 533 Maintenance Mapping Schema. 534 535 537 540 542 545 546 547 548 549 551 552 553 554 555 557 560 561 562 563 564 565 566 568 571 573 576 577 578 579 580 581 583 586 587 588 590 591 593 596 597 598 599 600 601 602 603 604 605 608 609 610 611 612 613 614 615 616 617 619 620 621 622 623 624 625 627 630 631 632 634 635 637 640 641 642 643 644 645 647 650 651 652 653 654 656 659 660 661 662 663 664 665 667 670 671 672 673 674 675 676 677 678 680 683 684 685 686 687 688 689 690 692 695 696 697 698 699 700 702 705 706 707 709 710 711 714 715 716 717 718 719 721 724 725 726 727 728 729 731 734 735 END 737 5. IANA Considerations 739 TBD 741 6. Security Considerations 743 The mapping extensions described in this document do not provide any 744 security services beyond those described by EPP [RFC5730] and 745 protocol layers used by EPP. The security considerations described in 746 these other specifications apply to this specification as well. 748 7. Implementation Status 750 Note to RFC Editor: Please remove this section and the reference to 751 [RFC7942] before publication. 753 This section records the status of known implementations of the 754 protocol defined by this specification at the time of posting of this 755 Internet-Draft, and is based on a proposal described in [RFC7942]. 756 The description of implementations in this section is intended to 757 assist the IETF in its decision processes in progressing drafts to 758 RFCs. Please note that the listing of any individual implementation 759 here does not imply endorsement by the IETF. Furthermore, no effort 760 has been spent to verify the information presented here that was 761 supplied by IETF contributors. This is not intended as, and must not 762 be construed to be, a catalog of available implementations or their 763 features. Readers are advised to note that other implementations may 764 exist. 766 According to [RFC7942], "this will allow reviewers and working groups 767 to assign due consideration to documents that have the benefit of 768 running code, which may serve as evidence of valuable experimentation 769 and feedback that have made the implemented protocols more mature. It 770 is up to the individual working groups to use this information as 771 they see fit". 773 Add implementation details once available. 775 8. References 777 8.1. Normative References 779 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 780 Requirement Levels", BCP 14, RFC 2119, March 1997, 781 . 783 [RFC5730] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)", 784 STD 69, RFC 5730, August 2009, 785 . 787 8.2. Informative References 789 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 790 Internet: Timestamps", RFC 3339, July 2002, 791 . 793 [RFC5891] Klensin, J., "Internationalized Domain Names in 794 Applications (IDNA): Protocol", RFC 5891, August 2010, 795 . 797 [RFC4122] Leach, P., Mealling, M. and Salz, R., "A Universally 798 Unique IDentifier (UUID) URN Namespace", RFC 4122, July 799 2015, 800 . 802 [RFC5952] Kawamura, S. and Kawashima, M., "A Recommendation for IPv6 803 Address Text Representation", RFC 5952, August 2010, 804 . 806 [RFC7942] Sheffer, Y. and Farrel, A., "Improving Awareness of 807 Running Code: The Implementation Status Section", RFC 808 7942, July 2016, 809 811 Appendix A. Change History 813 A.1. Change from 00 to 01 815 Removed JSON Schema. Clarified unique id with UUID. Added Common Data 816 Structures for better explanation. Fixed EPP poll response example. 817 Added und fixed References. 819 A.2. Change from 01 to 02 821 Clarified host field. Added TLDs to Common Data Structure. Added 822 Internationalization Considerations. Changed authors address and 823 contact details. 825 A.3. Change from 02 to 03 827 Added date-time Values to Internationalization Considerations. Sorted 828 Terminology and Definitions alphabetically. Changed start and end 829 date-time. Changed Reference URI to HTTPS. 831 A.4. Change from 03 to 04 833 Added Acknowledgements. Clarified UUID field to be not changed at all 834 Clarified environment field with production, ote, staging and dev. 835 Clarified connection and implementation fields. Fixed writing of 836 systems field. Removed author's private address. Moved this draft 837 from Experimental to Standard Track. 839 A.5. Change from 04 to 05 841 Changed title of this draft to be more specific. Added Change Log. 842 Split References into Normative and Informative References. Clarified 843 Common Data Types. Rephrased Abstract and Introduction. Added 844 Implementation Status Section. 846 A.6. Change from 05 to 06 848 Added IANA Considerations. Changed URIs from http to https. Added 849 new main Section 4. EPP Command Mapping. Added new JSON field purpose 850 for announce, change or cancel of a maintenance notification. 852 A.7. Change from 06 to 07 854 Fixed typo in Section 3.4. and added missing comma in the example of 855 Section 4.1. Added the field specification to help facilitate the 856 adoption of this document. Changed possible purposes to create, 857 update and delete to be closer to the EPP syntax. Cleaned 858 whitespaces. Updated Acknowledgements. 860 A.8. Change from 07 to EPPMAINT 00 862 Removed JSON payload in message and switched to specific 863 EPP message. Extended EPP command to provide details 864 on specific maintenance or list all maintenances. 866 A.9. Change from EPPMAINT 00 to EPPMAINT 01 868 Fixed typos and added missing change log text for EPPMAINT 00. 869 Added BEGIN and END flag to XML schema. Removed Character Encoding 870 Section. Fixed indentation in Section 2.3. 872 A.10. Change from EPPMAINT 01 to EPPMAINT 02 874 Changed the element to . Fixed 875 indentation in Section 4.1. Cleaned up whitespaces. 877 A.11. Change from EPPMAINT 02 to EPPMAINT03 879 Changed reference from RFC3492 to RFC5891. Fixed minor typos. 880 Added for a freeform maintenance description 881 with a maximum length of 1024. Added optional "msg" attribute to 882 and . 884 Appendix B. Acknowledgements 886 The author wishes to thank the following persons for their feedback 887 and suggestions (sorted alphabetically by company): 889 * Neal McPherson of 1&1 Internet 890 * Christopher Martens of Donuts 891 * Jody Kolker and Roger Carney of GoDaddy 892 * Raymond Zylstra of Neustar 893 * Patrick Mevzek of Uniregistry 894 * Andreas Huber of united-domains 895 * Craig Marchant of VentraIP 896 * James Gould of Verisign 898 Author's Address 900 Tobias Sattler 902 Email: tobias.sattler@me.com 903 URI: https://tobiassattler.com