Guide d intégration technique

Transcription

1 Guide d intégration technique version 1.55 afnic@afnic.fr - 1 -

2 Table des matières 1. Préface À propos de ce document Public ciblé Conventions typographiques Historique des révisions Epp vs mail Services disponibles sous chaque interface Différences de comportement entre les deux interfaces EPP Configuration et paramètres Les grands principes d'intégration Pas d implémentation des objets "host" (RFC 5732) Cas des opérations avec code retour 1000 et comportement du serveur en cas de problème Gestion du auth_info Choix d implémentation de la liste des messages de notification Support de DNSSEC Commandes implémentées Le <greeting> La commande <hello> Les commandes de gestion de session Les commandes d interrogation Les commandes de mise à jour d objets Gérer un nom de domaine Create - créer un nom de domaine Update - modifier les attributs du domaine Delete - Supprimer un domaine Restore - Restaurer un domaine Transfer Changement de bureau d enregistrement Trade - Transmettre un domaine Recover - Transmission forcée d un nom de domaine Vérifier la disponibilité d'un domaine Récupérer les données d'un domaine Gérer un contact Créer un contact Modifier un contact Supprimer un contact Identification d un contact titulaire Récupérer les données d'un contact...65 afnic@afnic.fr - 2 -

3 3.6. Syntaxe Notifications Gestion de la file de notification Notifications asynchrones Notifications exogènes Codes retours et messages d'erreurs Les codes retour Les messages d erreurs RFCs Mail Configuration et paramètres Les grands principes d'intégration Structure du formulaire Sémantique du formulaire Syntaxique du formulaire Exemples Les opérations Les tickets : notifications et actions Généralités sur les tickets Format du ticket Description de l ensemble des tickets Les opérations gérables uniquement par mail/fax Génération de code d autorisation Validation de trade Réponse à une identification en problem Annexe 1 Version 1.0 vers 1.1 du serveur EPP Chronologie Avant le 5 avril À partir du 5 avril 2011 et jusqu'au 13 décembre À partir du 13 décembre Notes de compatibilité afnic@afnic.fr - 3 -

4 1. Préface 1.1. À propos de ce document Ce guide d intégration réunit l ensemble des informations nécessaires à l implémentation de l interface applicative de gestion de domaines de l AFNIC. Cette interface offre deux moyens d accès : le mail : interface asynchrone, EPP (Extensible Provisioning Protocol) : protocole standard d échange entre registre et bureaux d enregistrements. En ce qui concerne EPP, l AFNIC a respecté le standard décrit dans les RFCs (cf 3.9 RFCs.). Ce document se contente donc de décrire les points spécifiques à l implémentation AFNIC du protocole. Les évolutions et les détails opérationnels pendant les phases de transition sont présentées dans l'annexe Public ciblé Ce document est un document technique à destination des développeurs souhaitant obtenir une description détaillée de l interface et à la recherche d exemples facilitant leur intégration. Il ne redétaille pas les procédures (cf. Guide des procédures ni La Charte de Nommage ( qui seront considérées comme connues Conventions typographiques Dans l ensemble du document on écrit : Entre < > les balises xml décrivant les trames EPP Dans un cadre sur fond bleu, les exemples de trames EPP Historique des révisions 24/11/ V1.0 08/04/ V1.1 08/06/ V1.2 Ajout de notifications EPP manquantes 31/08/ V1.3 Ajout de la notification EPP suppression portefeuille 19/11/2010 V1.35 lignes 5b et 5c dans le Sémantique du formulaire : Optional au lieu de Mandatory 04/02/2011 V Ajout du support DNSSEC en EPP dans le serveur version 1.1 afnic@afnic.fr - 4 -

5 03/03/2011 V1.55 Correction de l exemple de greeting Epp vs mail Ces deux interfaces ne donnent pas entièrement accès aux mêmes fonctions. Par ailleurs l une étant asynchrone et l autre synchrone le comportement du système de gestion des domaines n est pas le même suivant l interface utilisée. Ce sont ces différences que nous allons détailler dans les deux prochains chapitres. Enfin, il est à noter que l AFNIC favorise le développement d EPP et que de nouvelles fonctions pourront venir s ajouter dans la rubrique EPP. Les opérations relatives à DNSSEC ne peuvent pas être réalisées par mail. Pour les rendre disponibles, le client EPP devra mentionner l'extension secdns-1.1 lors du login Services disponibles sous chaque interface EPP Mail Web Domaine Create - Création d un domaine sans code d autorisation x x x Create - Création d un domaine avec code d autorisation x x x Delete Suppression d un domaine x x x Restore Restauration du domaine supprimé x x x Update [admin] - Mise à jour administrative x x x Update [tech] - Mise à jour technique des serveurs x x x Update [tech] - Mise à jour technique des signatures x x Update [context] - Mise à jour du statut hold d un domaine x x x Update [context] - Mise à jour du auth_info x x x Transfer - Changement de bureau d enregistrement x x x Transfer - avec conservation des signatures x x Trade - Transmission volontaire entre deux titulaires x x x Trade - avec conservation des signatures x x Recover Transmission forcée vers un nouveau titulaire x x x Abandon du transfer Abandon du trade x x Check - Disponibilité du nom de domaine x x Récupération du auth_info x x Info sur le domaine x x Contact Create - Création d un contact x x x Update - Mise à jour d un contact x x Delete - Suppression d un contact Information sur un contact x x afnic@afnic.fr - 5 -

