idnits 2.17.1 draft-sattler-epp-registry-maintenance-04.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 23, 2018) is 2224 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 23, 2018 3 Intended status: Standard Track 4 Expires: September 22, 2018 6 Registry Maintenance Notifications for the 7 Extensible Provisioning Protocol (EPP) 8 draft-sattler-epp-registry-maintenance-04 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 22, 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 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 20 87 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 20 89 1. Introduction 91 This document describes an Extensible Provision Protocol (EPP) 92 [RFC5730] mapping for the Registry Maintenance Notifications used 93 when Domain Name Registries will conduct a maintenance, and for 94 retrieving these information. 96 1.1. Terminology and Definitions 98 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 99 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 100 document are to be interpreted as described in [RFC2119] when 101 specified in their uppercase forms. 103 XML is case sensitive. Unless stated otherwise, XML specifications 104 and examples provided in this document MUST be interpreted in the 105 character case presented in order to develop a conforming 106 implementation. 108 In examples, "C:" represents lines sent by a protocol client and 109 "S:" represents lines returned by a protocol server. Indentation and 110 white space in examples are provided only to illustrate element 111 relationships and are not a REQUIRED feature of this protocol. 113 2. Object Attributes 115 2.1. Internationalized Domain Names 117 Names of affected hosts MUST be provided in Punycode according to 118 [RFC5891]. 120 2.2. Dates and Times 122 All dates and times attribute values MUST be expressed in Universal 123 Coordinated Time (UTC) using the Gregorian calendar. The extended 124 date-time form using upper case "T" and "Z" characters defined in ISO 125 8601 [RFC3339] MUST be used to represent date-time values. 127 2.3. Maintenance Elements 129 The element describes a single domain name registry 130 maintenance event during a specific time period. This element will 131 be used at EPP messages and to extend the EPP command. 133 For creating a new maintenance the attribute MUST be 134 'active', the attribute MUST be set and the attribute 135 SHALL NOT be present. 137 For updating a maintenance the attribute MUST be 138 'active', the attributes and MUST be 139 set. 141 For deleting a maintenance the attribute MUST be 142 'inactive', and the attributes and MUST 143 be set. 145 146 MUST be present and an UUID according [RFC4122] and SHALL NOT be 147 changed if maintenance got updated or deleted. A human-readable 148 description of the maintenance is identified via an OPTIONAL 149 "msg" attribute. 151 152 MUST be present and contains one or more elements. 153 The server SHOULD NOT list systems which are not affected by the 154 maintenance. 156 157 MUST be present at least once and is an element of , 158 and 160 161 MUST be present and indicates the name of the affected system, 162 such as 'EPP', 'WHOIS', 'DNS', 'Portal', etc. 164 165 MUST be present and indicates the affected maintained system 166 (host or IP address). 167 Hostname SHALL be Punycode according [RFC5891]. 168 IPv4 addresses SHALL be dotted-decimal notation. 169 An example of this textual representation is "192.0.2.0". 170 IPv6 addresses SHALL be according [RFC5952]. 171 An example of this textual representation is 172 "2001:db8::1:0:0:1". 174 175 MUST be present and contains the impact level; values SHOULD 176 either be 'blackout' or 'partial' 178 179 MUST be present and indicates the type of the affected system; 180 values SHOULD either be 'production', 'ote', 'staging' or 'dev' 182 183 MUST be present and indicates the start of the maintenance 184 according ISO 8601 [RFC3339] 185 Format: YYYY-MM-DDThh:mm:ssTZ 187 188 MUST be present and indicates the end of the maintenance 189 according ISO 8601 [RFC3339] 190 Format: YYYY-MM-DDThh:mm:ssTZ 192 193 MUST be present and contains the reason behind the maintenance; 194 values SHOULD either be 'planned' or 'emergency' 196 197 MAY be present and contains URI to detailed maintenance 198 description 200 201 MAY be present and provides a freeform description of the 202 maintenance without having to create and traverse an external 203 resource. The maximum length MUST NOT exceed 1024 bit. 205 206 MUST be present and contains elements 208 209 MUST be present and contains the affected top-level domain. 210 Punycode encoded according [RFC5891] 212 213 MUST be present and contains and 214 216 217 MUST be present and indicates if a client needs to do something 218 that is connection related, such as a reconnect. The value 219 SHALL boolean. 221 222 MUST be present and indicates if a client needs to do something 223 that is implementation related, such as a code change. The 224 value SHALL be boolean. 226 227 MUST be present and indicates the status of the maintenance. 228 The value SHALL be either 'active' or 'inactive' 230 231 MUST be present and contains the creation date of the maintenance 232 according ISO 8601 [RFC3339] 233 Format: YYYY-MM-DDThh:mm:ssTZ 235 236 MAY be present and contains the updated date of the maintenance 237 according ISO 8601 [RFC3339]. 238 Format: YYYY-MM-DDThh:mm:ssTZ 240 3. EPP Command Mapping 242 A detailed description of the EPP syntax and semantics can be found 243 in the EPP core protocol specification [RFC5730]. The command 244 mappings described here are specifically for the use to notify of 245 Registry Maintenances and Registry Maintenance object mapping. 247 3.1. EPP Query Commands 249 EPP [RFC5730] provides three commands to retrieve object information: 250 to determine if an object is known to the server, to 251 retrieve detailed information associated with an object, and 252 to retrieve object transfer status information. 254 3.1.1. EPP Command 256 Available check semantics do not apply to maintenance objects, so 257 there is no mapping defined for the EPP command. 259 3.1.2. EPP Command 261 Transfer semantics do not apply to maintenance objects, so there is 262 no mapping defined for the EPP command. 264 3.1.3. EPP Command 266 EPP provides the command that is used to retrieve registry 267 maintenance information. In addition to the standard EPP command 268 elements, the command MUST contain a 269 element that identifies the maintenance namespace. The 270 element MUST contain a child element. It is either to 271 retrieve a specific maintenance notification or to 272 query all maintenance notifications. 274 Example command with to get one specific 275 maintenance: 277 C: 278 C: 279 C: 280 C: 281 C: 283 C: 2e6df9b0-4092-4491-bcc8-9fb2166dcee6 284 C: 285 C: 286 C: ABC-12345 287 C: 288 C: 290 Example response for one specific maintenance notification: 292 S: 293 S: 294 S: 295 S: 296 S: Command completed successfully 297 S: 298 S: 299 S: 301 S: 302 S: 2e6df9b0-4092-4491-bcc8-9fb2166dcee6 303 S: 304 S: 305 S: 306 S: EPP 307 S: epp.registry.example 308 S: blackout 309 S: 310 S: 311 S: 312 S: 2017-04-30T06:00:00Z 313 S: 2013-10-22T14:25:57Z 314 S: planned 315 S: 316 S: https://www.registry.example/notice?123 317 S: 318 S: free text 319 S: 320 S: example 321 S: test 322 S: 323 S: 324 S: false 325 S: false 326 S: 327 S: active 328 S: 2017-02-08T22:10:00Z 329 S: 330 S: 331 S: 332 S: 333 S: ABC-12345 334 S: 54321-XYZ 335 S: 336 S: 337 S: 339 Example command with to query all maintenances: 341 C: 342 C: 343 C: 344 C: 345 C: 347 C: 348 C: 349 C: 350 C: ABC-12345 351 C: 352 C: 354 Example response querying all maintenances: 356 S: 357 S: 358 S: 359 S: 360 S: Command completed successfully 361 S: 362 S: 363 S: 365 S: 366 S: 367 S: 2e6df9b0-4092-4491-bcc8-9fb2166dcee6 368 S: 369 S: 2017-04-30T06:00:00Z 370 S: 2017-04-30T07:00:00Z 371 S: 2017-02-08T22:10:00Z 372 S: 373 S: 374 S: 91e9dabf-c4e9-4c19-a56c-78e3e89c2e2f 375 S: 376 S: 2017-06-15T04:30:00Z 377 S: 2017-06-15T05:30:00Z 378 S: 2017-02-08T22:10:00Z 379 S: 2017-03-08T20:11:00Z 380 S: 381 S: 382 S: 383 S: 384 S: 385 S: ABC-12345 386 S: 54321-XYZ 387 S: 388 S: 389 S: 391 3.1.4. EPP Command 393 The EPP command and response is defined in Section 2.9.2.3 of 394 [RFC5730]. The Registry Maintenance Notification is included in the 395 EPP response of [RFC5730]. 397 For the Registry Maintenance Notification, there are three types of 398 poll messages. The poll messages apply whenever the domain name 399 registry creates, updates or deletes a maintenance. In the case of 400 a Registry Maintenance specific message, a element 401 will be included within the element of the standard 402 response. 404 The element will include a reference to the 405 Registry Maintenance namespace. EPP data contained within the 406 element is formatted according to the 407 maintenance-poll schema. 409 Example command: 411 C: 412 C: 413 C: 414 C: 415 C: ABC-12345 416 C: 417 C: 419 Example response with the Registry Maintenance poll message: 421 S: 422 S: 423 S: 424 S: 425 S: Command completed successfully; ack to dequeue 426 S: 427 S: 428 S: 2017-02-08T22:10:00Z 429 S: Registry Maintenance Notification 430 S: 431 S: 432 S: 434 S: 435 S: 2e6df9b0-4092-4491-bcc8-9fb2166dcee6 436 S: 437 S: 438 S: EPP 439 S: epp.registry.example 440 S: blackout 441 S: 442 S: 443 S: 444 S: 2017-04-30T06:00:00Z 445 S: 2013-10-22T14:25:57Z 446 S: planned 447 S: 448 S: https://www.registry.example/notice?123 449 S: 450 S: 451 S: example 452 S: test 453 S: 454 S: 455 S: false 456 S: false 457 S: 458 S: active 459 S: 2017-02-08T22:10:00Z 460 S: 461 S: 462 S: 463 S: 464 S: ABC-12345 465 S: 54321-XYZ 466 S: 467 S: 468 S: 470 3.2. EPP Transform Commands 472 EPP provides five commands to transform objects: to create 473 an instance of an object, to delete an instance of an 474 object, to extend the validity period of an object, 475 to manage object sponsorship changes, and to 476 change information associated with an object. 478 3.2.1. EPP Command 480 Create semantics do not apply to maintenance objects, so there is no 481 mapping defined for the EPP command. 483 3.2.2. EPP Command 485 Delete semantics do not apply to maintenance objects, so there is no 486 mapping defined for the EPP command. 488 3.2.3. EPP Command 490 Renew semantics do not apply to maintenance objects, so there is no 491 mapping defined for the EPP command. 493 3.2.4. EPP Command 495 Transfer semantics do not apply to maintenance objects, so there is 496 no mapping defined for the EPP command. 498 3.2.5. EPP Command 500 Update semantics do not apply to maintenance objects, so there is no 501 mapping defined for the EPP command. 503 4. Formal Syntax 505 One schema is presented here that is the EPP Registry Maintenance 506 schema. 508 The formal syntax presented here is a complete schema representation 509 of the object mapping suitable for automated validation of EPP XML 510 instances. The BEGIN and END tags are not part of the schema; they 511 are used to note the beginning and ending of the schema for URI 512 registration purposes. 514 4.1. Registry Maintenance EPP Mapping Schema 516 BEGIN 517 518 525 528 529 531 532 533 Extensible Provisioning Protocol v1.0 534 Maintenance Mapping Schema. 535 536 538 541 543 546 547 548 549 550 552 553 554 555 556 558 561 562 563 564 565 566 567 569 572 574 577 578 579 580 581 582 584 587 588 589 591 592 594 597 598 599 600 601 602 603 604 605 606 609 610 611 612 613 614 615 616 617 618 620 621 622 623 624 625 626 628 631 632 633 635 636 638 641 642 643 644 645 646 648 651 652 653 654 655 657 660 661 662 663 664 665 666 668 671 672 673 674 675 676 677 678 679 681 684 685 686 687 688 689 690 691 693 696 697 698 699 700 701 703 706 707 708 710 711 712 715 716 717 718 719 720 722 725 726 727 728 729 730 732 735 736 END 738 5. IANA Considerations 740 TBD 742 6. Security Considerations 744 The mapping extensions described in this document do not provide any 745 security services beyond those described by EPP [RFC5730] and 746 protocol layers used by EPP. The security considerations described in 747 these other specifications apply to this specification as well. 749 7. Implementation Status 751 Note to RFC Editor: Please remove this section and the reference to 752 [RFC7942] before publication. 754 This section records the status of known implementations of the 755 protocol defined by this specification at the time of posting of this 756 Internet-Draft, and is based on a proposal described in [RFC7942]. 757 The description of implementations in this section is intended to 758 assist the IETF in its decision processes in progressing drafts to 759 RFCs. Please note that the listing of any individual implementation 760 here does not imply endorsement by the IETF. Furthermore, no effort 761 has been spent to verify the information presented here that was 762 supplied by IETF contributors. This is not intended as, and must not 763 be construed to be, a catalog of available implementations or their 764 features. Readers are advised to note that other implementations may 765 exist. 767 According to [RFC7942], "this will allow reviewers and working groups 768 to assign due consideration to documents that have the benefit of 769 running code, which may serve as evidence of valuable experimentation 770 and feedback that have made the implemented protocols more mature. It 771 is up to the individual working groups to use this information as 772 they see fit". 774 Add implementation details once available. 776 8. References 778 8.1. Normative References 780 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 781 Requirement Levels", BCP 14, RFC 2119, March 1997, 782 . 784 [RFC5730] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)", 785 STD 69, RFC 5730, August 2009, 786 . 788 8.2. Informative References 790 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 791 Internet: Timestamps", RFC 3339, July 2002, 792 . 794 [RFC5891] Klensin, J., "Internationalized Domain Names in 795 Applications (IDNA): Protocol", RFC 5891, August 2010, 796 . 798 [RFC4122] Leach, P., Mealling, M. and Salz, R., "A Universally 799 Unique IDentifier (UUID) URN Namespace", RFC 4122, July 800 2015, 801 . 803 [RFC5952] Kawamura, S. and Kawashima, M., "A Recommendation for IPv6 804 Address Text Representation", RFC 5952, August 2010, 805 . 807 [RFC7942] Sheffer, Y. and Farrel, A., "Improving Awareness of 808 Running Code: The Implementation Status Section", RFC 809 7942, July 2016, 810 812 Appendix A. Change History 814 A.1. Change from 00 to 01 816 Removed JSON Schema. Clarified unique id with UUID. Added Common Data 817 Structures for better explanation. Fixed EPP poll response example. 818 Added und fixed References. 820 A.2. Change from 01 to 02 822 Clarified host field. Added TLDs to Common Data Structure. Added 823 Internationalization Considerations. Changed authors address and 824 contact details. 826 A.3. Change from 02 to 03 828 Added date-time Values to Internationalization Considerations. Sorted 829 Terminology and Definitions alphabetically. Changed start and end 830 date-time. Changed Reference URI to HTTPS. 832 A.4. Change from 03 to 04 834 Added Acknowledgements. Clarified UUID field to be not changed at all 835 Clarified environment field with production, ote, staging and dev. 836 Clarified connection and implementation fields. Fixed writing of 837 systems field. Removed author's private address. Moved this draft 838 from Experimental to Standard Track. 840 A.5. Change from 04 to 05 842 Changed title of this draft to be more specific. Added Change Log. 843 Split References into Normative and Informative References. Clarified 844 Common Data Types. Rephrased Abstract and Introduction. Added 845 Implementation Status Section. 847 A.6. Change from 05 to 06 849 Added IANA Considerations. Changed URIs from http to https. Added 850 new main Section 4. EPP Command Mapping. Added new JSON field purpose 851 for announce, change or cancel of a maintenance notification. 853 A.7. Change from 06 to 07 855 Fixed typo in Section 3.4. and added missing comma in the example of 856 Section 4.1. Added the field specification to help facilitate the 857 adoption of this document. Changed possible purposes to create, 858 update and delete to be closer to the EPP syntax. Cleaned 859 whitespaces. Updated Acknowledgements. 861 A.8. Change from 07 to EPPMAINT 00 863 Removed JSON payload in message and switched to specific 864 EPP message. Extended EPP command to provide details 865 on specific maintenance or list all maintenances. 867 A.9. Change from EPPMAINT 00 to EPPMAINT 01 869 Fixed typos and added missing change log text for EPPMAINT 00. 870 Added BEGIN and END flag to XML schema. Removed Character Encoding 871 Section. Fixed indentation in Section 2.3. 873 A.10. Change from EPPMAINT 01 to EPPMAINT 02 875 Changed the element to . Fixed 876 indentation in Section 4.1. Cleaned up whitespaces. 878 A.11. Change from EPPMAINT 02 to EPPMAINT 03 880 Changed reference from RFC3492 to RFC5891. Fixed minor typos. 881 Added for a freeform maintenance description 882 with a maximum length of 1024. Added optional "msg" attribute to 883 and . 885 A.12. Change from EPPMAINT 03 to EPPMAINT 04 887 Fixed minor typos and added one acknowledgement. 889 Appendix B. Acknowledgements 891 The author wishes to thank the following persons for their feedback 892 and suggestions (sorted alphabetically by company): 894 * Neal McPherson of 1&1 Internet 895 * Anthony Eden of DNSimple 896 * Christopher Martens of Donuts 897 * Jody Kolker and Roger Carney of GoDaddy 898 * Raymond Zylstra of Neustar 899 * Patrick Mevzek of Uniregistry 900 * Andreas Huber of united-domains 901 * Craig Marchant of VentraIP 902 * James Gould of Verisign 904 Author's Address 906 Tobias Sattler 908 Email: tobias.sattler@me.com 909 URI: https://tobiassattler.com