FT_SSL¶

Decoder/encoder for TLS/SSL protocol.

Category:
Preprocessor

Supported flags

FF_SSL_TLS

FF_SSL_SELF_SIGNED_CERTIFICATE

FF_SSL_INDICATE_HANDSHAKE_REQUESTS

FF_SSL_TLS_AUTO

FF_SSL_COMPATIBILITY

FF_SSL_VERIFY

FF_SSL_SUPPORT_CLIENT_CERTIFICATES

FF_SSL_INDICATE_SERVER_CERTIFICATES

FF_SSL_INDICATE_EXCEPTIONS

FF_SSL_ENABLE_ALPN

FF_SSL_INDICATE_CLIENT_CERT_REQUESTS

FF_SSL_DECODE_ONLY

FF_SSL_KEEP_SERIAL_NUMBERS

FF_SSL_DONT_IMPORT_SELF_SIGNED

FF_SSL_DISABLE_TLS_1_0

FF_SSL_DISABLE_TLS_1_1

FF_SSL_TLS_COMPATIBILITY

FF_SSL_STRICT_VERIFICATION

FF_SSL_SCT_VERIFICATION

FF_SSL_INDICATE_ALPN_SELECT_PROTOCOL

FF_SSL_ENABLE_OCSP_RESPONSES

FF_SSL_MORE_EXCEPTIONS

Object types

OT_SSL_HANDSHAKE_OUTGOING

OT_SSL_HANDSHAKE_INCOMING

OT_SSL_INVALID_SERVER_CERTIFICATE

OT_SSL_SERVER_CERTIFICATE

OT_SSL_EXCEPTION

OT_SSL_CLIENT_CERT_REQUEST

OT_SSL_HANDSHAKE_OUTGOING_PROTOCOL

Indicates object parts:
yes

The filter uses a man-in-the-middle scheme for decoding the encrypted content. It detects SSL handshakes automatically and generates a compatible SSL certificate for each server. The generated certificates are saved to the cert.db file in the SSL subfolder of the configuration folder specified in the pf_init call. The certificates in cert.db are encrypted. By default, the filter generates a chained certificate inherited from a common root with the default subject “NetFilterSDK”. It is possible to change this name using the pf_setRootSSLCertSubject function.

The generated root certificate is added automatically to the following stores:

Windows certificate storage.
The certificate stores used by Mozilla products (Firefox, Thunderbird) and other products using the same library for SSL communication. There must be an NSS folder containing Mozilla libraries in the same directory as the executable.
Opera certificate storage.

To disable warnings in applications using their own certificate stores, import the ProtocolFilters root certificate into their store manually. The root certificate is stored in the <configuration folder>\SSL\<root name>.cer file, where <configuration folder> is the folder specified in the pf_init call, and <root name> is the name specified in the pf_setRootSSLCertSubject call. The default root certificate file name is NetFilterSDK.cer. The private key is the same for generated root certificates, unless the RSIF_GENERATE_ROOT_PRIVATE_KEY flag is specified in the pf_setRootSSLCertImportFlags call before the first run of pf_setRootSSLCertSubject.

Warning

Administrative rights are required for adding certificates to Windows certificate storage. I.e. the filtering process must have elevated administrative rights.

FF_SSL_SELF_SIGNED_CERTIFICATE¶

When the FF_SSL_SELF_SIGNED_CERTIFICATE flag is specified for the FT_SSL filter, the library generates self-signed certificates for filtered SSL sessions. Applications using Windows certificate storage, such as Internet Explorer, work without warnings in this case too. However, other applications, such as Firefox, show alerts and do not allow continuing data transmission until the user confirms.

SSL exceptions¶

In some cases, it is not possible to filter SSL-protected data. For example, when a client rejects the generated server certificates. In this case, the filter counts unsuccessful attempts to filter an encrypted connection from a process to a host. After the second unsuccessful attempt, it stops trying to decode SSL and creates a record in the x2.db file in the SSL folder to avoid blocking data transmission in the future.

