RFC 5730
Extensible Provisioning Protocol (EPP)
Part 1 of 13 💖 more chapters coming, bestie!
Extensible Provisioning Protocol (EPP) 🎀
Okay so this is RFC 5730, and it's giving "the official EPP spec" 💅. It's a Standards Track document, and it's also STD 69, iykyk ✨. S. Hollenbeck from VeriSign, Inc. wrote it, it's part of the Network Working Group series, and it came out in August 2009 🗓️. It obsoletes RFC 4930, so 4930 is officially retired and this one is the new hotness 👑.
Abstract ✨
Bestie, the abstract is serving "here's what we're building" 🦋. It's an application-layer client-server protocol for provisioning and managing objects that live in a shared central repository. It's specified in XML, and it defines generic object management operations plus an extensible framework that maps protocol operations to objects 🧩. The document includes a protocol specification, an object mapping template, and an XML media type registration. Also, it obsoletes RFC 4930 again, because it's that important 🌸.
Status of This Memo 📜
This document specifies an Internet standards track protocol for the Internet community, and it's asking for discussion and suggestions for improvements 💬. For the standardization state and status of this protocol, check the current edition of the "Internet Official Protocol Standards" (STD 1) 🔍. Distribution of this memo is unlimited 🌈.
Copyright Notice ©️
Copyright (c) 2009 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 in effect on the date of publication of this document (http://trustee.ietf.org/license-info). Please read these carefully, bestie, because they describe your rights and restrictions with respect to this document 📖.
Table of Contents 🗺️
1. Introduction ....................................................3
1.1. Conventions Used in This Document ..........................3
2. Protocol Description ............................................4
2.1. Transport Mapping Considerations ...........................7
2.2. Protocol Identification ....................................8
2.3. Hello Format ...............................................8
2.4. Greeting Format ............................................8
2.5. Command Format ............................................12
2.6. Response Format ...........................................13
2.7. Protocol Extension Framework ..............................16
2.7.1. Protocol Extension .................................16
2.7.2. Object Extension ...................................17
2.7.3. Command-Response Extension .........................18
2.8. Object Identification .....................................18
2.9. Protocol Commands .........................................19
2.9.1. Session Management Commands ........................19
2.9.1.1. EPP <login> Command .......................20
2.9.1.2. EPP <logout> Command ......................22
2.9.2. Query Commands .....................................23
2.9.2.1. EPP <check> Command .......................23
2.9.2.2. EPP <info> Command ........................25
2.9.2.3. EPP <poll> Command ........................26
2.9.2.4. EPP <transfer> Query Command ..............30
2.9.3. Object Transform Commands ..........................31
2.9.3.1. EPP <create> Command ......................32
2.9.3.2. EPP <delete> Command ......................33
2.9.3.3. EPP <renew> Command .......................34
2.9.3.4. EPP <transfer> Command ....................35
2.9.3.5. EPP <update> Command ......................38
3. Result Codes ...................................................39
4. Formal Syntax ..................................................45
4.1. Base Schema ...............................................45
4.2. Shared Structure Schema ...................................56
5. Internationalization Considerations ............................59
6. IANA Considerations ............................................59
7. Security Considerations ........................................60
8. Acknowledgements ...............................................61
9. References .....................................................62
9.1. Normative References ......................................62
9.2. Informative References ....................................62
Appendix A. Object Mapping Template ..............................64
Appendix B. Media Type Registration: application/epp+xml .........66
Appendix C. Changes from RFC 4930 ................................671. Introduction ✨
Okay, the intro is where the magic starts 🪄. This document describes the specifications for the Extensible Provisioning Protocol (EPP) version 1.0, which is an XML text protocol. It lets multiple service providers do object-provisioning operations using one shared central object repository 🏪. EPP is specified with Extensible Markup Language (XML) 1.0 as described in [W3C.REC-xml-20040204], and with XML Schema notation as described in [W3C.REC-xmlschema-1-20041028] and [W3C.REC-xmlschema-2-20041028]. And honestly? EPP meets and exceeds the requirements for a generic registry registrar protocol as described in [RFC3375] 😭🔥. This document obsoletes RFC 4930 [RFC4930], as we already covered, so no drama 🫶.
EPP content is identified by the MIME media type application/epp+xml. The registration info for this media type is in an appendix to this document 📎.
EPP is built for diverse operating environments, where transport and security requirements can vary a lot 🌍. It's unlikely that one transport or one security spec will fit every operator, so EPP was designed to run in a layered protocol environment 🍰. Bindings to specific transport and security protocols are outside the scope of this specification, so they're not in here 🙅♀️.
The original motivation for this protocol was to provide a standard Internet domain name registration protocol for use between domain name registrars and domain name registries 🌐. It gives registrar applications a way to talk to registry applications. It's also expected to have additional uses beyond domain name registration, which is so iconic 🦋.
XML is case sensitive, so pay attention to capitalization, bestie 🙈. Unless stated otherwise, XML specifications and examples in this document MUST be interpreted in the character case presented, if you want to build a conforming implementation 💖. That MUST is non-negotiable, no cap.
1.1. Conventions Used in This Document 📏
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] 🧠.
In examples, C: means lines sent by a protocol client, and S: means lines returned by a protocol server 💬. Indentation and white space in examples are only there to show how the elements relate, and they are not REQUIRED features of this protocol, so don't panic if your spacing looks different 🌸. A protocol client that is authorized to manage an existing object is called a "sponsoring" client all the way through this document, and that's the main character of the object's lifecycle 👑.
2. Protocol Description 💖
okay so EPP is a stateful XML protocol that can ride on multiple transport protocols 🚀 Once the lower-layer security protocols are protecting the connection, clients swap identification, authentication, and option info, and then they keep sending client-initiated command-response exchanges. The vibe is very organized. Every EPP command is atomic (no partial success, no partial failure) and designed to be idempotent, which means running a command more than once has the same net effect on system state as running it once. Literally so safe 🫶
EPP gives you four basic service elements: service discovery, commands, responses, and an extension framework. That framework is how you define managed objects and link protocol requests and responses to those objects. Main character energy ✨
Now the server side. A server MUST respond to client-initiated communication (whether that's a lower-layer connection request or an EPP service discovery message) by sending a greeting back to the client 👋 And a server MUST promptly respond to each EPP command with a coordinated response that describes the results of processing that command. Here's the state machine so you can see the whole message exchange flow in detail 🦋
|
V
+-----------------+ +-----------------+
| Waiting for | Connected | Prepare |
| Client |----------------->| Greeting |
+-----------------+ or <hello> +-----------------+
^ |
| Close Connection Send |
| or Idle Greeting |
+-----------------+ V
| End | Timeout +-----------------+
| Session |<-----------------| Waiting for |
+-----------------+ | Client |
^ ^ ^ Send +-------->| Authentication |
| | | Response | +-----------------+
| | | +--------------+ |
| | | | Prepare Fail | | <login>
| | +-----| Response | | Received
| | Send +--------------+ V
| | 2501 ^ +-----------------+
| | Response | | Processing |
| | +---------| <login> |
| | Auth Fail +-----------------+
| | Timeout |
| +-------------------------------+ | Auth OK
| | V
| +-----------------+ <hello> +-----------------+
| | Prepare |<----------| Waiting for |
| | Greeting |---------->| Command or |
| +-----------------+ Send | <hello> |
| Send x5xx Greeting +-----------------+
| Response +-----------------+ Send ^ |
+-----------| Prepare | Response | | Command
| Response |----------+ | Received
+-----------------+ V
^ +-----------------+
Command | | Processing |
Processed +----------| Command |
+-----------------+Figure 1: EPP Server State Machine
EPP commands come in three flavours: session management commands, query commands, and object transform commands. Session management commands start and end persistent sessions with an EPP server. Query commands are read-only, so they just fetch object info. Transform commands are read-write, so they handle object management operations ✏️
Commands are processed by the server in the order the client sent them 📬 The server sends back an immediate response confirming it got and processed the command, but the protocol also has features that let transform commands go through offline review before the requested action is actually finished. In those situations, the response MUST clearly say that the command has been received and processed but that the requested action is pending. The object's state MUST clearly reflect that the pending action is being processed. The server MUST also notify the client once the offline processing is complete. Object mappings SHOULD describe standard formats for the notices that announce completion of offline processing. Organized and iconic 💅
EPP uses XML namespaces for two things: making the object management framework extensible, and identifying the schemas needed for XML instance parsing and validation. These namespaces and schema definitions identify both the base protocol schema and the schemas for managed objects. The namespace prefixes in examples (like the string "foo" in "xmlns:foo") are only there for illustration 🧚 A conforming implementation MUST NOT require the use of these or any other specific namespace prefixes. No gatekeeping prefixes, bestie 🙈
All XML instances SHOULD begin with an <?xml?> declaration. That declaration tells you the XML version in use, can optionally name the character encoding, and can optionally hint to an XML parser that an external schema file is needed to validate the instance. Conformant XML parsers recognize both UTF-8 (defined in RFC 3629 [RFC3629]) and UTF-16 (defined in RFC 2781 [RFC2781]). Per RFC 2277 [RFC2277], UTF-8 is the RECOMMENDED character encoding for EPP 🌸
XML also allows character encodings other than UTF-8 and UTF-16. UTF-8 is the default that XML assumes when there's no "encoding" attribute or byte order mark (BOM), so the "encoding" attribute in the XML declaration is OPTIONAL if you're using UTF-8. EPP clients and servers MUST accept a UTF-8 BOM if one is present, though emitting a UTF-8 BOM is NOT RECOMMENDED 🫧
Example XML declarations:
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<?xml version="1.0" standalone="no"?>
<?xml version="1.0" encoding="UTF-8"?>
<?xml version="1.0"?>2.1. Transport Mapping Considerations 🚚
okay so as we said, EPP can be layered over multiple transport protocols. There's still a set of considerations that MUST be addressed by any transport mapping defined for EPP 📋 Here they are:
- The transport mapping MUST preserve command order.
- The transport mapping MUST address the relationship between sessions and the client-server connection concept.
- The transport mapping MUST preserve the stateful nature of the protocol.
- The transport mapping MUST frame data units.
- The transport mapping MUST be onto a transport, such as TCP [RFC0793] or Stream Control Transmission Protocol (SCTP) [RFC4960], that provides congestion avoidance that follows RFC 2914 [RFC2914]; or, if it maps onto a protocol such as SMTP [RFC5321] or Blocks Extensible Exchange Protocol (BEEP) [RFC3080], then the performance issues need to take into account issues of overload, server availability, and so forth.
- The transport mapping MUST ensure reliability.
- The transport mapping MUST explicitly allow or prohibit pipelining.
Pipelining, also known as command streaming, is when a client sends multiple commands to a server without waiting for each response first. After sending them, the client waits for the responses to show up in the same order as the completed commands 🏃♀️ Pipelining can give you performance gains, especially on high-latency transports, but defining a transport mapping that supports it comes with extra considerations:
- Commands MUST be processed independent of each other.
- Depending on the transport, pipelining MAY be possible in the form of sending a complete session in a well-defined "batch".
- The transport mapping MUST describe how an error in processing a command affects continued operation of the session.
A transport mapping MUST explain how all of these requirements are met, given the transport protocol being used to exchange data. Receipts, please 🧾💜
2.2. Protocol Identification 🪪
All EPP XML instances MUST begin with an <epp> element. This element marks the start of an EPP protocol element and names the namespace used within the protocol. The <epp> start element and its matching </epp> ending element MUST be applied to all structures sent by both clients and servers. No exceptions, the whole family is wrapped 🎀
Example "start" and "end" EPP elements:
<epp xmlns="urn:ietf:params:xml:ns:epp-1.0">
</epp>2.3. Hello Format 👋
EPP MAY be carried over both connection-oriented and connection-less transport protocols. An EPP client MAY request a <greeting> from an EPP server at any time between a successful <login> command and a <logout> command, by sending a <hello> to the server ✨ This is especially useful in a connection-less environment, where a server can't send back a <greeting> in response to a client-initiated connection. An EPP <hello> MUST be an empty element with no child elements. Tiny but mighty 🌈
Example <hello>:
C:<?xml version="1.0" encoding="UTF-8" standalone="no"?>
C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0">
C: <hello/>
C:</epp>2.4. Greeting Format ✨
okay so when a client says hi with a <hello> element and the connection works, the EPP server replies with a <greeting> element 🧚 it's basically the server introducing itself, and a greeting includes all of this:
- An
<svID>element that contains the name of the server. 🏷️ - An
<svDate>element that contains the server's current date and time in Universal Coordinated Time (UTC). ⏰ - An
<svcMenu>element that lists the services the server supports, including:- One or more
<version>elements that identify the protocol versions supported by the server. 🔢 - One or more
<lang>elements that contain the identifiers of the text response languages known by the server. Language identifiers MUST be structured as documented in [RFC4646]. 🌍 - One or more
<objURI>elements that contain namespace URIs representing the objects that the server is capable of managing. A server MAY limit object management privileges on a per-client basis. 🔒 - An OPTIONAL
<svcExtension>element that contains one or more<extURI>elements that contain namespace URIs representing object extensions supported by the server. 🧩 - A
<dcp>(data collection policy) element that contains child elements used to describe the server's privacy policy for data collection and management. Policy implications usually go way beyond the client-server relationship 👀 both clients and servers can have relationships with other entities that need to know the server operator's data collection policy so they can make informed provisioning decisions. Policy information MUST be disclosed to provisioning entities, though how you share policy data outside of direct protocol interaction is beyond the scope of this specification. The child elements are:- An
<access>element that describes the access the server gives the client on behalf of the originating data source. The<access>element MUST contain one of the following child elements:<all/>: Access is given to all identified data.<none/>: No access is provided to identified data.<null/>: Data is not persistent, so no access is possible.<personal/>: Access is given to identified data relating to individuals and organizational entities.<personalAndOther/>: Access is given to identified data relating to individuals, organizational entities, and other data of a non-personal nature.<other/>: Access is given to other identified data of a non-personal nature.
- One or more
<statement>elements that describe data collection purposes, data recipients, and data retention. Each<statement>element MUST contain a<purpose>element, a<recipient>element, and a<retention>element. The<purpose>element MUST contain one or more of the following child elements that describe the purposes for which data is collected:<admin/>: Administrative purposes. Information can be used for administrative and technical support of the provisioning system.<contact/>: Contact for marketing purposes. Information can be used to contact individuals, through a communications channel other than the protocol, for the promotion of a product or service.<prov/>: Object-provisioning purposes. Information can be used to identify objects and inter-object relationships.<other/>: Other purposes. Information may be used in other ways not captured by the above definitions.
- The
<recipient>element MUST contain one or more of the following child elements that describe the recipients of collected data:<other/>: Other entities following unknown practices.<ours>: Server operator and/or entities acting as agents or entities for whom the server operator is acting as an agent. An agent in this instance is defined as a third party that processes data only on behalf of the service provider for the completion of the stated purposes. The<ours>element contains an OPTIONAL<recDesc>element that can be used to describe the recipient.<public/>: Public forums.<same/>: Other entities following server practices.<unrelated/>: Unrelated third parties.
- The
<retention>element MUST contain one of the following child elements that describe data retention practices:<business/>: Data persists per business practices.<indefinite/>: Data persists indefinitely.<legal/>: Data persists per legal requirements.<none/>: Data is not persistent and is not retained for more than a brief period of time necessary to make use of it during the course of a single online interaction.<stated/>: Data persists to meet the stated purpose.
- An OPTIONAL
<expiry>element that describes the lifetime of the policy. The<expiry>element MUST contain one of the following child elements:<absolute/>: The policy is valid from the current date and time until it expires on the specified date and time.<relative/>: The policy is valid from the current date and time until the end of the specified duration.
- An
- One or more
Data collection policy elements are based on work described in the World Wide Web Consortium's Platform for Privacy Preferences [W3C.REC-P3P-20020416] specification. 🔐
Here's an example greeting, so you can see how it all lands together 💖
S:<?xml version="1.0" encoding="UTF-8" standalone="no"?>
S:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0">
S: <greeting>
S: <svID>Example EPP server epp.example.com</svID>
S: <svDate>2000-06-08T22:00:00.0Z</svDate>
S: <svcMenu>
S: <version>1.0</version>
S: <lang>en</lang>
S: <lang>fr</lang>
S: <objURI>urn:ietf:params:xml:ns:obj1</objURI>
S: <objURI>urn:ietf:params:xml:ns:obj2</objURI>
S: <objURI>urn:ietf:params:xml:ns:obj3</objURI>
S: <svcExtension>
S: <extURI>http://custom/obj1ext-1.0</extURI>
S: </svcExtension>
S: </svcMenu>
S: <dcp>
S: <access><all/></access>
S: <statement>
S: <purpose><admin/><prov/></purpose>
S: <recipient><ours/><public/></recipient>
S: <retention><stated/></retention>
S: </statement>
S: </dcp>
S: </greeting>
S:</epp>2.5. Command Format 💅
so this is how the client talks to the server: it sends a command, and the server sends back a response 📬 besides the standard EPP elements, an EPP command has these:
- A command element whose tag matches one of the valid EPP commands described in this document. The command element MAY contain either protocol-specified or object-specified child elements. 🎯
- An OPTIONAL
<extension>element that MAY be used for server-defined command extensions. 🧩 - An OPTIONAL
<clTRID>(client transaction identifier) element that MAY be used to uniquely identify the command to the client. Clients are responsible for maintaining their own transaction identifier space to ensure uniqueness. 🆔
Here's an example command with object-specified child elements 🦋
C:<?xml version="1.0" encoding="UTF-8" standalone="no"?>
C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0">
C: <command>
C: <info>
C: <obj:info xmlns:obj="urn:ietf:params:xml:ns:obj">
C: <obj:name>example</obj:name>
C: </obj:info>
C: </info>
C: <clTRID>ABC-12345</clTRID>
C: </command>
C:</epp>2.6. Response Format ✨
okay so the EPP server always answers a client command with a response, and bestie, EPP commands are atomic 💅. That means a command either succeeds completely or fails completely, no in-between. Success and failure results MUST NOT be mixed. On top of the standard EPP elements, a response has these pieces:
- One or more <result> elements that tell you whether the command worked or flopped. If it was processed successfully, only one <result> element MUST be returned. If it wasn't processed successfully, multiple <result> elements MAY be returned to explain all the failure conditions. Each <result> element has this attribute and these child elements:
- A "code" attribute. Its value is a four-digit, decimal number that describes the success or failure of the command 🔢
- A <msg> element with a human-readable description of the response code. The language is set by an OPTIONAL "lang" attribute. If it isn't specified, the default attribute value MUST be "en" (English) 🇬🇧
- Zero or more OPTIONAL <value> elements that identify a client-provided element (including the XML tag and value) or other information that caused a server error condition 🫣
- Zero or more OPTIONAL <extValue> elements that can give extra error diagnostic info, including:
- A <value> element that identifies the client-provided element (including XML tag and value) that caused a server error condition
- A <reason> element with a human-readable message describing why the error happened. The language is set by an OPTIONAL "lang" attribute. If it isn't specified, the default attribute value MUST be "en" (English) 💀
- An OPTIONAL <msgQ> element that describes messages queued for client retrieval. Here's the tea: a <msgQ> element MUST NOT be present if there are no messages queued for client retrieval. A <msgQ> element MAY be present in responses to EPP commands other than the <poll> command if messages are queued for retrieval. A <msgQ> element MUST be present in responses to the EPP <poll> command if messages are queued for retrieval. The <msgQ> element has these attributes:
- A "count" attribute that describes the number of messages that exist in the queue 🧮
- An "id" attribute used to uniquely identify the message at the head of the queue 🪪
The <msgQ> element also has these OPTIONAL child elements, which MUST be returned in response to a <poll> request command and MUST NOT be returned in response to any other command, including a <poll> acknowledgement:
- A <qDate> element that contains the date and time the message was enqueued 🗓️
- A <msg> element with a human-readable message. The language is set by an OPTIONAL "lang" attribute. If it isn't specified, the default attribute value MUST be "en" (English). This element MAY contain XML content for formatting purposes, but that XML content is not specified by the protocol and will thus not be processed for validity 🎨
- An OPTIONAL <resData> (response data) element that contains child elements specific to the command and associated object 🎁
- An OPTIONAL <extension> element that MAY be used for server-defined response extensions 🧩
- A <trID> (transaction identifier) element containing the transaction identifier the server assigned to the command the response is for. It's formed from the <clTRID> attached to the command (if the client supplied one) and a <svTRID> (server transaction identifier) that the server assigns and keeps unique to itself 🆔
Transaction identifiers give you command-response synchronization integrity 🔗. They SHOULD be logged, retained, and protected so that both the client and the server have consistent temporal and state-management records 📚.
Here's an example response without <value> or <resData>:
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="1000">
S: <msg lang="en">Command completed successfully</msg>
S: </result>
S: <trID>
S: <clTRID>ABC-12345</clTRID>
S: <svTRID>54321-XYZ</svTRID>
S: </trID>
S: </response>
S:</epp>Example response with <resData>:
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="1000">
S: <msg>Command completed successfully</msg>
S: </result>
S: <resData>
S: <obj:creData xmlns:obj="urn:ietf:params:xml:ns:obj">
S: <obj:name>example</obj:name>
S: </obj:creData>
S: </resData>
S: <trID>
S: <clTRID>ABC-12345</clTRID>
S: <svTRID>54321-XYZ</svTRID>
S: </trID>
S: </response>
S:</epp>Example response with error value elements:
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="2004">
S: <msg>Parameter value range error</msg>
S: <value xmlns:obj="urn:ietf:params:xml:ns:obj">
S: <obj:elem1>2525</obj:elem1>
S: </value>
S: </result>
S: <result code="2005">
S: <msg>Parameter value syntax error</msg>
S: <value xmlns:obj="urn:ietf:params:xml:ns:obj">
S: <obj:elem2>ex(ample</obj:elem2>
S: </value>
S: <extValue>
S: <value xmlns:obj="urn:ietf:params:xml:ns:obj">
S: <obj:elem3>abc.ex(ample</obj:elem3>
S: </value>
S: <reason>Invalid character found.</reason>
S: </extValue>
S: </result>
S: <trID>
S: <clTRID>ABC-12345</clTRID>
S: <svTRID>54321-XYZ</svTRID>
S: </trID>
S: </response>
S:</epp>Example response with notice of waiting server messages:
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="1000">
S: <msg>Command completed successfully</msg>
S: </result>
S: <msgQ count="5" id="12345"/>
S: <trID>
S: <clTRID>ABC-12345</clTRID>
S: <svTRID>54321-XYZ</svTRID>
S: </trID>
S: </response>
S:</epp>Command success or failure MUST NOT be assumed if no response is returned or if a returned response is malformed 🚨. Protocol idempotency keeps it safe to retry a command when response delivery fails 🔁.
2.7. Protocol Extension Framework ✨
EPP comes with an extension framework, so features can be added at the protocol, object, and command-response levels. It's giving extensibility 🧚.
2.7.1. Protocol Extension
The EPP extension framework lets you define new protocol elements using XML namespace notation, with a reference to an XML schema that defines the namespace 📛. The <epp> element that starts a protocol instance has several child element choices, and one of them is an <extension> element whose children define the extension. Here's the generic version of a protocol extension element:
C:<epp>
C: <extension>
C: <!-- One or more extension elements. -->
C: <ext:foo xmlns:ext="urn:ietf:params:xml:ns:ext">
C: <!-- One or more extension child elements. -->
C: </ext:foo>
C: </extension>
C:</epp>This document does not define mappings for specific extensions 🙅♀️. Extension specifications MUST be described in separate documents that define the objects and operations subject to the extension 📄.
2.7.2. Object Extension
EPP has an extensible object management framework that defines the syntax and semantics of protocol operations applied to a managed object 🗂️. This framework pushes the definition of each protocol operation into the context of a specific object, so you can add mappings for new objects without touching the base protocol. Iconic 👑.
Protocol elements that hold object-specific data are identified using XML namespace notation with a reference to an XML schema that defines the namespace. The EPP schema supports dynamic object schemas on a per-command and per-response basis. Here's how the start of an object-specific command element looks in generic terms:
C:<EPPCommandName>
C: <object:command xmlns:object="urn:ietf:params:xml:ns:object">
C: <!-- One or more object-specific command elements. -->
C: </object:command>
C:</EPPCommandName>An object-specific response element looks pretty similar:
S:<resData>
S: <object:resData xmlns:object="urn:ietf:params:xml:ns:object">
S: <!-- One or more object-specific response elements. -->
S: </object:resData>
S:</resData>This document does not define mappings for specific objects. The mapping of EPP to an object MUST be described in separate documents that specifically address each command and response in the context of the object 🧾. There's also a suggested object mapping outline included as an appendix to this document 🫶.
2.7.3. Command-Response Extension
EPP has a facility for protocol command and response extensions 🪄. Protocol commands and responses MAY be extended by an <extension> element that contains additional elements whose syntax and semantics aren't explicitly defined by EPP or an EPP object mapping. This element is OPTIONAL. Extensions are typically defined by agreement between client and server, and they MAY be used to extend EPP for unique operational needs 🛠️. Here's how a server-extended command element looks in generic terms:
C:<command>
C: <!-- EPPCommandName can be "create", "update", etc. -->
C: <EPPCommandName>
C: <object:command xmlns:object="urn:ietf:params:xml:ns:object">
C: <!-- One or more object-specific command elements. -->
C: </object:command>
C: </EPPCommandName>
C: <extension>
C: <!-- One or more server-defined elements. -->
C: </extension>
C:</command>A server-extended response element is described similarly:
S:<response>
S: <result code="1000">
S: <msg lang="en">Command completed successfully</msg>
S: </result>
S: <extension>
S: <!-- One or more server-defined elements. -->
S: </extension>
S: <trID>
S: <clTRID>ABC-12345</clTRID>
S: <svTRID>54321-XYZ</svTRID>
S: </trID>
S:</response>This document does not define any specific server extensions 🙅♀️. The mapping of server extensions to EPP MUST be described in separate documents that specifically address extended commands and responses in the server's operational context 🖥️.
2.8. Object Identification ✨
Okay so some objects, like name servers and contacts, are useful in more than one repository 🦋. But keeping separate copies of the same object info across lots of repos gets messy fast, and that mess can cause real problems on the Internet 💀. Like, if you rename a name server in one repo but not in a second repo that uses it for domain name delegation, DNS queries can return unexpected results. Not it 🙅
Globally unique identifiers help repos share object info without the drama 🫶. A globally unique identifier MUST be assigned to every object when the object is created, and the identifier MUST be returned to the client as part of any request to retrieve the detailed attributes of an object. The exact identifier values are up to repository policy, but they SHOULD be built using this algorithm:
- a. Divide the provisioning repository world into a number of object repository classes.
- b. Each repository within a class is assigned an identifier that is maintained by IANA.
- c. Each repository is responsible for assigning a unique local identifier for each object within the repository.
- d. The globally unique identifier is a concatenation of the local identifier, followed by a hyphen (
-, ASCII value0x002D), followed by the repository identifier.
2.9. Protocol Commands 💅
EPP gives you commands to manage sessions, retrieve object info, and do transformation operations on objects 🧚. All EPP commands are atomic and designed so they can be made idempotent, meaning they either succeed completely or fail completely and give predictable results even when you run them again 🔁. This section walks through each EPP command with examples and representative server responses.
2.9.1. Session Management Commands 🎀
EPP has two session commands: <login> to start a session with a server, and <logout> to end one 👋. The <login> command sets up an ongoing server session that keeps the client's identity and authorization info safe for the whole session 🔐.
2.9.1.1. EPP <login> Command 🔑
The <login> command is how you start a session with an EPP server after it sends its greeting 💖. A <login> command MUST be sent to a server before any other EPP command to set up an ongoing session, so no skipping ahead 🙃. Server operators MAY limit the number of failed login attempts N, where 1 <= N <= infinity. If you hit that limit, the connection to the server gets closed (if one exists) 💀.
Before a client can successfully complete a <login> command, a client identifier and initial password MUST be created on the server 🔐. The client identifier and initial password MUST also be delivered to the client using an out-of-band method that protects them from inadvertent disclosure, so nobody spills them by accident 🙈.
In addition to the standard EPP command elements, the <login> command has these child elements:
- A
<clID>element that contains the client identifier the server assigned to the client. - A
<pw>element that contains the client's plain text password. The value of this element is case sensitive. - An OPTIONAL
<newPW>element that contains a new plain text password to be assigned to the client for use with later<login>commands. The value of this element is case sensitive. - An
<options>element that contains these child elements:- A
<version>element that contains the protocol version to be used for the command or ongoing server session. - A
<lang>element that contains the text response language to be used for the command or ongoing server session commands.
- A
The values of the <version> and <lang> elements MUST exactly match one of the values presented in the EPP greeting.
- A
<svcs>element that contains one or more<objURI>elements. These hold the namespace URIs for the objects you'll manage during the session. The<svcs>element MAY contain an OPTIONAL<svcExtension>element, which contains one or more<extURI>elements that identify the object extensions to be used during the session.
The PLAIN Simple Authentication and Security Layer (SASL) mechanism presented in [RFC4616] describes a format for putting a user identifier, an authorization identifier, and a password into one plain-text string 🧠. The EPP authentication mechanism is similar, except EPP doesn't need a session-level authorization identifier, and the user identifier and password live in separate XML elements 🎀. Additional identification and authorization schemes MUST be provided at other protocol layers if you want more robust security services 🛡️.
Here's an example <login> command:
C:<?xml version="1.0" encoding="UTF-8" standalone="no"?>
C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0">
C: <command>
C: <login>
C: <clID>ClientX</clID>
C: <pw>foo-BAR2</pw>
C: <newPW>bar-FOO2</newPW>
C: <options>
C: <version>1.0</version>
C: <lang>en</lang>
C: </options>
C: <svcs>
C: <objURI>urn:ietf:params:xml:ns:obj1</objURI>
C: <objURI>urn:ietf:params:xml:ns:obj2</objURI>
C: <objURI>urn:ietf:params:xml:ns:obj3</objURI>
C: <svcExtension>
C: <extURI>http://custom/obj1ext-1.0</extURI>
C: </svcExtension>
C: </svcs>
C: </login>
C: <clTRID>ABC-12345</clTRID>
C: </command>
C:</epp>When a <login> command has been processed successfully, a server MUST respond with an EPP response that has no <resData> element 🎉. If it works, the server creates and maintains a new session that SHOULD be ended by a future <logout> command 🌸.
Here's an example <login> response:
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="1000">
S: <msg>Command completed successfully</msg>
S: </result>
S: <trID>
S: <clTRID>ABC-12345</clTRID>
S: <svTRID>54321-XYZ</svTRID>
S: </trID>
S: </response>
S:</epp>Recap, bestie: the <login> command establishes a session with an EPP server. A <login> command MUST be rejected if it's received within an existing session 🚫. This command MUST be available to all clients 👑.
2.9.1.2. EPP <logout> Command 🦋
The <logout> command ends a session with an EPP server 🌙. The <logout> command MUST be represented as an empty element with no child elements 🫧.
A server MAY end a session because a client has been inactive or the session has gone on too long ⏰. How long counts as "too inactive" or "too long" is up to server policy, and this protocol doesn't specify it 🤷.
Transport mappings MUST explicitly describe any connection-oriented processing that happens after a <logout> command is processed and the session ends. This one's important, so don't skip it!! 🚨
Here's an example <logout> command:
C:<?xml version="1.0" encoding="UTF-8" standalone="no"?>
C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0">
C: <command>
C: <logout/>
C: <clTRID>ABC-12345</clTRID>
C: </command>
C:</epp>When a <logout> command has been processed successfully, a server MUST respond with an EPP response that has no <resData> element. If that works out, the server MUST also end the current session 🏁.
Here's an example <logout> response:
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="1500">
S: <msg>Command completed successfully; ending session</msg>
S: </result>
S: <trID>
S: <clTRID>ABC-12345</clTRID>
S: <svTRID>54321-XYZ</svTRID>
S: </trID>
S: </response>
S:</epp>Quick recap: the <logout> command ends a session with an EPP server. A <logout> command MUST be rejected if it hasn't been preceded by a successful <login> command 🙅♀️. This command MUST be available to all clients 💜.
2.9.2. Query Commands 🔍
2.9.2.1. EPP <check> Command ✨
okay so the EPP <check> command is basically the "is this name taken?" move 💅 It lets a client find out if an object can be provisioned in a repository before sending a <create> command. It's a hint, not a guarantee, bestie, because whether something actually gets provisioned is up to server policy 🙈
The stuff you need to identify an object is different for every object type, so the child elements of <check> are defined through the EPP extension framework 🧚 On top of the usual EPP command elements, the <check> command has this child element:
- An object-specific
<obj:check>element that identifies the objects to be queried. Multiple objects of the same type MAY be queried within a single<check>command. 🫶
Here's an example <check> command 👇
C:<?xml version="1.0" encoding="UTF-8" standalone="no"?>
C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0">
C: <command>
C: <check>
C: <obj:check xmlns:obj="urn:ietf:params:xml:ns:obj">
C: <obj:name>example1</obj:name>
C: <obj:name>example2</obj:name>
C: <obj:name>example3</obj:name>
C: </obj:check>
C: </check>
C: <clTRID>ABC-12346</clTRID>
C: </command>
C:</epp>When a <check> command gets processed successfully, the server MUST respond with an EPP <resData> element that MUST contain a child element identifying the object namespace. The child elements of <resData> are object-specific, but the EPP <resData> element MUST also contain an <obj:chkData> element holding one or more <obj:cd> (check data) elements 💖 Each <obj:cd> element has these child elements:
- An object-specific element that identifies the queried object. This element MUST contain an "avail" attribute whose value tells you if the object is available (can it be provisioned or not) at the moment the
<check>command finished. A value of "1" or "true" means the object can be provisioned. A value of "0" or "false" means it cannot. ✨ - An OPTIONAL
<obj:reason>element that MAY be provided when an object cannot be provisioned. If it's there, it holds server-specific text explaining why the object can't be provisioned. This text MUST be in the response language that was previously negotiated with the client. An OPTIONAL "lang" attribute MAY be present to identify the language if the negotiated value is something other than the default value of "en" (English) 🌸
Here's an example <check> response 👇
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="1000">
S: <msg>Command completed successfully</msg>
S: </result>
S: <resData>
S: <obj:chkData xmlns:obj="urn:ietf:params:xml:ns:obj">
S: <obj:cd>
S: <obj:name avail="1">example1</obj:name>
S: </obj:cd>
S: <obj:cd>
S: <obj:name avail="0">example2</obj:name>
S: <obj:reason>In use</obj:reason>
S: </obj:cd>
S: <obj:cd>
S: <obj:name avail="1">example3</obj:name>
S: </obj:cd>
S: </obj:chkData>
S: </resData>
S: <trID>
S: <clTRID>ABC-12346</clTRID>
S: <svTRID>54322-XYZ</svTRID>
S: </trID>
S: </response>
S:</epp>The EPP <check> command is used to determine if an object can be provisioned within a repository. This action MUST be open to all authorized clients 🦋
2.9.2.2. EPP <info> Command 🔍
the EPP <info> command is how you pull up information about an object that already exists 👀 Both the stuff needed to identify the object and the type of info you want back are object-specific, so the child elements of <info> are defined through the EPP extension framework too. On top of the standard EPP command elements, the <info> command has this child element:
- An object-specific
<obj:info>element that identifies the object to be queried. 🎀
Here's an example <info> command 👇
C:<?xml version="1.0" encoding="UTF-8" standalone="no"?>
C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0">
C: <command>
C: <info>
C: <obj:info xmlns:obj="urn:ietf:params:xml:ns:obj">
C: <!-- Object-specific elements. -->
C: </obj:info>
C: </info>
C: <clTRID>ABC-12346</clTRID>
C: </command>
C:</epp>When an <info> command gets processed successfully, the server MUST respond with an EPP <resData> element that MUST contain a child element identifying the object namespace and the Repository Object IDentifier (ROID) that was assigned to the object when it was created 🌈 Any other child elements of <resData> are object-specific.
Here's an example <info> response 👇
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="1000">
S: <msg>Command completed successfully</msg>
S: </result>
S: <resData>
S: <obj:infData xmlns:obj="urn:ietf:params:xml:ns:obj">
S: <obj:roid>EXAMPLE1-REP</obj:roid>
S: <!-- Object-specific elements. -->
S: </obj:infData>
S: </resData>
S: <trID>
S: <clTRID>ABC-12346</clTRID>
S: <svTRID>54322-XYZ</svTRID>
S: </trID>
S: </response>
S:</epp>The EPP <info> command is used to retrieve information associated with an existing object. This action SHOULD be limited to authorized clients, and restricting it to the sponsoring client is RECOMMENDED. 🔒 this one's a big deal, so don't skip it, bestie 💀
2.9.2.3. EPP <poll> Command ✨
okay so the <poll> command is how a client digs up service messages the server has queued up just for them 📬. If the queue isn't empty, a successful response to a <poll> command MUST return the first message from the message queue. Every response from the server carries a server-unique message identifier that MUST be provided to acknowledge receipt, plus a counter for how many messages are sitting in the queue 🔢. After the client gets a message, it MUST respond with an explicit acknowledgement to confirm it arrived. Then the server MUST dequeue the message and decrement the counter, which bumps the next message (if there is one) up for retrieval 🎀.
Servers sometimes do things to objects that aren't a direct reply to a client request, or one client's action can indirectly involve a second client 👀. Examples are deletion upon expiration, automatic renewal upon expiration, and transfer coordination. Other types of service information MAY be defined as a matter of server policy 💅. Service messages SHOULD be created for passive clients affected by an action on an object. Service messages MAY also be created for active clients that request an action on an object, though such messages MUST NOT replace the normal protocol response to the request 🙈. For example, <transfer> actions SHOULD be reported to the client that has the authority to approve or reject a transfer request. Other ways of notifying clients, like offline reporting, are also possible, but they're beyond the scope of this specification 🌸.
Message queues can eat server resources if clients don't retrieve and acknowledge messages regularly 💀.
Servers MAY implement other mechanisms to dequeue and deliver messages if queue maintenance needs exceed server resource consumption limits. Server operators SHOULD consider time-sensitivity and resource management factors when picking a delivery method for service information, because some message types can reasonably be delivered using non-protocol methods that need fewer server resources 🧚.
Some of the info in a <poll> response can be object-specific, so some child elements of the <poll> response MAY be specified using the EPP extension framework 🦋. The <poll> command MUST be represented as an empty element with no child elements. An "op" attribute with value "req" is REQUIRED to retrieve the first message from the server message queue. An "op" attribute (with value "ack") and a "msgID" attribute (whose value matches the "id" attribute copied from the <msg> element in the message being acknowledged) are REQUIRED to acknowledge receipt of a message 🫶.
Here's an example <poll> command:
C:<?xml version="1.0" encoding="UTF-8" standalone="no"?>
C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0">
C: <command>
C: <poll op="req"/>
C: <clTRID>ABC-12345</clTRID>
C: </command>
C:</epp>The returned result code tells you a message has been dequeued and returned in response to a <poll> command 🎉.
Here's an example <poll> response with object-specific info 👑:
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>2000-06-08T22:00:00.0Z</qDate>
S: <msg>Transfer requested.</msg>
S: </msgQ>
S: <resData>
S: <obj:trnData
S: xmlns:obj="urn:ietf:params:xml:ns:obj-1.0">
S: <obj:name>example.com</obj:name>
S: <obj:trStatus>pending</obj:trStatus>
S: <obj:reID>ClientX</obj:reID>
S: <obj:reDate>2000-06-08T22:00:00.0Z</obj:reDate>
S: <obj:acID>ClientY</obj:acID>
S: <obj:acDate>2000-06-13T22:00:00.0Z</obj:acDate>
S: <obj:exDate>2002-09-08T22:00:00.0Z</obj:exDate>
S: </obj:trnData>
S: </resData>
S: <trID>
S: <clTRID>ABC-12345</clTRID>
S: <svTRID>54321-XYZ</svTRID>
S: </trID>
S: </response>
S:</epp>A client MUST acknowledge each response so the message gets dequeued and the next ones become available for retrieval 🔥.
Here's the <poll> acknowledgement command:
C:<?xml version="1.0" encoding="UTF-8" standalone="no"?>
C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0">
C: <command>
C: <poll op="ack" msgID="12345"/>
C: <clTRID>ABC-12346</clTRID>
C: </command>
C:</epp>A <poll> acknowledgement response tells you which message was acknowledged and how many messages are left in the queue 📉.
Here's the acknowledgement response:
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="1000">
S: <msg>Command completed successfully</msg>
S: </result>
S: <msgQ count="4" id="12345"/>
S: <trID>
S: <clTRID>ABC-12346</clTRID>
S: <svTRID>54322-XYZ</svTRID>
S: </trID>
S: </response>
S:</epp>Service messages can also come back with no object info at all 🌈.
Here's a <poll> response with mixed message content and no object-specific info:
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="4" id="12346">
S: <qDate>2000-06-08T22:10:00.0Z</qDate>
S: <msg lang="en">Credit balance low.
S: <limit>100</limit><bal>5</bal>
S: </msg>
S: </msgQ>
S: <trID>
S: <clTRID>ABC-12346</clTRID>
S: <svTRID>54321-XYZ</svTRID>
S: </trID>
S: </response>
S:</epp>The result code and message here are how the server says the queue is empty 🫧.
Here's a <poll> response noting an empty message queue:
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="1300">
S: <msg>Command completed successfully; no messages</msg>
S: </result>
S: <trID>
S: <clTRID>ABC-12346</clTRID>
S: <svTRID>54321-XYZ</svTRID>
S: </trID>
S: </response>
S:</epp>Lastly, the EPP <poll> command is how a client pulls service messages from a server 🥹. This action SHOULD be limited to authorized clients. Queuing service messages and limiting queue access on a per-client basis is RECOMMENDED 💜.
2.9.2.4. EPP <transfer> Query Command
The EPP <transfer> command gives you a query operation so a client can check the real-time status of pending and completed transfer requests 🔍. The stuff needed to identify an object in a transfer request is object-specific, so the child elements of the <transfer> query command are specified using the EPP extension framework 🧩. On top of the standard EPP command elements, the <transfer> command has an "op" attribute with value "query" and this child element:
- An object-specific <obj:transfer> element that identifies the object whose transfer status is requested.
Transfer status is usually sensitive info for the clients involved in the operation 🔒. Object mappings MUST provide features to restrict transfer queries to authorized clients, such as by requiring authorization information as part of the request.
Here's an example <transfer> query command:
C:<?xml version="1.0" encoding="UTF-8" standalone="no"?>
C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0">
C: <command>
C: <transfer op="query">
C: <obj:transfer xmlns:obj="urn:ietf:params:xml:ns:obj">
C: <!-- Object-specific elements. -->
C: </obj:transfer>
C: </transfer>
C: <clTRID>ABC-12346</clTRID>
C: </command>
C:</epp>When a <transfer> query command has been processed successfully, a server MUST respond with an EPP <resData> element that MUST contain a child element identifying the object namespace 🌷. The child elements of the <resData> element are object-specific, but they MUST include elements that identify the object, the status of the transfer, the identifier of the client that requested the transfer, the date and time the request was made, the identifier of the client authorized to act on the request, and the date and time by which an action is expected. They can also include an OPTIONAL date and time noting changes in the object's validity period (if applicable) that happen as a result of the transfer ⏳.
Here's an example <transfer> query response:
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="1000">
S: <msg>Command completed successfully</msg>
S: </result>
S: <resData>
S: <obj:trnData xmlns:obj="urn:ietf:params:xml:ns:obj">
S: <obj:name>example</obj:name>
S: <obj:trStatus>pending</obj:trStatus>
S: <obj:reID>ClientX</obj:reID>
S: <obj:reDate>2000-06-08T22:00:00.0Z</obj:reDate>
S: <obj:acID>ClientY</obj:acID>
S: <obj:acDate>2000-06-13T22:00:00.0Z</obj:acDate>
S: <obj:exDate>2002-09-08T22:00:00.0Z</obj:exDate>
S: </obj:trnData>
S: </resData>
S: <trID>
S: <clTRID>ABC-12346</clTRID>
S: <svTRID>54322-XYZ</svTRID>
S: </trID>
S: </response>
S:</epp>Again, the <transfer> query is a real-time status check for pending and completed transfer requests 📡. This action SHOULD be limited to authorized clients. Restricting queries to the requesting and responding clients is RECOMMENDED. Object transfer MAY be unavailable or limited by object-specific policies 🦋.
2.9.3. Object Transform Commands
EPP gives you five commands to transform objects 🛠️. <create> makes a new instance of an object on a server ✨. <delete> removes an instance of an object from a server 🗑️. <renew> extends the validity period of an object ⏫. <transfer> manages changes in client sponsorship of an object 🤝. And <update> changes the info associated with an object 💖.
2.9.3.1. EPP <create> Command ✨
Okay so the <create> command is how you make a brand-new object 🧚. You can make one for an indefinite period, or you can give it a specific validity period. 🎀 If you do use a validity period, the EPP mapping for that object MUST describe its status over time, so both client and server know what to expect 💅.
The bits you need to identify an object (and its attributes) are object-specific, so the child elements of <create> get defined through the EPP extension framework 🌸. On top of the standard EPP command elements, the <create> command has this child element:
- An object-specific <obj:create> element that identifies the object to be created, plus the elements that are required to create it.
Here's an example <create> command 💖:
C:<?xml version="1.0" encoding="UTF-8" standalone="no"?>
C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0">
C: <command>
C: <create>
C: <obj:create xmlns:obj="urn:ietf:params:xml:ns:obj">
C: <!-- Object-specific elements. -->
C: </obj:create>
C: </create>
C: <clTRID>ABC-12345</clTRID>
C: </command>
C:</epp>When a <create> command goes through successfully, the server MAY reply with an EPP <resData> element. That <resData> MUST contain a child element that identifies the object namespace 🦋. Its child elements are object-specific too.
Here's an example <create> response with <resData> ✨:
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="1000">
S: <msg>Command completed successfully</msg>
S: </result>
S: <resData>
S: <obj:creData xmlns:obj="urn:ietf:params:xml:ns:obj">
S: <!-- Object-specific elements. -->
S: </obj:creData>
S: </resData>
S: <trID>
S: <clTRID>ABC-12345</clTRID>
S: <svTRID>54321-XYZ</svTRID>
S: </trID>
S: </response>
S:</epp>Lowkey the big rule here: creating objects SHOULD be limited to authorized clients 🔐, and it MAY be restricted on a per-client basis 👑.
2.9.3.2. EPP <delete> Command 🗑️
The <delete> command removes an object that already exists 🫶. Identifying an object is object-specific, so the child elements of <delete> are defined using the EPP extension framework. Along with the standard EPP command elements, <delete> has this child element:
- An object-specific <obj:delete> element that identifies the object to be deleted.
Example <delete> command 🍓:
C:<?xml version="1.0" encoding="UTF-8" standalone="no"?>
C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0">
C: <command>
C: <delete>
C: <obj:delete xmlns:obj="urn:ietf:params:xml:ns:obj">
C: <!-- Object-specific elements. -->
C: </obj:delete>
C: </delete>
C: <clTRID>ABC-12346</clTRID>
C: </command>
C:</epp>When a <delete> command succeeds, the server MAY send back an EPP <resData> element. That <resData> MUST contain a child element that identifies the object namespace, and its child elements are object-specific.
Example <delete> response without <resData> 🙈:
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="1000">
S: <msg>Command completed successfully</msg>
S: </result>
S: <trID>
S: <clTRID>ABC-12346</clTRID>
S: <svTRID>54322-XYZ</svTRID>
S: </trID>
S: </response>
S:</epp>Okay, so deleting SHOULD be limited to authorized clients. Restricting it to the sponsoring client is RECOMMENDED 💅, because it's the iconic move 👑.
2.9.3.3. EPP <renew> Command 🔁
The <renew> command extends the validity period of an object that already exists 🌈. The elements needed to identify an object and extend its validity period are object-specific, so the child elements of <renew> come from the EPP extension framework. On top of the standard EPP command elements, <renew> has this child element:
- An object-specific <obj:renew> element that identifies the object to be renewed, plus the elements that are required to extend the validity period of the object.
Example <renew> command ✨:
C:<?xml version="1.0" encoding="UTF-8" standalone="no"?>
C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0">
C: <command>
C: <renew>
C: <obj:renew xmlns:obj="urn:ietf:params:xml:ns:obj">
C: <!-- Object-specific elements. -->
C: </obj:renew>
C: </renew>
C: <clTRID>ABC-12346</clTRID>
C: </command>
C:</epp>When a <renew> command succeeds, the server MAY respond with an EPP <resData> element. That <resData> MUST contain a child element that identifies the object namespace, and its child elements are object-specific.
Example <renew> response with <resData> 🦋:
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="1000">
S: <msg>Command completed successfully</msg>
S: </result>
S: <resData>
S: <obj:renData xmlns:obj="urn:ietf:params:xml:ns:obj">
S: <!-- Object-specific elements. -->
S: </obj:renData>
S: </resData>
S: <trID>
S: <clTRID>ABC-12346</clTRID>
S: <svTRID>54322-XYZ</svTRID>
S: </trID>
S: </response>
S:</epp>Renewing SHOULD be limited to authorized clients, and restricting it to the sponsoring client is RECOMMENDED 🫶. Renewal MAY be unavailable or limited by object-specific policies 💀.
2.9.3.4. EPP <transfer> Command 🔄
The <transfer> command manages changes in client sponsorship of an existing object 💜. A client can start a transfer request, cancel one, approve one, or reject one, all by using the "op" command attribute ✨.
If a client wants to take over sponsorship of a known object from another client, it uses <transfer> with the "op" attribute set to "request" 🎀. Once a transfer has been requested, the same client can cancel it with a <transfer> command where "op" is set to "cancel". A cancel request MUST reach the server before the current sponsoring client approves or rejects the transfer, and before the server automatically processes the request because the responding client has gone quiet 🙈.
Once the server gets a transfer request, it MUST tell the current sponsoring client about it. It can do that by queuing a service message to be fetched with the <poll> command, or by using an out-of-band mechanism 📬. The status of any pending <transfer> command can be looked up with the <transfer> query command 🔍. Transfer service messages MUST include the object-specific elements specified for <transfer> command responses 💅.
The current sponsoring client MAY explicitly approve or reject the request 👑. To approve, it sends a <transfer> command with "op" set to "approve". To reject, it sends one with "op" set to "reject" 🙅♀️.
A server MAY automatically approve or reject any transfer request the sponsoring client hasn't explicitly handled within a fixed amount of time ⏰. How long to wait and what the default server behavior is are local matters that EPP doesn't specify. They SHOULD be documented in a server-specific profile document that describes default server behavior for client information 📖.
Objects that can be transferred MUST have associated authorization information, and that information MUST be provided to complete a <transfer> command 🔐. The kind of authorization information needed is object-specific. Passwords or more complex public key cryptography mechanisms are typical 🗝️.
The elements needed to identify an object and complete its transfer are object-specific, so the child elements of <transfer> come from the EPP extension framework. On top of the standard EPP command elements, <transfer> has this child element:
- An object-specific <obj:transfer> element that identifies the object to be transferred, plus the elements that are required to process the transfer command.
Example <transfer> command 🌸:
C:<?xml version="1.0" encoding="UTF-8" standalone="no"?>
C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0">
C: <command>
C: <transfer op="request">
C: <obj:transfer xmlns:obj="urn:ietf:params:xml:ns:obj">
C: <!-- Object-specific elements. -->
C: </obj:transfer>
C: </transfer>
C: <clTRID>ABC-12346</clTRID>
C: </command>
C:</epp>When a <transfer> command succeeds, the server MUST respond with an EPP <resData> element, and that <resData> MUST contain a child element that identifies the object namespace 🫧. Its child elements are object-specific, but they MUST include elements that identify the object, the status of the transfer, the identifier of the client that requested the transfer, and the date and time that request was made. They also MUST include the identifier of the client that is authorized to act on the request, and the date and time by which an action is expected. There's also an OPTIONAL date and time that notes any changes to the object's validity period (if applicable) that come from the transfer 📅.
Example <transfer> response with <resData> 🧚:
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="1001">
S: <msg>Command completed successfully; action pending</msg>
S: </result>
S: <resData>
S: <obj:trnData xmlns:obj="urn:ietf:params:xml:ns:obj">
S: <obj:name>example</obj:name>
S: <obj:trStatus>pending</obj:trStatus>
S: <obj:reID>ClientX</obj:reID>
S: <obj:reDate>2000-06-08T22:00:00.0Z</obj:reDate>
S: <obj:acID>ClientY</obj:acID>
S: <obj:acDate>2000-06-13T22:00:00.0Z</obj:acDate>
S: <obj:exDate>2002-09-08T22:00:00.0Z</obj:exDate>
S: </obj:trnData>
S: </resData>
S: <trID>
S: <clTRID>ABC-12346</clTRID>
S: <svTRID>54322-XYZ</svTRID>
S: </trID>
S: </response>
S:</epp>Final boss energy here 👑: transfers SHOULD be limited to authorized clients. It's RECOMMENDED that <transfer> requests go only to a client other than the current sponsoring client, that <transfer> approval requests go only to the current sponsoring client, and that <transfer> cancellation requests go only to the original requesting client 🫶. Transfer MAY be unavailable or limited by object-specific policies 🌈✨
2.9.3.5. EPP <update> Command 🎀
okay so the EPP <update> command is how you change the info on an object that already exists 🦋 the elements needed to find and modify the object are object-specific, so the child elements of <update> get defined through the EPP extension framework 🧚 on top of the standard EPP command elements, <update> has this:
- An object-specific <obj:update> element that identifies the object to be updated and the elements that are required to modify the object. Object-specific elements MUST identify values to be added, values to be removed, or values to be changed.
here's an example <update> command:
C:<?xml version="1.0" encoding="UTF-8" standalone="no"?>
C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0">
C: <command>
C: <update>
C: <obj:update xmlns:obj="urn:ietf:params:xml:ns:obj">
C: <!-- Object-specific elements. -->
C: </obj:update>
C: </update>
C: <clTRID>ABC-12346</clTRID>
C: </command>
C:</epp>when an <update> goes through successfully, the server MAY send back an EPP <resData> element, and if it does, that element MUST contain a child element that identifies the object namespace ✨ the child elements of <resData> are object-specific, so it depends on the object type 💜
here's an <update> response without <resData> 💅
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="1000">
S: <msg>Command completed successfully</msg>
S: </result>
S: <trID>
S: <clTRID>ABC-12346</clTRID>
S: <svTRID>54322-XYZ</svTRID>
S: </trID>
S: </response>
S:</epp>real talk though, changing an existing object is a big deal 🔥 so this action SHOULD be limited to authorized clients, and restricting it to the sponsoring client is RECOMMENDED. iykyk 💀
3. Result Codes 🌈
okay bestie, EPP result codes are built on the reply code theory from section 4.2.1 of [RFC5321] 🧠 EPP uses four decimal digits to describe whether each command worked or flopped, and every single digit has a job ✨
the first digit tells you if the command succeeded or failed 🎀 the second digit tells you the response category, like syntax or security 🔐 and the third and fourth digits give the explicit details inside that category 🦋
there are only two possible first digits:
1yzz Positive completion reply. The command was accepted and
processed by the system without error.
2yzz Negative completion reply. The command was not accepted, and
the requested action did not occur.the second digit sorts responses into one of six categories:
x0zz Protocol Syntax
x1zz Implementation-specific Rules
x2zz Security
x3zz Data Management
x4zz Server System
x5zz Connection Managementthe third and fourth digits give you the detail within those categories 💖 the full list of valid result codes is below and also in the normative schema 📋
every EPP response MUST include a result code and a human-readable description of that code 🫶 the language of the description MAY be identified with the "lang" attribute on the <msg> element. if nothing is specified, the default language is English, identified as "en". the structure of valid "lang" values is described in [RFC4646] 🌸
the response text MAY be translated into other languages, but the translation MUST preserve the meaning of the code as described here 🌍 response code values MUST NOT be changed when translating text. not even a little 🙅♀️
the response text in the tables below is wrapped in quotes so you can clearly see where each string starts and ends 🎀 quotes MUST NOT be used to delimit these strings when the text is actually returned through the protocol. the quotes are just for the reading experience ✨
first up, the successful ones 🥳
Code Response text in English
____ ________________________
1000 "Command completed successfully"
This is the usual response code for a successfully
completed command that is not addressed by any other
1xxx-series response code.
1001 "Command completed successfully; action pending"
This response code MUST be returned when responding to a
command that requires offline activity before the
requested action can be completed. See Section 2 for a
description of other processing requirements.
1300 "Command completed successfully; no messages"
This response code MUST be returned when responding to a
<poll> request command and the server message queue is
empty.
1301 "Command completed successfully; ack to dequeue"
This response code MUST be returned when responding to a
<poll> request command and a message has been retrieved
from the server message queue.
1500 "Command completed successfully; ending session"
This response code MUST be returned when responding to a
successful <logout> command.and now the error ones 💀 don't panic, we've got this
Code Response text in English
____ ________________________
2000 "Unknown command"
This response code MUST be returned when a server receives
a command element that is not defined by EPP.
2001 "Command syntax error"
This response code MUST be returned when a server receives
an improperly formed command element.
2002 "Command use error"
This response code MUST be returned when a server receives
a properly formed command element but the command cannot
be executed due to a sequencing or context error. For
example, a <logout> command cannot be executed without
having first completed a <login> command.
2003 "Required parameter missing"
This response code MUST be returned when a server receives
a command for which a required parameter value has not
been provided.
2004 "Parameter value range error"
This response code MUST be returned when a server receives
a command parameter whose value is outside the range of
values specified by the protocol. The error value SHOULD
be returned via a <value> element in the EPP response.
2005 "Parameter value syntax error"
This response code MUST be returned when a server receives
a command containing a parameter whose value is improperly
formed. The error value SHOULD be returned via a <value>
element in the EPP response.
2100 "Unimplemented protocol version"
This response code MUST be returned when a server receives
a command element specifying a protocol version that is
not implemented by the server.
2101 "Unimplemented command"
This response code MUST be returned when a server receives
a valid EPP command element that is not implemented by the
server. For example, a <transfer> command can be
unimplemented for certain object types.
2102 "Unimplemented option"
This response code MUST be returned when a server receives
a valid EPP command element that contains a protocol
option that is not implemented by the server.
2103 "Unimplemented extension"
This response code MUST be returned when a server receives
a valid EPP command element that contains a protocol
command extension that is not implemented by the server.
2104 "Billing failure"
This response code MUST be returned when a server attempts
to execute a billable operation and the command cannot be
completed due to a client-billing failure.
2105 "Object is not eligible for renewal"
This response code MUST be returned when a client attempts
to <renew> an object that is not eligible for renewal in
accordance with server policy.
2106 "Object is not eligible for transfer"
This response code MUST be returned when a client attempts
to <transfer> an object that is not eligible for transfer
in accordance with server policy.
2200 "Authentication error"
This response code MUST be returned when a server notes an
error when validating client credentials.
2201 "Authorization error"
This response code MUST be returned when a server notes a
client-authorization error when executing a command. This
error is used to note that a client lacks privileges to
execute the requested command.
2202 "Invalid authorization information"
This response code MUST be returned when a server receives
invalid command authorization information when attempting
to confirm authorization to execute a command. This error
is used to note that a client has the privileges required
to execute the requested command, but the authorization
information provided by the client does not match the
authorization information archived by the server.
2300 "Object pending transfer"
This response code MUST be returned when a server receives
a command to transfer of an object that is pending
transfer due to an earlier transfer request.
2301 "Object not pending transfer"
This response code MUST be returned when a server receives
a command to confirm, reject, or cancel the transfer of an
object when no command has been made to transfer the
object.
2302 "Object exists"
This response code MUST be returned when a server receives
a command to create an object that already exists in the
repository.
2303 "Object does not exist"
This response code MUST be returned when a server receives
a command to query or transform an object that does not
exist in the repository.
2304 "Object status prohibits operation"
This response code MUST be returned when a server receives
a command to transform an object that cannot be completed
due to server policy or business practices. For example,
a server can disallow <transfer> commands under terms and
conditions that are matters of local policy, or the server
might have received a <delete> command for an object whose
status prohibits deletion.
2305 "Object association prohibits operation"
This response code MUST be returned when a server receives
a command to transform an object that cannot be completed
due to dependencies on other objects that are associated
with the target object. For example, a server can
disallow <delete> commands while an object has active
associations with other objects.
2306 "Parameter value policy error"3. Result Codes (continued) 🎀
Okay so this one is for when a server gets a parameter value that's syntactically valid but semantically invalid because of local policy 💅 For example, the server might only support a subset of a range of valid protocol parameter values. The error value SHOULD be returned via a <value> element in the EPP response ✨
2307 "Unimplemented object service"
This response code MUST be returned when a server receives a command to operate on an object service that the server doesn't support 🧚
2308 "Data management policy violation"
This response code MUST be returned when a server receives a command whose execution would break the server's data management policies 🙈 For example, removing all attribute values or object associations from an object might count as a violation of a server's data management policies.
2400 "Command failed"
This response code MUST be returned when a server can't execute a command because of an internal server error that has nothing to do with the protocol 🌸 The failure can be transient. The server MUST keep any ongoing session active.
2500 "Command failed; server closing connection"
This response code MUST be returned when a server gets a command it can't complete because of an internal server error that has nothing to do with the protocol 😭 The failure is not transient, and it will cause other commands to fail as well. The server MUST end the active session and close the existing connection.
2501 "Authentication error; server closing connection"
This response code MUST be returned when a server notices an error while validating client credentials and a server-defined limit on the number of allowable failures has been exceeded 🔒 The server MUST close the existing connection.
2502 "Session limit exceeded; server closing connection"
This response code MUST be returned when a server gets a <login> command and can't complete it because the client has gone over a system-defined limit on the number of sessions it can establish 👑 It might be possible to establish a session by ending existing unused sessions and closing inactive connections.
4. Formal Syntax 🧾
EPP is specified in XML Schema notation, and the schema here is a complete representation of EPP, so you can run automated validation on EPP XML instances 🤖 There are two schemas. The first is the base EPP schema. The second defines elements and structures that both the base EPP schema and object mapping schemas can use. The BEGIN and END tags are not part of the schema. They just mark where each schema starts and ends for URI registration purposes 💜
4.1. Base Schema 🌈
Okay, the legal bit is next, and yes it's a whole thing. Here's the copyright and license text exactly as written:
Copyright (c) 2009 IETF Trust and the persons identified as authors
of the code. All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
o Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
o Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in
the documentation and/or other materials provided with the
distribution.
o Neither the name of Internet Society, IETF or IETF Trust, nor the
names of specific contributors, may be used to endorse or promote
products derived from this software without specific prior written
permission.
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.Now the schema itself. The BEGIN tag starts it, and it's the actual XML Schema 🎀
BEGIN
<?xml version="1.0" encoding="UTF-8"?>
<schema targetNamespace="urn:ietf:params:xml:ns:epp-1.0"
xmlns:epp="urn:ietf:params:xml:ns:epp-1.0"
xmlns:eppcom="urn:ietf:params:xml:ns:eppcom-1.0"
xmlns="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified">
<!--
Import common element types.
-->
<import namespace="urn:ietf:params:xml:ns:eppcom-1.0"/>
<annotation>
<documentation>
Extensible Provisioning Protocol v1.0 schema.
</documentation>
</annotation>
<!--
Every EPP XML instance must begin with this element.
-->
<element name="epp" type="epp:eppType"/>
<!--
An EPP XML instance must contain a greeting, hello, command,
response, or extension.
-->
<complexType name="eppType">
<choice>
<element name="greeting" type="epp:greetingType"/>
<element name="hello"/>
<element name="command" type="epp:commandType"/>
<element name="response" type="epp:responseType"/>
<element name="extension" type="epp:extAnyType"/>
</choice>
</complexType>
<!--
A greeting is sent by a server in response to a client connection
or <hello>.
-->
<complexType name="greetingType">
<sequence>
<element name="svID" type="epp:sIDType"/>
<element name="svDate" type="dateTime"/>
<element name="svcMenu" type="epp:svcMenuType"/>
<element name="dcp" type="epp:dcpType"/>
</sequence>
</complexType>
<!--
Server IDs are strings with minimum and maximum length restrictions.
-->
<simpleType name="sIDType">
<restriction base="normalizedString">
<minLength value="3"/>
<maxLength value="64"/>
</restriction>
</simpleType>
<!--
A server greeting identifies available object services.
-->
<complexType name="svcMenuType">
<sequence>
<element name="version" type="epp:versionType"
maxOccurs="unbounded"/>
<element name="lang" type="language"
maxOccurs="unbounded"/>
<element name="objURI" type="anyURI"
maxOccurs="unbounded"/>
<element name="svcExtension" type="epp:extURIType"
minOccurs="0"/>
</sequence>
</complexType>
<!--
Data Collection Policy types.
-->
<complexType name="dcpType">
<sequence>
<element name="access" type="epp:dcpAccessType"/>
<element name="statement" type="epp:dcpStatementType"
maxOccurs="unbounded"/>
<element name="expiry" type="epp:dcpExpiryType"
minOccurs="0"/>
</sequence>
</complexType>
<complexType name="dcpAccessType">
<choice>
<element name="all"/>
<element name="none"/>
<element name="null"/>
<element name="other"/>
<element name="personal"/>
<element name="personalAndOther"/>
</choice>
</complexType>
<complexType name="dcpStatementType">
<sequence>
<element name="purpose" type="epp:dcpPurposeType"/>
<element name="recipient" type="epp:dcpRecipientType"/>
<element name="retention" type="epp:dcpRetentionType"/>
</sequence>
</complexType>
<complexType name="dcpPurposeType">
<sequence>
<element name="admin"
minOccurs="0"/>
<element name="contact"
minOccurs="0"/>
<element name="other"
minOccurs="0"/>
<element name="prov"
minOccurs="0"/>
</sequence>
</complexType>
<complexType name="dcpRecipientType">
<sequence>
<element name="other"
minOccurs="0"/>
<element name="ours" type="epp:dcpOursType"
minOccurs="0" maxOccurs="unbounded"/>
<element name="public"
minOccurs="0"/>
<element name="same"
minOccurs="0"/>
<element name="unrelated"
minOccurs="0"/>
</sequence>
</complexType>
<complexType name="dcpOursType">
<sequence>
<element name="recDesc" type="epp:dcpRecDescType"
minOccurs="0"/>
</sequence>
</complexType>
<simpleType name="dcpRecDescType">
<restriction base="token">
<minLength value="1"/>
<maxLength value="255"/>
</restriction>
</simpleType>
<complexType name="dcpRetentionType">
<choice>
<element name="business"/>
<element name="indefinite"/>
<element name="legal"/>
<element name="none"/>
<element name="stated"/>
</choice>
</complexType>
<complexType name="dcpExpiryType">
<choice>
<element name="absolute" type="dateTime"/>
<element name="relative" type="duration"/>
</choice>
</complexType>
<!--
Extension framework types.
-->
<complexType name="extAnyType">
<sequence>
<any namespace="##other"
maxOccurs="unbounded"/>
</sequence>
</complexType>
<complexType name="extURIType">
<sequence>
<element name="extURI" type="anyURI"
maxOccurs="unbounded"/>
</sequence>
</complexType>
<!--
An EPP version number is a dotted pair of decimal numbers.
-->
<simpleType name="versionType">
<restriction base="token">
<pattern value="[1-9]+\.[0-9]+"/>
<enumeration value="1.0"/>
</restriction>
</simpleType>
<!--
Command types.
-->
<complexType name="commandType">
<sequence>
<choice>
<element name="check" type="epp:readWriteType"/>
<element name="create" type="epp:readWriteType"/>
<element name="delete" type="epp:readWriteType"/>
<element name="info" type="epp:readWriteType"/>
<element name="login" type="epp:loginType"/>
<element name="logout"/>
<element name="poll" type="epp:pollType"/>
<element name="renew" type="epp:readWriteType"/>
<element name="transfer" type="epp:transferType"/>
<element name="update" type="epp:readWriteType"/>
</choice>
<element name="extension" type="epp:extAnyType"
minOccurs="0"/>
<element name="clTRID" type="epp:trIDStringType"
minOccurs="0"/>
</sequence>
</complexType>
<!--
The <login> command.
-->
<complexType name="loginType">
<sequence>
<element name="clID" type="eppcom:clIDType"/>
<element name="pw" type="epp:pwType"/>
<element name="newPW" type="epp:pwType"
minOccurs="0"/>
<element name="options" type="epp:credsOptionsType"/>
<element name="svcs" type="epp:loginSvcType"/>
</sequence>
</complexType> <complexType name="credsOptionsType">
<sequence>
<element name="version" type="epp:versionType"/>
<element name="lang" type="language"/>
</sequence>
</complexType>
<simpleType name="pwType">
<restriction base="token">
<minLength value="6"/>
<maxLength value="16"/>
</restriction>
</simpleType>
<complexType name="loginSvcType">
<sequence>
<element name="objURI" type="anyURI"
maxOccurs="unbounded"/>
<element name="svcExtension" type="epp:extURIType"
minOccurs="0"/>
</sequence>
</complexType>
<!--
The <poll> command.
-->
<complexType name="pollType">
<attribute name="op" type="epp:pollOpType"
use="required"/>
<attribute name="msgID" type="token"/>
</complexType>
<simpleType name="pollOpType">
<restriction base="token">
<enumeration value="ack"/>
<enumeration value="req"/>
</restriction>
</simpleType>
<!--
The <transfer> command. This is object-specific, and uses attributes
to identify the requested operation.
-->
<complexType name="transferType">
<sequence>
<any namespace="##other"/>
</sequence>
<attribute name="op" type="epp:transferOpType"
use="required"/>
</complexType>
<simpleType name="transferOpType">
<restriction base="token">
<enumeration value="approve"/>
<enumeration value="cancel"/>
<enumeration value="query"/>
<enumeration value="reject"/>
<enumeration value="request"/>
</restriction>
</simpleType>
<!--
All other object-centric commands. EPP doesn't specify the syntax or
semantics of object-centric command elements. The elements MUST be
described in detail in another schema specific to the object.
-->
<complexType name="readWriteType">
<sequence>
<any namespace="##other"/>
</sequence>
</complexType>
<complexType name="trIDType">
<sequence>
<element name="clTRID" type="epp:trIDStringType"
minOccurs="0"/>
<element name="svTRID" type="epp:trIDStringType"/>
</sequence>
</complexType>
<simpleType name="trIDStringType">
<restriction base="token">
<minLength value="3"/>
<maxLength value="64"/>
</restriction>
</simpleType>
<!--
Response types.
-->
<complexType name="responseType">
<sequence>
<element name="result" type="epp:resultType"
maxOccurs="unbounded"/>
<element name="msgQ" type="epp:msgQType"
minOccurs="0"/>
<element name="resData" type="epp:extAnyType"
minOccurs="0"/>
<element name="extension" type="epp:extAnyType"
minOccurs="0"/>
<element name="trID" type="epp:trIDType"/>
</sequence>
</complexType>
<complexType name="resultType">
<sequence>
<element name="msg" type="epp:msgType"/>
<choice minOccurs="0" maxOccurs="unbounded">
<element name="value" type="epp:errValueType"/>
<element name="extValue" type="epp:extErrValueType"/>
</choice>
</sequence>
<attribute name="code" type="epp:resultCodeType"
use="required"/>
</complexType>
<complexType name="errValueType" mixed="true">
<sequence>
<any namespace="##any" processContents="skip"/>
</sequence>
<anyAttribute namespace="##any" processContents="skip"/>
</complexType>
<complexType name="extErrValueType">
<sequence>
<element name="value" type="epp:errValueType"/>
<element name="reason" type="epp:msgType"/>
</sequence>
</complexType>
<complexType name="msgQType">
<sequence>
<element name="qDate" type="dateTime"
minOccurs="0"/>
<element name="msg" type="epp:mixedMsgType"
minOccurs="0"/>
</sequence>
<attribute name="count" type="unsignedLong"
use="required"/>
<attribute name="id" type="eppcom:minTokenType"
use="required"/>
</complexType>
<complexType name="mixedMsgType" mixed="true">
<sequence>
<any processContents="skip"
minOccurs="0" maxOccurs="unbounded"/>
</sequence>
<attribute name="lang" type="language"
default="en"/>
</complexType>
<!--
Human-readable text may be expressed in languages other than English.
-->
<complexType name="msgType">
<simpleContent>
<extension base="normalizedString">
<attribute name="lang" type="language"
default="en"/>
</extension>
</simpleContent>
</complexType>
<!--
EPP result codes.
-->
<simpleType name="resultCodeType">
<restriction base="unsignedShort">
<enumeration value="1000"/>
<enumeration value="1001"/>
<enumeration value="1300"/>
<enumeration value="1301"/>
<enumeration value="1500"/>
<enumeration value="2000"/>
<enumeration value="2001"/>
<enumeration value="2002"/>
<enumeration value="2003"/>
<enumeration value="2004"/>
<enumeration value="2005"/>
<enumeration value="2100"/>
<enumeration value="2101"/>
<enumeration value="2102"/>
<enumeration value="2103"/>
<enumeration value="2104"/>
<enumeration value="2105"/>
<enumeration value="2106"/>
<enumeration value="2200"/>
<enumeration value="2201"/>
<enumeration value="2202"/>
<enumeration value="2300"/>
<enumeration value="2301"/>
<enumeration value="2302"/>
<enumeration value="2303"/>
<enumeration value="2304"/>
<enumeration value="2305"/>
<enumeration value="2306"/>
<enumeration value="2307"/>
<enumeration value="2308"/>
<enumeration value="2400"/>
<enumeration value="2500"/>
<enumeration value="2501"/>
<enumeration value="2502"/>
</restriction>
</simpleType>
<!--
End of schema.
-->
</schema>
END4.2. Shared Structure Schema ✨
okay bestie, this is the shared structures schema, the stuff that gets reused across the whole EPP vibe 💜
Copyright (c) 2009 IETF Trust and the persons identified as authors of the code. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
- Neither the name of Internet Society, IETF or IETF Trust, nor the names of specific contributors, may be used to endorse or promote products derived from this software without specific prior written permission.
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.
the schema itself is below, copied exactly 🎀
BEGIN
<?xml version="1.0" encoding="UTF-8"?>
<schema targetNamespace="urn:ietf:params:xml:ns:eppcom-1.0"
xmlns:eppcom="urn:ietf:params:xml:ns:eppcom-1.0"
xmlns="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified">
<annotation>
<documentation>
Extensible Provisioning Protocol v1.0
shared structures schema.
</documentation>
</annotation>
<!--
Object authorization information types.
-->
<complexType name="pwAuthInfoType">
<simpleContent>
<extension base="normalizedString">
<attribute name="roid" type="eppcom:roidType"/>
</extension>
</simpleContent>
</complexType>
<complexType name="extAuthInfoType">
<sequence>
<any namespace="##other"/>
</sequence>
</complexType>
<!--
<check> response types.
-->
<complexType name="reasonType">
<simpleContent>
<extension base="eppcom:reasonBaseType">
<attribute name="lang" type="language"/>
</extension>
</simpleContent>
</complexType>
<simpleType name="reasonBaseType">
<restriction base="token">
<minLength value="1"/>
<maxLength value="32"/>
</restriction>
</simpleType>
<!--
Abstract client and object identifier type.
-->
<simpleType name="clIDType">
<restriction base="token">
<minLength value="3"/>
<maxLength value="16"/>
</restriction>
</simpleType>
<!--
DNS label type.
-->
<simpleType name="labelType">
<restriction base="token">
<minLength value="1"/>
<maxLength value="255"/>
</restriction>
</simpleType>
<!--
Non-empty token type.
-->
<simpleType name="minTokenType">
<restriction base="token">
<minLength value="1"/>
</restriction>
</simpleType>
<!--
Repository Object IDentifier type.
-->
<simpleType name="roidType">
<restriction base="token">
<pattern value="(\w|_){1,80}-\w{1,8}"/>
</restriction>
</simpleType>
<!--
Transfer status identifiers.
-->
<simpleType name="trStatusType">
<restriction base="token">
<enumeration value="clientApproved"/>
<enumeration value="clientCancelled"/>
<enumeration value="clientRejected"/>
<enumeration value="pending"/>
<enumeration value="serverApproved"/>
<enumeration value="serverCancelled"/>
</restriction>
</simpleType>
<!--
End of schema.
-->
</schema>
END5. Internationalization Considerations 🌍
okay so EPP is written in XML, and XML already speaks Unicode, which means it can handle basically every character and it's giving global bestie energy 💖. The more compact way to store it is UTF-8 🦋. Conformant XML processors recognize both UTF-8 and UTF-16. XML can use other encodings if you set an "encoding" attribute in the <?xml?> declaration, but in environments where parser-encoding-support incompatibility exists, use of UTF-8 is RECOMMENDED. Safe and slay 💅.
EPP also sends a human-readable message with every result code 🎀. This document describes the result codes in English, but the actual text returned with a result MAY be provided in a language negotiated when a session is established. Languages other than English MUST be noted through specification of a "lang" attribute for each message. The valid values for the "lang" attribute and "lang" negotiation elements are described in [RFC4646] 🌈.
Now the date-time stuff, which is extremely important, so please pay attention 🙈. All date-time values presented via EPP MUST be expressed in Universal Coordinated Time using the Gregorian calendar. XML Schema lets you use time zone identifiers to show offsets from the zero meridian, but this option MUST NOT be used with EPP. The extended date-time form using upper case "T" and "Z" characters, defined in [W3C.REC-xmlschema-2-20041028], MUST be used to represent date-time values. XML Schema doesn't support truncated date-time forms or lower case "T" and "Z", so yeah, no shortcuts 💀.
6. IANA Considerations 📋
this document uses URNs to describe XML namespaces and XML schemas, following a registry mechanism described in [RFC3688] 🧚. Four URI assignments have been registered by the IANA ✨. Here they are, bestie:
Registration request for the EPP namespace:
URI: urn:ietf:params:xml:ns:epp-1.0
Registrant Contact: See the "Author's Address" section of this
document.
XML: None. Namespace URIs do not represent an XML specification.Registration request for the EPP XML schema:
URI: urn:ietf:params:xml:schema:epp-1.0
Registrant Contact: See the "Author's Address" section of this
document.
XML: See the "Base Schema" section of this document.Registration request for the EPP shared structure namespace:
URI: urn:ietf:params:xml:ns:eppcom-1.0
Registrant Contact: See the "Author's Address" section of this
document.
XML: None. Namespace URIs do not represent an XML specification.Registration request for the EPP shared structure XML schema:
URI: urn:ietf:params:xml:schema:eppcom-1.0
Registrant Contact: See the "Author's Address" section of this
document.
XML: See the "Shared Structure Schema" section of this document.There's also a MIME media type registration template included in Appendix B 🎀.
7. Security Considerations 🚨
okay, this section is SERIOUS, so read it slowly 😭. EPP only provides simple client-authentication services 💀. A passive attack is enough to recover client identifiers and passwords, which makes command forgery trivial. Protection against most common attacks and more robust security services MUST be provided by other protocol layers. Specifically, EPP instances MUST be protected using a transport mechanism or application protocol that provides integrity, confidentiality, and mutual, strong client-server authentication. No skipping this part, periodt 🔥.
EPP uses a variant of the PLAIN SASL mechanism described in [RFC4616] to provide a simple application-layer authentication service 🧁. This service augments or supplements the authentication and identification services that might be available at other protocol layers. Where the PLAIN SASL mechanism specifies an authorization identifier, an authentication identifier, and a password as a single string separated by ASCII NUL characters, EPP instead uses a combined authorization and authentication identifier and a password, provided as distinct XML elements. Different vibe, same goal ✨.
Repeated password guessing attempts can be discouraged by limiting the number of <login> attempts allowed on an open connection 🙅♀️. A server MAY close an open connection if multiple <login> attempts are made with an invalid client identifier, an invalid password, or both an invalid client identifier and an invalid password. Main character energy for the server, honestly 👑.
EPP uses authentication information associated with objects to confirm object-transfer authority 🦋. Authentication information exchanged between EPP clients and third-party entities MUST be exchanged using a facility that provides privacy and integrity services, to protect against unintended disclosure and modification while in transit. Do NOT send passwords over a sketchy channel, iykyk 🙈.
EPP instances SHOULD be protected using a transport mechanism or application protocol that provides anti-replay protection. EPP provides some protection against replay attacks through command idempotency and client-initiated transaction identification. Consecutive command replays will not change the state of an object in any way. There is, however, a chance of unintended or malicious consequence if a command is replayed after intervening commands have changed the object state and client identifiers are not used to detect replays. For example, a replayed<create>command that follows a<delete>command might succeed without additional facilities to prevent or detect the replay. Replay attacks are lowkey the villain arc here 😈.
As described in Section 2, EPP includes features that allow offline review of transform commands before the requested action is actually completed 📦. The server is required to notify the client when offline processing of the action has been completed 🔔. Notifications can be sent using an out-of-band mechanism that is not protected by the mechanism used to provide EPP transport security. Notifications sent without EPP's transport-security services should be protected using another mechanism that provides an appropriate level of protection for the notification. Protect your notifications, bestie 🫶.
8. Acknowledgements 💜
RFC 3730 is a product of the PROVREG working group, which suggested improvements and provided many invaluable comments 🌸. The author wishes to acknowledge the efforts of WG chairs Edward Lewis and Jaap Akkerhuis for their process and editorial contributions. RFC 4930 and this document are individual submissions, based on the work done in RFC 3730 ✨.
Specific suggestions that made it into this document came from Chris Bason, Eric Brunner-Williams, Jordyn Buchanan, Roger Castillo Cortazar, Dave Crocker, Ayesha Damaraju, Sheer El-Showk, Patrik Faltstrom, James Gould, John Immordino, Dan Kohn, Hong Liu, Klaus Malorny, Dan Manley, Michael Mealling, Patrick Mevzek, Andrew Newton, Budi Rahardjo, Asbjorn Steira, Rick Wesson, and Jay Westerdal. Literally a whole squad 🫶🎀.
9. References 📚
9.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. 🔑
[RFC2277] Alvestrand, H., "IETF Policy on Character Sets and Languages", BCP 18, RFC 2277, January 1998. 🌐
[RFC2914] Floyd, S., "Congestion Control Principles", BCP 41, RFC 2914, September 2000. 🚦
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, November 2003. 🦋
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, January 2004. 🧚
[RFC4646] Phillips, A. and M. Davis, "Tags for Identifying Languages", BCP 47, RFC 4646, September 2006. 🌈
[W3C.REC-xml-20040204] Sperberg-McQueen, C., Maler, E., Yergeau, F., Paoli, J., and T. Bray, "Extensible Markup Language (XML) 1.0 (Third Edition)", World Wide Web Consortium FirstEdition REC-xml-20040204, February 2004, <http://www.w3.org/TR/2004/REC-xml-20040204>. 📄
[W3C.REC-xmlschema-1-20041028] Maloney, M., Thompson, H., Mendelsohn, N., and D. Beech, "XML Schema Part 1: Structures Second Edition", World Wide Web Consortium Recommendation REC-xmlschema-1-20041028, October 2004, <http://www.w3.org/TR/2004/REC-xmlschema-1-20041028>. 🗂️
[W3C.REC-xmlschema-2-20041028] Malhotra, A. and P. Biron, "XML Schema Part 2: Datatypes Second Edition", World Wide Web Consortium Recommendation REC-xmlschema-2-20041028, October 2004, <http://www.w3.org/TR/2004/REC-xmlschema-2-20041028>. 🔢
9.2. Informative References
[RFC0793] Postel, J., "Transmission Control Protocol", STD 7, RFC 793, September 1981. 🛰️
[RFC2781] Hoffman, P. and F. Yergeau, "UTF-16, an encoding of ISO 10646", RFC 2781, February 2000. 🔤
[RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media Types", RFC 3023, January 2001. 🎞️
[RFC3080] Rose, M., "The Blocks Extensible Exchange Protocol Core", RFC 3080, March 2001. 🧱
[RFC3375] Hollenbeck, S., "Generic Registry-Registrar Protocol Requirements", RFC 3375, September 2002. 📝
[RFC4616] Zeilenga, K., "The PLAIN Simple Authentication and Security Layer (SASL) Mechanism", RFC 4616, August 2006. 🔐
[RFC4930] Hollenbeck, S., "Extensible Provisioning Protocol (EPP)", RFC 4930, May 2007. 🧃
[RFC4960] Stewart, R., "Stream Control Transmission Protocol", RFC 4960, September 2007. 🌊
[RFC5321] Klensin, J., "Simple Mail Transfer Protocol", RFC 5321, October 2008. 💌
[W3C.REC-P3P-20020416] Marchiori, M., "The Platform for Privacy Preferences 1.0 (P3P1.0) Specification", World Wide Web Consortium Recommendation REC-P3P-20020416, April 2002, <http://www.w3.org/TR/2002/REC-P3P-20020416>. 🕵️♀️
Appendix A. Object Mapping Template ✨
okay so this appendix is basically a fill-in-the-blanks template 🧚 for writing up how an object gets mapped to EPP. Docs that describe EPP object mappings SHOULD follow a layout similar to this one 💅. If the mapping is written up as an Internet-Draft or an RFC, you'll need some extra sections too 📝.
1. Introduction
Give an intro that describes the object and gives a quick overview of how it maps to EPP 🌸.
2. Object Attributes
Describe the object's attributes, and link to syntax specs where it makes sense 🔥. Examples are a name or identifier, and dates tied to modification events 📅.
3. EPP Command Mapping
3.1. EPP Query Commands
3.1.1. EPP <check> Command
Describe the object-specific mappings needed to implement the EPP <check> command 🦋. Include both sample commands and sample responses 💖.
3.1.2. EPP <info> Command
Describe the object-specific mappings needed to implement the EPP <info> command 🦋. Include both sample commands and sample responses 💖.
3.1.3. EPP <poll> Command
Describe the object-specific mappings needed to implement the EPP <poll> command 🦋. Include both sample commands and sample responses 💖.
3.1.4. EPP <transfer> Command
Describe the object-specific mappings needed to implement the EPP <transfer> query command 🦋. Include both sample commands and sample responses 💖.
3.2. EPP Transform Commands
3.2.1. EPP <create> Command
Describe the object-specific mappings needed to implement the EPP <create> command 🦋. Include both sample commands and sample responses 💖. Also cover the object's status over time, including the expected client and server behavior if a validity period is used ⏳. This part is lowkey important, so don't skip it 👀.
3.2.2. EPP <delete> Command
Describe the object-specific mappings needed to implement the EPP <delete> command 🦋. Include both sample commands and sample responses 💖.
3.2.3. EPP <renew> Command
Describe the object-specific mappings needed to implement the EPP <renew> command 🦋. Include both sample commands and sample responses 💖.
3.2.4. EPP <transfer> Command
Describe the object-specific mappings needed to implement the EPP <transfer> command 🦋. Include both sample commands and sample responses 💖.
3.2.4. EPP <update> Command
Describe the object-specific mappings needed to implement the EPP <update> command 🦋. Include both sample commands and sample responses 💖.
4. Formal Syntax
Provide the XML schema for the object mapping 📜. An XML DTD MUST NOT be used 🚫, because DTDs just don't give you enough support for XML namespaces and strong data typing 💀.
Appendix B. Media Type Registration: application/epp+xml 🎀
MIME media type name: application
MIME subtype name: epp+xml
Required parameters: none
Optional parameters: Same as the charset parameter of application/xml as specified in [RFC3023].
Encoding considerations: Same as the encoding considerations of application/xml as specified in [RFC3023].
Security considerations: This type has all of the security considerations described in [RFC3023] plus the considerations specified in the Security Considerations section of this document 🔐.
Interoperability considerations: XML has proven to be interoperable across WWW Distributed Authoring and Versioning (WebDAV) clients and servers 🌈, and for import and export from multiple XML authoring tools 🛠️. For maximum interoperability, validating processors are recommended 💅. Non-validating processors can be more efficient, but they are not required to handle all features of XML 🤷♀️. For further information, see Section 2.9, "Standalone Document Declaration", and Section 5, "Conformance", of [W3C.REC-xml-20040204] 📚.
Published specification: This document.
Applications that use this media type: EPP is device-, platform-, and vendor-neutral and is supported by multiple service providers 🦋.
Additional information: If used, magic numbers, fragment identifiers, base URIs, and use of the BOM should be as specified in [RFC3023] 🧾.
Magic number(s): None.
File extension(s): .xml
Macintosh file type code(s): "TEXT"
Person & email address for further information: See the "Author's Address" section of this document 💌.
Intended usage: COMMON
Author/Change controller: IETF
Appendix C. Changes from RFC 4930 🍓
- Changed
"This document obsoletes RFC 3730"to"This document obsoletes RFC 4930"🔄. - Replaced references to RFC 2595 with references to RFC 4616 🔁.
- Replaced references to RFC 2821 with references to RFC 5321 🔁.
- Replaced references to RFC 2960 with references to RFC 4960 🔁.
- Replaced references to RFC 3066 with references to RFC 4646 🔁.
- Replaced references to RFC 3730 with references to RFC 4930 🔁.
- Added
"A protocol client that is authorized to manage an existing object is described as a "sponsoring" client throughout this document"in Section 1.1 🧑💼. This is the sponsoring client definition, and it's giving clarity ✨. - Changed
"This action MUST be open to all authorized clients"to"This command MUST be available to all clients"in the descriptions of the <login> and <logout> commands 🔑. - Changed
"Specific result codes are listed in the table below"to"The complete list of valid result codes is enumerated below and in the normative schema"in Section 3 📋. - Added a new paragraph to Section 7 to give guidance on the need to protect offline transaction notices 🛡️. Security matters, bestie 🔐.
- Added a reference to Appendix B in the IANA Considerations section 🏷️.
- Added BSD license text to the XML schema section 📜.
Author's Address 💖
Scott Hollenbeck VeriSign, Inc. 21345 Ridgetop Circle Dulles, VA 20166-6503 US
EMail: shollenbeck@verisign.com 💌
📦 where this page comes from
- ietf: rfc5730 2009-08
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms