Perl API communication module

This document provides all the basic information you need to start using the Perl module IpsetNg to communicate ipset-ng server. It covers important IpsetNg module concepts, shows examples for various use cases, and gives links to more information. Perl module IpsetNg will help you quickly and easily build interaction with the ipset-ng server to your perl application.
There are a few setup steps you need to complete before you can use this Perl module:

  • Required pre install library libipsng.
  • Download and unzip latest perlipsetng-x.x.x.tar.gz archive.
  • Change directory to root of unzipped archive and run: perl Makefile.PL ; make test, if the test is successful, run: make install.
  • In archive include basic example to connect and the compound with the information processing ipset-ng server.
  • See the sample script files in src/modules/libipsng/Perl/IpsetNg/script from source directory for detail.

Example code to Perl UDP client and Perl SSL client.


+ Perl IpsetNg module base function

Base API compatible UDP/TCP-SSL function description
set_verbose(0/1) print extended connect information
set_packet(cmd,type,ipv,dnsbl,timeout,tbl) create predefined request
$return = send_preset(ip) send predefined request
$return = send(cmd,type,ipv,dnsbl,timeout,tbl,ip,net) create and send full request
ret_print($return) debug printing receive result
help_print() print options help
ipset-ng server return server return status integer
Base API UDP communicate function description
net_init(port,host,password) create instance and set server IP address, UDP port, AES password
$return = net_chkip(ip,tbl) send UDP packet to ipset-ng server
net_close() clear and free instance
Base API TCP/SSL communicate function description
ssl_init(port,host,cert,cipher,sni,sesscache,sslsecure) create instance and set server communicate parameters
ssl_setinfo(0/3) print extended SSL session information
$return = ssl_chkip(ip,tbl) send TCP/SSL packet to ipset-ng server
ssl_close() clear and free instance


+ set_verbose

set_verbose(
verbose - level printing, available values: 0 - disable, 1 - enable
);

return value: no return values.

Printing extended connect information, useful for debugging.


+ set_packet

set_packet(
cmd, - set ipset command,
type, - set table type, valid: white | black | add | del | table
ipv - set ipv protocol, valid: ipv4 | ipv6
dnsbl, - set enable/disable check in dnsbl, valid: true | false
timeout, - set timeouts in seconds if add ip to ipset tables
tbl - set ipset table name
);

return value: if success return true, otherwise, return false.

Create predefined packet request to server.
Function require parametrs: ip or net, tbl and type.
See full summary table of possible values.
Default values: cmd = test, dnsbl = false, timeout = 0, ipv = ipv4.


+ send

send(
cmd, - set ipset command,
type, - set table type, valid: white | black | add | del | table
ipv - set ipv protocol, valid: ipv4 | ipv6
dnsbl, - set enable/disable check in dnsbl, valid: true | false
timeout, - set timeouts in seconds if add ip to ipset tables
tbl, - set ipset table name
ip, - set test IP address (1.2.3.4) from server
net - set test NET address (1.2.3.0/24) from server
- valid command for ip: add | del | test
- valid command for net: add | del
- valid command for tbl: create | destroy | flush
);

return value: see ipset-ng server return for detail.

Create full packet request to server.
See full summary table of possible values.
Function require parametrs: ip or net, tbl and type.
Default values: cmd = test, dnsbl = false, timeout = 0, ipv = ipv4.


+ send_preset

send_preset(
ip - set test IP address (1.2.3.4) from server
);

return value: see ipset-ng server return for detail.

Send predefined packet request to server.
Function require parametrs: ip. No default values.


+ ret_print

ret_print(
int return - return from functions send(..), send_preset(..), net_chkip(..), ssl_chkip(..)
);

return value: no return values.

Print full reason of request from IPSETD-NG server, debug only.


+ help_print

help_print();

return value: always return true = 1.

Print full summary table of possible values, assistance in the development only.
Function no parameters.


+ net_init

net_init(
host, - set UDP server host
port, - set UDP server port
password - set server password to crypt AES connection data (optional)

);

return value: if success return true, otherwise, return false.

Initialize instance and add IPSETD-NG server IP address or hostname, UDP port and server password to crypt AES connection data.
Function require parametrs: host and port.

AES crypt mode (128/192/256) automatically selected and depends on the length of the password string.
Maximum ciphertext password length = 32 characters


+ net_close

net_close();

return value: no return values.

Clear and free before initialized instance.
Function no parameters.


+ net_chkip

net_chkip(
ip, - set test IP address (1.2.3.4) from server
tbl - set ipset table name
);

return value: see ipset-ng server return for detail.

Create preset to check IP address UDP packet request to server.
Function require parametrs: ip and tbl.


