Functions

Driver registration

NF_STATUS nf_srv_registerDriver(const char *driverName)
Parameters:

driverName – The name of network hooking driver, without “.sys” extension.

Returns:

NF_STATUS_SUCCESS on success, or other NF_STATUS error code on fail. Windows API function GetLastError() returns an extended error code in case if the function returns NF_STATUS_FAIL.

Description:

Registers and starts a driver with specified name (without “.sys” extension).

Any application that uses driver API tries to register the driver automatically during a call to nf_init, if it is not yet registered. The administrative rights are required to perform this operation. The driver starts immediately after registration, and reboot is not required. The driver will be loaded automatically on each system start. When the driver is registered and started, a client process doesn’t require administrative rights for using it via API.

NF_STATUS nf_srv_unRegisterDriver(const char *driverName)
Parameters:

driverName – The name of network hooking driver, without “.sys” extension.

Returns:

NF_STATUS_SUCCESS on success, or other NF_STATUS error code on fail. Windows API function GetLastError() returns an extended error code in case if the function returns NF_STATUS_FAIL.

Description:

Unregisters a driver with specified name (without “.sys” extension).

Unregistering the driver requires administrative rights. Delete windows\system32\drivers\<driverName>.sys (or from another folder if the driver is registered in other place) and reboot to remove the driver from system completely.

Initialization

NF_STATUS nf_srv_init(const char *driverName, NF_EventHandler *pHandler, NF_SRV_OPTIONS *options)
Parameters:

  • driverName – The name of network hooking driver, without “.sys” extension.

  • pHandler – Pointer to NF_EventHandler object.

  • options – Pointer to NF_SRV_OPTIONS structure.

Returns:

NF_STATUS_SUCCESS on success, or other NF_STATUS error code on fail.

Description:

Call this function to initialize an attachment with the hooking driver and set the event handler object. The library calls NF_EventHandler methods from a thread pool.

By default the driver uses NF_SRV_ALLOW filtering flag and doesn’t filter the transmitted data. To filter the transmitted packets add the filtering rules with necessary flags using the function nf_srv_addRule.

The function returns NF_STATUS_FAIL in case if some other process is already attached to driver. The driver doesn’t allow multiple attachments. If additional process must filter the network data on the same system, rename and register another copy of the driver, then use the new name in nf_srv_init call from another process.

void nf_srv_free()
Description:

Stops the filtering threads, abortss all filtered connections and detaches from the hooking driver.

This function aborts all filtered TCP connections, which means that all unsent buffered data will be lost.

Filtering rules

NF_STATUS nf_srv_addRule(PNF_SRV_RULE pRule, int toHead)
Parameters:

  • pRule – A pointer to NF_SRV_RULE structure.

  • toHead – TRUE (1) - add rule to list head, FALSE (0) - add rule to list tail

Returns:

NF_STATUS_SUCCESS on success, or other NF_STATUS error code on fail.

Description:

Add the specified filtering rule to list.

The list of rules is scanned from the beginning and a first matching rule is applied. The new rules are added to the list head or tail, depending on toHead parameter. The driver doesn’t filter the network activity of the attached process. In effect the rules are not applied to the sockets created by a process that uses driver API.

NF_STATUS nf_srv_setRules(PNF_SRV_RULE pRules, int count)
Parameters:

  • pRules – A pointer to array of NF_SRV_RULE structures.

  • count – Number of items in pRules array

Returns:

NF_STATUS_SUCCESS on success, or other NF_STATUS error code on fail.

Description:

Replace the rules in driver with the specified array.

It is an atomic operation, which means that the old rules are replaced with new list in a single synchronized call. If the rules list in driver is empty, the new list is assigned as current.

NF_STATUS nf_srv_deleteRules()
Returns:

NF_STATUS_SUCCESS on success, or other NF_STATUS error code on fail.

Description:

Remove all added filtering rules.

The rules are removed automatically after closing the attached process. The filtering flags assigned to an active TCP connection persist even after removing the matching rules, until closing the connection or the process attached to driver.

TCP protocol

NF_STATUS nf_srv_tcpClose(ENDPOINT_ID id)
Parameters:

