API communication IpsetNg class in PHP

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

  • Download and unzip latest phpipsetng-x.x.x.tar.gz archive.
  • Change directory to root of unzipped archive and copy libipset-ng.php to php include directory of you project.
  • In archive include basic example to connect and the compound with the information processing ipset-ng server.
  • See the archive files test-ip-ipsetng.php and test-ip-ssl-ipsetng.php for more detail.

Example code to php UDP client and php SSL client.


+ PHP class IpsetNg base function

Base API compatible UDP/TCP-SSL function description
$instace = new IpsetNg() init class instance
$instace->pktIpsng(ip,net,tbl,type,cmd,dnsbl,timeout,ipv) create request
$instace->sendStr() print send json packet
$instace->clear() clear class instance
ipset-ng server return server return array
Base API UDP communicate function description
$instace->addServer(host,port) set server IP & UDP port
$instace->setKeyCrypt(password) global set password, crypt AES algorithm UDP connection data
$instace->pktCrypt(password) packet set password, crypt AES algorithm UDP connection data
Array = $instace->sendIpsng() send packet to ipset-ng server
Base API TCP/SSL communicate function description
$instace->addSSLServer(host,port) set SSL server host & TCP/SSL port
$instace->addSSLCerts(certs) path to SSL client certificate + ca + key file
$instace->showSSLCerts() show details certificates
$instace->addSSLCiphers(cipher) set SSL cipher string
$instace->addSSLTimeout(30) set SSL connection timeout default 15 second
Array = $instace->sendSSLIpsng(bool) send SSL packet to ipset-ng server


+ IpsetNg

$instace = new IpsetNg();

Create and init new IpsetNg class instance.


+ pktIpsng

$instace->pktIpsng(
ip, - set test IP address (1.2.3.4) from server
net, - set test NET address (1.2.3.0/24) from server
tbl, - set ipset table name
type, - set table type, valid: white | black | add | del | table
cmd, - set ipset command,
- valid command for ip: add | del | test
- valid command for net: add | del
- valid command for tbl: create | destroy | flush

dnsbl, - set enable/disable check in dnsbl, valid: true | false
timeout, - set timeouts in seconds if add ip to ipset tables
ipv - set ipv protocol, valid: ipv4 | ipv6
);
return value: if success return true, otherwise, return false.

Create request to server. Only valid choice at one packet may be ip or net.
If operation of ipset table, empty ip and net, selected command require: create | destroy | flush
Function require parametrs: ip or net, tbl and type.
Default values in cmd = test, dnsbl = false, timeout = 0, ipv = ipv4.


+ sendStr

$instace->sendStr();
return value: json prepared string.

Print prepared send json packet, debug only.


+ clear

$instace->clear();

Clear and destroy IpsetNg class instance.


+ addServer

$instace->addServer(
host, - set UDP server host
port - set UDP server port
);
return value: if success return true, otherwise, return false.

Add to IpsetNg class instance ipset-ng server IP address or hostname and UDP port.


+ setKeyCrypt

$instace->setKeyCrypt(
password, - set server password to crypt AES connection data
);
return value: if success return true, otherwise, return false.

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


+ pktCrypt

$instace->pktCrypt(
password, - set server password to crypt AES connection data
);
return value: if success return true, otherwise, return false.

Set this packet password to crypt AES(128/192/256) connection data.
AES crypt mode (128/192/256) automatically selected and depends on the length of the password string.
Maximum ciphertext password length - 16 bytes


+ sendIpsng

Array = $instace->sendIpsng();
return value: see ipset-ng server return for detail.

Sent request UDP packet to ipset-ng server.


+ addSSLServer

$instace->addSSLServer(
host, - set SSL server host
port - set SSL server port
);
return value: if success return true, otherwise, return false.

Add to IpsetNg class instance ipset-ng server IP address or hostname and TCP/SSL port.


+ addSSLCerts

