Перейти к содержанию

hmac: HMAC функции для nginx-module-lua и LuaJIT

Установка

Если вы еще не подписались на RPM репозиторий, зарегистрируйтесь. После этого вы можете продолжить с следующими шагами.

CentOS/RHEL 7 или Amazon Linux 2

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 lua-resty-hmac

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install lua5.1-resty-hmac

Чтобы использовать эту библиотеку Lua с NGINX, убедитесь, что nginx-module-lua установлен.

Этот документ описывает lua-resty-hmac v0.6, выпущенный 31 мая 2023 года.

Эта библиотека требует сборку nginx с OpenSSL, модуль ngx_lua и LuaJIT 2.0.

Синопсис

    # nginx.conf:

    server {
        location = /test {
            content_by_lua_file conf/test.lua;
        }
    }

    -- conf/test.lua:

    local hmac = require "resty.hmac"

    local hmac_sha1 = hmac:new("secret_key", hmac.ALGOS.SHA1)
    if not hmac_sha1 then
        ngx.say("не удалось создать объект hmac_sha1")
        return
    end

    local ok = hmac_sha1:update("he")
    if not ok then
        ngx.say("не удалось добавить данные")
        return
    end

    ok = hmac_sha1:update("llo")
    if not ok then
        ngx.say("не удалось добавить данные")
        return
    end

    local mac = hmac_sha1:final()  -- бинарный mac

    local str = require "resty.string"
    ngx.say("hmac_sha1: ", str.to_hex(mac))
        -- вывод: "hmac_sha1: aee4b890b574ea8fa4f6a66aed96c3e590e5925a"

    -- не забудьте сбросить после final!
    if not hmac_sha1:reset() then
        ngx.say("не удалось сбросить hmac_sha1")
        return
    end

    -- короткая версия
    ngx.say("hmac_sha1: ", hmac_sha1:final("world", true))
        -- вывод: "hmac_sha1: 4e9538f1efbe565c522acfb72fce6092ea6b15e0"

Методы

Чтобы загрузить эту библиотеку,

  1. вам нужно указать путь к этой библиотеке в директиве ngx_lua lua_package_path. Например, lua_package_path "/path/to/lua-resty-hmac/lib/?.lua;;";.
  2. используйте require, чтобы загрузить библиотеку в локальную переменную Lua:
    local hmac = require "resty.hmac"

new

синтаксис: local hmac_sha256 = hmac:new(key [, hash_algorithm])

Создает новый экземпляр hmac. Если не удалось, возвращает nil.

Аргумент key указывает ключ, который будет использоваться при вычислении кода аутентификации сообщения (MAC). key — это строка lua, которая может содержать печатные символы или двоичные данные.

Аргумент hash_algorithm указывает, какой алгоритм хеширования использовать (hmac.ALGOS.MD5, hmac.ALGOS.SHA1, hmac.ALGOS.SHA256, hmac.ALGOS.SHA512). Значение по умолчанию — hmac.ALGOS.MD5.

update

синтаксис: hmac_sha256:update(data)

Обновляет вычисление MAC, чтобы включить новые данные. Если не удалось, возвращает false.

Аргумент data указывает дополнительные данные, которые нужно включить в MAC. data — это строка lua, которая может содержать печатные символы или двоичные данные.

final

синтаксис: local mac = hmac_sha256:final([data, output_hex])

Завершает вычисление MAC и возвращает окончательное значение MAC. Если не удалось, возвращает nil. Когда output_hex не равно true, возвращает строку lua, содержащую необработанный, двоичный MAC. Когда output_hex равно true, возвращает строку lua, содержащую шестнадцатеричное представление MAC.

Аргумент data указывает дополнительные данные, которые нужно включить в MAC перед завершением вычисления. Значение по умолчанию — nil.

Аргумент output_hex указывает, следует ли возвращать MAC в шестнадцатеричном или двоичном формате. Если true, MAC будет возвращен в шестнадцатеричном формате. Значение по умолчанию — false.

reset

синтаксис: hmac_sha256:reset()

Сбрасывает внутренний контекст hmac, чтобы его можно было повторно использовать для вычисления нового MAC. Если не удалось, возвращает false. Если успешно, key и hash_algorithm остаются прежними, но вся другая информация очищается.

Это ДОЛЖНО быть вызвано после hmac_sha256:final(), чтобы вычислить новый MAC, используя тот же экземпляр hmac.

Предварительные требования

См. также

GitHub

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