UrlEncryptionFilter

The UrlEncryptionFilter supports full and partial URL and query encryption. The encrypted URL and query can consist of several encrypted and plain parts, depending on the verification policy. Such a URL will be blocked or passed decrypted to the backend. The UrlEncryptionFilter also supports session stickiness for CSRF protection.

IMPORTANT

If multiple UrlEncryptionFilters are configured, they have to share the same Encryption_Key, Encryption_StatusCode, and Encryption_Provider. For a description of these parameters, see the table UrlEncryptionFilter configuration below.

note

A UrlEncryptionFilter with fully encrypted URLs does not support Set-Cookie headers with the path attribute. This is because on the client side the path will not match the encrypted URL.

Limitations

Due to the complexity of inline JavaScript code, URL encryption may not work correctly in some cases.

For example. if a specific function aJavaScriptFunction does not only perform checks, but also calls URLs, the following content will not work well:

<a href="#" onclick="aJavaScriptFunction()">Some Text</a>

You should replace it with the following content:

<a href="#" onclick="aJavaScriptFunction(); return false">Some Text</a>

So to avoid potential pitfalls, we recommend using as little inline JavaScript as possible. Instead, include JavaScript files that contain the code.

Library

libLuaFilter.so.1

Configuration

Encryption_EntryPoint

• Type:list of newline-separated strings
• Usage Constraints: required

Defines the application/back-end entry points, in the form of a newline-separated list of entry point URLs. These are the only URLs that can always be accessed without being encrypted, irrespectively of the enforcement policy.

Encryption_Provider

• Type: enum: EncryptionDefaultProvider, EncryptionWithMacProvider
• Usage Constraints: optional
• Default: EncryptionDefaultProvider, secure default: EncryptionWithMacProvider

Defines the method that is used to encrypt and decrypt URLs. Both encryption providers encrypt the URL. The provider EncryptionWithMacProvider additionally tags the encrypted URL with a MAC (Message Authentication Code), to prevent modifications. Encryption is done with the AES-128-CBC algorithm, MAC with HmacSHA1 algorithms. This parameter must be the same for all UrlEncryptionFilters in the same instance. So if you change the default in one UrlEncryptionFilter of an instance, also adapt it in the instance's other UrlEncryptionFilters.

Encryption_Key

• Type: string
• Usage Constraints: required

Defines the key used for encryption. For safety reasons it should be at least 16 characters long.

Encryption_MyHosts

• Type: string
• Usage Constraints: optional

Defines a list of hosts which points to us where an absolute URL containing one of those hosts must be encrypted, all other absolute URLs will not be encrypted.

Encryption_UrlEnforcement

• Type: enum: plain, partial, encrypted
• Default: plain, secure default: encrypted

Defines the enforcement policy. Possible values: plain, partial, encrypted.
- Plain: encryption is not needed.
- Partial: a part of the URL must be encrypted.
- Encrypted: The whole URL must be encrypted. Query is not included.

Encryption_Query

• Type: string
• Usage Constraints: optional
• Default: secure default: encrypted

Defines if and how the query must be encrypted. If this attribute is not configured, the query is unaffected by the UrlEncryptionFilter. You can set either encrypted for full query encryption or a list of <parameter-name> = both | value where both means name and value are encrypted and value means only the value is encrypted.
Example 1: encrypted
Example 2: passwd = both; userid = both; id = value

Encryption_Url

• Type: enum: plain, encrypted
• Usage Constraints: optional
• Default: encrypted, secure default: encrypted

Defines if the url should be encrypted:
- encrypted: encrypts the url
- plain: does not encrypt the url.

Encryption_QueryWhiteList

• Type: string
• Usage Constraints: optional
• Default:

Defines which query parameter names do not need to be encrypted. The white list is effectively applied to the EncrytpionQuery parameter. The white listed names are newline-separated and are interpreted as Lua regular expressions. Example: param1 order `[0-9]+ * myprefix _.`

