HeXHub Firewalls • Functions

	1. Using firewalls and firewall plugins in your applications

To use DDoSflt in other programs than HeXHub you need to register it as a system driver (if it's not already registered) then you can obtain a handle to driver by opening a file called \\.\DDoSflt .
To use firewall plugins you need to load the library and first call InitPlugin, when you unload the firewall call UnloadPlugin. Some plugin firewalls may have more functions implemented, for more information see plugins.txt.
Firewall functions can be called with DeviceIoControl (DDoSflt) or FirewallIOCTL (firewall plugins).
IoControl codes (needed for DeviceIoControl) are as following:

0x2220c0 = IOCTL_START
Input: none
Output: none

After loading the driver, call this function to install firewall hook.

0x2220c4 = IOCTL_STOP
Input: none
Output: none

Call this function to disable the firewall without unloading it.

Input: a DWORD containing an IP address
Output: none

This function notifies the firewall that a DDoS attack is in progress and adds an IP to DDoS filter. Until IOCTL_DDOSSTOP is called, all traffic from IPs that are in DDoS filter will be filtered.

Input: none
Output: none

This function notifies the firewall that DDoS attack was stopped, the function will delete the DDoS filter.

0x2220d0 = IOCTL_BAN0
Input: two DWORDs containing an IP range
Output: none

This function sets a ban on an IP range.

0x2220d4 = IOCTL_GETFLT
Input: none
Output: DWORD

This function returns the number of filtered TCP/SYN packets that were sent from IPs found in DDoS filter.

0x2220d8 = IOCTL_REMOVE
Input: two DWORDs containing an IP range
Output: none

Use this function to unban an IP range.

0x2220dc = IOCTL_GETVER
Input: none
Output: DWORD

Use this function to query driver's version. Low byte contains major version number.

0x2220e0 = IOCTL_OPTIONS
Input: a FirewallParametersInfo structure
Output: none

This function will change firewall's parameters (see 4.1.)

0x2220e4 = IOCTL_ADDPORT
Input: a port_info structure
Output: none

This function will register a port used by hub and will set maximum allowed SYN packets / second allowed from all users

0x2220e8 = IOCTL_DELPORT
Input: port value in network byte order
Output: none

This function unregisters a port that was registered using IOCTL_ADDPORT

Input: none
Output: a FirewallStatistics structure (see 4.3.)

This function retrieves and resets firewall's statistics

Input: port value in network byte order
Output: a port_info structure

This function retrieves statistics for specified ports (member synRate of port_info structure will have median SYN packets / second value). Use 0 as port value to get statistics for unregistered ports (a median value for all ports).

0x2220f4 = IOCTL_ABOUT
Input: none
Output: a 512 bytes string

This function returns firewall's version and copyright information as an ASCIIZ string.

0x2220f8 = IOCTL_LOOKUP
Input: two DWORDs containing an IP range
Output: DWORD

This function returns information about an IP range as a combination of flags (one or more bans may be found).
bit 0 = exact IP range was found in banlist
bit 1 = this range is intersected with a banned range
bit 2 = this range is fully included in a bigger range ban
bit 3 = this range fully includes a smaller banned range

0x2220fc = IOCTL_GETCFG
Input: none
Output: a FirewallParametersInfo structure

This function will retrieve current firewall configuration (see 4.1.)

0x222100 = IOCTL_DDOSCNT
Input: none
Output: DWORD

This function retrieves number of IPs in DDoS filter

0x222104 = IOCTL_DDOSFLT
Input: DWORD
Output: DWORD[input_value]

This function returns specified number of IPs from DDoS filter.

Input: none
Output: 3 tables of 256 dwords each

This function returns IP protocol statistics used by !stats ip. All tables have 256 dwords, the 80-bit protocol identifier is an index in each table. First table contains number of sent packets since last call to IOCTL_CLRPROTO, second table contains number of sent packets and third table contains last IP that send or received last packet.

Input: none
Output: none

This function clears protocol statistics tables.

0x222114 = IOCTL_ENUMBANS (DDoSflt 1.07+)
Input: DWORD (a 0-based index in firewall's banlist)
Output: two DWORDs containing an IP range

This function returns an entry from firewall's banlist.

2. Structures used by firewall

2.1. FirewallParametersInfo

typedef struct _FirewallParametersInfo{
WORD pcapFlags; // bit 0 = WinPCap is enabled, bit 1 = detection of adapters was completed (this WORD is not used by version 1.03 of DDoSflt)
WORD pcapAdapters; // mask of enabled / disabled adapters used by WinPCap procedures (this WORD is not used by version 1.03 of DDoSflt)
DWORD pcapTimer; // timeout for capturing packets using WinPCap procedures (not used by version 1.03 of DDoSflt)
BYTE pcapSyn; // maximum number of TCP/SYN packets per second allowed from one IP
BYTE pcapUdp; // maximum number of UDP packets per second allowed from one IP
BYTE pcapIcmp; // maximum number of ICMP packets per second allowed from one IP
BYTE firewallFlags; // bit 0 = firewall is registered
// bit 1 = firewall is started
// bit 2 = maximum SYN/second on hub's registered ports will be checked
// bit 3 = maximum SYN/second on unregistered ports will be checked
// bit 4 = ICMP traffic will be blocked
// bit 5 = TCP/RST packets will not be sent (will be filtered)
// bit 6 = if flood is detected, the application will call the firewall to set a _ban0_ (not used by firewall)
// bit 7 = if flood is detected, a notification message will be sent in opchat (not used by firewall)
WORD hubSyn; // maximum SYN rate allowed for one of registered hub's ports
WORD otherSyn; // maximum SYN rate allowed for non-registered ports
} FirewallParametersInfo;

2.2. port_info

typedef struct _port_info{
WORD port; // port value in network byte order
int synRate; // maximum number of TCP/SYN packets per second allowed from all users
} port_info;

2.3. FirewallStatistics

typedef struct _FirewallStatistics{
syn_str synFlood; // information about last SYN packets received
syn_str udpFlood; // information about last UDP packets received
syn_str icmpFlood; // information about last ICMP packets received
DWORD fltSyn; // number of filtered TCP/SYN packets that were sent from IPs found in DDoS filter
DWORD fltBan; // number of filtered packets sent from banned[0] IPs
DWORD fltPort; // number of filtered SYN packets sent to hub's ports if flood was detected
DWORD pchklast; // internally used by firewall, pointer to a syn_info structure in driver's allocated memory
} FirewallStatistics;

2.4. syn_str

typedef struct _syn_str{
BYTE syn_idx; // index in s_info array
BYTE is_flood; // 0 = no flood was detected
// 1 = flood was detected
// 2 = port scan detected
// 3 = SYN flood was detected
// 4 = UDP flood was detected
// 5 = ICMP flood was detected
DWORD last_ip; // last IP that was detected as flooding
syn_info s_info[20]; // array with information about last packets
} syn_str;

2.5. syn_info

typedef struct _syn_info{
DWORD timer1; // number of milliseconds since firewall was started
DWORD lastIp; // sender's IP (network byte order)
DWORD lastDstIp; // destination IP (network byte order)
DWORD lastPort; // destination port (network byte order)
WORD isFlood; // 0 = no flood was detected, 1 = flood was detected
WORD checkSum; // packet checksum delta (not used by version 1.03)
} syn_info;

3. Firewall plugins need to export all these functions:

3.1. InitPlugin

LPCTSTR InitPlugin(LPFN _GetFunction);

This function MUST be exported by plugin, all other are optional. Plugins that don't export this function are not loaded.
Plugins are auto-detected by the presence of this function in export table. This function will be called on every plugin initialization, the parameter is a pointer to the GetFunction() procedure.
The function should return a pointer to a NULL-terminated string that specifies its description.
If the function returns NULL, there was an error, and plugin will no longer be used.

On initialization, the plugin can use the GetFunction() procedure to get addresses of procedures that can be called from hub. Its prototype is as follows:

LPFN GetFunction(LPCTSTR functionName);

functionName = pointer to a NULL terminated string specifying a procedure from hub

Function returns the pointer to specified function or NULL if function cannot be found.

3.2. UnloadPlugin

void UnloadPlugin(void);

This function is called (if exported by plugin) when plugin is unloaded from memory, or when hub quits. The plugin can unregister all commands / bots / help strings / etc.

3.3. FirewallIOCTL

BOOL FirewallIOCTL(DWORD hDriver,DWORD dwIoControlCode,LPVOID lpInBuffer,DWORD nInBufferSize,LPVOID lpOutBuffer,DWORD nOutBufferSize,LPDWORD lpBytesReturned,LPOVERLAPPED lpOverlapped);

This function allows a plugin to provide, change or to intercept firewall functions as described in firewall.txt.
hDriver = a handle to loaded driver (by default DDoSflt) that can be used in a DeviceIoControl to call functions that are not supported by this plugin or 1 if no driver is loaded
dwIoControlCode = control code of operation
lpInBuffer = input buffer
nInBufferSize = size of input buffer
lpOutBuffer = output buffer
nOutBufferSize = size of output buffer
lpBytesReturned = pointer to variable to receive the number of bytes written
lpOverlapped = pointer to an overlapped structure as described in MSDN

If a plugin exports this function, it must update the buffer pointed by lpBytesReturned with the correct number of bytes written.


There are no comments for this page, you can write one here.