Technical Integration Guide

Transcription

1 TECHNICAL INTEGRATION GUIDE February 25th, Technical Integration Guide - Version February 25th,

2 TECHNICAL INTEGRATION GUIDE February 25th, Table of content 1. Preface About this document Target audience Typographical rules Revisions history IDN Reference documents Brief backgrounder on IDN technology Warning Terms and definitions Table of accepted characters Use of Unicode versions vs LDH versions EPP Configuration and parameters Major integration principles No implementation of "host" objects (RFC 5732) Cases of operations with a 1000 return code and server behavior in case of problem Auth_info management Implementation choice of the notifications list DNSSEC support Implemented commands The <greeting> The <hello> command Session management commands Interrogation commands Object Update commands Managing a domain name Create create a domain name Update modify a domain name attributes Delete Delete a domain name Restore Domain name restore Transfer Registrar change Trade Holder change (Transmission) Recover Forced domain name transmission Checking a domain availability

3 TECHNICAL INTEGRATION GUIDE February 25th, Retrieve domain data Managing a contact Contact Creation Modifying a contact Deleting a contact Identification of a contact holder Retrieve data of a contact Notifications Managing the notification queue Asynchronous notifications Exogenous notifications Return codes and error messsages Return codes Error messages RFCs Web interface : the ticket system General principles on tickets Ticket format Description of all the tickets Operations that can only be handled by /fax Authorization code generation Trade validation Notification of Monitoring of the Qualification Procedure Notification of Suspension, Blocking and Deletion of Domain Name Portfolio Substantiation DAS (Domain Availability Service) Parameters to interrogate the service The information available Validity of the domain tested domain name State of DNS publication Information on restrictions relating to this domain name Key dates on existing domain names

4 TECHNICAL INTEGRATION GUIDE February 25th, DAS and IDN Examples Domain name that does not exist and is not subject to any restrictions Domain name subject to prior review Fanciful domain name Domain name that exists and is not subject to any restrictions Deleted domain name in redemption period Existing domain name and subject to prior review Query on different domains with different IDN query in its Unicode form IDN query in its ACE form

5 TECHNICAL INTEGRATION GUIDE February 25th, Preface 1.1. About this document This integration guide contains all of the information required to implement the AFNIC domain management application interface. This interface offers two different ways accesses: Web interface, EPP (Extensible Provisioning Protocol): standard exchange protocol between a registry and its registrars. In regards to EPP, AFNIC has respected the standard described in the RFCs (see 3.8 RFCs.). This document only describes the specific points of AFNIC's implementation of the protocol Target audience This document is a technical document for developers that wish to have a detailed description of the interface and examples to help them with the integration. It does not go over the procedures again (See Procedure Manual nor The Naming Charter ( Both documents are considered as already known Typographical rules Throughout the document we write: Between < > the xml markups describing the epp requests In a blue frame, examples of EPP requests Revisions history 24/11/ V1.0 08/04/ V1.1 08/06/ V1.2 - Addition of missing EPP notifications 31/08/ V1.3 Addition of EPP notification Portfolio deletion - 5 -

6 TECHNICAL INTEGRATION GUIDE February 25th, /11/ V1.35 Optional instead Mandatory in the 5b and 5c lines in the form semantics 07/02/2011 V1.5 - Adding DNSSEC support in EPP in the server version /03/2011 V1.55 Correction of the greeting example /12/2011 V2.0 - Remove the mail interface, changes in the EPP interface following the opening to Europe and the ultra-marine country-code Top Level Domains - stop of the identification - opening of the qualification. 03/07/2012 V2.5 - Addition of the concerning the IDN and the DAS. 17/12/2012 v2.6 Remove of ZoneCheck 25/02/2013 v2.7 Remove of serverrestoreprohibited 2. IDN 2.1. Reference documents The implementation of IDNs at AFNIC is based on the IDNA2008 standard, and the following reference documents. Definitions and protocol: RFC 5890 (08/ pages): Internationalized Domain Names for Applications (IDNA): Definitions and Document Framework RFC 5891 (08/ pages): Internationalized Domain Names in Applications (IDNA): Protocol RFC 5892 (08/ pages): The Unicode Code Points and Internationalized Domain Names for Applications (IDNA) RFC 5894 (08/ pages): Internationalized Domain Names for Applications (IDNA): Background, Explanation, and Rationale Punycode encoding algorithm: RFC 3492 (03/ pages) : Punycode: A Bootstring encoding of Unicode for Internationalized Domain Names in Applications (IDNA) 2.2. Brief backgrounder on IDN technology The DNS protocol was not originally defined to be restricted to a set of characters. It is its use and other limitations of "the age" (the protocol is 30 years old) that have resulted in the definition of the syntactic rules we know today. The purpose of the IDNA2008 standard is to reconcile human needs and technical constraints by allowing the use of all forms of writing in domain names. All these forms of writing and the characters they use are defined and grouped together under a standard called Unicode. Since the syntactic rules for domain names require the use of single letters of the Latin alphabet ("a" to "z"), as well as numbers, hyphens, and periods to separate labels, a mechanism for the canonical formation of Unicode domain names and for encoding them has been developed to create names consistent with these rules. While in applications such as web browsers, Unicode names will be displayed, their DNS resolution will be performed using their encoded form (this is normally transparent to the user who should not have to handle this type of domain name)