Encryption_Mapping

• Type: String
• Usage Constraints: optional
• Default: text/html.* HtmlUrlEncrypter
• Syntax: <content-type-lua-regex> <encrypter>

Defines which encryption engine to use based on the response's content type. The rules are newline separated.
<encrypter>: Either "HtmlUrlEncrypter", "GenericUrlEncrypter", "GenericUrlRelativeUrlsResolverEncrypter", or "ExtendedHtmlUrlEncrypter".
- HtmlUrlEncrypter: Use this encrypter for all HTML pages (text/HTML).
- GenericUrlEncrypter: Use this option if you expect no relative URL in the page. If you set this value, also specify the parameter Encryption_GenericEncrypterPatterns.
- GenericUrlRelativeUrlsResolverEncrypter: Use this option if you do expect relative URLs in the page. If you set this value, also specify the parameter Encryption_GenericUrlRelativeUrlsResolverEncrypter_PatternsMapping.
- ExtendedHtmlUrlEncrypter: Use this option for all HTML pages (text/HTML), if you need additional rules for special inline JavaScript URLs. If you set this value, also specify the parameter Encryption_ExtendedHtmlUrlEncrypter_Patterns.
If more engines match the content type, they will be executed in the order they are defined. |

Encryption_GenericUrlRelativeUrlsResolverEncrypter_PatternsMapping

• Type: String
• Usage Constraints: optional

This parameter is required if the parameter Encryption_Mapping uses the "GenericUrlRelativeUrlsResolverEncrypter" encrypter. The patterns are newline-separated strings with the following syntax: <content-type-lua-regex> <pattern-parameter-name>
<content-type-lua-regex>: The content type of the response to be encrypted.
<pattern-parameter-name>: The name of the parameter containing the pattern rules. This parameter has the same syntax as the parameter Encryption_GenericEncrypterPatterns. The parameter name has to start with "Encryption_".

Example:

 <init-param>
  <param-name>Encryption_Mapping</param-name>
  <param-value>
   text/html.* HtmlUrlEncrypter
   text/css.* GenericUrlRelativeUrlsResolverEncrypter
  </param-value>
 </init-param>
 <init-param>
  <param-name>Encryption_GenericUrlRelativeUrlsResolverEncrypter_PatternsMapping</param-name>
  <param-value>
   text/css.* Encryption_CssPatterns
  </param-value>
 </init-param>
 <init-param>
  <param-name>Encryption_CssPatterns</param-name>
 <param-value>
   (url%()([^%)]*)(%)) => false true false
  </param-value>
 </init-param>

Encryption_ExtendedHtmlUrlEncrypter_Patterns

• Type: String
• Usage Constraints: optional

This parameter is required if the parameter Encryption_Mapping uses the "GenericUrlRelativeUrlsResolverEncrypter" encrypter. This parameter has the same syntax as the parameter Encryption_GenericEncrypterPatterns.

