Provided by: libnet-epp-perl_0.26-1_all bug

Name

       Net::EPP::Simple - a simple EPP client interface for the most common jobs.

Synopsis

               #!/usr/bin/perl
               use Net::EPP::Simple;
               use strict;

               my $epp = Net::EPP::Simple->new(
                       host    => 'epp.nic.tld',
                       user    => 'my-id',
                       pass    => 'my-password',
               );

               my $domain = 'example.tld';

               if ($epp->check_domain($domain) == 1) {
                       print "Domain is available\n" ;

               } else {
                       my $info = $epp->domain_info($domain);
                       printf("Domain was registered on %s by %s\n", $info->{crDate}, $info->{crID});

               }

Description

       This module provides a high level interface to EPP. It hides all the boilerplate of
       connecting, logging in, building request frames and parsing response frames behind a
       simple, Perlish interface.

       It is based on the Net::EPP::Client module and uses Net::EPP::Frame to build request
       frames.

Constructor

       The constructor for "Net::EPP::Simple" has the same general form as the one for
       Net::EPP::Client, but with the following exceptions:

       •   Unless otherwise set, "port" defaults to 700

       •   Unless the "no_ssl" parameter is set, SSL is always on

       •   You can use the "user" and "pass" parameters to supply authentication information.

       •   You can use the "newPW" parameter to specify a new password.

       •   The "login_security" parameter can be used to force the use of the Login Security
           Extension (see RFC8807). "Net::EPP::Simple" will automatically use this extension if
           the server supports it, but clients may wish to force this behaviour to prevent
           downgrade attacks.

       •   The "appname" parameter can be used to specify the value of the "<app<gt"> element in
           the Login Security extension (if used). Unless specified, the name and current version
           of "Net::EPP::Simple" will be used.

       •   The "timeout" parameter controls how long the client waits for a response from the
           server before returning an error.

       •   if "debug" is set, "Net::EPP::Simple" will output verbose debugging information on
           "STDERR", including all frames sent to and received from the server.

       •   "reconnect" can be used to disable automatic reconnection (it is enabled by default).
           Before sending a frame to the server, "Net::EPP::Simple" will send a "<hello>" to
           check that the connection is up, if not, it will try to reconnect, aborting after the
           nth time, where n is the value of "reconnect" (the default is 3).

       •   "login" can be used to disable automatic logins. If you set it to 0, you can manually
           log in using the "$epp->_login()" method.

       •   "objects" is a reference to an array of the EPP object schema URIs that the client
           requires.

       •   "stdobj" is a flag saying the client only requires the standard EPP "contact-1.0",
           "domain-1.0", and "host-1.0" schemas.

       •   If neither "objects" nor "stdobj" is specified then the client will echo the server's
           object schema list.

       •   "extensions" is a reference to an array of the EPP extension schema URIs that the
           client requires.

       •   "stdext" is a flag saying the client only requires the standard EPP "secDNS-1.1"
           DNSSEC extension schema.

       •   If neither "extensions" nor "stdext" is specified then the client will echo the
           server's extension schema list.

       •   The "lang" parameter can be used to specify the language. The default is ""en"".

       The constructor will establish a connection to the server and retrieve the greeting (which
       is available via "$epp->{greeting}") and then send a "<login>" request.

       If the login fails, the constructor will return "undef" and set $Net::EPP::Simple::Error
       and $Net::EPP::Simple::Code.

   Client and Server SSL options
       RFC 5730 requires that all EPP instances must be protected using "mutual, strong client-
       server authentication". In practice, this means that both client and server must present
       an SSL certificate, and that they must both verify the certificate of their peer.

       Server Certificate Verification

       "Net::EPP::Simple" will verify the certificate presented by a server if the "verify", and
       either "ca_file" or "ca_path" are passed to the constructor:

               my $epp = Net::EPP::Simple->new(
                       host    => 'epp.nic.tld',
                       user    => 'my-id',
                       pass    => 'my-password',
                       verify  => 1,
                       ca_file => '/etc/pki/tls/certs/ca-bundle.crt',
                       ca_path => '/etc/pki/tls/certs',
               );

       "Net::EPP::Simple" will fail to connect to the server if the certificate is not valid.

       You can disable SSL certificate verification by omitting the "verify" argument or setting
       it to "undef". This is strongly discouraged, particularly in production environments.

       SSL Cipher Selection

       You can restrict the ciphers that you will use to connect to the server by passing a
       "ciphers" parameter to the constructor. This is a colon- separated list of cipher names
       and aliases. See <http://www.openssl.org/docs/apps/ciphers.html#CIPHER_STRINGS> for
       further details. As an example, the following cipher list is suggested for clients who
       wish to ensure high-security connections to servers:

               HIGH:!ADH:!MEDIUM:!LOW:!SSLv2:!EXP

       Client Certificates

       If you are connecting to an EPP server which requires a client certificate, you can
       configure "Net::EPP::Simple" to use one as follows:

           my $epp = Net::EPP::Simple->new(
               host        => 'epp.nic.tld',
               user        => 'my-id',
               pass        => 'my-password',
               key         => '/path/to/my.key',
               cert        => '/path/to/my.crt',
               passphrase  => 'foobar123',
           );

       "key" is the filename of the private key, "cert" is the filename of the certificate. If
       the private key is encrypted, the "passphrase" parameter will be used to decrypt it.

   Configuration File
       "Net::EPP::Simple" supports the use of a simple configuration file. To use this feature,
       you need to install the Config::Simple module.

       When starting up, "Net::EPP::Simple" will look for "$HOME/.net-epp-simple-rc". This file
       is an ini-style configuration file.

       Default Options

       You can specify default options for all EPP servers using the "[default]" section:

               [default]
               default=epp.nic.tld
               debug=1

       Server Specific Options

       You can specify options for for specific EPP servers by giving each EPP server its own
       section:

               [epp.nic.tld]
               user=abc123
               pass=foo2bar
               port=777
               ssl=0

       This means that when you write a script that uses "Net::EPP::Simple", you can do the
       following:

               # config file has a default server:
               my $epp = Net::EPP::Simple->new;

               # config file has connection options for this EPP server:
               my $epp = Net::EPP:Simple->new('host' => 'epp.nic.tld');

       Any parameters provided to the constructor will override those in the config file.

