API communication routine in libipsng C/C++

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

  • Download and unzip latest ipset-ng archive.
  • Change directory to root of unzipped archive and type: make ; make clean
  • To build the libipsng library you must go to the root source directory, and execute: make clean ; make libips

Example code to build libipsng UDP client and libipsng SSL client. Building programm easy example


+ libipsng base function

Base API function description
ipsng_net_init(...) init UDP client
ipsng_ssl_init(...) init TCP/SSL client
ipsng_ssl_setinfo(...) set verbose print TCP/SSL session
ipsng_send(...) communicate to server
ipsng_set_packet(...) set packet parametrs
ipsng_net_close(...) close and clear resource UDP client
ipsng_ssl_close(...) close and clear resource TCP/SSL client


+ libipsng base macro

Macro API function description
ipsng_net_send(ngnet,cmd,type,ipv,dnsbl,ip,net,tbl) communicate to server (UDP)
ipsng_ssl_send(ngssl,cmd,type,ipv,dnsbl,ip,net,tbl) communicate to server (SSL)
ipsng_set_check(tbl) set complette check IP parametrs from table tbl
ipsng_set_add(tbl) set complette add IP parametrs to table tbl
ipsng_set_del(tbl) set complette del IP parametrs from table tbl
ipsng_net_chkip(ngnet,ip,tbl) check ip (1.2.3.0) from table tbl (UDP)
ipsng_ssl_chkip(ngssl,ip,tbl) check ip (1.2.3.0) from table tbl (SSL)
ipsng_net_addnet(ngnet,net,tbl) add net (1.2.3.0/24) to table tbl (UDP)
ipsng_ssl_addnet(ngssl,net,tbl) add net (1.2.3.0/24) to table tbl (SSL)
ipsng_net_ip_preset(ngnet,ip) use preset, before call ipsng_set_packet() (UDP)
ipsng_ssl_ip_preset(ngssl,ip) use preset, before call ipsng_set_packet() (SSL)


+ ipsng_net_init

IPSNGNET_t *ipsng_net_init(
int, - UDP server port
const char *, - UDP server host
const char * - password - crypt AES connection data
);

ipsng_net_init - lets prepare the IPSNGNET_t structure for the ipset-ng server on UDP protocol.
return value: pointer to a structure IPSNGNET_t, in the case of failure returns NULL.


+ ipsng_ssl_init

IPSNGSSL_t *ipsng_ssl_init(
int, - SSL server port
long, - SSL cache: num session, 0 disable
const char *, - SSL server host
const char *, - path to SSL client certificate + ca + key file
const char *, - SSL cipher string
const char *, - check SSL SNI - server host name
bool, - use SSL secure protocol
bool, - show SSL info
bool, - show SSL session statistic
bool - print other message
);

ipsng_ssl_init - lets prepare the IPSNGSSL_t structure for the ipset-ng server on TCP/SSL protocol.
cipher string - is priority use SSL ciphers a handshake. See for detail: www.openssl.org
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
return value: pointer to a structure IPSNGSSL_t, in the case of failure returns NULL.
Example concat SSL certificates for libipsng client: cat ./cert.client.pem ./cert.ca.pem ./key.client.pem > ./full.client.pem


+ ipsng_ssl_setinfo

void *ipsng_ssl_setinfo(
IPSNGSSL_t *, - ngssl structure
int - verbose level print TCP/SSL session
);
int verbose - verbose level print TCP/SSL session, available values:

  • 0 - the whole display is suppressed
  • 1 - show connect information and warning message
  • 2 - show connect information, warning message and certificates negotiate
  • 3 - the complete withdrawal of statistical information sessions on a connection, and other information


+ ipsng_send

int ipsng_send(
IPSNGSSL_t *, - ngssl structure
IPSNGNET_t *, - ngnet structure
int, - ipset command, see ENUM ipsetype
int, - table type, see ENUM tbltype
int, - ipv protocol, see ENUM netftype
int, - enable/disable check in dnsbl, 0/1
int, - timeouts if add ip to ipset tables
const char *, - single ip address 1.2.3.4
const char *, - net ip addresses 1.2.3.0/24
const char * - ipset table name
);

ipsng_send - sends data to the ipset-ng server, using the structures prepared to work with the server. For UDP protocol - IPSNGNET_t, for TCP/SSL protocol - IPSNGSSL_t.
return integer value:

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

See ENUM cmdtype in src/modules/libipsng/libipsng.h from source directory for detail.


+ ipsng_set_packet

void ipsng_set_packet(
int, - ipset command, see ENUM ipsetype
int, - table type, see ENUM tbltype
int, - ipv protocol, see ENUM netftype
int, - enable/disable check in dnsbl, 0/1
int, - timeouts IP address (live time) if add ip to ipset tables
const char * - ipset table name
);