id – Connection identifier

Returns:

NF_STATUS_SUCCESS on success, or other NF_STATUS error code on fail.

Description:

Closes the connection with given id.

The driver cancels all pending send and receive requests and aborts the connection. For graceful disconnect call nf_srv_tcpPostSend and nf_srv_tcpPostReceive with zero length buffer after receiving the calls NF_EventHandler::tcpSend and NF_EventHandler::tcpReceive with zero buffer.

NF_STATUS nf_srv_tcpPostReceive(ENDPOINT_ID id, const char *buf, int len)
Parameters:

  • id – Connection identifier

  • buf – Pointer to data buffer

  • len – Buffer length

Returns:

NF_STATUS_SUCCESS on success, or other NF_STATUS error code on fail.

Description:

Pass the buffer to local process via TCP connection with specified id.

The method NF_EventHandler::tcpCanReceive is called when the internal packet buffer is empty. The function always returns NF_STATUS_SUCCESS after buffering the data. To optimize the usage of memory split large buffers to chunks and indicate each chunk after receiving tcpCanReceive. There is no need to wait for tcpCanReceive before indicating the first chunk. If len is zero, the driver sends a controlled disconnect request to local process for the specified TCP connection.

NF_STATUS nf_srv_tcpPostSend(ENDPOINT_ID id, const char *buf, int len)
Parameters:

  • id – Connection identifier

  • buf – Pointer to data buffer

  • len – Buffer length

Returns:

NF_STATUS_SUCCESS on success, or other NF_STATUS error code on fail.

Description:

Pass the buffer to local process via TCP connection with specified id.

The method NF_EventHandler::tcpCanSend is called when the internal packet buffer is empty. The function always returns NF_STATUS_SUCCESS after buffering the data. To optimize the usage of memory split the large buffers to chunks and send each chunk after receiving tcpCanSend. There is no need to wait for tcpCanSend before sending the first chunk. If len is zero, the driver initiates a controlled disconnect for the specified TCP connection. The driver aborts the connection in case if NF_EventHandler::tcpSend with zero len was not yet called.

NF_STATUS nf_srv_tcpSetConnectionState(ENDPOINT_ID id, BOOL suspended)
Parameters:

  • id – Connection identifier

  • suspended – TRUE to suspend, FALSE to resume

Returns:

NF_STATUS_SUCCESS on success, or other NF_STATUS error code on fail.

Description:

Suspends or resumes indicating sends and receives for the specified TCP connection via NF_EventHandler methods.

The library automatically suspends the connections having large amount of data in send or receive buffers, to avoid wasting memory when the network application or remote server are too slow. The automatic suspending is temporary, and the library resumes indicating new packets after successful delivery of the buffered data.

NF_STATUS nf_srv_getTCPConnInfo(ENDPOINT_ID id, PNF_TCP_CONN_INFO pConnInfo)
Parameters:

  • id – Connection identifier

  • pConnInfo – Pointer to NF_TCP_CONN_INFO structure

Returns:

NF_STATUS_SUCCESS on success, or other NF_STATUS error code on fail.

Description:

Returns in pConnInfo the properties of TCP connection with specified id.

NF_STATUS nf_srv_tcpSetProxy(ENDPOINT_ID id, SRV_PROXY_TYPE proxyType, const char *proxyAddress, int proxyAddressLen, const char *userName, const char *userPassword)
Parameters:

  • id – Endpoint identifier

  • proxyType – Type of proxy (SRVPROXY_NONE or SRVPROXY_SOCKS5)

  • proxyAddress – Network address of the proxy (sockaddr_in or sockaddr_in6)

  • proxyAddressLen – Size of proxyAddress

  • userName – Optional proxy user name (can be NULL)

  • userPassword – Optional proxy password (can be NULL)

Returns:

NF_STATUS_SUCCESS on success, or other NF_STATUS error code on fail.

Description:

Redirect TCP traffic with given id to the specified SOCKS proxy from tcpConnectRequest event. If id is zero, the function specifies proxy for all TCP connections, and can be called from any place after nf_srv_init.

If id is zero, the function specifies proxy for all TCP connections, and can be called from any place after nf_srv_init.