6 Notification (au bureau d enregistrement hors notification de fin d opérations) Transfer sortant x x x Recover sortant x x x Trade sortant x x x Identification d un titulaire x x x Suppression de contact par le Garbage Collector x Génération de Code d autorisation x x x 2.2. Différences de comportement entre les deux interfaces Asynchrone vs synchrone L interface mail est une interface asynchrone. Elle est basée sur un système d accusé réception (bonne réception du message et allocation d un numéro de formulaire), et sur un système de traitement après vérification de la demande (ouverture et allocation d un numéro de ticket). Cette interface doit donc permettre de gérer l émission de demande (par envoi de formulaires) et la gestion des tickets (pour les opérations avec suivi). En mode nominal le mail permet de travailler dans des délais extrêmement courts de l ordre de la minute, mais cette interface n étant pas prioritaire au niveau des traitements, l asynchronisme peut provoquer des délais plus importants. Ces délais peuvent avoir lieu très en amont (délai dans l émission du numéro de formulaire) ou en cours de traitement (délai dans l émission de numéro de ticket ou de commutation d état du ticket). En revanche une demande pour laquelle un numéro de formulaire a été émis n est jamais perdue. Quel que soit le délai, la demande sera traitée et une réponse sera envoyée au bureau d'enregistrement. EPP est une interface synchrone. Elle est basée sur un double système de réponse temps réel du serveur et de notification asynchrone. La réponse temps réel du serveur contient au minimum la bonne prise en charge de la commande et peut aller jusqu à la réponse de finalisation de la commande pour les commandes synchrones. Pour certaines commandes asynchrones, une notification est émise ultérieurement à la fin du traitement. Ecriture vs lecture Le mail permet uniquement de générer des opérations de traitement sur les domaines. Pour intégrer un système complet, il faudra utiliser le web. L AFNIC offre par ailleurs un ensemble de webservices qui n est plus maintenu et qu il n est pas recommandé d intégrer dans un système automatisé. EPP offre un ensemble complet de fonctions permettant aussi bien le traitement de domaines, le traitement de contacts et la gestion d opérations de type vérification de disponibilité ou information sur un domaine. Modularité Le mail permet des traitements tout en regroupant plusieurs commandes en un seul formulaire. Cela possède un aspect positif pour faciliter l enchaînement de afnic@afnic.fr - 6 -

7 plusieurs commandes et un aspect négatif dans le traitement et la gestion des réponses et des cas d erreurs lors de problèmes sur une partie seulement des traitements. EPP a une approche modulaire permettant d effectuer uniquement des opérations unitaires. Son automatisation aisée permet de gérer des traitements par lots côté client. Priorité 3. EPP L AFNIC a fait le choix de favoriser EPP dans les traitements. Des commandes arrivant quasi simultanément par mail et par EPP verront le traitement EPP passer avant le traitement mail Configuration et paramètres Banc de production EPP : epp.nic.fr port : 700 accès authentifié par certificat nombre de connexions disponibles : 2 adresses IP pouvant accéder au serveur : 2 comptes disponibles : 1 Banc de test EPP : epp.test.nic.fr port : 700 accès authentifié par certificat nombre de connexions disponibles : 2 adresses IP pouvant accéder au serveur : illimitées comptes disponibles : Les grands principes d'intégration Au-delà du standard EPP tel qu il est décrit dans les RFCs, l AFNIC a posé un certains nombres de principes d intégration qu il est bon de connaître avant de se lancer dans le développement d un client EPP Pas d implémentation des objets "host" (RFC 5732) Ce concept étant assez éloigné de la gestion de l AFNIC des serveurs de noms, nous avons choisi d adopter la méthode où les serveurs de noms sont des attributs du nom de domaine Cas des opérations avec code retour 1000 et comportement du serveur en cas de problème afnic@afnic.fr - 7 -

8 Une précaution est nécessaire lors du développement de clients qui se connectent à notre serveur EPP. En effet, nous indiquons à plusieurs reprises dans la suite du document, des opérations renvoyant un code retour Cela est le comportement attendu dans des conditions normales de fonctionnement de la chaîne d enregistrement des noms de domaine. Nous différencions les problèmes mineurs, majeurs et bloquants. Un problème mineur ou majeur représente un problème sur la chaîne de traitement n affectant pas la bonne réception des demandes. La chaîne de traitements est alors indisponible le temps que le problème soit résolu. Toute opération affectée par le problème, renvoie exceptionnellement un code retour 1001 pendant cette période et des notifications seront émises. Pour un problème mineur, les opérations sur les objets "contact", les consultations des files de notifications et les opérations EPP de type "query" ne sont pas affectées. Dans le cas d un problème bloquant, le serveur réagit de façon plus radicale et aucune opération de type "transform" sur les domaines ne peut être prise en compte. Un message d erreur "command failed" (code 2400) est alors retourné pour toute nouvelle commande Gestion du auth_info Le protocole EPP prévoit l utilisation d un auth_info, pour les noms de domaine, qui sont utilisé dans le cadre des opérations de transfer (changement de bureau d enregistrement). Les opérations que nous décrivons par la suite permettent aux bureaux d enregistrement qui utilisent notre serveur EPP de récupérer les auth_info de tout leur portefeuille de domaines et de modifier ceux-ci si nécessaire. De plus, compte tenu de l utilisation obligatoire de ce auth_info pour tout changement de bureau d enregistrement, une règle impose la mise à disposition de ce code par le bureau gestionnaire du nom de domaine. Chaque bureau est libre de choisir la meilleure méthode permettant la diffusion de cette information Choix d implémentation de la liste des messages de notification Nous avons choisi d indiquer lors de n importe quelle réponse du serveur le nombre de messages dans la file d attente (à moins qu il n y ait aucun message, auquel cas, cette information ne doit pas être fournie). Le RFC 5730 n oblige à fournir cette information que dans le cas des réponses aux commandes <poll> alors qu elle est optionnelle pour les autres types de commandes. Concrètement, cela implique que dès qu un message doit être notifié à un bureau d enregistrement, celui-ci en est averti par la présence de l élément <msgq> présent dans les réponses à toutes les commandes envoyées au serveur. Il est vivement conseillé de prendre connaissance de ces messages au fur et à mesure que ceux-ci arrivent puisqu au milieu des messages de suivi d opérations de afnic@afnic.fr - 8 -