Availability Checks

       You can do a simple "<check>" request for an object like so:

               my $result = $epp->check_domain($domain);

               my $result = $epp->check_host($host);

               my $result = $epp->check_contact($contact);

       Each of these methods has the same profile. They will return one of the following:

       •   "undef" in the case of an error (check $Net::EPP::Simple::Error and
           $Net::EPP::Simple::Code).

       •   0 if the object is already provisioned.

       •   1 if the object is available.

Retrieving Object Information

   Domain Objects
               my $info = $epp->domain_info($domain, $authInfo, $follow);

       This method constructs an "<info>" frame and sends it to the server, then parses the
       response into a simple hash ref. If there is an error, this method will return "undef",
       and you can then check $Net::EPP::Simple::Error and $Net::EPP::Simple::Code.

       If $authInfo is defined, it will be sent to the server as per RFC 5731, Section 3.1.2.

       If the $follow parameter is true, then "Net::EPP::Simple" will also retrieve the relevant
       host and contact details for a domain: instead of returning an object name or ID for the
       domain's registrant, contact associations, DNS servers or subordinate hosts, the values
       will be replaced with the return value from the appropriate "host_info()" or
       "contact_info()" command (unless there was an error, in which case the original object ID
       will be used instead).

   Host Objects
               my $info = $epp->host_info($host);

       This method constructs an "<info>" frame and sends it to the server, then parses the
       response into a simple hash ref. If there is an error, this method will return "undef",
       and you can then check $Net::EPP::Simple::Error and $Net::EPP::Simple::Code.

   Contact Objects
               my $info = $epp->contact_info($contact, $authInfo, $roid);

       This method constructs an "<info>" frame and sends it to the server, then parses the
       response into a simple hash ref. If there is an error, this method will return "undef",
       and you can then check $Net::EPP::Simple::Error and $Net::EPP::Simple::Code.

       If $authInfo is defined, it will be sent to the server as per RFC RFC 5733, Section 3.1.2.

       If the $roid parameter to "host_info()" is set, then the "roid" attribute will be set on
       the "<authInfo>" element.

   Domain Information
       The hash ref returned by "domain_info()" will usually look something like this:

               $info = {
                 'contacts' => {
                   'admin' => 'contact-id'
                   'tech' => 'contact-id'
                   'billing' => 'contact-id'
                 },
                 'registrant' => 'contact-id',
                 'clID' => 'registrar-id',
                 'roid' => 'tld-12345',
                 'status' => [
                   'ok'
                 ],
                 'authInfo' => 'abc-12345',
                 'name' => 'example.tld',
                 'trDate' => '2011-01-18T11:08:03.0Z',
                 'ns' => [
                   'ns0.example.com',
                   'ns1.example.com',
                 ],
                 'crDate' => '2011-02-16T12:06:31.0Z',
                 'exDate' => '2011-02-16T12:06:31.0Z',
                 'crID' => 'registrar-id',
                 'upDate' => '2011-08-29T04:02:12.0Z',
                 hosts => [
                   'ns0.example.tld',
                   'ns1.example.tld',
                 ],
               };

       Members of the "contacts" hash ref may be strings or, if there are multiple associations
       of the same type, an anonymous array of strings.  If the server uses the Host Attribute
       model instead of the Host Object model, then the "ns" member will look like this:

               $info->{ns} = [
                 {
                   name => 'ns0.example.com',
                   addrs => [
                     version => 'v4',
                     addr => '10.0.0.1',
                   ],
                 },
                 {
                   name => 'ns1.example.com',
                   addrs => [
                     version => 'v4',
                     addr => '10.0.0.2',
                   ],
                 },
               ];

       Note that there may be multiple members in the "addrs" section and that the "version"
       attribute is optional.

   Host Information
       The hash ref returned by "host_info()" will usually look something like this:

               $info = {
                 'crDate' => '2011-09-17T15:38:56.0Z',
                 'clID' => 'registrar-id',
                 'crID' => 'registrar-id',
                 'roid' => 'tld-12345',
                 'status' => [
                   'linked',
                   'serverDeleteProhibited',
                 ],
                 'name' => 'ns0.example.tld',
                 'addrs' => [
                   {
                     'version' => 'v4',
                     'addr' => '10.0.0.1'
                   }
                 ]
               };

       Note that hosts may have multiple addresses, and that "version" is optional.

   Contact Information
       The hash ref returned by "contact_info()" will usually look something like this:

               $VAR1 = {
                 'id' => 'contact-id',
                 'postalInfo' => {
                   'int' => {
                     'name' => 'John Doe',
                     'org' => 'Example Inc.',
                     'addr' => {
                       'street' => [
                         '123 Example Dr.'
                         'Suite 100'
                       ],
                       'city' => 'Dulles',
                       'sp' => 'VA',
                       'pc' => '20116-6503'
                       'cc' => 'US',
                     }
                   }
                 },
                 'clID' => 'registrar-id',
                 'roid' => 'CNIC-HA321983',
                 'status' => [
                   'linked',
                   'serverDeleteProhibited'
                 ],
                 'voice' => '+1.7035555555x1234',
                 'fax' => '+1.7035555556',
                 'email' => 'jdoe@example.com',
                 'crDate' => '2011-09-23T03:51:29.0Z',
                 'upDate' => '1999-11-30T00:00:00.0Z'
               };

       There may be up to two members of the "postalInfo" hash, corresponding to the "int" and
       "loc" internationalised and localised types.

