Internet DRAFT - draft-mayrhofer-eppext-servicemessage
draft-mayrhofer-eppext-servicemessage
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 <poll> 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 <poll> Command
This extension adds elements to the response to a <poll> 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 <poll> command nor to
the response of the <poll> command with the "op" attribute set to
"ack".
3.1.2. Other Query Commands
This extension does not add any elements to the <check>, <info> and
<transfer> query commands.
3.2. EPP Transform Commands
This extension does not add any elements to any of the EPP transform
commands (<create>, <delete>, <renew>, <transfer>, <update>).
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
<epp xsi:schemaLocation="urn:ietf:params:xml:ns:epp-1.0 epp-1.0.xsd">
<response>
<result code="1301">
<msg lang="en-US">Command completed successfully; ack to dequeue</msg>
</result>
<msgQ count="1" id="137526">
<qDate>2013-11-27T04:04:51.0Z</qDate>
<msg lang="en-US">Transfer Approved.</msg>
</msgQ>
<resData>
<domain:trnData xsi:schemaLocation="urn:ietf:params:xml:ns:domain-1.0 domain-1.0.xsd">
<domain:name>test.example</domain:name>
<domain:trStatus>clientApproved</domain:trStatus>
<domain:reID>reg1</domain:reID>
<domain:reDate>2013-11-27T04:03:29.0Z</domain:reDate>
<domain:acID>reg2</domain:acID>
<domain:acDate>2013-11-27T04:04:51.0Z</domain:acDate>
</domain:trnData>
<message xmlns="http://tld-box.at/xmlns/resdata-1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
type="TransferApproved">
<desc>Inbound transfer of test.example was APPROVED.
Subordinate hosts ns1.test.example, ns2.test.example were also
transferred.</desc>
<data>
<entry name="host">ns1.test.example</entry>
<entry name="host">ns2.test.example</entry>
</data>
</message>
</resData>
<trID>
<svTRID>123</svTRID>
</trID>
</response>
</epp>
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
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<epp xmlns="urn:ietf:params:xml:ns:epp-1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<response>
<result code="1301">
<msg>Command completed successfully; ack to dequeue</msg>
</result>
<msgQ count="1" id="2267">
<qDate>2016-02-25T13:46:36.879301Z</qDate>
<msg>The following domains have expired as of 2016-02-25:
test-expire1.example, test-expire2.example</msg>
</msgQ>
<resData>
<message xmlns="http://tld-box.at/xmlns/resdata-1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" type="HasExpired">
<desc>The following domains have expired as of 2016-02-25:
test-expire1.example, test-expire2.example</desc>
<data>
<entry name="date">2016-02-25</entry>
<entry name="domain">test-expire1.example</entry>
<entry name="domain">test-expire2.example</entry>
</data>
</message>
</resData>
<trID>
<clTRID>AD59FECE-5928-11E4-8467-BBC5AB10F032</clTRID>
<svTRID>20141021134636989450F6-primary-tldbox</svTRID>
</trID>
</response>
</epp>
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
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<epp xmlns="urn:ietf:params:xml:ns:epp-1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<response>
<result code="1301">
<msg>Command completed successfully; ack to dequeue</msg>
</result>
<msgQ count="88" id="1816">
<qDate>2014-10-21T14:31:54.524131Z</qDate>
<msg>EPP response to command with client-id [05908A94-592F-11E4-ABEA-51CFAB10F032]
and server-id [20141021143201978589AD-secondary-tldbox]</msg>
</msgQ>
<resData>
<message xmlns="http://tld-box.at/xmlns/resdata-1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" type="ResponseRecovery">
<desc>EPP response to command with client-id [05908A94-592F-11E4-ABEA-51CFAB10F032]
and server-id [20141021143201978589AD-secondary-tldbox]</desc>
<data>
<epp xmlns="urn:ietf:params:xml:ns:epp-1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<response>
<result code="1000">
<msg>Command completed successfully</msg>
</result>
<msgQ count="8" id="1975"/>
<resData>
<domain:creData xmlns:domain="urn:ietf:params:xml:ns:domain-1.0" xmlns="urn:ietf:params:xml:ns:domain-1.0">
<domain:name>test-connection-interrupt.example</domain:name>
<domain:crDate>2014-10-21T14:32:01.984360Z</domain:crDate>
<domain:exDate>2015-10-21T14:32:01.984360Z</domain:exDate>
</domain:creData>
</resData>
<trID>
<clTRID>05908A94-592F-11E4-ABEA-51CFAB10F032</clTRID>
<svTRID>20141021143201978589AD-secondary-tldbox</svTRID>
</trID>
</response>
</epp>
</data>
</message>
</resData>
<trID>
<clTRID>06706F24-592F-11E4-ABEA-51CFAB10F032</clTRID>
<svTRID>20141021143203441442CD-primary-tldbox</svTRID>
</trID>
</response>
</epp>
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:
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<epp xmlns="urn:ietf:params:xml:ns:epp-1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<response>
<result code="1301">
<msg>Command completed successfully; ack to dequeue</msg>
</result>
<msgQ count="1" id="16031">
<qDate>2014-12-28T13:48:22.097813Z</qDate>
<msg>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))</msg>
</msgQ>
<resData>
<message xmlns="http://tld-box.at/xmlns/resdata-1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" type="DelegationStatusSet">
<desc>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))</desc>
<data>
<entry name="domain">test-freeze.example</entry>
<entry name="status">serverUpdateProhibited</entry>
<entry name="comment">testcase comment freeze (2014-12-28T13:48:22.097813Z)</entry>
<entry name="status">serverTransferProhibited</entry>
<entry name="comment">testcase comment freeze (2014-12-28T13:48:22.097813Z)</entry>
</data>
</message>
</resData>
<trID>
<clTRID>40FD1B64-5ABB-11E4-BFE1-587CAB10F032</clTRID>
<svTRID>2014102313482238365346-primary-tldbox</svTRID>
</trID>
</response>
</epp>
3.4. Formal Syntax
The XML Schema of the extension is as follows:
<?xml version="1.0" encoding="UTF-8"?>
Mayrhofer Expires April 26, 2015 [Page 8]
Internet-Draft EPP Service Messages Extension October 2014
<schema targetNamespace="http://tld-box.at/xmlns/resdata-1.1"
xmlns:tld="http://tld-box.at/xmlns/resdata-1.1"
xmlns:epp="urn:ietf:params:xml:ns:epp-1.0"
xmlns="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified">
<!-- Import common element types. -->
<import namespace="urn:ietf:params:xml:ns:epp-1.0"
schemaLocation="epp-1.0.xsd"/>
<annotation>
<documentation>
Extensible Provisioning Protocol v1.0
nic.at Service Message extension
draft-mayrhofer-eppext-servicemessage-00
</documentation>
</annotation>
<!-- service message -->
<element name="message" type="tld:messageType"/>
<complexType name="messageType">
<sequence>
<element name="desc" type="string"/>
<element name="reftrID" type="tld:reftrIDType"
minOccurs="0"/>
<element name="data" type="tld:messageDataType"
minOccurs="0"/>
</sequence>
<attribute name="type" type="tld:messageTypeType"
use="required"/>
</complexType>
<complexType name="frameType">
<sequence>
<any namespace="##other"/>
</sequence>
</complexType>
<complexType name="messageDataType">
<sequence>
<element name="entry" type="tld:attributeType"
maxOccurs="unbounded" minOccurs="0"/>
<element name="request" type="tld:frameType" minOccurs="0"/>
<element name="response" type="tld:frameType" minOccurs="0"/>
<any namespace="##other" minOccurs="0"/>
Mayrhofer Expires April 26, 2015 [Page 9]
Internet-Draft EPP Service Messages Extension October 2014
</sequence>
</complexType>
<simpleType name="messageTypeType">
<restriction base="token">
<maxLength value="100"/>
</restriction>
</simpleType>
<complexType name="reftrIDType">
<sequence>
<element name="clTRID" type="epp:trIDStringType"
minOccurs="0"/>
<element name="svTRID" type="epp:trIDStringType"/>
</sequence>
</complexType>
<!-- attributes -->
<complexType name="attributeType">
<simpleContent>
<extension base="string">
<attribute name="name" type="token"
use="required"/>
</extension>
</simpleContent>
</complexType>
</schema>
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]
