secure-token: Модуль безопасных токенов для NGINX

Установка Debian/Ubuntu

Данная документация относится к APT пакету nginx-module-secure-token, предоставленному репозиторием GetPageSpeed Extras.

Настройте репозиторий APT, как описано в настройке репозитория APT.
Установите модуль:

sudo apt-get update
sudo apt-get install nginx-module-secure-token

Показать дистрибутивы и архитектуры

| Дистрибутив | Версия             | Компонент   | Архитектуры   |
|-------------|--------------------|-------------|-----------------|
| debian      | bookworm           | main        | amd64, arm64    |
| debian      | bookworm-mainline  | main        | amd64, arm64    |
| debian      | trixie             | main        | amd64, arm64    |
| debian      | trixie-mainline    | main        | amd64, arm64    |
| ubuntu      | focal              | main        | amd64, arm64    |
| ubuntu      | focal-mainline     | main        | amd64, arm64    |
| ubuntu      | jammy              | main        | amd64, arm64    |
| ubuntu      | jammy-mainline     | main        | amd64, arm64    |
| ubuntu      | noble              | main        | amd64, arm64    |
| ubuntu      | noble-mainline     | main        | amd64, arm64    |

Генерирует CDN токены, либо в виде куки, либо в виде параметра строки запроса (только m3u8, mpd, f4m). В настоящее время поддерживает токены Akamai v2 и токены Amazon CloudFront. Кроме того, модуль поддерживает шифрование URI с использованием настроенного ключа.

Конфигурация

Общие параметры токенов

secure_token

синтаксис: secure_token value
по умолчанию: none
контекст: http, server, location

Устанавливает значение токена, который должен быть встроен в манифест/возвращен в виде куки. Значение параметра может содержать переменные и часто ссылается на переменные, установленные этим модулем (с помощью блоков secure_token_akamai / secure_token_cloudfront)

secure_token_avoid_cookies

синтаксис: secure_token_avoid_cookies on/off
по умолчанию: on
контекст: http, server, location

При включении модуль предпочитает использовать токен строки запроса вместо куки токена. Токен строки запроса в настоящее время поддерживается только для следующих mime-типов (другие mime-типы возвращают токен куки): * application/vnd.apple.mpegurl * application/dash+xml * video/f4m

secure_token_types

синтаксис: secure_token_types mime_type ...
по умолчанию: none
контекст: http, server, location

Определяет набор mime-типов, которые должны возвращать токен

secure_token_uri_filename_prefix

синтаксис: secure_token_uri_filename_prefix prefix
по умолчанию: none
контекст: http, server, location

Определяет набор префиксов, которые будут сопоставляться с именем файла URI, только URI, имя файла которых начинается с одного из определенных префиксов, будут возвращать токен

secure_token_expires_time

синтаксис: secure_token_expires_time time
по умолчанию: none
контекст: http, server, location

Устанавливает время истечения сроков для ответов, которые не токенизированы (определяет значения заголовков HTTP Cache-Control и Expires)

secure_token_cookie_token_expires_time

синтаксис: secure_token_cookie_token_expires_time time
по умолчанию: none
контекст: http, server, location

Устанавливает время истечения сроков для ответов, которые токенизированы куки токеном (определяет значения заголовков HTTP Cache-Control и Expires)

secure_token_query_token_expires_time

синтаксис: secure_token_query_token_expires_time time
по умолчанию: none
контекст: http, server, location

Устанавливает время истечения сроков для ответов, которые токенизированы токеном строки запроса (определяет значения заголовков HTTP Cache-Control и Expires)

secure_token_cache_scope

синтаксис: secure_token_cache_scope scope
по умолчанию: public
контекст: http, server, location

Устанавливает область кэша (публичная/приватная) для ответов, которые не токенизированы

secure_token_token_cache_scope

синтаксис: secure_token_token_cache_scope scope
по умолчанию: private
контекст: http, server, location

Устанавливает область кэша (публичная/приватная) для ответов, которые токенизированы (строка запроса / куки)

secure_token_last_modified

синтаксис: secure_token_last_modified time
по умолчанию: Sun, 19 Nov 2000 08:52:00 GMT
контекст: http, server, location