7 TECHNICAL INTEGRATION GUIDE February 25th, Warning Although its impact may seem small, it is important to note that AFNIC implements the IDNA2008 standard, which slightly differs from the IDNA2003 standard. With respect to the processing of the characters included, the German Eszett (ß) is encoded, not transformed into "ss" as in the previous version of the IDN standard. In addition, the canonicalization step (nameprep) has disappeared, which will have some impact on the use of our interfaces. Each AFNIC application is now free to apply its own rules in this respect. Besides the fact that Unicode domain names must be in Normal Form C, we have chosen to allow the entry of capitals (to ensure backward compatibility with current uses) but their lower-case equivalents will actually be taken into account by the system (note that the Eszett is only accepted in its lower-case form). For example, the domain name "Thé-ou-Café.fr" is not legal in accordance with the IDNA2008 standard. We shall accept it, however once it has been standardized as "thé-ou-café.fr". With more "exotic" alphabets than the Latin, the problem will no doubt be more complex, but as long as AFNIC continues to use the characters indicated in the list below in this document, their canonical form will continue to apply Terms and definitions Unicode: Standard enabling any character in any form of writing to be encoded in a unique fashion (Unicode on Wikipedia). UTF-8: One of the encoding formats used to encode Unicode characters. ISO : One of the ISO 8-bit encoding standards of the Latin alphabet. Also known as latin9. LatinX: Other names of certain ISO standards. Unlike Latin1, Latin9 includes the ligation "e in o". LDH: "LETTER-DIGIT-HYPHEN" the only ASCII characters authorized for the composition of a label in a domain name. ASCII: "American Standard Code for Information Interchange", the oldest computer standard for encoding characters. Strictly speaking 7-bit, it can only encode 128 characters. ACE: "ASCII Compatible Encoding" is the encoded version of a domain name in its LDH form (xn-caf-dma in Punycode, i.e. its "A-label form"). IDN: "Internationalized Domain Name", containing characters other than ASCII characters alone. Canonicalization: The canonical formation of a string of characters. For example, in Latin, putting a string of characters in their lower-case form is one of the operations that can be involved in a canonicalization process. Normal Form C: Normal form requiring that the characters be (pre)composed. A character corresponds to a unique code point. This exclude characters obtained by using diacritical marks combined with base characters. Code point: Single index associated with a character. Glyph: Graphical representation of a character - 7 -

8 TECHNICAL INTEGRATION GUIDE February 25th, NAMEPREP: Defines the version in canonical form of a Unicode domain name (was part of IDNA2003, no longer exists in IDNA2008). Punycode: Reversible and unique algorithm, used to transform a canonicalized IDN into its ACE form Table of accepted characters The following table represents the set of characters may be used to compose the label of a domain name. Historically, only the first 37 characters in this table were allowed, but as of May 3, 2012, it will be possible to use 30 new characters in the composition of the labels of domain names. The "ASCII equivalent" column is special in that it will only be meaningful during the sunrise period (note that sometimes the ASCII equivalent of a Unicode character is a group of two characters). This will be detailed a little later in this document. # Code point Glyph Name ASCII equivalent 1 U+002D - HYPHEN-MINUS SIGN - 2 U DIGIT ZERO 0 3 U DIGIT ONE 1 4 U DIGIT TWO 2 5 U DIGIT THREE 3 6 U DIGIT FOUR 4 7 U DIGIT FIVE 5 8 U DIGIT SIX 6 9 U DIGIT SEVEN 7 10 U DIGIT EIGHT 8 11 U DIGIT NINE 9 12 U+0061 a LATIN SMALL LETTER A a 13 U+0062 b LATIN SMALL LETTER B b 14 U+0063 c LATIN SMALL LETTER C c 15 U+0064 d LATIN SMALL LETTER D d 16 U+0065 e LATIN SMALL LETTER E e 17 U+0066 f LATIN SMALL LETTER F f 18 U+0067 g LATIN SMALL LETTER G g 19 U+0068 h LATIN SMALL LETTER H h 20 U+0069 i LATIN SMALL LETTER I i 21 U+006A j LATIN SMALL LETTER J j 22 U+006B k LATIN SMALL LETTER K k 23 U+006C l LATIN SMALL LETTER L l 24 U+006D m LATIN SMALL LETTER M m 25 U+006E n LATIN SMALL LETTER N n 26 U+006F o LATIN SMALL LETTER O o 27 U+0070 p LATIN SMALL LETTER P p - 8 -

9 TECHNICAL INTEGRATION GUIDE February 25th, U+0071 q LATIN SMALL LETTER Q q 29 U+0072 r LATIN SMALL LETTER R r 30 U+0073 s LATIN SMALL LETTER S s 31 U+0074 t LATIN SMALL LETTER T t 32 U+0075 u LATIN SMALL LETTER U u 33 U+0076 v LATIN SMALL LETTER V v 34 U+0077 w LATIN SMALL LETTER W w 35 U+0078 x LATIN SMALL LETTER X x 36 U+0079 y LATIN SMALL LETTER Y y 37 U+007A z LATIN SMALL LETTER Z z 38 U+00DF ß LATIN SMALL LETTER SHARP S ss 39 U+00E0 à LATIN SMALL LETTER A WITH GRAVE a 40 U+00E1 á LATIN SMALL LETTER A WITH ACUTE a 41 U+00E2 â LATIN SMALL LETTER A WITH CIRCUMFLEX a 42 U+00E3 ã LATIN SMALL LETTER A WITH TILDE a 43 U+00E4 ä LATIN SMALL LETTER A WITH DIAERESIS a 44 U+00E5 å LATIN SMALL LETTER A WITH RING ABOVE a 45 U+00E6 æ LATIN SMALL LETTER AE ae 46 U+00E7 ç LATIN SMALL LETTER C WITH CEDILLA c 47 U+00E8 è LATIN SMALL LETTER E WITH GRAVE e 48 U+00E9 é LATIN SMALL LETTER E WITH ACUTE e 49 U+00EA ê LATIN SMALL LETTER E WITH CIRCUMFLEX e 50 U+00EB ë LATIN SMALL LETTER E WITH DIAERESIS e 51 U+00EC ì LATIN SMALL LETTER I WITH GRAVE i 52 U+00ED í LATIN SMALL LETTER I WITH ACUTE i 53 U+00EE î LATIN SMALL LETTER I WITH CIRCUMFLEX i 54 U+00EF ï LATIN SMALL LETTER I WITH DIAERESIS i 55 U+00F1 ñ LATIN SMALL LETTER N WITH TILDE n 56 U+00F2 ò LATIN SMALL LETTER O WITH GRAVE o 57 U+00F3 ó LATIN SMALL LETTER O WITH ACUTE o 58 U+00F4 ô LATIN SMALL LETTER O WITH CIRCUMFLEX o 59 U+00F5 õ LATIN SMALL LETTER O WITH TILDE o 60 U+00F6 ö LATIN SMALL LETTER O WITH DIAERESIS o 61 U+00F9 ù LATIN SMALL LETTER U WITH GRAVE u 62 U+00FA ú LATIN SMALL LETTER U WITH ACUTE u 63 U+00FB û LATIN SMALL LETTER U WITH CIRCUMFLEX u 64 U+00FC ü LATIN SMALL LETTER U WITH DIAERESIS u 65 U+00FD ý LATIN SMALL LETTER Y WITH ACUTE y 66 U+00FF ÿ LATIN SMALL LETTER Y WITH DIAERESIS y 67 U+0153 œ LATIN SMALL LIGATURE OE oe - 9 -

