README & ngx_encode_base64url

Author: denji

README renamed to README.md

@@ -4,42 +4,32 @@ Nginx HMAC Secure Link Module
 Description:
 --
 
-The Nginx HMAC secure link module enhances the security and functionality
-of the standard secure link module. Secure token is created using secure
-HMAC construction with an arbitrary hash algorithm supported by OpenSSL,
-e.g., md5, sha1, sha256, sha512. Furthermore, secure token is created as
-described in RFC2104, that is,
-H(secret_key XOR opad,H(secret_key XOR ipad, message))
-instead of a simple 
-MD5(secret_key,message, expire).
+The Nginx HMAC secure link module enhances the security and functionality of the standard secure link module.  
+Secure token is created using secure HMAC construction with an arbitrary hash algorithm supported by OpenSSL, e.g., `md5`, `sha1`, `sha256`, `sha512`. Furthermore, secure token is created as described in RFC2104, that is, `H(secret_key XOR opad,H(secret_key XOR ipad, message))` instead of a simple `MD5(secret_key,message, expire)`.
 
 Installation:
 --
 
-You'll need to re-compile Nginx from source to include this module.
-Modify your compile of Nginx by adding the following directive
-(modified to suit your path of course):
+You'll need to re-compile Nginx from source to include this module.  
+Modify your compile of Nginx by adding the following directive (modified to suit your path of course):
 
-./configure --add-module=/absolute/path/to/nginx-hmac-secure-link
-make
-make install
+    ./configure --add-module=/absolute/path/to/nginx-hmac-secure-link
+    make
+    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. For improved security the timestamp in
-ISO 8601 format should be appended to the message to be hashed.
+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`.
 
-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.
+For improved security the timestamp in ISO 8601 format should be appended to the message to be hashed.
+
+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.
 
+```nginx
 location ^~ /files/ {
-
     # Variable to be passed are secure token, timestamp, expiration period (optional)
     secure_link  $arg_st,$arg_ts,$arg_e;
 
@@ -64,12 +54,13 @@ location ^~ /files/ {
 
     rewrite ^/files/(.*)$ /files/$1 break;
 }
+```
 
-Application side should use a standard hash_hmac function to generate hash, which
-then needs to be base64url encoded. Example in Perl below.
+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
+#### Variable $data contains secure token, timestamp in ISO 8601 format, and expiration period in seconds
+
+```nginx
 perl_set $secure_token '
     sub {
         use Digest::SHA qw(hmac_sha256_base64);
@@ -89,42 +80,44 @@ perl_set $secure_token '
         return $data;
     }
 ';
+```
 
 A similar function in PHP
 
-    $timestamp = date("c");
-    $expire = 60;
-    $secret = "my_very_secret_key";
-    $algo = "sha256";
-
-    $stringtosign = "/files/top_secret.pdf" . $timestamp . $expire;
+```php
+$stringtosign = "/files/top_secret.pdf{$timestam}{$expire}";
+$secret = 'my_very_secret_key';
+$expire = 60;
+$algo = 'sha256';
+$timestamp = date('c');
 
-    $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 . "&ts=" . $timestamp . "&e=" . $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}&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.
+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.
 
+```nginx
 location ^~ /backend_location/ {
     set $expire 60;
 
-    secure_link_hmac_message $uri$time_iso8601$expire;
+    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$uri?st=$secure_link_token&ts=$time_iso8601&e=$expire;
+    proxy_pass "http://backend_server$uri?st=$secure_link_token&ts=$time_iso8601&e=$expire";
 }
+```
 
 
 Contributing:
 --
 
-Git source repositories:
-http://github.com/timo2/nginx-hmac-secure-link/tree/master
+Git source repositories: http://github.com/nginx-modules/nginx-hmac-secure-link/tree/master
 
 Please feel free to fork the project at GitHub and submit pull requests or patches.

ngx_http_hmac_secure_link_module.c

@@ -31,7 +31,6 @@ static void *ngx_http_secure_link_create_conf(ngx_conf_t *cf);
 static char *ngx_http_secure_link_merge_conf(ngx_conf_t *cf, void *parent,
     void *child);
 static ngx_int_t ngx_http_secure_link_add_variables(ngx_conf_t *cf);
-void ngx_secure_link_encode_base64url(ngx_str_t *dst, ngx_str_t *src);
 
 
 static ngx_command_t  ngx_http_hmac_secure_link_commands[] = {
@@ -331,7 +330,7 @@ ngx_http_secure_link_token_variable(ngx_http_request_t *r,
 
     HMAC(evp_md, key.data, key.len, value.data, value.len, hmac.data, &hmac.len);
 
-    ngx_secure_link_encode_base64url(&token, &hmac);
+    ngx_encode_base64url(&token, &hmac);
 
     v->data = token.data;
     v->len = token.len;
@@ -433,40 +432,3 @@ ngx_http_secure_link_add_variables(ngx_conf_t *cf)
 
     return NGX_OK;
 }
-
-/* A copy of ngx_encode_base64url from ngx_string.c included in Nginx version 1.5.x */
-void
-ngx_secure_link_encode_base64url(ngx_str_t *dst, ngx_str_t *src)
-{
-    static u_char   basis64[] =
-            "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
-    u_char         *d, *s;
-    size_t          len;
-
-    len = src->len;
-    s = src->data;
-    d = dst->data;
-
-    while (len > 2) {
-        *d++ = basis64[(s[0] >> 2) & 0x3f];
-        *d++ = basis64[((s[0] & 3) << 4) | (s[1] >> 4)];
-        *d++ = basis64[((s[1] & 0x0f) << 2) | (s[2] >> 6)];
-        *d++ = basis64[s[2] & 0x3f];
-
-        s += 3;
-        len -= 3;
-    }
-
-    if (len) {
-        *d++ = basis64[(s[0] >> 2) & 0x3f];
-
-        if (len == 1) {
-            *d++ = basis64[(s[0] & 3) << 4];
-        } else {
-            *d++ = basis64[((s[0] & 3) << 4) | (s[1] >> 4)];
-            *d++ = basis64[(s[1] & 0x0f) << 2];
-        }
-    }
-
-    dst->len = d - dst->data;
-}