Устанавливает значение заголовка last-modified для ответов, которые не токенизированы. Пустая строка оставляет значение last-modified без изменений, в то время как строка "now" устанавливает заголовок на текущее время сервера.

secure_token_token_last_modified

синтаксис: secure_token_token_last_modified time
по умолчанию: now
контекст: http, server, location

Устанавливает значение заголовка last-modified для ответов, которые токенизированы (строка запроса / куки) Пустая строка оставляет значение last-modified без изменений, в то время как строка "now" устанавливает заголовок на текущее время сервера.

secure_token_content_type_m3u8

синтаксис: secure_token_content_type_m3u8 type
по умолчанию: application/vnd.apple.mpegurl
контекст: http, server, location

Устанавливает тип содержимого, который должен анализироваться как m3u8 для вставки токена

secure_token_content_type_mpd

синтаксис: secure_token_content_type_mpd type
по умолчанию: application/dash+xml
контекст: http, server, location

Устанавливает тип содержимого, который должен анализироваться как mpd для вставки токена

secure_token_content_type_f4m

синтаксис: secure_token_content_type_f4m type
по умолчанию: video/f4m
контекст: http, server, location

Устанавливает тип содержимого, который должен анализироваться как f4m для вставки токена

Параметры токена Akamai

secure_token_akamai

синтаксис: secure_token_akamai $variable { ... }
контекст: http

Создает новую переменную, значение которой является токеном Akamai, созданным согласно параметрам, указанным в блоке.

Блок поддерживает следующие параметры:

key

синтаксис: key key_hex
по умолчанию: N/A (обязательный)

Устанавливает секретный ключ.

param_name

синтаксис: param_name name
по умолчанию: __hdnea__

Устанавливает имя параметра токена (либо имя куки, либо имя параметра строки запроса)

acl

синтаксис: acl acl
по умолчанию: $secure_token_baseuri_comma

Устанавливает подписанную часть URL (ACL). Значение параметра может содержать переменные.

start

синтаксис: start time
по умолчанию: 0

Устанавливает время начала токена (см. Формат времени ниже)

end

синтаксис: end time
по умолчанию: 86400

Устанавливает время окончания токена (см. Формат времени ниже)

ip_address

синтаксис: ip_address address
по умолчанию: none

Устанавливает IP-адрес, который должен быть встроен в токен. Значение параметра может содержать переменные, например $remote_addr.

Параметры токена CloudFront

secure_token_cloudfront

синтаксис: secure_token_cloudfront $variable { ... }
контекст: http

Создает новую переменную, значение которой является токеном CloudFront, созданным согласно параметрам, указанным в блоке.

Блок поддерживает следующие параметры:

private_key_file

синтаксис: private_key_file filename
по умолчанию: N/A (обязательный)

Устанавливает имя файла приватного ключа (файл PEM)

key_pair_id

синтаксис: key_pair_id id
по умолчанию: N/A (обязательный)

Устанавливает идентификатор ключевой пары

acl

синтаксис: acl acl
по умолчанию: $secure_token_baseuri_comma

Устанавливает подписанную часть URL (ACL). Значение параметра может содержать переменные.

end

синтаксис: end time
по умолчанию: 86400

Устанавливает время окончания токена (см. Формат времени ниже)

ip_address

синтаксис: ip_address address
по умолчанию: none

Устанавливает IP-адрес, который должен быть встроен в токен. Значение параметра может содержать переменные, например $remote_addr/32 может быть использован для ограничения токена для конкретного IP-адреса клиента.

Параметры токена Broadpeak

secure_token_broadpeak

синтаксис: secure_token_broadpeak $variable { ... }
контекст: http

Создает новую переменную, значение которой является токеном Broadpeak, созданным согласно параметрам, указанным в блоке.

Блок поддерживает следующие параметры:

key

синтаксис: key key
по умолчанию: N/A (обязательный)

Устанавливает секретный ключ. Значение параметра может содержать переменные.

param_name

синтаксис: param_name name
по умолчанию: token

Устанавливает имя параметра токена (либо имя куки, либо имя параметра строки запроса)

