PYTHON API communication module

This document provides all the basic information you need to start using the Python 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. Python module IpsetNg will help you quickly and easily build interaction with the ipset-ng server to your Python application.
There are a few setup steps you need to complete before you can use this Python module:

  • Required pre install library libipsng.
  • Download and unzip latest pyipsetng-x.x.x.tar.gz archive.
  • Change directory to root of unzipped archive and run: ./configure.sh, if the installation process is successful, run: ./configure.sh --clean.
  • 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/Python/example from source directory for detail.
  • To uninstall IpsetNg Python module, change directory to root of unzipped archive and run: ./configure.sh --uninstall.

Example code to Python UDP client and Python SSL client.


+ Python IpsetNg module base function

Base API UDP communicate function: ipsetng.net description
ipsetng.net.init(port,host,password) create instance and set server IP address, UDP port, AES password
ipsetng.net.close() clear and free instance
ipsetng.net.set_verbose(0/1) print extended connect information
ipsetng.net.set_packet(cmd,type,ipv,dnsbl,timeout,tbl) create predefined request
return = ipsetng.net.chkip(ip,tbl) send UDP packet to ipset-ng server
return = ipsetng.net.send_pre(ip) send predefined request
return = ipsetng.net.send(cmd,type,ipv,dnsbl,timeout,tbl,ip,net) create and send full request
ipsetng.net.ret_print(return) debug printing receive result (helper)
ipsetng.net.help_print() print network packet options (helper)
ipsetng.net.list_print() print module list functions (helper)
Base API TCP/SSL communicate function: ipsetng.ssl description
ipsetng.ssl.init(port,host,cert,cipher,sni,sesscache,sslsecure) create instance and set server communicate parameters
ipsetng.ssl.close() clear and free instance
ipsetng.ssl.set_info(0/3) print extended SSL session information
ipsetng.ssl.set_verbose(0/1) print extended connect information
ipsetng.ssl.set_packet(cmd,type,ipv,dnsbl,timeout,tbl) create predefined request
return = ipsetng.ssl.chkip(ip,tbl) send TCP/SSL packet to ipset-ng server
return = ipsetng.ssl.send_pre(ip) send predefined request
return = ipsetng.ssl.send(cmd,type,ipv,dnsbl,timeout,tbl,ip,net) create and send full request
ipsetng.ssl.ret_print(return) debug printing receive result (helper)
ipsetng.ssl.help_print() print network packet options (helper)
ipsetng.ssl.list_print() print module list functions (helper)


+ ipsetng.net.set_verbose,
+ ipsetng.ssl.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.


+ ipsetng.net.set_packet,
+ ipsetng.ssl.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.


+ ipsetng.net.send,
+ ipsetng.ssl.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.


+ ipsetng.net.send_pre,
+ ipsetng.ssl.send_pre

send_pre(
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.


+ ipsetng.net.chkip,
+ ipsetng.ssl.chkip

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/TCP-SSL packet request to server.
Function require parametrs: ip and tbl.


+ ipsetng.net.ret_print,
+ ipsetng.ssl.ret_print

ret_print(
int return - return from functions send(..), send_pre(..), chkip(..)
);

return value: no return values.

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


+ ipsetng.net.help_print,
+ ipsetng.ssl.help_print

help_print();

return value: no return values

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


+ ipsetng.net.list_print,
+ ipsetng.ssl.list_print

list_print();

return value: no return values

Print full module functions list, assistance in the development only.
Function no parameters.


+ ipsetng.net.init

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


+ ipsetng.net.close

close();

return value: no return values.

Clear and free before initialized instance.
Function no parameters.


+ ipsetng.ssl.init

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 Python client: cat ./cert.client.pem ./cert.ca.pem ./key.client.pem > ./full.client.pem


+ ipsetng.ssl.close

close();

return value: no return values.

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


+ ipsetng.ssl.set_info

set_info(
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_pre(..), 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 Python IpsetNg module for UDP connection

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


    #!/usr/bin/env python
    # -*- coding: utf-8 -*-

    import ipsetng

    ipsetng.net.set_verbose(1)
    ipsetng.net.init(1919,'127.0.0.1','my access word!')
    x = ipsetng.net.chkip('1.2.3.4','blacklist')
    ipsetng.net.ret_print(x)
    ipsetng.net.close()



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

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


    #!/usr/bin/env python
    # -*- coding: utf-8 -*-

        import ipsetng

        # no show connect and other debug information set to 0
            ipsetng.ssl.set_verbose(1)

        # init SSL instance, require: host, port, certificates
            ipsetng.ssl.init(
                        5000,
                        '127.0.0.1',
                        '/etc/ipset-ng/ssl/last-client-full.pem',
                        'ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH',
                        None,
                        10,
                        1
            )

        # 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
            ipsetng.ssl.set_info(3)

        # create and send full packet
            x = ipsetng.ssl.send(
                        'test',
                        'black',
                        'ipv4',
                        1,
                        0,
                        'blacklist',
                        '46.119.121.149',
                        None
            )
            ipsetng.ssl.ret_print(x)

        # close SSL session and free instance
            ipsetng.ssl.close()


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


  Meta Tags: PYTHON API ipset-ng