Synopsis

This module computes and checks request URLs for a required security token. This module is not compiled by default and must be specified using the

--with-http_secure_link_module

argument to configure when compiling nginx. Note that this module is only supported in nginx version 0.7.18 and higher.

Example usage:

Consider the example where a link that should be accessible throughout a year starting December 22 2010, is located in a given URI. The request URI includes a query string with an argument, st, that specifies the MD5 hash:

http://example.com/p/files/top_secret.pdf?st=PIrEk4JX5gJPTGmvqJG41g&e=1324527723

To construct the above hash, in PHP you can issue the following command (using PHP CLI):

php -r 'print  str_replace("=", "", strtr(base64_encode(md5("segredo/p/files/top_secret.pdf1324527723", TRUE)), "+/", "-_")) . "\n";'

to print the MD5 hash in a separate line. Of course if you're running a web app your app must do this automatically. Note that the MD5 hash is in binary form.

The expire time can obtained by using the time() function in PHP — or similar in other programming language — in order to obtain the Unix epoch.

location /p/ {
    ## This must match the URI part related to the MD5 hash and expiration time.
    secure_link $arg_st,$arg_e;
 
    ## This is how the MD5 hash is built from a secret token, an URI and an 
    ## expiration time.
    secure_link_md5 segredo$uri$arg_e;
 
    ## If the hash is incorrect then $secure_link is a null string.
    if ($secure_link = "") {
        return 403;
    }
 
    ## The current local time is greater than the specified expiration time.
    if ($secure_link = "0") {
        return 403;
    }
 
    ## If everything is ok $secure_link is 1.
}


Directives

secure_link_secret

syntax: secure_link_secret secret_word

default: none

context: location

deprecated: 0.8.50, use secure_link_md5

variables: no

This directive has been deprecated as of nginx 0.8.50 in favor of secure_link_md5.

secure_link

syntax: secure_link md5_hash[,expiration_time]

default: none

context: location

variables: yes

This directive specifies the MD5 hash value and the expiration time of this link URI. The md5_hash should be encoded using Base64 for URLs. expiration_time is the Unix epoch.

If no expiration_time is specified then the link never expires.

secure_link_md5

syntax: secure_link_md5 secret_token_concatenated_with_protected_uri

default: none

context: location

variables: yes

This directive specifies the string you want to be hashed by MD5. The string can be obtained using variables like in the example above. This hash value is compared with the md5_hash given in the secure_link directive. If they agree $secure_link equals 1, otherwise it's the null string.

variables

$secure_link

This variable behaves differently depending on whether secure_link_secret is used or not:

• If using secure_link_secret, when the requested URI is correct, i.e., matches the computed MD5 hash, $secure_link equals the protected URI. Otherwise it's the null string.

• If using secure_link and secure_link_md5, when the requested URI is correct, i.e., matches the computed MD5 hash, then $secure_link equals 1. If the current local time exceeds the $expiration_time then $secure_link equals 0. Otherwise it's the null string.

$secure_link_expires

Equals the $expiration_time when specified.