Version: 4.6.x.x LTS

EncryptionFilter

The EncryptionFilter supports signing and encryption of URLs issued by the content provider or the reverse proxy for protection against various kinds of attacks.

The table below provides an overview of the effects of URL encryption and URL signing:

			Prevents CSRF	Prevents forceful browsing	Prevents caching	URL obfuscation	Allows bookmarking
URL -encryption	Constant key	No random		X		X	X
		Random		X	X	X	X
	Session-based key	No random	X	X	X	X
		Random	X	X	X	X
URL signing	Constant key	No random		X			X
		Random		X	X		X
	Session-based key	No random	X	X	X
		Random	X	X	X

URL encryption
URL encryption is configurable and completely transparent. The HTML generated by the content provider is rewritten.
URL signing
URL signing is used to prevent web application attacks such as forceful browsing and CSRF (cross-site request forgery). Signing URLs (i.e. links) thwarts such techniques by ensuring that only links issued by the reverse proxy may be accessed. For standard use, the signature data contains the session ID (session-based key) to ensure that links differ from session to session. The signature is stored in a query string parameter. The filter allows configuration of a set of entry URLs for which signature validation is disabled. These are typically the entry points of your application.
See the chapter Configuring URL signing and form signing on page for a configuration example.

URL tagging

When using encrypted or signed URLs, it may happen that the URL cannot be decrypted or validated. To be able to handle such situations appropriately, nevisProxy must be able to distinguish between unencrypted URLs and errors due to missing keys. This is achieved by building the URL as follows:

