Skip to content

Commit 337aaa1

Browse files
committed
README & ngx_encode_base64url
1 parent c87d21f commit 337aaa1

File tree

2 files changed

+37
-82
lines changed

2 files changed

+37
-82
lines changed

README renamed to README.md

Lines changed: 36 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -4,42 +4,32 @@ Nginx HMAC Secure Link Module
44
Description:
55
--
66

7-
The Nginx HMAC secure link module enhances the security and functionality
8-
of the standard secure link module. Secure token is created using secure
9-
HMAC construction with an arbitrary hash algorithm supported by OpenSSL,
10-
e.g., md5, sha1, sha256, sha512. Furthermore, secure token is created as
11-
described in RFC2104, that is,
12-
H(secret_key XOR opad,H(secret_key XOR ipad, message))
13-
instead of a simple
14-
MD5(secret_key,message, expire).
7+
The Nginx HMAC secure link module enhances the security and functionality of the standard secure link module.
8+
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)`.
159

1610
Installation:
1711
--
1812

19-
You'll need to re-compile Nginx from source to include this module.
20-
Modify your compile of Nginx by adding the following directive
21-
(modified to suit your path of course):
13+
You'll need to re-compile Nginx from source to include this module.
14+
Modify your compile of Nginx by adding the following directive (modified to suit your path of course):
2215

23-
./configure --add-module=/absolute/path/to/nginx-hmac-secure-link
24-
make
25-
make install
16+
./configure --add-module=/absolute/path/to/nginx-hmac-secure-link
17+
make
18+
make install
2619

2720
Usage:
2821
--
2922

30-
Message to be hashed is defined by secure_link_hmac_message, secret_key
31-
is given by secure_link_hmac_secret, and hashing algorithm H is defined
32-
by secure_link_hmac_algorithm. For improved security the timestamp in
33-
ISO 8601 format should be appended to the message to be hashed.
23+
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`.
3424

35-
It is possible to create links with limited lifetime. This is defined by
36-
an optional parameter. If the expiration period is zero or it is not specified,
37-
a link has the unlimited lifetime.
25+
For improved security the timestamp in ISO 8601 format should be appended to the message to be hashed.
26+
27+
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.
3828

3929
Configuration example for server side.
4030

31+
```nginx
4132
location ^~ /files/ {
42-
4333
# Variable to be passed are secure token, timestamp, expiration period (optional)
4434
secure_link $arg_st,$arg_ts,$arg_e;
4535
@@ -64,12 +54,13 @@ location ^~ /files/ {
6454
6555
rewrite ^/files/(.*)$ /files/$1 break;
6656
}
57+
```
6758

68-
Application side should use a standard hash_hmac function to generate hash, which
69-
then needs to be base64url encoded. Example in Perl below.
59+
Application side should use a standard hash_hmac function to generate hash, which then needs to be base64url encoded. Example in Perl below.
7060

71-
# Variable $data contains secure token, timestamp in ISO 8601 format, and expiration
72-
# period in seconds
61+
#### Variable $data contains secure token, timestamp in ISO 8601 format, and expiration period in seconds
62+
63+
```nginx
7364
perl_set $secure_token '
7465
sub {
7566
use Digest::SHA qw(hmac_sha256_base64);
@@ -89,42 +80,44 @@ perl_set $secure_token '
8980
return $data;
9081
}
9182
';
83+
```
9284

9385
A similar function in PHP
9486

95-
$timestamp = date("c");
96-
$expire = 60;
97-
$secret = "my_very_secret_key";
98-
$algo = "sha256";
99-
100-
$stringtosign = "/files/top_secret.pdf" . $timestamp . $expire;
87+
```php
88+
$stringtosign = "/files/top_secret.pdf{$timestam}{$expire}";
89+
$secret = 'my_very_secret_key';
90+
$expire = 60;
91+
$algo = 'sha256';
92+
$timestamp = date('c');
10193

102-
$hashmac = base64_encode(hash_hmac($algo,$stringtosign,$secret,true));
103-
$hashmac = strtr($hashmac,"+/","-_"));
104-
$hashmac = str_replace("=","",$hashmac);
105-
$host = $_SERVER['HTTP_HOST'];
106-
$loc = "https://" . $host . "/files/top_secret.pdf" . "?st=" . $hashmac . "&ts=" . $timestamp . "&e=" . $expire;
94+
$hashmac = base64_encode(hash_hmac($algo, $stringtosign, $secret, true));
95+
$hashmac = strtr($hashmac, '+/', '-_'));
96+
$hashmac = str_replace('=', '', $hashmac);
97+
$host = $_SERVER['HTTP_HOST'];
98+
$loc = "https://{$host}/files/top_secret.pdf?st={$hashmac}&ts={$timestamp}&e={$expire}";
99+
```
107100