10 TECHNICAL INTEGRATION GUIDE February 25th, Use of Unicode versions vs LDH versions Domain names are present in the server names, in the URL, and in the addresses: here are the forms accepted by AFNIC interfaces. Detailed error messages will be returned in cases of non-compliance with these rules. Domain name: EPP interface: the only acceptable form for domain names is the LDH form, i.e. the ACE version for IDNs. Web interface: Unicode version and LDH version are accepted. Server name: ONLY the LDH version is acceptable. URL: ONLY the LDH version is acceptable. ONLY the LDH version is acceptable. 3. EPP 3.1. Configuration and parameters EPP production bed : epp.nic.fr port : 700 access authentified by a certificate number of connexions available : 2 IP adresses that can access the server : 2 available accounts : 1 EPP test bed : epp.sandbox.nic.fr port : 700 access authentified by a certificate number of connexions available : 4 IP adresses that can access the server : unlimited available accounts : Major integration principles Besides the EPP standard as described in the RFCs, AFNIC has added several integration principles that are good to be aware of before developing an EPP client No implementation of "host" objects (RFC 5732) As this concept is rather remote from the way AFNIC manages name servers, we have chosen that the name servers should be domain name attributes Cases of operations with a 1000 return code and server behavior in case of problem

11 TECHNICAL INTEGRATION GUIDE February 25th, A precaution is necessary during the development of clients that connect to our EPP server. Indeed, we indicate several times in the following pages that some operations will answer with a 1000 return code. This behavior is expected in normal working conditions of the domain registration chain. We differenciate between minor, major and blocking problems. A minor problem represents a problem on the chain that does not affect the good reception of the requests. The chain is then asynchronous until the problem is solved. Any operation affected by the problem will exceptionally answer with a 1001 return code during that time and notifications will be issued. For a minor problem, operations on «contact» objects, notification queues consultations and EPP operations like «querry» will not be affected. In case of a blocking problem, the server reacts in a more radical way and no operations like «transform» on domain names can be taken into account. An error message «command failed» (code 2400) is then returned for any new command Auth_info management The EPP protocol allows the use of an auth_info for domain names that are used for transfer operations (registrar change). The operations described hereafter allow the registrars to use our EPP server to retrieve the auth_info codes of their complete domain portfolio and modify them if necessary. In addition, as the use of this auth_info code is mandatory for any registrar change, a rule forces the registrar in charge of the domain name to give it to the domain holder. Each registrar is free to choose the best way to issue this information to the holder Implementation choice of the notifications list We have chosen to indicate during any server answer the number of messages in the queue (unless there is none, in which case this information does not appear). RFC 5730 obliges to communicate this information only in the cases of answers to the <poll> commands and makes it optional for any other type of commands. In concrete terms, this implies that as soon as a message is notified to a registrar, the registrar is informed by the presence of the <msgq> element in any answer to commands sent to the server. It is strongly advised to read these messages as they arrive, they may contain operation follow-ups, technical modifications or transfer request you might find interesting to answer DNSSEC support The EPP server manages the secdns-1.1 extention as described in RFC 5910, excluding any other versions. Implementation specifications are as follows:

12 TECHNICAL INTEGRATION GUIDE February 25th, The server only supports «the DS data interface» (<secdns:dsdata>), section 4.1 of RFC 5910, without information on the associated key (no <secdns:keydata> element) ; the presence of information on the key will generate a 2102 error code. In the same way as for name servers, DNSSEC elements are only accepted during an update[tech] operation. Their presence during a create operation will generate a 2103 error code. A domain name can have up to 6 associated DS records: the number of elements <secdns:dsdata> present in the section <secdns:add> during an update[tech] operation is therefore limited to have the domain's final status with no more than 6 DS records. The maxsiglife element is not supported, it presence inside a client request will generate a 2102 error code. The urgent attribute is not supported, it presence inside a client request will generate a 2102 error code. During a transfer operation, the AFNIC extension frnic-1.2 must necessarily include a keepds flag which is a boolean: if its value is 1, actual DS records for the domain name are maintained after the transfer if already present, if its value is 0 in case of a successful transfer any existing DS record will be deleted. Trade and recover operations work the same way as the transfer described above

