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 the event handler class for processing events from NF_EventHandler.

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

  • id – Endpoint id

  • pObject – Filtered object

Description:

Posts 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 the new filter (OT_NEXT, OT_PREV - relative to typeBase)

  • typeBase – Type of the origin filter

Description:

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

BOOL pf_deleteFilter(ENDPOINT_ID id, PF_FilterType type)
Description:

Removes the specified filter from the 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 the filtering chain.

Parameters:

  • id – Endpoint id

  • type – Type of the filter

void pf_setRootSSLCertSubject(const char *rootSubject)
Description:

Specifies the subject of a root certificate, used for generating other SSL certificates.

This name appears in the “Issued by” field of certificates assigned to filtered SSL connections. Default value is “NetFilterSDK”. If the corresponding certificate doesn’t exist in the configuration folder, the library creates it and imports it to CA certificate stores (Windows internal storage, Firefox and other products using Mozilla engine, Opera, Pidgin). Importing works asynchronously in a separate thread.

The additional attributes can be added to the subject name string passed to pf_setRootSSLCertSubject(Ex) as follows:

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 specifying your 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 the root certificate in the fileName buffer, with the length in characters 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 an unexpected disconnect during handshake

EXC_TLS = 1

TLS exceptions, switching the version of the TLS protocol

EXC_CERT_REVOKED = 2

Certificate revocation exceptions

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

Specifies a timeout in seconds for storing SSL filter exceptions. After the specified duration expires, 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 the ePF_RootSSLImportFlag enumeration, allowing control over importing the root SSL certificate to supported stores in pf_setRootSSLCertSubject.

The function can be called before pf_setRootSSLCertSubject.

Possible values for the flags parameter:

RSIF_DONT_IMPORT = 0

Don’t import the root certificate to file stores, except for Windows storage.

RSIF_IMPORT_TO_MOZILLA_AND_OPERA = 1

Import the root certificate only to Opera and Mozilla-based products.

RSIF_IMPORT_TO_PIDGIN = 2

Import the root certificate only to the Pidgin storage.

RSIF_IMPORT_EVERYWHERE = 3

Import the root certificate to all supported file stores.

RSIF_GENERATE_ROOT_PRIVATE_KEY = 4

Generate a unique private key for the 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 a cache file instead of generating them each session.

RSIF_DONT_IMPORT_TO_SYSTEM_STORE = 64

Disable importing the root certificate to system stores

Default value is 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 the owner of the specified process formatted as <domain>\<user name>.

PFObject *PFObject_create(tPF_ObjectType type, int nStreams);
Description:

Creates a new object with the specified type and number of streams

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

Loads a header from a stream.

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

Saves a header to a stream.

BOOL pf_unzipStream(PFStream *pStream)
Description:

Decompresses gzip, brotli and zstd encoded stream contents in place.

void pf_waitForImportCompletion()
Description:

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

BOOL pf_startLog(const char *logFileName)
Description:

Starts saving the debug log to the specified file. This function is available only in the 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 a pf_stopLog call.

void pf_stopLog()
Description:

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

BOOL pf_loadOpenSSLEngine(const char *name)
Description:

Loads and initializes the OpenSSL engine using the provided module file name. To load the engine from the current folder, specify the path as .\engine.dll on Windows, ./engine.so on Linux/macOS. To avoid possible issues, the OpenSSL libraries must be linked dynamically on Linux/macOS.

BOOL pf_assignFile(PFStream *pStream, const char *fileName)
Description:

Assigns a file to the specified stream, so that the content is loaded from and saved to the specified file.