Ethernet Connector

AUTAPF Plugin API

Introduction to the AUTAPF Plugin API

NetworkActiv AUTAPF v2.2 supports Client IP Filtering and Data Manipulation plugins. Using a Client IP Filtering plugin, each client connection can be filtered by its IP address via arbitrary procedures, such as by accessing a database or Web API. An Online geolocation database is one example of the type of Web API that may be accessed using a Client IP Filtering plugin. Using a Data Manipulation plugin, the TCP or UDP data can be changed in either direction (client-to-server or server-to-client). For example, if an HTTP connection were being forwarded, every instance of "Slavery" could be replaced with "Freedom". In fact, the replacement data could be of a different length, but in that case it would also be advisable to change the Data-Length header. Real-world uses of a Data Manipulation plugin might be to encrypt/decrypt transmissions, add header fields (such as for spam filtering), or remove sensitive information (such as from emails).

See Client IP Filtering template and Data Manipulation template for fully functioning code examples.

Plugins are made in the form of a DLL that exports certain functions (procedures). While each type of plugin has functions specifically tailored to its offering, there are certain functions that all AUTAPF plugins SHOULD export:

GetPluginType() is the only required auxilliary function as of this writing. This function has the following prototypes:

AFX_EXT_CLASS const WCHAR *GetPluginType();

GetPluginType() SHOULD return "ClientIPFiltering" for IP filtering and "DataManipulation" for Data Manipulation.

Those functions whose names end in Cmd are meant to be run directly at the command prompt via rundll32. For example:

rundll32.exe NA_AUTAPF_Plugin_IPFiltering.dll,IsIPAllowedCmd 127.0.0.1

Be sure to use a 32-bit DLL with the 32-bit AUTAPF and vice versa.

Specifications for Client IP Filtering plugins

Client IP Filtering plugins MUST export the following functions:

AFX_EXT_CLASS bool IsIPAllowed(const WCHAR *IPAddress);

IsIPAllowed() returns a boolean indicating whether the IP address is to be allowed. Both IPv4 and IPv6 addresses are possible, including those IPv6 addresses having a scope ID. For example: 12.34.56.78 or 1111:2222:3333:4444:5555:6666:7777:8888%1234567890 . Because this function is called for every new session, the plugin could optionally log connections or trigger special events that should run each time a client connects.

Specifications for Data Manipulation plugins

Data Manipulation plugins MUST export the following functions:

struct ManipulationBuffer { const _SOCKADDR_INET *ClientAddress; // 4/8 bytes; const _SOCKADDR_INET *ListeningAddress;// 4/8 bytes; const _SOCKADDR_INET *OLAddress; // 4/8 bytes; const _SOCKADDR_INET *ServerAddress; // 4/8 bytes; unsigned long BufferSize; // 4 bytes; unsigned long BytesReceived; // 4 bytes; INT_PTR Reserved; // 4/8 bytes; char Buffer[]; // Variable bytes; see BufferSize; }; AFX_EXT_CLASS ManipulationBuffer *ProcessUpstreamData(ManipulationBuffer *InBuffer); AFX_EXT_CLASS void CALLBACK ProcessUpstreamDataCmd(HINSTANCE hinst, LPSTR InBuffer, int nCmdShow); AFX_EXT_CLASS ManipulationBuffer *ProcessDownstreamData(ManipulationBuffer *InBuffer); AFX_EXT_CLASS void CALLBACK ProcessDownstreamDataCmd(HINSTANCE hinst, LPSTR InBuffer, int nCmdShow);

ProcessUpstreamData() and ProcessDownstreamData() receive a ManipulationBuffer containing the data as it was received from either the client or the server, respectively. That is, ProcessUpstreamData() receives data from the client while ProcessDownstreamData() receives data from the server. Each of these functions may read or write to the provided Buffer[]. Reading and writing must be limited to the BufferSize. If the output (result) data to be sent along is larger than the provided buffer, a different buffer must be returned by the plugin. AUTAPF will not delete this buffer, so a static buffer management approach is recommended on the part of the plugin. Be sure to differentiate connections using the provided ClientAddress and ListeningAddress so that the same buffer is not used by more than one session simultaneously. Otherwise, data could be mingled between sessions. In most cases, the buffer received as input to the function is sufficient in size for operations that increase the data size a modest amount. Each of these functions returns a pointer either to the (possibly modified) receive buffer, or otherwise to a different buffer as allocated by the plugin. The BytesReceived field MUST be set to the length of data to be sent along. If the original input buffer is being used for output and the data length remains the same, then this field is already set correctly.