Object Transfers

       The EPP "<transfer>" command suppots five different operations: query, request, cancel,
       approve, and reject. "Net::EPP::Simple" makes these available using the following methods:

               # For domain objects:

               $epp->domain_transfer_query($domain);
               $epp->domain_transfer_cancel($domain);
               $epp->domain_transfer_request($domain, $authInfo, $period);
               $epp->domain_transfer_approve($domain);
               $epp->domain_transfer_reject($domain);

               # For contact objects:

               $epp->contact_transfer_query($contact);
               $epp->contact_transfer_cancel($contact);
               $epp->contact_transfer_request($contact, $authInfo);
               $epp->contact_transfer_approve($contact);
               $epp->contact_transfer_reject($contact);

       Most of these methods will just set the value of $Net::EPP::Simple::Code and return either
       true or false. However, the "domain_transfer_request()", "domain_transfer_query()",
       "contact_transfer_request()" and "contact_transfer_query()" methods will return a hash ref
       that looks like this:

               my $trnData = {
                 'name' => 'example.tld',
                 'reID' => 'losing-registrar',
                 'acDate' => '2011-12-04T12:24:53.0Z',
                 'acID' => 'gaining-registrar',
                 'reDate' => '2011-11-29T12:24:53.0Z',
                 'trStatus' => 'pending'
               };