13 TECHNICAL INTEGRATION GUIDE February 25th, Implemented commands The <greeting> The <greeting> is not a command the client can send to the EPP server, but it is the welcome banner it will send when a connexion is made. It is also the answer sent in response to a <hello> command (this command is detailed in the next section). Why detail this banner if it is not a command? Simply because the information it gives out is important and necessary for the <login> command. Even though the <greeting> reproduced here is only given as an example and the detail of its content can be found in the RFC 5730, two pieces of information are of importance: the versions of the supported protocol (<version> element) and the accepted languages (<lang> element). Only one choice, among those values, will be accepted during the session establishment with the <login> command. <greeting> example that can be sent by the AFNIC EPP server: S:<?xml version="1.0" encoding="utf-8" standalone="no"?> S:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> S: <greeting> S: <svid>epp PROD Server on nergal.nic.fr (V1.1.0)<svID> S: <svdate> t12:34:56.0z</svdate> S: <svcmenu> S: <version>1.0</version> S: <lang>en</lang> S: <objuri>urn:ietf:params:xml:ns:contact-1.0</objuri> S: <objuri>urn:ietf:params:xml:ns:domain-1.0</objuri> S: <svcextension> S: <exturi>urn:ietf:params:xml:ns:rgp-1.0</exturi> S: <exturi> S: <exturi>urn:ietf:params:xml:ns:secdns-1.1</exturi> S: </svcextension> S: </svcmenu> S: <dcp> S: <access><all/></access> S: <statement> S: <purpose><admin/><prov/></purpose> S: <recipient><ours/><public/></recipient> S: <retention><stated/></retention> S: </statement> S: </dcp> S: </greeting> S:</epp>

14 TECHNICAL INTEGRATION GUIDE February 25th, The <hello> command Even though it is not an EPP command strictly speaking, this command is particularly important and usefull as it will allow an EPP client to check if the connection with the server is correctly established. Indeed, as soon as a connection is established with the server, it is possible, at any moment, to send this command to the server that will answer with an EPP welcome banner (the <greeting>), even if the authentication (<login>) phase is not completed. In the event the time-out mecanisms should be activated (for more details refer to the document Technical policies of the Registry underway) to end «inactive» sessions, it is very possible to send a «heartbeat» by regularly making this command in order to maintain sessions that are less used (of course, the frequency of this «heartbeat» shall remain reasonable, in view of the «time-out» and rate-limiting parameters eventually put in place). For example, we can imagine this command being executed every 2 minutes to maintain an open connection and check that the server is responding as being an acceptable frequency. Example of request sent by the client: C:<?xml version="1.0" encoding="utf-8" standalone="no"?> C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> C: <hello/> C:</epp> Session management commands The EPP protocol offers 2 commands that allow to establish (<login>) and end a session with the server (<logout>). Once the session is opened, it will only end at the client's request (<logout>) or if the server should, for internal reasons, end it («time-out» on an inactive session, technical problem,...) or if the customer interrupts the TCP connection (if this interruption is done within the normal framework of the client use, it is strongly recommended to use a <logout> before cutting off the TCP connection). As the number of simultaneous sessions can be limited it must be meticulously managed The <login> command During the server connection, the server sends a (<greeting>) banner to the client indicating by doing so that it is ready to receive a command to establish a session. This command requires the EPP login generated by AFNIC for each registrar and the associated password (it has been decided, for safety reasons and partitioning of the different AFNIC interfaces, to create new logins, without any link with those already existing). If those are

15 TECHNICAL INTEGRATION GUIDE February 25th, correctly indicated and if the number of sessions currently opened does not exceed the maximum allowed number, the session should normally be established. The <login> command also offers the possibility to modify the password associated with this login. There is no limitation for this use and it is even strongly recommended to change it during the first session opening on the EPP server. <login> command example sent by a client: C:<?xml version="1.0" encoding="utf-8" standalone="no"?> C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> C: <command> C: <login> C: <clid>-kiffucol911-.fr</clid> C: <pw>toto1</pw> C: <newpw>toto2</newpw> C: <options> C: <version>1.0</version> C: <lang>en</lang> C: </options> C: <svcs> C: <objuri>urn:ietf:params:xml:ns:contact-1.0</objuri> C: <objuri>urn:ietf:params:xml:ns:domain-1.0</objuri> C: <svcextension> C: <exturi>urn:ietf:params:xml:ns:rgp-1.0</exturi> C: <exturi> C: </svcextension> C: </svcs> C: </login> C: <cltrid>une-reference-client-par-exemple</cltrid> C: </command> C:</epp> The result for this command will be the opening of a session for the registrar with the EPP login «kiffucol911-.fr», the password «toto1», and that decides for security reasons to change it with «toto2» (of course, it is this new password that will need to be used upon the next session establishment, as the change is taken into account right away) Strict authentification A strict check is made to ensure that during each session all the EPP extensions used have been indicated by the client during its authentication at the start of the session. If a new extension appears in a command, it will be rejected. That thus means that it is at least necessary to announce explicitly: The frnic-1.2 extension for operations on contacts and certain operations on domain names such as transfer, trade, recover, etc

