Skip to main content
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 CSRFPrevents forceful browsingPrevents cachingURL obfuscationAllows bookmarking
URL -encryptionConstant keyNo randomXXX
RandomXXXX
Session-based keyNo randomXXXX
RandomXXXX
URL signingConstant keyNo randomXX
RandomXXX
Session-based keyNo randomXXX
RandomXXX
  • 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>.