acl

синтаксис: acl acl
по умолчанию: $secure_token_baseuri_comma

Устанавливает подписанную часть URL (ACL). Значение параметра может содержать переменные.

start

синтаксис: start time
по умолчанию: 0

Устанавливает время начала токена (см. Формат времени ниже)

end

синтаксис: end time
по умолчанию: 86400

Устанавливает время окончания токена (см. Формат времени ниже)

session_start

синтаксис: session_start time
по умолчанию: N/A

Устанавливает время начала сессии, требуемое для catchup. Значение параметра может содержать переменные.

session_end

синтаксис: session_end time
по умолчанию: N/A

Устанавливает время окончания сессии, требуемое для catchup. Значение параметра может содержать переменные.

additional_querylist

синтаксис: additional_querylist expr
по умолчанию: N/A

Устанавливает основное значение токена, значение должно быть списком пар имя=значение без каких-либо разделителей. Например, "ip=${arg_ip}account=${arg_account}device=${arg_device}". Значение параметра может содержать переменные.

Параметры шифрования URI

secure_token_encrypt_uri

синтаксис: secure_token_encrypt_uri on/off
по умолчанию: off
контекст: http, server, location

Включает/выключает шифрование uri

secure_token_encrypt_uri_key

синтаксис: secure_token_encrypt_uri_key key_hex
по умолчанию: none
контекст: http, server, location

Устанавливает ключ шифрования, ключ должен быть длиной 256 бит (64 шестнадцатиричных символа)

secure_token_encrypt_uri_iv

синтаксис: secure_token_encrypt_uri_iv iv_hex
по умолчанию: none
контекст: http, server, location

Устанавливает вектор инициализации шифрования, вектор инициализации должен быть длиной 128 бит (32 шестнадцатиричных символа)

secure_token_encrypt_uri_part

синтаксис: secure_token_encrypt_uri_part expression
по умолчанию: none
контекст: http, server, location

Выражение, которое вычисляет часть URL, которая должна быть зашифрована в регулярных выражениях. Для нерегулярных местоположений, зашифрованной частью является всё, что следует за путем, определенным в блоке location.

Пример 1:

  location /secret_param/([^/]+)/some_other_param/.* {
    secure_token_encrypt_uri_part $1;
    ...
  }

В этой конфигурации будет зашифровано/расшифровано только значение secret_param.

Пример 2:

  location /base/ {
    ...
  }

В этой конфигурации всё, что следует за /base/, будет зашифровано/расшифровано.

secure_token_encrypt_uri_hash_size

синтаксис: secure_token_encrypt_uri_hash_size size
по умолчанию: 8
контекст: http, server, location

Размер в байтах хеша, используемого для проверки URI после расшифровки, значение должно быть от 0 до 16.

Формат времени

Некоторые из указанных выше параметров конфигурации поддерживают как абсолютные временные отметки, так и временные отметки, относительно now. Эти параметры могут быть установлены в конфигурации с использованием одного из следующих форматов: * epoch - unix временная метка 0 (01/01/1970) * max - unix временная метка 2147483647 (18/01/2038) * @1481230000 - unix временная метка 1481230000 (8/12/2016) * 10d / +10d - now + 10 дней * -5m - now - 5 минут

Примеры конфигураций

Упаковка HLS с токенами Akamai

    secure_token_akamai $token {
        key 1234;
        acl "$secure_token_baseuri_comma*";
    }

    server {

        location ~ ^/hls/p/\d+/(sp/\d+/)?serveFlavor/ {
            vod hls;

            g2o        on;

            secure_token $token;
            secure_token_types application/vnd.apple.mpegurl;

            secure_token_expires_time 100d;
            secure_token_query_token_expires_time 1h;

            more_set_headers 'Access-Control-Allow-Headers: *';
            more_set_headers 'Access-Control-Expose-Headers: Server,range,Content-Length,Content-Range';
            more_set_headers 'Access-Control-Allow-Methods: GET, HEAD, OPTIONS';
            more_set_headers 'Access-Control-Allow-Origin: *';
        }

    }