9 modifications techniques par exemple peuvent très bien se trouver des demandes de transfer auxquelles il pourrait être intéressant de répondre Support de DNSSEC Le serveur EPP gère l'extension secdns-1.1 telle que décrite dans le RFC 5910, à l'exclusion de toute autre version. Les spécificités de mise en œuvre sont les suivantes : Le serveur supporte uniquement «l'interface données DS» (<secdndsdata>), section 4.1 du RFC 5910, sans informations sur la clef associée (pas d'élément <secdnkeydata>) ; la présence d'informations relatives à la clef générera une erreur De manière similaire aux serveurs de noms, les éléments DNSSEC ne sont acceptés que lors d'une opération update[tech] ; leur présence lors d'un create provoquera une erreur Un nom de domaine peut avoir au plus 6 enregistrements DS associés : le nombre d'élements <secdndsdata> présents dans la section <secdnadd> lors d'une opération update[tech] est donc limité de telle façon que l'état final du nom de domaine n'ait pas plus de 6 enregistrements DS. L'attribut maxsiglife n'est pas supporté, sa présence dans la demande du client générera une erreur L'attribut urgent n'est pas supporté, sa présence dans la demande du client avec la valeur 1 générera une erreur Lors d'une opération transfer, la partie extension AFNIC ( doit obligatoirement comporter un drapeau keepds qui est un booléen : s'il vaut 1, les enregistrements DS actuels du domaine sont conservés après le transfert si déjà présents, alors que s'il vaut 0 en cas de transfert réussi tout enregistrement DS existant sera supprimé ; pendant la phase transitoire pour les bureaux utilisant toujours l'extension ce booléen ne pouvant pas être présent, une opération transfer réussie aura toujours pour effet de supprimer les DS existants. Les opérations trade et recover fonctionnent de manière identique au transfer évoqué au-dessus. La présence de l'élément <secdnadd> lors d'une opération update[tech] entraînera l'exécution de tests spécifiques à DNSSEC par ZoneCheck. Le contenu de ces tests est rappelé à l'adresse Tous les algorithmes de génération de clef et de condensat sont acceptés, mais certains tests ZoneCheck afnic@afnic.fr - 9 -

10 sont succeptibles de remonter des erreurs fatales pour les algorithmes connus lorsque des problèmes spécifiques sont détectés, et donc in fine d'empêcher la prise en compte de l'opération update demandée Commandes implémentées Le <greeting> Le <greeting> n est pas une commande que le client peut envoyer au serveur EPP mais la bannière d accueil que ce dernier va envoyer au moment de l établissement de la connexion. C est aussi la réponse qui sera envoyée en réponse à une commande <hello> (cette commande est abordée au point suivant). Pourquoi s attarder sur cette bannière si ce n est pas une commande? Tout simplement parce que les informations qu elle fournit ont leur importance et sont nécessaires, entre autres, pour la commande <login>. Bien que le <greeting> qui est reproduit ci-après ne soit donné qu à titre d exemple et que le détail de ce qu il peut contenir peut être trouvé dans le RFC 5730, il faut être particulièrement attentif à au moins 2 informations fournies, à savoir les versions du protocole supportées (élément <version>) et les langues acceptées (élément <lang>). Seul un choix, parmi ces valeurs, sera accepté lors de l établissement de la session avec la commande <login>. Exemple de <greeting> pouvant être envoyé par le serveur EPP de l AFNIC : <?xml version="1.0" encoding="utf-8" standalone="no"?> <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> <greeting> <svid>epp PROD Server on nergal.nic.fr (V1.1.0)<svID> <svdate> t12:34:56.0z</svdate> <svcmenu> <version>1.0</version> <lang>en</lang> <objuri>urn:ietf:params:xml:ns:contact-1.0</objuri> <objuri>urn:ietf:params:xml:ns:domain-1.0</objuri> <svcextension> <exturi>urn:ietf:params:xml:ns:rgp-1.0</exturi> <exturi> <exturi> <exturi>urn:ietf:params:xml:ns:secdns-1.1</exturi> </svcextension> </svcmenu> <dcp> <access><all/></access> <statement> <purpose><admin/><prov/></purpose> <recipient><ours/><public/></recipient> <retention><stated/></retention> </statement> </dcp> </greeting> </epp> afnic@afnic.fr

11 La commande <hello> Bien que ce ne soit pas une commande EPP à proprement parler, cette commande est particulièrement importante et utile car elle va permettre à un client EPP de vérifier que la connexion avec le serveur est correctement établie. En effet, dès lors qu une connexion est établie avec le serveur, il est possible, à tout moment d envoyer cette commande à laquelle le serveur répondra en envoyant la bannière d accueil EPP (le <greeting>), et ceci, même si la phase d authentification (<login>) n est pas encore complétée. Dans la mesure où des mécanismes de time-out devaient être activés (pour plus de détails, se référer au document Les politiques techniques du registre en cours d élaboration) pour clore des sessions «inactives», il est tout à fait possible de réaliser un «heartbeat» en exécutant cette commande de manière régulière afin de maintenir ouvertes des sessions peu utilisées (bien entendu, la fréquence de ce «heartbeat» devra rester raisonnable, eu égard aux paramètres de «time-out» et de rate-limiting éventuellement mis en place). Par exemple, on peut très bien imaginer qu exécuter cette commande toutes les 2 minutes pour maintenir une connexion ouverte et s assurer que le serveur est toujours à l écoute est une fréquence acceptable. Exemple de requête envoyée par le 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> Les commandes de gestion de session Le protocole EPP propose 2 commandes permettant d établir (<login>) et de terminer une session avec le serveur (<logout>). Une fois la session établie, celle-ci ne se terminera que sur demande du client (<logout>) ou si le serveur devait, pour des raisons internes la clore («time-out» sur session inactive, problèmes technique, ) ou si le client interrompt la connexion TCP (si cette interruption se fait dans le cadre normal d utilisation du client, il est vivement recommandé d effectuer un <logout> avant de couper la connexion TCP). Le nombre de sessions simultanées pouvant être limité, la gestion de celles-ci se doit d être rigoureuse La commande <login> Lors de la connexion au serveur, celui-ci envoie une bannière au client (<greeting>) indiquant, par là même, qu il est disposé à recevoir une commande d établissement de session. Cette commande nécessite de connaître l identifiant EPP généré par l AFNIC pour chacun de ses bureaux d enregistrement ainsi que le mot de passe qui lui est associé (il a été choisi, afnic@afnic.fr

12 pour des raisons de sécurité et «d étanchéité» entre les différentes interfaces proposées par l AFNIC, de créer de nouveaux identifiants, sans le moindre lien avec ceux qui pouvaient jusqu à présent exister). Si ceux-ci sont correctement renseignés et que le nombre de sessions actuellement établies n a pas atteint le nombre maximum autorisé, la session doit normalement s établir. La commande <login> offre aussi la possibilité de modifier le mot de passe associé à cet identifiant, il n y a aucune limitation à cet usage et il est même vivement conseillé de le modifier lors de la première ouverture de session sur le serveur EPP. Exemple de commande <login> envoyée par un 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> 1.0</extURI> C: </svcextension> C: </svcs> C: </login> C: <cltrid>une-reference-client-par-exemple</cltrid> C: </command> C:</epp> Le résultat de cette commande sera l ouverture d une session pour le bureau d enregistrement dont l identifiant EPP est «kiffucol911-.fr», le mot de passe est «toto1», et qui par mesure de sécurité décide de le changer par «toto2» (bien entendue, c est ce nouveau mot de passe qui devra être utilisé lors du prochain établissement de session, puisque la prise en compte de cette modification est immédiate) La commande <logout> Nous l avons déjà indiqué, un client souhaitant avoir une gestion propre des sessions EPP doit envoyer une commande de fin de session (<logout>) (et, dans l idéal, attendre la réponse du serveur) avant de couper la connexion TCP avec le serveur. Bien que le serveur soit à même de détecter des déconnexions «sauvages» des clients EPP, ce type de déconnexion pourrait afnic@afnic.fr

13 ne pas libérer aussi vite que désiré les ressources limitées allouées à chaque bureau d enregistrement. Pour être tout à fait clair, si nous n autorisons, par exemple, que N sessions simultanées par bureau d enregistrement au serveur EPP, que celles-ci sont toutes utilisées à un instant donné, déconnecter un client sans phase de <logout> pourrait avoir comme effet de ne pas prendre immédiatement en compte cette déconnexion. Cela empêche du même coup toute nouvelle connexion et ainsi renvoie un code retour «2502» le temps que le système détecte et gère correctement cette déconnexion. Exemple de commande <logout> envoyée par un 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> Les commandes d interrogation Bien que dans les chapitres qui suivent, nous détaillons les commandes pour les différents types d objets (contact et domain), voici un bref aperçu de ce qui est disponible et l usage pour lequel ces commandes ont été prévues La commande <check> Cette commande va permettre de connaître la disponibilité d un objet. Compte tenu de la gestion interne que nous avons pour les «contacts», à savoir, c est un algorithme interne qui détermine l identifiant (Nic-handle) qui sera associé à un objet «contact», celle-ci n est utilisable que pour les objets «domain». Avant toute création de nom de domaine, il est vivement conseillé d utiliser cette commande (ou son équivalent si un autre mécanisme de DAS -Domain Availibility System- devait être mis en place par l AFNIC) afin d en vérifier la disponibilité La commande <info> Lorsque vous souhaitez avoir des informations sur un nom de domaine ou sur un contact dont vous connaissez l identifiant, c est cette commande qu il faut utiliser. Un bureau d enregistrement pourra récupérer les infomations sur les contacts liés aux objets de son portefeuille, et uniquement ceux là. Pour les noms de domaine, il est possible, dès lors que l on connaît le mot de passe associé à celui-ci (élément <authinfo>), d avoir les informations sur des domaines gérés par un autre bureau d enregistrement (ce mot de passe est, entre autres, transmis par le titulaire lors des opérations de <transfer>). afnic@afnic.fr

14 Il est important de noter que cette commande ne devrait être utilisée que pour récupérer des infos sur les objets, et non pour vérifier la disponibilité de ceux-ci, par exemple. Cette fonction étant la raison d être de la commande <check> La commande <poll> Au cours des différentes opérations qui seront réalisées sur les objets du portefeuille d un bureau d enregistrement, des messages de notifications auront besoin d être transmis à celui-ci. Ces messages seront mis dans une file consultable à l aide de la commande <poll>. Quelques exemples d utilisation pourront être trouvés pluis loin, mais dans le principe, voici comment fonctionne cette file de messages de notifications. Chaque fois qu une information liées à une opération (et pour laquelle il existe un message spécifique) doit être transmise, celle-ci est mise dans une file de messages. Dès lors que des messages sont prêts à être lus, l information est indiquée dans les réponses aux commandes envoyées sur le serveur (élément <msgq> renseigné). La commande <poll> va permettre de prendre connaissance du message le plus ancien qui se trouve dans la file. Pour que celui-ci soit supprimé de la file de message, il faut utiliser à nouveau cette commande mais en indiquant le numéro de message à supprimer qui doit correspondre à celui qui vient d être lu (la procédure détaillée peut-être trouvée dans le RFC 5730). Il est probable que le document «les politiques techniques du registre» impose des limitations quand aux délais de garde des messages dans notre système, s y référer pour plus de détails Les commandes de mise à jour d objets Ces commandes sont toutes détaillées par la suite, il est fortement conseillé de lire les RFCs suivants : 5730 (généralités sur les commandes), 5731 (spécificités liées aux objets «domain»), 5732 (spécificités liées aux objets «contact») ainsi que le 5910 (spécificités liées à DNSSEC). En voici la liste exhaustive : <domain:create> <domain:update> <domain:delete> <domain:transfer> <frnic:trade> et <frnic:recover> (opérations sur les domaines avec utilisation d une extension) <contact:create> <contact:update> afnic@afnic.fr

15 3.4. Gérer un nom de domaine Create - créer un nom de domaine Le protocole EPP (RFC 5730) permet la création de noms de domaine (RFC 5731). Il convient de distinguer deux types de dépôts, chacun ayant sa spécificité. Le premier type de dépôt, que nous qualifions de "direct", doit être utilisé pour un enregistrement standard de nom de domaine (cf. La Charte de Nommage AFNIC - Art ) Le second type de dépôt, que nous qualifions de "dépôt avec code d autorisation", doit être utilisé pour un enregistrement sous conditions de nom de domaine (cf. La Charte de Nommage AFNIC Art ) Dépôt "direct" d un nom de domaine Ce cas représente 99,99 % des opérations de création et il n y a pas beaucoup d informations à fournir pour ce type d opération. En ce qui concerne les nic-handles, d un point de vue EPP, XX FRNIC est un ROID (Repository Object Identifier) et ce n est pas ce qui est censé être utilisé comme référence pour les objets "contact". Un objet "contact" est référencé uniquement avec la "partie gauche" du nic-handle, à savoir ce dernier sans le " -FRNIC". Voici les éléments qui doivent être présents lors de la commande et leur description succincte. L absence d éléments obligatoire et/ou la présence d autres éléments renvoient une erreur. Nom de l élément Nombre d occurrences <domain:name> 1 <domain:period> 0-1 <domain:registrant> 1 <domain:contact type="admin"> 1 <domain:contact type="tech"> 1-3 <domain:authinfo> 1 <domain:pw> 1 <cltrid> 0-1 <domain:name> contient le nom de domaine complet (exemple-nddepp.fr). <domain:period> n a pas vraiment de sens compte tenu de la gestion actuelle des noms de domaine renouvelés par tacite reconduction. Il a été convenu de ne pas renvoyer d erreur lorsqu il est présent mais de n accepter que 2 valeurs bien précises pour celui-ci. Soit <domain:period unit="y">1</domain:period> Soit <domain:period unit="m">12</domain:period> afnic@afnic.fr

16 <domain:registrant> contient l identifiant du titulaire déduit du nichandle de celui-ci auquel on aura retiré le suffixe (FRNIC) et le caractère séparateur "-". <domain:contact type="admin"> contient l identifiant du contact administratif. <domain:contact type="tech"> contient l identifiant d un contact technique. <domain:authinfo> contient le auth_info que le bureau d enregistrement choisit d associer à ce nom de domaine. Dans le cas de la création "avec code d autorisation", ce auth_info est imposé. Il n est pas prévu dans l immédiat de proposer un autre mécanisme que le mot de passe (<domain:pw>). Ce dernier étant libre, il est fortement recommandé d associer un auth_info différent pour tous ses noms de domaine. Il n est par ailleurs pas possible d utiliser l attribut "roid". De manière à ne pas être ambigu à ce niveau, son utilisation a pour résultat de renvoyer une erreur. <cltrid> est optionnel. Il est vivement conseillé de renseigner ce champ pour un meilleur suivi des commandes et pour éventuellement effectuer des recherches et des opérations de «debugging» de vos clients EPP. Exemple de requête envoyée par le 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> Dans ce contexte de création "simple", si toutes les règles de nommage et syntaxiques sont respectées et si le nom de domaine est libre, le serveur envoie une réponse avec comme code retour Pour être plus précis, en cas de succès pour le dépôt du nom de domaine, le seul code retour possible est Il ne peut pas y avoir de code retour 1001 pour ce type de dépôt sauf problème mineur ou majeur. À noter, dans la réponse du serveur les dates de création et d expiration (<domain:crdate> et <domain:exdate>), cette dernière étant donnée à afnic@afnic.fr

17 titre indicatif et pour être cohérent avec l élément <domain:period> lorsque celui-ci est fourni par le client. Exemple de réponse envoyée par le serveur : <?xml version="1.0" encoding="utf-8" standalone="no"?> <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> <response> <result code="1000"> <msg>command completed successfully</msg> </result> <resdata> <domain:credata xmlns:domain="urn:ietf:params:xml:ns:domain-1.0"> <domain:name>ndd-de-test-0001.fr</domain:name> <domain:crdate> t00:00:00.0z</domain:crdate> <domain:exdate> t00:00:00.0z</domain:exdate> </domain:credata> </resdata> <trid> <cltrid>une-reference-client-par-exemple</cltrid> <svtrid>frnic </svtrid> </trid> </response> </epp> Exemple de code retour 1001 envoyé par le serveur : <?xml version="1.0" encoding="utf-8" standalone="yes"?> <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"> <response> <result code="1001"> <msg>command completed successfully; action pending</msg> </result> <resdata> <domain:credata xmlns:domain="urn:ietf:params:xml:ns:domain- 1.0"> <domain:name>dom-epp-wytxubuz.fr</domain:name> <domain:crdate> t15:22:15.0z</domain:crdate> <domain:exdate> t00:00:00.0z</domain:exdate> </domain:credata> </resdata> <trid> <cltrid>frnic client </cltrid> <svtrid>dev-photon </svtrid> </trid> </response> </epp> Dépôt "avec code d autorisation" d un nom de domaine Une telle opération nécessite d obtenir un code d autorisation (cf. Guide des Procédures Rappelons que celui-ci est associé au triplet (bureau d enregistrement, nom de domaine, nic-handle du titulaire). afnic@afnic.fr

18 Une fois que le code est créé, le dépôt du nom de domaine se fait pratiquement comme ce que nous avons décrit lors du dépôt "direct" à 2 nuances près. La première c est que l identifiant du titulaire n est pas libre mais doit correspondre à celui associé au code d autorisation, la seconde c est que le code d autorisation doit être utilisé en lieu et place du auth_info dans l élément <domain:authinfo>, ce dernier n étant donc plus libre. Par contre, il est obligatoire de procéder à la modification de celui-ci via une commande <domain:update> avant de le transmettre au client final. Il est à noter que cela ne change rien au reste de la requête et que le traitement de celle-ci est soumis aux mêmes règles que le cas précédemment décrit. Ceci impliquant, entre autres, que nous nous trouvons dans le cas où un dépôt réussi génère une réponse avec un code retour 1000 (c est pour cette raison que la réponse du serveur n est pas reproduite). Exemple de requête envoyée par le 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> Après la création Une fois le domaine créé, il est consultable en utilisant la commande <domain:info> et est visible dans le Whois (un délai de propagation supplémentaire est possible compte tenu de l architecture de réplication des bases de données mise en place, mais dans des conditions optimales, la synchronisation des données se fait au fil de l eau). Bien que le processus d identification se déroule sur le titulaire, celui-ci impacte sur l état du nom de domaine une fois ce dernier créé. En effet, si le titulaire est déjà "identifié", le domaine peut être dans l état "ok", dans le cas contraire, celui-ci est dans l état "servertransferprohibited" et "servertradeprohibited". afnic@afnic.fr

19 Update - modifier les attributs du domaine Nous avons choisi de définir 3 types de modifications bien distinctes via la même commande EPP, à savoir la commande <domain:update>. Dans un cas la modification porte sur les contacts associés à un nom de domaine (technique et/ou administratifs), dans un autre, uniquement sur la configuration DNS et dans le dernier cas, uniquement sur l état du nom de domaine et le auth_info qui lui est associé Update [admin] - Modification de la liste des contacts La modification de la liste des contacts associés à un nom de domaine, qu ils soient techniques et/ou administratifs va passer par une commande <domain:update>. Bien qu EPP et le mapping domain prévoient la modification du titulaire du nom de domaine par le biais de cette commande, nous n autorisons pas cette action. Un changement de titulaire passe par les commandes <domain:trade> et <domain:recover> que nous traiterons un peu plus loin dans ce document. Il est important de garder à l esprit que les modifications sur les listes de contacts ne doivent pas transgresser les règles d occurrences indiquées dans la section sur la création d un nom de domaine. En effet, la commande <domain:update> permettant l utilisation de deux sous-commandes <domain:add> et <domain:rem>, toute suppression d un contact amenant la disparition de ce type de contact pour le domaine doit s accompagner de l ajout d un autre contact de ce même type. Par exemple, la règle actuelle qui veut qu il n y ait qu un contact administratif pour un nom de domaine se traduit lors de la modification de celui-ci par la suppression du contact actuel et l ajout d un nouveau, dans la même commande EPP (l exemple que nous donnerons plus loin reprendra ce cas). Chaque élément <domain:add> et <domain:rem> peut contenir des éléments de type <domain:contact> (déjà présentés dans la section "créer un nom de domaine"). Si un même contact est présent en même temps dans <domain:add> et <domain:rem>, la commande est acceptée, les deux opérations s annulent et les autres modifications indiquées dans la commande sont prises en compte normalement. Concrètement, une commande indiquant l ajout des contacts techniques VIL1666 et MIS78 ainsi que la suppression du contact technique VIL1666 est équivalente à une commande indiquant uniquement l ajout du contact technique MIS78. Si nous reprenons l exemple du nom de domaine précédemment créé auquel nous souhaiterions ajouter un troisième contact technique et modifier le contact administratif, voici la requête XML qui est envoyée. afnic@afnic.fr

20 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> Exemple de réponse envoyée par le serveur (pour ce type de commande, le code retour est toujours 1000 sauf problème mineur ou majeur) : <?xml version="1.0" encoding="utf-8" standalone="no"?> <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> <response> <result code="1000"> <msg>command completed successfully</msg> </result> <trid> <cltrid>une-reference-client-par-exemple</cltrid> <svtrid>frnic </svtrid> </trid> </response> </epp> Exemple de réponse en cas de code retour 1001 : <?xml version="1.0" encoding="utf-8" standalone="yes"?> <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"> <response> <result code="1001"> <msg>command completed successfully; action pending</msg> </result> <msgq count="1" id="63480"/> <trid> <cltrid>frnic client </cltrid> <svtrid>dev-photon </svtrid> </trid> </response> </epp> afnic@afnic.fr

21 Update [tech] - Modification de la configuration des serveurs de noms La commande est utilisée pour indiquer une configuration DNS initiale pour un nom de domaine qui n en a pas encore ou pour modifier une configuration DNS existante. Par modification, il faut comprendre aussi la suppression pure et simple de la liste des serveurs de noms d un nom de domaine, ceci afin d être cohérent avec la possibilité de réserver un nom de domaine sans lien avec la publication DNS. Cette commande est aussi utilisée pour ajouter ou supprimer des délégations signées (enregistrements DS). La commande est envoyée par le client (pour simplifier, nous considèrons que celle-ci est syntaxiquement correcte et que les glues nécessaires sont bien présentes), le format retenu pour les serveurs de noms étant celui où ces derniers sont des attributs de l objet "domain" et non pas des références sur des objets "host" (RFC 5732). Lorsque la commande est traitée, le serveur renvoie un code retour 1001 indiquant que celle-ci est prise en compte. Dans le même temps, l état "pendingupdate" est appliqué au nom de domaine. Une fois que l outil ZoneCheck a réalisé les tests nécessaires à la validation de la configuration technique (sauf si l on se trouve dans le cas ou la commande <domain:update> est utilisée pour "vider" une configuration existante de ses serveurs de nom, auquel cas, exécuter ZoneCheck n a aucun sens) l état "pendingupdate" est supprimé et deux cas peuvent se présenter : La configuration est OK (ce qui est forcément le cas lorsque nous sommes en présence d une liste de serveurs "vide") et dans ce cas elle est directement visible dans le Whois et peut être publiée au prochain rechargement du fichier de zone (à moins que l état "clienthold" ou "serverhold" ne soit positionné, empêchant ainsi la publication DNS). La configuration est KO et elle est tout simplement ignorée. Rien n est modifié dans le Whois ou dans les DNS. La commande <poll> est utilisée pour connaître le résultat de l opération de mise à jour. Une notification est émise quel que soit le résultat final du ZoneCheck. ATTENTION : La configuration DNS ne distingue pas un serveur comme étant le primaire et les autres comme étant des secondaires. L ordre des serveurs envoyés n a donc aucune importance. Même si dans les faits ceuxci seront généralement retournés suivant le même ordre (que ce soit via le Whois ou via la réponse à une commande <domain:info>), il ne faut pas chercher derrière cet ordre une quelconque règle de priorité. La commande <domain:update> ne peut contenir que les éléments <domain:add> et/ou <domain:rem>. Le premier contenant les informations nécessaires pour ajouter un ou plusieurs serveurs de noms à la configuration existante, le second permettant de supprimer un ou plusieurs afnic@afnic.fr

22 serveurs de noms. La modification d un serveur de noms pour mettre à jour les glues qui lui sont affectées passe par sa présence dans <domain:rem> (juste le nom du serveur) et dans <domain:add> (avec les nouvelles glues à appliquer). Pour rappel, nous n avons pas implémenté le RFC 5732, à savoir les objets de type "host" permettant de référencer les serveurs de noms. Nous préférons utiliser la possibilité de décrire les serveurs de noms comme attributs des objets "domain". Chacun des éléments <domain:add> et <domain:rem> ne peut contenir que l unique élément <domain:ns>, toute présence d un autre élément amenant ainsi la confusion sur le type de modification demandée entraîne une erreur. De même, chaque élément <domain:ns> ne sont composé que d une collection d éléments <domain:hostattr>. Voici les sous éléments qui sont présents dans l élément <domain:hostattr> et leur description succincte. L absence d éléments obligatoire et/ou la présence d autres éléments renvoie une erreur. Nom de l élément Nombre d occurences <domain:hostname> 1 <domain:hostaddr ip="v4"> 0-n <domain:hostaddr ip="v6"> 0-n <domain:hostname> contient le nom de domaine complet du serveur de noms. <domain:hostaddr ip="v4"> contient une adresse IPv4 à associer au serveur de noms lorsqu une glue est nécessaire (uniquement pour <domain:add>, interdit pour <domain:rem>). <domain:hostaddr ip="v6"> contient une adresse IPv6 à associer au serveur de noms lorsqu une glue est nécessaire (uniquement pour <domain:add>, interdit pour <domain:rem>). Si la présence d une glue s avère nécessaire, il n est pas obligatoire de fournir des adresses ipv4 et des adresses ipv6. Une seule adresse, quel que soit son type, est suffisante (mais rien n empêche d en mettre plusieurs). La commande peut être associée à une extension <secdnupdate> si des opérations DNSSEC sont souhaitées et que l'extension secdns a été choisie par le client lors de la connexion. Dans ce cas l'extension devra contenir un élément <secdnrem> et/ou un élément <secdnadd>. L'élément <secdnrem> contient soit le seul élément <secdnall> (s'il est présent avec la valeur 1 il a pour effet de supprimer tous les enregistrements DS liés au domaine) soit un ou plusieurs éléments <secdndsdata>. L'élément <secdnadd> contient un ou plusieurs élément <secdndsdata>. afnic@afnic.fr

