Aller au contenu

hmac: Fonctions HMAC pour nginx-module-lua et LuaJIT

Installation

Si vous n'avez pas configuré l'abonnement au dépôt RPM, inscrivez-vous. Ensuite, vous pouvez procéder avec les étapes suivantes.

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

Pour utiliser cette bibliothèque Lua avec NGINX, assurez-vous que le nginx-module-lua est installé.

Ce document décrit lua-resty-hmac v0.6 publiée le 31 mai 2023.

Cette bibliothèque nécessite une version d'nginx avec OpenSSL, le module ngx_lua, et LuaJIT 2.0.

Synopsis

    # 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("échec de la création de l'objet hmac_sha1")
        return
    end

    local ok = hmac_sha1:update("he")
    if not ok then
        ngx.say("échec de l'ajout de données")
        return
    end

    ok = hmac_sha1:update("llo")
    if not ok then
        ngx.say("échec de l'ajout de données")
        return
    end

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

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

    -- n'oubliez pas de réinitialiser après final !
    if not hmac_sha1:reset() then
        ngx.say("échec de la réinitialisation de hmac_sha1")
        return
    end

    -- version courte
    ngx.say("hmac_sha1: ", hmac_sha1:final("world", true))
        -- sortie : "hmac_sha1: 4e9538f1efbe565c522acfb72fce6092ea6b15e0"

Méthodes

Pour charger cette bibliothèque,

  1. vous devez spécifier le chemin de cette bibliothèque dans la directive lua_package_path de ngx_lua. Par exemple, lua_package_path "/path/to/lua-resty-hmac/lib/?.lua;;";.
  2. vous utilisez require pour charger la bibliothèque dans une variable Lua locale :
    local hmac = require "resty.hmac"

new

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

Crée une nouvelle instance hmac. En cas d'échec, retourne nil.

L'argument key spécifie la clé à utiliser lors du calcul du code d'authentification de message (MAC). key est une chaîne Lua qui peut contenir des caractères imprimables ou des données binaires.

L'argument hash_algorithm spécifie quel algorithme de hachage utiliser (hmac.ALGOS.MD5, hmac.ALGOS.SHA1, hmac.ALGOS.SHA256, hmac.ALGOS.SHA512). La valeur par défaut est hmac.ALGOS.MD5.

update

syntax: hmac_sha256:update(data)

Met à jour le calcul du MAC pour inclure de nouvelles données. En cas d'échec, retourne false.

L'argument data spécifie les données supplémentaires à inclure dans le MAC. data est une chaîne Lua qui peut contenir des caractères imprimables ou des données binaires.

final

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

Finalise le calcul du MAC et retourne la valeur finale du MAC. En cas d'échec, retourne nil. Lorsque output_hex n'est pas true, retourne une chaîne Lua contenant le MAC brut et binaire. Lorsque output_hex est true, retourne une chaîne Lua contenant la représentation hexadécimale du MAC.

L'argument data spécifie les données supplémentaires à inclure dans le MAC avant de finaliser le calcul. La valeur par défaut est nil.

L'argument output_hex spécifie si le MAC doit être retourné en hexadécimal ou en binaire. Si true, le MAC sera retourné en hexadécimal. La valeur par défaut est false.

reset

syntax: hmac_sha256:reset()

Réinitialise le contexte interne hmac afin qu'il puisse être réutilisé pour calculer un nouveau MAC. En cas d'échec, retourne false. Si réussi, la key et hash_algorithm restent les mêmes mais toutes les autres informations sont effacées.

Cela DOIT être appelé après hmac_sha256:final() afin de calculer un nouveau MAC en utilisant la même instance hmac.

Prérequis

Voir aussi

GitHub

Vous pouvez trouver des conseils de configuration supplémentaires et de la documentation pour ce module dans le dépôt GitHub pour nginx-module-hmac.