16 TECHNICAL INTEGRATION GUIDE February 25th, the rgp-1.0 extension in order to restore a domain name and possibly the secdns-1.1 extension if you want to manage DNSSEC. A strict check is made to ensure that the EPP extensions chosen by the customer at the time of authentication are among the EPP extensions announced by the server; The presence of any other "exotic" extension (not announced by the server in the <greeting>) will result in a failed authentication, as will the absence of any mandatory extension. The combination of these two tests imposes you to authenticate with one of the following combinations: domain-1.0, contact-1.0, frnic-1.2, rgp-1.0 or domain-1.0, contact-1.0, frnic-1.2, rgp-1.0, secdns The <logout> command As already indicated, a client that wishes to have a clean EPP session management must send an end of session command (<logout>) (and, ideally, wait for a server answer) before cutting the TCP connection with the server. Even though the server can detect «wild» EPP client cut-offs, these types may not free the limited ressources allocated to each registrar quickly enough. To be totally clear, if we only authorize, for each registrar, X number of simultaneous sessions with the EPP server (cf 3.1 Configuration and parameters), and that all of these sessions are all used at the same time, disconnecting a client without a <logout> phase could have for consequence that the cut-off will not be taken immediatly into account. This will then block any new connections returning the code 2502 until the system detects and manages this cut-off. <logout> command example sent by a client: C:<?xml version="1.0" encoding="utf-8" standalone="no"?> C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> C: <command> C: <logout/> C: <cltrid>une-reference-client-par-exemple</cltrid> C: </command> C:</epp>

17 TECHNICAL INTEGRATION GUIDE February 25th, Interrogation commands Even though we detail the commands for the different types of objects (contact and domain) in the following chapters, here is a brief outline of what commands are available and the use they have been intended to The <check> command This command enables to check if an object is available. Considering our internal way of managing «contacts», namely, an internal algorythm that determines the identifier (Nic-handle) that will be associated to a «contact» object, the <check> command can only be used on «domain» objects. Before any domain creation, it is strongly recommended to check availability. It is strongly recommended to use the DAS service (Domain Availability System) IRIS D-CHK. Cf 6. DAS. The DAS service is to be preferred to the EPP command The <info> command When you wish to retrieve information on a domain name or a contact for which you know the identifier, you need to use this command. A registrar can only retrieve information on contacts linked to objects in his portfolio. For domain names it is possible, if the associated password (<authinfo> element) is known, to retrieve information on a domain name maintained by another registrar (this password is given by the holder during the <transfer> operation among others). It is important to note that this command should only be used to retrieve information on objects and not used to check their availability for instance. This function is available through the <check> command. Example for a IDN: C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0" xmlns:xsi=" xsi:schemalocation="urn:ietf:params:xml:ns:epp-1.0 epp-1.0.xsd"> C: <command> C: <info> C: <domain:info xmlns:domain="urn:ietf:params:xml:ns:domain-1.0" xsi:schemalocation="urn:ietf:params:xml:ns:domain-1.0 domain-1.0.xsd"> C: <domain:name hosts="all">xn--strae-42-tya.fr</domain:name> C: </domain:info> C: </info> C: <cltrid>pasterriblecommesecret666</cltrid> C: </command> C:</epp>

18 TECHNICAL INTEGRATION GUIDE February 25th, Example of answer sent by the server: S:<?xml version="1.0" encoding="utf-8" standalone="yes"?> S:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0" xmlns:xsi=" xsi:schemalocation="urn:ietf:params:xml:ns:epp-1.0 epp-1.0.xsd"> S: <response> S: <result code="1000"> S: <msg>command completed successfully</msg> S: </result> S: <resdata> S: <domain:infdata xmlns:domain="urn:ietf:params:xml:ns:domain-1.0"> S: <domain:name>xn--strae-42-tya.fr</domain:name> S: <domain:roid>dom frnic</domain:roid> S: <domain:status s="inactive"/> S: <domain:registrant>tgca108</domain:registrant> S: <domain:contact type="admin">tgca108</domain:contact> S: <domain:contact type="tech">vl0</domain:contact> S: <domain:clid>-naqjanir485-.fr</domain:clid> S: <domain:crdate> t13:16:24.0z</domain:crdate> S: <domain:exdate> t00:00:00.0z</domain:exdate> S: <domain:update> t13:16:24.0z</domain:update> S: <domain:authinfo> S: <domain:pw>idn2012</domain:pw> S: </domain:authinfo> S: </domain:infdata> S: </resdata> S: <trid> S: <cltrid>pasterriblecommesecret666</cltrid> S: <svtrid>dev-vraiton </svtrid> S: </trid> S: </response> S:</epp> The <poll> command During the different operations on the objects of a registrar's portfolio, notification messages will need to be sent to him. These messages will be set in a queue that can be read with the <poll> command. A few examples can be found further down, but here is how this notification message queue works. Each time an information linked to an operation (for which a specific message exists) must be sent it is added in a message queue. As soon as the messages are ready to be read, the information is indicated in the server's answer to commands (<msgq> element indicated). The <poll> command retrieves the oldest message in the queue. In order to delete this message from the queue the command must be used again with the message number corresponding to the one just read (the detailed procedure can be found in RFC 5730) Object Update commands These commands are all detailed further down, it is strongly advised to read the following RFCs: 5730 (commands presentation), 5731 (specificities on «domain» objects), 5732 (specificities on «contact» objects) as well as the 5910 (DNSSEC specificities)

19 TECHNICAL INTEGRATION GUIDE February 25th, Here is an exhaustive list: <domain:create> <domain:update> <domain:delete> <domain:transfer> <frnic:trade> and <frnic:recover> (domain operation with the use of an extention) <contact:create> <contact:update> 3.4. Managing a domain name Create create a domain name The EPP protocol (RFC 5730) allows domain name creation (RFC 5731). It is important to distinguish to types of creations, each one having its own specificity. The first type of creation, we will qualify of «direct», must be used for a standard domain name creation (see The AFNIC Naming Charter ) The second type of creation, we will qualify as «creation with authorization code», must be used for domain name creations under conditions (see The AFNIC Naming Charter) "Direct" domain name creation This case represents 99,99% of creation operations and does not require much information. As for the nic-handles, from an EPP point of view, XX12345-FRNIC is a ROID (Repository Object Identifier) and is not supposed to be used as a reference for «contact» objects. A «contact» object is only referenced with the left hand side of the the nic-handle, meaning without the " -FRNIC"

