Date post: | 28-Oct-2015 |
Category: |
Documents |
Upload: | robert-adams |
View: | 158 times |
Download: | 4 times |
- 3 -
Table of Contents
1. INTRODUCTION ................................................................................................................ - 9 -
2. EURID IMPLEMENTATION SPECIFICITIES .......................................................................... - 11 -
2.1. TIME ZONE .......................................................................................................................................... - 11 -
2.2. STANDARD AND EURID EPP SCHEMA DIFFERENCES .................................................................................... - 11 -
2.2.1. Standard EPP Schemas ........................................................................................................... - 11 -
2.2.2. EURid-specific schemas .......................................................................................................... - 12 -
2.2.3. Conceptual differences ........................................................................................................... - 12 -
2.2.4. Data differences ..................................................................................................................... - 13 -
2.2.5. Added commands ................................................................................................................... - 14 -
2.2.6. Unimplemented EPP commands ............................................................................................ - 14 -
2.3. TRANSPORT AND SECURITY ..................................................................................................................... - 15 -
2.4. NUMBER OF PARALLEL CONNECTIONS ....................................................................................................... - 15 -
2.5. VERSIONS ........................................................................................................................................... - 15 -
2.6. EURID-SPECIFIC OBJURI’S ..................................................................................................................... - 16 -
2.7. EURID-SPECIFIC EXTURI’S ..................................................................................................................... - 16 -
3. STRUCTURE OF EPP COMMANDS AND RESPONSES .......................................................... - 18 -
3.1. INTRODUCTION .................................................................................................................................... - 18 -
3.2. XML ................................................................................................................................................. - 18 -
3.2.1. XML declaration ..................................................................................................................... - 18 -
3.3. BYTE COUNT HEADING ........................................................................................................................... - 18 -
3.4. XML VALIDATION ................................................................................................................................. - 20 -
3.4.1. XML syntax error .................................................................................................................... - 20 -
3.5. COMMAND FORMAT ............................................................................................................................. - 22 -
3.5.1. Client EPP command ............................................................................................................... - 22 -
3.5.2. Server EPP response ............................................................................................................... - 23 -
4. SESSION HANDLING ........................................................................................................ - 26 -
4.1. INTRODUCTION .................................................................................................................................... - 26 -
4.1.1. Transport and security ............................................................................................................ - 26 -
4.1.2. Hostnames and port numbers ................................................................................................ - 26 -
4.2. HELLO / GREETING ............................................................................................................................... - 27 -
4.2.1. Purpose ................................................................................................................................... - 27 -
4.2.2. Request syntax........................................................................................................................ - 27 -
4.2.3. Reply syntax ............................................................................................................................ - 28 -
4.2.4. Examples................................................................................................................................. - 28 -
4.3. LOGIN ................................................................................................................................................ - 29 -
4.3.1. Purpose ................................................................................................................................... - 29 -
4.3.2. Request syntax........................................................................................................................ - 29 -
4.3.3. Which <objURI> or <extURI> to use? ...................................................................................... - 30 -
4.3.4. What happens if one forgets a required extURI? ................................................................... - 30 -
4.3.5. Reply syntax ............................................................................................................................ - 30 -
4.3.6. Return codes ........................................................................................................................... - 31 -
4.3.7. Examples................................................................................................................................. - 31 -
4.4. LOGOUT ............................................................................................................................................. - 32 -
4.4.1. Purpose ................................................................................................................................... - 32 -
4.4.2. Request syntax........................................................................................................................ - 32 -
4.4.3. Reply syntax ............................................................................................................................ - 32 -
- 4 -
4.4.4. Return codes ........................................................................................................................... - 32 -
4.4.5. Examples................................................................................................................................. - 33 -
5. CONTACTS ...................................................................................................................... - 35 -
5.1. INTRODUCTION .................................................................................................................................... - 35 -
5.1.1. Contact ID’s ............................................................................................................................ - 35 -
5.1.2. Contact types .......................................................................................................................... - 35 -
5.1.3. Contact coordinates ............................................................................................................... - 36 -
5.2. CREATE CONTACT ................................................................................................................................. - 37 -
5.2.1. Purpose ................................................................................................................................... - 37 -
5.2.2. Request syntax........................................................................................................................ - 37 -
5.2.3. Reply syntax ............................................................................................................................ - 39 -
5.2.4. Return codes ........................................................................................................................... - 40 -
5.2.5. Examples................................................................................................................................. - 41 -
5.3. DELETE CONTACT ................................................................................................................................. - 42 -
5.3.1. Purpose ................................................................................................................................... - 42 -
5.3.2. Request syntax........................................................................................................................ - 42 -
5.3.3. Reply syntax ............................................................................................................................ - 42 -
5.3.4. Return codes ........................................................................................................................... - 43 -
5.3.5. Examples................................................................................................................................. - 43 -
5.4. UPDATE CONTACT ................................................................................................................................ - 44 -
5.4.1. Purpose ................................................................................................................................... - 44 -
5.4.2. Request syntax........................................................................................................................ - 44 -
5.4.3. Reply syntax ............................................................................................................................ - 46 -
5.4.4. Return codes ........................................................................................................................... - 46 -
5.4.5. Examples................................................................................................................................. - 47 -
5.5. INFO CONTACT ..................................................................................................................................... - 48 -
5.5.1. Purpose ................................................................................................................................... - 48 -
5.5.2. Request syntax........................................................................................................................ - 48 -
5.5.3. Reply syntax ............................................................................................................................ - 49 -
5.5.4. Return codes ........................................................................................................................... - 50 -
5.5.5. Examples................................................................................................................................. - 50 -
6. DOMAINS ....................................................................................................................... - 52 -
6.1. INTRODUCTION .................................................................................................................................... - 52 -
6.1.1. Associating name servers to a domain name ......................................................................... - 52 -
6.1.2. Domain name extension ......................................................................................................... - 52 -
6.1.3. Key Data Interface (secDNS 1.1) ............................................................................................. - 52 -
6.1.4. Valid term period values ......................................................................................................... - 53 -
6.2. CREATE DOMAIN .................................................................................................................................. - 54 -
6.2.1. Purpose ................................................................................................................................... - 54 -
6.2.2. Request syntax........................................................................................................................ - 54 -
6.2.3. Reply syntax ............................................................................................................................ - 57 -
6.2.4. Return codes ........................................................................................................................... - 57 -
6.2.5. Examples................................................................................................................................. - 59 -
6.3. DELETE DOMAIN .................................................................................................................................. - 60 -
6.3.1. Purpose ................................................................................................................................... - 60 -
6.3.1.1. Cancelling a scheduled deletion ............................................................................................. - 60 -
6.3.2. Request syntax........................................................................................................................ - 60 -
6.3.3. Reply syntax ............................................................................................................................ - 61 -
6.3.4. Return codes ........................................................................................................................... - 61 -
- 5 -
6.3.5. Examples................................................................................................................................. - 62 -
6.4. RENEW DOMAIN .................................................................................................................................. - 63 -
6.4.1. Purpose ................................................................................................................................... - 63 -
6.4.2. Request syntax........................................................................................................................ - 63 -
6.4.3. Reply syntax ............................................................................................................................ - 64 -
6.4.4. Return codes ........................................................................................................................... - 64 -
6.4.5. Examples................................................................................................................................. - 65 -
6.5. UPDATE DOMAIN ................................................................................................................................. - 66 -
6.5.1. Purpose ................................................................................................................................... - 66 -
6.5.2. Request syntax........................................................................................................................ - 67 -
6.5.3. Reply syntax ............................................................................................................................ - 70 -
6.5.4. Return codes ........................................................................................................................... - 70 -
6.5.5. Examples................................................................................................................................. - 71 -
6.6. CHECK DOMAIN ................................................................................................................................... - 73 -
6.6.1. Purpose ................................................................................................................................... - 73 -
6.6.2. Request syntax........................................................................................................................ - 73 -
6.6.3. Reply syntax ............................................................................................................................ - 74 -
6.6.4. Return codes ........................................................................................................................... - 75 -
6.6.5. Examples................................................................................................................................. - 75 -
6.7. INFO DOMAIN ...................................................................................................................................... - 76 -
6.7.1. Purpose ................................................................................................................................... - 76 -
6.7.2. Request syntax........................................................................................................................ - 76 -
6.7.3. Reply syntax ............................................................................................................................ - 77 -
6.7.4. Return codes ........................................................................................................................... - 79 -
6.7.5. Examples................................................................................................................................. - 80 -
7. TRANSFER DOMAIN ........................................................................................................ - 82 -
7.1. PURPOSE ............................................................................................................................................ - 82 -
7.2. REQUEST SYNTAX ................................................................................................................................. - 82 -
7.3. REPLY SYNTAX ..................................................................................................................................... - 84 -
7.4. RETURN CODES .................................................................................................................................... - 84 -
7.5. EXAMPLES .......................................................................................................................................... - 86 -
8. NAME SERVER GROUPS .................................................................................................. - 89 -
8.1. INTRODUCTION .................................................................................................................................... - 89 -
8.2. CREATE NAME SERVER GROUPS ............................................................................................................... - 89 -
8.2.1. Purpose ................................................................................................................................... - 89 -
8.2.2. Request syntax........................................................................................................................ - 89 -
8.2.3. Reply syntax ............................................................................................................................ - 90 -
8.2.4. Return codes ........................................................................................................................... - 90 -
8.2.5. Examples................................................................................................................................. - 90 -
8.3. DELETE NAME SERVER GROUPS ............................................................................................................... - 91 -
8.3.1. Purpose ................................................................................................................................... - 91 -
8.3.2. Request syntax........................................................................................................................ - 91 -
8.3.3. Reply syntax ............................................................................................................................ - 91 -
8.3.4. Return codes ........................................................................................................................... - 92 -
8.3.5. Examples................................................................................................................................. - 92 -
8.4. UPDATE NAME SERVER GROUPS .............................................................................................................. - 93 -
8.4.1. Purpose ................................................................................................................................... - 93 -
8.4.2. Request syntax........................................................................................................................ - 93 -
8.4.3. Reply syntax ............................................................................................................................ - 93 -
- 6 -
8.4.4. Return codes ........................................................................................................................... - 94 -
8.4.5. Examples................................................................................................................................. - 94 -
8.5. CHECK NAME SERVER GROUPS ................................................................................................................ - 95 -
8.5.1. Purpose ................................................................................................................................... - 95 -
8.5.2. Request syntax........................................................................................................................ - 95 -
8.5.3. Reply syntax ............................................................................................................................ - 96 -
8.5.4. Return codes ........................................................................................................................... - 96 -
8.5.5. Examples................................................................................................................................. - 96 -
8.6. INFO NAME SERVER GROUPS ................................................................................................................... - 97 -
8.6.1. Purpose ................................................................................................................................... - 97 -
8.6.2. Request syntax........................................................................................................................ - 97 -
8.6.3. Reply syntax ............................................................................................................................ - 98 -
8.6.4. Return codes ........................................................................................................................... - 98 -
8.6.5. Examples................................................................................................................................. - 99 -
9. KEYGROUPS .................................................................................................................. - 101 -
9.1. INTRODUCTION .................................................................................................................................. - 101 -
9.2. CREATE KEYGROUP ............................................................................................................................. - 102 -
9.2.1. Purpose ................................................................................................................................. - 102 -
9.2.2. Request syntax...................................................................................................................... - 102 -
9.2.3. Reply syntax .......................................................................................................................... - 103 -
9.2.4. Return codes ......................................................................................................................... - 103 -
9.2.5. Examples............................................................................................................................... - 104 -
9.3. DELETE KEYGROUP.............................................................................................................................. - 105 -
9.3.1. Purpose ................................................................................................................................. - 105 -
9.3.2. Request syntax...................................................................................................................... - 105 -
9.3.3. Reply syntax .......................................................................................................................... - 105 -
9.3.4. Return codes ......................................................................................................................... - 106 -
9.3.5. Examples............................................................................................................................... - 106 -
9.4. UPDATE KEYGROUP ............................................................................................................................ - 107 -
9.4.1. Purpose ................................................................................................................................. - 107 -
9.4.2. Request syntax...................................................................................................................... - 107 -
9.4.3. Reply syntax .......................................................................................................................... - 108 -
9.4.4. Return codes ......................................................................................................................... - 108 -
9.4.5. Examples............................................................................................................................... - 109 -
9.5. CHECK KEYGROUP............................................................................................................................... - 110 -
9.5.1. Purpose ................................................................................................................................. - 110 -
9.5.2. Request syntax...................................................................................................................... - 110 -
9.5.3. Reply syntax .......................................................................................................................... - 110 -
9.5.4. Return codes ......................................................................................................................... - 111 -
9.5.5. Examples............................................................................................................................... - 111 -
9.6. INFO KEYGROUP ................................................................................................................................. - 112 -
9.6.1. Purpose ................................................................................................................................. - 112 -
9.6.2. Request syntax...................................................................................................................... - 112 -
9.6.3. Reply syntax .......................................................................................................................... - 112 -
9.6.4. Return codes ......................................................................................................................... - 113 -
9.6.5. Examples............................................................................................................................... - 113 -
10. POLL ............................................................................................................................. - 115 -
10.1. PURPOSE .......................................................................................................................................... - 115 -
10.2. REQUEST SYNTAX ............................................................................................................................... - 115 -
- 7 -
10.3. REPLY SYNTAX ................................................................................................................................... - 116 -
10.3.1. Response to a ‘req’ operation ............................................................................................... - 116 -
10.3.2. Response to an ‘ack’ operation ............................................................................................ - 116 -
10.4. RETURN CODES .................................................................................................................................. - 117 -
10.5. EXAMPLES ........................................................................................................................................ - 117 -
11. INFO REGISTRARS ......................................................................................................... - 119 -
11.1. PURPOSE .......................................................................................................................................... - 119 -
11.2. REQUEST SYNTAX ............................................................................................................................... - 119 -
11.3. REPLY SYNTAX ................................................................................................................................... - 119 -
11.4. EXAMPLES ........................................................................................................................................ - 120 -
APPENDIX 1: ACCEPTED COUNTRY CODES FOR REGISTRANT CONTACTS ................................ - 122 -
APPENDIX 2: ACCEPTED LANGUAGE CODES FOR REGISTRANT CONTACTS .............................. - 123 -
APPENDIX 3: INDEX FOR ALL EPP COMMAND EXAMPLES ...................................................... - 124 -
- 9 -
1. Introduction
This document details the EPP based interface as implemented by EURid.
EPP is a protocol for registering and managing domain names (and not only) in a generic way. Each
registry has its own way of working, which means that some features will apply, while others will
have a slightly different implementation. This is why the designers of EPP have made it "extensible"
from the outset. Due to some fundamental differences in the conceptual model, as well as in the
data format of some fields, a few compromises have been made.
For each possible command, we will look briefly at the command and response syntax and relate it
to the EURid situation. As you will discover, because of the legal framework we are working within,
there are some fundamental differences that must be taken into account. We have tried to keep as
close to the standard as possible, but certain policy decisions for the .eu domain space simply do not
fit within the EPP framework.
XML schemas are a means of describing exactly the possible content of an XML document. As such,
we refer to the schema definitions that describe EPP’s syntax. When working with XML, you are
expected to send a valid document. It is for this reason that you should validate your document
against the schemas provided. In order to ensure that this is carried out in all cases, the EURid EPP
system will use a validating XML parser to run a validation as the first step of the handling of the
XML document. Invalid documents will generate an error message from the validation tool which is
sent back to the sender.
- 11 -
2. EURid implementation specificities
2.1. Time zone
EURid's EPP system returns the date and time in UTC, as specified by the EPP standard; however, the
registry uses local Belgian time (CET/CEST) for all operations. Please note that this can have an
impact when scheduling transactions close to midnight. This may result in the command being
executed on a different day (e.g. a command scheduled at 2012-08-31T23:59:59.000Z would be
executed at 2012-09-01 01:59:59.000 CEST). Normally, Belgian time is UTC +1h. During Daylight
Savings Time it is UTC +2h.
2.2. Standard and EURid EPP Schema differences
The schemas describe SYNTACTICALLY VALID documents (as far as the protocol is concerned). The
Extensible Provisioning Protocol aims at being generic in order to accommodate a range of situations
where other TLDs have different procedures. Furthermore, EPP allows for the protocol to be
extended (these can be mandatory). Consequently, a document that is valid in one environment
might be invalid in another.
EURid opted to adapt the schema (through extensions) that keeps divergences from the “standard”
to a minimum. Also note that there are two (2) levels of limitations: one imposed by the EPP schema
(as far as possible, we have used the standard schema) and one imposed by the .eu policy or
technical implementation.
2.2.1. Standard EPP Schemas
Use the standard EPP schemas as defined in the RFCs.
Schema file Remark
contact-1.0.xsd RFC5733
domain-1.0.xsd RFC5731
epp-1.0.xsd RFC5730
eppcom-1.0.xsd RFC5730
host-1.0.xsd N.A.
secDNS-1.1.xsd RFC5910
- 12 -
2.2.2. EURid-specific schemas
Schema file Description all-1.0.xsd Utility schema file that imports all the other schema files.
authInfo-1.0.xsd Extension to info command (in the context of a domain name transfer).
contact-ext-1.0.xsd Specification of the contact object extensions
domain-ext-1.0.xsd Specification of the domain object extensions
dss-1.0.xsd Specification of the DSS extension
dynUpdate-1.0.xsd Specification of dynamic update notifications
euridcom-1.0.xsd Shared elements in EURid extensions.
idn-1.0.xsd Specification of the idn:mapping extension
keygroup-1.1.xsd Specification of the keygroup object
nsgroup-1.0.xsd Specification of the nsgroup object (deprecated)
nsgroup-1.1.xsd Specification of the nsgroup object
poll-1.0.xsd Specification for displaying poll data
registrar-1.0.xsd Specification of the registar:info command
2.2.3. Conceptual differences
In the following table, we will list the conceptual differences between the “standard” EPP and
EURid’s implementation. In most cases, each of these differences will require some extension to the
standard.
EPP EURid Contacts
A contact is defined without a type. It acquires its type from its usage. The same contact can be used in different roles.
A contact has a type BY DEFINITION and can only be used in that role. If the same person has two roles (e.g. a billing contact and a technical contact) then it has to be defined twice.
A contact is generic and control can be passed on to another registrar.
A contact object belongs to a registrar and cannot be transferred to another registrar.
Name servers
There are two possible ways of working: 1. Name servers are objects in their own
right. If they need glue records (IP addresses), they must be created before they can be linked to a domain;
2. Name servers are just ‘attributes’ of domain name registration. This is the option chosen by EURid.
A name server is not an independent object; it is an attribute of the domain and comes into existence when it is linked to a domain. When it belongs to the same domain as the one it is linked to, it must be provided with an IP address (a "glue record").
Name server groups
Name server group is an object type unknown to EPP.
EURid defines objects called name server groups, which are a set of name servers.
Keygroups
Keygroup is an object type unknown to EPP. EURid defines objects called keygroups, which are a grouping of DNSSEC keys.
- 13 -
2.2.4. Data differences
The following tables will give an idea of the data differences that exist between the EPP draft and
the EURid implementation. More detailed information can be found in the description of each
command.
Domain object Field EURid length EPP length Remarks
domain 2-63 1-255 No change in schema but the back-end application returns an error when the name is longer than 63 characters.
ns (hostname) 4-100 1-255 No change in the format but the software returns an error when shorter than 4 and longer than 100 characters.
ns (hostAddr) 15 3-45 The backend will only accept valid IP addresses for the glue records.
nsgroup 1-50 NA
Contact object Field EURid length EPP length Remarks
name 50 1-255 ATTENTION: The “name” field is limited to 50 characters.
language 2 NA Standard language codes: "bg"|"cs"|"da"|"de"|"el"|"en"|"es"|"et"|"fi"|"fr"|"ga"|"hu"|"it"|"lt"|"lv"|"mt"|"nl"|"pl"|"pt"|"ro"|"sk"|"sl"|"sv"
org 100 0-255 ATTENTION: The “org” field is limited to 100 characters.
street 1-255 1-255
pc 1-16 1-16
city 1-255 1-255
sp 1-255 1-255
country 2 2
phone 1-17 0-17
fax 0-17 0-17
email 255 Min 1
vat 20 NA Defined as an extension
- 14 -
2.2.5. Added commands
The following table shows commands that have been added in the EURid system:
EURid Purpose <create> nsgroup Create a name server group. <update> nsgroup Update a name server group <delete> nsgroup Delete a name server group. <check> nsgroup Check a name server group. <info> nsgroup Get info on a name server group. <info> registrar Obtain registrar account information. <create> keygroup Create a keygroup. <update> keygroup Update a keygroup. <delete> keygroup Delete a keygroup. <check> keygroup Check a keygroup. <info> keygroup Get information on a keygroup.
2.2.6. Unimplemented EPP commands
EPP commands that are not implemented in the EURid system:
EPP-command(s) Remarks transfer approve NOT IMPLEMENTED.
The use of an authorisation code for the transfer of domain names renders the approval by domain
name holders unnecessary. transfer reject NOT IMPLEMENTED. See previous item. transfer query NOT IMPLEMENTED. See previous item.
- 15 -
2.3. Transport and security
EPP is intended for use in diverse operating environments where transport and security
requirements vary greatly. However, EURid provides EPP only on a Secure Socket Layer (SSL)
mechanism over standard TCP/IP sockets.
EPP security considerations are resolved by the transport layer and are beyond the scope of this
document.
EURid only uses EPP in synchronous mode: a response to a command must be received by the client
before sending another command (the EPP standard, however, allows synchronous as well as
asynchronous mode).
The EPP protocol can be layered over multiple transport protocols. EURid will only provide a
connection-oriented EPP service.
We only use EPP in a connection-oriented mode. A connection-less mode can be simulated by
sending a login/command/logout combination in one set; but this is not the normal way to proceed.
There is no actual timeout on the connection open time by clients. An EPP session requires the
connection between two peers as described in the standard.
2.4. Number of parallel connections
The number of simultaneously open connections per registrar account is six (6). Attempting to open
a seventh connection will close the oldest connection (i.e. the first connection to be established).
2.5. Versions
New versions of the EURid implementation, offering new functionality, can co-exist for a (defined)
period of time. Version management will be done via the <extURI> element of the <svcExtension>
element.
The most recent version of the EURid EPP implementation can be found in the EPP response after:
Opening a connection to the EPP server; or,
Sending a <hello> command.
- 16 -
2.6. EURid-specific objURI’s
These are the EURid-specific objURI’s to use in the login command.
URI of <objURI> Namespace prefix
http://www.eurid.eu/xml/epp/nsgroup-1.0 nsgroup
http://www.eurid.eu/xml/epp/nsgroup-1.1 nsgroup
http://www.eurid.eu/xml/epp/registrar-1.0 registrar
http://www.eurid.eu/xml/epp/keygroup-1.1 keygroup
Notice that the nsgroup-1.0 objURI can be still be used but is considered deprecated.
2.7. EURid-specific extURI’s
These are the EURid-specific extURI’s to use in the login command.
URI of <extURI> Namespace prefix
http://www.eurid.eu/xml/epp/contact-ext-1.0 contact-ext
http://www.eurid.eu/xml/epp/domain-ext-1.0 domain-ext
http://www.eurid.eu/xml/epp/dynUpdate-1.0 dynupdate
http://www.eurid.eu/xml/epp/authInfo-1.0 authinfo
http://www.eurid.eu/xml/epp/poll-1.0 poll
http://www.eurid.eu/xml/epp/idn-1.0 idn
http://www.eurid.eu/xml/epp/dss-1.0 dss1
1 Notice that the DSS-1.0 extURI can only mentioned at login by registrars that are subscribed to the DSS
service.
- 18 -
3. Structure of EPP Commands and responses
3.1. Introduction
The main standard reference document that specifies the client-server EPP protocol is the RFC5730. It fixes the format of the commands and responses as well as their possible extensions.
3.2. XML
Recall that XML is case sensitive. Unless otherwise stated, XML specifications and examples provided
with this document must be interpreted in the character case presented.
All EPP commands and responses are enclosed within an <epp> … </epp> XML block.
3.2.1. XML declaration
Every client request must start with a <?xml?> declaration using a recognized character set (UTF-8,
ASCII-7 or ISO-8859-1), with an XML version of 1.0.
<?xml version='1.0' encoding='UTF-8'?> <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> ... </epp>
Notice that the recommended character set for client-generated commands is UTF-8. First, it
provides the cleanest support for IDNs; second, it is the character set used in the server responses.
In particular, any client command mentioning an IDN causes the EPP server to return the domain
name both in ACE and Unicode representations. In such situation, the client software should be able
to read UTF-8 encoded server responses.
3.3. Byte count heading
Any client message sent to the EPP server must consist of:
A 4 bytes header followed by
The EPP command as an XML instance.
The header is a 32 bit integer value equal to the total message size, including the 4 bytes header
itself. The message size is expressed in bytes. The byte count must be represented in Network
order/big endian format.
For instance, the following EPP logout command:
- 19 -
<?xml version='1.0' encoding='UTF-8'?> <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> <command> <logout/> <clTRID>logout-example01</clTRID> </command> </epp>
Becomes the following message (shown here in a hexadecimal dump):
Figure 1 - Logout message with its byte counter heading (highlighted).
Assuming that newlines are encoded with a LF (0A hex) character and that indentation was done
with space pairs (20 20 hex), then the XML part is 167 bytes long. Adding the 4 bytes from the
header, the total message length is 173 bytes or AB in hexadecimal notation. Hence the AB value in
the fourth byte (i.e. last byte in the highlighted section).
The server will parse incoming XML messages on the socket by reading the first 4 bytes, and then by
reading a block of the size indicated by the heading, minus 4. This message is processed and the
response is sent back on the socket (also preceded by a 4-byte number in Network order) before the
next message can be processed.
Please note that when working with IDN domain names or IDN name servers, the
number of characters may not equal the number of bytes.
- 20 -
3.4. XML validation
The EPP server uses a validating XML parser that controls the conformance of the incoming messages to the XML schema. A client who wants to design an EPP client implementation should use from the EPP XML schema (.xsd files) used to validate all XML messages sent to the server for conformance with the EURid EPP implementation. These files can be found in the Library – Technical – XML section of the Registrar Extranet on http://registry.int.eurid.eu/library/technical.
3.4.1. XML syntax error
When the server receives a message that does not conform to the published XML schemas, then it
replies with a syntax error.
For example, assume that an authenticated EPP client sends a <contact:delete> command with a
<contact:id> that is –incorrectly- empty:
<?xml version="1.0" encoding="UTF-8"?> <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> <command> <delete> <contact:delete xmlns:contact="urn:ietf:params:xml:ns:contact-1.0"> <contact:id></contact:id> </contact:delete> </delete> </command> </epp>
The server replies with a response like:
<?xml version="1.0" encoding="UTF-8"?> <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> <response> <result code="2001"> <msg>Command syntax error</msg> <extValue> <value> <undef/> </value> <reason>line:6 column:9: string length (0) is less than minLength facet (3) for clIDType in namespace urn:ietf:params:xml:ns:eppcom-1.0</reason> </extValue> </result> <trID> <clTRID>invalid1</clTRID> <svTRID>eurid-0</svTRID> </trID> </response> </epp>
- 21 -
Every validation error will follow the above pattern:
A result code equal to 2001;
The <msg> tag has the value “Command syntax error”;
The <reason> tag contains a detailed error message with the position of the detected
error(s) and the XML schema that was infringed (in the above example ‘eppcom’).
All client XML EPP messages sent to the EURid EPP server should have been validated against the
latest XML EPP schema provided by EURid prior to their use.
- 22 -
3.5. Command format
3.5.1. Client EPP command
A generic EPP client command is formed as below (we will show client documents with a light blue
background), without the preceding 4 bytes.
<?xml version='1.0' encoding='UTF-8'?> <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> <command> <create> <contact:create xmlns:contact='urn:ietf:params:xml:ns:contact-1.0'> <contact:id>client_id002</contact:id> … </contact:create> </create> <extension> <contact-ext:create xmlns:contact-ext='http://www.eurid.eu/xml/epp/contact-ext-1.0'> <contact-ext:type>registrant</contact-ext:type> … </contact-ext:create> </extension> <clTRID>contact-create02</clTRID> </command> </epp> </epp>
Elements Description
<command> Contains the whole EPP command block.
<create> To be replaced by one of the allowed commands, i.e. defined in the schema (e.g. <login>, <check>, <info>, <update>,<delete> ...). It defines the requested action to be performed. Commands are described in the following chapters.
<extension> Defines a set of DNSSEC or EURid-specific extensions for the command. Some of them are mandatory.
<clTRID> (Client transaction identifier) uniquely identifies the command to the client. This ID is chosen by the client and needs to be unique only within the client's scope. See the official EPP specification for constraints about this ID. The EPP server does not process or use this ID, it is only returned as-is to the client in the response.
- 23 -
3.5.2. Server EPP response
A generic EPP server response is formed as follows (we will show all server response documents on a
light red background), without the preceding 4 bytes:
<?xml version="1.0" encoding="UTF-8"?> <epp xmlns="urn:ietf:params:xml:ns:epp-1.0" xmlns:contact="urn:ietf:params:xml:ns:contact-1.0"> <response> <result code="1000"> <msg>Command completed successfully</msg> </result> <resData> <contact:creData> <contact:id>c16212471</contact:id> <contact:crDate>2012-10-03T12:14:04.059Z</contact:crDate> </contact:creData> </resData> <trID> <clTRID>contact-create02</clTRID> <svTRID>eurid-94044093</svTRID> </trID> </response> </epp>
Elements Description
<response> Contains the whole server response block.
<result> Contains the result code, message and service-specific values for the command.
<msg> Contains the EPP message text for the corresponding reply code. There is a one to one mapping between error code and error messages.
<value> Contains a context-specific value for more informative reference, such as XML parsing error column, line and message, specific transaction-processing error. See each specific command for more information on the content of the value field.
<resData> Contains object-specific data related to the object and command in process, such as a newly created ID, information data etc.
<extension> Contains the EURid-specific response extension.
<trID> Is composed of 2 blocks which, together, define a unique transaction identifier.
- 24 -
3.5.2.1. Successful response codes
Response code Response text
1000 “Command completed successfully.” This is the default response code for a successfully completed command.
1001 “Command completed successfully; action pending.” This response code is used when responding to a command that requires offline activity before the requested action can be completed. Commands that requires offline activity are:
The transfer command;
The delete command.
1300 “Command completed successfully; no messages.” This response code is used when responding to a <poll> request command and when the server message queue is empty.
1301 “Command completed successfully; ack to dequeue.” This response code is used 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 is returned when responding to a successful <logout> command.
As a convention, the response code 1000 will not be mentioned further in the document
unless the successful response code can be different than 1000.
- 26 -
4. Session handling
4.1. Introduction
4.1.1. Transport and security
EPP is intended for use in diverse operating environments where transport and security
requirements vary greatly. However, EURid is providing EPP only on a Secure Socket Layer (SSL)
mechanism over standard TCP/IP sockets.
The SSL Certificates can be found in the Registrar Extranet at: https://secure.registry.eu/services/epp
EURid uses EPP only in synchronous mode: a response to a command must be received by the client
before sending another command (the EPP standard however, allows synchronous as well as
asynchronous mode).
The EPP protocol can be layered over multiple transport protocols. EURid provides a connection-
oriented EPP service.
However, a connection-less mode can be simulated by sending a login/command/logout
combination in one set; but this is not the normal way to proceed. There is no actual timeout on the
connection open time by clients. An EPP session requires the connection between two peers as
described in the standard.
4.1.2. Hostnames and port numbers
Up-to-date addresses of the EPP servers are documented in the Registrar Extranet. For convenience,
we list here the pages for the different environments.
Environment Link
Production https://secure.registry.eu/services/epp
Try-out https://secure.registry.eu/services/tryout-system
Staging https://secure.registry.eu/services/staging-system
- 27 -
4.2. Hello / Greeting
4.2.1. Purpose
The purpose is to obtain a <greeting> from the EPP server that will handle your requests and that
contains an enumeration of EPP services that the server provides. It is used to keep an open
connection with the EPP servers.
In response, the EPP server answers with a <greeting>. The server will also send a <greeting> when a
connection or session is established.
A client can request a <greeting> from the EPP server by sending a <hello> command at any time.
The <hello> tag must be an empty XML element with no child element. An EPP client can send a
<hello> command at any time.
4.2.2. Request syntax
The content of a <hello> element is specified in the RFC5730 section 2.3.
Similarly, the syntax of a <greeting> is specified in the same RFC5730 under section 2.4. The
syntactic validation rules for the <hello> and <greeting> commands are to be found in the XML
Schema file ‘epp-1.0.xsd’.
The <greeting> tag contains the following elements:
Elements Occurrence Min-max
Description
<hello> 1
- 28 -
4.2.3. Reply syntax
Elements Description
<svID> The name of the server (eurid.eu).
<svDate> The current server date and time in UTC. Please be aware that dates in EPP are returned in UTC, while scheduled operations will be performed in Belgian time (CET/CEST).
<svcMenu> The services supported by the server.
<version> The EPP version currently supported.
<lang> The text response language currently supported as defined in RFC3066. Only “en” (English) is available for the time being.
<objURI> The list of namespace URIs representing the objects that the server is capable of managing: contacts, domains, … etc.
<svcExtension><extURI> The list of namespace URIs representing extended objects that the server is capable of managing.
<dcp> Information related to privacy policies.
Please note the <extURI> tag in the svc extension in the greeting above:
<extURI>http://www.eurid.eu/xml/epp/dss-1.0</extURI>. This tag is present even if a registrar does
not use the DNSSEC Signing Service. However, this extURI element can only be used in your
login command once you have subscribed to the DNSSEC Signing Service.
4.2.4. Examples
Description Command file Response file
Hello message/greeting response hello-cmd greeting
- 29 -
4.3. Login
4.3.1. Purpose
The purpose is to authenticate the user/client with the EPP server. The login command must be sent
before any other command can be executed (except for the <hello> command).
This command is used to establish the registrar’s credentials. The userid and EPP password are used
to authenticate the party that wants to set up the session.
An EPP connection is kept open by the server between a <login> and a <logout> command from the
client.
4.3.2. Request syntax
The content of a <login> command is explained in the RFC5730 under section 2.9.1.1. The syntactic
validation rules are to be found in the XML Schema file ‘epp-1.0.xsd’.
The login command contains the following elements (only the begin tags are shown and each block
should be ended by its corresponding end tag “</tag>”):
Elements Occurrence
min-max Size + remarks
<login> 1
<clID> 1 token: 3-16
<pw> 1 token: 6-16
<newPW> 0-1 ignored by EPP
<options> 1
<version> 1 reg exp: [1-9]+\.[0-9]+
<lang> 1 language (XML built-in)
<svcs> 1
<objURI> 1-* any URI
<svcExtension> 0-1 any URI
<extURI> 0-* any URI
<clTRID> 0-1 token: 3-64
Elements Description
<cIID> The registrar ID of the connecting client.
<pw> The EPP password of the connecting client (registrar). This is the password that you have to provide when you activate your account at the start of your contract.
<version> The EPP version the client supports (1.0). This will be used for versioning (on EPP standard level) in the future.
<lang> The preferred language of the client for this connection (actually ignored by EURid). Both <version> and <lang> must match one of the server proposition(s).
<svcs> A list of <objURI> and <extURI> the client wants to use with the EPP server
- 30 -
during this connection. One <extURI> has a special meaning (and is mandatory), it is used to indicate the desired “build” number of the server. This number corresponds to a certain release of the software that adheres to a certain version of the EPP draft documents and a certain set of Eurid specific functionality.
Each transaction can be completed with a user-provided transaction ID that can be used to identify a
command/response pair.
4.3.3. Which <objURI> or <extURI> to use?
Ground rule: The <objURI> and <extURI> occurring in a <login> must be a subset of the <objURI>
and <extURI> that are listed in a <greeting> command that is returned by the EPP
server. In other words: a <login> may not contain a <objURI> or a <extURI> that was
not part of a <greeting> command.
The easiest approach for selecting the URI’s for your login command is to follow these steps:
1. Copy all the <objURI> and <extURI> from the <greeting> response.
2. Remove the object(s) or extension(s) that you did not subscribe to.
Example: The DNSSEC Signing Service (DSS) can be used by registrars that have
explicitly enrolled to this service. Registrars that are not subscribed to DSS
should not use the DSS <extURI> in their login.
4.3.4. What happens if one forgets a required extURI?
When a login command is submitted with one or more missing extURI’s, then any future command
that requires one of the missing extensions will fail with a result code = 2002 and a <msg> tag with
“Command use error” text and a <reason> with the message “Extension does not match command.”.
As an example, the command <domain:transfer> requires the domain-ext extension. If that
extension wasn’t mentioned in a <extURI> tag at login, then any <domain:transfer> will fail with a
result code 2002.
4.3.5. Reply syntax
Elements Description
<result code>
<msg>
<clTRID> The transaction ID for tracking the command that was provided by the EPP client in the incoming command.
<svTRID> The transaction ID that is provided by the server.
- 31 -
4.3.6. Return codes
Error cases
Result code
<msg> <reason> Likely cause
2001 Command syntax error Line:xx column:yy: string value ‘zz.z’ is not a valid enumeration value for versionType in namespace urn:ietf:params:xml:ns:epp-1.0.
Incorrect value in <version> tag (MUST be 1.0).
2103 Unimplemented extension
extURI cannot be empty. An <extURI> tag was empty
2103 Unimplemented extension
Unknown extURI: ‘http://www.eurid.eu/xml/epp/foobar-1.0’.
Attempting to use an unknown <extURI>
2200 Authentication error N.A. Password is not correct
2201 Authorization error DNSSEC Signing Service is not enabled for this account.
Attempting to use DSS but not subscribed to this service
2307 Unimplemented object service
Unknown objURI 'http://www.eurid.eu/xml/epp/foobar-1.0'.
The objURI foobar-1.0' is not known
2307 Unimplemented object service
objURI cannot be empty. Attempting to use an empty objURI
4.3.7. Examples
Description Command file Response file
Logging in EPP without DNSSEC login01-cmd.xml login01-resp.xml
Logging in EPP with DNSSEC &
nsgroup 1.1
login02-cmd.xml login02-resp.xml
Logging in EPP with nsgroup 1.1
and DSS
login03-cmd.xml login03-resp.xml
- 32 -
4.4. Logout
4.4.1. Purpose
The EPP <logout> command is used to close a session with the EPP server. The transport connection
(SSL socket) is closed by the server after the emission of the <logout> response by the server.
The <logout> command is represented as a tag with no child elements.
4.4.2. Request syntax
The <logout> tag contains the following elements:
Elements Occurrence
min-max Size + remarks
<logout/> 1
<clTRID> The transaction ID for tracking the command that was
provided by the EPP client in the incoming command.
4.4.3. Reply syntax
Elements Description
<result code>
<msg>
<clTRID> The transaction ID for tracking the command that was provided by the EPP client in the incoming command.
<svTRID> The transaction ID that is provided by the server.
4.4.4. Return codes
Error cases
Result code
<msg> <reason> Likely cause
2002 Command use error
N.A. Trying to logout while not logged in.
- 33 -
4.4.5. Examples
Description Command file Response filex
Example of logout command logout-cmd.xml logout-resp.xml
- 35 -
5. Contacts
5.1. Introduction
This chapter is based on RFC5733 which describes the individual or organisational social information identifiers, better known as “contacts”. It defines the EPP command syntax and semantics of these contacts. RFC5733 supersedes RFC4933.
5.1.1. Contact ID’s
Every EPP contact object is identified by a server-unique identifier. Contact identifiers start with a
small letter “c” followed by a unique numeric ID. The EPP <contact:create> command allows the
client to send a requested ID for the new contact, but this field is ignored (as allowed by EPP) by the
server and a newly-created ID is returned instead in the server response.
5.1.2. Contact types
The types of contacts that can be linked to a domain name are described below:
Contact type Description
registrant A private person or an organisation that is the holder of the domain name.
billing A contact from the registrar to whom invoices related to the domain name will be sent.
Only one active billing contact per registrar.
technical A contact person working for the registrar that is responsible for the technical support related to the domain name.
Up to of 10 active technical contacts per registrar.
onsite A contact related to the registrant or a third party, e.g. an intermediate website builder, who can be contacted in case of a technical problem with the domain name.
A registrar can have from zero to an unlimited number of onsite contacts.
reseller A person or organisation to whom the registrar delegated part of the (commercial) relationship with the registrant.
A registrar can have from zero to an unlimited number of resellers.
The rules governing the links between a domain name and the contacts are summarised here:
Contact type Rules
registrant Exactly one registrant contact per domain name.
billing Exactly one billing contact per domain name.
technical From zero to nine technical contacts per domain name.
A domain name must be linked to at least one active support
- 36 -
contact (technical or onsite).
A domain name can be connected to another technical contact at will.
onsite From zero to five onsite contacts per domain name.
A domain name must be linked to at least one active support contact (technical or onsite).
A domain name can be connected to another onsite contact at any time.
reseller From zero to one reseller contact per domain name.
A domain name can be connected to another reseller at any time.
Standard EPP does not enforce a specific role for each contact: in principle, the same contact object
could be used in different roles. However, EURid requires that you define a role for a contact upon
its creation in a <contact-ext> extension tag. A contact can only be used in the role it was created
for. Each link between a domain name and a contact should follow that rule.
For example, you cannot link a contact of type "tech" to a domain as a "billing", you MUST use it as a
"tech". If you want to use the same person for different roles, you will need to create a new contact
for each of them.
The reseller contact type was introduced with version 9.4. Except for the rule that stipulates that at
most one reseller can be bound to a domain name, a reseller contact can appear in every XML
element where an onsite contact is allowed.
5.1.3. Contact coordinates
Every contact also has associated postal address information. EURid stores postal information in a
less restrictive way to accommodate for the many different formats being used worldwide.
It is the responsibility of the registrar to provide an address in a readable format.
For a list of all allowed characters in the <name>, <org> and <addr> fields, please consult the document “Characters allowed in Name, Organization and Address fields” published in the Technical part in the “Library” section of the Registrar Extranet on www.registry.eu .
- 37 -
5.2. Create contact
5.2.1. Purpose
The <contact:create> command allows to create a contact object of a given type (billing, technical), a
registrant or onsite.
5.2.2. Request syntax
The <contact:create> tag contains the following elements:
Elements Occurrence
min-max Size + remarks
<contact:create> 1
<contact:id> 1 token: 3-16
ignored by the EPP server
<contact:postalInfo> 1 Attribute type can only be the value ”loc”.
Only 1 block is accepted (although the schema allows for 2).
<contact:name> 1 normalizedString 1-50
<contact:org> 0-1 normalizedString 0-100; is required for a contact of type “tech” and “billing”.
<contact:addr> 1
<contact:street> 1-3 normalizedString 0-255
<contact:city> 1 normalizedString 1-255
<contact:sp> 0-1 normalizedString 0-255
<contact:pc> 0-1 token: 0-16; is required by EURid.
<contact:cc> 1 token: 2 (must be uppercase); see list of possible values in Addendum II.
<contact:voice> 1 token: (\+[0-9]{1,3}\.[0-9]{1,14})
max length: 17
optional attrib: x: token
This field is required by EURid.
<contact:fax> 0-1 token: (\+[0-9]{1,3}\.[0-9]{1,14})?
max length: 17
This field is required for “tech” and “billing” contacts.
<contact:email> 1 token
<contact:authInfo> 1 optional attrib: roid= token
(\w|_){1,80}-\w{1,8}
<contact:pw> 1 As it is a required element in the schema, it must be provided; however, you do not have to specify a value between the tags. If present, the value is ignored by the EPP server.
<contact:disclose> 0 Is not used by EURid.
<extension> 0-1 Contains EURID specific elements; must always be
- 38 -
present as the type is required.
<ext> 1 Not used by EURid.
<contact-ext:create> 1
<contact-ext:type> 1 "billing"|"tech"|"registrant"|"onsite"|"reseller"
<contact-ext:vat> 0-1 token: 1-20
<contact-ext:lang> 0-1 See addendum II “Accepted language codes for registrant contacts.
Although optional in the schema, the back-end will return an error if this element is omitted.
<clTRID> 0-1 token: 3-64
Elements Description
<id> According to the EPP standard, this field contains the (proposed) ID for the contact. It is ignored by EURid since we always create a unique contact ID as “c” + a unique number.
<postalInfoType> The address information of the contact. The schema allows it to occur twice (e.g. with a local address or an international address). EURid only accepts the type “loc” with UTF-8 character set (containing non-ASCII characters). If “int” is specified as type, this will be rejected as a policy error. Only one postalInfoType block is accepted.
<name> The complete name of the contact to create. The first and the last name should be put in that field. It is a good practice to start with the last name, followed by the first name because in the web interface contacts are ordered by name. This field is limited to 50 characters. Trying to register a contact using more than 50 characters in the “name” field will result in an error message.
<org> The company name of the contact. If the contact:type is “registrant”, “onsite” or "reseller", no “contact:org” is required. However if the contact:type is “tech” or “billing” a “contact:org” tag is mandatory. This field is limited to 100 characters. Trying to register a contact using more than 100 characters in the “org” field will result in an error message. In the web interface there are two fields for the company name, in case it would be needed. This is not used by EPP.
<street> You can provide up to three instances of this element. It contains the postal street information of the contact. It should contain information in such a way that it could look like a correct address when printed on a letter as: COMPANY NAME (CONTACT) NAME STREET(1) STREET(2) STREET(3) PC CITY, SP
<city> The city of the contact.
<sp> The state or province of the contact.
<pc> The postal code of the contact. This field can be up to 16 characters.
<cc> The two-letters country code of the contact to create, as defined in [ISO3166]. For registrants, only country codes from countries belonging to
- 39 -
the EU are accepted as required by the regulation 874/2004. Accepted ISO codes can be found in Addendum 1.
<voice> The phone number of the contact that is being created. It should be a string that begins with a plus sign ("+"), followed by a country code, followed by a dot ("."), followed by a sequence of digits representing the telephone number. An optional "x" attribute is provided to note the telephone extension (but this attribute is ignored by EURid).
<fax> The facsimile number of the contact. The syntax is the same as for telephone but without the extension attribute.
<email> Email address syntax is defined in [RFC2822].
<authInfo> Is ignored by EURid.
<disclose> There is an additional (optional) element in the schema that contains postal information that can be disclosed. This is not used by EURid.
EURid extensions:
Elements Description
<contact-ext:type> The type of contact to create. Can be one of: “registrant”, “billing”, “onsite”, "reseller", “tech”.
<contact-ext:vat> The VAT of the contact. This tag is optional. The recommended way to signal no VAT number is needed is by not providing the XML tags. However, due to a small oversight in the code, an empty value is accepted by the system and treated equivalently as if the tag would not be there at all. As this is considered to be more a cosmetic issue, and to not introduce any unnecessary code breaks, EURid has opted not to correct this.
<contact-ext:lang> The preferred language of the holder of the domain name. This must be the language of the registration agreement with the registrar and is also the language for ADR proceedings (except for ADRs against the registry). Although it is not a required field in the schema, as a EURid policy, it must be provided and only a language from the list (see addendum II) will be accepted.
5.2.3. Reply syntax
Elements Description
<response>
<result code=”XXXX”> XXXX stands for the return code
<msg>
<resData>
<contact:creData>
<contact:id> The unique ID assigned to the created contact by the EPP server.
<contact:crDate> The creation date and time of the contact. This date that is returned here, is formatted in UTC while scheduled operations are performed in Belgian time (CET/CEST).
<trID>
<clTRID> The transaction ID for tracking the command that was provided by the EPP client in the incoming command.
<svTRID> The transaction ID that is provided by the server.
- 40 -
5.2.4. Return codes
Error cases
Result code
<msg> <reason> Likely cause
2001 Command syntax error
line:xx column:yy Value missing for city
2003 Required parameter missing
Value for street missing. Value missing for street
2003 Required parameter missing
Value for postal code missing.
Value missing for postal code
2003 Required parameter missing
Value for organisation missing.
Trying to create a tech contact without organisation name
2003 Required parameter missing
Value for fax number missing.
Trying to create a tech contact without fax number
2003 Required parameter missing
Value for language code missing.
Trying to create a contact with no language code.
2005 Parameter value syntax error
Invalid value for name (value too long).
Contact name exceeds the 50 characters limit
2005 Parameter value syntax error
Invalid value for name (invalid characters).
Invalid characters used in the contact name
2005 Parameter value syntax error
Invalid value for street (invalid characters).
Invalid characters used in the street name
2005 Parameter value syntax error
Invalid value for city (invalid characters).
Invalid characters used in the city field
2005 Parameter value syntax error
Invalid value for state/province (invalid characters).
Invalid characters used in the state/province field
2005 Parameter value syntax error
Invalid country code. Country code does not exist, it is
not in uppercase, it contains invalid
characters, or if type =registrant, it
is not in the EU
2005 Parameter value syntax error
Invalid email. Not a correct email address
2005 Parameter value syntax error
Invalid value for organisation (value too long).
Org name exceeds the 100 characters limit
2005 Parameter value syntax error
Invalid value for organisation (invalid characters).
Invalid characters used in the organisation name
2005 Parameter value syntax error
Invalid value for VAT (invalid characters).
Invalid characters used in the VAT field
2303 Object does not exist
Contact ‘cXXXX’ is not an active contact.
2306 Parameter value policy error
Invalid contact type. Trying to create an unknown contact type
2308 Data management policy violation
Already at maximum number of billing contacts.
Trying to create a second billing contact
2308 Data management Already at maximum Trying to create an 11th tech
- 41 -
policy violation number of technical contacts.
contact
5.2.5. Examples
Description Command file Response file
Creation of a tech contact contact-create01-cmd.xml contact-create01-resp.xml
Creation of a registrant (as
individual)
contact-create02-cmd.xml contact-create02-resp.xml
Creation of a registrant (as an
organisation)
contact-create03-cmd.xml contact-create03-resp.xml
Creation of a contact with special
characters
contact-create04-cmd.xml contact-create04-resp.xml
Creation of an onsite contact contact-create05-cmd.xml contact-create05-resp.xml
Creation of a reseller contact contact-create06-cmd.xml contact-create06-resp.xml
Creation of an onsite contact in
ASCII
contact-create07-cmd.xml contact-create07-resp.xml
Creation of a reseller contact in
ASCII
contact-create08-cmd.xml contact-create08-resp.xml
- 42 -
5.3. Delete contact
5.3.1. Purpose
The EPP <contact:delete> allows a client to delete a contact object.
The contact identifier is the server-unique identifier of the contact object to delete.
A contact object should not be deleted if it is associated with other known objects; for example,
when a contact is still linked to a domain name.
5.3.2. Request syntax
The <contact:delete> tag contains the following elements:
Elements Occurrence
min-max Size + remarks
<contact:delete> 1
<contact:id> 1 token: 3-16
<clTRID> 0-1 token: 3-64
Elements Description
<id> The contact identifier of the contact you want to delete.
<clTRID> The transaction ID that is provided by you for your own reference.
5.3.3. Reply syntax
Elements Description
<result code=”XXXX”> XXXX stands for the return code
<msg>
<trID>
<clTRID> The transaction ID that is provided by you for your own reference.
<svTRID> The transaction ID that is provided by the server.
- 43 -
5.3.4. Return codes
Error cases
Result
code
<msg> <reason> Likely cause
2001 Command syntax
error
line:6 column:9: ... Contact delete command
without a contact ID to delete.
Non-compliant to the XML
schema
2303 Object does not
exist
Object does not exist The contact does not exist.
2305 Object association
prohibits operation
Contact ‘cxxxxx’ is still linked
to 1 domain(s).
The contact is still linked to a
domain(s).
5.3.5. Examples
Description Command file Response file
Contact delete example contact-delete01-cmd.xml contact-delete01-resp.xml
- 44 -
5.4. Update contact
5.4.1. Purpose
The EPP <contact:update> command allows to modify the attributes of a contact object.
The EPP protocol provides for a granular update, meaning that you don’t have to re-specify all
unchanged fields (with the exception for a change in address where the whole <addr> needs to be
specified).
The command must contain the server-unique identifier of the contact object to be updated. In
addition, the command must also contain this element:
<contact:chg> The tag that contains object attribute values to be changed.
The EPP protocol offers the possibility of adding and removing a status from a contact.
This is not used by EURid and as it is an optional element in the schema.
If it is provided, it is not taken into account. Updating the status is not supported.
For a list of all allowed characters in the <name>, <org> and <addr> fields, please consult the
document “Characters allowed in Name, Organisation and Address fields” that has been published in
the “Library” (“Technical” – “Registration Guidelines”) section of the Registrar Extranet on
www.registry.eu.
5.4.2. Request syntax
The <contact:update> tag contains the following elements:
Elements Occurrence
min-max Size + remarks
<contact:update> 1
<contact:id> 1 Token: 3-16
<contact:add> 0 Not used by EURid
<contact:status> 0 Not used by EURid
<contact:rem> 0 Not used by EURid
<contact:status> 0 Not used by EURid
<contact:chg> 0-1
<contact:postalInfo> 0-2 Required attribute type =”loc”.
Although the schema is not modified by EURid, the
application will only accept the type ”loc”. Only 1
block is accepted (although the schema allows for
2).
<contact:name> 1 normalizedString 1-50
- 45 -
<contact:org> 0-1 normalizedString 0-100; is required for a contact of
type “tech” and “billing”
<contact:addr> 1
<contact:street> 1-3 normalizedString 0-255
<contact:city> 1 normalizedString 1-255
<contact:sp> 0-1 normalizedString 0-255
<contact:pc> 0-1 token: 0-16; is required by EURid.
<contact:cc> 1 token: 2 (must be uppercase); see list of possible
values in Addendum II.
<contactvoice> 1 token: (\+[0-9]{1,3}\.[0-9]{1,14})?
max length: 17
optional attrib: x= (token)
This field is required by EURid.
<contact:fax> 0-1 token: (\+[0-9]{1,3}\.[0-9]{1,14})?
max length: 17
This field is required for “tech” and “billing”
contacts.
<contact:email> 1 token
<extension> 0-1
<contact-ext:update> 1
<contact-ext:chg>
<contact-ext:vat> 0-1 Token: 1-20
<contact-ext:lang> 0-1 See addendum II “Accepted language codes for
registrant contacts.
Although optional in the schema, the server will
return an error if this element is omitted.
<clTRID> 0-1 Token: 3-64
Elements Description
<id> According to the EPP standard, this field contains the (proposed) ID for the
contact. It is ignored by EURid since we always create a unique contact ID
as “C” + a unique number.
<chg> The element that indicates that (one of) the following elements needs to
be updated in the database. The various fields embedded in a
<contact:chg> block are the same as for contact creation.
Please refer to that command for more information.
All fields are optional as you only need to specify those that change.
Except when you want to change a part of the <addr> block, because then
you need to specify the complete block.
- 46 -
5.4.3. Reply syntax
Elements Description
<response>
<result code=”XXXX”> XXXX stands for the return code
<msg>
<trID>
<svTRID> A server generated transaction ID.
5.4.4. Return codes
Error cases
Result
code
<msg> <reason> Likely cause
2001 Command syntax
error
line:xx column:yy … The command doesn’t
conform to XML Schema
2003 Required
parameter missing
Value for organisation missing. Organisation field is missing
or it has no value for tech or
onsite contacts
2003 Required
parameter missing
Value for street missing. Street field is missing or it has
no value
2003 Required
parameter missing
Value for postal code missing. Postal code missing
2003 Required
parameter missing
Value for fax number missing. Fax missing on tech contact
2005 Parameter value
syntax error
Invalid value for name (value
too long).
Name field no longer than 50
characters
2005 Parameter value
syntax error
Invalid value for name (invalid
characters).
Name field contains invalid
characters
2005 Parameter value
syntax error
Invalid value for organisation
(value too long).
Org field longer than 100
characters
2005 Parameter value
syntax error
Invalid value for organisation
(invalid characters).
Org field contains invalid
characters
2005 Parameter value
syntax error
Invalid value for street (invalid
characters).
Street field contains invalid
characters
2005 Parameter value
syntax error
Invalid value for city (invalid
characters).
City field contains invalid
characters
2005 Parameter value
syntax error
Invalid value for state/province
(invalid characters).
State field contains invalid
characters
2005 Parameter value
syntax error
Invalid country code. Country code does not exist,
it is not in uppercase, it
contains invalid characters, or
if type =registrant, it is not in
the EU
2005 Parameter value Invalid email. Invalid email (at syntax level)
- 47 -
syntax error
2005 Parameter value
syntax error
Invalid value for VAT (invalid
characters).
VAT field contains invalid
characters
2308 Data management
policy violation
Adding/removing status is not
supported
Trying to use the
unsupported tag
<contact:add>
5.4.5. Examples
Description Command file Response file
Update of the address of a contact contact-update01-cmd.xml contact-update01-resp.xml
Update of the phone number of a
contact
contact-update02-cmd.xml contact-update02-resp.xml
- 48 -
5.5. Info contact
5.5.1. Purpose
The EPP <contact:info> command is used to retrieve information associated with a contact object.
This command must contain the server-unique identifier of the contact object to be queried.
When requesting information about a contact that is not in your portfolio, you need to
have a transfer authorisation code.
5.5.2. Request syntax
The <contact:info> tag contains the following elements:
Elements Occurrence
min-max Size + remarks
<contact:info> 1
<contact:id> 1 token: 3-16
<contact:authInfo> 0-1
<contact:pw> 0-1
<clTRID> 0-1 token: 3-64
Elements Description
<contact:id> The contact ID for which you want to obtain the information.
<contact:authInfo>
<contact:pw> Attribute “roid” is ignored
<ext> Not supported
<clTRID> The transaction ID provided by the registrar for his own reference.
- 49 -
5.5.3. Reply syntax
The reply from the server contains the following contact information:
Elements Description
<result code>
<msg>
<resdata>
<contact:id> The contact ID for which you want to obtain the information.
<contact:roid> The Repository Object Identifier assigned to the contact object when the
contact was created. This information can be discarded.
<contact:status> The status associated with the contact object. Currently only the “ok”
status is supported.
<contact:postalInfo> The address information of the contact.
<contact:name> The complete name of the contact.
<contact:org> The company name of the contact.
<contact:street> The street information of the contact.
<contact:city> The city of the contact.
<contact:sp> The state or province of the contact.
<contact:pc> The postal code of the contact.
<contact:cc> The two-letter country code of the contact.
<contact:voice> The telephone number of the contact.
<contact:fax> The fax number of the contact.
<contactemail> The email address of the contact
<contact:cIID> The identifier of the current “sponsoring client”, i.e. the EURid
identification.
<contact:crID> The identifier of the client and subsystem that created the object. For
EURid, it contains the same information as <CIID>, since an object belongs
to a registrar and cannot be transferred or used by another registrar.
<contact:crDate> The creation date and time of the contact.
This date is formatted in UTC while scheduled operations are performed in
Belgian time (CET/CEST).
<contact:upDate> The last date and time in UTC format when the contact was updated.
<extension>
<contact-ext:type>
<contact-ext:vat>
<contact-ext:lang>
<trID>
<clTRID> The transaction ID for tracking the command that was provided by the EPP
client in the incoming command.
<svTRID> A server generated transaction ID.
- 50 -
5.5.4. Return codes
Error cases
Result
code
<msg> <reason> Likely cause
2303 Object does not
exist
Contact object does not exist You try to request info
about a contact that
does not exist.
5.5.5. Examples
Description Command file Response file
Contact info of a tech contact contact-info01-cmd.xml contact-info01-resp.xml
Contact info of an individual
registrant
contact-info02-cmd.xml contact-info02-resp.xml
Contact info of an organisational
registrant
contact-info03-cmd.xml contact-info03-resp.xml
Contact info of an organisational
registrant which is not in your
portfolio
contact-info04-cmd.xml contact-info04-resp.xml
Contact info of a reseller contact-info05-cmd.xml contact-info05-resp.xml
- 52 -
6. Domains
6.1. Introduction
This chapter is based on RFC5731 which describes the EPP Domain Name Mapping. It defines the
EPP command syntax and semantics of domains.
6.1.1. Associating name servers to a domain name
The EPP protocol specifies two possibilities of working with name servers:
Name servers as first class objects;
Name servers as attributes to a domain name.
EURid has adopted the second possibility.
In technical terms it means that you will need to use the <hostAttr> tag and not the <hostObj>
element.
EURid does not have host objects as separate entities. A name server is specified on the domain
object command and is created, deleted or updated as needed. A host/name server cannot be
accessed directly as an EPP object.
6.1.2. Domain name extension
The EPP standard supposes that the domain name that is being registered contains the trailing TLD
extension (i.e. Top-level domain extension). This is because EPP can be used by registries that
manage more than one extension. For consistency reasons, we will accept domain names without
the “.eu” extension.
If, however, an extension is provided, it will be checked and only “.eu” extensions will be accepted.
6.1.3. Key Data Interface (secDNS 1.1)
As mandated by the RFC5910 - section 4 -, a server must support one of the two secDNS interfaces:
1. The "DS Data Interface”; or,
2. The "Key Data Interface".
In the first interface the client is responsible for the creation of the DS information and is required to
pass DS information when performing adds and removes. The server in turn is required to pass DS
information for <domain:info> responses. The second interface, is where the client and the server
exchange the key data information with the <secDNS:keyData> tag only.
- 53 -
EURid has chosen to support the Key Data Interface. The reason for selecting the Key Data Interface
was to give the registry the possibility to generate all the DS records for the master .eu DNS zone file
in an uniform way (i.e. with the same hash algorithm).
6.1.4. Valid term period values
The valid period values for domain creation are:
Unit Values Remark
y ‘1’ | ‘2’ | ‘3’ | ‘4’ | ‘5’ | ‘6’ | ‘7’ | ’8’ | ‘9’ | ‘10’ Integer value in the range [1,10]
m ‘12’ | ‘24’ | ‘36’ | ‘48’ | ‘60’ | ‘72’ | ‘84’ | ‘96’ Value is a multiple of 12 in the range [12,96]
The registration term of a domain name cannot exceed 10 years. Also it is not possible to request
the reduction of the registration term of a domain name.
Since it is not possible to indicate a number of months higher than 99 on EPP, the period unit cannot
be ‘m’ (months) for domain name registrations of 9 or 10 years.
- 54 -
6.2. Create domain
6.2.1. Purpose
The EPP command <domain:create>allows a client to register an available domain name.
6.2.2. Request syntax
The <domain:create> tag contains the following elements:
Elements Occurrence
min-max Size + remarks
<create> 1
<domain:create> 1
<domain:name> 1 token: 1-263
<domain:period> 0-1
The valid period values for domain creation are:
1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | if the
unit is years (y) (integer value in the range
[1,10])
12 | 24 | 36 | 48 | 60 | 72 | 84 | 96 if the
unit is in months (m)
Attribute: unit = ”y” | “m”
<domain:ns> 0-1
<domain:hostAttr> 1-9 EURid server policy limits up to 9
<domain:hostName> 1 token: 4-255
<domain:hostAddr> 0-* attribute “ip” value “v4”(default) or “v6”;
token: 3-45
<domain:registrant> 1 token: 3-16
ATTENTION: Required by EURid.
<domain:contact> 2-*
token: 3-16
required attrib: "billing" | "tech"
ATTENTION: The registry policy requires 1 “billing”
contact and at least 1 of “tech” contact.
<domain:authInfo> 1 optional attrib: roid= token
(\w|_){1,80}-\w{1,8}
<domain:pw> 0-1
Is not used by EURid. As it is a required element in
the schema, it must be provided; however, you do
not have to specify a value between the tags.
<extension> 0-1 Contains DNSSEC or EURid specific extensions
<domain-ext:create> 1
<domain-ext:contact> 0-* onsite or reseller contacts
<domain-ext:nsgroup> 0-9 normalizedString 1-50
<domain-ext:keygroup> 0-1 normalizedString 1-50
- 55 -
<secDNScreate> 1
<secDNS:keyData> 0-*
<secDNS:flags> 1 256 | 257 Value is 256 for ZSK, or 257 for KSK
<secDNS:protocol> 1 3
<secDNS:alg> 1 3 | 5 | 6 | 7| 8 | 10
<secDNS:pubKey> 1 A base 64 value. Any spaces in the public key will be
removed. Maximum is 1024 base64 characters
<dss:create> 1
<dss:dssEnabled> 1 value: "true" | "false"
<dss:master> 1 token: 3-45
value is an IP address
<dss:slave> 1-9 token: 3-45
value is an IP address
<dss:nsecVariant> 0-1 Value: “NSEC” - optional
Only NSEC is supported by EURid.
<dss:useTsig> 0-1 value: "true" | "false"
to be used with caution
<clTRID> 0-1 Token: 3-64
Elements Description
<domain:name> Is the domain name to create with, or without the trailing “.eu”.
<domain:period> The domain validity period. A domain name can be registered for
up to 10 years.
<domain:ns> Is a list of name servers.
<hostAddr> elements allow for specifying required glue records.
The attribute ip=”v4” or “v6” can be specified. When adding a name
server and not specifying it IP type, the default type is IPv4. The EPP
server will return an error when an IPv6 address is entered while
the IP address type was set to IPv4 and vice versa.
<domain:registrant> The registrant (or domain name holder) of the domain. The
registrant must be a valid contact, created on the system before
with, either EPP or via the Registrar Extranet.
<domain:contact> The list of contacts associated with this domain. The type attribute
can be one of:
- “billing” (exactly 1)
- “tech” (0 to 9)
An invalid number of contacts or other contact types are not
allowed.
<domain:authInfo> The authorisation information associated with the domain. The
value is currently ignored.
- 56 -
<domain-ext:contact> The identifier of the “onsite” contact.
<domain-ext:nsgroup> The name of name server groups
<domain-ext:keygroup> A list of keys. Please refer to “Create keygroup” for more
information.
In the secDNS:create extension, the following elements can be found:
Elements Description
<secDNS:dsData> Groups the data for Delegation signer.
<secDNS:keyData> The DNSSEC key information.
<secDNSflags> Indicates the type of the key it can be:
- 256 (ZSK)
- 257 (KSK)
<secDNS:protocol> The protocol value for the associated key. The standard value is 3.
<secDNSalg> The number that represents the cryptographic algorithm as
described on RFC 4034.
<secDNS:pubKey> The public DNSSEC key.
You can find the following elements in the <dss:create> extension:
Elements Description
<dss:dssEnabled> To put a domain under the DNSSEC Signing Service, the value
should be indicated as “true”.
<dss:master> The IP address of the (hidden) master.
<dss:slave> The IP address(es) of the slave(s) name server(s).
<dss:useTsig> The transaction signature. Possible values are:
- “true” (flag enabled)
- “false” (flag not enabled)
Please note that there is one TSIG per master name server. By
default the TSIG is not enabled and the ACL is used (Access Control
List).
<dss:nsecVariant> “NSEC” (optional)
Please refer to the information on the Registrar Extranet for subscribing to the DNSSEC Signing
Service. Before the DSS for .eu can be used, the terms of use have to be accepted.
- 57 -
6.2.3. Reply syntax
Elements Description
<domain:creData> The grouping of the domain creation data.
<domain:name> The name of the domain that has been created.
<domain:crDate> The date and time the domain has been created.
<domain:exData> The end date of the registration term
6.2.4. Return codes
The table here below lists error messages you can encounter while using the domain-create
command.
Error cases
Result
code
<msg> <reason> Likely cause
2002 Command use
error
Extension does not match command A required <extURI>
or <objURI> was not
mentioned in the
login command.
2005 Parameter value
syntax
Invalid IP address for the master name
server: ${master}
Invalid IP address for
the master
2005 Parameter value
syntax error
Invalid name server 'ns1.abc.beçç'.
2005 Parameter value
syntax error
Invalid IP address '1234::1234’. The given IP address
has not the proper
format.
2005 Parameter value
syntax error
Invalid name server 'abc.d'.
2005 Parameter value
syntax error
Invalid domain name 'a'.
2005 Parameter value
syntax error
Invalid flags value '25'.
2005 Parameter value
syntax error
Invalid protocol value '8'.
2005 Parameter value
syntax error
Invalid algorithm value '12'.
2005 Parameter value
syntax error
Invalid pubKey.
2005 Parameter value
syntax error
Invalid IP address for the master name
server '123.123.123.'.
2005 Parameter value
syntax error
Invalid IP address for the slave name
server '123.123.123.'.
2102 Unimplemented hostObj is not supported.
- 58 -
option
2102 Unimplemented
option
Contact type ‘admin’ is not supported.
2104 Billing failure Not enough money for this transaction.
2202 Invalid
authorization
information
Unknown authorisation code. Wrong authorisation
code used
2302 Object exists Domain 'some-domain' is not available. “some-domain”
cannot be registered:
it is already in use,
reserved or blocked.
2303 Object does not
exist
Contact 'c123' is not an active contact. invalid format or not
existing
2303 Object does not
exist
Name server group 'some-nsgroup'
does not exist.
2303 Object does not
exist
Keygroup 'some-keygroup' does not
exist.
2306 Parameter value
policy error
This NSEC variant is currently not
allowed 'NSEC3'.
2306 Parameter value
policy error
Contact type 'abc' is not supported. wrong contact type
on extension
2306 Parameter value
policy error
Wrong type for contact 'cXXXX'. wrong type of
contact has been
selected
2306 Parameter value
policy error
Period must be in range 1-10 years or,
when expressed in months, be a
multiple of 12.
2308 Data management
policy violation
Duplicate contact alias 'c123'.
2308 Data management
policy violation
At least one tech or onsite contact
required.
2308 Data management
policy violation
Too many billing contacts. max 1
2308 Data management
policy violation
Too many tech contacts. max 9
2308 Data management
policy violation
Too many onsite contacts. max 5
2308 Data management
policy violation
Glue not required for 'ns.some-
domain.pt'.
2308 Data management
policy violation
Maximum 9 name servers allowed.
2308 Data management
policy violation
You cannot use keys and a keygroup.
2308 Data management
policy violation
When DNSSEC Signing Service is
enabled, at least one slave name server
- 59 -
must be defined.
2308 Data management
policy violation
When DNSSEC Signing Service is
enabled, a master name server must be
defined.
2308 Data management
policy violation
When DNSSEC Signing Service is not
enabled, no other DNSSEC Signing
Service data can be defined.
dss false but dss data
is indicated
2308 Data management
policy violation
Operation not available because of too
many hit points.
6.2.5. Examples
Description Command file Response file
Domain create with 1 tech and 1
billing contact
domain-create01-cmd.xml domain-create01-resp.xml
Domain create with IDN, 2 name
servers, 1 onsite and a reseller
contact
domain-create02-cmd.xml domain-create02-resp.xml
Domain create with 2 name
servers with glue (IPv4 and IPv6), 2
name server groups, 1 tech and 1
onsite contact and for a period of
3 years
domain-create03-cmd.xml domain-create03-resp.xml
Domain create with 1 tech contact,
1 name server (1 glue IPv4),
DNSSEC with 2 keys (KSK, ZSK) and
for a period of 1 year
domain-create04-cmd.xml domain-create04-resp.xml
- 60 -
6.3. Delete domain
6.3.1. Purpose
The EPP <domain:delete> command provides the possibility to delete a domain object at a given
date. When the deletion date is reached, the domain name will be placed in quarantine for 40 days.
After the quarantine period, the domain name will be available again for registration.
If a deletion date is set in the past, the quarantine period will start on the date the deletion request
is received. For example, if on 20th September you set a deletion date on August the 10th, then the
quarantine date will start at September 20th and not August 10th.
Please keep in mind that EURid’s EPP system returns the date in UTC as specified by the
EPP standard, but that all operations scheduled to happen at a certain point in time will
be processed in local Belgian time (CET/CEST).
The deletion date cannot be set farther than ten years in the future.
Description Occurrence
Deletion date in the past Will be placed into quarantine at the next deletion job.
Deletion date in the future Will be placed into quarantine at the first deletion job running at the
specified date
Without deletion date Happens immediately.
6.3.1.1. Cancelling a scheduled deletion
When a <domain:delete> command is send with the tag <domain-ext:cancel>, then existing deletion
date is cleared. In the previous implementations, this was implemented by the “undelete”
command.
6.3.2. Request syntax
The <domain:delete> tag contains the following elements:
Elements Occurrence
min-max Size + remarks
<delete>
<domain:delete> 1
<domain:name> token: 1-255
<extension> 0-1
<domain-ext:delete> 0-1
- 61 -
<domain-ext:schedule> 0-1
<domain-ext:delDate> 0-1
<domain-ext:cancel> 0-1
<clTRID> 0-1 token: 3-64
Elements Description
<domain:name> The domain to delete, with or without a trailing “.eu” extension.
<domain-ext:delDate> The deletion date.
When overwriting a deletion date with a new deletion date, than the new
deletion date will be taken into account.
<domain-ext:cancel> When present, the deletion date is cleared.
6.3.3. Reply syntax
Elements Description
<result code=”XXXX”> XXXX stands for the return code
<msg>
<trID>
<clTRID> The transaction ID for tracking the command that was provided by the
EPP client in the incoming command.
<svTRID> The transaction ID that is provided by the server.
6.3.4. Return codes
Successful cases
Result
code
<msg> Likely cause
1000 Command completed successfully This command is only returned when a so-
called “immediate delete” is executed.
1001 Command completed successfully;
action pending
The deletion will be executed at the
specified deletion date or the next deletion
job.
Error cases for the delete command
Result
code
<msg> <reason> Likely cause
2001 Command syntax
error
linexx column yy: invalid date
value: wrong type:
The command contains
the deletion date tag, but
- 62 -
with no value
2004 Parameter value
range error
Deletion date too far in the future Trying to delete a domain
name with a deletion date
further than 10 years in
the future is not allowed
2303 Object does not
exist
Domain ‘some-domain’ does not
exist.
Domain not registered
2304 Object status
prohibits operation
Domain ‘domain-delete-err-
domain-quarantine-1349881717’
does not belong to you.
Domain is already in
quarantine
Error cases for delete cancellation
Result
code
<msg> <reason> Likely cause
2303 Object does not
exist
Domain ‘abc’ does not exist. Domain is not registered
2304 Object status
prohibits operation
Domain 'domain-undelete-err-not-
schedule-for-delete-1349881719'
is not scheduled for delete.
Domain not scheduled for
deletion
2304 Object status
prohibits operation
Domain 'domain-undelete-err-
domain-in-quarantine-
1349881720' does not belong to
you.
Domain is in quarantine
already
6.3.5. Examples
Description Command file Response file
Delete domain with a deletion
date
domain-delete01-cmd.xml domain-delete01-resp.xml
Delete domain immediately domain-delete02-cmd.xml domain-delete02-resp.xml
Delete domain with a deletion
date in the past
domain-delete03-cmd.xml domain-delete03-resp.xml
Cancel scheduled deletion domain-undelete01-cmd.xml domain-undelete01-resp.xml
- 63 -
6.4. Renew domain
6.4.1. Purpose
The purpose of the <domain:renew> is to extend the term of a domain name registration. It allows
registrars to extend the term of existing registrations that are in their portfolio at any given moment.
The registration term of a domain can be extended multiple times, but the 10 year maximum term
can never be exceeded.
It is not possible to request a reduction of the registration term of a domain name.
If a domain name is scheduled to be deleted and a term extension is requested in such a way that
the new renewal date falls after the deletion date, then the pending deletion is automatically
cancelled (i.e. the deletion date is removed).
If the domain name is in quarantine, it reactivates the registrations and extends the registration
term.
6.4.2. Request syntax
The <domain:renew> tag contains the following elements:
Elements Occurrence
min-max Size + remarks
<renew> 1
<domain:renew> 1
<domain:name> 1 token: 1-255
valid domain name: 2 to 63 characters
<domain:curExpDate> 1 Expiry date in the format yyyy-mm-dd
<domain:period> 0-1
value: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | if the unit is
years (y)
12 | 24 | 36 | 48 | 60 | 72 | 84 | 96 if the unit is
months (m)
Attribute: unit = “y” | “m”
<cITRID> 0-1 token: 3-64
- 64 -
Elements Description
<domain:name> The domain name to be extended (with or without a trailing “.eu”
extension).
<domain:curExpDate> The current expiry date of the domain name registration.
<domain:period> The period that has to be added to the registration term of the domain.
Since it is not possible to indicate a number of months higher than 99 on
EPP, the period unit cannot be ‘m’ (months) for term extensions of 9
years.
6.4.3. Reply syntax
Elements Description
<domain:name> The domain name that has been extended.
<domain:exDate> The new expiry date of the domain registration in the
format yyyy-mm-ddT00.00:000z
6.4.4. Return codes
Error cases
Result
code
<msg> <reason> Likely cause
2001 Command syntax
error
Line:xx column:yy Invalid date
value: 2012-09-30T12:34:56.789z
Wrong date format.
2003 Required
parameter missing
Period must be specified. Term extension of a
domain name without
stating the period
extension
2304 Object status
prohibits operation
Domain ‘abc’ does not belong to
you
Term extension of a
domain name that is not
in your portfolio.
2306 Parameter value
policy error
Invalid current expiry date The value of the current
expiry date does not
match the value in our
database.
2306 Parameter value
policy error
The requested term extension is
invalid
Required term extension
breaks the 10 years rule.
2306 Parameter value
policy error
Period must be in range 1-10 years
or, when expressed in months, be
Trying to extend the
period of a domain name
- 65 -
a multiple of 12. higher than allowed.
6.4.5. Examples
Description Command file Response file
Extend the term for 5 years, period
in years
domain-renew01-cmd.xml domain-renew01-resp.xml
Extend domain for 8y deletion
date is removed
domain-renew02-cmd.xml domain-renew02-resp.xml
Extend domain for 8y deletion
date is not removed
domain-renew03-cmd.xml domain-renew03-resp.xml
Extend the term of an IDN domain
for 2 years in months
domain-renew04-cmd.xml domain-renew04-resp.xml
Extend term for 4y a quarantined
domain (reactivate)
domain-renew05-cmd.xml domain-renew05-resp.xml
- 66 -
6.5. Update domain
6.5.1. Purpose
The <domain:update> command allows to change one or more attribute values of a given domain
name object. This allows changing a part of a domain name without having to re-specify the
elements that do not change.
Therefore the command is composed of three possible actions:
<add>: Add additional data to the current domain name.
<rem>: Removes data from the domain name.
<chg>: Update current data from the domain name.
The tags must be in the following order: <add>, then <rem> and then <chg>.
For the update domain command at least one <contact:add>, <contact:rem>, or <contact:chg>
element must be provided if the command is not being extended. All of these elements may be
omitted if an <update> extension is present.
This transaction can be used to update data (and even link a new contact to the domain) related to a
domain name.
Name server names can be entered in all possible supported characters, provided a valid conversion
exists between the Unicode and ACE-notation.
Please note that the update domain command can also be used to put a certain domain name under
the DNSSEC Signing Service (DSS). Before the DSS can be used, the .eu terms of use have to be
accepted. Please refer to the Registrar Extranet for more information.
When using the <rem> tag, the IP address must also be provided by using the
<domain:hostAddr> tag
- 67 -
6.5.2. Request syntax
The <domain:update>tag contains the following elements:
Elements Occurrence
min-max Size + remarks
<domain:update> 1
<domain:name> 1 token: 1-255
<domain:add> 0-1
<domain:ns> 0-1
<domain:hostAttr> 1-*
<domain:hostname> 1 token: 4-255
<domain:hostAddr> 0-* Attribute “ip” value “v4” (default) or “v6”; token 3-45
<domain:contact> 0-* token: 3-16
required attrib: type = “tech” | “billing”
<domain:rem> 0-1
<domain:ns> 0-1
<domain:hostAttr> 1-*
<domain:hostname> 1 token: 4-255
<domain:hostAddr> 0-* Attribute “ip” value “v4” (default) or “v6”; token 3-45
<domain:contact> 0-* token: 3-16
required attrib: type = “tech” | “billing”
<domain:chg> 0-1
<domain:registrant> 0-1 token: 3-16
<extension> 0-1
<domain-ext:update> 1
<domain-ext:add> 0-1
<domain-ext:contact> 0-* token: 3-16
required attrib: type = “onsite”
<domain-ext:nsgroup> 0-9 normalizedString 1-50
<domain-ext:keygroup> 0-1 normalizedString 1-50
<domain-ext:rem> 0-1
<domain-ext:contact> 0-* token: 3-16
required attrib: type =”onsite” or "reseller"
<domain-ext:nsgroup> 0-9 normalizedString 1-50
<domain-ext:keygroup> 0-1 normalizedString 1-50
<secDNS:update> 0-1
- 68 -
<secDNS:add> 0-1 Optional attrib “urgent” is not supported by the EPP
server.
<secDNS:dsData> 0 Delegation signer data
<secDNS:keyData> 0-*
<secDNS:flags> 1 256 | 257 Value is 256 for ZSK, or 257 for KSK
<secDNS:protocol> 1 3
<secDNS:alg> 1 3 | 5 | 6 | 7| 8 | 10
<secDNS:pubKey> 1 A base 64 value. Any spaces in the public key will be
removed. Maximum is 1024 base64 characters.
<dss:dssEnabled> 1 value: "true" | "false"
<dss:master> 0-1 token: 3-45
value is an IP address
<dss:add> 0-1
<dss:slave> 0-9 token: 3-45
value is an IP address
<dss:rem> 0-1
<dss:slave> 0-9 token: 3-45
value is an IP address
<dss:nsecVariant> 0-1 Value: “NSEC”
<dss:useTsig> 0-1 value: "true" | "false"
to be used with caution
<clTRID> 0-1 Token: 3-64
Elements Description
<domain:name> The domain name registration to update (with or without a trailing “.eu”
extension).
The <add> and <rem> sections contain the following child elements in that order:
Elements Description
<domain:ns> It is used to add or remove one or more name servers from the name
server list.
<domain:hostAddr> This element allows for the specification of required glue records.
The attribute ip=”v4” or “v6” can be specified.
When adding a name server and not specifying its IP type, the default
value will be IPv4.
The EPP server will return an error when an IPv6 address is entered while
the IP address type was set to IPv4 and vice versa.
<domain:contact> One or more contact handles to add or remove from the contact list.
The type attribute can be :
- 69 -
“billing” (billing contact) (must be exactly 1);
“tech” (technical contact) (0-9)
The <chg> section contains the following child elements:
Elements Description
<domain:registrant> The domain registrant handle.
The <extensions> section contains the name server groups and keygroups.
Elements Description
<domain-ext:add> Adding a new name server group or keygroup.
<domain-ext:rem> Removing name server group or keygroup
The <secDNS:update> section the following elements can be found:
Elements Description
<secDNS:keyData> The DNSSEC key information.
<secDNS:flags> The type of the key.
It can be either 256 for ZSK, or 257 for KSK.
<secDNS:protocol> The protocol value for the associated key. The standard value for EURid is
3.
<secDNS:pubKey> The public DNSSEC key
The <dss:update> section contains the following elements:
Elements Description
<dss:dssEnabled> To put a domain under the DNSSEC Signing Service, the value should be
indicated as “true”.
To remove the domain from the DSS, the value should be indicated as
“false”.
<dss:master> The IP address of the (hidden) master.
In the event that the domain is put under DSS, one IP address for the
master must be specified.
<dss:slave> The IP address(es) of the slave(s) name server(s).
<dss:useTsig> The transaction signature.
Possible values are “true” (flag enabled) or “false” (flag not enabled).
Please note that there is one TSIG per master name server.
By default the TSIG is not enabled and the ACL (Access Control List) is
used.
- 70 -
6.5.3. Reply syntax
Elements Description
<result code=”XXXX”> XXXX stands for the return code
<msg>
<trID>
<clTRID> The transaction ID for tracking the command that was provided by the EPP
client in the incoming command.
<svTRID> The transaction ID that is provided by the server.
6.5.4. Return codes
Error cases
Result
code
<msg> <reason> Likely cause
2001 Command syntax
error
line:xx column:yy: … Add name server, glue record
missing
2005 Parameter value
syntax error
Invalid IP address ‘1.1.1’. Add name server, invalid glue
2005 Parameter value
syntax error
Invalid domain name ‘some-
domain.com’
The domain name does not
fulfil all technical details or
the provided domain
extension is not allowed.
2102 Unimplemented
option
Adding ‘ok’ status is not
supported.
The <domain:status> tag is
not supported.
2102 Unimplemented
option
Urgent updates are not supported. The <secDNS:update> tag has
the unsupported value
“urgent” set to true.
2102 Unimplemented
option
Adding ‘clientHold’ status is not
supported.
The <domain:status> tag is
not supported.
2102 Unimplemented
option
DS Data Interface is not supported. As mentioned in section 6.1.3
(Key Data Interface), EURid
supports Key Data interface
only.
2102 Unimplemented
option
hostObj is not supported.
2102 Unimplemented
option
Removing
‘clientTransferProhibited’ status is
not supported.
No locking action is allowed
in EPP
2303 Object does not
exist
Name server group ‘nsgroup-
1349875849’ does not exist.
Add non-existing name
server group
2303 Object does not
exist
Contact 'c12345' does not exist. The contact alias is invalid or
does not exist in your
- 71 -
portfolio.
2303 Object does not
exist
Domain 'domain-update-err-does-
not-exist' does not exist.
Domain update command for
a domain that does not exist
2303 Object does not
exist
Cannot remove non-existing key.
2304 Object status
prohibits operation
Domain ‘some-domain-name' does
not belong to you.
This domain is not in your
portfolio
2304 Object status
prohibits operation
Domain ‘some-domain-name' does
not belong to you.
Update an existing domain
out of registrar's portfolio or
in quarantine
2304 Object status
prohibits operation
Contact 'c12345' is not linked to
this registration.
Remove a tech contact not
linked to registration
2304 Object status
prohibits operation
Name server ‘some-name-server
192.148.32.21.eu' is not linked to
this registration.
Remove a name server which
is not linked to the
registration
2304 Object status
prohibits operation
This update could not be done on
a locked domain.
Adding DNSSEC info on a
locked domain is not
possible.
2308 Data management
policy violation
At least one tech or onsite contact
required.
Remove the last tech contact
2308 Data management
policy violation
Contact 'c12345' is already linked
to this registration.
Add a tech or onsite contact
already linked to the
registration
2308 Data management
policy violation
Name server ‘some-name-server
192.148.32.21.eu' is already linked
to this registration.
Add a name server which is
already linked to the
registration
2308 Data management
policy violation
Missing glue for ‘ns1.some-
nameserver.eu’.
No IP addressed mentioned
for the name server.
2308 Data management
policy violation
Glue not required for ‘ns1.some-
domain.eu’.
The given nameserver does
not belong to a (sub)domain
of the domain being
updated.
6.5.5. Examples
Description Command file Response file
Add and remove tech contact, add
and remove onsite contact, add
reseller contact, change registrant
domain_update01_cmd.xml domain_update01_resp.xml
- 72 -
Add and remove tech contact, add
and remove onsite contact, add
and remove nsgroup, add and
remove keygroup, change
registrant
domain_update02_cmd.xml domain_update02_resp.xml
DNSSEC keys— add ZSK, add KSK domain_update03_cmd.xml domain_update03_resp.xml
Remove all DNSSEC keys domain_update04_cmd.xml domain_update04_resp.xml
Remove of 1 name server with the
corresponding IP address
domain_update05_cmd.xml domain_update05_resp.xml
Remove of 2 name servers with
their corresponding IP addresses
domain_update06_cmd.xml domain_update06_resp.xml
Remove of DNSSEC key
information
domain_update07_cmd.xml domain_update07_resp.xml
Add 2 name servers with for each
an IPv4 and IPv6 glue record
domain_update08_cmd.xml domain_update08_resp.xml
- 73 -
6.6. Check domain
6.6.1. Purpose
The EPP command <domain:check>allows to enquire about:
The current availability of one or more domain names;
The availability date for a domain name that is currently in quarantine;
The existence of a domain name lock set by the registry.
In order to avoid abusive querying, a rate-limit has been introduced for the EPP command
<check:domain>. The rate-limit is for a sliding window of 60 (sixty) seconds and the quota is 360
checks during this period
6.6.2. Request syntax
The <domain:check> tag contains the following elements:
Elements Occurrence
min-max Size + remarks
<domain:check> 1
<domain:name> 1-* token: 1-255
<clTRID> 0-1 token: 3-64
Elements Description
<domain:name> Domain names (with or without the “.eu” extension) to be checked for
availability. You can check the availability of several domain names at the
same time.
Please keep the rate limit in mind as explained above.
- 74 -
6.6.3. Reply syntax
Elements Description
<domain:name avail=”X”> This tag shows the availability of the queried domain
name.
The “X” in the tag can have two possible values:
“true”: meaning that the domain name is
available for registration.
“false”: meaning that the domain name is
not available
<domain:reason> If the queried domain name is not available, this tag
will also be present and showing the reason why it is
not available.
Possible reasons are: in use, quarantine, reserved,
blocked and withdrawn.
<domain-ext:status
s="serverTransferProhibited"/>
This additional attribute is returned when a queried
domain name is locked.
<domain-ext:availableDate > When a quarantined domain name is queried, this
additional attribute is returned.
It will show the date and time when the domain
name will become available.
Please note that the time indicates the start of a 24
hour time period in which the domain name will be
released.
Dates in EPP are returned in UTC time format while
scheduled operations will be performed in Belgian
time (CET/CEST).
For IDN domain names the result will also contain the following elements in the extension:
Elements Description
<idn:ace> The queried IDN domain name in the ACE
representation.
<idn:unicode> The queried IDN domain name in the Unicode
representation.
The IDN extension for IDN domain names always displays both notations: Unicode and ACE. The
reply contains the domain name queried in the format used in the command.
- 75 -
6.6.4. Return codes
The table here below lists error messages you can encounter while using the <domain:check>
command.
Error cases
Result
code
<msg> <reason> Likely cause
2001 Command syntax
error
line:xx column:yy: … Domain name > 255
characters
2306 Parameter value
policy error
Excessive querying. The query rate limit has been
exceeded.
6.6.5. Examples
Description Command file Response file
Example of domain check
command of multiple domain
names
domain-check01-cmd.xml domain-check01-resp.xml
Querying the availability of a
locked domain name
domain-check02-cmd.xml domain-check02-resp.xml
- 76 -
6.7. Info domain
6.7.1. Purpose
The EPP command <domain:info> is used to retrieve information associated with a domain name.
The response to this command can vary depending on the registrar who is executing it.
In principle, a registrar can only request detailed information about a domain name in his portfolio.
However, details on domain names under the management of another registrar are returned only
when a valid transfer authcode is present in the <authInfo:info> tag.
The <domain:info> can be used for:
To retrieve data about a domain name that you are currently managing.
To generate a transfer authorisation code for a domain name that is currently in your
portfolio.
This authorisation code should be communicated to the registrant to give him the
opportunity to transfer away the domain name.
To retrieve data about a domain that is not (yet) under your management and you intend to
transfer to your portfolio.
In order to avoid abusive querying, a rate-limit has been introduced for the EPP command
<domain:info>. The rate-limit is for a sliding window of 60 (sixty) seconds and the quota is 180
checks during this period..
6.7.2. Request syntax
The <domain:info> tag contains the following elements:
Elements Occurrence
min-max Size + remarks
<domain:info> 1
<domain:name> 1 token: 1-255
<domain:authInfo> 0-1
<domain:pw> 1
<extension> 0-1
<authInfo:info> 1
<authInfo:request> 1
<clTRID> 0-1 token: 3-64
- 77 -
Elements Description
<domain:name> The domain name, with or without the extension “.eu”.
<domain:pw> The authorisation code which allows you to retrieve data about a
domain name that is not in your portfolio
<authInfo:request> Requesting for an authorisation code needed for a transfer.
This extension cannot be used when the domain name is not in the
portfolio of the registrar.
<clTRID> The transaction ID for tracking the command that was provided by the
EPP client in the incoming command.
6.7.3. Reply syntax
Elements Description
<domain:name> The domain name queried.
<domain:roid> The Repository Object iDentifier assigned to the domain when
it was created.
<domain:status> s=”ok”
When the domain name is locked, the following
statuses will be received:
o s=”serverTransferProhibited”
o s=”serverDeleteProhibited”
o s=”serverUpdateProhibited”
When the domain name lock is disabled, the following
statuses will be received:
o s=”serverTransferProhibited”
o s=”serverDeleteProhibited”
<domain:registrant> The contact handle of the current registrant of the domain.
<domain:contact type=”XXXX”> A list of all the other contact handles related to the queried
domain name.
XXXX stands for the contact type (billing, tech).
<domain:hostName> The name server that belongs to the domain name.
<domain:hostAddr> IPv4 or IPv6 address of the name server.
<domain:clID> The identifier of the sponsoring registrar.
<domain:crID> The identifier of the registrar who created the object (in the
EURid implementation, this is always the same as clID).
<domain:crDate> The UTC date/time of the creation of the domain name.
Dates are returned in UTC time format in EPP.
<domain:upID> The identifier of the client who last updated the object.
<domain:upDate> The UTC date/time of the last update of the domain name.
<domain:exDate> The UTC expiration date/time of the domain name.
Dates are returned in UTC time format in EPP while scheduled
operations will be performed in Belgian time (CET/CEST).
<domain:authInfo> Displays the authorisation code needed for a transfer (only if
- 78 -
requested)
<domain:pw> The authorisation password that was requested
<domain-ext:onHold> “true” when the domain name is on hold
“false” when the domain name is not on hold
<domain-ext:quarantined> “true” when the domain name is in quarantine
“false” when the domain name is not in quarantine
<domain-ext:deletionDate> If a domain name has been scheduled for deletion, but is not
yet in quarantine, the deletion date will be returned in UTC
time format.
<domain-ext:contact> Onsite or reseller contacts
<domain-ext:nsgroup> The name of name server groups
<domain-ext:keygroup> A list of keys. Please refer to “Create keygroup” for more
information.
When the domain name concerns a pending transfer and the command is initiated by the initiating
registrar of the transfer, the <domain:info> command also shows an additional extension <domain-
ext:pendingTransfer> with the following elements:
Elements Description
<domain-ext:registrant> The registrant contact identifier of the pending transfer.
<domain-ext:contact type=”XXXX”> A list of all the other contact handles related to the queried
domain name.
XXXX stands for the contact type (billing, onsite, tech).
<domain-ext:initiationDate> The initiation date of the transfer.
For IDN domain names the result will also contain the following fields in the extension:
Elements Description
<idn:ace> The registered IDN domain name in the ACE representation.
<idn:unicode> The registered IDN domain name in the Unicode
representation.
Elements Description
<secDNS:keyData> The DNSSEC key information.
<secDNS:flags> Indication of the key type. It can be either 256 for ZSK, or
257 for KSK.
<secDNS:protocol> The protocol value for the associated key. The standard
value for EURid is 3.
<secDNS:pubKey> The public DNSSEC key.
When subscribed to the DNSSEC Signing Service, the following elements can be found in the reply:
In the <dss:infData>, the following elements can be found in the reply:
- 79 -
Elements Description
<dss:dssEnabled> When a domain name is put under the DNSSEC Signing Service, than
the value will be “true”.
<dss:master> The IP address of the master.
<dss:slave> The IP address of the slave(s).
<dss:nsecVariant> Only NSEC is used.
<dss:useTsig> The transaction signature. Possible values are ‘true’ (flag enabled) or
‘false’ (flag disabled).
Please note that there is one TSIG per master name server. By default
the TSIG is not enabled and the ACL (Access Control List) is used.
6.7.4. Return codes
Error cases
Result
code
<msg> <reason> Likely cause
2005 Parameter value
syntax error
Invalid domain name ‘xxxx’. Invalid domain name
2202 Invalid
authorization
information
Domain 'some-domain' is locked. domain locked
(authcode ignored)
2202 Invalid
authorization
information
Unknown authorisation code. invalid authcode
2202 Invalid
authorization
information
Authorisation code was already
used.
code already used on a
transfer
2202 Invalid
authorization
information
Unknown authorisation code. Domain info with a valid
domain and a valid auth
code, but domain not
linked to auth code
2300 Object pending
transfer
Domain ‘some-domain’ is already
being transferred.
An authorisation code
cannot be requested for
a domain name that has
a pending transfer.
2303 Object does not
exist
(n.a.) domain not registered
2306 Parameter value
policy error
Excessive querying. The query rate limit has
been exceeded.
2308 Data management
policy violation
You can not obtain authorisation
code for a domain name which is
not yours.
The domain for which
you requested an
authcode is not in
your portfolio.
- 80 -
6.7.5. Examples
Description Command file Response file
Status in use and not locked/1
onsite & 1 tech contact/2 name
servers with glues (IPv4 and
IPv6)/no DNSSEC
domain-info01-cmd.xml domain-info01-resp.xml
Example with request for
authcode: status in use and not
locked/1 tech contact and no
onsite contact/no DNS and no
DNSSSEC
domain-info02-cmd.xml domain-info02-resp.xml
Status in use and not locked/in
other registrar's portfolio
domain-info03-cmd.xml domain-info03-resp.xml
Status in use and not locked/in
other registrar's portfolio and
using authcode on request/2
onsite contacts and no tech
contacts/2 name servers with no
glue/no DNSSEC
domain-info04-cmd.xml domain-info04-resp.xml
Status in quarantine/IDN Latin/1
tech & 1 onsite contact/1 name
server and no glue/1 DNSSEC key
domain-info05-cmd.xml domain-info05-resp.xml
Domain name in own portfolio
with a deletion date, nsgroup and
1 keygroup
domain-info06-cmd.xml domain-info06-resp.xml
Domain name that is not yet in the
registrar's portfolio, but has a
pending "ingoing" transfer.
domain-info07-cmd.xml domain-info07-resp.xml
Domain name that is in the
registrar's portfolio and has a
pending transfer (in portfolio
transfer)
domain-info08-cmd.xml domain-info08-resp.xml
- 81 -
Domain info without authcode
from a registrar who is not the
owner of a locked domain
domain-info09-cmd.xml domain-info09-resp.xml
Domain info of a pending transfer
and with a reseller contact
domain-info10-cmd.xml domain-info10-resp.xml
- 82 -
7. Transfer domain
7.1. Purpose
The purpose of the <domain:transfer> command is to transfer a domain name from one registrar to
another registrar.
It is the new registrar (the one the domain is transferred to) that has to initiate the transaction.
Registrants have to contact their old registrar to receive an authorisation code which they have to
give to the new registrar. The new registrar then initiates the transfer using this unique authorisation
code.
This authorisation code is used to confirm the transfer action.
The remaining term of the registration will be transferred to the new registration once the transfer
has been processed.
7.2. Request syntax
The <domain:transfer> tag contains the following elements:
Elements Occurrences
min-max Size + remarks
<domain:transfer> 1 required attrib: op=”request"
<domain:name> 1 token: 2-63
<domain:period> 0-1 required attrib: unit = "y"|"m"
value: 1-99
<domain:authInfo> 1
<domain:pw>
<extension> 0-1
<domain-ext:transfer>
<domain-ext:request>
<domain-ext:registrant> 1 token: 3-16
<domain-ext:contact> token: 3-16
Tech: 0-9
Onsite: 0-5
Billing: 1
Registrant: 0-1 (The absent registrant data
from the current registrar will be copied).
<domain-ext:ns> 0-1
<domain:hostAttr> 1-9
<domain:hostname> 1 token: 4-255
<domain:hostAddr> attribute “ip” value “v4”(default) or “v6” (can be
- 83 -
indicated)
token: 3-45
<secDNS:create>
<secDNS:keyData>
<secDNS:flags> 256 | 257 (value is 256 for ZSK, or 257 for KSK)
<secDNS:protocol> 3
<secDNS:alg> 3 | 5 | 6 | 7| 8 | 10
<dss:create>
<dss:dssEnabled>
<dss:master>
<dss:slave>
<dss:useTsig>
<dss:nsecVariant>
Elements Description
<transfer op="request"> The command tag to request a transfer.
Other operations are not implemented.
<domain:name> The domain name to be transferred, with or without a trailing “.eu”.
<domain:period> The domain term period. Only accepted are 1 with unit “y” (year) and
12 with unit “m” (month).
<domain:pw> The authorisation code with which the transfer request can be
confirmed. An authorisation code is valid for 40 calendar days and is
linked to one combination of registrant and domain name only.
<domain-ext:registrant> The registrant contact identifier of the transferred domain.
The registrant info will then be copied from the current registration.
When the <domain-ext:registrant> is absent, then a new registrant
contact object will be created and filled with data coming from the
current registrar.
When the tag is present, then its value must be the contact alias of a
registrant that currently exists in your portfolio.
<domain-ext:contact> These are the different contact identifiers of the domain.
Each contact should belong to the new registrar.
Please refer to “create contact” for information on the meaning of
each value.
<domain-ext:ns> The set of name servers, with or without IP addresses (only needed as
glue records). See also “create domain” for more information.
<nsgroup> The set of name server groups.
Please refer to the information on the Registrar Extranet for subscribing to the DNSSEC Signing
Service. Before the DSS for .eu can be used, the terms of use have to be accepted.
- 84 -
In the secDNS:create extension, the following elements can be found:
Elements Description
<secDNS:keyData> The DNSSEC key information.
<secDNS:flags> The type of the key. It can be:
- 256 (ZSK)
- 257 (KSK)
<secDNS:protocol> The protocol value for the associated key. Standard
In the dss:create extension, the following elements can be found:
Elements Description
<dss:dssEnabled> To put a domain under the DNSSEC Signing Service, the value should
be indicated as “true”.
<dss:master> The IP address of the (hidden) master.
<dss:slave> The IP address(es) of the slave(s) name server(s).
<dss:useTsig> The transaction signature. Possible values are:
- “true” (flag enabled)
- “false” (flag not enabled)
Please note that there is one TSIG per master name server. By default
the TSIG is not enabled and the ACL (Access Control List) is used.
<dss:nsecVariant> “NSEC” (optional)
7.3. Reply syntax
Elements Description
<result code=”XXXX”> XXXX stands for the return code
<msg>
<trID>
<clTRID> The transaction ID for tracking the command that was provided by the EPP
client in the incoming command.
<svTRID> The transaction ID that is provided by the server.
7.4. Return codes
Successful cases
Result
code
<msg> Likely cause
1000 Command completed successfully The transfer request is executed immediately.
1001 Command completed successfully;
action pending
The transfer request has been placed in the
validation queue.
- 85 -
Error cases
Result
code
<msg> <reason> Likely cause
2001 Command syntax
error
line:xx column:yy: …. first letter missing on key
2005 Parameter value
syntax error
Invalid algorithm value ‘9’
2005 Parameter value
syntax error
Invalid domain name 'c'.
2005 Parameter value
syntax error
Invalid domain name 'abcº'.
2005 Parameter value
syntax error
Invalid IP address '123.45.67'. invalid IP address
2005 Parameter value
syntax error
Invalid IP type for address '123.45.67.9'. wrong IP type
2005 Parameter value
syntax error
Invalid flags value '25'.
2202 Invalid
authorization
information
Authorisation code was already used.
2202 Invalid
authorization
information
Invalid authorisation code. wrong format or empty
2202 Invalid
authorization
information
Authorisation code has expired. authorisation code
expires after 40 days
2202 Invalid
authorization
information
Unknown authorisation code.
2202 Invalid
authorization
information
Authorization information is missing.
2300 Object pending
transfer
Domain ‘some-domain’ is already being
transferred.
2303 Object does not
exist
Contact 'c1122' is not an active contact. contact belongs to
other registrar
2304 Object status
prohibits operation
Domain 'some-domain-name' has
invalid status.
domain not registered or
in on hold status
2306 Parameter value
policy error
Period must be 1 year or 12 months.
2306 Parameter value
policy error
Wrong type for contact 'c123456'.
2308 Data management At least one tech or onsite contact
- 86 -
policy violation required.
2308 Data management
policy violation
Too many tech contacts. too many tech
2308 Data management
policy violation
Too many onsite contacts. too many onsite
2308 Data management
policy violation
Duplicate contact alias 'c12345'. contact alias repeated
(one as tech another as
billing)
2308 Data management
policy violation
Missing glue for 'ns2.msome-
domain.eu'.
glue required: the IP
address of the given
name server is missing
2308 Data management
policy violation
Glue not required for 'ns1.other-
domain.eu'.
glue not required
2308 Data management
policy violation
Unable to use name server groups,
name servers, keygroups or keys when
transfer profile is 'copy'.
2308 Data management
policy violation
Missing billing contact.
2308 Data management
policy violation
There is already a pending activation
request for this domain.
When there is a pending
activation request for a
reserved domain name
and another registrar
makes also a transfer
request.
2308 Data management
policy violation
Operation not available because of too
many hit points.
7.5. Examples
Description Command file Response file
Transfer of domain, copy of
registrant, 1 technical contact
transfer01-cmd.xml transfer01-resp.xml
Transfer of IDN domain, new
registrant, period tag added, 1
tech & 1 onsite contact
transfer02-cmd.xml transfer02-resp.xml
Transfer of domain, 1 onsite
contact, 1 reseller contact, 2 name
transfer03-cmd.xml transfer03-resp.xml
- 87 -
servers with glues (IPv4 & IPv6), 1
name server group
Transfer of domain, new
registrant, 1 tech contact and 2
DNSSEC keys
transfer04-cmd.xml transfer04-resp.xml
- 89 -
8. Name server groups
8.1. Introduction
The name server group mapping is a EURid specific object-extension to the EPP standard, coherent
with the EPP object extension framework. The name server group object allows a registrar to group
several name servers in one object, thus facilitating the mapping between a domain name and a list
of name servers.
When a name server group is attached to a domain name (at creation of the domain or through an
update), it has the same effect as linking all the name servers individually to that domain.
When the zone file is generated, the name server group is replaced by the name servers it contains.
The advantage is that an update becomes easy. Changing a name server group (e.g. adding an
additional name server) will have an effect on all the domain names that are linked to that name
server group.
8.2. Create name server groups
8.2.1. Purpose
To create a list of name servers that can be used as a placeholder on a domain registration.
8.2.2. Request syntax
The <nsgroup:create> tag contains the following elements:
Elements Occurrence
min-max Size + remarks
<create>
<nsgroup:create> 1
<nsgroup:name> 1 normalizedString 1-50
containing characters from [a-z][0-9][-.]
<nsgroup:ns> 0-9 token: 4-255
<clTRID> 0-1 token: 3-64
Elements Description
<nsgroup:name> The (chosen) name for the name server group.
<nsgroup:ns> The name of the server.
<clTRID> The transaction ID (for tracking the command).
- 90 -
8.2.3. Reply syntax
Elements Description
<result code=”XXXX”> XXXX stands for the return code
<msg> Message showing the result of the nsgroup creation
<trID>
<clTRID> The transaction ID for tracking the command that was
provided by the EPP client in the incoming command.
<svTRID> The transaction ID that is provided by the server.
8.2.4. Return codes
The table here below lists error messages you can encounter while using the create name server
command.
Error cases
Result
code
<msg> <reason> Likely cause
2005 Parameter value
syntax error
Invalid name server. Name server field
contains invalid
characters
2302 Object exists Name server group ‘some-nsgroup’
already exists.
Creating a nsgroup
that already exists.
8.2.5. Examples
Description Command file Response file
Creation of a nsgroup nsgroup-create01-cmd.xml nsgroup-create01-resp.xml
- 91 -
8.3. Delete name server groups
8.3.1. Purpose
The command <nsgroup:delete> can be used to delete a name server group.
It is not possible to delete a name server group that is still linked to one or more
domains.
8.3.2. Request syntax
The <nsgroup:delete> tag contains the following elements:
Elements Occurrence
min-max Size + remarks
<delete>
<nsgroup:delete> 1
<clTRID> 0-1 token: 3-64
Elements Description
<nsgroup:name> The name of the name server group that you want to delete.
<clTRID> The transaction ID (for tracking the command) that was provided by the
registrar in the incoming command.
8.3.3. Reply syntax
Elements Description
<result code=”XXXX”> XXXX stands for the return code
<msg> Message showing the result of the nsgroup creation
<trID>
<clTRID> The transaction ID for tracking the command that was
provided by the EPP client in the incoming command.
<svTRID> The transaction ID that is provided by the server.
- 92 -
8.3.4. Return codes
The table here below lists error messages you can encounter while using the delete name server
command.
Error cases
Result
code
<msg> <reason> Likely cause
2005 Parameter value
syntax error
Invalid name server group name
‘a,some-domain,com’.
Invalid characters
2303 Object does not
exist
Name server group ‘some-name server-
group’ does not exist.
Trying to delete an
name server group
that does not exists
2305 Object association
prohibits operation
Name server group ‘some-name server-
group’ is still linked to 1 domains.
Trying to delete a
name server group
that is still linked to at
least one domain.
8.3.5. Examples
Description Command file Response file
NSgroup delete example nsgroup-delete01-cmd.xml nsgroup-delete01-resp.xml
- 93 -
8.4. Update name server groups
8.4.1. Purpose
The command <nsgroup: update> allows to replace the content of a name server group.
Please note that this command updates the whole object at once. There is no <add>,
<chg> or <rem> sections as with some other EPP objects.
8.4.2. Request syntax
The <nsgroup: update> tag contains the following elements:
Elements Occurrence
min-max Size + remarks
<update> 1
<nsgroup: update> 1
<nsgroup:name> 1 normalizedString 1-50
containing characters from [a-z][0-9][-.]
<nsgroup:ns> 0-9 token: 4-255
<clTRID> 0-1 token: 3-64
Elements Description
<nsgroup:name> The name of the name server group.
<nsgroup:ns> The name of the server.
<cLTRID> The transaction ID for tracking the command that was provided by the
EPP client in the incoming command.
8.4.3. Reply syntax
Elements Description
<result code=”XXXX”> XXXX stands for the return code
<msg> Message showing the result of the nsgroup creation
<trid>
<clTRID> The transaction ID (for tracking the command) that was
provided by the registrar in the incoming command.
<svTRID> The transaction ID that is provided by the server.
- 94 -
8.4.4. Return codes
The table here below lists error messages you can encounter while using the update name server
command.
Error cases
Result
code
<msg> <reason> Likely cause
2005 Parameter value
syntax error
Invalid name server group name
‘a,some-domain,com’.
Invalid characters
2005 Parameter value
syntax error
Invalid name server name ‘ns.some-
domain,com’.
Invalid characters
2303 Object does not
exist
Name server group ‘nsgroup-some-
name’ does not exist.
The name server
group does not exist.
2308 Data management
policy violation
Missing glue for 'ns2.msome-
domain.eu'.
glue required
2308 Data management
policy violation
Glue not required for 'ns1.other-
domain.eu'.
glue not required
2308 Data management
policy violation
Unable to use name server groups,
name servers, keygroups or keys when
transfer profile is 'copy'.
8.4.5. Examples
Description Command file Response file
Example of an update of a name
server group
nsgroup-update01-cmd.xml nsgroup-update01-resp.xml
- 95 -
8.5. Check name server groups
8.5.1. Purpose
The command <nsgroup:check> can be used to determine the (in)existence of a name server group
in your portfolio.
Please note that a single <nsgroup:check> can be used to test the availability (or
inexistence) of more than one name server group.
8.5.2. Request syntax
The <nsgroup:check> tag contains the following elements:
Elements Occurrence
min-max Size + remarks
<check>
<nsgroup:check> 1
<nsgroup:name> 1-* normalizedString 1-50
containing characters from [a-z][0-9][-.]
<clTRID> 0-1 token: 3-64
Elements Description
<nsgroup:name> The (chosen) name for the name server group.
<clTRID> The transaction ID that is provided by the registrar for his own reference
- 96 -
8.5.3. Reply syntax
Elements Description
<result code=”XXXX”> XXXX stands for the return code
<msg> Message showing the result of the nsgroup creation
<resData>
<nsgroup:chkData>
<nsgroup:cd>
<nsgroup:name avail=”xxxx”> If the name server group is available for use, then
“xxxx” has the value “true”.
If the name server group is not available for use, then
“xxxx” has the value “false”.
<nsgroup:reason lang=”en”> If the name server group is not available for use, this
additional tag will become visible, showing the reason
of its unavailability.
Possible reasons:
In use
Invalid name server group name
<trID>
<clTRID> The transaction ID (for tracking the command) that
was provided by the registrar in the incoming
command.
<svTRID> The transaction ID that is provided by the server.
8.5.4. Return codes
There are no real error messages to be expected here, except for the error code ‘2001’ – ‘Command
syntax error’.
8.5.5. Examples
Description Command file Response file
Checking a non-existing name
server
nsgroup-check01-cmd.xml nsgroup-check01-resp.xml
Checking some existing name
server groups
nsgroup-check02-cmd.xml nsgroup-check02-resp.xml
- 97 -
8.6. Info name server groups
8.6.1. Purpose
The command <nsgroup:info> can be used to retrieve the content of an existing nsgroup.
Two variants are possible with this command:
1. When you are using nsgroup 1.0 you can only use this command for name server groups in
your own portfolio.
2. When you are using nsgroup 1.1 you can also use this command for name server groups that
are not in your own portfolio if you have the authorisation code.
8.6.2. Request syntax
The <nsgroup:info> tag contains the following elements:
Elements Occurrence
min-max Size + remarks
<info>
<nsgroup:info> 1
<nsgroup:name> 1 normalizedString 1-50
containing characters from [a-z][0-9][-.]
<nsgroup:authInfo> 0-1 Only possible when using nsgroup 1.1
<nsgroup:pw> 1
<clTRID> 0-1 token: 3-64
Elements Description
<nsgroup:name> The of the name server group.
<nsgroup:authInfo>
<nsgroup:pw> The authorisation code that is required to inquire nsgroups that are not
in your own portfolio.
<clTRID> The transaction ID (for tracking the command) that was provided by you
in the incoming command.
- 98 -
8.6.3. Reply syntax
Elements Description
<result code=”XXXX”> XXXX stands for the return code
<msg> Message showing the result of the nsgroup creation
<resData>
<nsgroup:infData>
<nsgroup:name> Name of the name server group that was inquired.
<nsgroup:ns> Name of a name server that belongs to the name
server group.
<extension>
<idn:mapping>
<idn:name>
<idn:ace> The queried IDN name server in the ACE
representation.
<idn:unicode> The queried IDN name server in the Unicode
representation.
<trID>
<clTRID> The transaction ID that is provided by you for your
own reference.
<svTRID> The transaction ID that is provided by the server.
8.6.4. Return codes
The table here below lists error messages you can be encountered while using the info name server
command.
Error cases for name server groups 1.0
Result
code
<msg> <reason> Likely cause
2001 Command
syntax error
line:xx column:yy: string length (51) is greater than
maxLength facet …
nsgroup:name > 50
characters
2001 Command
syntax error
line:xx column:yy: Element not allowed: … Used
nsgroup:authInfo
which is not
allowed in nsgroup
1.0
2005 Parameter
value syntax
error
Invalid name server group name 'a*?bc'. nsgroup name
invalid
2303 Object does
not exist
No such nsgroup in
your portfolio
- 99 -
Error cases for name server groups 1.1
Result
code
<msg> <reason> Likely cause
2001 Command
syntax error
line:xx column:yy: string length (51) is greater
than maxLength …
nsgroup:name > 50
characters
2005 Parameter
value syntax
error
Invalid name server group name 'a*?bc'. nsgroup name
invalid
2202 Invalid
authorization
information
Unknown authorisation code.
2202 Invalid
authorization
information
Invalid authorisation code.
2303 Object does
not exist
No such nsgroup in
your portfolio
8.6.5. Examples
Description Command file Response file
NSgroup info version 1.0 nsgroup-info01-cmd.xml nsgroup-info01-resp.xml
NSgroup info version 1.1 for
nsgroups in your own portfolio
nsgroup-info02-cmd.xml nsgroup-info02-resp.xml
NSgroup info version 1.1 for
nsgroups not in your own
portfolio (with authorisation
code)
nsgroup-info03-cmd.xml nsgroup-info03-resp.xml
- 101 -
9. Keygroups
9.1. Introduction
To simplify the management of keys linked to domain names, EURid has introduced the concept of
keygroup.
Without keygroups, you would need to create keys (e.g. a KSK and a ZSK) for each DNSSEC enabled
domain name. In cases where a large number of domain names needs to be made secure, this would
also mean the creation of a large number of individual key files (public and private keys).
The amount of work required to manage these keys would increase even more when they are about
to expire and need to be replaced individually.
Keygroups help to address this issue.
A keygroup is a reusable, named set of public keys.
Each keygroup has a unique name and can contain up to four keys. Once a domain name has been
created (registered), it can be linked to a keygroup simply by using the keygroup name. Linking a
domain name to a keygroup has the same effect as individually linking all the keys in that keygroup
to the domain name when the zone file is generated or updated.
Since one keygroup can be linked to any number of domain names, the number of keys to be
created or replaced is drastically reduced. For instance, consider a keygroup linked to 1000 domain
names. Changing a single key in that keygroup is the same as changing that key 1000 times for each
individual domain name (if keygroups were not used).
Rules when working with keygroups:
Each keygroup must have a distinct name within your portfolio.
A keygroup may have up to four DNSSEC keys at the time.
A keygroup may be associated to any number of domain names.
A domain name may at most be linked to one keygroup.
A domain name that is linked to individual keys cannot also be linked to a keygroup and vice
versa.
- 102 -
9.2. Create keygroup
9.2.1. Purpose
The command <keygroup:create> can be used to create keygroups.
9.2.2. Request syntax
The < keygroup:create> tag contains the following elements:
Elements Occurrence
min-max Size + remarks
<create> 1
<keygroup:create> 1
<keygroup:name> 1 normalizedString 1-50
containing characters from [a-z][0-9][-.]
<keygroup:keyData> 0-9
<keygroup:flags> 1 256 | 257 value is 256 for ZSK or 257 for KSK
<keygroup:protocol> 1 only “3” is currently accepted at EURid
<keygroup:alg> 1 3 | 5 | 6 | 7 | 8 | 10
<keygroup:pubKey> 1 A base 64 value. Any spaces in the public key will be
removed. Maximum is 1024 base64 characters.
<clTRID> 0-1 token: 3-64
Elements Description
<keygroup:name> The name for the keygroup
<keygroup:keyData> The keytag for the associated key.
<keygroup:flags> The type of the key. It can be either 256 for ZSK, or 257 for KSK.
<keygroup:protocol> The protocol value for the associated key.
Standard value for EURid is 3.
<keygroup:alg> The number that represents the algorithm.
<keygroup:pubKey> The public DNSSEC key.
<cLTRID> The transaction ID for tracking the command that was provided by the
EPP client in the incoming command.
- 103 -
9.2.3. Reply syntax
Elements Description
<result code=”XXXX”> XXXX stands for the return code
<msg> Message showing the result of the nsgroup creation
<trID>
<clTRID> The transaction ID for tracking the command that was
provided by the EPP client in the incoming command.
<svTRID> The transaction ID that is provided by the server.
9.2.4. Return codes
Error cases
Result
code
<msg> <reason> Likely cause
2005 Parameter value
syntax error
Invalid keygroup name ‘somé-
keygroup’.
Not allowed character
in <keygroup:name>
2005 Parameter value
syntax error
Invalid protocol ‘4’. Only protocol ‘3’ is
accepted.
2005 Parameter value
syntax error
Invalid algorithm ‘2’. Algorithm ‘2’ is not a
valid algorithm.
2005 Parameter value
syntax error
Invalid flags ‘258’. Flag ‘258’ is not a valid
flag.
2302 Object exists Keygroup ‘some-keygroup’ already
exists.
You cannot create a
keygroup that already
exists.
2308 Data management
policy violation
Duplicate key with keytag ‘xxxx’. You cannot create a
keygroup where to or
more keys are
identical.
- 104 -
9.2.5. Examples
Description Command file Response file
Basic create keygroup command keygroup-create01-cmd.xml keygroup-create01-resp.xml
Create keygroup command with
DNSSEC key
keygroup-create02-cmd.xml keygroup-create02-resp.xml
Create keygroup command with
4 DNSSEC keys
keygroup-create03-cmd.xml keygroup-create03-resp.xml
- 105 -
9.3. Delete keygroup
9.3.1. Purpose
The command <keygroup:delete> can be used to delete keygroups.
Note that it is not possible to delete a keygroup that is still linked to one or more domain names.
9.3.2. Request syntax
The < keygroup:delete> tag contains the following elements:
Elements Occurrence
min-max Size + remarks
<delete> 1
<keygroup:delete> 1
<keygroup:name> 1 normalizedString 1-50
containing characters from [a-z][0-9][-.]
<clTRID> 0-1 token: 3-64
Elements Description
<keygroup:name> The name for the keygroup
<cLTRID> The transaction ID for tracking the command that was provided by the
EPP client in the incoming command.
9.3.3. Reply syntax
Elements Description
<result code=”XXXX”> XXXX stands for the return code
<msg>
<trID>
<clTRID> The transaction ID that is provided by you for your own reference.
<svTRID> The transaction ID that is provided by the server.
- 106 -
9.3.4. Return codes
Error cases
Result
code
<msg> <reason> Likely cause
2005 Parameter value
syntax error
Invalid keygroup name ‘somé-
keygroup’.
Not allowed character
in <keygroup:name>
2303 Object does not
exist
Keygroup ‘some-keygroup’ does not
exist.
The keygroup does
not exist.
2305 Object association
prohibits operation
Keygroup ‘some-keygroup’ is still linked
to X domain(s).
Deleting a keygroup
that is still linked to X
domain names is not
allowed.
9.3.5. Examples
Description Command file Response file
Delete keygroup command keygroup-delete01-cmd.xml keygroup-delete01-resp.xml
- 107 -
9.4. Update keygroup
9.4.1. Purpose
The command <keygroup:update> can be used to update the content of keygroups.
Updating a keygroup replaces the current content by what is indicated in the command.
9.4.2. Request syntax
The < keygroup:delete> tag contains the following elements:
Elements Occurrence
min-max Size + remarks
<update> 1
<keygroup:update> 1
<keygroup:name> 1 normalizedString 1-50
containing characters from [a-z][0-9][-.]
<keygroup:keyData> 0-9
<keygroup:flags> 1 256 | 257 value is 256 for ZSK or 257 for KSK
<keygroup:protocol> 1 only “3” is currently accepted at EURid
<keygroup:alg> 1 3 | 5 | 6 | 7 | 8 | 10
<keygroup:pubKey> 1 A base 64 value. Any spaces in the public key will be
removed. Maximum is 1024 base64 characters.
<clTRID> 0-1 token: 3-64
Elements Description
<keygroup:name> The name for the keygroup
<keygroup:keyData> The keytag for the associated key.
<keygroup:flags> The type of the key. It can be either 256 for ZSK, or 257 for KSK.
<keygroup:protocol> The protocol value for the associated key. Standard value for EURid is 3.
<keygroup:alg> The number that represents the algorithm.
<keygroup:pubKey> The public DNSSEC key.
<cLTRID> The transaction ID for tracking the command that was provided by the
EPP client in the incoming command.
- 108 -
9.4.3. Reply syntax
Elements Description
<result code=”XXXX”> XXXX stands for the return code
<msg> Message showing the result of the nsgroup creation
<trID>
<clTRID> The transaction ID for tracking the command that was
provided by the EPP client in the incoming command.
<svTRID> The transaction ID that is provided by the server.
9.4.4. Return codes
Error cases
Result
code
<msg> <reason> Likely cause
2005 Parameter value
syntax error
Invalid keygroup name ‘somé-
keygroup’.
Not allowed character
in <keygroup:name>
2005 Parameter value
syntax error
Invalid protocol ‘4’. Only protocol ‘3’ is
accepted.
2005 Parameter value
syntax error
Invalid algorithm ‘2’. Algorithm ‘2’ is not a
valid algorithm.
2005 Parameter value
syntax error
Invalid flags ‘258’. Flag ‘258’ is not a valid
flag.
2303 Object does not
exist
Keygroup ‘some-keygroup’ does not
exist.
You cannot update a
keygroup that does
not exist.
2308 Data management
policy violation
Duplicate key with keytag ‘xxxx’. You cannot update a
keygroup where to or
more keys are
identical.
- 109 -
9.4.5. Examples
Description Command file Response file
Update keygroup remove all keys keygroup-update01-cmd.xml keygroup-update01-resp.xml
Update keygroup add 1 key keygroup-update02-cmd.xml keygroup-update02-resp.xml
Update keygroup update 1 key keygroup-update03-cmd.xml keygroup-update03-resp.xml
Update keygroup add 1 key keygroup-update04-cmd.xml keygroup-update04-resp.xml
Update keygroup remove 1 of 2
keys
keygroup-update05-cmd.xml keygroup-update05-resp.xml
- 110 -
9.5. Check keygroup
9.5.1. Purpose
The command <keygroup:check> can be used to check if a keygroups already exists. It provides a
hint that allows a client to anticipate the success or failure of provisioning a keygroup using the
<keygroup:create> command.
Please note that a check can be done on several keygroups within the same command.
9.5.2. Request syntax
The < keygroup:check> tag contains the following elements:
Elements Occurrence
min-max Size + remarks
<check> 1
<keygroup:check> 1
<keygroup:name> 1-* normalizedString 1-50
containing characters from [a-z][0-9][-.]
<clTRID> 0-1 token: 3-64
Elements Description
<keygroup:name> The name for the keygroup
<cLTRID> The transaction ID for tracking the command that was provided by the
EPP client in the incoming command.
9.5.3. Reply syntax
Elements Description
<result code=”XXXX”> XXXX stands for the return code
<msg> Message showing the result of the nsgroup creation
<resdata>
<keygroup:chkData>
<keygroup:cd>
<keygroup:name avail=”X”> This tag shows the availability of the queried
keygroup.
The “X” in the tag can have two possible values:
“false”: meaning that the keygroup is not
available
“true”: meaning that the keygroup is available
for registration
- 111 -
<keygroup:reason> If the queried keygroup is not available, this tag will
also be present and showing the reason why it is not
available.
Possible reasons are:
In use
Invalid keygroup name when the queried
keygroup name contains a character that is
not allowed.
<trID>
<clTRID> The transaction ID for tracking the command that was
provided by the EPP client in the incoming command.
<svTRID> The transaction ID that is provided by the server.
9.5.4. Return codes
There are no real error messages to be expected here, except for the error code ‘2001’ – ‘Command
syntax error.’.
9.5.5. Examples
Description Command file Response file
Checking a non-existing name
server
nsgroup-check01-cmd.xml nsgroup-check01-resp.xml
Checking some existing name
server groups
nsgroup-check02-cmd.xml nsgroup-check02-resp.xml
- 112 -
9.6. Info keygroup
9.6.1. Purpose
The command <keygroup:info> can be used to retrieve information about the current situation of an
existing keygroup.
9.6.2. Request syntax
The <keygroup:info> tag contains the following elements:
Elements Occurrence
min-max Size + remarks
<info> 1
<keygroup:info> 1
<keygroup:name> 1 normalizedString 1-50
containing characters from [a-z][0-9][-.]
<keygroup:authInfo> 0-1
<keygroup:pw> 1
<clTRID> 0-1 token: 3-64
Elements Description
<keygroup:name> The name for the keygroup
<keygroup:authInfo>
<keygroup:pw> The authorisation code needed to request information about keygroups
that are not in your portfolio.
<cLTRID> The transaction ID for tracking the command that was provided by the
EPP client in the incoming command.
9.6.3. Reply syntax
Elements Description
<result code=”XXXX”> XXXX stands for the return code
<msg> Message showing the result of the nsgroup creation
<resData>
<keygroup:infData>
<keygroup:name> The name of the keygroup.
<keygroup:keyData> The keytag of the associated key.
<keygroup:flags> The type of the key. It can be either 256 for ZSK, or
257 for KSK.
<keygroup:protocol> Only “3” is currently accepted at EURid.
<keygroup:alg> The number that represents the algorithm.
- 113 -
<keygroup:pubKey> The public DNSSEC key.
<trID>
<clTRID> The transaction ID for tracking the command that was
provided by the EPP client in the incoming command.
<svTRID> The transaction ID that is provided by the server.
9.6.4. Return codes
Error cases
Result
code
<msg> <reason> Likely cause
2005 Parameter value
syntax error
Invalid keygroup name ‘somé-
keygroup’.
Not allowed character
in <keygroup:name>
2303 Object does not
exist
Keygroup ‘some-keygroup’ does not
exist.
You cannot request
information about a
keygroup that does
not exist.
9.6.5. Examples
Description Command file Response file
Basic info keygroup command keygroup-info01-cmd.xml keygroup-info01-resp.xml
Info keygroup command with 1
key
keygroup-info02-cmd.xml keygroup-info02-resp.xml
Info keygroup command with 4
keys
keygroup-info03-cmd.xml keygroup-info03-resp.xml
Info keygroup command with 4
keys and with an authorisation
code
keygroup-info04-cmd.xml keygroup-info04-resp.xml
- 115 -
10. Poll
10.1. Purpose
To retrieve notifications from the registration system.
EURid‘s system will store all system-generated notifications in a queue and registrars can connect to
the EPP server to retrieve the messages one by one.
The EPP poll command defines two distinct operations (=ways of working):
1. The “req” (request) operation. When an EPP client sends an EPP poll command with the
‘req’ operation, the server will send a reply containing a message counter, a server-unique
message identifier and the first message/notification from the message queue. In the event
that the message queue is empty the server will reply that there are no messages pending.
2. The “ack” (acknowledgement) operation. When an EPP clients sends an EPP poll command
with the ‘ack’ operation and the server-unique ID of a previously returned message, then the
EPP server will dequeue (remove that message from the queue) (with given ID) and will
decrement the message count of the queue.
This method can be used to iterate through all pending messages.
The system makes sure that all notifications can only be acknowledged once regardless of the
chosen channel.
Please note that when you want the <resData> section to be visible in the response file,
you also need to have the following EURid-specific extURI added in the login command:
http://www.eurid.eu/xml/epp/poll-1.0.
10.2. Request syntax
The <poll> tag contains the following elements:
Elements Occurrence
min-max
Size + remarks
<poll> 1 required attrib: op="req"|"ack"; msgID required attribute when op=’ack’: token;
the value of the msgID‖ has to correspond to the value of
the ―id‖ attribute in the message that is being
acknowledged.
<clTRID> 0-1 token: 3-64
- 116 -
10.3. Reply syntax
10.3.1. Response to a ‘req’ operation
Elements Description
<result code=”XXXX”> XXXX stands for the return code
<msg>
<msgQ> attribute count (=number of messages waiting in the queue)
attribute id (the server generated unique identifier of the first message in
the queue)
<qDate> Timestamp of the moment when the event was queued.
<msg> A brief text description about the event to be notified. For information
purposes only.
<resData>
<poll:pollData>
<poll:context> The context of the event (e.g. TRANSFER, DOMAIN). The list of contexts is
defined elsewhere.
<poll:object> The specific object involved in the notified event.
<poll:action> The action that causes a significant change to the object.
<poll:code> A unique code identifying the event
<poll:detail> An optional message providing more information about the event
<trID>
<clTRID> The transaction ID for tracking the command that was provided by the
EPP client in the incoming command.
<svTRID> The transaction ID that is provided by the server.
10.3.2. Response to an ‘ack’ operation
Elements Description
<result code=”XXXX”> XXXX stands for the return code
<msg>
<msgQ> attribute count (=number of messages waiting in the queue)
attribute id (the server-generated unique identifier of the first message in
the queue)
<trID>
<clTRID> The transaction ID for tracking the command that was provided by the
EPP client in the incoming command.
<svTRID> The transaction ID that is provided by the server.
- 117 -
10.4. Return codes
Successful ‘req’ operation
Result code <msg> <reason>
1300 Command completed
successfully; no messages
N.A.
1301 Command completed
successfully; ack to dequeue
N.A.
Successful ‘ack’ operation
Result code <msg> <reason>
1000 Command completed
successfully
N.A.
1300 Command completed
successfully; no messages
N.A.
10.5. Examples
Description Command file Response file
Poll request command (case of 2
messages in queue). First
message is a "TRANSFER AWAY"
event.
poll01-req-cmd.xml poll01-req-resp.xml
Poll acknowledgement command
(1 message remaining in queue).
poll02-req-cmd.xml poll02-req-resp.xml
Poll request command (case of 1
message in queue). First message
is a “DOMAIN QUARANTINED”
event.
poll03-req-cmd.xml poll03-req-resp.xml
Poll acknowledgement command
(no more messages in queue).
poll04-req-cmd.xml poll04-req-resp.xml
Poll request command (case of an
empty queue).
poll05-req-cmd.xml poll05-req-resp.xml
- 119 -
11. Info registrars
This command can be used by registrars to retrieve current information about their registrar account
and can help them to monitor the status of their account. The information returned can, for
example, be used to predict whether certain transactions will fail due to insufficient funds or too
many hitpoints.
11.1. Purpose
The purpose of the command <registrar:info> is to obtain account information.
11.2. Request syntax
The <registrar:info> tag contains the following elements:
Elements Occurrence
min-max Size + remarks
<info> 1
<registrar:info> 1
<clTRID> 1 Token: 3-64
11.3. Reply syntax
Elements Description
<response>
<result code=”XXXX”> XXXX stands for the return code
<msg>
<resData>
<registrar:infData>
<registrar:amountAvailable> The amount of money left in your account which can be used to perform transactions on the registration system.
<registrar:hitPoints> This block contains information about the hit.
<registrar:nbrHitPoints> The current number of hit points.
<registrar:maxNbrHitPoints> The maximum number of hit points allowed.
<registrar:credits> There are two types:
“renewal” : the number of renewal credits available;
“promo”: the number of promo credits available.
- 120 -
11.4. Examples
Description Command file Response file
Example of info registrar registrar-info01-cmd.xml registrar-info01-resp.xml
- 122 -
Appendix 1: Accepted country codes for registrant contacts
AT (Austria)
BE (Belgium)
BG (Bulgaria)
CZ (Czech Republic)
CY (Cyprus)
DE (Germany)
DK (Denmark)
ES (Spain)
EE (Estonia)
FI (Finland)
FR (France)
GR (Greece)
GB (Great-Britain)
HR (Croatia)
HU (Hungary)
IE (Ireland)
IT (Italy)
LT (Lithuania)
LU (Luxemburg)
LV (Latvia)
MT (Malta)
NL (The Netherlands)
PL (Poland)
PT (Portugal)
RO (Romania)
SE (Sweden)
SK (Slovak Republic)
SI (Republic of Slovenia)
Other accepted country codes
AX (Aland Islands)
GF (French Guiana)
GI (Gibraltar)
GP (Guadeloupe)
MQ (Martinique)
RE (Reunion Island)
- 123 -
Appendix 2: Accepted language codes for registrant
contacts
bg (Bulgarian)
cs (Czech)
da (Danish)
de (German)
el (Greek)
en (English)
es (Spanish)
et (Estonian)
fi (Finnish)
fr (French)
ga (Gaelic)
hr (Croatian)
hu (Hungarian)
it (Italian)
lt (Lithuanian)
lv (Latvian)
mt (Maltese)
nl (Dutch)
pl (Polish)
pt (Portuguese)
ro (Romanian)
sk (Slovak)
sl (Slovene)
sv (Swedish)
- 124 -
Appendix 3: Index for all EPP command examples
EPP Command List of examples
Session handling
hello session_hello_samples.html
login session_login_samples.html
logout session_logout_samples.html
Contacts
create contact_create_samples.html
delete contact_delete_samples.html
update contact_update_samples.html
info contact_info_samples.html
Domains
create domain_create_samples.html
delete domain_delete_samples.html
renew domain_renew_samples.html
update domain_update_samples.html
check domain_check_samples.html
info domain_info_samples.html
Transfer domains
transfer transfer_domain_samples.html
Nameserver groups
create nsgroups_create_samples.hmtl
delete nsgroups_delete_samples.html
update nsgroups_update_samples.html
- 125 -
check nsgroups_check_samples.html
info nsgroups_info_samples.html
Keygroups
create keygroup_create_samples.html
delete keygroup_delete_samples.html
update keygroup_update_samples.html
check keygroup_check_samples.html
info keygroup_info_samples.html
Poll
poll poll_samples.html
Info registrar
info registrar info_registrar_samples.html