API functions

API functions

BOOL pf_init(PFEvents * pHandler, const wchar_t * dataFolder);

Initialize the library.
pHandler - Event handler
dataFolder - A path to configuration folder, where the library stores SSL certificates and temporary files

void pf_free();

Free the library.

NF_EventHandler * pf_getNFEventHandler();

Returns a pointer to event handler class for passing to nfapi::nf_init().

BOOL pf_postObject(ENDPOINT_ID id, PFObject * pObject);

Post an object to the specified endpoint.
id - Endpoint id
pObject - Filtered object

BOOL pf_addFilter(ENDPOINT_ID id,
		PF_FilterType type, 
		tPF_FilterFlags flags = FF_DEFAULT,
		PF_OpTarget target = OT_LAST, 
		PF_FilterType typeBase = FT_NONE);

Adds a new filter to session filtering chain.
id - Endpoint id
type - Type of the filter to add
flags - Filter specific flags
target - Position where to add new filter (OT_NEXT, OT_PREV - relative to typeBase)
typeBase - Type of origin filter

BOOL pf_deleteFilter(NFAPI_NS ENDPOINT_ID id, PF_FilterType type);

Removes the specified filter from chain.
id - Endpoint id
type - Type of the filter to remove

int pf_getFilterCount(NFAPI_NS ENDPOINT_ID id);

Returns the number of active filters for the specified connection.
id - Endpoint id

BOOL pf_isFilterActive(NFAPI_NS ENDPOINT_ID id, PF_FilterType type);

Returns TRUE if there is a filter of the specified type in filtering chain.
id - Endpoint id
type - Type of the filter

BOOL pf_canDisableFiltering(NFAPI_NS ENDPOINT_ID id);

Returns TRUE when it is safe to disable filtering for the connection with specified id (there are no filters in chain and internal buffers are empty).
id - Endpoint id

void pf_setRootSSLCertSubject(const char * rootSubject);

Specifies subject of a root certificate, used for generating other SSL certificates.
This name appears in "Issued by" field of certificates assigned to filtered SSL connections. Default value - "NetFilterSDK". If the appropriate certificate doesn't exist in the configuration folder, the library creates it and imports to CA certificate storages (Windows internal storage, Firefox and other products using Mozilla engine, Opera, Pidgin). The importing works asynchronously in a separate thread.

The additional attributes can be added to subject name string passed to pf_setRootSSLCertSubject(Ex) as following:
pf_setRootSSLCertSubject("Sample CA;O=Company;OU=R&D;L=City;S=State");

The attributes are added after subject name, formatted as name=value, divided by ';' or ','.

Here is a list of possible attribute names:
OU: OrganizationalUnit
O: Organization
L: Locality
S: StateOrProvinceName
C: CountryName

void pf_setRootSSLCertSubjectEx(const char * rootSubject, const char * x509, int x509Len, const char * pkey, int pkeyLen)

Same as pf_setRootSSLCertSubject, but additionally allows to specify own root certificate with private key instead of generating it automatically.

BOOL pf_loadCAStore(const char * rootCAFileName)

Load the specified file with root CA certificates in PEM format (required only on Linux/Mac OS).

BOOL pf_getRootSSLCertFileName(wchar_t * fileName, int fileNameLen)

Returns the full path to root certificate in fileName buffer, with length in symbols specified in fileNameLen. FALSE is returned when the buffer length is too small.

/** Class of SSL exceptions */
enum eEXCEPTION_CLASS
{
	// Generic exceptions generated because of unexpected disconnect during handshake
	EXC_GENERIC = 0,		
	// TLS exceptions, switching version of TLS protocol
	EXC_TLS = 1,			
	// Certificate revokation exceptions
	EXC_CERT_REVOKED = 2,	
	EXC_MAX
};
    
void pf_setExceptionsTimeout(eEXCEPTION_CLASS ec, unsigned __int64 timeout)

Specifies a timeout in seconds for storing SSL filter exceptions. After exceeding the specified duration value the exceptions are deleted. The default value is zero, which means that SSL exceptions are not deleted by timeout.

void pf_deleteExceptions(eEXCEPTION_CLASS ec)

Deletes SSL exceptions of the specified class.

void pf_setRootSSLCertImportFlags(unsigned long flags);

Specifies import flags from ePF_RootSSLImportFlag enumeration, allowing to control importing root SSL certificate in pf_setRootSSLCertSubject to supported storages. The function can be called before pf_setRootSSLCertSubject.
Possible values for flags parameter:
RSIF_DONT_IMPORT = 0 - don't import root certificate to file storages, except Windows storage.
RSIF_IMPORT_TO_MOZILLA_AND_OPERA = 1 - import root certificate only to Opera and Mozilla-based products.
RSIF_IMPORT_TO_PIDGIN = 2 - import root certificate only to Pidgin storage.
RSIF_IMPORT_EVERYWHERE = 3 - import root certificate to all supported file storages.
RSIF_GENERATE_ROOT_PRIVATE_KEY = 4 - generate a unique private key for root certificate.
RSIF_GENERATE_DOMAIN_PRIVATE_KEYS = 8 - generate a unique private key for each domain certificate.
RSIF_GENERATE_EC_PRIVATE_KEYS = 16 - generate EC keys instead of RSA.
RSIF_PERSISTENT_CERTIFICATE_CACHE = 32 - store the generated domain certificates in cache file instead of generating them each session.

Default value - RSIF_IMPORT_EVERYWHERE.

BOOL pf_getProcessOwnerA(unsigned long processId, char * buf, int len);
BOOL pf_getProcessOwnerW(unsigned long processId, wchar_t * buf, int len);

Returns an owner of the specified process formatted as <domain>\<user name>.

processId - Process identifier
buf - Buffer
len - Number of elements in buf

BOOL pf_readHeader(PFStream * pStream, PFHeader * ph);

Loads header from stream.

BOOL pf_writeHeader(PFStream * pStream, PFHeader * ph);

Saves header to stream.

BOOL pf_unzipStream(PFStream * pStream);

Decompresses gzip and br encoded stream contents in-place.

void pf_waitForImportCompletion();

Returns after completion of root certificate import thread. It is possible to call this function after starting the import of SSL root certificate with pf_setRootSSLCertSubject, to suspend the filtering until the root certificate is imported to all storages.

BOOL pf_startLog(const char * logFileName);

Start saving the debug log to the specified file. This function is available only in build configurations release_logs and release_c_api_logs. The log is started automatically, so this function is needed only to restart the log after pf_stopLog call.

void pf_stopLog();

Stop saving the debug log. This function is available only in build configurations release_logs and release_c_api_logs.

Requirements

Header	ProtocolFilters.h
Library	ProtocolFilters.lib