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: Boolean
• Usage Constraints: optional
• 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 array
• Usage Constraints: required, basic feature
• Description: The set of URLs for which signature verification is disabled.

EntryURLRedirect

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

ErrorPolicy

• Type: enum

• Possible values: 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>]

Configuration

AllowQueryStringAppend

Type: Boolean
Usage Constraint: optional
Default: false

Enables the 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 array
Usage Constraint: required

The set of URLs for which signature verification is disabled.

EntryURLRedirect

Type: Boolean
Usage Constraint: optional
Default: false

If set to true, entry URLs without a valid signature are redirected.

ErrorPolicy

Type: Enum
Possible values: block, redirect, trace
Usage Constraint: optional
Default: block

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 below.

<init-param>
    <param-name>ErrorPolicy</param-name>
    <param-value>
        PLAIN:trace
        UNKNOWN_KEY:redirect:/
        FAILED:redirect:entryPath
    </param-value>
</init-param>

ParsingMode

Type: Enum
Possible values: strict, tolerant
Usage Constraint: optional
Default: strict

The strict parsing mode makes errors terminate the whole parsing process.

RelaxationRulesMatchType

Type: Enum
Possible values: uri-match, url-match, uri-query-match, url-query-match
Usage Constraint: optional
Default: uri-match

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 Constraint: optional
Default: sig

The name of the query parameter storing the signature.

SignerKey

Type: String
Usage Constraint: required with URLMode sha1rsa, optional otherwise

The path to the file containing the private key for signing URLs.

Random

Type: String
Usage Constraint: optional
Default: not specified

Defines the random seed for HMAC or AES encryption. If not configured, the session ID 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 Constraint: optional
Default: 8192

Enables response buffering of the container to avoid fragmentation caused by HTML rewriting. The default value corresponds to the default value of the parameter 'BlockSize' of the Http(s)ConnnectorServlet.

RewriteBufferSize

Type: Integer
Usage Constraint: optional
Default: 16K

The size of the internal buffer (in bytes) for buffering HTML tags.

RandomizeURL

Type: Boolean
Usage Constraint: optional
Default: true

If the attribute RandomizeURL is set to false and Random is configured, identical URLs will be signed/encrypted to the same value. This allows browser caching to work.

URLMode

Type: Enum
Possible values: AES, hmacsha1, hmacmd5, sha1rsa, plain
Usage Constraint: optional
Default: hmacsha256
Secure default: hmacsha256

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 attributeSignerKey,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 Constraint: required with URLMode sha1rsa, optional otherwise

The path to the file containing the certificate to verify URLs.

FormMode

Type: Enum
Possible values: formsig, plain
Usage Constraint: optional
Default: plain

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 Constraint: optional
Default: formsig

The name of the hidden form field containing the form signature.

RemoveFormSigParamAfterVerification

Type: Boolean
Usage Constraint: optional
Default: false

Remove the "FormSignatureParameter" after verification is done. Set this attribute to true if you want to prevent that it is sent to the backend as well.

CheckMultipartFormData

Type: Boolean
Usage Constraint: optional
Default: true

This parameter configures the multipart request verification. Set the parameter to "false" to disable the multipart request verification.

ExtraFormRules

Type: Newline separated list of strings
Usage Constraint: optional
Syntax: <type>:<name_regex>[:<value-regex>]

The field is accepted, if the input matches the defined type, name and optional 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 Constraint: optional
Default: false

This parameter specifies if inline style sheets (i.e. the content of <style> tags in HTML documents) should be ignored.

IgnoreInlineJS

Type: Boolean
Usage Constraint: optional
Default: false

This parameter specifies if inline script (i.e. the content of <script> tags in HTML documents) should be ignored.

IgnoreHTMLComments

Type: Boolean
Usage Constraint: optional
Default: true

This parameter specifies if the contents of HTML comments should be ignored.

CrosslinkURLs

Type: String array
Usage Constraint: optional

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: new-line separated list of strings
Usage Constraint: optional
Syntax: <regexp>:<relaxation>

Enables configuration of rules to reduce the number of false positives. If there are several rules, the first matching rule will be applied. Any aggregation of relaxations must be configured explicitly. 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: See example below.

Example

<param-value>
    ^/appl/special/.*$:query-append,form-check-disabled
    ^/appl/.*$:form-check-disabled
</param-value>

PlainTextURLs

Type: new-line separated list of regular expressions
Usage Constraint: optional
Default: not set

A list of matching urls that should not be encrypted.

DumpDirectory

Type: String
Usage Constraint: optional

The path where the content of HTML responses are dumped if an error during their parsing occurs. If a path is specified and the directory is writable, dumping is enabled. Otherwise, it is disabled. 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 Constraint: optional, advanced
Default: 16 MB

The maximum size of the response dump in kilobytes.

EncryptionPrefix

Type: newline-separated list of strings
Usage Constraint: optional, advanced

A newline-separated list of strings defining the prefixes of the URI that will be encrypted.

GlobalRandom

Type: String
Usage Constraint: required

Defines the random seed used for HMAC tagging any signed or encrypted URL.

ContentTypes.*

Type: newline-separated list of regular expressions
Usage Constraint: optional, advanced

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: newline-separated list of regular expressions
Usage Constraint: optional, advanced

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. Example: =’(/appl/[/a-zA-Z0-9.]+)’

The system will ignore this parameter if the content type is "html", e.g. 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 Constraint: optional, advanced
Default: false

If this parameter is set to "true", the system will also evaluate the parameter ContentType.html.rules for content type HTML. When you configure the parameter 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 Constraint: optional, advanced

Ignores quotes as parenthesis around a string or similar inside the given ContentType code.

ContentType.*.separators

Type: String
Usage Constraint: optional, advanced

Defines the line-separators inside the given ContentType.

MaxMatchLen

Type: Integer
Usage Constraint: optional, advanced
Default: 2048

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: newline-separated list of regular expressions
Usage Constraint: optional, advanced

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.

ParameterWhiteList

Type: newline-separated list of rules
Usage Constraint: optional
Supported pragmas: break, continue
Syntax: <name_regex>:<value_regex>

Newline-separated list of pairs of regular expressions which specify that a parameter does not need to be checked if it matches the regular expression.