Creating Objects

       The following methods can be used to create a new object at the server:

               $epp->create_domain($domain);
               $epp->create_host($host);
               $epp->create_contact($contact);

       The argument for these methods is a hash ref of the same format as that returned by the
       info methods above. As a result, cloning an existing object is as simple as the following:

               my $info = $epp->contact_info($contact);

               # set a new contact ID to avoid clashing with the existing object
               $info->{id} = $new_contact;

               # randomize authInfo:
               $info->{authInfo} = $random_string;

               $epp->create_contact($info);

       "Net::EPP::Simple" will ignore object properties that it does not recognise, and those
       properties (such as server-managed status codes) that clients are not permitted to set.

   Creating New Domains
       When creating a new domain object, you may also specify a "period" key, like so:

               my $domain = {
                 'name' => 'example.tld',
                 'period' => 2,
                 'registrant' => 'contact-id',
                 'contacts' => {
                   'tech' => 'contact-id',
                   'admin' => 'contact-id',
                   'billing' => 'contact-id',
                 },
                 'status' => [
                   'clientTransferProhibited',
                 ],
                 'ns' => {
                   'ns0.example.com',
                   'ns1.example.com',
                 },
               };

               $epp->create_domain($domain);

       The "period" key is assumed to be in years rather than months. "Net::EPP::Simple" assumes
       the registry uses the host object model rather than the host attribute model.

   Creating Hosts
           my $host = {
               name  => 'ns1.example.tld',
               addrs => [
                   { ip => '123.45.67.89', version => 'v4' },
                   { ip => '98.76.54.32',  version => 'v4' },
               ],
           };
           $epp->create_host($host);

Updating Objects

       The following methods can be used to update an object at the server:

               $epp->update_domain($domain);
               $epp->update_host($host);
               $epp->update_contact($contact);

       Each of these methods has the same profile. They will return one of the following:

       •   undef in the case of an error (check $Net::EPP::Simple::Error and
           $Net::EPP::Simple::Code).

       •   1 if the update request was accepted.

       You may wish to check the value of $Net::EPP::Simple::Code to determine whether the
       response code was 1000 (OK) or 1001 (action pending).

   Updating Domains
       Use update_domain() method to update domains' data.

       The update info parameter may look like: $update_info = {
           name => $domain,
           chg  => {
               registrant => $new_registrant_id,
               authInfo   => $new_domain_password,
           },
           add => {
               # DNS info with "hostObj" or "hostAttr" model, see create_domain()
               ns       => [ ns1.example.com ns2.example.com ],
               contacts => {
                   tech    => 'contact-id',
                   billing => 'contact-id',
                   admin   => 'contact-id',
               },

               # Status info, simple form:
               status => [ qw/ clientUpdateProhibited clientHold / ],

               # Status info may be in more detailed form:
               # status => {
               #    clientUpdateProbhibited  => 'Avoid accidental change',
               #    clientHold               => 'This domain is not delegated',
               # },
           },
           rem => {
               ns       => [ ... ],
               contacts => {
                   tech    => 'old_tech_id',
                   billing => 'old_billing_id',
                   admin   => 'old_admin_id',
               },
               status => [ qw/ clientTransferProhibited ... / ],
           },
       }

       All fields except 'name' in $update_info hash are optional.

   Updating Contacts
       Use update_contact() method to update contact's data.

       The $update_info for contacts may look like this:

       $update_info = {
           id  => $contact_id,
           add => {
               status => [ qw/ clientDeleteProhibited / ],
               # OR
               # status => {
               #    clientDeleteProhibited  => 'Avoid accidental removal',
               # },
           },
           rem => {
               status => [ qw/ clientUpdateProhibited / ],
           },
           chg => {
               postalInfo => {
                   int => {
                         name => 'John Doe',
                         org => 'Example Inc.',
                         addr => {
                           street => [
                             '123 Example Dr.'
                             'Suite 100'
                           ],
                           city => 'Dulles',
                           sp => 'VA',
                           pc => '20116-6503'
                           cc => 'US',
                     },
                   },
               },
               voice => '+1.7035555555x1234',
               fax   => '+1.7035555556',
               email => 'jdoe@example.com',
               authInfo => 'new-contact-password',
           }, }

       All fields except 'id' in $update_info hash are optional.

   Updating Hosts
       Use update_host() method to update EPP hosts.

       The $update_info for hosts may look like this:

       $update_info = {
           name => 'ns1.example.com',
           add  => {
               status => [ qw/ clientDeleteProhibited / ],
               # OR
               # status => {
               #    clientDeleteProhibited  => 'Avoid accidental removal',
               # },

               addrs  => [
                   { ip => '123.45.67.89', version => 'v4' },
                   { ip => '98.76.54.32',  version => 'v4' },
               ],
           },
           rem => {
               status => [ qw/ clientUpdateProhibited / ],
               addrs  => [
                   { ip => '1.2.3.4', version => 'v4' },
                   { ip => '5.6.7.8', version => 'v4' },
               ],
           },
           chg => {
               name => 'ns2.example.com',
           },
       }

       All fields except first 'name' in $update_info hash are optional.

