Using API

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

By default the proxy allows all network activity and bypasses the data packets without filtering. The attached application must create one or more rules using the API to specify what network activity must be filtered. For example, it is possible to create a rule with all zeros except filteringFlag set to NFEXT_REDIRECT, and the driver will indicate the transmitted data for all TCP connections except local ones and the connections of processes started under root account.

The proxy aborts all filtered TCP connections and returns to “bypass all” mode after the nf_free call.

Note that if the filtering process is closed unexpectedly, the firewall rules continue redirecting TCP to a closed proxy, which blocks all TCP traffic. In such a case, it makes sense to use a monitor process that removes the added rules from the used anchor, like this:

pfctl -a com.apple/250.<name from nf_init> -F all

The process requires root rights to add firewall rules.

Usage scenarios

C++

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

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

  • Add the filtering rules using nf_setRules().

  • Handle API notifications in the overridden NF_EventHandler methods. The library calls these methods from separate threads, so synchronization is required if the same data is accessed simultaneously 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(). In this case the library continues indicating events for active TCP connections until they close, because the filtering flag is assigned when a connection is established and remains active for the lifetime of the connection.

  • Call nf_free() to detach from the extension.

C

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

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

Everything else is the same as for C++.