Network Working Group A. Mayrhofer Internet-Draft nic.at Intended status: Informational October 23, 2014 Expires: April 26, 2015 EPP Service Messages Extension draft-mayrhofer-eppext-servicemessage-00 Abstract EPP contains a mechanism to convey service messages to clients via the "poll" query command. This document specifies an extension defining a simple structured format for including additional information in service messages. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on April 26, 2015. Copyright Notice Copyright (c) 2014 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 (http://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 Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Mayrhofer Expires April 26, 2015 [Page 1] Internet-Draft EPP Service Messages Extension October 2014 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 3. EPP Command Mapping . . . . . . . . . . . . . . . . . . . . . 3 3.1. EPP Query Commands . . . . . . . . . . . . . . . . . . . 3 3.1.1. EPP Command . . . . . . . . . . . . . . . . . 3 3.1.2. Other Query Commands . . . . . . . . . . . . . . . . 4 3.2. EPP Transform Commands . . . . . . . . . . . . . . . . . 4 3.3. Examples . . . . . . . . . . . . . . . . . . . . . . . . 4 3.4. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . 8 4. Security Considerations . . . . . . . . . . . . . . . . . . . 10 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 11 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 7.1. Normative References . . . . . . . . . . . . . . . . . . 11 7.2. Informative References . . . . . . . . . . . . . . . . . 11 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 12 1. Introduction The Extensible Provisioning Protocol (EPP) [RFC5730] specifies a queue-based mechanism to convey service messages to clients. Clients can discover, retrieve and acknowledge such service messages via the "poll" query command. This mechanism is widely used in deployments of EPP servers. The contents of service messages is extensible. While EPP Object Mappings define object-specific messages for some specific situations (For example, see Section 3.3 of [RFC5732]), there is no generic structure defined for the many other situations in which domain name registries require conveying additional information. Such situations include: o Notifying a registrar if (and which) additional objects were transferred automatically together with a domain name. o Sending warnings to registrars when their credit level reaches a low water mark. o Providing a list of domain names that were auto-renewed by the registry on behalf of the client. o Sending warning messages to clients when objects in the registry are about to expire (or have expired recently). As outlined above, information to be sent in such "additional" service messages is typically (although not always) structured. For Mayrhofer Expires April 26, 2015 [Page 2] Internet-Draft EPP Service Messages Extension October 2014 interopability reasons, while it is highly desireable to keep a certain level of structure when conveying this information to clients, a proliferation of custom extensions for each and every situation should be avoided. This document specifies such a structure as an extension to the "resData" element of EPP service messages. The specification follows the guidelines contained in [RFC3735]. 2. Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. 3. EPP Command Mapping 3.1. EPP Query Commands 3.1.1. EPP Command This extension adds elements to the response to a command with the "op" attribute set to "req". Specifically, a "message" element is added to the "resData" section of the service message, containing the following elements/attributes: o A REQUIRED "type" attribute that identifies the type of service message. The definition of values for this attribute is subject to local server policy. o A REQUIRED "desc" element that contains free form text. o An OPTIONAL "reftrID" element ("reference transaction identifier") containing: * An OPTIONAL "clTRID" element that contains the client transaction identifier of the EPP transaction that instigated the service mesage. * A REQUIRED "svTRID" element that contains the server transaction identifier of the EPP transaction that instigated the service message. o An OPTIONAL "data" element, containing at least one of: * Zero or more OPTIONAL "entry" elements. Each "entry" element contains a REQUIRED "name" attribute. These elements transport Mayrhofer Expires April 26, 2015 [Page 3] Internet-Draft EPP Service Messages Extension October 2014 key/value tuples. The definition of values for the "name" attribute is subject to local server policy. * An OPTIONAL "request" element, containing an EPP request frame related to this service message. * An OPTIONAL "response" element, containing an EPP response frame related to this service message. Note that if both "request" and "response" elements are used, their contents MUST be from the same EPP transaction. * An OPTIONAL "any other" element from "any other" namespace - Note that this is used for legacy reasons in some situations to include EPP frames outside of the request/response elements pair, or other data. This extension does not add any elements to the command nor to the response of the command with the "op" attribute set to "ack". 3.1.2. Other Query Commands This extension does not add any elements to the , and query commands. 3.2. EPP Transform Commands This extension does not add any elements to any of the EPP transform commands (, , , , ). 3.3. Examples The following example informs a client that an inbound transfer was approved, and two subordinate host objects were automatically transferred together with the domain name: Mayrhofer Expires April 26, 2015 [Page 4] Internet-Draft EPP Service Messages Extension October 2014 Command completed successfully; ack to dequeue 2013-11-27T04:04:51.0Z Transfer Approved. test.example clientApproved reg1 2013-11-27T04:03:29.0Z reg2 2013-11-27T04:04:51.0Z Inbound transfer of test.example was APPROVED. Subordinate hosts ns1.test.example, ns2.test.example were also transferred. ns1.test.example ns2.test.example 123 In this example, the extension is used to inform a client that some domain names have expired recently: Mayrhofer Expires April 26, 2015 [Page 5] Internet-Draft EPP Service Messages Extension October 2014 Command completed successfully; ack to dequeue 2016-02-25T13:46:36.879301Z The following domains have expired as of 2016-02-25: test-expire1.example, test-expire2.example The following domains have expired as of 2016-02-25: test-expire1.example, test-expire2.example 2016-02-25 test-expire1.example test-expire2.example AD59FECE-5928-11E4-8467-BBC5AB10F032 20141021134636989450F6-primary-tldbox An interesting use case of this extension is when (for whatever reason) the connection between an EPP server and an EPP client fails while a request is being processed. Subsequently, the server cannot provide the client with the response frame. The following example illustrates how the response frame can be submitted to the client using this extension: Mayrhofer Expires April 26, 2015 [Page 6] Internet-Draft EPP Service Messages Extension October 2014 Command completed successfully; ack to dequeue 2014-10-21T14:31:54.524131Z EPP response to command with client-id [05908A94-592F-11E4-ABEA-51CFAB10F032] and server-id [20141021143201978589AD-secondary-tldbox] EPP response to command with client-id [05908A94-592F-11E4-ABEA-51CFAB10F032] and server-id [20141021143201978589AD-secondary-tldbox] Command completed successfully test-connection-interrupt.example 2014-10-21T14:32:01.984360Z 2015-10-21T14:32:01.984360Z 05908A94-592F-11E4-ABEA-51CFAB10F032 20141021143201978589AD-secondary-tldbox 06706F24-592F-11E4-ABEA-51CFAB10F032 20141021143203441442CD-primary-tldbox Note that, in the example above, the EPP response frame is included as a child element of the "data" element directly, using the "any" Mayrhofer Expires April 26, 2015 [Page 7] Internet-Draft EPP Service Messages Extension October 2014 element of the Schema. This is for legacy reasons of the current implementation, since the Schema described also allows an explicit "response" element that should be preferred for including EPP response frames. The example might be updated as the implementation is adapted. The following example informs a client that - for reasons that are outside of the scope of this document - status values on one of the domain names under his sponsorship have been set: Command completed successfully; ack to dequeue 2014-12-28T13:48:22.097813Z Status(es) added to domain [test---0039888rbx-vvgobook5xl4.tldbox]: serverUpdateProhibited (testcase comment freeze (2014-12-28T13:48:22.097813Z)), serverTransferProhibited (testcase comment freeze (2014-12-28T13:48:22.097813Z)) Status(es) added to domain [test-freeze.example]: serverUpdateProhibited (testcase comment freeze (2014-12-28T13:48:22.097813Z)), serverTransferProhibited (testcase comment freeze (2014-12-28T13:48:22.097813Z)) test-freeze.example serverUpdateProhibited testcase comment freeze (2014-12-28T13:48:22.097813Z) serverTransferProhibited testcase comment freeze (2014-12-28T13:48:22.097813Z) 40FD1B64-5ABB-11E4-BFE1-587CAB10F032 2014102313482238365346-primary-tldbox 3.4. Formal Syntax The XML Schema of the extension is as follows: Mayrhofer Expires April 26, 2015 [Page 8] Internet-Draft EPP Service Messages Extension October 2014 Extensible Provisioning Protocol v1.0 nic.at Service Message extension draft-mayrhofer-eppext-servicemessage-00 Mayrhofer Expires April 26, 2015 [Page 9] Internet-Draft EPP Service Messages Extension October 2014 4. Security Considerations This extension allows for inclusion of arbitrary EPP frames in service messages. Since EPP frames can include sensitive information, implementations MUST carefully consider risks related to the use of that mechanism, especially whenever EPP frames from other clients are involved. For example, a "login" frame typically contains authentication credentials, and hence MUST NOT be exposed to a third party client. 5. IANA Considerations IANA is requested to register the specified extension with the "Extensions for the Extensible Provisioning Protocol Registry" ([draft-ietf-eppext-reg-09.txt]). The required registration information is contained below: Mayrhofer Expires April 26, 2015 [Page 10] Internet-Draft EPP Service Messages Extension October 2014 -----BEGIN FORM----- Name of Extension: "EPP Service Messages Extension" Document Status: Informational Reference: http://tools.ietf.org/html/draft-mayrhofer-eppext-servicemessage-01 Registrant Name and Email Address: Alexander Mayrhofer, alexander.mayrhofer@nic.at TLDs: .at, .berlin, .brussels, .hamburg, .reise, .tirol, .versicherung, .vlaanderen, .voting, .wien IPR Disclosure: None Status: Active Notes: The .at TLD currently uses the schema under a different namespace identifier -----END FORM----- 6. Acknowledgements The extension was specified and implemented by Achim Adam, Bernhard Reutner-Fischer, Marcel Gruenauer and Mark Hofstetter. Achim Adam also performed reviews, suggested text, and provided the examples contained in this document. 7. References 7.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC5730] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)", STD 69, RFC 5730, August 2009. 7.2. Informative References [RFC3735] Hollenbeck, S., "Guidelines for Extending the Extensible Provisioning Protocol (EPP)", RFC 3735, March 2004. Mayrhofer Expires April 26, 2015 [Page 11] Internet-Draft EPP Service Messages Extension October 2014 [RFC5732] Hollenbeck, S., "Extensible Provisioning Protocol (EPP) Host Mapping", STD 69, RFC 5732, August 2009. Author's Address A. Mayrhofer nic.at GmbH Jakob-Haringer-Strasse 8 Salzburg 5020 AT Email: alexander.mayrhofer@nic.at Mayrhofer Expires April 26, 2015 [Page 12]