23 Chaque élément <secdndsdata> possède les sous-éléments suivants : Nom de l élément <secdnkeytag> 1 <secdnalg> 1 <secdndigesttype> 1 <secdndigest> 1 Nombre d occurences Il est rappelé que conformément au RFC 5910 l'ordre à une importance, le contenu de l'élément <secdnrem> étant pris en compte avant le contenu de l'élément <secdnadd>. L'attribut "urgent" dans l'élément <secdnupdate> n'est pas accepté, sa présence avec la valeur 1 générera une erreur L'élément <secdnchg> sous <secdnupdate> n'est pas accepté non plus car le seul sous-élément autorisé sous <secdnchg> est <secdnmaxsiglife> qui n'est pas supporté. Toute présence de l'élément <secdnchg> générera donc une erreur Exemple de requête envoyée par le client après une création pour fournir la configuration initiale d un nom de domaine : 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> afnic@afnic.fr

24 Exemple de requête envoyée par le client après une création pour fournir la configuration initiale d un nom de domaine sécurisé avec 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: C: <update> <domain:update C: xmlns:domain="urn:ietf:params:xml:ns:domain-1.0"> C: C: <domain:name>ndd-de-test-0001.fr</domain:name> <domain:add> C: <domain:ns> C: C: <domain:hostattr> <domain:hostname>ns1.nic.fr</domain:hostname> C: </domain:hostattr> C: C: <domain:hostattr> <domain:hostname>ns2.nic.fr</domain:hostname> C: </domain:hostattr> C: C: <domain:hostattr> <domain:hostname>ns.ndd-de-test-0001.fr</domain:hostname> C: <domain:hostaddr ip="v4"> </domain:hostaddr> C: C: <domain:hostaddr ip="v6">2001:660:3005:1::1:1</domain:hostaddr> </domain:hostattr> C: </domain:ns> C: C: </domain:add> </domain:update> C: </update> C: C: <extension> <secdnupdate xmlns:secdns="urn:ietf:params:xml:ns:secdns-1.1"> C: <secdnadd> C: C: <secdndsdata> <secdnkeytag>12346</secdnkeytag> C: <secdnalg>3</secdnalg> C: C: <secdndigesttype>1</secdndigesttype> <secdndigest>38ec35d5b3a34b44c39b38ec35d5b3a34b44c39b </secdndigest> C: C: </secdndsdata> </secdnadd> C: </secdnupdate> C: C: </extension> <cltrid>une-reference-client-par-exemple</cltrid> C: </command> C:</epp> Sur les commandes de type <domain:update>, les réponses envoyées par le serveur sont assez succinctes, c'est-à-dire qu il n y a pas d élément <resdata>. Par contre, le code retour est toujours égal à 1001 pour ce type de modification. Exemple de réponse envoyée par le serveur : <?xml version="1.0" encoding="utf-8" standalone="no"?> <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> <response> <result code="1001"> <msg>command completed successfully; action pending</msg> </result> <trid> <cltrid>une-reference-client-par-exemple</cltrid> <svtrid>frnic </svtrid> </trid> </response> </epp> afnic@afnic.fr

