Skip to content

Readme additions #77

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Readme additions #77

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5e9ec9b
Some formatting and an example for CF with HLS
Jul 22, 2019
bb00a2e
.
Jul 22, 2019
9e40839
indents
Jul 22, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
125 changes: 81 additions & 44 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,11 @@ In addition, the module supports the encryption of URIs with a configured key.

## Build

To link statically against nginx, cd to nginx source directory and execute:
To link statically against Nginx, cd to the Nginx source directory and execute:

./configure --add-module=/path/to/nginx-secure-token-module

To compile as a dynamic module (nginx 1.9.11+), use:
To compile as a dynamic module (Nginx 1.9.11+), use:

./configure --add-dynamic-module=/path/to/nginx-secure-token-module

Expand All @@ -22,7 +22,7 @@ Requires OpenSSL.

### Generic token parameters

#### secure_token
#### `secure_token`
* **syntax**: `secure_token value`
* **default**: `none`
* **context**: `http`, `server`, `location`
Expand All @@ -31,101 +31,101 @@ Sets the value of the token that should be embedded in the manifest/returned as
The parameter value can contain variables, and often points to variables set by this module
(using `secure_token_akamai` / `secure_token_cloudfront` blocks)

#### secure_token_avoid_cookies
#### `secure_token_avoid_cookies`
* **syntax**: `secure_token_avoid_cookies on/off`
* **default**: `on`
* **context**: `http`, `server`, `location`

When enabled the module prefers to use a query string token instead of a cookie token.
A query string token is currently supported only for the following mime types (other mime types return a cookie token):
* application/vnd.apple.mpegurl
* application/dash+xml
* video/f4m
* `application/vnd.apple.mpegurl`
* `application/dash+xml`
* `video/f4m`

#### secure_token_types
#### `secure_token_types`
* **syntax**: `secure_token_types mime_type ...`
* **default**: `none`
* **context**: `http`, `server`, `location`

Defines a set of mime types that should return a token

#### secure_token_uri_filename_prefix
#### `secure_token_uri_filename_prefix`
* **syntax**: `secure_token_uri_filename_prefix prefix`
* **default**: `none`
* **context**: `http`, `server`, `location`

Defines a set of prefixes that will be matched against the URI file name, only URIs whose file name
starts with one of the defined prefixes will return a token

#### secure_token_expires_time
#### `secure_token_expires_time`
* **syntax**: `secure_token_expires_time time`
* **default**: `none`
* **context**: `http`, `server`, `location`

Sets the expiration time of responses that are not tokenized
(determines the values of the Cache-Control and Expires HTTP headers)

#### secure_token_cookie_token_expires_time
#### `secure_token_cookie_token_expires_time`
* **syntax**: `secure_token_cookie_token_expires_time time`
* **default**: `none`
* **context**: `http`, `server`, `location`

Sets the expiration time of responses that are tokenized with a cookie token
(determines the values of the Cache-Control and Expires HTTP headers)

#### secure_token_query_token_expires_time
#### `secure_token_query_token_expires_time`
* **syntax**: `secure_token_query_token_expires_time time`
* **default**: `none`
* **context**: `http`, `server`, `location`

Sets the expiration time of responses that are tokenized with a query string token
(determines the values of the Cache-Control and Expires HTTP headers)

#### secure_token_cache_scope
#### `secure_token_cache_scope`
* **syntax**: `secure_token_cache_scope scope`
* **default**: `public`
* **context**: `http`, `server`, `location`

Sets the cache scope (public/private) of responses that are not tokenized

#### secure_token_token_cache_scope
#### `secure_token_token_cache_scope`
* **syntax**: `secure_token_token_cache_scope scope`
* **default**: `private`
* **context**: `http`, `server`, `location`

Sets the cache scope (public/private) of responses that are tokenized (query / cookie)

#### secure_token_last_modified
#### `secure_token_last_modified`
* **syntax**: `secure_token_last_modified time`
* **default**: `Sun, 19 Nov 2000 08:52:00 GMT`
* **context**: `http`, `server`, `location`

Sets the value of the last-modified header of responses that are not tokenized.
An empty string leaves the value of last-modified unaltered, while the string "now" sets the header to the server current time.

