| Command Reversal Extension for EPP | September 2026 | |
| Brown & Frakes | Informational | [Page] |
This document describes an Extensible Provisioning Protocol (EPP) extension mapping for reversing previous EPP commands.¶
The source for this document, and an issue tracker, may can be found at https://github.com/gbxyz/epp-reverse-extension.¶
This work is licensed under Creative Commons Attribution 4.0 International. To view a copy of this license, visit https://creativecommons.org/licenses/by/4.0/.¶
The Extensible Provisioning Protocol (EPP) provides a way for clients to create and update objects in a central repository. Usually, the commands that a client sends to a server will have been initiated upon request of a human being. As a result, occasionally a command is sent which contains an error.¶
EPP clients have some options to remedy such mistakes: for example, they can send a <delete> command to delete an object created in error (and may receive a refund if they do so within some grace period), cancel a previous <transfer> request, or send an <update> command to amend the properties of an object.¶
However, there are some circumstances where it is not possible to correct an error by using an existing command. For example, clients may inadvertently send multiple <renew> commands (because their implementation queries the server for a domain's expiry date, thereby defeating the idempotency measures built into EPP) or specify an incorrect period (e.g. a two-year renewal which should have only been for one year).¶
As another example, a client may perform an <update> command on an object, but keep no record of the previous state of the object, preventing them from correcting the error.¶
None of the mistakes in the examples above can be fixed using the existing EPP command repertoire. The extension described in this document attempts to provide an additional remedy for such cases, by providing a way for a client to request that a previous command be reversed. In order to reverse a command, the client need only record the <svTRID> returned by the server in its response to the command.¶
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.¶
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 REQUIRED features of this protocol.¶
A protocol client that is authorized to manage an existing object is described as a "sponsoring" client throughout this document.¶
XML 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.¶
EPP uses XML namespaces to provide an extensible object management framework and to identify schemas required for XML instance parsing and validation. These namespaces and schema definitions are used to identify both the base protocol schema and the schemas for managed objects.¶
The XML namespace prefixes used in examples (such as the string reverse in reverse:reverse) are solely for illustrative purposes.
A conforming implementation MUST NOT require the use of these or any other specific namespace prefixes.¶
In accordance with Section 3.2.2.1 of XML Schema Part 2: Datatypes
[XSD-DATATYPES]
, the allowable lexical representations for the
xs:boolean
datatype are the strings "
0
" and "
false
" for the concept 'false' and the strings "
1
" and "
true
" for the concept 'true'. Implementations
MUST
support both styles of lexical representation.¶
This specification provides a new EPP command, called <reverse>. As the set of EPP command verbs cannot be updated without updating the core EPP specifications, this command is implemented as an extension.¶
When a client wants to reverse a previous command, it sends an EPP command frame containing only an <extension> element. The <extension> element contains a <reverse> element, which in turn contains the details of the command the client wishes to reverse. The <reverse> element has the following child elements:¶
Example <reverse> request frame:¶
C: <?xml version="1.0" encoding="UTF-8"?> C: <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> C: <extension> C: <reverse:reverse C: xmlns:reverse="https://gavinbrown.xyz/xmlns/epp/reverse-1.0"> C: <reverse:reason>Reversing an accidental C: double renewal.</reverse:reason> C: <reverse:trID> C: <reverse:clTRID>ABC-10001</reverse:clTRID> C: <reverse:svTRID>54321-XYZ</reverse:svTRID> C: </reverse:trID> C: <reverse:clTRID>ABC-12345</reverse:clTRID> C: </reverse:reverse> C: </extension> C: </epp>¶
Which commands a server will accept <reverse> commands for is a matter of server policy (which server operators should provide to client operators). If a server acceps a <reverse> command, it MUST respond with a 1000 or 1001 result code. If the server returns a 1001 response, the client MUST be notified of outcome of the offline process via the EPP message queue. If the server rejects the command, it MUST respond with a 2400 result code.¶
Servers MUST NOT perform partial reversals of client commands. If the command cannot be reversed atomically and in full, the server MUST send a 2400 response back to the client.¶
If a server cannot perform a reversal of a client command because of a subsequent update, then it MUST send a 2400 response back to the client.¶
Servers MUST NOT allow a client to reverse a command that it did not originally submit. Servers SHOULD implement policies that flag <reverse> commands for offline processing where changes might have security implications (such as those which would remove client-assigned status codes, alter authorisation information or add or remove secDNS [RFC5910] records, etc).¶
Servers MUST reject a command which attempts to reverse a <reverse> command.¶
Servers which return 1001 response codes to <reverse> commands MUST notify clients of the outcome of the out-of-band process via the EPP message queue. The format of the <poll> message is as follows.¶
The <resData> element of the <poll> response contains a <revData> element which contains a <reTRID> element and a <reDate> element. The <reTRID> element contains an OPTIONAL <clTRID> and a <svTRID> element, which together identify the <reverse> command submitted by the client. The <reTRID> element has a MANDATORY "reResult" element which is a boolean, and which indicates the outcome of the offline review. The <revData> may also contain an OPTIONAL <reDate> element which contains the date and time when the offline review was completed.¶
The <msg> element contains a human-readable message describing the outcome of the review.¶
Example of a <poll> message:¶
S: <?xml version="1.0" encoding="utf-8" standalone="no"?> S: <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> S: <response> S: <result code="1301"> S: <msg>Command completed successfully; ack to dequeue</msg> S: </result> S: <msgQ count="5" id="12345"> S: <qDate>2016-04-04T22:01:00.0Z</qDate> S: <msg>Pending action completed successfully.</msg> S: </msgQ> S: <resData> S: <reverse:revData S: xmlns:reverse="https://gavinbrown.xyz/xmlns/epp/reverse-1.0"> S: <reverse:reTRID reResult="1"> S: <reverse:clTRID>ABC-12345</reverse:clTRID> S: <reverse:svTRID>54321-XYZ</reverse:svTRID> S: </reverse:reTRID> S: <reverse:reDate>2016-04-04T22:00:00.0Z</reverse:reDate> S: </reverse:revData> S: </resData> S: <trID> S: <clTRID>BCD-23456</clTRID> S: <svTRID>65432-WXY</svTRID> S: </trID> S: </response> S: </epp>¶
An EPP object mapping is specified in XML Schema notation. The formal syntax presented here is a complete schema representation of the object mapping suitable for automated validation of EPP XML instances.¶
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.¶
BEGIN
<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:epp="urn:ietf:params:xml:ns:epp-1.0"
xmlns:reverse="https://gavinbrown.xyz/xmlns/epp/reverse-1.0"
targetNamespace="https://gavinbrown.xyz/xmlns/epp/reverse-1.0"
elementFormDefault="qualified">
<annotation>
<documentation>
Extensible Provisioning Protocol v1.0 extension
schema for command reverseal.
</documentation>
</annotation>
<import
namespace="urn:ietf:params:xml:ns:epp-1.0"
schemaLocation="epp-1.0.xsd"/>
<!-- command element -->
<element name="reverse" type="reverse:reverseType"/>
<complexType name="reverseType">
<sequence>
<element name="reason" type="epp:msgType"
minOccurs="0" />
<element name="trID" type="reverse:trIDType"/>
<element name="clTRID" type="epp:trIDStringType"
minOccurs="0" />
</sequence>
</complexType>
<complexType name="trIDType">
<sequence>
<element name="clTRID" type="epp:trIDStringType"
minOccurs="0" />
<element name="svTRID" type="epp:trIDStringType" />
</sequence>
</complexType>
<!-- poll response element -->
<element name="revData" type="reverse:revDataType" />
<complexType name="revDataType">
<sequence>
<element name="reTRID" type="reverse:reTRIDType" />
<element name="reDate" type="dateTime" />
</sequence>
</complexType>
<complexType name="reTRIDType">
<complexContent>
<extension base="reverse:trIDType">
<attribute name="reResult" type="boolean" use="required" />
</extension>
</complexContent>
</complexType>
</schema>
END¶
The mapping extensions described in this document do not provide any security services beyond those described by EPP [RFC5730], and protocol layers used by EPP. The security considerations described in these other specifications apply to this specification as well.¶
This document uses URIs to describe XML namespaces and XML schemas conforming to a registry mechanism described in [RFC3688]. IANA has made the following registrations in the IETF XML Registry [IETF-XML-REGISTRY]:¶
Registration for the XML namespace ("ns" subregistry):¶
URI: https://gavinbrown.xyz/xmlns/epp/reverse-1.0¶
Registrant Contact: See the author of this document¶
XML: None. Namespace URIs do not represent an XML specification¶
Registration for the XML schema ("schema" subregistry):¶
URI: https://gavinbrown.xyz/xmlns/epp/reverse-1.0¶
Registrant Contact: See the author of this document¶
XML: See the "Formal Syntax" section of this document¶
IANA has made the following registration in the Extensions for the "Extensible Provisioning Protocol (EPP)" [EPP-EXTENSION-REGISTRY] registry described in [RFC7451]. The details of the registration are as follows:¶
The authors wish to thank Keith Gaughan and James Gould for early feedback.¶