Deleting Objects

       The following methods can be used to delete an object at the server:

               $epp->delete_domain($domain);
               $epp->delete_host($host);
               $epp->delete_contact($contact);

       Each of these methods has the same profile. They will return one of the following:

       •   undef in the case of an error (check $Net::EPP::Simple::Error and
           $Net::EPP::Simple::Code).

       •   1 if the deletion request was accepted.

       You may wish to check the value of $Net::EPP::Simple::Code to determine whether the
       response code was 1000 (OK) or 1001 (action pending).

Domain Renewal

       You can extend the validity period of the domain object by issuing a renew_domain()
       command.

        my $result = $epp->renew_domain({
            name         => 'example.com',
            cur_exp_date => '2011-02-05',  # current expiration date
            period       => 2,             # prolongation period in years
        });

       Return value is 1 on success and "undef" on error.  In the case of error
       $Net::EPP::Simple::Error contains the appropriate error message.

Miscellaneous Methods

               my $greeting = $epp->greeting;

       Returns the a Net::EPP::Frame::Greeting object representing the greeting returned by the
       server.

               $epp->ping;

       Checks that the connection is up by sending a "<hello>" to the server. Returns false if no
       response is received.

Overridden Methods From Net::EPP::Client

       "Net::EPP::Simple" overrides some methods inherited from Net::EPP::Client. These are
       described below:

   The "request()" Method
       "Net::EPP::Simple" overrides this method so it can automatically populate the "<clTRID>"
       element with a unique string. It then passes the frame back up to Net::EPP::Client.

   The "get_frame()" Method
       "Net::EPP::Simple" overrides this method so it can catch timeouts and network errors. If
       such an error occurs it will return "undef".

               $connected = $epp->connected;

       Returns a boolean if "Net::EPP::Simple" has a connection to the server. Note that this
       connection might have dropped, use "ping()" to test it.

               $authenticated = $epp->authenticated;

       Returns a boolean if "Net::EPP::Simple" has successfully authenticated with the server.

Package Variables

   $Net::EPP::Simple::Error
       This variable contains an english text message explaining the last error to occur. This is
       may be due to invalid parameters being passed to a method, a network error, or an error
       response being returned by the server.

   $Net::EPP::Simple::Message
       This variable contains the contains the text content of the "<msg>" element in the
       response frame for the last transaction.

   $Net::EPP::Simple::Code
       This variable contains the integer result code returned by the server for the last
       transaction. A successful transaction will always return an error code of 1999 or lower,
       for an unsuccessful transaction it will be 2011 or more. If there is an internal client
       error (due to invalid parameters being passed to a method, or a network error) then this
       will be set to 2400 ("COMMAND_FAILED"). See Net::EPP::ResponseCodes for more information
       about thes codes.