How to use URL encryption

 
Prerequisites

See article Prerequisites for using URL Encryption.

Introduction

To activate URL encryption, the encryption mode must be specified in the first place. Airlock supports pass phrase-based encryption (PBE) and session-based encryption schemes. The recommended setting is session-based, where all cryptographically encrypted values are only valid during one user's session. The pass phrase-based encryption mode makes it possible to have encrypted URLs, parameters and values valid over multiple user sessions.

Once URL encryption is activated, Airlock encrypts all relative and absolute URLs in the HTML responses of the back-end application. New since Airlock version 4.2.4, also absolute URLs with the same protocol and host name the last request was referred to will be encrypted.

Note: It is necessary to configure at least one exception pattern (see below) in order to use the URL encryption mechanism in a meaningful way. Once URL encryption is activated, Airlock only accepts encrypted URLs with a valid signature. At least one URL must be reachable in the plain format to enter the application context.

Illegal URL redirect location

External redirect location to redirect the user to if an invalid URL is detected.
Note: Invalid URLs may occur because of session timeouts or other terminated sessions and do not imply active attacks in all cases.

Example: /index.html

URL encryption path exception pattern

Once the URL encryption engine is activated for a Mapping, Airlock only accepts encrypted URLs to access the corresponding back-end application servers. However, there must be so-called bookmarks or entry URLs configured, which are accessible without encryption, in order to enter the application context in the first place. The exception patterns can be configured in a list of regular expressions. All incoming URLs that match one of these patterns are accepted by Airlock without encryption. The Ignore Case option specifies whether the pattern should be interpreted as case sensitive or not.

Note: The illegal URL redirect location (see above) must be one of these exceptions if it is located behind the same Mapping. Otherwise, a continuous redirect loop is initiated. It is recommended to only allow very simple and static URLs to be accessed as exceptions.

The following example specifies that the URL /index.html may be accessed without encryption. This way, users can set a bookmark for the index page in their browsers. From that point on, all URLs will be encrypted.

Example: ^/index\.html$

Preconditions / normal case

For URL Encryption to work 'out of the box', Airlock needs to recognise all URLs sent in the response of the back-end application server. This works automatically if the URL is placed in accordance with a common HTML specification.
This are:

• HTML-Tags (<a href="...">, <img src="...">, etc. )
• Meta-Tags (<meta http-equiv="refresh" content="5;URL="/rootpath/path1/">)
• Response Header "Redirect" (Status Code=302, not visible in the HTML source code!)

Important:
Only absolute URLs with the same protocol and host name the last request was referred to will be encrypted.
e.g.: <a href="http://www.mydomain.com/rootpath/path">... 

External, absolute links with different host name and protocol will NOT be encrypted.
e.g.: <a href="http://www.otherdomain.com/path">... 

Before 4.2.4:

Important: Only URLs without protocol and host name will be encrypted. URLs with protocol and host names will be interpreted as links to external systems and thus not changed.
e.g.: <a href="http://www.mydomain.com/rootpath/path">...

Hint: Rewrite links to remove protocol and host names, like for example "http://www.mydomain.com/rootpath/path" to "/rootpath/path".

Rewrite Response Body (any content):
https?://www.mydomain/rootpath/path => /rootpath/path 

Special Cases

If a URL appears in other places in the HTML document, it is possible to communicate to Airlock how such a URL can be recognized, by using special rules. Examples would be:

• Embedded source (<script> or <style> parts)
• Events (e.g. JavaScript attributes as onload, onclick, etc.)

Syntax to mark a URL which has to be encrypted:

?<URL>URL

Airlock 4.2 uses a different syntax (note the question mark and the colon sign):  $<URL>:URL

Example:

<script type="text/javascript">
loadFunctions = function() {
sfHover(Array('mainNavigation'), Array('li'));
preloadImages(Array('fileadmin/images/logo.jpg'));
}

if (window.attachEvent) {
window.attachEvent("onload", loadFunctions);
}
</script> Rewrite Rule:
(anything-before URL)(URL)(anything-after URL) => $1$2$3

e.g.:
(Array\(['"]?)(?<URL>.*)(['"]?\)) => $1$2$3

Better:
(Array\(['"]?)(?<URL>[^)'"]*)(['"]?\)) => $1$2$3

[^)'"] means that ), ' and " are not included in the URL and are used to define the end of the URL.

To rewrite events (e.g. JavaScript events like onclick, onload, etc.) use the same principle, but activate only the checkbox "Events"

Further Examples:
Given embedded JavaScript Code:

<script language="javascript">
...
Array("res/xslt/navigation.xslt");
Array("res/xslt/status_header.xslt","res/xslt/status_ncb.xslt");
Array("ajax_navigation");
...
</script> Solution:
Rewrite Rule to encrypt ALL URLs in in this example:
(Array\(['"]?)(?<URL>[^'")]*)(['"],['"])?(?<URL>[^'")]*)?(['"]?\)) => $1$2$3$4$5

Result:

<script language="javascript">
... 
Array("/javascript/$xp2/8C24M2dZcjIwytNV77oIs79jjcxO2IH/rm5uW+xNvDYI6L55qRpErKvw9JPol9kt$/p/p/p/p/p/p");
Array("/javascript/$xp2/936fRNlNfC0zjx1HoH9+....YxAY5e08Xzm+ECYt5rQ==$/p/p/p/p/p/p","/javascript/$xp2/gL8h32q+nz88PBMjlSun9wj8...SnSbv3fUwbv3RrOAZUtA==$/p/p/p/p/p/p");
Array("/javascript/$xp2/3H83hf5W3/164AoUgVD34TSkLfj3XdhvPn8S7kjk8Fc85ZWXMO4wxHIB3fvZhXLJ$/p/p/p/p/p/p");
...
</script> 

Special URLs and special content types

URLs can appear in other document types as well, for example in document types like "text/css". In this case it is also possible to configure rules so that Airlock recognizes those URLs and encrypt them. Mostly this is used for image URLs in CSS files with content type "text/css", as shown in the following example.

Example:

.calendar thead tr { background: url("/jira/includes/js/calendar/skins/aqua/title-bg.gif") repeat-x 0 100%; color: #000; }
.calendar thead .title { /* This holds the current "month, year" */
font-weight: bold; /* Pressing it will take you to the current date */
text-align: center;
padding: 2px;
With the function "Rewrite Response Body (any content)" it is possible to define the URL to encrypt as follows:

The principle is the same as what we saw in the last chapter. To define the URL to encrypt, use ?<URL>URL as well. For this example and for most other cases, set a default rule using "Rewrite Stylesheet URLs".

The function "Rewrite Response Body (any content)" can also be used if URLs are placed at non HTML conform locations in HTML documents (content-type: "text/html"). In this case not even the function "Rewrite Response Body (HTML only)" with option "URI" will work. 

When will URL encryption not work?

URL encryption does not work if URLs are built or assembled dynamically on the client side e.g. by JavaScript functions.

Example:
window.location ='/dp/english/e_services.jsp?Page=A1'+'&sinj02_Title='+variable+'&isSearch=tr';

Define such URLs as exception patterns.

Useful Tool

During implementation, in some cases it is necessary to use tools to analyse the responses, in order to find the URLs which are not encrypted and may cause trouble. One of these tools is ieHTTPheaders (for Internet Explorer) or Tamper Data when using Mozilla Firefox.

Form Protection

In addition to URL Encryption it is possible to sign all form information of an application. See the article about Form protection.