idnits 2.17.1 draft-sattler-epp-registry-maintenance-05.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 29, 2018) is 2219 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 29, 2018 3 Intended status: Standard Track 4 Expires: September 28, 2018 6 Registry Maintenance Notifications for the 7 Extensible Provisioning Protocol (EPP) 8 draft-sattler-epp-registry-maintenance-05 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 28, 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 A.12. Change from EPPMAINT 03 to EPPMAINT 04 . . . . . . . . . 19 86 A.13. Change from EPPMAINT 04 to EPPMAINT 05 . . . . . . . . . 19 87 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 20 88 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 20 90 1. Introduction 92 This document describes an Extensible Provision Protocol (EPP) 93 [RFC5730] mapping for the Registry Maintenance Notifications used 94 when Domain Name Registries will conduct a maintenance, and for 95 retrieving these information. 97 1.1. Terminology and Definitions 99 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 100 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 101 document are to be interpreted as described in [RFC2119] when 102 specified in their uppercase forms. 104 XML is case sensitive. Unless stated otherwise, XML specifications 105 and examples provided in this document MUST be interpreted in the 106 character case presented in order to develop a conforming 107 implementation. 109 In examples, "C:" represents lines sent by a protocol client and 110 "S:" represents lines returned by a protocol server. Indentation and 111 white space in examples are provided only to illustrate element 112 relationships and are not a REQUIRED feature of this protocol. 114 2. Object Attributes 116 2.1. Internationalized Domain Names 118 Names of affected hosts MUST be provided in Punycode according to 119 [RFC5891]. 121 2.2. Dates and Times 123 All dates and times attribute values MUST be expressed in Universal 124 Coordinated Time (UTC) using the Gregorian calendar. The extended 125 date-time form using upper case "T" and "Z" characters defined in ISO 126 8601 [RFC3339] MUST be used to represent date-time values. 128 2.3. Maintenance Elements 130 The element describes a single domain name registry 131 maintenance event during a specific time period. This element will 132 be used at EPP messages and to extend the EPP command. 134 For creating a new maintenance the attribute MUST be 135 'active', the attribute MUST be set and the attribute 136 SHALL NOT be present. 138 For updating a maintenance the attribute MUST be 139 'active', the attributes and MUST be 140 set. 142 For deleting a maintenance the attribute MUST be 143 'inactive', and the attributes and MUST 144 be set. 146 147 MUST be present and an UUID according [RFC4122] and SHALL NOT be 148 changed if maintenance got updated or deleted. A human-readable 149 description of the maintenance is identified via an OPTIONAL 150 "msg" attribute. 152 153 MUST be present and contains one or more elements. 154 The server SHOULD NOT list systems which are not affected by the 155 maintenance. 157 158 MUST be present at least once and is an element of , 159 and 161 162 MUST be present and indicates the name of the affected system, 163 such as 'EPP', 'WHOIS', 'DNS', 'Portal', etc. 165 166 MUST be present and indicates the affected maintained system 167 (host or IP address). 168 Hostname SHALL be Punycode according [RFC5891]. 169 IPv4 addresses SHALL be dotted-decimal notation. 170 An example of this textual representation is "192.0.2.0". 171 IPv6 addresses SHALL be according [RFC5952]. 172 An example of this textual representation is 173 "2001:db8::1:0:0:1". 175 176 MUST be present and contains the impact level; values SHOULD 177 either be 'blackout' or 'partial' 179 180 MUST be present and indicates the type of the affected system; 181 values SHOULD either be 'production', 'ote', 'staging' or 'dev' 183 184 MUST be present and indicates the start of the maintenance 185 according ISO 8601 [RFC3339] 186 Format: YYYY-MM-DDThh:mm:ssTZ 188 189 MUST be present and indicates the end of the maintenance 190 according ISO 8601 [RFC3339], and MUST be equal to or greater 191 than 192 Format: YYYY-MM-DDThh:mm:ssTZ 194 195 MUST be present and contains the reason behind the maintenance; 196 values SHOULD either be 'planned' or 'emergency' 198 199 MAY be present and contains URI to detailed maintenance 200 description 202 203 MAY be present and provides a freeform description of the 204 maintenance without having to create and traverse an external 205 resource. The maximum length MUST NOT exceed 1024 bit. 207 208 MUST be present and contains elements 210 211 MUST be present and contains the affected top-level domain. 212 Punycode encoded according [RFC5891] 214 215 MUST be present and contains and 216 218 219 MUST be present and indicates if a client needs to do something 220 that is connection related, such as a reconnect. The value 221 SHALL boolean. 223 224 MUST be present and indicates if a client needs to do something 225 that is implementation related, such as a code change. The 226 value SHALL be boolean. 228 229 MUST be present and indicates the status of the maintenance. 230 The value SHALL be either 'active' or 'inactive' 232 233 MUST be present and contains the creation date of the maintenance 234 according ISO 8601 [RFC3339] 235 Format: YYYY-MM-DDThh:mm:ssTZ 237 238 MAY be present and contains the updated date of the maintenance 239 according ISO 8601 [RFC3339], and if set MUST be equal to or 240 greater than 241 Format: YYYY-MM-DDThh:mm:ssTZ 243 3. EPP Command Mapping 245 A detailed description of the EPP syntax and semantics can be found 246 in the EPP core protocol specification [RFC5730]. The command 247 mappings described here are specifically for the use to notify of 248 Registry Maintenances and Registry Maintenance object mapping. 250 3.1. EPP Query Commands 252 EPP [RFC5730] provides three commands to retrieve object information: 253 to determine if an object is known to the server, to 254 retrieve detailed information associated with an object, and 255 to retrieve object transfer status information. 257 3.1.1. EPP Command 259 Available check semantics do not apply to maintenance objects, so 260 there is no mapping defined for the EPP command. 262 3.1.2. EPP Command 264 Transfer semantics do not apply to maintenance objects, so there is 265 no mapping defined for the EPP command. 267 3.1.3. EPP Command 269 EPP provides the command that is used to retrieve registry 270 maintenance information. In addition to the standard EPP command 271 elements, the command MUST contain a 272 element that identifies the maintenance namespace. The 273 element MUST contain a child element. It is either to 274 retrieve a specific maintenance notification or to 275 query all maintenance notifications. 277 Example command with to get one specific 278 maintenance: 280 C: 281 C: 282 C: 283 C: 284 C: 286 C: 2e6df9b0-4092-4491-bcc8-9fb2166dcee6 287 C: 288 C: 289 C: ABC-12345 290 C: 291 C: 293 Example response for one specific maintenance notification: 295 S: 296 S: 297 S: 298 S: 299 S: Command completed successfully 300 S: 301 S: 302 S: 304 S: 305 S: 2e6df9b0-4092-4491-bcc8-9fb2166dcee6 306 S: 307 S: 308 S: 309 S: EPP 310 S: epp.registry.example 311 S: blackout 312 S: 313 S: 314 S: 315 S: 2017-09-30T06:00:00Z 316 S: 2017-09-30T14:25:57Z 317 S: planned 318 S: 319 S: https://www.registry.example/notice?123 320 S: 321 S: free text 322 S: 323 S: example 324 S: test 325 S: 326 S: 327 S: false 328 S: false 329 S: 330 S: active 331 S: 2017-03-08T22:10:00Z 332 S: 333 S: 334 S: 335 S: 336 S: ABC-12345 337 S: 54321-XYZ 338 S: 339 S: 340 S: 342 Example command with to query all maintenances: 344 C: 345 C: 346 C: 347 C: 348 C: 350 C: 351 C: 352 C: 353 C: ABC-12345 354 C: 355 C: 357 Example response querying all maintenances: 359 S: 360 S: 361 S: 362 S: 363 S: Command completed successfully 364 S: 365 S: 366 S: 368 S: 369 S: 370 S: 2e6df9b0-4092-4491-bcc8-9fb2166dcee6 371 S: 372 S: 2017-04-30T06:00:00Z 373 S: 2017-04-30T07:00:00Z 374 S: 2017-02-08T22:10:00Z 375 S: 376 S: 377 S: 91e9dabf-c4e9-4c19-a56c-78e3e89c2e2f 378 S: 379 S: 2017-06-15T04:30:00Z 380 S: 2017-06-15T05:30:00Z 381 S: 2017-02-08T22:10:00Z 382 S: 2017-03-08T20:11:00Z 383 S: 384 S: 385 S: 386 S: 387 S: 388 S: ABC-12345 389 S: 54321-XYZ 390 S: 391 S: 392 S: 394 3.1.4. EPP Command 396 The EPP command and response is defined in Section 2.9.2.3 of 397 [RFC5730]. The Registry Maintenance Notification is included in the 398 EPP response of [RFC5730]. 400 For the Registry Maintenance Notification, there are three types of 401 poll messages. The poll messages apply whenever the domain name 402 registry creates, updates or deletes a maintenance. In the case of 403 a Registry Maintenance specific message, a element 404 will be included within the element of the standard 405 response. 407 The element will include a reference to the 408 Registry Maintenance namespace. EPP data contained within the 409 element is formatted according to the 410 maintenance-poll schema. 412 Example command: 414 C: 415 C: 416 C: 417 C: 418 C: ABC-12345 419 C: 420 C: 422 Example response with the Registry Maintenance poll message: 424 S: 425 S: 426 S: 427 S: 428 S: Command completed successfully; ack to dequeue 429 S: 430 S: 431 S: 2017-02-08T22:10:00Z 432 S: Registry Maintenance Notification 433 S: 434 S: 435 S: 437 S: 438 S: 2e6df9b0-4092-4491-bcc8-9fb2166dcee6 439 S: 440 S: 441 S: EPP 442 S: epp.registry.example 443 S: blackout 444 S: 445 S: 446 S: 447 S: 2017-10-30T06:00:00Z 448 S: 2017-10-30T14:25:57Z 449 S: planned 450 S: 451 S: https://www.registry.example/notice?123 452 S: 453 S: 454 S: example 455 S: test 456 S: 457 S: 458 S: false 459 S: false 460 S: 461 S: active 462 S: 2017-02-08T22:10:00Z 463 S: 464 S: 465 S: 466 S: 467 S: ABC-12345 468 S: 54321-XYZ 469 S: 470 S: 471 S: 473 3.2. EPP Transform Commands 475 EPP provides five commands to transform objects: to create 476 an instance of an object, to delete an instance of an 477 object, to extend the validity period of an object, 478 to manage object sponsorship changes, and to 479 change information associated with an object. 481 3.2.1. EPP Command 483 Create semantics do not apply to maintenance objects, so there is no 484 mapping defined for the EPP command. 486 3.2.2. EPP Command 488 Delete semantics do not apply to maintenance objects, so there is no 489 mapping defined for the EPP command. 491 3.2.3. EPP Command 493 Renew semantics do not apply to maintenance objects, so there is no 494 mapping defined for the EPP command. 496 3.2.4. EPP Command 498 Transfer semantics do not apply to maintenance objects, so there is 499 no mapping defined for the EPP command. 501 3.2.5. EPP Command 503 Update semantics do not apply to maintenance objects, so there is no 504 mapping defined for the EPP command. 506 4. Formal Syntax 508 One schema is presented here that is the EPP Registry Maintenance 509 schema. 511 The formal syntax presented here is a complete schema representation 512 of the object mapping suitable for automated validation of EPP XML 513 instances. The BEGIN and END tags are not part of the schema; they 514 are used to note the beginning and ending of the schema for URI 515 registration purposes. 517 4.1. Registry Maintenance EPP Mapping Schema 519 BEGIN 520 521 528 531 532 534 535 536 Extensible Provisioning Protocol v1.0 537 Maintenance Mapping Schema. 538 539 541 544 546 549 550 551 552 553 555 556 557 558 559 561 564 565 566 567 568 569 570 572 575 577 580 581 582 583 584 585 587 590 591 592 594 595 597 600 601 602 603 604 605 606 607 608 609 612 613 614 615 616 617 618 619 620 621 623 624 625 626 627 628 629 631 634 635 636 638 639 641 644 645 646 647 648 649 651 654 655 656 657 658 660 663 664 665 666 667 668 669 671 674 675 676 677 678 679 680 681 682 684 687 688 689 690 691 692 693 694 696 699 700 701 702 703 704 706 709 710 711 713 714 715 718 719 720 721 722 723 725 728 729 730 731 732 733 735 738 739 END 741 5. IANA Considerations 743 TBD 745 6. Security Considerations 747 The mapping extensions described in this document do not provide any 748 security services beyond those described by EPP [RFC5730] and 749 protocol layers used by EPP. The security considerations described in 750 these other specifications apply to this specification as well. 752 7. Implementation Status 754 Note to RFC Editor: Please remove this section and the reference to 755 [RFC7942] before publication. 757 This section records the status of known implementations of the 758 protocol defined by this specification at the time of posting of this 759 Internet-Draft, and is based on a proposal described in [RFC7942]. 760 The description of implementations in this section is intended to 761 assist the IETF in its decision processes in progressing drafts to 762 RFCs. Please note that the listing of any individual implementation 763 here does not imply endorsement by the IETF. Furthermore, no effort 764 has been spent to verify the information presented here that was 765 supplied by IETF contributors. This is not intended as, and must not 766 be construed to be, a catalog of available implementations or their 767 features. Readers are advised to note that other implementations may 768 exist. 770 According to [RFC7942], "this will allow reviewers and working groups 771 to assign due consideration to documents that have the benefit of 772 running code, which may serve as evidence of valuable experimentation 773 and feedback that have made the implemented protocols more mature. It 774 is up to the individual working groups to use this information as 775 they see fit". 777 Add implementation details once available. 779 8. References 781 8.1. Normative References 783 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 784 Requirement Levels", BCP 14, RFC 2119, March 1997, 785 . 787 [RFC5730] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)", 788 STD 69, RFC 5730, August 2009, 789 . 791 8.2. Informative References 793 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 794 Internet: Timestamps", RFC 3339, July 2002, 795 . 797 [RFC5891] Klensin, J., "Internationalized Domain Names in 798 Applications (IDNA): Protocol", RFC 5891, August 2010, 799 . 801 [RFC4122] Leach, P., Mealling, M. and Salz, R., "A Universally 802 Unique IDentifier (UUID) URN Namespace", RFC 4122, July 803 2015, 804 . 806 [RFC5952] Kawamura, S. and Kawashima, M., "A Recommendation for IPv6 807 Address Text Representation", RFC 5952, August 2010, 808 . 810 [RFC7942] Sheffer, Y. and Farrel, A., "Improving Awareness of 811 Running Code: The Implementation Status Section", RFC 812 7942, July 2016, 813 815 Appendix A. Change History 817 A.1. Change from 00 to 01 819 Removed JSON Schema. Clarified unique id with UUID. Added Common Data 820 Structures for better explanation. Fixed EPP poll response example. 821 Added und fixed References. 823 A.2. Change from 01 to 02 825 Clarified host field. Added TLDs to Common Data Structure. Added 826 Internationalization Considerations. Changed authors address and 827 contact details. 829 A.3. Change from 02 to 03 831 Added date-time Values to Internationalization Considerations. Sorted 832 Terminology and Definitions alphabetically. Changed start and end 833 date-time. Changed Reference URI to HTTPS. 835 A.4. Change from 03 to 04 837 Added Acknowledgements. Clarified UUID field to be not changed at all 838 Clarified environment field with production, ote, staging and dev. 839 Clarified connection and implementation fields. Fixed writing of 840 systems field. Removed author's private address. Moved this draft 841 from Experimental to Standard Track. 843 A.5. Change from 04 to 05 845 Changed title of this draft to be more specific. Added Change Log. 846 Split References into Normative and Informative References. Clarified 847 Common Data Types. Rephrased Abstract and Introduction. Added 848 Implementation Status Section. 850 A.6. Change from 05 to 06 852 Added IANA Considerations. Changed URIs from http to https. Added 853 new main Section 4. EPP Command Mapping. Added new JSON field purpose 854 for announce, change or cancel of a maintenance notification. 856 A.7. Change from 06 to 07 858 Fixed typo in Section 3.4. and added missing comma in the example of 859 Section 4.1. Added the field specification to help facilitate the 860 adoption of this document. Changed possible purposes to create, 861 update and delete to be closer to the EPP syntax. Cleaned 862 whitespaces. Updated Acknowledgements. 864 A.8. Change from 07 to EPPMAINT 00 866 Removed JSON payload in message and switched to specific 867 EPP message. Extended EPP command to provide details 868 on specific maintenance or list all maintenances. 870 A.9. Change from EPPMAINT 00 to EPPMAINT 01 872 Fixed typos and added missing change log text for EPPMAINT 00. 873 Added BEGIN and END flag to XML schema. Removed Character Encoding 874 Section. Fixed indentation in Section 2.3. 876 A.10. Change from EPPMAINT 01 to EPPMAINT 02 878 Changed the element to . Fixed 879 indentation in Section 4.1. Cleaned up whitespaces. 881 A.11. Change from EPPMAINT 02 to EPPMAINT 03 883 Changed reference from RFC3492 to RFC5891. Fixed minor typos. 884 Added for a freeform maintenance description 885 with a maximum length of 1024. Added optional "msg" attribute to 886 and . 888 A.12. Change from EPPMAINT 03 to EPPMAINT 04 890 Fixed minor typos and added one acknowledgement. 892 A.13. Change from EPPMAINT 04 to EPPMAINT 05 894 Added missing whitespace. Fixed dates in examples. Added 895 clarification that must be equal to or greater than 896 , same applies for and if 897 set. 899 Appendix B. Acknowledgements 901 The author wishes to thank the following persons for their feedback 902 and suggestions (sorted alphabetically by company): 904 * Neal McPherson of 1&1 Internet 905 * Anthony Eden of DNSimple 906 * Christopher Martens of Donuts 907 * Jody Kolker and Roger Carney of GoDaddy 908 * Raymond Zylstra of Neustar 909 * Patrick Mevzek of Uniregistry 910 * Andreas Huber of united-domains 911 * Craig Marchant of VentraIP 912 * James Gould of Verisign 914 Author's Address 916 Tobias Sattler 918 Email: tobias.sattler@me.com 919 URI: https://tobiassattler.com