Skip to main content
Version: 5.7.x.x Java 8 ELS

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 effects of URL encryption and URL signing 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: 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>]

    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
  • 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​

  • ype: Boolean
  • sage Constraint: optional
  • efault: true
  • f the attribute RandomizeURL is set to false and Random is configured, identical URs 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: hmacsha1
  • 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.
<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.