It is possible to control adding exceptions by using the FF_SSL_INDICATE_EXCEPTIONS flag and the pf_setExceptionsTimeout() and pf_deleteExceptions() functions.

FF_SSL_INDICATE_EXCEPTIONS¶

When the FF_SSL_INDICATE_EXCEPTIONS flag is specified in pf_addFilter, the filter calls dataPartAvailable each time the server or client closes a connection during the SSL handshake. In such cases, the SSL filter adds the corresponding remote host:port pair to the list of exceptions after 2 unsuccessful attempts to establish an SSL connection. The indicated objects of type OT_SSL_EXCEPTION have one stream containing the remote host name from the TLS SNI field, or the remote endpoint string host:port if the SNI field is empty. dataPartAvailable can return DPCR_BLOCK to avoid adding the host to the list of exceptions. If it returns any other code, the exception is added as usual.

FF_SSL_INDICATE_HANDSHAKE_REQUESTS¶

When the FF_SSL_INDICATE_HANDSHAKE_REQUESTS flag is specified in pf_addFilter, the filter indicates SSL handshake requests via the dataPartAvailable event. The indicated objects contain one stream with a host name specified in the extended TLS field by a client application. The stream contains an IP address if the client application doesn’t specify a host name during the handshake. The object type is OT_SSL_HANDSHAKE_OUTGOING for outgoing connections and OT_SSL_HANDSHAKE_INCOMING for incoming connections. dataPartAvailable can return one of the following codes:

DPCR_FILTER
continue filtering SSL and decode/encode the transmitted data.
DPCR_BYPASS
don’t filter SSL, remove the SSL filter from the chain and bypass the transmitted packets as-is.
DPCR_BLOCK
close the connection.
DPCR_FILTER_READ_ONLY
enable the FF_SSL_DECODE_ONLY flag and continue filtering SSL without encoding the data between proxy and server.

FF_SSL_DECODE_ONLY¶

When the FF_SSL_DECODE_ONLY flag is enabled, the traffic between proxy and server is not encoded. It is useful, for example, when a local or remote server should handle both HTTP and HTTPS traffic as generic HTTP. It is possible to enable the flag dynamically by returning DPCR_FILTER_READ_ONLY from dataPartAvailable for an OT_SSL_HANDSHAKE_OUTGOING object containing a known domain name.

FF_SSL_TLS_AUTO¶

When the FF_SSL_TLS_AUTO flag is enabled, the filter tries to detect the TLS handshake automatically in the first 8 kilobytes of packets transmitted after adding the filter. It is useful for decoding TLS for unknown protocols that establish an encoded session dynamically using a special protocol command.

FF_SSL_COMPATIBILITY¶

The FF_SSL_COMPATIBILITY flag is required to avoid issues with the RPC over HTTPS protocol in MS Outlook. It is necessary to use this flag when filtering HTTPS connections of Outlook. When this flag is enabled, the filter uses the RC4 algorithm for the SSL session and doesn’t change the size of transmitted packets. In other cases, RPC over HTTPS sometimes hangs in the middle of communicating with Exchange via proxy.

FF_SSL_VERIFY¶

When the FF_SSL_VERIFY flag is specified, the SSL filter verifies the server certificates using Windows API. When a server returns an invalid certificate, for example revoked, expired, self-signed or with an untrusted root, the filter calls dataPartAvailable with an object of type OT_SSL_INVALID_SERVER_CERTIFICATE.

The indicated objects with type OT_SSL_INVALID_SERVER_CERTIFICATE have the following streams:

SSL_ICS_SUBJECT = 0
Certificate subject name
SSL_ICS_DOMAIN = 1
Domain name from the TLS SNI field
SSL_ICS_ERROR = 2
String with hexadecimal error number. It is a bitmask with CERT_TRUST_* error bits
SSL_ICS_CERTIFICATE = 3
Server certificate bytes in DER format

dataPartAvailable can return one of the following codes:

DPCR_FILTER
continue filtering SSL and decode/encode the transmitted data. In this case, the SSL filter substitutes the invalid certificate with its own generated certificate having the same time values, but a valid root.
DPCR_BYPASS
don’t filter SSL. Block the connection once, add the host to the list of exceptions and don’t filter connections with this host:port in the future. The connection is blocked because there is no way to bypass the data immediately at the stage when the server certificate is already requested.
DPCR_BLOCK
close the connection.

If the certificate is not revoked, the SSL filter validates it every 24 hours.

FF_SSL_SUPPORT_CLIENT_CERTIFICATES¶

The FF_SSL_SUPPORT_CLIENT_CERTIFICATES flag can be specified for filtering SSL when a server requires a client certificate. By default, the SSL filter adds an exception in this case. If the FF_SSL_SUPPORT_CLIENT_CERTIFICATES flag is specified, the filter requests a client certificate, tries to find an appropriate certificate with an exportable private key in Windows storage, then uses the found certificate for filtering SSL. So in this case, the SSL filter requires the following:

The client certificate must be imported to Windows storage with an exportable private key, even if the client application uses its own certificate storage. I.e. it is necessary to mark the private key as exportable when importing the certificate from a *.pfx or *.p12 file.
To have access to all user certificate stores, the filtering application must run as a service under the LocalSystem account.

FF_SSL_INDICATE_SERVER_CERTIFICATES¶

When the FF_SSL_INDICATE_SERVER_CERTIFICATES flag is specified in pf_addFilter, the filter indicates SSL server certificates via the dataPartAvailable event. The indicated objects of type OT_SSL_SERVER_CERTIFICATE have 3 streams:

SSL_SCS_CERTIFICATE = 0
Server certificate bytes
SSL_SCS_SUBJECT = 1
Certificate subject name
SSL_SCS_ISSUER = 2
Certificate issuer name

The filtering application can analyze the certificate and return one of the following codes:

DPCR_FILTER
continue filtering SSL and decode/encode the transmitted data.
DPCR_BYPASS
don’t filter SSL. Block the connection once, add the host to the list of exceptions and don’t filter connections with this host:port in the future. The connection is blocked because there is no way to bypass the data immediately at the stage when the server certificate is already requested.
DPCR_BLOCK
close the connection.

FF_SSL_INDICATE_CLIENT_CERT_REQUESTS¶

When the FF_SSL_INDICATE_CLIENT_CERT_REQUESTS flag is enabled and the server requests a client certificate, the SSL filter indicates via dataPartAvailable an object of type OT_SSL_CLIENT_CERT_REQUEST containing the following streams:

SSL_CCS_DOMAIN = 0
Domain name from the TLS SNI field
SSL_CCS_CERTIFICATE = 1
Certificate bytes in DER format
SSL_CCS_PKEY = 2
Private key bytes in DER format

The SSL_CCS_DOMAIN stream contains the server domain name (or IP address if the name is not specified in SNI). If dataPartAvailable returns DPCR_BYPASS, the SSL filter adds the host to the internal list of exceptions and doesn’t try to filter SSL for this host in the future. If dataPartAvailable returns DPCR_FILTER, it is possible to specify a client-side certificate in the SSL_CCS_CERTIFICATE stream and a private key in the SSL_CCS_PKEY stream, in DER (ASN.1) format. If the certificate is not specified, the request is forwarded to the client application. For any other return code, certificate requests are handled as described above when the FF_SSL_SUPPORT_CLIENT_CERTIFICATES flag is enabled.

FF_SSL_ENABLE_ALPN¶

The FF_SSL_ENABLE_ALPN flag enables the TLS extension for negotiating the next protocol (e.g. HTTP/2, SPDY, HTTP/1.1). The flag is disabled by default to block HTTP/2 and SPDY. In this case, browsers use generic HTTP 1.0 and 1.1 protocols supported by the HTTP filter. When the FT_HTTP2 filter is added, the FF_SSL_ENABLE_ALPN flag is added automatically. Also, the h2 protocol is negotiated in this case, and http/1.1 if FT_HTTP is added too.

FF_SSL_INDICATE_ALPN_SELECT_PROTOCOL¶