20 TECHNICAL INTEGRATION GUIDE February 25th, Here are the elements that must be indicated in the command and a brief decription. If some of these elements are missing or if others are added an error will be returned. Element Name Number of occurrences <domain:name> 1 <domain:period> < <domain:registrant> d <domain:contact o type="admin"> 1 <domain:contact m type="tech"> 1-3 <domain:authinfo> a 1 i<domain:pw> 1 <cltrid> n 0-1 <domain:name> contains the complete domain name (example-dnepp.fr). <domain:period> not used at this time as domain names are tacitly renewed. It has been decided not to return an error when indicated but to only accept two precise values: Either <domain:period unit="y">1</domain:period> Either <domain:period unit="m">12</domain:period> <domain:registrant> contains the holder identifier deduced from its nic-handle from which the suffix (FRNIC) has been removed as well as the separator character "-". <domain:contact type="admin"> contains the admin contact identifier. <domain:contact type="tech"> contains the technical contact identitifier. <domain:authinfo> contains the auth_info the registrar has chosen to associate to this domain name. In the case of a creation «with an authorization code», this auth_info is imposed. At this time a mechanism other than the password (<domain:pw>) is not scheduled. As this password is free, it is strongly recommended to associate different auth_info for each domain name. It is also impossible to use the «roid» attribute. For no ambiguity, using it will return an error. <cltrid> is optional. It is strongly advised to indicate this field for a better follow up of commands and if necessary for search requests and EPP clients «troubleshooting» operations

21 TECHNICAL INTEGRATION GUIDE February 25th, Example of a request sent by the client: C:<?xml version="1.0" encoding="utf-8" standalone="no"?> C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> C: <command> C: <create> C: <domain:create C: xmlns:domain="urn:ietf:params:xml:ns:domain-1.0"> C: <domain:name>ndd-de-test-0001.fr</domain:name> C: <domain:period unit="y">1</domain:period> C: <domain:registrant>mm4567</domain:registrant> C: <domain:contact type="admin">nfc1</domain:contact> C: <domain:contact type="tech">nfc1</domain:contact> C: <domain:contact type="tech">vil1666</domain:contact> C: <domain:authinfo> C: <domain:pw>warlordz666</domain:pw> C: </domain:authinfo> C: </domain:create> C: </create> C: <cltrid>une-reference-client-par-exemple</cltrid> C: </command> C:</epp> In this context of a «simple» creation, if all the naming and syntax rules are respected and if the domain name is available, the server answers with a 1000 return code. More precisely, in case of a successfull domain creation, the only return code possible is There cannot be a 1001 return code for this type of creation unless there is a minor or major problem. Note that, in the server answer, are indicated the domain name creation and expiration dates (<domain:crdate> and <domain:exdate>), the latter being indicated to remain coherent with the <domain:period> element when it is indicated by the client. Example of answer sent by the server: S:<?xml version="1.0" encoding="utf-8" standalone="no"?> S:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> S: <response> S: <result code="1000"> S: <msg>command completed successfully</msg> S: </result> S: <resdata> S: <domain:credata S: xmlns:domain="urn:ietf:params:xml:ns:domain-1.0"> S: <domain:name>ndd-de-test-0001.fr</domain:name> S: <domain:crdate> t00:00:00.0z</domain:crdate> S: <domain:exdate> t00:00:00.0z</domain:exdate> S: </domain:credata> S: </resdata> S: <trid> S: <cltrid>une-reference-client-par-exemple</cltrid> S: <svtrid>frnic </svtrid> S: </trid> S: </response> S:</epp>

22 TECHNICAL INTEGRATION GUIDE February 25th, Example of answer sent by the server (1001 return code): S:<?xml version="1.0" encoding="utf-8" standalone="yes"?> S:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> S: <response> S: <result code="1001"> S: <msg>command completed successfully; action pending</msg> S: </result> S: <resdata> S: <domain:credata S: xmlns:domain="urn:ietf:params:xml:ns:domain-1.0"> S: <domain:name>dom-epp-wytxubuz.fr</domain:name> S: <domain:crdate> t15:22:15.0z</domain:crdate> S: <domain:exdate> t00:00:00.0z</domain:exdate> S: </domain:credata> S: </resdata> S: <trid> S: <cltrid>frnic client </cltrid> S: <svtrid>dev-photon </svtrid> S: </trid> S: </response> S:</epp> Domain name creation "with an authorization code" Such an operation requires an authorization code (see. Procedure Manual ). Reminder: this code is associated to three informations (the registrar, the domain name and the holder nic-handle). Once the code is created, the domain name creation is done almost in the same way as described during the «direct» creation except for two details. The first is that the holder identifier is not free and must correspond to the one associated to the authorization code, the second is that the authorization code must be used instead of the auth_info in the <domain:authinfo> element as it is not free. On the other hand it is mandatory to change it with the <domain:update> command before giving it to the final holder. Please note that this does not change the rest of the request and that it is handled under the same rules as the previous case. Meaning that a successfull registration will generate an answer with the return code 1000 (this is the reason why the server answer is not reproduced)

