ICAPFilter

ICAP, the Internet Content Adaption Protocol, is a lightweight protocol that enables an ICAP client to pass HTTP messages to an ICAP server for some sort of transformation or other processing. See RFC 3507 for details.

The main use case for implementing an ICAPFilter is the integration of an external virus scanner such as Kaspersky, Symantec, or CLAM AV. The current ICAPFilter implementation is compliant with Kaspersky (kav4proxy-5.5-5) and CLAM AV (C-ICAP/060708).

A request is sent to the ICAP server only if the request meets all conditions set by the ScanRequest, BodyRequired and ScanRequestHeaderCondition parameters of the ICAPFilter.

A response is sent to the ICAP server only if the response meets all conditions set by the ScanResponse and ScanResponseHeaderCondition parameters, and does not meet the conditions set by the SkipResponseHeaderCondition parameter.

If a response meets both the conditions of the parameters ScanResponseHeaderCondition and SkipResponseHeaderCondition, then the parameter SkipResponseHeaderCondition takes precedence and the response is not sent to the ICAP server.

Classname

ch::nevis::isiweb4::filter::icap::ICAPFilter

Library

libICAPFilter.so.1

Default RequestFlags

+NEEDS_PARAMS +NEEDS_FORM_MULTIPARTS

Configuration

ErrorCode

Type: integer
Usage Constraints: optional
Default: 403

The status code of the answer that is sent if a request is blocked.

ScanRequest

Type: boolean
Usage Constraints: optional
Default: false
Secure Default: true

If set to true, the HTTP request is passed to the ICAP server - file upload scenario.

ScanResponse

Type: boolean
Usage Constraints: optional
Default: false
Secure Default: true

If set to true, the HTTP response is passed to the ICAP server - file download scenario.

BodyRequired

Type: boolean
Usage Constraints: optional, conditional
Default: true
Secure Default: false

If set to true, only HTTP requests with a body are passed on to the ICAP server.

ScanRequestHeaderCondition

Type: string
Usage Constraints: optional
Syntax: <header_name>:<regexp>

If this parameter is configured, the HTTP request is only passed to the ICAP server if the specified header is present and matches the specified regexp. If not configured, all HTTP requests can be passed on to the ICAP server. If the SplitMultipartBody parameter is set to false or the request is not a "multi-part" content type, or the request is a "multi-part" message, but with an empty body, then the headers of the request are tested for matching. Otherwise ("multi-part" message), each part is processed as follows:

• If a part itself is a "multi-part" message, then the part is processed recursively until a "simple" part is found.
• If a part itself is NOT a "multi-part" message ("simple"), then the headers of the part are tested for matching. The current part is sent to the ICAP server ONLY if the specified header is NOT present in the part's headers, OR matches the specified regexp, AND the part meets the condition of the BodyRequired parameter (it had a body if required).

In this context, a message is considered "multi-part", if its main Content-Type is multi-part. The subtype can be anything. For example, multi-part/mixed, multi-part/alternative, multi-part/form-data are all considered as "multi-part" messages.

ScanResponseHeaderCondition

Type: string
Usage Constraints: optional
Syntax: <header_name>:<regexp>

If configured, the HTTP response is only passed on to the ICAP server if the configured header is present and matches the configured regexp. If not configured, all HTTP responses are passed on to the ICAP server.

SkipResponseHeaderCondition

Type: string
Usage Constraints: optional
Syntax: <header_name>:<regexp>

If this parameter is configured, the HTTP response is not passed on to the ICAP server if the specified header is present and matches the specified regexp. If this parameter is not configured, all HTTP responses can be passed on to the ICAP server.

BufferRequest

Type: boolean
Usage Constraints: optional
Default: true

If BufferRequest is set to true, the body of the HTTP request will be buffered. This enables use of ’Message Preview’ and ’204 Not Modified’ of the ICAP protocol for performance optimization. If request buffering is disabled, the HTTP request will be streamed through the ICAP server without any limitation of size on the reverse proxy.

BufferResponse

Type: boolean
Usage Constraints: optional
Default: true

If BufferResponse is set to true, the body of the HTTP response will be buffered. This enables use of ’Message Preview’ and ’204 Not Modified’ of the ICAP protocol for performance optimization. If response buffering is disabled, the HTTP response will be ’streamed through’ the ICAP server without any limitation of size on the reverse proxy.

RequestBufferSize

Type: integer
Usage Constraints: optional
Default: 100000

The maximum size of a HTTP request body that will be buffered.

ResponseBufferSize

Type: integer
Usage Constraints: optional
Default: 100000

The maximum size of a HTTP response body that will be buffered.

AllowRequestModification

Type: boolean
Usage Constraints: optional
Default: false

ICAP servers can include a (modified) HTTP request in a response. If AllowRequestModification is set to true, such HTTP requests are used for further processing. If it is set to false, an error message is returned. Must be enabled if request buffering is disabled.

AllowResponseModification

Type: boolean
Usage Constraints: optional
Default: false

ICAP servers can include a (modified) HTTP response in a response. If AllowResponseModification is set to true, such HTTP responses are sent to the client. If it is set to false, an error message is returned. Must be enabled, if response buffering is disabled.

ResponseLineSize

Type: integer
Usage Constraints: optional, min: 512, max: 524288
Default: 4096

The maximum line size allowed for any header (ICAP or embedded HTTP).