The FF_SSL_INDICATE_ALPN_SELECT_PROTOCOL flag enables indication of each ALPN protocol offered by the client via dataPartAvailable as OT_SSL_HANDSHAKE_OUTGOING_PROTOCOL objects. Each protocol is indicated as a separate OT_SSL_HANDSHAKE_OUTGOING_PROTOCOL object. The objects contain a protocol name in a single stream. If dataPartAvailable returns DPCR_FILTER for a protocol from OT_SSL_HANDSHAKE_OUTGOING_PROTOCOL, the protocol is selected for negotiation with the server. Any other return code blocks negotiation of the protocol, so it cannot be used in the corresponding session.

FF_SSL_KEEP_SERIAL_NUMBERS¶

The FF_SSL_KEEP_SERIAL_NUMBERS flag instructs to copy serial numbers from original server certificates. It is useful if they are required by client applications.

FF_SSL_DONT_IMPORT_SELF_SIGNED¶

FF_SSL_DONT_IMPORT_SELF_SIGNED - don’t import the generated self-signed certificates to trusted stores.

FF_SSL_DISABLE_TLS_1_0, FF_SSL_DISABLE_TLS_1_1¶

FF_SSL_DISABLE_TLS_1_0: Disable TLS 1.0 protocol support for connections with remote servers.
FF_SSL_DISABLE_TLS_1_1: Disable TLS 1.1 protocol support for connections with remote servers.

FF_SSL_TLS_COMPATIBILITY¶

FF_SSL_TLS_COMPATIBILITY - enable automatic switching to the old TLS 1.0 protocol when the server doesn’t support newer versions. When the TLS handshake fails, the SSL filter tries to establish a TLS 1.0 session. If it succeeds, the SSL filter adds a TLS exception (EXC_TLS) and uses TLS 1.0 for subsequent sessions with the corresponding host:port.

FF_SSL_STRICT_VERIFICATION¶

FF_SSL_STRICT_VERIFICATION - use strict rules when the FF_SSL_VERIFY flag is enabled. As a result, connections from clients and servers using old versions of the TLS protocol may fail. Full DH key checks are executed no more than once a day for each host. On Linux/macOS, this flag also enables CRL and optionally OCSP validation.

FF_SSL_SCT_VERIFICATION¶

FF_SSL_SCT_VERIFICATION - enable Signed Certificate Timestamps verification for server certificates when the FF_SSL_VERIFY flag is enabled.

FF_SSL_ENABLE_OCSP_RESPONSES¶

FF_SSL_ENABLE_OCSP_RESPONSES - enable OCSP responses for generated certificates. It allows fixing issues with applications like curl.exe that have validation of the revocation status of server certificates enabled by default.

FF_SSL_MORE_EXCEPTIONS¶

This flag allows adding SSL exceptions when the TLS handshake is prematurely aborted by the client, in situations that sometimes lead to false positives. It is possible to use this flag when it is necessary to avoid blocking TLS connections when a client uses various kinds of protection from MITM.

Known issues¶

Some versions of Windows Update use additional certificate checks. SSL is filtered properly, but after establishing a connection and transmitting several packets, it is blocked by the Windows Update service. To avoid issues, don’t add the SSL filter for svchost.exe.
Windows Office services use additional certificate checks. Add exceptions for ucmapi.exe, fixmapi.exe and other Office processes that require online authentication.
MS Teams TCP connections via HTTPS proxy cannot be filtered properly. Don’t add the SSL filter for the teams.exe process.

In other cases, when some application doesn’t work properly with the SSL filter, it is possible to implement in your application a whitelist of processes/domains/IPs/ports to avoid filtering SSL in such cases. It is possible to use the FF_SSL_INDICATE_HANDSHAKE_REQUESTS flag for the SSL filter, analyze the whitelist parameters in the dataPartAvailable event and return DPCR_BYPASS to disable filtering SSL at the handshake stage. The domain names taken from the SNI field of TLS extensions are indicated in OT_SSL_HANDSHAKE_OUTGOING objects.