Pular para conteúdo

hmac: Funções HMAC para nginx-module-lua e LuaJIT

Instalação

Se você ainda não configurou a assinatura do repositório RPM, inscreva-se. Depois, você pode prosseguir com os seguintes passos.

CentOS/RHEL 7 ou 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

Para usar esta biblioteca Lua com NGINX, certifique-se de que o nginx-module-lua esteja instalado.

Este documento descreve lua-resty-hmac v0.6 lançado em 31 de maio de 2023.

Esta biblioteca requer uma build do nginx com OpenSSL, o módulo ngx_lua e LuaJIT 2.0.

Sinopse

    # 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("falha ao criar o objeto hmac_sha1")
        return
    end

    local ok = hmac_sha1:update("he")
    if not ok then
        ngx.say("falha ao adicionar dados")
        return
    end

    ok = hmac_sha1:update("llo")
    if not ok then
        ngx.say("falha ao adicionar dados")
        return
    end

    local mac = hmac_sha1:final()  -- mac binário

    local str = require "resty.string"
    ngx.say("hmac_sha1: ", str.to_hex(mac))
        -- saída: "hmac_sha1: aee4b890b574ea8fa4f6a66aed96c3e590e5925a"

    -- não se esqueça de redefinir após final!
    if not hmac_sha1:reset() then
        ngx.say("falha ao redefinir hmac_sha1")
        return
    end

    -- versão curta
    ngx.say("hmac_sha1: ", hmac_sha1:final("world", true))
        -- saída: "hmac_sha1: 4e9538f1efbe565c522acfb72fce6092ea6b15e0"

Métodos

Para carregar esta biblioteca,

  1. você precisa especificar o caminho desta biblioteca na diretiva lua_package_path do ngx_lua. Por exemplo, lua_package_path "/path/to/lua-resty-hmac/lib/?.lua;;";.
  2. você usa require para carregar a biblioteca em uma variável Lua local:
    local hmac = require "resty.hmac"

new

syntax: local hmac_sha256 = hmac:new(key [, hash_algorithm])

Cria uma nova instância de hmac. Se falhar, retorna nil.

O argumento key especifica a chave a ser usada ao calcular o código de autenticação de mensagem (MAC). key é uma string Lua que pode conter caracteres imprimíveis ou dados binários.

O argumento hash_algorithm especifica qual algoritmo de hash usar (hmac.ALGOS.MD5, hmac.ALGOS.SHA1, hmac.ALGOS.SHA256, hmac.ALGOS.SHA512). O valor padrão é hmac.ALGOS.MD5.

update

syntax: hmac_sha256:update(data)

Atualiza o cálculo do MAC para incluir novos dados. Se falhar, retorna false.

O argumento data especifica os dados adicionais a serem incluídos no MAC. data é uma string Lua que pode conter caracteres imprimíveis ou dados binários.

final

syntax: local mac = hmac_sha256:final([data, output_hex])

Finaliza o cálculo do MAC e retorna o valor final do MAC. Se falhar, retorna nil. Quando output_hex não é true, retorna uma string Lua contendo o MAC bruto e binário. Quando output_hex é true, retorna uma string Lua contendo a representação hexadecimal do MAC.

O argumento data especifica os dados adicionais a serem incluídos no MAC antes de finalizar o cálculo. O valor padrão é nil.

O argumento output_hex especifica se o MAC deve ser retornado como hexadecimal ou binário. Se true, o MAC será retornado como hexadecimal. O valor padrão é false.

reset

syntax: hmac_sha256:reset()

Redefine o contexto interno do hmac para que possa ser reutilizado para calcular um novo MAC. Se falhar, retorna false. Se for bem-sucedido, a key e o hash_algorithm permanecem os mesmos, mas todas as outras informações são limpas.

Isso DEVE ser chamado após hmac_sha256:final() para calcular um novo MAC usando a mesma instância de hmac.

Pré-requisitos

Veja Também

GitHub

Você pode encontrar dicas adicionais de configuração e documentação para este módulo no repositório GitHub do nginx-module-hmac.