Functions¶

Initialization¶

NF_STATUS nf_init(const char *driverName, NF_EventHandler *pHandler)¶

Parameters:

driverName – The bundle name of network extension.
pHandler – Pointer to NF_EventHandler object.

Returns:

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

Description:

Call this function to initialize attachment to the network extension and set the event handler object. The library calls NF_EventHandler methods from multiple threads.

By default, the extension uses the NF_ALLOW filtering flag and does not filter the transmitted data. To filter the transmitted packets, add the filtering rules with necessary flags using the nf_addRule(Ex) or nf_setRules(Ex) functions.

The function returns NF_STATUS_FAIL if another process is already attached to the network extension. The extension does not allow multiple attachments. If an additional process needs to filter the network data on the same system, it is possible to rename and register another copy of the extension, then use the new name in the nf_init call from another process.

It is possible to call nf_setOptions before nf_init to specify additional parameters.

If driverName starts with the ‘/’ character, the parameter is used as the full path to the Unix socket for communicating with the Network Extension. The path can be modified in the Network Extension code.

void nf_free()¶

Description:: Stops the filtering threads, aborts all filtered connections and detaches from the filtering extension.

This function aborts all filtered TCP connections, which means that all unsent buffered data will be lost. To avoid this, it is possible to remove the filtering rules by calling nf_deleteRules, and wait until the filtered connections close gracefully.

void nf_setOptions(int nThreads, int flags)¶

Parameters:

nThreads – Number of worker threads for NF_EventHandler events.
flags – Must be zero.

Description:

Specifies the number of worker threads and initialization flags.

The function can be called before nf_init. If it is called after the initialization, the changes will not be applied until the library is reinitialized. By default, nThreads = 1 and flags = 0. It means that the events are indicated from a single thread and all flags are disabled. When nThreads = 0, the code detects the number of logical processors and uses it as the number of worker threads.

Filtering rules¶

NF_STATUS nf_addRule(PNF_RULE pRule, int toHead)¶

Parameters:

pRule – A pointer to NF_RULE structure.
toHead – TRUE (1) - add the rule to the head of the list, FALSE (0) - add the rule to the tail of the list

Returns:

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

Description:

Add the specified filtering rule to the list.

NF_STATUS nf_addRuleEx(PNF_RULE_EX pRule, int toHead)¶

Parameters:

pRule – A pointer to NF_RULE_EX structure.
toHead – TRUE (1) - add the rule to the head of the list, FALSE (0) - add the rule to the tail of the list

Returns:

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

Description:

Add the specified filtering rule to the list.

The list of rules is scanned from the beginning and the first matching rule is applied. The new rules are added to the head or tail of the list, depending on the toHead parameter. The extension does not filter the network activity of the attached process. As a result, the rules are not applied to the sockets created by a process that uses the extension API. NF_RULE_EX rules are added to the same list as NF_RULE. NF_RULE is treated as NF_RULE_EX without additional conditions. So it is possible to add both types of rules in any order.

NF_STATUS nf_setRules(PNF_RULE pRules, int count)¶

Parameters:

pRules – A pointer to array of NF_RULE structures.
count – Number of items in pRules array

Returns:

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

Description:

Replace the rules in the extension with the specified array.

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

NF_STATUS nf_setRulesEx(PNF_RULE_EX pRules, int count)¶

Parameters:

pRules – A pointer to array of NF_RULE_EX structures.
count – Number of items in pRules array

Returns:

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

Description:

Replace the rules in the extension with the specified array.

NF_STATUS nf_deleteRules()¶

Returns:: NF_STATUS_SUCCESS on success, or other NF_STATUS error code on failure.
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 the connection is closed or the process attached to the extension terminates.

TCP protocol¶

NF_STATUS nf_tcpClose(ENDPOINT_ID id)¶

Parameters:: id – Connection identifier
Returns:: NF_STATUS_SUCCESS on success, or other NF_STATUS error code on failure.
Description:: Closes the connection with the given id.

The extension cancels all pending send and receive requests and aborts the connection. For a graceful disconnect, call nf_tcpPostSend and nf_tcpPostReceive with a zero-length buffer after receiving the NF_EventHandler::tcpSend and NF_EventHandler::tcpReceive calls with a zero-length buffer.

NF_STATUS nf_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 failure.

Description:

Pass the buffer to the local process via the TCP connection with the 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 memory usage, split large buffers into 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 extension sends a graceful disconnect request to the local process for the specified TCP connection.

NF_STATUS nf_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 failure.

Description:

Pass the buffer to the local process via the TCP connection with the 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 memory usage, split large buffers into 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 extension initiates a graceful disconnect for the specified TCP connection.

NF_STATUS nf_tcpSetConnectionState(ENDPOINT_ID id, int 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 failure.

Description:

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

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

NF_STATUS nf_tcpDisableFiltering(ENDPOINT_ID id)¶

Parameters:: id – Connection identifier
Returns:: NF_STATUS_SUCCESS on success, or other NF_STATUS error code on failure.
Description:: Disables calling TCP events for the specified endpoint.

This function can be used to improve performance if the filtering application is not interested in packets transmitted via some filtered connection (with NF_FILTER flag assigned). It is possible to call this function in the tcpConnected event to stop indicating new packets.

NF_STATUS nf_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 failure.

Description:

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

UDP protocol¶

The UDP filtering functions are currently disabled. Only access control is available for UDP using rules.

Common functions¶

NF_STATUS nf_getProcessName(unsigned int pid, char *buf, int len)¶

Parameters:

pid – Process identifier
buf – Memory buffer for process name
len – Size of buf, in characters.

Returns:

NF_STATUS_SUCCESS on success

Description:

Returns the process name for the given process id.

nf_getProcessName returns the command line for the specified pid.

NF_STATUS nf_getUid(ENDPOINT_ID id, unsigned int *pUid)¶

Parameters:

id – Endpoint identifier
pUid – Pointer to user identifier

Returns:

NF_STATUS_SUCCESS on success

Description:

Returns the user identifier for the given endpoint id.

NF_STATUS nf_getUserName(unsigned int uid, char *buf, int len)¶

Parameters:

uid – User identifier
buf – Memory buffer for user name
len – Size of buf, in characters.

Returns:

NF_STATUS_SUCCESS on success

Description:

Returns the user name for the given user id.

NF_STATUS nf_requireFileLimit(int file_limit)¶

Parameters:: file_limit – New limit for the number of file handles
Returns:: NF_STATUS_SUCCESS on success
Description:: Sets a new process limit for the number of file handles

By default, the OS has a low limit on the number of file handles. It is possible to specify a larger limit if the filtering application uses its own sockets.

int nf_isDisconnected()¶

Returns:: 1 or 0.
Description:: Returns 1 if the network extension is unloaded after nf_init, 0 otherwise.

It is possible to call this function periodically to check if the network filtering is still working. If the extension is unloaded unexpectedly, all filtered connections are closed automatically. In this case, it is possible to stop the application, or try to reattach to the extension after it is loaded again by calling nf_init and adding the rules.