Functions

BOOL pf_init(PFEvents *pHandler, const wchar_t *dataFolder)
Parameters:

  • pHandler – A pointer to PFEvents

  • dataFolder – A path to configuration folder, where the library stores SSL certificates and temporary files

Description:

Initialize the library.

void pf_free()
Description:

Free the library.

NF_EventHandler *pf_getNFEventHandler()
Description:

Returns a pointer to event handler class for processing the events from NF_EventHandler.

BOOL pf_postObject(ENDPOINT_ID id, PFObject *pObject)
Parameters:

  • id – Endpoint id

  • pObject – Filtered object

Description:

Post an object to the specified endpoint.

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

  • 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

Description:

Adds a new filter to session filtering chain. See Filters.

BOOL pf_deleteFilter(ENDPOINT_ID id, PF_FilterType type)
Description:

Removes the specified filter from chain.

Parameters:

  • id – Endpoint id

  • type – Type of the filter to remove

int pf_getFilterCount(ENDPOINT_ID id)
Description:

Returns the number of active filters for the specified connection.

Parameters:

id – Endpoint id

BOOL pf_isFilterActive(ENDPOINT_ID id, PF_FilterType type)
Description:

Returns TRUE if there is a filter of the specified type in filtering chain.

Parameters:

  • id – Endpoint id

  • type – Type of the filter

void pf_setRootSSLCertSubject(const char *rootSubject)
Description:

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)
Description:

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)
Description:

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)
Description:

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.

Types of SSL exceptions (enum eEXCEPTION_CLASS)

EXC_GENERIC = 0

Generic exceptions generated because of unexpected disconnect during handshake

EXC_TLS = 1

TLS exceptions, switching version of TLS protocol

EXC_CERT_REVOKED = 2

Certificate revokation exceptions

void pf_setExceptionsTimeout(eEXCEPTION_CLASS ec, unsigned long long timeout)
Description:

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)
Description:

Deletes SSL exceptions of the specified class.

void pf_setRootSSLCertImportFlags(unsigned long flags)
Description:

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 private 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)
Parameters:

  • processId – Process identifier

  • buf – Buffer

  • len – Number of elements in buf

Description:

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

BOOL pf_readHeader(PFStream *pStream, PFHeader *ph)
Description:

Loads header from stream.

BOOL pf_writeHeader(PFStream *pStream, PFHeader *ph)
Description:

Saves header to stream.

BOOL pf_unzipStream(PFStream *pStream)
Description:

Decompresses gzip and br encoded stream contents in-place.

void pf_waitForImportCompletion()
Description:

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)
Description:

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()
Description:

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