NF_STATUS nf_srv_getDestinationAddress(PNF_ADDRESS srcAddress, PNF_ADDRESS dstAddress, char protocol, unsigned long long payloadHash)
Parameters:

  • srcAddress – Pointer to source address in NF_ADDRESS structure for searching in NAT table

  • dstAddress – Pointer to destination address in NF_ADDRESS structure

  • protocol – IPPROTO_TCP or IPPROTO_UDP

  • payloadHash – UDP data hash for identifying the first received datagram from some endpoint. Not used for TCP.

Returns:

NF_STATUS_SUCCESS on success, or other NF_STATUS error code on fail.

Description:

Returns the destination address for TCP connections and UDP sockets by source address.

For TCP protocol it is necessary to specify the source address in srcAddress field, IPPROTO_TCP in protocol. The matching destination address will be returned in dstAddress.

For UDP protocol it is necessary to specify both source and destination addresses in srcAddress and dstAddress fields, IPPROTO_UDP in protocol. The matching destination address will be returned in dstAddress.

UDP protocol

NF_STATUS nf_srv_udpPostReceive(ENDPOINT_ID id, const unsigned char *remoteAddress, const char *buf, int len, PNF_UDP_OPTIONS options)
Parameters:

  • id – Socket identifier

  • remoteAddress – Remote address (sockaddr_in* for IPv4 and sockaddr_in6* for IPv6)

  • buf – Pointer to data buffer

  • len – Buffer length

  • options – Pointer to NF_UDP_OPTIONS structure

Returns:

NF_STATUS_SUCCESS on success, or other NF_STATUS error code on fail.

Description:

Indicate the buffer to local process via specified socket.

The method NF_EventHandler::udpCanReceive is called when the internal packet buffer is empty. NF_UDP_OPTIONS structure contains datagram parameters including control data buffer. options cannot be NULL. It is necessary to copy the structure passed to udpReceive event.

NF_STATUS nf_srv_udpPostSend(ENDPOINT_ID id, const unsigned char *remoteAddress, const char *buf, int len, PNF_UDP_OPTIONS options)
Parameters:

  • id – Socket identifier

  • remoteAddress – Remote address (sockaddr_in* for IPv4 and sockaddr_in6* for IPv6)

  • buf – Pointer to data buffer

  • len – Buffer length

  • options – Pointer to NF_UDP_OPTIONS structure

Returns:

NF_STATUS_SUCCESS on success, or other NF_STATUS error code on fail.

Description:

Send the buffer to remote server via specified endpoint.

The method NF_EventHandler::udpCanSend is called when the internal packet buffer is empty. NF_UDP_OPTIONS structure contains datagram parameters including control data buffer. options cannot be NULL. It is necessary to copy the structure passed to udpSend event.

NF_STATUS nf_srv_udpSetConnectionState(ENDPOINT_ID id, BOOL suspended)
Parameters:

  • id – Socket identifier

  • suspended – TRUE to suspend, FALSE to resume

Returns:

NF_STATUS_SUCCESS on success, or other NF_STATUS error code on fail.

Description:

Suspends or resumes indicating sends and receives for the specified UDP socket via NF_EventHandler methods.

The library automatically suspends the connections having large amount of data in send or receive buffers, to avoid wasting memory when the network application or remote server are too slow. The automatic suspending is temporary, and the library resumes indicating new packets after successful delivery of the buffered data.

NF_STATUS nf_srv_getUDPConnInfo(ENDPOINT_ID id, PNF_UDP_CONN_INFO pConnInfo)
Parameters:
Returns:

NF_STATUS_SUCCESS on success, or other NF_STATUS error code on fail.

Description:

Returns in pConnInfo the properties of UDP socket with specified id.

NF_STATUS nf_srv_udpSetProxy(ENDPOINT_ID id, SRV_PROXY_TYPE proxyType, const char *proxyAddress, int proxyAddressLen, const char *userName, const char *userPassword)
Parameters:

  • id – Endpoint identifier

  • proxyType – Type of proxy (SRVPROXY_NONE or SRVPROXY_SOCKS5)

  • proxyAddress – Network address of the proxy (sockaddr_in or sockaddr_in6)

  • proxyAddressLen – Size of proxyAddress

  • userName – Optional proxy user name (can be NULL)

  • userPassword – Optional proxy password (can be NULL)