/<plain prefix>/<HK><HU><RA><ENC> (in the case of encryption)
/<plain url>?sig=<HK><HU><RA><SIG> (in the case of signing)
with
SIG= base64(hmac(key,plain-url))
ENC = base64(encrypted(key,RA2+plain-url))
RA = base16(random)
RA2 = base16(random2)
HU = base16(hmac(global-key,RA+ENC) (in the case of encryption)
HU = base16(hmac(global-key,RA+SIG) (in the case of signing)
HK = base16(hmac(global-key,key))

plain-url: URL is not signed/encrypted
key: HttpSession Id or configured random
global-key: configured random

info

In base64 encoding, the character / is replaced by - to avoid clashes due to the special meaning of the / character.

Form protection
The EncryptionFilter can also protect HTML forms by signing them. Form protection uses the same tagging scheme as URI protection.
Protection of HTML forms is achieved by creating a signature over the names of the input fields and their value, if there are any (i.e. in case of hidden fields, select, radio, or checkbox buttons). The signature is inserted into the form as a hidden field. Form signatures will prevent web application attacks that involve injection or removal of form fields, or modification of field values.
Limitations
- Form signing is currently only active for POST forms. This is due to the fact that on the HTTP layer, a form GET request cannot be distinguished from a normal GET request issued by the user clicking on a link.
- URL signing currently does not work with GET forms for the same reason, and because most browsers discard any query string in the form action.
- The use of the EncryptionFilter is restricted to HTML4 and/or XHTML1 content.

Classname

ch::nevis::isiweb4::filter::validation::EncryptionFilter

Library

libInputValidationFilter.so.1

Profiles

JavaScript-Parsing: Regular expressions for some common JavaScript constructs containing URLs.

Configuration

AllowQueryStringAppend

Type: string
Usage Constraints: optional, advanced
Default: false
Description: Set ’AllowQueryStringAppend=true’ to enable appending of non-encrypted query parameters to signed or encrypted URLs. Note that using this feature weakens the security of the encryption filter and that it should only be used if necessary, e.g. to integrate HTML forms with ’GET’ or JavaScript.

EntryURL

Type: string arraystring array
Usage Constraints: required, basic feature
Default: -
Description: The set of URLs for which signature verification is disabled.

EntryURLRedirect

Type: boolean
Usage Constraints: optional, advanced
Default: false
Description: If set to true, entry URLs without a valid signature are redirected.

ErrorPolicy

Type: enum: block, redirect, trace
Usage Constraints: optional, basic feature
Default: block
Description: Specifies the behavior of the filter in case of a signature validation error:
- block: The request is blocked and the user receives an error message (default: 403)
- redirect: The request is redirected. Use the following syntax to redirect the request:
```
<status>:<action>[:<url>|:<entryPath>]
```
If you configure the redirect without setting a URL or an entryPath keyword, the filter redirects the request to the first configured entry URL. If the entryPath keyword is set, the filter redirects the request to the entry path of the URL without the key. In case of a specified URL, the request is redirected to the given URL.
Trace: The request is passed through, but a trace message with error severity is generated. See code example:
```
<init-param>
 <param-name>ErrorPolicy</param-name>
 <param-value>
  PLAIN:trace
  UNKNOWN_KEY:redirect:/
  FAILED:redirect:entryPath
 </param-value>
</init-param>
```

ParsingMode

Type: enum: strict, tolerant
Usage Constraints: optional, advanced
Default: strict
Description: -

RelaxationRulesMatchType

Type: enum: uri-match, url-match, uri-query-match, url-query-match
Usage Constraints: optional, advanced
Default: uri-match
Description: Permits configuration of the test string for the RelaxationRule regexp as follows:
- uri-match: absolute URI, i.e. /some-request.html;
- url-match: fully qualified URL, i.e. https://www.adnovum.ch/qualified.html;
- uri-query-match: absolute URI with query string,i.e. /some-request.html?any-query;
- uri-query-match: fully qualified URL with query string,i.e. https://www.adnovum.ch/some-request.html?any-query

SignatureQueryParam

Type: string
Usage Constraints: optional, advanced
Default: sig
Description: The name of the query parameter storing the signature.

SignerKey

Type: string
Usage Constraints: required with URLMode sha1rsa, optional otherwise
Default: -
Description: The path to the file containing the private key for signing URLs.

Random

Type: string
Usage Constraints: optional, advanced
Default: not specified
Description: Defines the random seed for HMAC or AES encryption. If Random is not configured, the HttpSessionID will be used. You can also build random using attributes from the AuthService (AUTH:<key>;) or environment (ENV:<key>;).
An example: AUTH:isiwebuserid;ENV:HTTP_SOMETHING:key;CONST:abcd;

ResponseBufferSize

Type: integer
Usage Constraints: optional, advanced
Default: 8192
Description: Enables response buffering of the container to avoid fragmentation caused by HTML rewriting.
The default (8192) corresponds to the default value of the parameter 'BlockSize' of the Http(s)ConnnectorServlet.

RewriteBufferSize

Type: integer
Usage Constraints: optional, advanced
Default: 16K
Description: The size of the internal buffer (in bytes) for buffering HTML tags.

RandomizeURL

Type: boolean
Usage Constraints: optional, advanced
Default: true
Description: If the attribute RandomizeURL is set to false and Random is configured (see above), identical URLs will be signed/encrypted to the same value. This allows browser caching to work.

URLMode

Type: enum: AES, hmacsha1, hmacmd5, sha1rsa, plain
Usage Constraints: optional, advanced
Default: hmacsha1secure, hmacsha256
Description: This attribute specifies the URL protection mode to use:
- AES: Encrypts the URLs with AES (SHA1).
- AES_SHA256: Encrypts the URLs with AES (SHA256).
- hmacsha1: Signs the URL's query string using the (random) container session ID as a signer key. Uses SHA1 for hashing.
- hmacsha256: Signs the URL's query string using the (random) container session ID as a signer key. Uses SHA256 for hashing.
- hmacmd5: Uses MD5 as hashing algorithm (instead of SHA).
- sha1rsa: Signs queries with the key specified by the attribute SignerKey, and verifies queries with the public key, which is defined by the attribute VerifierCert.
- sha256rsa: Signs queries with the key specified by the attribute SignerKey, and verifies queries with the public key, which is defined by the attribute VerifierCert. Uses SHA256 for hashing.
- plain: Disables URL protection. URL signing offers the same level of protection as URL encryption, but without the drawback of causing mapping problems.

VerifierCert

Type: string
Usage Constraints: required with URLMode sha1rsa, optional otherwise
Default: -
Description: The path to the file containing the certificate to verify URLs.

FormMode

Type: enum: formsig, plain
Usage Constraints: optional, advanced
Default: plain
Description: This attribute specifies the HTML form protection mode to use:
- formsig: Signs forms using a hidden form field (preserves form structure and names).
- plain: Disables form protection.

FormSignatureParam

Type: string
Usage Constraints: optional, advanced
Default: formsig
Description: The name of the hidden form field containing the form signature.

RemoveFormSigParamAfterVerification

Type: boolean
Usage Constraints: optional, advanced
Default: false
Description: Remove the "FormSignatureParameter" after verification is done. Set this attribute to true if you want to prevent that the "FormSignatureParam" is sent to the backend as well.

CheckMultipartFormData

Type: boolean
Usage Constraints: optional, advanced
Default: true
Description: This parameter configures the multipart request verification. Multipart request verification is enabled by default. Set the parameter to "false" to disable the multipart request verification.

ExtraFormRules

Type:
Usage Constraints: optional, advanced
Default: -
Description: Newline separated list of strings with the following syntax:
```
<type>:<name_regex>[:<value-regex>]
```
The field is accepted, if the input matches the defined type, name and optionally value, and the request comes back from the frontend.
This feature is useful if you have an input-type file (which usually generates a multi-part body), but the filename is sent first with Javascript code. This feature will prevent the filter from blocking the file, as long as it matches the defined rule.

IgnoreInlineCSS

Type: boolean
Usage Constraints: optional, advanced
Default: false
Description: This parameter specifies if inline style sheets (i.e. the content of <style> tags in HTML documents) should be ignored.

IgnoreInlineJS

Type: boolean
Usage Constraints: optional, advanced
Default: false
Description: This parameter specifies if inline script (i.e. the content of <script> tags in HTML documents) should be ignored.

IgnoreHTMLComments

Type: boolean
Usage Constraints: optional, advanced
Default: true
Description: This parameter specifies if the contents of HTML comments should be ignored.

CrosslinkURLs

Type: string array
Usage Constraints: optional, advanced
Default: none
Description: A list of fully-qualified URL prefixes that point outside the proxy’s URL namespace. This can be useful for shared static key setups across several proxies, or multiple virtual hosts served by one proxy.

RelaxationRules

Type: string array
Usage Constraints: optional, advanced
Default: none
Description: Enables configuration of a newline-separated list of <regexp>":"*(<relaxation>",") to reduce the number of "false positives".
The following values can be configured for <relaxation>:
- plain-url: Requests with a plain URL, i.e., a URL that is not signed/encrypted, are passed through.
- query-append: Requests with a valid signed/encrypted URL, but an additional part of the query string will be passed through.
- plain-form: Requests containing form data without the hidden field containing the signed form metadata will be passed through.
- form-append: Requests containing form data including the hidden field, but with additional form fields will be passed through.
- form-check-disabled: Requests containing form data will be passed through without any form data check.
  Notes: If there are several rules, the first matching rule will be applied. The default regexp type is "PCRE(da)". Any aggregation of relaxations must be configured explicitly. See example below.
```
<param-value>
^/appl/special/.*$:query-append,form-check-disabled
^/appl/.*$:form-check-disabled
</param-value>
```

PlainTextURLs

Type: string (regex)
Usage Constraints: optional
Default: not set
Description: A list of regular expressions (<regexp>, separated by newlines) matching urls that should not be encrypted. The default regexp type is "PCRE(da)" (see also: Regular expressions).

DumpDirectory

Type: string
Usage Constraints: optional, advanced
Default: none
Description: The path where the content of HTML responses is dumped if an error during their parsing occurs. If ’DumpDirectory’ is specified and the directory is writable, dumping is enabled; otherwise, it is disabled.
Note: For every dumped response a new file is created. The name of the file is the response’s transfer-id plus ".resp" as file extension. The exact location of every dump is printed into the navajo.log.

MaxResponseDumpSize

Type: integer
Usage Constraints: optional, advanced
Default/max: 16 MB
Description: The maximum size of the response dump in kilobytes.

EncryptionPrefix

Type: string array
Usage Constraints: optional, advanced
Default: none
Description: A newline-separated list of strings defining the prefixes of the URI that will be encrypted.

GlobalRandom

Type: string
Usage Constraints: required
Default: -
Description: Defines the random seed used for HMAC tagging any signed or encrypted URL.

ContentTypeHTML

Type: list of content-types
Usage Constraints: optional, advanced
Default: text/html, application/xhtml
Description: Newline- or comma-separated list of content types for HTML. If the content-type of a response starts with one of the configured values, the content is parsed with the respective parser.

Deprecated

This attribute is deprecated. Use ContentTypes.html instead.

ContentTypeJavaScript

Type: list of content-types
Usage Constraints: optional, advanced
Default: text/javascript
Description: Newline or comma-separated list of content types for JavaScript files. If the content-type of a response starts with one of the configured values, the content is parsed with the respective parser.

Deprecated

This attribute is deprecated. Use ContentTypes.javascript instead.

ContentTypeStyleSheet

Type: list of content-types
Usage Constraints: optional, advanced
Default: text/css
Description: Newline- or comma-separated list of content types for style sheets. If the content-type of a response starts with one of the configured values, the content is parsed with the respective parser.

Deprecated

This attribute is deprecated. Use ContentTypes.css instead.

ContentTypes.*

Type: string
Usage Constraints: optional, advanced
Default: -
Description: A newline-separated list of regular expressions that defines the content type. For example: ContentTypes.json=^application/json.
For each *, at least define the ContentType.*.rules parameter.

ContentType.*.rules

Type: string
Usage Constraints: optional, advanced
Default: -
Description: Defines a newline-separated list of regular expressions to identify URLs inside the given content type. The sub-expression must contain the URL to be encrypted/signed (including the entry URL).
The default regexp type is "PCRE(da)" (see also: Regular expressions).
Example: =’(/appl/[/a-zA-Z0-9.]+)’
info
The system will ignore this parameter if the content type is "html" (ContentType.html.rules). To enable the evaluation of the rules for content type HTML, set the parameter ContentType.html.rules.enabled (see below).

ContentType.html.rules.enabled

Type: boolean
Usage Constraints: optional, advanced
Default: false
Description: If this parameter is set to "true", the system will also evaluate the parameter ContentType.*.rules for content type HTML (ContentType.html.rules).
When you configure the parameter ContentType.*.rules for HTML, keep in mind that there are already some built-in HTML rules. If you add these built-in rules to the configuration of ContentType.html.rules, the system will encrypt the URLs twice. These targets are encrypted automatically: HREF, SRC, ICONSRC, ACTION, BACKGROUND, CODEBASE, CODE, IMAGEPATH, LOWSRC, and ARCHIVE.

ContentType.*.rules.ignoreQuotes

Type: string
Usage Constraints: optional, advanced
Default: -
Description: Ignores quotes as parenthesis around a string or similar inside the given ContentType code.

ContentType.*.separators

Type: string
Usage Constraints: optional, advanced
Default: -
Description: Defines the line-separators inside the given ContentType.

MaxMatchLen

Type: integer
Usage Constraints: required, advanced
Default: 2048
Description: Maximum length of a string a regular expression rule may match. The amount of memory needed for response rewriting grows with the configured value. For performance reasons, the maximum should be kept as low as possible. When set to zero, there is no limit to the length of a matched URL. Such a setting is not recommended.

SubstringUrlPatterns

Type: list of regular expressions
Usage Constraints: optional, advanced
Default: not configured
Description: A newline-separated list of patterns used to search for URLs within URLs processed by the filter. The first parenthesized sub-expression returned by the first matching pattern is handled as a separate URL and rewritten before the parent string is processed. One substring replacement is performed at most for any input. The URLs are not recursively processed further.
The patterns should be configured carefully to encrypt/sign any part of the input at most once.
This advanced feature is aimed at web applications that pass URLs in a well-defined format inside the URL suffix known as fragment, separated from the query string by the ’#’ character. If no SubstringUrlPatterns were defined, the fragment would be passed through in plain. A pattern defined to match exclusively on the fragment never results in multiple encryption of any URL processed.
The default regexp type is "PCRE(da)" (see also: Regular expressions).

ParameterWhiteList

Type: string array
Usage Constraints: optional
Default: false
Supported pragmas: break, continue
Description: Newline-separated list of pairs of PCRE regular expressions which specify that a parameter does not need to be checked if it matches the regular expression. Syntax is: <name_regex>:<value_regex>.

EncryptionFilter

Profiles​

Configuration​

AllowQueryStringAppend​

EntryURL​

EntryURLRedirect​

ErrorPolicy​

ParsingMode​

RelaxationRulesMatchType​

SignatureQueryParam​

SignerKey​

Random​

ResponseBufferSize​

RewriteBufferSize​

RandomizeURL​

URLMode​

VerifierCert​

FormMode​

FormSignatureParam​

RemoveFormSigParamAfterVerification​

CheckMultipartFormData​

ExtraFormRules​

IgnoreInlineCSS​

IgnoreInlineJS​

IgnoreHTMLComments​

CrosslinkURLs​

RelaxationRules​

PlainTextURLs​

DumpDirectory​

MaxResponseDumpSize​

EncryptionPrefix​

GlobalRandom​

ContentTypeHTML​

ContentTypeJavaScript​

ContentTypeStyleSheet​

ContentTypes.*​

ContentType.*.rules​

ContentType.html.rules.enabled​

ContentType.*.rules.ignoreQuotes​

ContentType.*.separators​

MaxMatchLen​

SubstringUrlPatterns​

ParameterWhiteList​

Profiles

Configuration

AllowQueryStringAppend

EntryURL

EntryURLRedirect

ErrorPolicy

ParsingMode

RelaxationRulesMatchType

SignatureQueryParam

SignerKey

Random

ResponseBufferSize

RewriteBufferSize

RandomizeURL

URLMode

VerifierCert

FormMode

FormSignatureParam

RemoveFormSigParamAfterVerification

CheckMultipartFormData

ExtraFormRules

IgnoreInlineCSS

IgnoreInlineJS

IgnoreHTMLComments

CrosslinkURLs

RelaxationRules

PlainTextURLs

DumpDirectory

MaxResponseDumpSize

EncryptionPrefix

GlobalRandom

ContentTypeHTML

ContentTypeJavaScript

ContentTypeStyleSheet

ContentTypes.*

ContentType.*.rules

ContentType.html.rules.enabled

ContentType.*.rules.ignoreQuotes

ContentType.*.separators

MaxMatchLen

SubstringUrlPatterns

ParameterWhiteList