mod_download_token

Summary

The mod_download_token is an Apache 2.x module for controlling access to resources (files, pages) on your server. When mod_download_token is enabled for a particular <Location>, it will reject all requests which do not contain a valid token in the URL.

The tokens are typically issued by a script on the webpage and will only be valid for a configured period of time.

This project was inspired by the mod_auth_token Apache module (see http://code.google.com/p/mod-auth-token/), but offers more secure token generation (using SHA-1 function instead of MD5).

Installation

To install mod_download_token from sources, first make sure that you have appropriate developer packages for Apache 2.x available on your system (apxs utility will be required to build the module).

Then untar the sources and run the following command in module's directory:

make install

If everything went OK, you should have the 'mod_download_token.so' file in Apache's module directory.

Now add the following line to Apache's configuration file (typically httpd.conf):

LoadModule download_token_module modules/mod_download_token.so

Restart Apache to load the module.

To confirm that everything was installed correctly, verify that 'download_token_module' is listed in the output of the following command:

apache2 -t -D DUMP_MODULES

Configuration

The mod_download_token does not protect any files by default. To enable protection for a specific set of files on your server, create a similar section in Apache's configuration files:

<Location /protected/directory> DownloadToken On DownloadTokenSecret "secret" DownloadTokenTimeout 10 DownloadTokenHashFunction sha1 </Location>

This configuration will cause mod_download_token to restrict access to any files below the "/protected/directory" path on your server (try opening them in a browser, you will get "401 Unauthorized" HTTP error).

The DownloadToken directive enables token protection for all directories and files below the location path (/protected/directory in the example).

The DownloadTokenSecret directive specifies a password. It ensures that only you can issue tokens to that server location. Change it to something difficult to guess and NEVER make this value public. Note that this option is mandatory! Protection will be disabled if you do not set the secret.

The DownloadTokenTimeout is an optional directive which specifies the time (in seconds) after which tokens will expire. The default value is 60 seconds.

The DownloadTokenHashFunction is an optional directive which selects the hash function used to generate tokens. Currently two hash functions are supported:

• sha1 - the default, more secure, generates 40-character tokens
• md5 - not really safe, only use if you absolutely need short (32-character) tokens

Generating tokens

So now we know how to deny access to files on a server. But how do you grant it back to legitimate users?

This is accomplished by generating specially crafted URLs with tokens.

Let's say that we have a file named 'restricted.txt' in the protected directory. Without the mod_download_token module, it would be available under the following URL: http://serverhost/protected/directory/restricted.txt

With mod_download_token, 'restricted.txt' will only be accessible through this URL: http://serverhost/protected/directory/TOKEN/TIMESTAMP/restricted.txt

Here, the 'http://serverhost/protected/directory/' part of URL is a prefix. Anything in the URL up to the <Location> directory is ignored by mod_download_token.

The '/restricted.txt' is the protected resource. Note that the leading slash is significant.

The TOKEN is a hexadecimal string containing a message digest (result of SHA-1 or MD5 hash function). It authenticates the request, confirming that the URL was generated by a trusted source. To generate TOKEN, you need to concatenate three string values:

• the secret value specified in DownloadTokenSecret
• the path to the protected resource ('/restricted.txt' in this case)
• current timestamp formatted as 8-digit hexadecimal string The resulting string must then be hashed with the hash function specified in the DownloadTokenHashFunction directive (typically SHA-1) to obtain the TOKEN value.

The TIMESTAMP is an 8-digit hexadecimal timestamp when the URL becomes active. It's the same timestamp string which is passed to the MD5 function when generating TOKEN. Note that nothing prevents you from generating URLs with future timestamps. Such URLs will not be active until that time.

Sample PHP code for generating URLs with tokens (assuming that you use the default SHA-1 hash function):

Development

The most current development version of this module is available at: https://github.com/ajakubek/mod_download_token/

Bugs can be reported at: https://github.com/ajakubek/mod_download_token/issues

License

This software is distributed under the MIT license. Please see the LICENSE file included in the package for details.