Helpful Howto for EPP registrars

Ver 0.1.3 -- Sept 28, 2001

 

Appendix B — Helpful Howto for EPP registrars

Document Overview
General EPP Overview
Basic things you can do with EPP
The Nitty-Gritty
  Domain Registration: Domain Create
  Contact Creation
  Host (aka "Nameserver") Creation
  Domain Create (con't)
  Querying existing objects: the INFO command
  Object Updates
  Object Deletions
  Beyond Basic Operations in EPP

Object Transfers
EPP Versions
Help!!
Document History
Author Credits

Document Overview

This document is intended to aid registrars who are just starting out with EPP. Whether you are new to the domain name registrar scene, or if you are growing your domain name registration portfolio with an EPP registry (e.g. .NAME, .INFO, .PRO, .BIZ, etc...), this document should give you the necessary help to get started. For those registrars who already have experience with RRP (e.g. VeriSign's COM/NET/ORG registry), this document contains helpful hints and EPP/RRP comparisons.

Back to top
 

General EPP Overview

There are two majors aspects to EPP: objects and actions. Objects are entities stored in the EPP registry, such as domains, contacts and hosts (aka "nameservers"). Actions affect changes to the registry and the objects it contains (eg. check, create, update, delete...). EPP registries and registrars communicate via messages in XML format. XML conveniently organizes data in requests and responses into logical groups and hierarchies. Because of the way the protocol is defined, it is transport independant. This means that a registry may offer any number of transport layers to carry the EPP message (eg. plain TCP, TCP+TLS, SMTP, BEEP, ...). EPP is also easily extensible. Registries, depending their own or their domain's business needs, may define additional object type or actions, or even additional payload data for existing messages.

Back to top
 

Basic things you can do with EPP

In the arena of domain names, the most obvious is registering domains. As explained earlier, EPP defines three main object types: domains, contacts and hosts. It also defines a core set of actions (some of which are not applicable to all object types): check, info, create, update, delete, transfer and renew.

For those of you who come from an RRP background, this chart draws a parallel between RRP and EPP:

  EPP RPP
Objects: domain domain
  host nameserver
  contact <new>
Actions: check check
  info status
  create add
  update mod
  del delete
  Transfer transfer
  renew renew

Outside of the realm of objects, EPP defines the following requests: login, logout, hello, and poll. Login and logout should be pretty self-explanatory: they allow a registrar to establish a persistent connection to an EPP registry. The "hello" request allows a registrar to solicit a greeting from the registry (the greeting will be explained more a little later). The poll action is the mechanism by which a registrar can retrieve notifications from the registry, such as object transfer-away notifications.

The greeting is used by an EPP registry to let the registrar know which services and options it offers. In a connection-oriented session, the greeting is spontaneously sent by the registry when the registrar connects. In a connectionless session (e.g. SMTP), the registrar must expressly ask for a greeting by sending the "hello" command. This command can also be used in connection-oriented sessions, although the services offered since the greeting was sent should not have changed.

EPP allows for two types of sessions: persistent and stateless. In a persistent session, the registrar establishes a connection (e.g. over a TCP socket) and issues the login command before any other request. The login contains the registrar's client ID, password (and optionally a new password), preferred language, preferred protocol version and a list of services which the registrar wishes to use. An EPP registry could reject a login from a registrar for a number of reasons. Those include:

  • bad client ID or password

  • invalid new password (if it was supplied)

  • unsupported protocol version

  • unsupported service

  • unsupported language or dialect.

Note that providing a new password in a login is the only way the registrar can change its password through EPP.

Here is an example of the login command where the registrar wishes to use domain, contact and host services:

Notice that the "creds" (i.e. credentials) are contained outside of the login tag. This is what facilitates stateless sessions. Once a registrar is logged in, the creds must not be present in any further commands, including the logout. In a stateless session, the registrar must specify the creds at each command. If a registrar is using a connection-oriented transport (e.g. a TCP socket), it is recommended that a persistent session be used. This is usually more efficient because the server doesn't have to validate the client ID and password at each command. Some registrars might only allow persistent sessions over connection-oriented transports. Note that it is more efficient to maintain the same connection and session for as long as possible. As many registries require secure, encrypted communications, the "handshake" portion of the connection can be resource intensive. Repeating the steps of connecting, logging in, sending a single command, logging out, and disconnecting would be very costly to the registrar and the registry. If the registrar is using a connectionless transport (e.g. SMTP), then a stateless session must be used and the login and logout commands are not valid and will be rejected.

In every EPP command, there are two other optional command elements: unspec and clTRID. The latter is pretty simple. It is a client transaction identifier holder. The registrar may use it to track requests for logging or auditing. The clTRID, if supplied, is returned along with the svTRID (server transaction identifier) in the response to an EPP command. In the response, they are both wrapped in the trID tag. It is highly recommended that the registrar use the clTRID for every "transform" action (i.e. create, delete, update, transfer, renew).

The registrar may optionally use the clTRID in query actions, but because these actions don't normally incur a charge to the registrar, transaction tracing and tracking is not as critical.

The unspec tag is a little more complex. It can be present in both EPP requests and responses. It is a placeholder for registry-specific extensions to EPP. For instance, the .info registry, during its Sunrise Registration Period, was using the unspec tag to hold the domain trademark data in create, info and update commands. The registrar should contact their registry operator to determine if there are any unspec extensions that must be used in interactions with the registry.

Now, let's look at few typical tasks that a registrar would want to perform. We'll describe the commands and the required data for those commands.

Back to top
 

The Nitty-Gritty

Domain Registration: Domain Create

Being at the core of a domain registrar's functionality, we'll start with this one. Actually, we'll start with a step a registrar should perform before issuing a domain create action. To not waste precious time of the registrant, there is a command to allow the registrar to check if a domain name is available before actually submitting a registration for it. EPP offers this in the domain check action. This command actually allows a list of domains to be checked. The command is as follows:

(A note for these XML examples: the namespace specifications for these commands might vary depending on the version of EPP the registry is using. Please see the section at the end of document regarding EPP versions.)

The response will contain the same list of domains (though not necessarily in the same order) with indicators to say whether the registry knows of this domain or not.

Here is a typical response:

The "+" sign indicates that the domain exists in the registry. The "-" sign, then logically, means that the domain does not exist in the registry and is available for registration.

If a domain is available for registration, then the registrar can continue with the domain create command. With all of the optional data defined by EPP, this command is one of the simplest. All it requires is the name of the domain to create and the authorization information for the new domain. Authorization Information (or simply "auth info") is a passphrase a registrar asks of its registrant when creating a domain or a contact. This passphrase is used by the registrant to authorize a transfer of the object to another registrar. A reminder for RRP graduates, this command equates to "add domain".

Now, unfortunately, sometimes this command might not always be this simple. First, without specifying a period of activity for the domain, the registry will apply its default, which might or might not be 1 year. It's always best to specify a period so that there's no ambiguity and no surprise if the default value is not what was expected.

Second, some registries might impose that some of the optional data is required. The .info registry, for example, requires 2 nameservers, a registrant contact and at least three other contacts, one for each type (admin, billing, and tech). So it's very likely that you might have to specify other commands before the domain create. Let's move on for the moment to the creation of other EPP objects.

Back to top
 

Contact Creation

EPP is designed for thick registry operators who require contact information for centralized WHOIS services. Therefore, an EPP registrar is allowed to create contact objects in the registry and associate them to domains. Contact object maintenance is the most complicated part of EPP. Once you've mastered it, the rest is easy.

To create a contact, a registrar must collect the following information from the registrant (optional items are marked with a '*'): name, organization*, postal address (street (up to three), city, state/province*, postal code* and country), voice phone number*, fax phone number* and email address. Now, because of the demands of a multilingual world, the postal address of a contact can be specified in UTF-8 encoding (note that some registries might not support this). EPP requires that there be at least an ASCII 7-bit version provided. This is for more legacy uses, such as traditional WHOIS.

Ok, so, the contact create command goes something like this:

Now, watch out. Depending on the version of EPP which the registry is using, you may or may not have to specify a contact ID on contact creation. At the time of this writing, the .INFO registry is/was using a version of EPP where you don't specify the contact ID. The response to the contact creation will return the newly-created Repository Object Identifier. This "ROID" will identify the contact object in associations with domain objects. In newer versions of the protocol, the registrar-specified contact id is used.

The contact create example above only shows the including of the 7-bit ASCII address in the "contact:ascii" tag. This information is mandatory (although some elements in the address are optional). There is an additional and optional address tag called "contact:i15d". The "i15d" is short for "internationalized" (starts with i ends with d with 15 characters between them. Clever, huh?). This tag can contain the contact's address with UTF-8 characters.

The sp, pc and cc tags in the address contain the state/province, postal code and country code, respectively. The country code must be specified using the standard ISO country code listing. And, yes, it currently does not include "UK" (among other countries). "GB" should be used in its place.

Once the contact is created, the object identifier can be used in associations with domain objects. Domains can have a single registrant contact. hey can also have any number of administrative, billing and technical contacts. Let's put this aside for a moment and take a look at nameserver creation.

Back to top
 

Host (aka "Nameserver") Creation

Nameserver creation is pretty simple. There are two types of nameservers: those that belong to the TLD(s) that are authoritative to the registry and those that don't (i.e. "foreign nameservers"). The difference between the two is the nameservers that are outside of the authoritative TLD(s) of the registry don't get IPs in the registry. The idea is that only the authoritative registry for the nameserver's domain should know the nameserver's IP address(es). The native nameservers can have up to 13 addresses (a limit imposed by many, if not most, registries). IP addresses in EPP come in two forms: IPv4 and IPv6. Note that some registries might not allow IPv6. Also note that the EPP registry may prohibit certain IP ranges from being used. Check the EPP Host spec or with your registrar for those ranges, but those are usually the ones that haven't been allocated for public use by IANA.

The host create command:

Notice that you can mix and match IP address types for a single host.
That's it. Pretty simple, huh?

Back to top
 

Domain Create (con't)

Now, let's get back to the domain creation. Here it is with contacts, nameservers and the period specified:

Notice that the same contact ID is being used for both the admin and tech contact types. That contact ID could have also been used for the registrant. Also take notice that the nameservers for this new domain are not using the same domain name. EPP registries will not implicitly create nameservers in the same domain namespace upon creation of the domain. That's because native nameserver require at least 1 IP address, which can't be specified in the domain create command. Note that the order of the nameserver is not significant in DNS resolution of the domain. This order is not necessarily preserved in the "domain info" response.

Back to top
 

Querying existing objects: the INFO command

Once an object is in the EPP registry, a registrar may retrieve information regarding the object. This is achieved through the "info" command. The info request for any of the currently known EPP objects is very simple. All that is required is the object identifier. For domains and nameservers, this is the fully qualified name of the object (i.e. the domain's name or the nameserver's name). For contacts, this is either the contact's ROID that was returned by the creation of the object or the contact id that was provided by the registrar in the contact create request. This depends on the version of EPP that the registry is using. For RRP users, "info" is synonymous with the "status" command. The major difference is that, in RRP, only the current sponsoring registrar is permitted to use the status command on a domain or nameserver. In EPP, all registrars are permitted to use the info command for all objects. Registry policy defines what is viewable by registrars using info. Typically, only the current sponsoring registrar is returned the object's auth info in the response from the server. This protects the object from malicious transfer requests, since the auth info is required by the registrar requesting the transfer.

To provide a typical example of usage, here is a domain info request.

The server's response to this request could be something like this:

The example response show many of the typical fields in any info response. The common fields are as follows:

  • roid -- the ROID of the object in the registry

  • status -- the current status of the object (there can be multiple); there may also be optional descriptive text for each status

  • clID -- the ID of the object's current sponsoring registrar

  • crID -- the ID of the registrar that created the object

  • crDate -- the UTC date of the object's creation

  • upID -- the ID of the registrar that last updated the object (absent if the object has never been updated)

  • upDate -- the UTC date when the object was last updated (absent if the object has never been updated)

  • trDate -- the UTC date marking the last successful transfer of the object (absent if the object has never been transferred; for hosts, this is the same value as the parent domain in the registry)

  • authInfo -- the auth info field for the object (absent if the querying registrar is not the sponsoring registrar; not applicable to host objects)

For domains, the following may also be there:

  • name -- the fully qualified name of the domain
  • registrant -- the domain's contact that is acting as the registrant
  • contact -- the domain's contacts (admin, tech or billing); there can be any number of these
  • ns -- the list of hosts serving as nameservers for resolution of the domain
  • host -- the list of hosts that exist in the same domain name space as the queried domain
  • exDate -- the UTC expiry date of the domain; the domain renew or transfer actions may be used to extend the life of a domain beyond its original creation period; note that an EPP registry may impose a maximum lifetime for domain objects (like, say, 10 years).

For hosts, the following info response fields may be present:

  • name -- the fully qualified name of the host

  • addr -- the list of IP addresses assigned to the host

  • linked -- boolean value to indicate if this host is linked to a domain

For contacts, the following fields may be present:

  • id -- the contact's id (only present in recent versions of EPP)

  • ascii -- the 7-bit ASCII version of the postal address*

  • i15d -- the UTF-8 version of the postal address*

  • linked -- boolean value to indicate if this contact is linked to a domain

* Both of the address types contain the name, org, addr, voice, fax, and email elements. The addr element further contains the street, city, sp, pc, and cc sub-elements. "sp", "pc" and "cc" being state/province, postal code, and country code, respectively.

Back to top
 

Object Updates

With all three types of objects in the registry, we can now move on to the update command.

Generally, the update command contains three elements: items to add, items to remove and items to change. The items in each of these elements depend on the type of object being updated. For example, you may add or remove contacts from a domain, or change the fax number of a contact. Please note that whatever data elements where mandatory on object creation are still mandatory on update. For example, if a domain requires at least one tech contact and you wish to change that contact, you'll have add a new tech contact and remove the old one. EPP allows you to perform those two actions in a single domain update command.

Another note: a registrar may only update objects for which it is the current sponsoring registrar.

Domain Update

The updatable values for domain objects are the registrant, the contact list, the nameserver list, the status list and the auth info. The registrant value is changeable (i.e. it "cannot" be removed or added, since it is not a list). In the update command, simply specify a new value and the server will replace the old one. If the registrant value is optional in the registry with which you are communicating, you may specify an empty tag (i.e. "<domain:registrant/>" or "<domain:registrant></domain:registrant>") and the server will "remove" the existing value. With the RTKs available today from Sourceforge, leaving the registrant value null or NULL will have it omitted from the XML request to signify to the server that no change is requested to the registrant value. Specifying an empty string (i.e. "") will force the RTK to send an empty tag to the server. The registrant must be a valid contact in the registry in order for the update to be successful.

Since both the contact and nameserver parameters are lists, values may be added or removed from them. In the update command, simply specify a valid contact or nameserver identifier to add a new value to the lists. To remove an existing contact or nameserver from the domain's current associations, specify that contact or nameserver in the "remove" list. When removing a contact, the proper contact type must be specified in the remove list. Since a single contact can cast in multiple roles with the domain, the registry needs to know specifically which contact to remove.

The status values are also contained in a list and can be added or removed. The registrar is only permitted to add or remove stati that start with "client" (eg. "clientHold"). Depending on the version of EPP in use at the registry, the list of available stati might vary (in the Java and the C++ RTK's that use the IDLs defined by a group of registry operators, the list of stati is available in the epp_DomainStatusType class or enum). When adding new stati to a domain, the registrar is permitted to specify a short text message to accompany the status. When removing stati, the descriptive text should not be included. Also if a status is already applied to a domain, the status cannot be applied again. If the registrar wishes to change the status descriptive text, then the status must be removed and then re-added to the domain. This should be possible to perform in a single update command.

The auth info is another changeable value. As it is required for domain objects, it cannot be set to a blank value, in fact EPP imposes minimum and maximum length values on the auth info.

Here is an example of a domain update command:

Contact Update

The contact update action is not as equally balanced as the domain update. The bulk of the updateable data is in the "change" portion. The only values that can be added or removed are contact stati. The format for the status values is the same as in the domain update command (i.e. only client-usable status values, plus an optional descriptive text).

The changeable data for a contact is the address. Both of them actually, since there's an ASCII version and an I15D version.

Host Update

This is the simplest of the update commands. For a host, IP addresses and stati may be added or removed. Also, the host's name may be changed. The status additions and removals are the same as with domains and contacts. The IP addresses follow the same format as in the host create (i.e. the actual IP address and address type).

The host update command allows for the full host name to be changed. For instance, you may rename "ns1.domain.tld" to "ns2.domain.tld". This should usually present no problem, so long as the former does not already exist. You may also rename the domain in which the host resides. For example, changing "ns1.domain1.tld" to "ns1.domain2.tld". Of course, to do this, "domain2.tld" must exist in the registry. And if "domain2.tld" is outside of the TLD bounds of the registry, the restriction of no IP addresses comes into play.

Here a sample host update command:

Back to top
 

Object Deletions

Just as you can create objects in a registry, you can delete them too. Of course, you must be the current sponsoring registrar in order to successfully delete an object. There also might be further restrictions on some objects. For instance, objects associated to other objects cannot be deleted until the association is removed. An example of this would be a contact being associated with a domain. The contact cannot be deleted until its associate with the domain is removed (via the domain update command). Note though that the domain can be delete without disassociated it from the contacts and hosts. The delete (once the object truly disappears) automatically frees associated objects.

All delete commands follow the sample simple pattern. All that is required is the object's identifier (domain name, host name or contact ID or ROID). Here is a delete command for a host object:

Note that some registries may impose time restrictions on object deletions, especially in regard to domains. It is common for a registry to allow a "hard" delete within 5 days of domain creation, and to provide a "soft" delete after the first 5 days. A "hard" delete is when the domain is truly removed from the registry upon successful delete. A "soft" delete adds the "pendingDelete" status to the domain. A registry-defined period of time later (often 5 days) the domain will truly disappear. This is to allow accidental deletes to be undone, though that usually requires a call to the registry operator support staff. Check with the registry with which you are dealing to determine the policies applicable to you.

Back to top
 

Beyond Basic Operations in EPP

Outside the basic check, info, create, update and delete, there's a few more operations available to some objects.

Domain Renewals

When a domain is created, a "period" is usually specified by the registrar (or defaulted by the registry if it's absent from the command). The period, in years or in months, defines the lifetime of the domain object. After that period passes, the domain expires. Although, things may not be that simple. We'll deal with registry policies in a moment. First, let's take a look at extending the validity period of a domain.

(Note that none of this section applies to Contact or Host objects. Those objects never expire, although when and if a domain expires, the child hosts, if any, will likely be locked, which could affect the resolution of other domains they serve.)

Anytime before a domain expires, it may be renewed by the sponsoring registrar. The expiry date of a domain can be found through the domain info command. The original expiry date is also returned on domain creation. In the domain renew command, three values can be provided: the domain name (required), the current expiry date (year, month and day -- required) and the renewal period (optional). The current expiry is required to provide idempotency to the renew command. This means that the same renew command cannot be processed multiple times. This protects the registrar against such things as "double clicks" from the registrant, incomplete renew requests because of a broken connection to the registry or, otherwise, bugs in registrar code. To issue a subsequent renewal on the same domain, the new expiry date must be used (it is provided in the renew response). The period allows the registrar to specify a value other than the registry's default renewal period (which is often a year). According to EPP, the renewal period can be anywhere from 0 to 99 years or months. Registries often narrow this down a little ('cause 0 years is just silly). Typically, a registry limits the expiration date of a domain to be no more than 10 years in the future.

Now, what happens when a domain expires? Well, this depends heavily on registry policy. EPP does not define any action that the registry must take when an object expires. Registries tend to treat domains similar to magazine subscriptions. Registrant retention is important because it generates revenue. So registries will try to encourage registrants (through their registrars) to renew their domains. This is also good for registrars because it means revenue to them as well. Typical actions you might see a registry take are auto-renewal of domains which have expired. Normally the registrar will have a grace period during which the domain can be deleted with no charge. Some registries might simply extend the life of the domain for a short period of time to give late registrants time to decide on renewal, and attempt to delete the domain if there is no action taken by the registrar. The registrar should be aware that during these "grace" periods, the domains might go into a locked state where the name is no longer resolvable in DNS. If there are hosts in that domain that are serving other domains, then those domains might become unresovable as well. Between registry-auto-renewals and notifications to registrants, domain expiry and renewal can be a complex matter. Be sure to contact your registry operator to make sure you know which policies are in place.

Those with experience with RRP and VeriSign's COM/NET/ORG registry will know that domain expiry and renewals can be tricky. The registrar's system should be proactive in dealing with domain expirations using, perhaps, advance notifications to the registrant. Some registrants might just never respond, so the registrar should be able to delete the domain before there is a charge for the auto-renewal.

Back to top
 

Object Transfers

In EPP, both domain and contact objects may transferred between registrars. This changes the sponsorship of the object in the registry from the losing to the gaining registrar. The key to object transfers is the authorization information for each object. For those coming from RRP, the auth info is what prevents registrars from "stealing" domains (and now contacts) from other registrars. Only the current sponsoring registrar, and, consequently, the registrant, have access to the auth info (via the "info" command). The registrant gives this string to the registrar to which they wish to transfer. This allows the requesting (or "gaining") registrar to issue a transfer for an object and to query its current transfer status. Once an object is successfully transferred, the gaining registrar should recommend the registrant change their auth info for the transferred object so that the losing registrar cannot reclaim the object without the registrant's permission in a subsequent transfer.

The transfer command in EPP has several operations: query, request, approve, reject and cancel. The requesting registrar should perform a transfer query first to ensure that the auth info is valid. Here is the transfer query command for a domain object:

The response would look something like this:

The response contains the information of the current or most recent transfer issued on the queried object. If the object has never been transferred, then the EPP registry will return an error code. If the trStatus is "pending" then a transfer is currently being executed on the object. Other stati for transfers are: approved, cancelled, rejected, autoApproved, and autoCancelled. Those all indicate that the last transfer operation is complete and another may be issued. The "reID" and "reDate" are the client id of the requesting registrar, and the date of the request, respectively. The "acID" is the ID of the "losing" registrar for that transfer request. The "acDate" can have two meanings. If the transfer is pending, then the acDate is the date by which the losing registrar can take action on the transfer (i.e. approve or reject it). If the transfer is complete, then this is the date when the transfer was finalized (either by the losing registrar approving or rejecting it, the gaining registrar canceling it or by the EPP registry taking automatic action). The proposed expiry date from transferring domains is in "exDate". This member will not be present for contact transfers since contacts never expire.

Maybe this would be a good time to talk about how transfers work in EPP. RRP users will find most of this familiar.

  1. A registrant goes to a new registrar with their domain. Maybe the new registrar has a better package deal with better prices?

  2. The registrant provides the auth info to the registrar.

  3. The registrar issues a transfer request, with an optional renewal period. If the auth info provided was invalid, then the transfer request will fail. (A transfer "query" could have told the registrar this, but why perform in two requests to the registry what you can accomplish with a single request?)

  4. If the request was successful, the current sponsoring registrar receives notification that a domain of theirs is being transfered away.

  5. Depending on registry policy, the losing registrar might have a couple of days to proactively approve or reject the transfer. The requesting registrar also has a chance to cancel the transfer request during this time.

  6. If the losing registrar takes no action, the registry will likely automatically approve or reject the transfer depending on their policies. Most will usually auto-approve transfers.

  7. The gaining registrar should receive notification of the results of the transfer. If the transfer is successful, the gaining registrar will be charged for the renewal period of the domain. If none was specified in the request, the registry usually assigns a default (often 1 year).

So, here's the transfer request for a domain:

Notice that the requesting registrar is asking for a 2 year renewal. The response to the transfer should be identical to the transfer query request. In fact, responses to all types of transfer operations have the same format.

If the losing registrar wishes to take action on a transfer, the following command may be used:

Only the domain name and auth info are required in the request from the losing registrar.

As mentioned in the steps above, the current sponsoring registrar will receive notification of a pending transfer. This will likely be through the poll mechanism, which is described below. The optional data that will appear in the poll response will be the results in a transfer query.

Registrar Session Management

As a registrar, it isn't simply enough to be able to manage objects. As a registry client, you should be able to manage your sessions as well. This includes such aspects as keeping a persistent connection alive during period of little or no activity and dealing with notifications from the registry. Luckily, in EPP, those two can be accomplished with a single command: Poll.

Polling

As stated earlier, polling accomplishes two goals: keeping a session alive and retrieving notifications from the registry. It's great for keeping a persistent connection alive because of its harmless nature. Its default form is a query. Registries that use EPP maintain a queue of messages and notifications for each registrar. These messages will typically be regarding object transfers, but may also include such things as low balance notifications, pending domain expiry, auto-renewal notifications, and so on. Unfortunately, with exception of a plain text message, EPP doesn't define the data that can be returned in a poll response. This is up to registry policy and EPP extensions.

The way that poll works is such: A registrar may poll its queue in the registry. Poll comes in two operations: Query and Acknowledge. As a registry processes changes to objects, notifications may be added to the end the registrar's queue. The registrar may use poll-query to retrieve the message sitting at the front of the queue. If the queue is empty the response code and text will say that. If there is a notification, there will be a message id, message text and optional data in the response. The registrar must then issue a "poll/ack" to dequeue the message. The notification's id must be supplied in the poll/ack. The registrar repeats this process until the queue is empty.

Most registries will terminate a persistent connection if there is no activity on the connection for a given period of time (contact your registry to find out that period). For a single connection, the registrar should keep track of the last communication time and poll the registry when the elapsed time is just under the registry timeout value. If you poll too often, you might be needlessly taxing the registry's system and you might be wasting time when your system processor could be doing something more productive.

RRP users can equate poll with the 'describe' command for keeping connections alive. There is no equivalent of registry message queues in RRP.

EPP Response Codes

EPP organizes its error codes into groups. There are two major headings: success and failure. The former has response codes in 1000s range. The latter in the 2000s range. Within these ranges the response codes are further divided. The group is as follows:

x0xx -- Protocol syntax

x1xx -- Server policy and implementation rules

x2xx -- Security and authorization

x3xx -- Data management

x4xx -- Server and internal errors

x5xx -- Connection management

Every response in EPP contains a response and a corresponding text. Along with that is a language indicator. The default language is "en". Registries have the option of providing the message texts in the language that was indicated in the "creds" (for example, at login time).

1000 - Command completed successfully

Everything's a-okay! The command was successful. If a object was created, then an "info" should now be possible on that object.

1300 - Command completed successfully; no messages

Standard Poll response when there are no message waiting in the server for your registrar account.

1301 - <variable notification message from poll response>

Poll response where a meaning full message is provided. Depending on the message, there might also be additional data included in the Poll response (e.g. to identify the domain being transferred).

1500 - Command completed successfully; ending session

The standard response to a successful logout.

2000 - Unknown command

The registrar has sent the registry an unknown command (i.e. none of login, logout, hello, poll, check, info, create, update, delete, transfer, or renew).

2001 - Command syntax error

Generic error message when the server doesn't understand what you've sent. Maybe the XML is invalid. Try passing it through a validator. Perhaps you are including parameters that don't belong to the command in question.

2002 - Command use error

The registrar is asking the registry to do something that is not valid in the current context, like a logout before a login. Or a domain create (without creds) outside of a session in a connection-based transport (e.g. TCP).

2003 - Required parameter missing

A domain create without the domain name. Contact update without any "add", "rem" and "chg" tags. Something was missing in the request that the server requires to execute the command.

2004 - Parameter value range error

This error code can means a few things. Most common causes are parameters that are too long (domain names, auth info, contact name, etc...). It could also be used for numeric parameters that are either too large or too small for the range defined by the registry (e.g. domain period). Data should be verified as much as possible by the registrar before sending to the registry. Return to the registrant and get him or her to correct the input data and resubmit.

2005 - Parameter value syntax error

The format of the parameter is not correct. This usually does not include length checking, which should be covered by error code 2004. A typical cause of this error code is in contact creates where the voice or fax phone number don't match the E.164 format for international telephone numbers. A (North American) example of this would be "+1.4165550101". The regular expression for this in the XML schemas is "(\+[0-9]{1,3}\.[0-9]{1,12})?". The number between the "+" and "." signs is the country's dialing code.

2100 - Unimplemented protocol version

The registrar has attempted a login using a version of the protocol that is not supported by the registry. The registrar is free to attempt further logins with different version numbers using the same connection.

2101 - Unimplemented command

This error will be returned if an action being attempted on an object is not implemented by either the protocol or the server. For example, host renew. Further attempts of this command will fail.

2102 - Unimplemented option

This error code would be returned if the registrar is attempting to issue a sessionless command (with creds) when the server has not implemented that feature. Essentially, 2102 will appear if the registrar is attempting a valid command with options that are not supported by the registry.

2103 - Unimplemented extension

An extension that the registrar is attempting to use (maybe from another registry) is not supported by this registry. Removing the extension from the XML request and retry the command.

2104 - Billing failure

This could mean a few things. The most command cause is that the registrar is out of funds in the registry. Further retries of the command will fail until the registrar's account balance is increased. Some registries may implement a "low threshold" notification system so that registrars can be warned when their balance runs dangerously low. If the registrar's balance is not the problem, then the server may be experiencing internal problems. The registry operator should be contacted in this case to report the problem.

2105 - Object is not eligible for renewal

2106 - Object is not eligible for transfer

A typical case for this error code and message would be trying to transfer an object shortly after it's been created. In the case of domain registries, some have defined a period of time after a domain has been created when transfers are not permitted.

2200 - Authentication error

In a session-based connection, this error code will be returned on a login if the client ID or password are incorrect. This can also be returned by any command in a sessionless situation where the command creds are invalid.

2201 - Authorization error

This response would normally occur when trying to perform an update, delete or renew an object that is not sponsored by the acting registrar.

2202 - Invalid authorization information

This response occurs if the auth info in the transfer command (query or request) is invalid. Note that the auth info is not required for the approve, reject and cancel transfer operations. The registrar should confirm the correctness of the auth info with the registrant before continuing.

2300 - Object pending transfer

If a domain is already in the midst of a transfer, this error will be returned by the registry. Perhaps the registrant has forgotten that they have already requested a transfer (through you or via another registrar). If your registrar is the losing registrar of the current pending transfer, maybe the registrant has changed his or her mind and wishes to return to you. In that case, you can issue a transfer reject command on the object and the requesting registrar will be notified of the cancellation.

2301 - Object not pending transfer

This code will be returned if a transfer approve, reject or cancel is issue on an object that is not in a pending transfer state. Perhaps the registrar's records are out of sync with the registry. Perform an info on the object and determine a new course of action.

2302 - Object exists

This error code will be returned if the registrar attempts to create an object that already exists. The registrar should go back to the registrant to present other alternatives (maybe variations on the original domain name). As the create command is usually the most resource-intensive in the registry, the registrar should avoid getting this message. Using the check command before a create is *highly* recommended. But in cases of race conditions (like at a scheduled release of a popular domain name), a create might still return this error code even after a check determined that the object was not known to the registry.

2303 - Object does not exist

Update, delete, renew and transfer commands will return this code if the object is not found in the registry. Correct the request and try again.

2304 - Object status prohibits operation

Mostly self-explanatory. Typical cases are trying to issue a transfer for an object that has been locked by the current sponsoring registrar. Or an update to an object that is locked. The current owning registrar would have to remove that status in order to allow the operation to be successful. If the object is not your own, then perhaps there are compliance or legal issues that dictate that the object should locked until they are resolved.

2305 - Object association prohibits operation

This error could occur if the registrar tries to delete a host or contact that is currently associated to a domain. The association must be broken before the delete is issued.

2306 - Parameter value policy error

This will typically happen when a request to the registry is within proper EPP bounds, but the registry has stricter validation. For example, a domain create where the period exceeds the registry's policy limits (most has a maximum of 10 years, where EPP allows for more).

2307 - Unimplemented object service

In this case, the registry might have defined a particular object, but does not permit all EPP actions to be performed upon it (like <contact:renew>). Or perhaps, the registry has not defined the object at all.

2308 - Data management policy violation

2400 - Command failed

Something went wrong in the registry and none of the 2000, 2100, 2200 or 2300 error codes could handle the problem. Verify the XML you are sending to the registry to see if it's indeed valid. If you are still stumped, it might be best to contact the registry operator. Give them as much information as you can (XML logs are the best).

2500 - Command failed; server ending session

Similar to 2400, but this time the registry server thought that the command failure was fatal to your session and has decided to terminate it. Same recommendations as with 2400.

2501 - Timeout; server ending session

There has been no activity on the connection for some time. Some registry might send this message just before cutting the connection (although some may skip this message altogether). Increase your polling frequency and reconnect.

2502 - Session limit exceeded; server closing connection

The registry has implemented a limit to the number of connections a registrar may have. This may be the same for all registrars or may be adjustable depending on the registrar's registration rate. Either reduce the number of connections your are attempting or contact the registry operator to see if the limit may be move up for your registrar. Note that some registries might simply refuse additional connections (base on source IP address) without sending this message.

There is an implementation of a Registrar Toolkit available from SourceForge that has two additional error code, which are not part of the protocol and which are not generated by the registry. If you use this toolkit, you might encounter these error codes.

2600 - Communications failure

This error usually occurs as a connection is being attempted. Perhaps the connection information is incorrect or the server is down, or unreachable. Retrying the connection couldn't hurt, but further investigation is recommended.

2601 - Unexpected server disconnect

The operating system has signaled to the client that the server has closed its end of the socket connection. Retrying the connection is recommended, unless something unusual has occurred (physical network connection broken, etc...). If this occurs immediately after a successful connection, then perhaps the SSL/TLS certificate the registrar is using has expired or its signing certificate authority is not recognized by the server. Another possibility is that the registrar's system has reach its limit on connection to the registry.

Back to top
 

EPP Versions

Because of the issues of contractual launch dates and schedules, some registries have opted to take a snapshot of the Extensible Provisioning Protocol in a point in time and implement that version. At the time of this writing, Afilias' .INFO registry is using a version of EPP which dates around April 2001. As other registries launch synchronous registration systems other versions will be in place.

The latest specs can always be found at the IETF ( http://www.ietf.org ). They are currently in Internet Draft form and can be found at http://ietf.org/html.charters/provreg-charter.html .

The version used by the .INFO registry can be found in the EPP-RTK distribution from Sourceforge. Download any distribution in the 0.3.X version range here http://sourceforge.net/projects/epp-rtk . The specs are contained in two directories under epp-rtk/java/doc/epp. epp01 is the directory that contains the draft docs for the "01" release of the protocol. epp02 is the directory that contains the XML schemas for the pre-release of the "02" spec. Unfortunately, no drafts exist for these schemas. The registrar should read the drafts on epp01 and then supplement that with the schemas from epp02.

Back to top
 

Help!!

If after reading this document, you still more information or if you have any questions, browse over to http://epp-rtk.sourceforge.net -- this will lead you to the SF site for the EPP-RTK project. From there you can sign up for the epp-rtk-devel or epp-rtk-general mailing lists. Ask your questions there or search through the archives to see if anyone else has already asked the same questions. Feel free also to post questions on the discussion boards (though the mailing lists are better).

Back to top
 

Document History

Daniel Manley; Aug 23, 2001; Initial release; ver 0.1.0.

Daniel Manley; Aug 30, 2001; Minor spelling corrections and misc rewording where clarity was lacking; ver 0.1.1

Daniel Manley; Sept 10, 2001; EPP corrections and rewording so that the document better reflects the text of the protocol specs; ver 0.1.2

Daniel Manley; Sept 28, 2001; added more descriptions to the EPP Response codes; ver 0.1.3

Back to top
 

Author Credits

This document was orignally written by Daniel Manley (tubadanm@users.sourceforge.net), in August of 2001, at the request of Liberty Registry Management Services, the outsourcer of the .INFO registry for Afilias. I hope those reading this will feel a little more at ease with EPP.

I'd also like to thank Scott Hollenbeck, the author of EPP, for his input into this document... and for the use of his XML examples.

Back to top
 

 

 

| Table of Contents | Section 1 | Section 2 | Section 3 | Section 4 |
| Section 5 | Section 6 | Section 7 | Section 8 | Section 9 | Section 10 |

Comments concerning this site should be sent to orginfo@isoc.org.
©2002 ISOC and Afilias Ltd.  All rights reserved.