Упаковка HDS с токенами CloudFront

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

    server {

        location ~ ^/hds/p/\d+/(sp/\d+/)?serveFlavor/ {
            vod hds;
            vod_segment_duration 6000;
            vod_align_segments_to_key_frames on;
            vod_segment_count_policy last_rounded;

            secure_token $token;
            secure_token_types video/f4m;

            secure_token_expires_time 100d;
            secure_token_query_token_expires_time 1h;

            more_set_headers 'Access-Control-Allow-Headers: *';
            more_set_headers 'Access-Control-Expose-Headers: Server,range,Content-Length,Content-Range';
            more_set_headers 'Access-Control-Allow-Methods: GET, HEAD, OPTIONS';
            more_set_headers 'Access-Control-Allow-Origin: *';
        }

    }

Зашифрованный HLS с безопасностью токена на ключе шифрования

Эта конфигурация включает безопасность токена, при этом имея статические URL для видео сегментов, это позволяет кэшировать сегменты прозрачно прокси-серверами.

    secure_token_akamai $token {
        key 1234;
        acl "$secure_token_baseuri_comma*";
    }

    server {

        location ~ ^/s/hls/enc/p/\d+/(sp/\d+/)?serveFlavor/ {
            vod hls;
            vod_secret_key "password$vod_filepath";

            secure_token $token;
            secure_token_types application/vnd.apple.mpegurl;

            secure_token_expires_time 100d;
            secure_token_query_token_expires_time 1h;

            secure_token_uri_filename_prefix index;
            secure_token_tokenize_segments off;

            akamai_token_validate $arg___hdnea__;
            akamai_token_validate_key 1234;
            akamai_token_validate_uri_filename_prefix encryption;
            akamai_token_validate_uri_filename_prefix index;
        }

    }

Примечание: эта конфигурация требует модуль https://github.com/kaltura/nginx-akamai-token-validate-module в дополнение к nginx-secure-token-module

Добавление безопасности токена к существующему HDS/HLS живому потоку

    secure_token_akamai $token {
        key 1234;
        acl "$secure_token_baseuri_comma*";
    }

    server {

        location /secure-live/ {
            proxy_pass http://original.live.domain;

            secure_token $token;
            secure_token_types text/xml application/vnd.apple.mpegurl;      
            secure_token_content_type_f4m text/xml;

            secure_token_expires_time 100d;
            secure_token_query_token_expires_time 1h;

            akamai_token_validate $arg___hdnea__;
            akamai_token_validate_key 1234;
            akamai_token_validate_strip_token __hdnea__;
        }

    }

Примечание: эта конфигурация требует модуль https://github.com/kaltura/nginx-akamai-token-validate-module в дополнение к nginx-secure-token-module

Шифрование URI

    location ~ ^/hls/p/\d+/(sp/\d+/)?serveFlavor/entryId/([^/]+)/(.*) {
        vod hls;
        vod_secret_key "password$2";

        secure_token_encrypt_uri on;
        secure_token_encrypt_uri_key 000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f;
        secure_token_encrypt_uri_iv 00000000000000000000000000000000;
        secure_token_encrypt_uri_part $3;
        secure_token_types application/vnd.apple.mpegurl;

        add_header Last-Modified "Sun, 19 Nov 2000 08:52:00 GMT";
        expires 100d;
    }

Переменные Nginx

Модуль добавляет следующие переменные nginx: * $secure_token_baseuri - содержит значение встроенной переменной $uri, усеченной до последнего слэша (/). Например, если $uri равен /a/b/c.htm, то $secure_token_baseuri будет /a/b/. * $secure_token_baseuri_comma - такое же, как и $secure_token_baseuri, за исключением того, что если это значение содержит запятую (,) то значение усечено до положения запятой. Например, если $uri равен /a/b/c.htm, то $secure_token_baseuri_comma будет /a/b/; если $uri равен /a/b,c/d.htm, то $secure_token_baseuri_comma будет /a/b. * $secure_token_original_uri - содержит оригинальный (зашифрованный) uri при использовании шифрования uri. Обратите внимание, что встроенная переменная $uri содержит измененный (расшифрованный) uri в этом случае.