Saltar a contenido

hmac: Funciones HMAC para nginx-module-lua y LuaJIT

Instalación

Si no has configurado la suscripción al repositorio RPM, regístrate. Luego puedes proceder con los siguientes pasos.

CentOS/RHEL 7 o 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 de Lua con NGINX, asegúrate de que nginx-module-lua esté instalado.

Este documento describe lua-resty-hmac v0.6 lanzado el 31 de mayo de 2023.

Esta biblioteca requiere una compilación de nginx con OpenSSL, el módulo ngx_lua y LuaJIT 2.0.

Sinopsis

    # 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("falló al crear el objeto hmac_sha1")
        return
    end

    local ok = hmac_sha1:update("he")
    if not ok then
        ngx.say("falló al agregar datos")
        return
    end

    ok = hmac_sha1:update("llo")
    if not ok then
        ngx.say("falló al agregar datos")
        return
    end

    local mac = hmac_sha1:final()  -- mac binario

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

    -- ¡no olvides reiniciar después de final!
    if not hmac_sha1:reset() then
        ngx.say("falló al reiniciar hmac_sha1")
        return
    end

    -- versión corta
    ngx.say("hmac_sha1: ", hmac_sha1:final("world", true))
        -- salida: "hmac_sha1: 4e9538f1efbe565c522acfb72fce6092ea6b15e0"

Métodos

Para cargar esta biblioteca,

  1. necesitas especificar la ruta de esta biblioteca en la directiva lua_package_path de ngx_lua. Por ejemplo, lua_package_path "/path/to/lua-resty-hmac/lib/?.lua;;";.
  2. usas require para cargar la biblioteca en una variable local de Lua:
    local hmac = require "resty.hmac"

new

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

Crea una nueva instancia de hmac. Si falla, devuelve nil.

El argumento key especifica la clave a utilizar al calcular el código de autenticación de mensaje (MAC). key es una cadena de lua que puede contener caracteres imprimibles o datos binarios.

El argumento hash_algorithm especifica qué algoritmo de hash usar (hmac.ALGOS.MD5, hmac.ALGOS.SHA1, hmac.ALGOS.SHA256, hmac.ALGOS.SHA512). El valor predeterminado es hmac.ALGOS.MD5.

update

syntax: hmac_sha256:update(data)

Actualiza el cálculo del MAC para incluir nuevos datos. Si falla, devuelve false.

El argumento data especifica los datos adicionales a incluir en el MAC. data es una cadena de lua que puede contener caracteres imprimibles o datos binarios.

final

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

Finaliza el cálculo del MAC y devuelve el valor final del MAC. Si falla, devuelve nil. Cuando output_hex no es true, devuelve una cadena de lua que contiene el MAC binario en crudo. Cuando output_hex es true, devuelve una cadena de lua que contiene la representación hexadecimal del MAC.

El argumento data especifica los datos adicionales a incluir en el MAC antes de finalizar el cálculo. El valor predeterminado es nil.

El argumento output_hex especifica si el MAC debe ser devuelto como hexadecimal o binario. Si true, el MAC será devuelto como hexadecimal. El valor predeterminado es false.

reset

syntax: hmac_sha256:reset()

Reinicia el contexto interno de hmac para que pueda ser reutilizado para calcular un nuevo MAC. Si falla, devuelve false. Si tiene éxito, la key y el hash_algorithm permanecen iguales, pero toda la otra información se borra.

Esto DEBE ser llamado después de hmac_sha256:final() para calcular un nuevo MAC utilizando la misma instancia de hmac.

Requisitos previos

Véase También

GitHub

Puedes encontrar consejos de configuración adicionales y documentación para este módulo en el repositorio de GitHub para nginx-module-hmac.