108101
It is also possible to use this module with a Nginx acting as proxy server.
109102

110-
The string to be signed is defined in secure_link_hmac_message, the secure_link_token
111-
variable contains then a secure token to be passed to backend server.
103+
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.
112104

105+
```nginx
113106
location ^~ /backend_location/ {
114107
set $expire 60;
115108
116-
secure_link_hmac_message $uri$time_iso8601$expire;
109+
secure_link_hmac_message "$uri$time_iso8601$expire";
117110
secure_link_hmac_secret "my_very_secret_key";
118111
secure_link_hmac_algorithm sha256;
119112
120-
proxy_pass http://backend_server$uri?st=$secure_link_token&ts=$time_iso8601&e=$expire;
113+
proxy_pass "http://backend_server$uri?st=$secure_link_token&ts=$time_iso8601&e=$expire";
121114
}
115+
```
122116

123117

124118
Contributing:
125119
--
126120

127-
Git source repositories:
128-
http://github.com/timo2/nginx-hmac-secure-link/tree/master
121+
Git source repositories: http://github.com/nginx-modules/nginx-hmac-secure-link/tree/master
129122

130123
Please feel free to fork the project at GitHub and submit pull requests or patches.

ngx_http_hmac_secure_link_module.c

Lines changed: 1 addition & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,6 @@ static void *ngx_http_secure_link_create_conf(ngx_conf_t *cf);
3131
static char *ngx_http_secure_link_merge_conf(ngx_conf_t *cf, void *parent,
3232
void *child);
3333
static ngx_int_t ngx_http_secure_link_add_variables(ngx_conf_t *cf);
34-
void ngx_secure_link_encode_base64url(ngx_str_t *dst, ngx_str_t *src);
3534

3635

3736
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,
331330

332331
HMAC(evp_md, key.data, key.len, value.data, value.len, hmac.data, &hmac.len);
333332

334-
ngx_secure_link_encode_base64url(&token, &hmac);
333+
ngx_encode_base64url(&token, &hmac);
335334

336335
v->data = token.data;
337336
v->len = token.len;
@@ -433,40 +432,3 @@ ngx_http_secure_link_add_variables(ngx_conf_t *cf)
433432

434433
return NGX_OK;
435434
}
436-
437-
/* A copy of ngx_encode_base64url from ngx_string.c included in Nginx version 1.5.x */
438-
void
439-
ngx_secure_link_encode_base64url(ngx_str_t *dst, ngx_str_t *src)
440-
{
441-
static u_char basis64[] =
442-
"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
443-
u_char *d, *s;
444-
size_t len;
445-
446-
len = src->len;
447-
s = src->data;
448-
d = dst->data;
449-
450-
while (len > 2) {
451-
*d++ = basis64[(s[0] >> 2) & 0x3f];
452-
*d++ = basis64[((s[0] & 3) << 4) | (s[1] >> 4)];
453-
*d++ = basis64[((s[1] & 0x0f) << 2) | (s[2] >> 6)];
454-
*d++ = basis64[s[2] & 0x3f];
455-
456-
s += 3;
457-
len -= 3;
458-
}
459-
460-
if (len) {
461-
*d++ = basis64[(s[0] >> 2) & 0x3f];
462-
463-
if (len == 1) {
464-
*d++ = basis64[(s[0] & 3) << 4];
465-
} else {
466-
*d++ = basis64[((s[0] & 3) << 4) | (s[1] >> 4)];
467-
*d++ = basis64[(s[1] & 0x0f) << 2];
468-
}
469-
}
470-
471-
dst->len = d - dst->data;
472-
}

0 commit comments

Comments
 (0)