BlockSize

Type: integer
Usage Constraints: optional, min: 512, max: 524288
Default: 4096

The block size for read/write operations.

PreviewSize

Type: integer
Usage Constraints: optional, min: 0, max: 524288
Default: 4096

The ICAP 'Preview Size'. This parameter will set the header "Preview" on REQMOD and RESPMOD. If the PreviewSize is 0, no preview header will be set.

RequestTimeout

Type: integer
Usage Constraints: optional, min: 0, max: 3600000
Default: 120000

The TCP timeout, in milliseconds, for the reading of the response from the ICAP server.

ConnectTimeout

Type: integer
Usage Constraints: optional, min: 0, max: 3600000
Default: 15000

Timeout in milliseconds for opening the TCP connection to the ICAP server.

PropagateFromEnv

Type: string array
Usage Constraints: optional
Default: REMOTE_ADDR:X-Client-IP

An array of <key>:<name> pairs:

• <key>: the key that is used for the environment look-up
• <name>: the name that is used for the propagated property, if the value is given.

The header <name>:<value> is added to the ICAP request. This mechanism makes it possible to pass on additional, non-HTTP information such as IP addresses to the ICAP server.

InetAddress

Type: string
Usage Constraints: required

Address of the ICAP server with the format of <host>:<port>, where <host> may be an IP address or a host name.

HostName

Type: string
Usage Constraints: optional

Configures the host name of the ICAP server. If not configured, the host part of InetAddress is used.

TargetURI

Type: string
Usage Constraints: required

The absolute part of the URI of the ICAP server.

SplitMultipartBody

Type: boolean
Usage Constraints: optional
Default: true

In case of a file upload, the browser sends a multi-part body that contains one or several files. Most virus scanners that act as ICAP servers cannot process multi-part bodies as they are made for scanning simple file downloads. If SplitMultipartBody is set to true, the multi-part upload is split and every part is sent to the ICAP server as an individual ICAP request. If enabled, also enable the BufferRequest parameter and disable the parameter AllowRequestModification.

VerificationMode

Type: enum
Possible values: required, optional
Default: required

If set to optional, all responses will be passed through if the ICAP service is down. Be aware that in this case it becomes possible to inject malicious data if the ICAP service is down.

IncludeRequestHeadersWithResponse

Type: boolean
Usage Constraints: optional
Default: false

If set to true, the request line and request headers are includes as well with the response.

SoLingerTimeout

Type: boolean
Usage Constraints: optional
Default: false

If enabled, it will set the lingering time of the socket to zero. This will hard close the TCP connection in case of a timeout, by sending an RST TCP message instead of the usual FIN TCP message.

PropagateConfig

Type: new-line separated list
Usage Constraints: optional

Defines a newline separated list of <configToPropagate>:<headerName> pairs, where

• <configToPropagate> is the name of the configured parameter to propagate to the ICAP server (currently the parameters AllowResponseModification and AllowRequestModification are supported).
• <headerName> is the name of the header that is used for the propagated parameter. It is strongly recommended to choose a unique name. The system sends the configured parameters with every ICAP request to the server.

DNSCache.TTL

Type: integer
Usage Constraints: optional
Default: 86400

Specifies the time period in seconds to cache DNS info, before the system will retrieve the IP address again.

UseSSL

Type: boolean
Usage Constraints: optional
Default: false

If true, an TLS-connection will be opened to the ICAP-service. The following SSL parameters are only evaluated if UseSSL is true.

SSLProtocol

Type: string
Usage Constraints: optional
Default: -all +TLSv1.2 +TLSv1.3 Secure Default: -all +TLSv1.2 +TLSv1.3

Defines the TLS protocol to be used.

SSLCipherSuites

Type: string
Usage Constraints: optional
Default and secure default: ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:DHE-RSA-AES128-GCM-SHA256

This attribute defines the SSL cipher suite to use. You can set all ciphers that are supported by OpenSSL. You can have maximal 2 newline separated lines with the following syntax: [protocol] cipher-spec, where:

• protocol: The optional protocol specifier can configure the Cipher Suite for a specific SSL version. Possible values include "SSL" for all SSL Protocols up to and including TLSv1.2 and "TLSv1.3" for TLSv1.3. If not set, then SSL is taken.
• cipher-spec: colon-separated cipher-spec string consisting of OpenSSL cipher specifications to configure the Cipher Suite the server is permitted to negotiate in the SSL handshake phase

For a list of TLSv1.3 cipher names, see the OpenSSL documentation (https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_ciphersuites.html).

SSLCACertificateFile

Type: string
Usage Constraints: required if SSLCheckPeerHostname is enabled

Defines the CA certificate file.

SSLClientKeyFile

Type: string
Usage Constraints: optional

Defines the client key file.

SSLClientCertificateFile

Type: string
Usage Constraints: required if a SSLClientKeyFile is set

The X509 node certificate or certificate chain that is sent to the application server if requested by a SSL/TLS CertificateRequest message. If the file contains a certificate chain then the certificates must be in PEM format and must be sorted starting with the subject's certificate (actual client or server certificate), followed by intermediate CA certificates if applicable, and ending at the highest level (root) CA.

SSLCheckPeerHostname

Type: boolean
Usage Constraints: optional
Default: false

Defines if the DNS name is checked against the common name in the certificate.