1Net::DRI is Copyright (C) 2005-2010, Patrick Mevzek <netdri@dotandco.com> 2Official website for Net::DRI information and download: 3http://www.dotandco.com/services/software/Net-DRI/index.en 4 5Net::DRI 6======== 7 8A Perl library to access Domain Name Registries/Registrars: 9DRI stands for Domain Registration Interface and aims to be, 10for domain name registries/registrars/resellers 11what Perl DBI is for databases. 12 13Net::DRI offers a uniform API to access services. 14It can be used by registrars to access registries. 15It can be used by clients to access registrars and/or resellers. 16It can be used by anonyone to do whois, DAS or IRIS DCHK queries. 17 18It is an OO framework that can be easily extended to 19handle various protocols (RRP, EPP, custom protocols) and 20various transports methods (TCP, TLS, SOAP, email, etc...). 21 22Specific policies for each registry are handled in a Net::DRI::DRD 23subclass, DRD standing for Domain Registry Driver with registry 24being used broadly to describe a service offering domain names 25and related things, which can be provided by a true domain name 26registry, a registrar or a reseller at any level in the chain. 27 28Net::DRI standardizes as much as possible on EPP which is the current 29standard for domain name activities, for example for status codes. 30 31Net::DRI has been used to help conduct IETF interoperability tests, and is used 32in production by various organizations with success. 33 34Currently Net::DRI ships with: 35 36- a full RRP implementation (RFC 2832 & 3632) 37- a full EPP implementation (STD 69 aka RFC 5730/5731/5732/5733/5734/3735 ), including registry notifications 38- many EPP extensions: 39 * GracePeriod (RFC 3915) 40 * E164 for ENUM (RFC 4114) 41 * Enum Validation (RFC 5076) 42 * SecDNS for DNSSEC (RFC 4310) 43 * Infrastructure ENUM in Austria 44 * NSgroup (used by .BE and .EU) 45 * CentralNic extensions: Release, TTL, WebForwarding 46 * Domain/Contact/Host and other extensions needed for extra services in various TLD: 47 .EU .COM .NET .MOBI .AERO .CAT .US .PL .SE .BE .AT .COOP .LU .ASIA .AU .NAME .ORG .UK 48 .DE .CH .LI .HN .SC .VC .AG .BZ .LC .MN .ME .CZ .TRAVEL .NO .BR .JOBS .PRO .FR .PT 49 .CX .GS .TL .KI .MS .MU .NF .HT .IM .SI .NG .NA .IT .NL .CA 50- a full DAS (Domain Availability Service) implementation for .BE .EU .NL .AU 51- a full Whois implementation (RFC 3912) for thin and thick registries : 52 support included for domain names in .COM .NET .ORG .BIZ .INFO .AERO 53 .EU .MOBI .NAME .LU .WS .SE .CAT .AT .TRAVEL .US .PT 54- an IRIS (RFC3981) implementation with LWZ transport (RFC4993) for DCHK (5144): 55 currently only DENIC registry (.DE) provide this service 56 XCP transport (RFC4992) is also available 57- an UDP/TCP/TLS socket transport 58- an HTTP/HTTPS transport 59- various SOAP transports over HTTP/HTTPS 60- an SMTP transport 61- Net::DRI::DRD::* modules for : .EU .COM .NET .TV .CC .WS .SE .PL .US .CAT .FR 62 .BE .MOBI .INFO .ORG .AT .LU .BIZ .NAME .NU .UK .AU .AERO .ASIA .COOP 63 IENUMAT .DE .CH .LI .HN .SC .VC .AG .BZ .LC .MN .ME .CZ .TRAVEL .PT 64 .NO .BR .PRO CoCCA CentralNic .IM .SI .CO.CZ .IT AdamsNames .AU .GL .NL .CA 65- a Net::DRI::DRD::AFNIC covering AFNIC registry for .FR 66 (only domain_check through web services and all operations by email or EPP) 67- Net::DRI::DRD::* modules to use registrars API for Gandi, OVH, BookMyName, OpenSRS 68- a shell (Net::DRI::Shell) providing autocompletion, logging and batch operations to be able 69 to leverage all Net::DRI power without writing any line of code 70 (see Net::DRI::Shell module documentation for all details) 71 72If you are a registry/registrar/reseller, we would welcome 73the opportunity to be able to test Net::DRI against your system. Please 74drop a note to the authors of Net::DRI and do not hesitate to provide 75this framework to your clients (see license file). 76 77If you are already using Net::DRI or planning to do so, please let us also know. 78Do not hesitate to let others know and if you want, you are welcome to make a link 79back to our website at <http://www.dotandco.com/services/software/Net-DRI/index.en> 80 81Perl modules needed 82------------------- 83 84Make sure to use at least Perl 5.8.4 as earlier versions have issues 85with utf8 handling which will cause errors for EPP. 86 87You also need the following modules: 88 89Carp (*) 90DateTime 91DateTime::Duration 92DateTime::Format::Strptime 93DateTime::Format::ISO8601 (>=0.06) 94DateTime::TimeZone 95Class::Accessor 96Class::Accessor::Chained 97Time::HiRes 98Email::Valid 99IO::Socket::INET (*) 100IO::Socket::SSL (>=0.90) 101XML::LibXML (>=1.61) 102UNIVERSAL::require 103SOAP::Lite (needed only for AFNIC, BookMyName, OVH, Gandi webservices) 104SOAP::WSDL (needed only for OVH webservices) 105MIME::Entity (needed only for AFNIC emails) 106Net::SMTP (needed only for AFNIC emails) 107LWP::UserAgent (needed only for OpenSRS, .PL and .IT) 108Digest::MD5 (needed only for OpenSRS) 109Net::DNS (needed only for .DE IRIS DCHK queries) 110IO::Uncompress::RawInflate (needed only for .DE IRIS DCHK queries) (*) 111 112 113All dates and durations exchanged with Net::DRI should be 114DateTime and DateTime::Duration objects 115 116Modules marked (*) are core Perl modules. 117 118Install 119------- 120 121Use the standard procedure: 122perl Makefile.PL ; make ; make test ; make install 123Or just copy the content of the lib/ directory somewhere in your path. 124You can use tests available in t/ to make sure everything is well. 125(all tests are done locally and do not require a network connection; 126those who require a network connection are not enabled by default) 127 128LICENSE INFORMATION 129------------------- 130 131This program is free software; you can redistribute it and/or modify 132it under the terms of the GNU General Public License as published by 133the Free Software Foundation; either version 2 of the License, or 134(at your option) any later version. 135 136This program is distributed in the hope that it will be useful, 137but WITHOUT ANY WARRANTY; without even the implied warranty of 138MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 139GNU General Public License for more details. 140 141See the accompanying LICENSE file for all details. 142 143Some parts of this library have been contributed by other authors, 144and are copyrighted to them. See each specific module documentation. 145 146How to use 147---------- 148 149You can find examples in the eg subdirectory: 150 151afnic_ws.pl : as AFNIC member, to use AFNIC web services 152afnic_email.pl : as AFNIC member, to use the email robot 153ws_rrp.pl : as registrar, to connect to .WS using RRP 154eurid_epp.pl : as registrar, connect to EURid test systems 155cat_epp.pl : as registrar, connect to .CAT test systems 156coop_epp.pl : as registrar, connect to .COOP test systems 157epp_client_no.pl (+ xmlfilter.pl) : as registrar, do operations with the .NO registry 158das.pl : for anyone, to check domain availability in various TLDs 159whois.pl : for anyone, to do whois queries for some TLDs. 160iris_dchk.pl : for anyone, to do IRIS DCHK queries for some .DE domain names 161 162In the t subdirectory, the test files can also be studied for insight 163of all the API available. 164 165All errors trigger an exception using die and a specific class 166(Net::DRI::Exception). Thus all calls to Net::DRI methods should be 167put in an eval() to easily trap exceptions. Please see Net::DRI::Exception 168for details about information available when an exception is raised. 169 170Net::DRI uses an internal cache (in the future many different backends will 171be available for this service), and you can provide the global time to live of objects 172in it when you create the Net::DRI object. A negative ttl means no cache at all. 173It is recommended not to completely disable the cache, and to have a ttl of at 174least of few seconds: it will cut down the use of checks and related verifications 175done at registry, especially for complex operations. 176 177Typical use of this library would be like the following 178(but please not that parts of this documentation may be outdated, 179and you should double check inside the Changes file as well as the examples 180described above and the test files): 181 182- $dri=Net::DRI->new(...) to create the global object. Save the result, 183 everything will be done with methods applied on this object. 184 You can choose the logging you wish (among base modules provided: no logging 185 at all, all logging to STDERR and logging into files, one per registry+profile) 186 and the cache time to live. See Net::DRI module documentation for more information 187 on caching and logging. 188 189- $dri->add_registry(...) to add a new registry driver 190 First argument is the registry class name (Net::DRI::DRD:: will be added if no :: is found), 191 second argument is an hash ref setting information : you should have at least 192 a clid key whose value is the client identifier at this registry for the client connecting 193 (this is needed for the various _is_mine() methods - see below) 194 195 You can attach as many registry drivers as you need to a single Net::DRI object 196 this would enable you to easily operate on multiple registries at the same time 197 Use $dri->target('registry name') to set the current registry, the one which 198 will receive all future calls. 199 The target method returns the $dri object, thus can be chained with other calls. 200 Besides the registry name you can also pass a domain name or a TLD, and the library 201 will try to find the correct registry. This will work only if you have no overlap between 202 your TLDs among various registries 203 204- $dri->add_profile('profilename','profiletype',{transport params},{protocol params}) 205 (or add_current_profile with same parameters as in add_profile and it will also 206 set the default profile to the one being created) 207 to use registry driver default for profiletype (see transport_protocol_default in each DRD modules) 208 for transport & protocol classes. 209 210 Each registry driver is used through a specific profile. Each driver can have at the same time 211 as many profiles as needed. 212 A profile is: 213 - a name 214 - a transport, with specific parameters 215 - a protocol, with specific parameters 216 217 This enables you to be connected to the same registries with different credentials at the same 218 time, or through different transports, if the registry provides for example access by email 219 and by TCP at the same time. 220 221 You switch profile using the $dri->target('registry name','profile name') call. 222 223 add_profile() and add_current_profile() return a Net::DRI::Protocol::ResultStatus 224 in all cases, and this should be tested with ->is_success() to be sure the profile 225 has been created correctly. 226 They may also die for some other internal errors. 227 228 Optionnally, you can use an auto target function: 229 by providing details about which profile to use for each given action, 230 Net::DRI can switch to the profile needed automatically, thus you will not need 231 anymore to call target() by yourself. 232 To do that, you will need to provide information by calling: 233 $dri->set_auto_target('profile','type','action') 234 Profile is the profile name to use when doing 235 action 'action' (check, info, create, etc...) on object type 'type' (domain, host, contact). 236 The profile must exist before calling set_auto_target() 237 A default profile can be specified when type and/or action is undef. 238 239- after registries and profiles have been created (others can be added at any time), 240 you can apply many methods (see below) to the $dri object 241 You can change the current registry and/or current profile at any time using $dri->target(...,...) 242 243 You get back for most of the calls an object representing the status. 244 It is an instance of Net::DRI::Protocol::ResultStatus, please see its documentation. 245 Through it you can access all details about the operation that has been done, including 246 raw data, using the get_data() and get_data_collection() methods (see module documentation). 247 As long as you keep the object, the data is there, and will not be deleted, while data 248 in cache (and accessed through $dri->get_info()) will be deleted after its time to live 249 has elapsed. 250 251 You can also always use: 252 result_is_success() result_code() result_native_code() result_message() result_lang() 253 result_is_pending() result_trid() methods 254 to get back the same information (if not given by the methods or if you want to discard output) 255 256 Information that has been sent by registry will also be available through $dri->get_info(...) 257 with a specific key. The key to use depends on the operation, but should be mostly registry-independent. 258 get_info() gives back information related to the latest operation. 259 If you use target() and later get_info() you will get information related to the latest operation 260 for the registry/profile specified in the target() call. 261 262 See below the list of methods you can call, and information available after each in get_info() 263 264- when you are finished, call $dri->end() to deallocate ressources and close any open connections. 265 266 267If using the Socket transport, you can make sure the connection is still open by using the 268ping() method, such as : $dri->transport()->ping() 269It will return 1 if the connection is still there, 0 otherwise. 270If you pass a true value to ping(), it will automatically reconnect if the connection is broken. 271 272Available API 273------------- 274 275Please see the included tests (directory t/) and examples (directory eg/) for many 276examples of use and full API coverage. 277 278* has_object($type) 279 280 gives 1 if the registry manages objects of type $type (domain, ns, contact, etc...) 281 282* periods() 283 284 gives the list of all registration periods allowed by the current registry. 285 Periods are given as DateTime::Duration objects. 286 287* is_my_tld() 288 289 with a domain name as argument, returns 1 if the current registry handles this 290 domain name (TLD of domain name is handled by registry) 291 292* cache_clear() 293 294 completely delete cache for current registry and current profile 295 296* verify_name_domain() verify_name_host() 297 298 gives 0 if the given argument is a correct name for a domain name or an hostname 299 at the current registry. 300 301* verify_duration_create() verify_duration_renew() verify_duration_transfer() 302 303 called internally at various stages in Net::DRI to verify that we can add/renew/transfer 304 a domain name 305 306* domain_create() 307 308 Create a domain name and associated operations (except if pure creation is asked) 309 at the current registry and current profile. A domain name and an hash ref should be provided. 310 The hash ref can have a "duration" key with its value being a DateTime::Duration object, 311 and a "ns" key with its value being a Net::DRI::Data::Hosts object. 312 313 The following operations are done (if pure creation is asked, only step 4 is done): 314 315 0) we do a domain_check operation and stop if the domain exists already 316 1) we separate nameservers : those being inside domain name being created, those being outside 317 2) we test outside nameservers for existence at registry, and if it fails, we try to create them 318 3) we create all needed contacts, for thick registries 319 4) we create domain 320 5) we create nameservers that are inside domain (in-bailiwick nameservers) 321 6) we update domain to add nameservers created at step 5. 322 7) if a status key exists in hash ref given, we try to change status of newly created domain name 323 324 You get back a ResultStatus that may contain all results chained, see this module documentation. 325 326 You may use get_info with the following keys to get more information: 327 - exDate : for the current expiration date (a DateTime object) 328 - status : for the current status of domain name 329 330* domain_delete() 331 332 Delete a domain and associated opeations (except if a pure deletion is askedt) 333 at the current registry and current profile. 334 A domain name should be provided. 335 336 The following operations are done (if pure delete is asked, only step 3 is done): 337 338 1) we find the current list of nameservers for this domain 339 2) we remove all nameservers from this domain 340 3) we delete the domain name 341 (which can fail if some nameservers use the domain name in their FQDN, 342 we should try to rename them first, it is planned for later) 343 344 See domain_create() for information on what you get back. 345 346* domain_info() 347 348 Ask for all information on a given domain name at the current registry and current profile. 349 A second optional parameter is an hash ref. It can include an auth key, for EPP registries for example. 350 351 You may use get_info or ResultStatus::get_data with the following keys to get more information: 352 - ns : a Net::DRI::Data::Hosts object representing the nameservers of the domain 353 - status : a Net::DRI::Data::StatusList object representing the current status list of the domain queried 354 - exDate, crDate, upDate, trDate : DateTime objects representing the expiration, creation, last update, and 355 transfer date for the domain queried 356 - clID, crID, upID : (strings) local registry ID of the current sponsoring registrar, the registrar having created, 357 and the registrar (or registry) having last modified the domain queried 358 359* domain_check() 360 361 Check if a domain name exists or not at the current registry and current profile. 362 363 $dri->get_info('exist') returns 0 or 1 364 365* domain_check_multi() 366 367 Check if the given list of domain names exist or not at the current registry and current profile. 368 369 $dri->get_info('exist','domain',$domain) returns 0 or 1 for the given domain name in $domain 370 (the cache ttl must be positive and large enough (few seconds) for that to work) ; 371 you can also use $rc->get_data('domain',$domain,'exist') - please note the different API - 372 which will always have data, independently from cache. 373 374* domain_exist() 375 376 Same as previous, but we get back 0 or 1 if the domain does not exist/exist or undef if we do not know. 377 378* domain_update() 379 380 Update the domain name given as argument at the current registry and current profile. 381 Most of the time you should use the following more specific methods. 382 383* domain_update_ns() 384 385 Update nameservers of the domain name given as argument at the current registry and current profile. 386 Most of the time you should use the following more specific methods. 387 388* domain_update_ns_add() 389 390 For the given domain name as first argument, 391 add the nameservers given as second argument (being a Net::DRI::Data::Hosts object). 392 393* domain_update_ns_del() 394 395 Same as previous to delete nameservers 396 397* domain_update_ns_set() 398 399 Same as previous to set the current list of nameservers, irrespective to what they are now. 400 401* domain_update_status() 402 403 Update statuses of the domain name given as argument at the current registry and current profile. 404 Most of the time you should use the following more specific methods. 405 406* domain_update_status_add() 407 408 For the given domain name as first argument, add the statuses given as second argument. 409 410 To create the second argument, call $dri->create_status()->no() 411 with up to three parameters : 412 - first one is a string among renew, update, transfer, publish, delete (choices depending on the registry), 413 which sets what is forbidden, 414 - second (optional) one is a message (ex: Payment overdue), 415 - third (optional, default to 'en') is the language of the previous message. 416 417 The call to ->create_status() creates a new object from a class which is a subclass of Net::DRI::Data::StatusList, 418 that can be used in all functions related to statuses. 419 420* domain_update_status_del() 421 422 Same as previous to delete statuses. 423 424* domain_update_status_set() 425 426 Same as previous to set the current list of status, irrespective to what they are now. 427 428* domain_update_contact() 429 430 Update contacts of the domain name given as argument at the current registry and current profile. 431 Most of the time you should use the following more specific methods. 432 433* domain_update_contact_add() 434 435 For the given domain name as first argument, add the contacts given as second argument which is a 436 Net::DRI::Data::ContactSet instance. 437 438* domain_update_contact_del() 439 440 Same as previous to delete contacts. 441 442* domain_update_contact_set() 443 444 Same as previous to set the current list of contacts, irrespective to what they are now. 445 446* domain_renew() 447 448 Renew the domain name provided as first argument, 449 with optionnally a ref hash, with keys duration and current_expiration. 450 451 You may use get_info() to retrieve the same information as after domain_create() 452 453* domain_transfer() 454 455 Various operations related to transfers of domain names. 456 Most of the time you should use the following more specific methods. 457 458* domain_transfer_start() 459 460 Start the transfer of the given domain name as first argument. 461 A second optional argument is an hash ref that can include for example an auth key for authorization information. 462 463* domain_transfer_stop() 464 465 Stop the transfer of the given domain name as first argument (used by the registrar having started the transfer). 466 A second optional argument is an hash ref that can include for example an auth key for authorization information. 467 468* domain_transfer_query() 469 470 Query the state of the ongoing transfer for the given domain name as first argument. 471 A second optional argument is an hash ref that can include for example an auth key for authorization information. 472 473* domain_transfer_accept() 474 475 Accept the transfer of the given domain name as first argument (used by the registrar currently sponsoring the domain name). 476 A second optional argument is an hash ref that can include for example an auth key for authorization information. 477 478* domain_transfer_refuse() 479 480 Refuse the transfer of the given domain name as first argument (used by the registrar currently sponsoring the domain name). 481 A second optional argument is an hash ref that can include for example an auth key for authorization information. 482 483* domain_can() 484 485 For the domain name given as first argument, and for the operation given as second 486 (being either 'renew','update','delete' or 'tranfer'), returns 1 if we can 487 do the requested operation at the current registry and current profile. 488 We check the domain name status, and if possible who sponsors currently the domain name, 489 and if the action requested needs sponsorship. 490 491* domain_status_allows() 492 493 Check if the current status of the domain name given as first argument allows 494 for a specific operation. 495 Most of the time you should use the following more specific methods. 496 497* domain_status_allows_delete() 498 499 Returns 1 if we can delete the domain name given as first argument at the current registry and current profile. 500 Else, 0. 501 502* domain_status_allows_update() 503 504 Same for update. 505 506* domain_status_allows_renew() 507 508 Same for renew. 509 510* domain_status_allows_transfer() 511 512 Same for transfer. 513 514* domain_current_status() 515 516 Returns the status of the domain name given as first argument at the current registry and current profile. 517 (status is a Net::DRI::Data::StatusList or subclass object) 518 519* domain_is_mine() 520 521 Returns 1 if we are the current sponsor of the domain name given as first argument 522 at the current registry and current profile. 523 Else, 0. 524 525* host_create() 526 527 Create a new nameserver. The first argument should be a Net::DRI::Data::Hosts object. 528 Some registries may require or permit a second argument, used in the same way as in domain_create() 529 530* host_delete() 531 532 Delete a nameserver. The first and only argument should be a Net::DRI::Data::Hosts object or a string. 533 534* host_info() 535 536 Retrieve information about a namserver. The first and only argument should be a Net::DRI::Data::Hosts object or a string. 537 538 You may use get_info with the following keys to get more information: 539 - self : a Net::DRI::Data::Hosts for the nameserver itself (name + IP addresses) 540 - exDate, crDate, upDate, trDate, clID, crID, upID : see domain_info() 541 542* host_check() 543* host_check_multi() 544* host_exist() 545* host_update() 546* host_update_ip() 547* host_update_ip_add() 548* host_update_ip_del() 549* host_update_ip_set() 550* host_update_status() 551* host_update_status_add() 552* host_update_status_del() 553* host_update_status_set() 554* host_update_name_set() 555* host_current_status() 556* host_is_mine() 557 558See corresponding domain_* methods. 559 560* contact_create() 561 562 Create a new contact at registry. The first and only argument should be a Net::DRI::Data::Contact object (or one of its subclasses). 563 564* contact_delete() 565* contact_info() 566* contact_check() 567* contact_check_multi() 568* contact_exist() 569* contact_update() 570* contact_update_status() 571* contact_update_status_add() 572* contact_update_status_del() 573* contact_update_status_set() 574* contact_transfer() 575* contact_transfer_start() 576* contact_transfer_stop() 577* contact_transfer_query() 578* contact_transfer_accept() 579* contact_transfer_refuse() 580* contact_is_mine() 581 582See above methods. 583 584* message_retrieve() message_delete() message_waiting() message_count() : to handle registry messages (see t/601vnds_epp.t) 585