Using API

The network extension must be installed on the target system as described in the Installation topic.

The API library provides two interfaces for use from C++ and C code, selected by defining the symbol _C_API.

By default, the extension allows all network activity and passes through data packets without filtering. The attached application must create one or more rules using the API to specify which network activity should be filtered. For example, it is possible to create a rule with all fields set to zero except filteringFlag set to NF_FILTER, and the driver will indicate the transmitted data for all TCP connections except local ones.

The extension aborts all filtered TCP connections and returns to “bypass all” mode after expected or unexpected termination of the attached process.

Only one process can use the extension at a time. It is possible to register additional instances of the extension with different names in case several processes need to filter the network activity on the same system. See the Installation section for details.

By default, attaching to the extension requires root privileges, because it runs in a security container. It is possible to run the extension as a regular process by modifying the project settings. In this case the Unix sockets used for interprocess communication can be created in any folder to allow access from an unprivileged account.

Usage scenarios

C++

  • Implement the methods of NF_EventHandler by defining a class derived from this interface.

  • Initialize the API by calling nf_init(), specifying the driver name and a pointer to an object of a class derived from NF_EventHandler.

  • Add filtering rules using nf_addRule(), nf_addRuleEx(), nf_setRules(), nf_setRulesEx().

  • Handle API notifications in the overridden NF_EventHandler methods. The library calls these methods from a separate thread, so synchronization is required if the same data are simultaneously accessed from other threads. It is possible to save copies of the indicated data buffers and send the filtered data back to the destination from any thread later.

  • To remove the rules and disable filtering of new connections, call nf_deleteRules(). The library continues to indicate events for active TCP connections in this case until they are closed, because the filtering flag is assigned when a connection is being established, and remains active during the connection lifetime.

  • Call nf_free() to detach from the extension.

C

  • Define the symbol _C_API before including nfapi_macos.h and build nfproxy using “”make C_API=1””.

  • For C projects NF_EventHandler is defined as a structure with pointers to event handler functions.

Everything else is the same as for C++.