--- name: "Net::EPP::Client" section: "3pm" platform: "linux" package: "libnet-epp-perl" version: "0.28-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Net::EPP::Client" --- # Net::EPP::Client(3pm) a client library for the TLS transport \ of the Extensible Provisioning Protocol (EPP) \. ## NAME Net::EPP::Client - a client library for the TLS transport \ of the Extensible Provisioning Protocol (EPP) \. ## SYNOPSIS ``` #!/usr/bin/perl use Net::EPP::Client; use strict; my $epp = Net::EPP::Client->new('host' => 'epp.nic.tld'); my $greeting = $epp->connect; $epp->send_frame('login.xml'); my $answer = $epp->get_frame; my $answer = $epp->request(''); ``` ## DESCRIPTION RFC 5743 \ defines a TCP- (and TLS-) based transport model for EPP, and this module implements a client for that model. You can establish and manage EPP connections and send and receive responses over this connection. `"Net::EPP::Client"` is a low-level EPP client. If you are writing applications, you should use Net::EPP::Simple instead. ## CONSTRUCTOR ``` my $epp = Net::EPP::Client->new(%PARAMS); ``` The constructor method creates a new EPP client object. It accepts a number of parameters: - • `"host"` MANDATORY. Specifies the computer to connect to. This may be a DNS hostname or an IP address. If a hostname is provided, IPv6 will be used if available. - • `"port"` OPTIONAL. Specifies the TCP port to connect to. This defaults to `700`. - • `"ssl"` OPTIONAL. If the value of this parameter is false, then a plaintext connection will be created. Otherwise, IO::Socket::SSL will be used to provide an encrypted connection. - • `"frames"` DEPRECATED. If the value of this parameter is false, then the `request()` and `get_frame()` methods (see below) will return strings instead of `"Net::EPP::Frame::Response"` objects. ## METHODS ### CONNECTING TO A SERVER ``` my $greeting = $epp->connect(%PARAMS); ``` This method establishes the TCP connection. You can use the `%PARAMS` hash to specify arguments that will be passed on to the constructors for IO::Socket::IP (such as a timeout) or IO::Socket::SSL (such as certificate information). Which of these modules will be used is determined by the `"ssl"` parameter that was provided when instantiating the object. See the relevant manpage for examples. This method will `croak()` if connection fails, so be sure to use `eval()` if you want to catch the error. By default, the return value for `connect()` will be the EPP \ frame returned by the server. Please note that the same caveat about blocking applies to this method as to `get_frame()` (see below). If you want to get the greeting yourself, set `$params{no_greeting}` to `1`. If TLS is enabled, then you can use `%params` to configure a client certificate and/or server certificate validation behaviour. ### COMMUNICATING WITH THE SERVER ``` my $answer = $epp->request($question); ``` This is a simple wrapper around `get_frame()` and `send_frame()` (see below). This method accepts a "question" frame as an argument, sends it to the server, and then returns the next frame the server sends back. ### GETTING A FRAME FROM THE SERVER ``` my $frame = $epp->get_frame; ``` This method returns an EPP response frame from the server. This will be a Net::EPP::Frame::Response object unless the `"frames"` argument to the constructor was false, in which case it will be a string containing a blob of XML. **Important Note**: this method will block your program until it receives the full frame from the server. That could be a bad thing for your program, so you might want to consider using the `alarm()` function to apply a timeout, like so: ``` my $timeout = 10; # ten seconds eval { local $SIG{ALRM} = sub { die "alarm\n" }; alarm($timeout); my $frame = $epp->get_frame; alarm(0); }; if ($@ ne '') { alarm(0); print "timed out\n"; } ``` If the connection to the server closes before the response can be received, or the server returned a mal-formed frame, this method will `croak()`. ### SENDING A FRAME TO THE SERVER ``` $epp->send_frame($frame); ``` This sends a request frame to the server. `$frame` may be one of: - • a scalar containing XML - • a scalar containing a filename - • an XML::LibXML::Document object (or an instance of a subclass) - • an XML::DOM::Document object (or an instance of a subclass) ### DISCONNECTING FROM THE SERVER ``` $epp->disconnect; ``` This closes the connection. An EPP server should always close a connection after a \ frame has been received and acknowledged; this method is provided to allow you to clean up on the client side, or close the connection out of sync with the server. ``` $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. ``` $socket = $epp->connection; ``` Returns the underlying socket. ## COPYRIGHT This module is (c) 2008 - 2023 CentralNic Ltd and 2024 Gavin Brown. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.