$instace->addSSLServer(
certs, - path to SSL client certificate + ca + key fail
);
return value: if success return true, otherwise, return false.

Lets prepare the client certificate, private key and CA root certificate to IpsetNg instance.
Example concat SSL certificates for use in client: cat ./cert.client.pem ./cert.ca.pem ./key.client.pem > ./full.client.pem


+ showSSLCerts

$instace->showSSLCerts(
certs, - path to SSL certificate or empty
);

Show current loading certificates, is parameters certs is empty, or show certificates use path from certs.


+ addSSLCiphers

$instace->addSSLCiphers(
cipher, - set SSL cipher string
);
return value: if success return true, otherwise, return false.

Set priority use SSL ciphers a handshake. See for detail: www.openssl.org


+ addSSLTimeout

$instace->addSSLTimeout(
timeout, - set timeout to SSL connection
);
return value: if success return true, otherwise, return false.

Set send/recive timeouts to SSL connection. Default value 15 second.


+ sendSSLIpsng

Array = $instace->sendSSLIpsng(
bool - debug and show SSL connect statistic, valid: true | false
);
return value: see ipset-ng server return for detail.

Sent request SSL packet to ipset-ng server.


+ ipset-ng server return

From function sendIpsng and sendSSLIpsng return server response is array:
id - unique id, automatic generate and check
ret - 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

    // Example return:

        send: {"id":7359,"cmd":11,"tbl":"whitelist","type":2,"ip":"1.2.3.4","ipv":2,"dnsbl":1}
        recive: Array
    (
        [id] => 7359
        [ret] => 404
    )



+ IpsNg PHP UDP easy examle

Example php routine, single IP address check in black-list type from UDP server.


    <?php

        require('libipset-ng.php');

        $host = '127.0.0.1';
        $port = 1919;
        $key  = "my access word!";

        print "\n\tSending IP check to ipset-ng ".$host.", port ".$port."\n";
        print "\tpress Ctrl-C to stop\n\n";

        $json_recv = Array();

        $IpsetNg = new IpsetNg();
        $IpsetNg->addServer($host, $port);
        $IpsetNg->pktIpsng("1.2.3.4",null,"whitelist","white");

        $IpsetNg->setKeyCrypt($key);

        $json_recv = $IpsetNg->sendIpsng(); // send packet to ng server

        echo "\tsend: ".$IpsetNg->sendStr()."\n";
        echo "\trecive: ";

        print_r($json_recv);

        $IpsetNg->clear();
        unset($IpsetNg);



+ IpsNg PHP SSL easy examle

Example php routine, single IP address check in black-list type from SSL server.


    <?php

        require('libipset-ng.php');

        $host = '127.0.0.1';
        $port = 5000;

        print "\n\tSending IP check to ipset-ng ".$host.", port ".$port."\n";
        print "\tpress Ctrl-C to stop\n\n";

        //
        // !WARNING! if prepare SSL connection,
        // not use setKeyCrypt() and/or pktCrypt()
        //

        $json_recv = Array();

        $IpsetNg = new IpsetNg();
        $IpsetNg->addSSLServer($host, $port);
        $IpsetNg->addSSLCerts("/etc/ipset-ng/ssl/last-client-full.pem");
        $IpsetNg->showSSLCerts(); // info certificates

        $IpsetNg->pktIpsng("1.2.3.4",null,"whitelist","white");

        $IpsetNg->addSSLCiphers("ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH");
        $IpsetNg->addSSLTimeout(30); // timeout 30 second

        $ssl_stat = true; // true | false - debug & show connect statistic

        $json_recv = $IpsetNg->sendSSLIpsng($ssl_stat); // send packet to ng server

        echo "\tsend: ".$IpsetNg->sendStr()."\n";
        echo "\trecive: ";

        print_r($json_recv);

        $IpsetNg->clear();
        unset($IpsetNg);




  Meta Tags: PHP API ipset-ng