#### secure_token_token_last_modified
#### `secure_token_token_last_modified`
* **syntax**: `secure_token_token_last_modified time`
* **default**: `now`
* **context**: `http`, `server`, `location`

Sets the value of the last-modified header of responses that are tokenized (query / cookie)
An empty string leaves the value of last-modified unaltered, while the string "now" sets the header to the server current time.

#### secure_token_content_type_m3u8
#### `secure_token_content_type_m3u8`
* **syntax**: `secure_token_content_type_m3u8 type`
* **default**: `application/vnd.apple.mpegurl`
* **context**: `http`, `server`, `location`

Sets the content type that should be parsed as m3u8 for token insertion

#### secure_token_content_type_mpd
#### `secure_token_content_type_mpd`
* **syntax**: `secure_token_content_type_mpd type`
* **default**: `application/dash+xml`
* **context**: `http`, `server`, `location`

Sets the content type that should be parsed as mpd for token insertion

#### secure_token_content_type_f4m
#### `secure_token_content_type_f4m`
* **syntax**: `secure_token_content_type_f4m type`
* **default**: `video/f4m`
* **context**: `http`, `server`, `location`
Expand All @@ -134,7 +134,7 @@ Sets the content type that should be parsed as f4m for token insertion

### Akamai token parameters

#### secure_token_akamai
#### `secure_token_akamai`
* **syntax**: `secure_token_akamai $variable { ... }`
* **context**: `http`

Expand All @@ -149,40 +149,40 @@ The block supports the following parameters:

Sets the secret key.

#### param_name
#### `param_name`
* **syntax**: `param_name name`
* **default**: `__hdnea__`

Sets the token parameter name (either the name of the cookie or the query string parameter)

#### acl
#### `acl`
* **syntax**: `acl acl`
* **default**: `$secure_token_baseuri_comma`

Sets the signed part of the URL (ACL). The parameter value can contain variables.

#### start
#### `start`
* **syntax**: `start time`
* **default**: `0`

Sets the start time of the token (see `Time format` below)

#### end
#### `end`
* **syntax**: `end time`
* **default**: `86400`

Sets the end time of the token (see `Time format` below)

#### ip_address
#### `ip_address`
* **syntax**: `ip_address address`
* **default**: `none`

Sets the IP address that should be embedded in the token.
The parameter value can contain variables, e.g. $remote_addr.
The parameter value can contain variables, e.g. `$remote_addr`.

### CloudFront token parameters

#### secure_token_cloudfront
#### `secure_token_cloudfront`
* **syntax**: `secure_token_cloudfront $variable { ... }`
* **context**: `http`

Expand All @@ -191,31 +191,31 @@ parameters specified within the block.

The block supports the following parameters:

#### private_key_file
#### `private_key_file`
* **syntax**: `private_key_file filename`
* **default**: `N/A (mandatory)`

Sets the file name of the private key (PEM file)

#### key_pair_id
#### `key_pair_id`
* **syntax**: `key_pair_id id`
* **default**: `N/A (mandatory)`

Sets the key pair id

#### acl
#### `acl`
* **syntax**: `acl acl`
* **default**: `$secure_token_baseuri_comma`

Sets the signed part of the URL (ACL). The parameter value can contain variables.

#### end
#### `end`
* **syntax**: `end time`
* **default**: `86400`

Sets the end time of the token (see `Time format` below)

#### ip_address
#### `ip_address`
* **syntax**: `ip_address address`
* **default**: `none`

Expand All @@ -224,28 +224,28 @@ The parameter value can contain variables, e.g. $remote_addr/32 can be used to l

### URI encryption parameters

#### secure_token_encrypt_uri
#### `secure_token_encrypt_uri`
* **syntax**: `secure_token_encrypt_uri on/off`
* **default**: `off`
* **context**: `http`, `server`, `location`

Enables/disables uri encryption
Enables/disables URI encryption

#### secure_token_encrypt_uri_key
#### `secure_token_encrypt_uri_key`
* **syntax**: `secure_token_encrypt_uri_key key_hex`
* **default**: `none`
* **context**: `http`, `server`, `location`

