vmod_secdown

Varnish Secure Download Module

Author:	Aurelien Guillaume
Date:	2011-08-08
Version:	1.1
Manual section:	3

SYNOPSIS

import secdown

DESCRIPTION

For specific purposes, i had to imagine a way to use Varnish as a cache for various files that should be protected against hotlinking/mass downloading. Protection by the referer was not enough, so unique downloads links had to be generated, but I still wanted the files to be cached by Varnish.

So, this module is freely inspired from the functionnality described at http://wiki.nginx.org/HttpSecureDownload and it should be compatible with this implementation.

At this stage, this module is mostly a proof-of-concept; it has only received minimal testing and we have never used it in production. I will update this file if/when it reaches a more usable status.

So far the module builds and runs on Linux--on other platforms, you are on your own.

Patches are welcome.

FUNCTIONS

vmod_secdown implements the following calls:

check_url

Prototype

check_url(STRING protected_url, STRING secret, STRING expired_url, STRING error_url)

Return value

STRING (URL that the user should be directed to)

Description

Checks the validity of a protected URL. A protected URL looks like this::

http://hostname/path/to/protected/file/<md5_hash>/<expiration_timestamp>

Optionnally, the check can be relaxed to a prefix instead of a full path::

http://hostname/path/to/protected/file/<md5_hash>/<expiration_timestamp>x<prefix_len>

Since Varnish already does some processing on the URL, req.url, which does not contain the http://hostname part is probably a good candidate in your VCL scripts.

expiration_timestamp is a 8-digit unix_timestamp (seconds since beginning of 1970) in hexadecimal format.

prefix_len is a 4-digit hexadecimal number representing the maximal path len to consider for inclusion in MD5 hashs.

md5_hash is a MD5 hash generated out of the following string, by your application::

/path/to/protected/file/<secret>/<expiration_timestamp>

if prefix_len is set, the path will be cut to this number of bytes, and "x<prefix_len>" will be added to the string to be hashed.

The secret is some secret string of your choice, known only of your application, which will serve to generate the expiring links.

The function check_url will return a string, which will be either:

expired_url, when the hash is valid, but the timestamp is in the past..
error_url if there's been another error (bad hash, bad url scheme, other internal errors)

Examples

Protection of the /protected/ directory.:

if (req.url ~ "^/protected/")
{
        set req.url = secdown.check_url(req.url, "h4ckme", "/expired.html", "/error.html")
}

COPYRIGHT

This document is licensed under the same licence as Varnish itself. See LICENCE for details.

footplus / libvmod-secdown