Returns:

NF_STATUS_SUCCESS on success, or other NF_STATUS error code on fail.

Description:

Redirect UDP traffic with given id to the specified SOCKS proxy from udpCreated event. If id is zero, the function specifies proxy for all UDP datagrams, and can be called from any place after nf_srv_init.

If id is zero, the function specifies proxy for all UDP packets, and can be called from any place after nf_srv_init.

NF_STATUS nf_srv_getUDPRemoteAddress(ENDPOINT_ID id, unsigned char *remoteAddress, int remoteAddressLen)
Parameters:

  • id – Endpoint id

  • remoteAddress – Pointer to destination address in sockaddr_in or sockaddr_in6 structure

  • remoteAddressLen – Size of remoteAddress buffer

Returns:

NF_STATUS_SUCCESS on success, or other NF_STATUS error code on fail.

Description:

Returns destination address for UDP socket with given endpoint id.

It is possible to call this function to get the destination address for UDP datagrams in udpCreated event.

Flow control contexts and statistics

NF_STATUS nf_srv_addFlowCtl(PNF_SRV_FLOWCTL_DATA pData, unsigned int *pFcHandle)
Parameters:

  • pData – A pointer to NF_SRV_FLOWCTL_DATA structure.

  • pFcHandle – Returns a flow control context handle on success

Returns:

NF_STATUS_SUCCESS on success, or other NF_STATUS error code on fail.

Description:

Add a flow control context with specified parameters.

Call this function to add a new flow control context with specified parameters.

NF_STATUS nf_srv_deleteFlowCtl(unsigned int fcHandle)
Parameters:

fcHandle – Flow control context handle

Returns:

NF_STATUS_SUCCESS on success, or other NF_STATUS error code on fail.

Description:

Delete flow control context.

Deletes the flow control context with specified handle and disables it’s association with TCP/UDP sockets. When fcHandle is zero, deletes all existing flow control contexts. All flow control contexts are deleted automatically after detaching from driver with nf_free or on unexpected shutdown of the filtering process.

NF_STATUS nf_srv_modifyFlowCtl(unsigned int fcHandle, PNF_SRV_FLOWCTL_DATA pData)
Parameters:

  • fcHandle – Flow control context handle

  • pData – A pointer to NF_SRV_FLOWCTL_DATA structure.

Returns:

NF_STATUS_SUCCESS on success, or other NF_STATUS error code on fail.

Description:

Modify flow control context parameters.

The function changes the parameters of flow control context with specified handle.

NF_STATUS nf_srv_getFlowCtlStat(unsigned int fcHandle, PNF_SRV_FLOWCTL_STAT pStat)
Parameters:

  • fcHandle – Flow control context handle

  • pStat – A pointer to NF_SRV_FLOWCTL_STAT structure.

Returns:

NF_STATUS_SUCCESS on success, or other NF_STATUS error code on fail.

Description:

Returns the flow control context statistics.

The function returns the statistics counted for flow control context with specified handle.

Common functions

NF_STATUS nf_srv_setTimeout(NF_SRV_TIMEOUT_TYPE type, unsigned int value)
Parameters:

  • type –

    Timeout type:

    • NSTT_NAT_TCP - timeout for TCP NAT entries. Default value is 2 hours.

    • NSTT_NAT_TCP_SYN - timeout for TCP NAT entries with SYN_SENT state, which means that the connection is not yet established. Default value is 20 seconds.

    • NSTT_NAT_TCP_CLOSE - timeout for TCP NAT entries in CLOSED state. Default value is 20 seconds.

    • NSTT_NAT_UDP - timeout for UDP NAT entries. Default value is 20 seconds.

  • value – Timeout value in seconds. It is possible to specify zero value to disable timeout.

Returns:

NF_STATUS_SUCCESS on success, or other NF_STATUS error code on fail.

Description:

Specifies a timeout value for the network activity.

The driver deletes inactive TCP and UDP NAT entries after exceeding the specified timeouts.