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

Установка

Вы можете установить этот модуль в любой дистрибутив на базе RHEL, включая, но не ограничиваясь:

RedHat Enterprise Linux 7, 8, 9 и 10
CentOS 7, 8, 9
AlmaLinux 8, 9
Rocky Linux 8, 9
Amazon Linux 2 и Amazon Linux 2023

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 и Amazon Linux 2

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-secure-token

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-secure-token

Включите модуль, добавив следующее в начало файла /etc/nginx/nginx.conf:

load_module modules/ngx_http_secure_token_filter_module.so;

Этот документ описывает nginx-module-secure-token v1.5, выпущенный 27 июня 2022 года.

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

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

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

secure_token

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

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

secure_token_avoid_cookies

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

Когда включено, модуль предпочитает использовать токен строки запроса вместо токена cookie. Токен строки запроса в настоящее время поддерживается только для следующих типов MIME (другие типы MIME возвращают токен cookie): * 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

Устанавливает время истечения ответов, которые токенизированы с помощью токена cookie (определяет значения заголовков 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

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

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 для ответов, которые токенизированы (строка запроса / cookie). Пустая строка оставляет значение 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__

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

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

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

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 в этом случае.

GitHub

Вы можете найти дополнительные советы по конфигурации и документацию для этого модуля в репозитории GitHub для nginx-module-secure-token.