Mod_Anti_Tamper

-------------------------
Anti Tamper Module for Apache 2.x

Version 0.1 Alpha Experimental.

Copyright (c) 2005 Stefano Di Paola 
Released under GPL 2.0
-------------------------

What Is Mod AntiTamper (AT)

AntiTamper is an Apache 2.x module that could be used to
prevent some sort of url and cookie tampering.

Specifically, AT could stop a lot of those malicious bots that take advantage from search engines.
Moreover, attack techniques like Http Response Splitting and session hijacking/fixation will be mitigated.

For a quick and dirty start go to examples/README.

Is important to notice that mod_anti_tamper is not an alternative to mod_security,
which is more exaustive and useful for all web situations.
AT could be a complement to mod_security.

Introduction

- What is HMAC
HMAC is a validation algorithm to check the integrity of informations coupled with
a secret password.
http://www.faqs.org/rfcs/rfc2104.html

AT will automatically generate a password and will save it in a 'safe' place
(root owner with 600 mode).

How AT Works

 AT is composed by two primary active components.

1. A filter for url links integrity check.
2. A filter for cookie integrity check.

Url Filter

<Preliminary Statement>
At the moment, filtering is applied only when:

1. a query is present. (E.g. "Url?query").

2. Server name is the same server name in url
(eg. "http://www.wisec.it/testpage.php?id=2" on www.wisec.it server)

3. reference is relative Url.
(eg. "/testpage.php?id=2")

4. method is GET.

</Preliminary Statement>

The filter for urls takes an apache generated html page and parses it by using a parser based
on libxml and on mod_proxy_html. Then it rewrites all links by adding a HMAC sign which univocally
validates the url.

HMAC sign validation is computed on the absolute path to server:
E.g.

If we have a link:
<a href="http://www.wisec.it/testpage.php?id=2">click here</a>

AT URL Filter will validate:

/testpage.php?id=2

and will rewrite the link in the following fashion:

<a href="http://www.wisec.it/testpage.php?id=2&_auth=1234567890">click here</a>

Where "_auth" is the variable instanced with the computed sign authentication value.

Consequently the server will accept the request for this url only and only if
"id" is equal to 2 and the request path is "/testpage.php"

Let's see the flow scheme:

1. A client asks for a page on Apache server.
2. Apache generate a html page 'A'.
3. AT reads 'A' and modifies it by computing and adding a sign to every link contained in every html attribute.
4. The client receives the modified html page.

Now there are two kind of possibilities:

A.
5A. User is a normal visitor and by clicking on links in the page can transparently browse on on the web site.
6A. AT infact verifies the sign on the fly and allows browsing by giving access to the requested page.

B.
5B. User is a malicious visitor and tries to change variables values inside the request for some of the links
embedded in the returned page by the Apache server and modified by AT.
6B. AT module computes the sign and compares it with the _auth variable, but as these are not equal,
AT will redirect the user to a predefined page.
The requested (dynamic) page wont see the query and wont elaborate the request.

Cookie Filter

AT intercepts Cookies to and from Apache.
If cookie is from Apache then AT signs the Cookie with HMAC and sends it to the client;
If cookie is from a client, then AT computes the validation sign and compares it with the one inside the cookie.
If there no match the cookie is dropped else the cookie is sent to the server.


For Example:

In the response header we have:
Set-Cookie: PHPSESSID=111111

AT intercepts the cookie computes the sign and then appends it to the cookie:

Set-Cookie: PHPSESSID=111111:_auth=1234567890

The client will store the modified cookie:

PHPSESSID=111111:_auth=1234567890

When the client sends the stored cookie to the server, AT intercepts it and verifies it on the fly.

Again, we have to face two situations:

Scenario A.
 The cookie is validated. AT deletes the sign and forwards the cookie to Apache.

Cookie: PHPSESSID=111111(:_auth=1234567890 <- deleted)

Cookie: PHPSESSID=111111

Scenario B
 Cookie is not validated, AT drops the cookie and doesn't forward it to the Apache chain.
 
Nota Bene: If a cookie is not validate by AT, no redirect will be done.


An example configuration can be found in examples/anti_tamper_http2.config

Configuration Variables.

----------
ATHmacUrl
Syntax: ATHmacUrl [On|Off]

Context: server config, virtual host, directory, .htaccess

Description:
Turns on/off Url Filtering

Default: On
----------


----------
ATHmacCookie

Syntax: ATHmacCookie [On|Off]  

Context: server config, virtual host, directory, .htaccess

Description:
Turns on/off Cookie Filtering

Default: On
----------

----------
ATSetSecretPath

Syntax: ATSetSecretPath <fullpath>

Context: server config

Description:
Sets absolute path for the secret password file. If there is no file a new password will be generated.


Default: /etc/httpd/conf/anti_tamper_secret
----------

----------
ATHmacUseIP

Syntax: ATHmacUseIP [URL|COOKIE|BOTH|NONE]  

Context: server config, virtual host, directory, .htaccess

Description:
Adds Client IP when computes HMAC digest for URL|COOKIE|BOTH|NONE 

Default: NONE
----------

----------
ATSetHmacURLLibrary

Syntax: ATSetHmacURLLibrary <full_path_solib> <exported_function> <authlen>

Context: server config

Description:
By setting this value you can create your own validation digest algorithm on an external shared library stored
in a path defined in <full_path_solib>. 

Your home made function must have the following syntax:

char *exported_function ( request_rec *r , char *data,int data_len, const unsigned char *key,int key_len) 

<authlen> is the (fixed) lenght  in bytes of the digest.

Default:  hmac-sha1 function ( internal ).

----------

----------
ATSetHmacCookieLibrary

Context: server config

Syntax: ATSetHmacCookieLibrary <full_path_solib> <exported_function> <authlen>

Description:
See ATSetHmacURLLibrary

Default: hmac-sha1 function ( internal ).

----------

----------
ATRedirect_url

Syntax: ATRedirect_url <url>  

Context: server config, virtual host, directory, .htaccess

Description:
Page to be redirect on a non validated request. (returns 302 found)
NB. At the moment url must be a static url like /index.php or error.html without any query string like
error.php?error=400.

Default: / (server root)
 
----------

----------
ATSetHMACPrefix

Syntax: ATSetHMACPrefix <prefix>

Context: server config

Description:
The name of the variable containing the digest. (allowed chars [_A-Za-z0-9]).

Default: _auth
----------

----------
ATSetDontModifyPrefix
Syntax: ATSetDontModifyPrefix <prefix>

Context: server config

Description:
If we don't want AT to modify some link, (non trusted links inserted by non trusted users),
we could add this prefix to the url and AT wont modify it in the parsing phase.

Warning: this is true on output pages only.

Default: dontmodify
----------

Wisec is brought to you by...

Wisec is written and mantained by Stefano Di Paola.

Wisec uses open standards, including XHTML, CSS2, and XML-RPC.