What is mod_auth_token ?

mod_auth_token is a famous apache module that allow you to generate URIS for a determined time window, you can also limit them by IP. This is very useful to handle file downloads, generated URIS can't be hot-linked (after it expires), also it allows you to protect very large files that can't be piped trough a script languages due to memory limitation.

Who is using mod_auth_token

Various commercial and video sharing sites are running mod_auth_token module, if you want to be listed here, please fille an issue.

Updates version 1.0.6

New version 1.0.6 is available and has good performance, it has been tested on a heavily loaded site for several months now (www.citiesxl.com From MonteCristo Games). This release introduce a new configuration item (AuthTokenLimitByIp) which limit the access to the ressource only for the ip who generated the link. This release is backward compatible and it should be safe to use on production. The reason that is in beta is the lack of feedback from users.

As always, if you need a feature or found a bug, don't hesitate to fill an issue .

How it works ?

A secret string is shared between the token generator and the Apache server. The token is an hex-encoded MD5 hash of the secret string, relative file path and the timestamp. It is encoded onto the URI as: uri-prefix/token/timestamp-in-hex/rel-path For example : /downloads/dee0ed6174a894113d5e8f6c98f0e92b/43eaf9c5/file_to_protect.txt Apache will verify this token and allow (or not) the access to the resource.

Install

Please read INSTALL file in tgz.

If link are broken before installing, rebuild them by typing rm -f configure autoreconf -fi automake -f ./configure make

You can also grab the latest source code to get the latest patches.

Example

Apache Configuration

First we need to configure the apache server. <Location /downloads/> AuthTokenSecret "secret string" AuthTokenPrefix /downloads/ AuthTokenTimeout 60 AuthTokenLimitByIp off </Location>

By such configuration, we tell Apache that accesses on /downloads/ is protected by : * A timeout of the links set to 60 seconds * The Ip address of the client who generated the token (so people can't share links, this setting is optional)

URI generation

PHP

Now you have to generate URIs on dynamically in such way (here is an example for PHP): ``` $fileName = "/file_to_protect.txt"; // The file to access

// Let's generate the token depending if we set AuthTokenLimitByIp if ($ipLimitation) { $token = md5($secret . $fileName . $hexTime . $_SERVER['REMOTE_ADDR']); } else { $token = md5($secret . $fileName. $hexTime); }

// We build the url $url = $protectedPath . $token. "/" . $hexTime . $fileName; echo $url; ?> ```

Python

Sample python code contributed by Ales Teska ```

!/usr/bin/env python

import os, time, hashlib

secret = "secret string" # Same as AuthTokenSecret protectedPath = "/downloads/" # Same as AuthTokenPrefix ipLimitation = False # Same as AuthTokenLimitByIp hexTime = "{0:x}".format(int(time.time())) # Time in Hexadecimal
fileName = "/file_to_protect.txt" # The file to access

Let's generate the token depending if we set AuthTokenLimitByIp

if ipLimitation: token = hashlib.md5(''.join([secret, fileName, hexTime, os.environ["REMOTE_ADDR"]])).hexdigest() else: token = hashlib.md5(''.join([secret, fileName, hexTime])).hexdigest()

We build the url

url = ''.join([protectedPath, token, "/", hexTime, fileName]) print url ```

Perl

Please note that a perl module made by Assaf Gordon exists to generate URIs: you can check it here : http://search.cpan.org/~agordon/Authen-ModAuthToken-0.03/

Sample perl code contributed by aanbar ```

!/usr/bin/perl

use strict; use warnings;

print protectedPath('SecretWord', '/downloads/', 1, 'file.zip' );

sub protectedPath { use Digest::MD5 qw/md5_hex/; my ( $secret, $protectedPath, $ipLimitation, $fileName ) = @_; my $hexTime = sprintf("%x", time() ); my $token = md5_hex($secret . $fileName. $hexTime); $token = md5_hex($secret . $fileName . $hexTime . $ENV{'REMOTE_ADDR'}) if $ipLimitation; return $protectedPath . $token. '/' . $hexTime . '/' . $fileName; }

``` Of course, you can implement this in any language that you want. Don't hesitate to post here implementations in other languages, they will appear in this page.

Java

Sample Java code contributed by kanchangxin ``` String secret="secret string"; // Same as AuthTokenSecret String protectedPath="/vod/"; // Same as AuthTokenPrefix //boolean ipLimitation=false; // Same as AuthTokenLimitByIp long time= (new Date()).getTime(); // Time in decimal time=time/1000; // timestamp of java is longer than PHP String hexTime =Long.toHexString(time); // hexTime in Hexadecimal
String token =getMD5( (secret+ filePathName + hexTime).getBytes()); return protectedPath +token+"/"+hexTime+ filePathName;

public String getMD5(byte[] source) { String s = null; char hexDigits[] = { '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'a', 'b', 'c', 'd', 'e', 'f' }; try { java.security.MessageDigest md = java.security.MessageDigest .getInstance("MD5"); md.update(source); byte tmp[] = md.digest(); char str[] = new char[16 * 2]; int k = 0; for (int i = 0; i < 16; i++) { byte byte0 = tmp[i]; str[k++] = hexDigits[byte0 >>> 4 & 0xf]; str[k++] = hexDigits[byte0 & 0xf]; } s = new String(str); } catch (Exception e) { e.printStackTrace(); } return s; } ```

More documentation

Ajbapps has made a guide here to setup apache with mod_auth_token for Streaming.

License

mod_auth_token is released under the Apache 2.0 License

Credits

mod_auth_token is an apache module written by Mikael Johansson and by David Alves.

Inspired from mod_secdownload in LIGHTTPD.