25 Update [context] - Modification de l état du domaine et/ou du auth_info Cette opération est complètement indépendante de la configuration DNS du nom de domaine concerné. Elle permet au bureau d enregistrement de positionner ou retirer le flag "clienthold". S il est positionné, un nom de domaine, même s il est associé à une configuration DNS validée par notre outil ZoneCheck, ne sera pas annoncé dans le DNS. Quelles que soient les modifications faites sur ce flag, cela ne déclenche aucune relance des tests de vérification ZoneCheck. Les deux processus sont réellement indépendants. ATTENTION : Certaines opérations (il convient de consulter le guide des procédures pour plus de détails sur ce sujet) peuvent avoir comme conséquence de supprimer ce flag dès lors qu elles aboutissent. Ce sont à nouveau les éléments <domain:add> et <domain:rem> qui sont utilisés pour ajouter/supprimer un flag. Ces éléments ne peuvent contenir qu un seul élément. Nom de l élément <domain:status s="clienthold"> 1 Nombre d occurences <domain:status s="clienthold"> est envoyé tel quel. Le RFC 5731 permet l envoi d un message clair associé à l élément <domain:status> ainsi que l utilisation d un attribut (lang) indiquant la langue de ce message. Ce message n étant pas traité chez nous, l élément doit être vide. Concernant la modification du auth_info associé au nom de domaine, l utilisation de l élément <domain:chg> est nécessaire et bien que celui-ci puisse avoir comme éléments fils <domain:registrant> et <domain:authinfo>, seul ce dernier est accepté. La présence de l élément <domain:registrant> entraîne un retour d erreur de la part du serveur EPP. L utilisation de <domain:authinfo> est tout à fait similaire à celle indiquée pour une opération de création. afnic@afnic.fr