23 TECHNICAL INTEGRATION GUIDE February 25th, Example of a request sent by the client: C:<?xml version="1.0" encoding="utf-8" standalone="no"?> C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> C: <command> C: <create> C: <domain:create C: xmlns:domain="urn:ietf:params:xml:ns:domain-1.0"> C: <domain:name>ndd-reserve-0001.fr</domain:name> C: <domain:period unit="m">12</domain:period> C: <domain:registrant>mm4567</domain:registrant> C: <domain:contact type="admin">nfc1</domain:contact> C: <domain:contact type="tech">nfc1</domain:contact> C: <domain:contact type="tech">vil1666</domain:contact> C: <domain:authinfo> C: <domain:pw>ndcr t </domain:pw> C: </domain:authinfo> C: </domain:create> C: </create> C: <cltrid>une-reference-client-par-exemple</cltrid> C: </command> C:</epp> After the creation Once the domain is created, it can be available for consultation with the <domain:info> command and visible in the Whois (an additional propagation delay is possible because of the way our database replication architecture is done, but in the best conditions, data synchronisation is done in near real time). Eventhough the qualification (see Procedure Manual) process is done on the holder, its progress can impact the status of the domain name once it is created. Indeed, if the holder is in phase of request for supporting documents, the domain name will be in suspending status then blocking status which will change the EPP status

24 TECHNICAL INTEGRATION GUIDE February 25th, Summary table of the operations accepted according to the state of the qualification process: State of the qualification process Whois: reachstatus Whois: eligstatus Operations denied Domain status start pending pending contact:update - problem (suspended) ok/- ok/- contact:update domain:trade domain:transfer contact:update servertransferprohibited + servertradeprohibited problem (blocked) ok/- ok/- domain:trade domain:transfer domain:restore domain:delete domain:update domain:create finished ok/- ok/- aucune - serverhold + serverupdateprohibited + serverdeleteprohibited + servertransferprohibited + servertradeprohibited Update modify a domain name attributes We have chosen to define 3 types of very distinct modifications with the same EPP command: <domain:update>. In case the modification concerns the contacts associated to a domain name (technical and/or adminstrative), or only the DNS configuration or only on the domain name status and its associated auth_info Update [admin] Contact list modification The modification of the contact list associated to a domain name, whether technical and/or administrative, must be requested with a <domain:update> command. Eventhough EPP and the domain mapping allows the domain holder change with this command, we do not authorize this action. A domain holder change is done with the <domain:trade> and <domain:recover> commands that we will detail later on in this document. It is important to keep in mind that modifications on contact lists cannot overstep the rules of occurrences indicated in the domain name creation section. Indeed, as the <domain:update> command allows the use of two sub-commands <domain:add> and <domain:rem>, any deletion of a contact that leads to the deletion of that type of contact for the domain name must contain the addition of another contact of the same type. For instance, the actual rule that limits to one the number of administrative contacts for a

25 TECHNICAL INTEGRATION GUIDE February 25th, domain name is translated during its modification by the deletion of the actual contact and the addition of a new one, within the same EPP command (the example given further down will go over this case). Each element <domain:add> and <domain:rem> can contain <domain:contact> elements (already described in the «domain name creation» section). If the same contact is contained both in <domain:add> and <domain:rem>, the command is accepted, both operations will cancel themselves and the other modifications requested in the command will be taken into account normally. In concrete terms, a command that indicates the addition of technical contacts VIL1666 and MIS78 as well as the deletion of the technical contact VIL1666 equals a command that would only contain the addition of the technical contact MIS78. If we stay on the example of the domain we created above and add a third technical contact and change the administrative contact, here is the XML request that is sent. C:<?xml version="1.0" encoding="utf-8" standalone="no"?> C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> C: <command> C: <update> C: <domain:update C: xmlns:domain="urn:ietf:params:xml:ns:domain-1.0"> C: <domain:name>ndd-de-test-0001.fr</domain:name> C: <domain:add> C: <domain:contact type="admin">vil1666</domain:contact> C: <domain:contact type="tech">jap777</domain:contact> C: </domain:add> C: <domain:rem> C: <domain:contact type="admin">nfc1</domain:contact> C: </domain:rem> C: </domain:update> C: </update> C: <cltrid>une-reference-client-par-exemple</cltrid> C: </command> C:</epp>

26 TECHNICAL INTEGRATION GUIDE February 25th, Example of an answer given by the server (for this type of command, the return code is 1000 unless there is a minor or major problem): S:<?xml version="1.0" encoding="utf-8" standalone="no"?> S:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> S: <response> S: <result code="1000"> S: <msg>command completed successfully</msg> S: </result> S: <trid> S: <cltrid>une-reference-client-par-exemple</cltrid> S: <svtrid>frnic </svtrid> S: </trid> S: </response> S:</epp> Example of answer in case of code return 1001: S:<?xml version="1.0" encoding="utf-8" standalone="no"?> S:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0">s: <response> S: <result code="1001"> S: <msg>command completed successfully; action pending</msg> S: </result> S: <msgq count="1" id="63480"/> S: <trid> S: <cltrid>une-reference-client-par-exemple</cltrid> S: <svtrid>frnic </svtrid> S: </trid> S: </response> S:</epp> Update [tech] Name server configuration modification The command is used to indicate an initial DNS configuration for a domain name that doesn't have any yet or to change an existing DNS configuration. By modification, we also mean the pure and simple deletion of the domain's name server list in order to have the possibility to reserve a domain name without any DNS publication. This command is also used to add or delete signed delegations (DS records). The command is sent by the client (to simplify, we consider this command to be syntactically correct and that the necessary glues are present), the format we have chosen for the name servers is the one where they are attributes of the «domain» object and not as references on «host» objects (RFC 5732). When the command is handled, the server answers with a return code The configuration is directly visible in the Whois and can be published during the next DNS zone file reload (unless the status "clienthold" or "serverhold" is indicated which prevents the DNS publication)