ipsng_set_packet - sets global parameters for the packet sent to the ipset-ng server.

int cmd table command (ENUM ipsetype):

  • IPSET_CMD_CREATE - create ipset table
  • IPSET_CMD_DESTROY - delete ipset table
  • IPSET_CMD_FLUSH - clear ipset table

int cmd IP address command (ENUM ipsetype):

  • IPSET_CMD_ADD - add IP address to table
  • IPSET_CMD_DEL - del IP address from table
  • IPSET_CMD_TEST - test IP address from table

int type type table select (ENUM tbltype):

  • TBL_LST_BLACK - black list table type
  • TBL_LST_WHITE - white list table type
  • TBL_LST_ADD - add to table type
  • TBL_LST_DEL - del from table type
  • TBL_LST_TABLE - table operation type

int ipv Internet Protocol select (ENUM netftype):

  • NFPROTO_IPV4 - Internet Protocol version 4
  • NFPROTO_IPV6 - Internet Protocol version 6


+ ipsng_net_close

void ipsng_net_close(
IPSNGNET_t * - ngnet structure
);

ipsng_net_close - clears the IPSNGNET_t resources and closes the connection to the server.


+ ipsng_ssl_close

void ipsng_ssl_close(
IPSNGSSL_t * - ngssl structure
);

ipsng_ssl_close - clears the IPSNGSSL_t resources and closes the connection to the server.


+ ipsng_net easy examle

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


    #include <libipsng.h>

    IPSNGNET_t *ngnet = ipsng_net_init(port,host,NULL);
    int ret = ipsng_net_chkip(ngnet,ip,table);

    switch(ret) {
        case SEND_IN_BLOCK: { printf("return SEND_IN_BLOCK - host is blocked"); break; }
        case SEND_NO_BLOCK: { printf("return SEND_NO_BLOCK - host is good status"); break; }
        case SEND_ERROR:    { printf("return SEND_ERROR - error value of request, server response"); break; }
        case SEND_INCOR:    { printf("return SEND_INCOR - incorrect request, bad json string, e.t.c."); break; }
        case SEND_FATAL:    { printf("return SEND_FATAL - error communication or other system error"); break; }
    }
    ipsng_net_close(ngnet);


Enable AES 128/192/256 crypt mode:


    // server access password
    const char secret[] = "my access word!";

    IPSNGNET_t *ngnet = ipsng_net_init(port,host,secret);


WARNING - maximum ciphertext secret length = 32 characters
AES crypt mode (128/192/256) automatically selected and depends on the length of the password string.
See full listing example in source directory: src/modules/libipsng/example/example-ip-net.c


+ ipsng_ssl easy examle

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


    #include <libipsng.h>

    const char cert[]   = "/etc/ipset-ng/ssl/last-client-full.pem";
    const char cipher[] = "ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH";

    IPSNGSSL_t *ngssl = ipsng_ssl_init(port,0,host,cert,cipher,NULL,true,true,false,true);
    int ret = ipsng_ssl_chkip(ngssl,ip,table);

    switch(ret) {
        case SEND_IN_BLOCK: { printf("return SEND_IN_BLOCK - host is blocked"); break; }
        case SEND_NO_BLOCK: { printf("return SEND_NO_BLOCK - host is good status"); break; }
        case SEND_ERROR:    { printf("return SEND_ERROR - error value of request, server response"); break; }
        case SEND_INCOR:    { printf("return SEND_INCOR - incorrect request, bad json string, e.t.c."); break; }
        case SEND_FATAL:    { printf("return SEND_FATAL - error communication or other system error"); break; }
    }
    ipsng_ssl_close(ngssl);


About set priority SSL ciphers, see: www.openssl.org
See full listing example in source directory: src/modules/libipsng/example/example-ip-ssl.c


+ compile programm include libipsng

Before, build ipset-ng client library: make clean ; make libips And included in you program code header file #include <libipsng.h>
If you want to build libipsng libraries in the unsupported OpenSSL, type: make clean ; make libips OSSL=NO

static linked:

static assembly without the use of the OpenSSL library:

gcc example-ip-net.c /usr/lib/libipsng.a -o example-ip-net -L. -lm

or:

gcc --static example-ip-net.c -o example-ip-net -L. -lipsng -lm

static assembly using a OpenSSL library:

gcc example-ip-net.c /usr/lib/libipsng.a -o example-ip-net -L. -lssl -lcrypto -lm

or:

gcc --static example-ip-net.c -o example-ip-net -L. -lipsng -lssl -lcrypto -lm

dynamic linked:

dynamic assembly without the use of the OpenSSL library:

gcc example-ip-net.c -o example-ip-net -lipsng -lm

dynamic assembly using a OpenSSL library:

gcc example-ip-net.c -o example-ip-net -lipsng -lssl -lcrypto -lm

  Meta Tags: C/C++ API libipsng