Code sample:

 <init-param>
 <param-name>Encryption_ExtendedHtmlUrlEncrypter_Patterns</param-name>
 <param-value>
  (addEventListener%("click", function%(")([^%)]*)("%)) => false true false
  </param-value>
 </init-param>
 <init-param>
 <param-name>Encryption_Mapping</param-name>
 <param-value>
   text/html.* ExtendedHtmlUrlEncrypter
 </param-value>
 </init-param>

Encryption_SessionSticky

• Type: enum: on, off
• Usage Constraints: optional
• Default: off

Defines if the URL encryption is bound to a session. If this is set to "on", only URLs which where encrypted in a given session are allowed, all others get blocked.

Encryption_StatusCode

• Type: Integer
• Usage Constraints: optional
• Default: 403

Defines the status code to return if an invalid URL is sent by the front end.

Encryption_StaticIv

• Type: boolean
• Usage Constraints: optional
• Default: false, secure default: false

If StaticIv is set to true, all encrypted values are not-randomized and the same original URL produces always the same encrypted URL. Setting this value to true is not recommended. Default is false.

Encryption_VerifyBody

• Type: boolean
• Usage Constraints: optional
• Default: false

Enables verification of the query parameters found within the request body. Thus, it is not possible to bypass verification. When using html forms that send POST requests on submit, you have to allow the form's parameters to be received by the proxy unencrypted. This can be achieved by listing the parameters that needs to be encrypted in Encrypt_Query or when Encrypt_Query is set to "encrypted", adding the form's parameters to Encrypt_QueryWhitelist. In normal cases, the forms' parameters are the input tags inside the form in the html source, so each input's name attribute have to be listed in the whitelist (even the hidden input).

Encryption_GenericEncrypterPatterns

• Type: string
• Usage Constraints: optional
• Default:

This parameter is required if you have a GenericUrlEncrypter configured in the parameter Encryption_Mapping.
The patterns are newline-separated strings with the following syntax: <lua-regex> => <one or more booleans which part to encrypt>
For example: (href=')(.-)(') => false true false will encypt the part between href='' and '.

Encryption_PlainTextUrls

• Type: string
• Usage Constraints: optional

This parameter defines a newline separated list of Lua regular expressions (lua-regexs) for URLs that should not be encrypted. Anchors are not yet supported.

Example

The web.xml contains the encryption and enforcement of the URL encryption. Let's say on the /a/b you want to have encryption, then just map the following filter to /a/b/*. Let us further assume that the connector's name is my.host.ch.

<filter>
    <filter-name>HTMLUrlEncryption</filter-name>
    <filter-class>ch::nevis::isiweb4::filter::lua::encryption::UrlEncryptionFilter</filter-class>

        <init-param>
            <param-name>Encryption_Key</param-name>
            <param-value>1234567890</param-value>
        </init-param>
        <init-param>
            <param-name>Encryption_EntryPoint</param-name>
            <param-value>/a/b/index.html</param-value>
        </init-param>
        <init-param>
            <param-name>Encryption_UrlEnforcement</param-name>
            <param-value>encrypted</param-value>
        </init-param>
        <init-param>
            <param-name>Encryption_Mapping</param-name>
            <param-value>
                text/html.* HtmlUrlEncrypter
            </param-value>
        </init-param>
        <init-param>
            <param-name>Encryption_MyHosts</param-name>
            <param-value>https://my.host.ch</param-value>
        </init-param>
</filter>

If you also have JavaScript inside HTML and as external resource to rewrite, add a follow-up filter right after the filter "HTMLUrlEncryption".

<filter>
    <filter-name>JSUrlEncryptionFixUp</filter-name>
    <filter-class>ch::nevis::isiweb4::filter::lua::encryption::UrlEncryptionFilter</filter-class>

        <init-param>
            <param-name>Encryption_Key</param-name>
            <param-value>1234567890</param-value>
        </init-param>
        <init-param>
            <param-name>Encryption_EntryPoint</param-name>
            <param-value>/a/b/index.html</param-value>
        </init-param>
        <init-param>
            <param-name>Encryption_Mapping</param-name>
            <param-value>
                text/.* GenericUrlEncrypter
                application/x%-javascript.* GenericUrlEncrypter
            </param-value>
        </init-param>
        <init-param>
            <param-name>Encryption_GenericEncrypterPatterns</param-name>
            <param-value>
                (var.=.")(.-)("(wink) => false true false
            </param-value>
        </init-param>
        <init-param>
            <param-name>Encryption_MyHosts</param-name>
            <param-value>https://my.host.ch</param-value>
        </init-param>
</filter>

If you have only external JavaScript to rewrite, you can define this all in the above "HTMLUrlEncryption" filter definition.

ch::nevis::isiweb4::filter::lua::encryption::UrlEncryptionFilter