From 4bfd864f10b68b71482b35c818559068ef8d5797 Mon Sep 17 00:00:00 2001 From: Thomas Voss Date: Wed, 27 Nov 2024 20:54:24 +0100 Subject: doc: Add RFC documents --- doc/rfc/rfc9167.txt | 981 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 981 insertions(+) create mode 100644 doc/rfc/rfc9167.txt (limited to 'doc/rfc/rfc9167.txt') diff --git a/doc/rfc/rfc9167.txt b/doc/rfc/rfc9167.txt new file mode 100644 index 0000000..96e57ec --- /dev/null +++ b/doc/rfc/rfc9167.txt @@ -0,0 +1,981 @@ + + + + +Internet Engineering Task Force (IETF) T. Sattler +Request for Comments: 9167 +Category: Standards Track R. Carney +ISSN: 2070-1721 J. Kolker + GoDaddy Inc. + December 2021 + + + Registry Maintenance Notification for the Extensible Provisioning + Protocol (EPP) + +Abstract + + This document describes an Extensible Provisioning Protocol (EPP) + extension called "Registry Maintenance Notification", which is used + by EPP servers to notify EPP clients and allow EPP clients to query + EPP servers regarding maintenance events. + +Status of This Memo + + This is an Internet Standards Track document. + + This document is a product of the Internet Engineering Task Force + (IETF). It represents the consensus of the IETF community. It has + received public review and has been approved for publication by the + Internet Engineering Steering Group (IESG). Further information on + Internet Standards is available in Section 2 of RFC 7841. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + https://www.rfc-editor.org/info/rfc9167. + +Copyright Notice + + Copyright (c) 2021 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (https://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + include Revised BSD License text as described in Section 4.e of the + Trust Legal Provisions and are provided without warranty as described + in the Revised BSD License. + +Table of Contents + + 1. Introduction + 1.1. Terminology and Definitions + 2. Migrating to Newer Versions of This Extension + 3. Object Attributes + 3.1. Internationalized Domain Names + 3.2. Dates and Times + 3.3. Maintenance Elements + 4. EPP Command Mapping + 4.1. EPP Query Commands + 4.1.1. EPP Command + 4.1.2. EPP Command + 4.2. EPP Transform Commands + 5. Formal Syntax + 5.1. Registry Maintenance Notification EPP Mapping Schema + 6. IANA Considerations + 6.1. XML Namespace + 6.2. EPP Extension Registry + 7. Security Considerations + 8. References + 8.1. Normative References + 8.2. Informative References + Acknowledgments + Authors' Addresses + +1. Introduction + + The Extensible Provisioning Protocol (EPP), as defined in [RFC5730], + is a protocol whose original motivation is to provide a standard + Internet domain name registration protocol for use between registries + and registrars. + + Registries routinely update systems to ensure a higher quality of + service, implement new services, or upgrade protocols to the latest + standards. These updates are pushed to various registry environments + during time frames communicated to registrars as "maintenance + events". Maintenance events may require making services unavailable + for some limited time while the upgrade happens. Registries usually + inform registrars about maintenance events in various formats, none + of which are standardized between registries. + + The DNS namespace expansion has led to many additional registries + that registrars must interact with, adding more maintenance events + and formats. It is now desirable to provide an efficient approach to + notify registrars. + + This document describes an extension mapping for version 1.0 of the + EPP to provide a mechanism by which EPP servers may notify EPP + clients of and allow EPP clients to query EPP servers on upcoming + maintenance events. + +1.1. Terminology and Definitions + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and + "OPTIONAL" in this document are to be interpreted as described in + BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all + capitals, as shown here. + + XML [W3C.REC-xml-20081126] is case sensitive. Unless stated + otherwise, XML specifications and examples provided in this document + MUST be interpreted in the character case presented in order to + develop a conforming implementation. + + The XML namespace prefix "maint" is used for the namespace + "urn:ietf:params:xml:ns:epp:maintenance-1.0", but implementations + MUST NOT depend on it and instead employ a proper namespace-aware XML + parser and serializer to interpret and output the XML documents. + + "ote" is an abbreviation for "Operational Test and Evaluation". + + In examples, "C:" represents lines sent by a protocol client, and + "S:" represents lines returned by a protocol server. Indentation and + white space in examples are provided only to illustrate element + relationships and are not a required feature of this protocol. + +2. Migrating to Newer Versions of This Extension + + Servers that implement this extension SHOULD provide a way for + clients to progressively update their implementations when a new + version of the extension is deployed. A newer version of the + extension is expected to use an XML namespace with a higher version + number than the prior versions. + + Servers SHOULD (for a temporary migration period up to server policy) + provide support for older versions of the extension in parallel to + the newest version and allow clients to execute their preferred + version of the command based on the maintenance + elements of the server . The version of the maintenance + response MUST match the version of the maintenance + command executed by the server. + + Servers MUST return a Registry Maintenance Notification poll message + matching the newest negotiated version of the maintenance extension, + based on an intersection of the maintenance elements in the + server and the client command. If the + intersection of the maintenance elements of the server + and the client command results in an empty set, + the server MUST return the newest version of the Registry Maintenance + Notification poll message supported by the server based on "Usage + with Poll-Message EPP Responses" in Section 6 of [RFC9038]. + +3. Object Attributes + +3.1. Internationalized Domain Names + + Names of affected hosts MUST be provided in A-label form, according + to [RFC5891]. + +3.2. Dates and Times + + All date and time attribute values MUST be expressed in Universal + Coordinated Time (UTC) using the Gregorian calendar. The date-time + format defined as "date-time" in [RFC3339], with time-offset="Z", + MUST be used. + +3.3. Maintenance Elements + + The element describes a single registry maintenance + event during a specific period. This element is used in a + maintenance item EPP command and response as well as in a + response. + + If an element is not marked as optional, it is mandatory. + + + The server-unique identifier for the maintenance event with the + OPTIONAL "name" attribute that includes a human-readable name of + the event. The server-unique identifier SHALL NOT be changed if + the event is updated or deleted. When the "name" attribute is + set, the OPTIONAL "lang" attribute, per the language structure in + [RFC5646], MAY be present to identify the language if the + negotiated value is something other than the default value of "en" + (English). + + + Zero or more OPTIONAL types of the maintenance event, with the + possible set of values defined by server policy, such as "Routine + Maintenance", "Software Update", "Software Upgrade", or "Extended + Outage". The OPTIONAL "lang" attribute MAY be present to identify + the language if the negotiated value is something other than the + default value of "en" (English). + + + The OPTIONAL element for a Registry Maintenance + Notification poll message; values MUST be "create", "update", + "delete", "courtesy", or "end". For the "create" and "update" + types, the server includes the state of the maintenance event + after the creation or update. For the "delete" type, the server + includes the state of the event before the delete. The "courtesy" + provides a reminder of an event, and the "end" provides a + notification of the end of the event without updating the + maintenance object and includes the latest state of the event. + This element MUST be present only for poll messages. + + + One or more elements that are affected by the + maintenance event. + + + The element contains the following child + elements: + + + The name of the affected system, such as "EPP", "WHOIS", + "DNS", "Portal", "RDAP", etc. + + + The OPTIONAL affected maintained system's hostname, which + SHALL be in A-label form, according to [RFC5891]. + + + The impact level; the values MUST be "full", "partial", or + "none". If access is expected to be intermittently + unavailable, it is "partial". If access is expected to be + completely unavailable, it is "full". If access is not + affected, it is "none". + + + The type of the affected system; the attribute "type" is REQUIRED + and MUST be "production", "ote", "staging", "dev", or "custom". + For extensibility, the element includes the + OPTIONAL "name" attribute that can define the name of the custom + environment when the element "type" attribute + has the "custom" value. For example, for the custom "marketing" + environment, the element should be: + . + + + The date and time of the start of the maintenance event. + + + The date and time of the end of the maintenance event. The + element MUST be greater than the + element. + + + The reason behind the maintenance event; the values MUST be either + "planned" or "emergency". + + + The OPTIONAL URI to the detailed maintenance event description, + formatted according to [RFC3986]. + + + Zero or more OPTIONAL free-form descriptions of the maintenance + event, usable without creating and traversing an external resource + as defined by the element. The OPTIONAL "lang" + attribute MAY be present to identify the language if the + negotiated value is something other than the default value of "en" + (English). The OPTIONAL "type" attribute MAY be present to + identify the format of the description. It MUST be either "plain" + for plain text or "html" for HTML text, as defined in [HTML5], and + XML-escaped, with a default value of "plain". + + + The OPTIONAL element contains one or more + child elements. If the is not present, the entire + system is affected. + + + The affected top-level domain or registry zone, which SHALL be + in A-label form, according to [RFC5891]. + + + + The OPTIONAL element contains the + following child elements: + + + The value SHALL be boolean and indicates if a client needs + to perform a connection-related action such as a reconnect. + The attribute should only be used as a flag to indicate + connections will be affected. Servers SHOULD include a + description of how the connections are affected in the + element or use the + element above. + + + The value SHALL be boolean and indicates if a client needs + to perform an implementation-related action such as a code + change. The attribute should only be used as a flag to + indicate implementation will be affected. Servers SHOULD + include a description of how the implementation is affected + in the element or use the + element above. + + + The date and time of the maintenance object creation. + + + The OPTIONAL date and time of the most recent maintenance + object modification. This element MUST NOT be present if the + maintenance object has never been modified. + +4. EPP Command Mapping + + A detailed description of the EPP syntax and semantics can be found + in the EPP core protocol specification [RFC5730]. The command + mappings described here are specifically used to notify registrars of + registry maintenance events and object mapping. + +4.1. EPP Query Commands + + EPP [RFC5730] provides three commands to retrieve object information: + to determine if an object is known to the server, to + retrieve detailed information associated with an object, and + to retrieve object transfer status information. + + This extension does not add any elements to EPP and + commands or responses. + +4.1.1. EPP Command + + EPP provides the command that is used to retrieve registry + maintenance information. In addition to the standard EPP command + elements, the command MUST contain a element that + identifies the maintenance namespace. + + The element MUST contain a child element. It is either + the child element, described in Section 4.1.1.1, to query + for a specific maintenance item or the child element, + described in Section 4.1.1.2, to query all maintenance items. + +4.1.1.1. Info Maintenance Item + + The information regarding a specific maintenance item can be + retrieved by using the command with the element + and the child element, defined in Section 3.3. If the + maintenance identifier does not exist, the server MUST return an EPP + error result code of 2303 ("Object does not exist") [RFC5730]. + + The following is an example of retrieving a specific maintenance item + in an command. + + C: + C: + C: + C: + C: + C: 2e6df9b0-4092-4491-bcc8-9fb2166dcee6 + C: + C: + C: ABC-12345 + C: + C: + + When an command has been processed successfully, the EPP + element MUST contain a child element that + identifies the maintenance namespace. The element + contains the element defined in Section 3.3. + + The following is an example of returning a specific maintenance item + in an response. + + S: + S: + S: + S: + S: Command completed successfully + S: + S: + S: + S: + S: 2e6df9b0-4092-4491-bcc8-9fb2166dcee6 + S: + S: Routine Maintenance + S: + S: + S: EPP + S: epp.registry.example + S: + S: full + S: + S: + S: + S: 2021-12-30T06:00:00Z + S: 2021-12-30T07:00:00Z + S: planned + S: + S: https://www.registry.example/notice?123 + S: + S: free-text + S: + S: Freitext + S: + S: + S: example + S: test + S: + S: + S: false + S: false + S: + S: 2021-11-08T22:10:00Z + S: + S: + S: + S: + S: ABC-12345 + S: 54321-XYZ + S: + S: + S: + +4.1.1.2. Info Maintenance List + + The information for a list of maintenance items can be retrieved by + using the command with the element and the empty + child element. Server policy determines if completed + maintenance events will be included in the list of maintenance items. + + The following is an example of retrieving the list of maintenance + items in an command. + + C: + C: + C: + C: + C: + C: + C: + C: + C: ABC-12345 + C: + C: + + When an command has been processed successfully, the EPP + element MUST contain a child element that + identifies the maintenance namespace. The element + contains the element with zero or more + child elements. The element contains the following + child elements: + + + The element defined in Section 3.3. + + + The element defined in Section 3.3. + + + The element defined in Section 3.3. + + + The element defined in Section 3.3. + + + The OPTIONAL element defined in Section 3.3. + + The following is an example of returning the list of maintenance + items in an response. + + S: + S: + S: + S: + S: Command completed successfully + S: + S: + S: + S: + S: + S: 2e6df9b0-4092-4491-bcc8-9fb2166dcee6 + S: + S: 2021-12-30T06:00:00Z + S: 2021-12-30T07:00:00Z + S: 2021-11-08T22:10:00Z + S: + S: + S: 91e9dabf-c4e9-4c19-a56c-78e3e89c2e2f + S: + S: 2021-12-15T04:30:00Z + S: 2021-12-15T05:30:00Z + S: 2021-11-08T22:11:00Z + S: 2021-11-17T15:00:00Z + S: + S: + S: + S: + S: + S: ABC-12345 + S: 54321-XYZ + S: + S: + S: + +4.1.2. EPP Command + + The EPP command and response are defined in Section 2.9.2.3 of + [RFC5730]. The Registry Maintenance Notification is included in the + EPP response in [RFC5730]. + + There are five types of poll messages for the Registry Maintenance + Notification, defined by the element in Section 3.3. + A poll message might be generated when a maintenance event is + created, updated, or deleted. A courtesy poll message can be sent as + a reminder of an upcoming maintenance event. An end poll message can + be sent when the maintenance event is completed. In the case of a + message specific to Registry Maintenance, a element + that identifies the maintenance namespace will be included within the + element of the standard response. The + element contains the element defined in + Section 3.3. + + The following is an example of a command: + + C: + C: + C: + C: + C: ABC-12345 + C: + C: + + Example response: + + S: + S: + S: + S: + S: Command completed successfully; ack to dequeue + S: + S: + S: 2021-11-08T22:10:00Z + S: Registry Maintenance Notification + S: + S: + S: + S: + S: 2e6df9b0-4092-4491-bcc8-9fb2166dcee6 + S: create + S: + S: + S: EPP + S: epp.registry.example + S: + S: full + S: + S: + S: + S: 2021-12-30T06:00:00Z + S: 2021-12-30T07:00:00Z + S: planned + S: + S: https://www.registry.example/notice?123 + S: + S: + S: example + S: test + S: + S: + S: false + S: false + S: + S: 2021-11-08T22:10:00Z + S: + S: + S: + S: + S: ABC-12345 + S: 54321-XYZ + S: + S: + S: + +4.2. EPP Transform Commands + + EPP provides five commands to transform objects: to create + an instance of an object, to delete an instance of an + object, to extend the validity period of an object, + to manage object sponsorship changes, and to + change information associated with an object. + + This extension does not add any elements to the EPP , + , , , and commands. + +5. Formal Syntax + + The EPP Registry Maintenance Notification schema is presented here. + + The formal syntax is a complete schema representation of the object + mapping suitable for automated validation of EPP XML instances. The + and tags are not part of the schema; they + are used to note the beginning and end of the schema for URI + registration purposes. + +5.1. Registry Maintenance Notification EPP Mapping Schema + + + + + + + + + + Extensible Provisioning Protocol v1.0 + Registry Maintenance Notification Mapping Schema. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +6. IANA Considerations + +6.1. XML Namespace + + This document uses URNs to describe XML namespaces and XML schemas + conforming to a registry mechanism defined in [RFC3688]. + + The following entry has been registered as an XML namespace: + + URI: urn:ietf:params:xml:ns:epp:maintenance-1.0 + Registrant Contact: IESG + XML: None. Namespace URIs do not represent an XML specification. + + The following entry has been registered to the XML maintenance + schema: + + URI: urn:ietf:params:xml:schema:epp:maintenance-1.0 + Registrant Contact: IESG + XML: See the "Formal Syntax" section of this document. + +6.2. EPP Extension Registry + + The following entry has been added to the "Extensions for the + Extensible Provisioning Protocol (EPP)" registry, described in + [RFC7451]: + + Name of Extension: Registry Maintenance Notification for the + Extensible Provisioning Protocol (EPP) + Document status: Standards Track + Reference: RFC 9167 + Registrant Name and Email Address: IESG + TLDs: Any + IPR Disclosure: None + Status: Active + Notes: None + +7. Security Considerations + + The security considerations of [RFC5730] apply in this document. + Additionally, a server MUST only provide maintenance information to + clients that are authorized. Suppose a client queries a maintenance + identifier that it is not authorized to access per Section 4.1.1.1, + "Info Maintenance Item". In that case, the server SHOULD return an + EPP error result code of 2201 ("Authorization error") or 2303 + ("Object does not exist") [RFC5730]. The list of top-level domains + or registry zones returned in the "Info Maintenance Item" response + SHOULD be filtered based on the top-level domains or registry zones + for which the client is authorized. Authorization of poll messages + is done at the time of poll message insertion and not at the time of + poll message consumption. + +8. References + +8.1. Normative References + + [HTML5] WHATWG, "HTML - Living Standard", December 2021, + . + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, + DOI 10.17487/RFC2119, March 1997, + . + + [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: + Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, + . + + [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform + Resource Identifier (URI): Generic Syntax", STD 66, + RFC 3986, DOI 10.17487/RFC3986, January 2005, + . + + [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying + Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, + September 2009, . + + [RFC5730] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)", + STD 69, RFC 5730, DOI 10.17487/RFC5730, August 2009, + . + + [RFC5891] Klensin, J., "Internationalized Domain Names in + Applications (IDNA): Protocol", RFC 5891, + DOI 10.17487/RFC5891, August 2010, + . + + [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC + 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, + May 2017, . + + [RFC9038] Gould, J. and M. Casanova, "Extensible Provisioning + Protocol (EPP) Unhandled Namespaces", RFC 9038, + DOI 10.17487/RFC9038, May 2021, + . + + [W3C.REC-xml-20081126] + Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and + F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth + Edition)", World Wide Web Consortium Recommendation REC- + xml-20081126, November 2008, + . + +8.2. Informative References + + [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, + DOI 10.17487/RFC3688, January 2004, + . + + [RFC7451] Hollenbeck, S., "Extension Registry for the Extensible + Provisioning Protocol", RFC 7451, DOI 10.17487/RFC7451, + February 2015, . + +Acknowledgments + + The authors wish to thank the following persons for their feedback + and suggestions: James Gould, Michael Bauland, Patrick Mevzek, Quoc- + Anh Pham, Raymond Zylstra, Christopher Martens, Anthony Eden, Neal + McPherson, Craig Marchant, and Andreas Huber. + +Authors' Addresses + + Tobias Sattler + + Email: mail@tobiassattler.com + URI: https://tobiassattler.com + + + Roger Carney + GoDaddy Inc. + 2155 E GoDaddy Way + Tempe, AZ 85284 + United States of America + + Email: rcarney@godaddy.com + URI: https://www.godaddy.com + + + Jody Kolker + GoDaddy Inc. + 2155 E GoDaddy Way + Tempe, AZ 85284 + United States of America + + Email: jkolker@godaddy.com + URI: https://www.godaddy.com -- cgit v1.2.3