27 TECHNICAL INTEGRATION GUIDE February 25th, IMPORTANT: The DNS configuration does not distinguish a server as being the primary or the others as being secondaries. This means the order of the servers has no importance. Even though they are usually returned according to the same order (via the Whois or via the answer to a command <domain:info>), there are no priority rules behind this order. The <domain:update> command can only contain the elements <domain:add> and/or <domain:rem>. The first contains the information necessary to add one or several name servers to the existing configuration, the second one to delete one or several name servers. The modification of a name server to update it glue has to be present in <domain:rem> (just the name server) and in <domain:add> (with the new glue to apply). As a reminder, we have not implemented RFC 5732, on objects of type "host" that allow to reference the name servers. We prefer to use the possibility to describe the name servers as attributes of the «domain» objects. Each of the <domain:add> and <domain:rem> elements can only contain the single element <domain:ns>, any other element present that could be confusing as to which type of modification is requested will lead to an error. In addition, each <domain:ns> element is only composed of a one single collection of <domain:hostattr> elements. Here are the sub-elements that are present in the <domain:hostattr> element and their brief description. The absence of mandatory elements and/or presence of other elements will return an error. Element name Number of occurences <domain:hostname> 1 <domain:hostaddr ip="v4"> 0-n <domain:hostaddr ip="v6"> 0-n <domain:hostname> contains the complete domain name of the name server. <domain:hostaddr ip="v4"> contains an Ipv4 address to associate to the name server when a glue is necessary (only for <domain:add>, forbidden for <domain:rem>). <domain:hostaddr ip="v6"> contains an Ipv6 address to associate to the name server when a glue is necessary (only for <domain:add>, forbidden for <domain:rem>). If the presence of a glue is necessary, it is not mandatory to indicate ipv4 and ipv6 addresses. One address, whatever its type, is sufficient (but several can be indicated). The command can be associated to a <secdns:update> extension if DNSSEC operations are wanted and that the secdns extension was chosen

28 TECHNICAL INTEGRATION GUIDE February 25th, by the client during connection. In that case the extension will need to contain a <secdns:rem> element and/or a <secdns:add> element. The <secdns:rem> element contains either the <secdns:all> element alone (if present with the value 1 it will delete all DS records linked to the domain name) either one or several <secdns:dsdata> elements. The <secdns:add> element contains one or more <secdns:dsdata> elements. Each <secdns:dsdata> element is composed of the following subelements: Element name Number of occurences <secdns:keytag> 1 <secdns:alg> 1 <secdns:digesttype> 1 <secdns:digest> 1 We would like to remind you that according to RFC 5910 order is important, as the content of element <secdns:rem> is taken into account before the content of element <secdns:add>. The "urgent" attribute in the <secdns:update> element is not accepted, its presence with a value set ot 1 will generate a 2102 error code. The <secdns:chg> element under <secdns:update> is not accepted either because the only sub-element allowed under <secdns:chg> is <secdns:maxsiglife> which is not supported. The presence of the <secdns:chg> element will generate a 2102 error code

29 TECHNICAL INTEGRATION GUIDE February 25th, Example of a request sent by the client after a creation to indicate the initial configuration for a domain name: C:<?xml version="1.0" encoding="utf-8" standalone="no"?> C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> C: <command> C: <update> C: <domain:update C: xmlns:domain="urn:ietf:params:xml:ns:domain-1.0"> C: <domain:name>ndd-de-test-0001.fr</domain:name> C: <domain:add> C: <domain:ns> C: <domain:hostattr> C: <domain:hostname>ns1.nic.fr</domain:hostname> C: </domain:hostattr> C: <domain:hostattr> C: <domain:hostname>ns2.nic.fr</domain:hostname> C: </domain:hostattr> C: <domain:hostattr> C: <domain:hostname>ns.ndd-de-test-0001.fr</domain:hostname> C: <domain:hostaddr ip="v4"> </domain:hostaddr> C: <domain:hostaddr ip="v6">2001:660:3005:1::1:1</domain:hostaddr> C: </domain:hostattr> C: </domain:ns> C: </domain:add> C: </domain:update> C: </update> C: <cltrid>une-reference-client-par-exemple</cltrid> C: </command> C:</epp> Example of a request sent by the client after a creation to give the initial configuration of a domain name secured with DNSSEC: C:<?xml version="1.0" encoding="utf-8" standalone="no"?> C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> C: <command> C: <update> C: <domain:update C: xmlns:domain="urn:ietf:params:xml:ns:domain-1.0"> C: <domain:name>ndd-de-test-0001.fr</domain:name> C: <domain:add> C: <domain:ns> C: <domain:hostattr> C: <domain:hostname>ns1.nic.fr</domain:hostname> C: </domain:hostattr> C: <domain:hostattr> C: <domain:hostname>ns2.nic.fr</domain:hostname> C: </domain:hostattr> C: <domain:hostattr> C: <domain:hostname>ns.ndd-de-test-0001.fr</domain:hostname> C: <domain:hostaddr ip="v4"> </domain:hostaddr> C: <domain:hostaddr ip="v6">2001:660:3005:1::1:1</domain:hostaddr> C: </domain:hostattr> C: </domain:ns> C: </domain:add> C: </domain:update> C: </update> C: <extension> C: <secdns:update xmlns:secdns="urn:ietf:params:xml:ns:secdns-1.1"> C: <secdns:add> C: <secdns:dsdata> C: <secdns:keytag>12346</secdns:keytag> C: <secdns:alg>3</secdns:alg> C: <secdns:digesttype>1</secdns:digesttype> C: <secdns:digest>38ec35d5b3a34b44c39b38ec35d5b3a34b44c39b </secdns:digest> C: </secdns:dsdata> C: </secdns:add> C: </secdns:update> C: </extension> C: <cltrid>une-reference-client-par-exemple</cltrid> C: </command> C:</epp>