Added timestamps in ISO 8601 format. Support for proxy mode

Author: omonar

README

@@ -27,42 +27,99 @@ make install
 Usage:
 --
 
-Message to be hashed is defined by secure_link_hmac_message, secret_key 
-is given by secure_link_hmac_secret, and hashing algorithm H is defined 
-by secure_link_hmac_algorithm. The expiration timestamp can be either 
-appended to secret key, or message to be hashed, or both.
+Message to be hashed is defined by secure_link_hmac_message, secret_key
+is given by secure_link_hmac_secret, and hashing algorithm H is defined
+by secure_link_hmac_algorithm. For improved security the timestamp in
+ISO 8601 format should be appended to the message to be hashed.
 
-Configuration example below.
+It is possible to create links with limited lifetime. This is defined by
+an optional parameter. If the expiration period is zero or it is not specified,
+a link has the unlimited lifetime.
+
+Configuration example for server side.
 
 location ^~ /files/ {
-    secure_link $arg_st,$arg_e;
-    secure_link_hmac_secret my_secret_key$arg_e;
-    secure_link_hmac_message $uri;
+
+    # Variable to be passed are secure token, timestamp, expiration period (optional)
+    secure_link  $arg_st,$arg_ts,$arg_e;
+
+    # Secret key
+    secure_link_hmac_secret my_secret_key;
+
+    # Message to be verified
+    secure_link_hmac_message $uri$arg_ts$arg_e;
+
+    # Cryptographic hash function to be used
     secure_link_hmac_algorithm sha256;
 
-    if ($secure_link = "") {
-	return 403;
-    }
+    # If the hash is incorrect then $secure_link is a null string.
+    # If the hash is correct but the link has already expired then $secure_link is zero.
+    # If the hash is correct and the link has not expired then $secure_link is one.
 
-    if ($secure_link = "0") {
-	return 410;
+    # In production environment, we should not reveal to potential attacker
+    # why hmac authentication has failed
+    if ($secure_link != "1") {
+        return 404;
     }
 
-    rewrite ^/files/(.$)$ /files/$1 break;
+    rewrite ^/files/(.*)$ /files/$1 break;
 }
 
-Application side should use a standard hash_hmac function to generate
-hash, which then needs to be base64 encoded. Example in PHP
+Application side should use a standard hash_hmac function to generate hash, which
+then needs to be base64url encoded. Example in Perl below.
+
+# Variable $data contains secure token, timestamp in ISO 8601 format, and expiration
+# period in seconds
+perl_set $secure_token '
+    sub {
+        use Digest::SHA qw(hmac_sha256_base64);
+        use POSIX qw(strftime);
+
+        my $now = time();
+        my $tz = strftime("%z", localtime($now));
+        $tz =~ s/(\d{2})(\d{2})/$1:$2/;
+        my $timestamp = strftime("%Y-%m-%dT%H:%M:%S", localtime($now)) . $tz;
+        my $expire = 60;
+        my $key = "my_very_secret_key";
+        my $r = shift;
+        my $data = $r->uri;
+        my $digest = hmac_sha256_base64($data . $timestamp . $expire,  $key);
+        $digest =~ tr(+/)(-_);
+        $data = "st=" . $digest . "&ts=" . $timestamp . "&e=" . $expire;
+        return $data;
+    }
+';
+
+A similar function in PHP
 
-    $expire = time() + 3600;
-    $secret = "my_secret_key" . $expire;
+    $timestamp = date("c");
+    $expire = 60;
+    $secret = "my_very_secret_key";
     $algo = "sha256";
-    $path = "/files/top_secret.pdf";
-    $hashmac = base64_encode(hash_hmac($algo,$path,$secret,true));
+
+    $stringtosign = "/files/top_secret.pdf" . $timestamp . $expire;
+
+    $hashmac = base64_encode(hash_hmac($algo,$stringtosign,$secret,true));
     $hashmac = strtr($hashmac,"+/","-_"));
     $hashmac = str_replace("=","",$hashmac);
     $host = $_SERVER['HTTP_HOST'];
-    $loc = "https://" . $host . "/files/top_secret.pdf" . "?st=" . $hashmac . "&e=" . $expire;
+    $loc = "https://" . $host . "/files/top_secret.pdf" . "?st=" . $hashmac . "&ts=" . $timestamp . "&e=" . $expire;
+
+It is also possible to use this module with a Nginx acting as proxy server.
+
+The string to be signed is defined in secure_link_hmac_message, the secure_link_token
+variable contains then a secure token to be passed to backend server.
+
+location ^~ /backend_location/ {
+                set $expire 60;
+
+                secure_link_hmac_message $uri$time_iso8601$expire;
+                secure_link_hmac_secret "my_very_secret_key";
+                secure_link_hmac_algorithm sha256;
+
+                proxy_pass http://backend_server_ip_$uri?st=$secure_link_token&ts=$time_iso8601&e=$expire;
+        }
+
 
 Contributing:
 --