+ ssl_init

ssl_init(
port, - set SSL server port
host, - set SSL server host
certs, - path to SSL client certificate + ca + key fail
cipher, - set SSL cipher string
sni, - check SSL SNI - server host name
sesscache, - SSL cache: num session, 0 disable
sslsecure - use SSL secure protocol
);

return value: if success return true, otherwise, return false.
sni string - a client indicates which hostname it is attempting to connect to at the start of the handshaking process. See for detail: SNI wiki
cipher string - is priority use SSL ciphers a handshake. See for detail: www.openssl.org

Initialize instance on TCP/SSL protocol and add IPSETD-NG server IP address or hostname, SSL port and other SSL require parameters.
Function require parametrs: host, port,cert.
Example concat SSL certificates for libipsng Perl client: cat ./cert.client.pem ./cert.ca.pem ./key.client.pem > ./full.client.pem


+ ssl_close

ssl_close();

return value: no return values.

Clear and free before initialized SSL instance.
Function no parameters.


+ ssl_chkip

ssl_chkip(
ip, - set test IP address (1.2.3.4) from server
tbl - set ipset table name
);

return value: see ipset-ng server return for detail.

Create preset to check IP address TCP/SSL packet request to server.
Function require parametrs: ip and tbl.


+ ssl_setinfo

ssl_setinfo(
verbose - level SSL debug printing, available values: 0 | 1 | 2 | 3
);

return value: no return values.

Printing extended SSL session information, useful for debugging.
SSL level debug printing:

  • 0 - disable all message
  • 1 - SSL connect message
  • 2 - SSL session statistic
  • 3 - and other SSL engine message


+ ipset-ng server return

Return server response integer from functions send(..), send_preset(..), net_chkip(..), ssl_chkip(..)
For debug purpose use function ret_print(..)
Return code:

  • (404) - host is blocked
  • (200) - host is good status
  • (500) - error value of request, server response
  • (403) - incorrect request, bad json string, e.t.c.
  • (-1) - error communication or other system error


+ Available options of possible values

Full summary table of options possible values.


+ Available options for ipset command:

option ENUM description
create 2 create table
destroy 3 destroy table
flush 4 flush table
add 9 add ip or net to table
del 10 del ip or net to table
test 11 test ip from table


+ Available options for table type:

option ENUM description
black 1 black list type
white 2 white list type
add 3 add ip or net to list type
del 4 del ip or net to list type
table 5 table operation type


+ Available options for protocol family:

option ENUM description
inet 2 internet protocol version 4
ipv4 2 internet protocol version 4
inet6 10 internet protocol version 6
ipv6 10 internet protocol version 6
iphex 33 built-in HEX protocol, not use


+ An example of using the Perl IpsetNg module for UDP connection

Example Perl routine, single IP address check in black-list type from UDP protocol in IPSETD-NG server:


    #!/usr/bin/perl

    use warnings;
    use strict;

    use ExtUtils::testlib;
    use IpsetNg;

    my $port = 1919;
    my $server = '127.0.0.1';
    my $secret = 'my access word!';

    IpsetNg::set_verbose(1);

    IpsetNg::net_init($port,$server,$secret);

    my $x = IpsetNg::net_chkip('1.2.3.4','blacklist');
    IpsetNg::ret_print($x);

    IpsetNg::net_close();



+ An example of using the Perl IpsetNg module for TCP/SSL connection

Example Perl routine, single IP address check in black-list type from TCP/SSL protocol in IPSETD-NG server:


    #!/usr/bin/perl

        use warnings;
        use strict;

        use ExtUtils::testlib;

        # import ':all' for use short functions name
        use IpsetNg ':all';

        # no show connect and other debug information set to 0
        set_verbose(1);

        my $port = 1919;
        my $server = '127.0.0.1';
        my $cert = '/etc/ipset-ng/ssl/last-client-full.pem';
        my $cipher = 'ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH';
        my $sesscache = 10;
        my $sslsecure = 1;

        ssl_init(
            $port,
            $server,
            $cert,
            $cipher,
            0,
            $sesscache,
            $sslsecure
        );

        # ssl_setinfo: 0,1,2 or 3
        # 0 - disable all SSL engine message
        # 1 - SSL connect message
        # 2 - SSL session statistic
        # 3 - other SSL engine message
        ssl_setinfo(3);

        # create and send full packet
        my $xx = send('test', 'black', 'ipv4', 1, 0, 'blacklist', '46.119.121.149' );
        ret_print($xx);

        # close SSL session and free instance
        ssl_close();


For more examples, see sample script files in src/modules/libipsng/Perl/IpsetNg/script from source directory for detail.


  Meta Tags: Perl API ipset-ng