Sets the encryption key, the key has to be 256 bits (64 hex characters)

#### secure_token_encrypt_uri_iv
#### `secure_token_encrypt_uri_iv`
* **syntax**: `secure_token_encrypt_uri_iv iv_hex`
* **default**: `none`
* **context**: `http`, `server`, `location`

Sets the encryption iv, the iv has to be 128 bits (32 hex characters)

#### secure_token_encrypt_uri_part
#### `secure_token_encrypt_uri_part`
* **syntax**: `secure_token_encrypt_uri_part expression`
* **default**: `none`
* **context**: `http`, `server`, `location`
Expand All @@ -260,7 +260,7 @@ Example 1:
...
}
```
In this configuration, only the value of secret_param will be encrypted/decrypted.
In this configuration, only the value of `secret_param` will be encrypted/decrypted.

Example 2:
```
Expand All @@ -270,21 +270,21 @@ Example 2:
```
In this configuration, everything following /base/ will be encrypted/decrypted.

#### secure_token_encrypt_uri_hash_size
#### `secure_token_encrypt_uri_hash_size`
* **syntax**: `secure_token_encrypt_uri_hash_size size`
* **default**: `8`
* **context**: `http`, `server`, `location`

The size in bytes of hash used to validate the uri after decryption, the value has to be between 0 and 16.
The size in bytes of hash used to validate the URI after decryption, the value has to be between 0 and 16.

### Time format

Some of the configuration parameters mentioned above, support both absolute timestamps,
and timestamps relative to `now`.
These parameters can be set in the configuration using one of the following formats:
* `epoch` - unix timestamp 0 (01/01/1970)
* `max` - unix timestamp 2147483647 (18/01/2038)
* `@1481230000` - unix timestamp 1481230000 (8/12/2016)
* `epoch` - UNIX timestamp 0 (01/01/1970)
* `max` - UNIX timestamp 2147483647 (18/01/2038)
* `@1481230000` - UNIX timestamp 1481230000 (8/12/2016)
* `10d` / `+10d` - `now` + 10 days
* `-5m` - `now` - 5 minutes

Expand Down Expand Up @@ -319,6 +319,43 @@ These parameters can be set in the configuration using one of the following form
}
```

### HLS packaging with CloudFront tokens
```
http {
...
secure_token_expires_time 100d; // this is just an example, adjust to your needs
secure_token_query_token_expires_time 1h; // this is just an example, adjust to your needs

secure_token_cloudfront $token {
private_key_file /path/to/pem;
key_pair_id KEY_ID;
acl "$scheme://$http_host$secure_token_baseuri_comma*";
}

server {
# serve flavor HLS
location ~ ^/hls/p/\d+/(sp/\d+/)?serveFlavor/ {
vod hls;

vod_bootstrap_segment_durations 2000;
vod_bootstrap_segment_durations 2000;
vod_bootstrap_segment_durations 2000;
vod_bootstrap_segment_durations 4000;

more_set_headers 'Access-Control-Allow-Headers: Origin,Range,Accept-Encoding,Referer,Cache-Control';
more_set_headers 'Access-Control-Expose-Headers: Server,Content-Length,Content-Range,Date';
more_set_headers 'Access-Control-Allow-Methods: GET, HEAD, OPTIONS';
more_set_headers 'Access-Control-Allow-Origin: *';

secure_token_types application/vnd.apple.mpegurl application/dash+xml text/xml;
secure_token $token;
}

}
...
}
```

### HDS packaging with CloudFront tokens
```
secure_token_cloudfront $token {
Expand Down Expand Up @@ -434,7 +471,7 @@ in addition to nginx-secure-token-module

## Nginx variables

The module adds the following nginx variables:
The module adds the following Nginx variables:
* `$secure_token_baseuri` - contains the value of the `$uri` built in variable truncated up to the last slash (/).
For exmaple, if `$uri` is /a/b/c.htm then `$secure_token_baseuri` will be /a/b/.
* `$secure_token_baseuri_comma` - same as `$secure_token_baseuri`, except that if this value contains a comma (,)
Expand Down