$ opm get jkeys089/lua-resty-hmac

名称

lua-resty-hmac - 用于 ngx_lua 和 LuaJIT 的 HMAC 函数

状态

该库仍在积极开发中，被认为已准备好用于生产环境。

描述

此库需要一个带有 OpenSSL 的 nginx 构建，ngx_lua 模块 和 LuaJIT 2.0。

概要

        # nginx.conf:
    
        lua_package_path "/path/to/lua-resty-hmac/lib/?.lua;;";
    
        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("failed to create the hmac_sha1 object")
            return
        end
    
        local ok = hmac_sha1:update("he")
        if not ok then
            ngx.say("failed to add data")
            return
        end
    
        ok = hmac_sha1:update("llo")
        if not ok then
            ngx.say("failed to add data")
            return
        end
    
        local mac = hmac_sha1:final()  -- binary mac
    
        local str = require "resty.string"
        ngx.say("hmac_sha1: ", str.to_hex(mac))
            -- output: "hmac_sha1: aee4b890b574ea8fa4f6a66aed96c3e590e5925a"
    
        -- dont forget to reset after final!
        if not hmac_sha1:reset() then
            ngx.say("failed to reset hmac_sha1")
            return
        end
    
        -- short version
        ngx.say("hmac_sha1: ", hmac_sha1:final("world", true))
            -- output: "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 时，返回包含原始二进制 MAC 的 Lua 字符串。当 output_hex 为 true 时，返回包含 MAC 的十六进制表示形式的 Lua 字符串。

data 参数指定在完成计算之前要包含在 MAC 中的附加数据。默认值为 nil。

output_hex 参数指定 MAC 应该以十六进制还是二进制形式返回。如果为 true，则 MAC 将以十六进制形式返回。默认值为 false。

reset

语法：hmac_sha256:reset()

重置内部 hmac 上下文，以便可以重复使用它来计算新的 MAC。如果失败，则返回 false。如果成功，则 key 和 hash_algorithm 保持不变，但所有其他信息都将被清除。

在 hmac_sha256:final() 之后必须调用此函数，才能使用相同的 hmac 实例计算新的 MAC。

先决条件

• LuaJIT 2.0+

• ngx_lua 模块

• lua-resty-string 0.8+

• OpenSSL 1.0.0+

安装

建议直接使用最新的 ngx_openresty 捆绑包。在构建 ngx_openresty 捆绑包时，需要启用 LuaJIT，方法是将其 ./configure 脚本传递 --with-luajit 选项。

此外，您需要配置 lua_package_path 指令，以将 lua-resty-hmac 源代码树的路径添加到 ngx_lua 的 Lua 模块搜索路径中，如下所示

        # nginx.conf
        http {
            lua_package_path "/path/to/lua-resty-hmac/lib/?.lua;;";
            ...
        }

然后在 Lua 中加载库

        local hmac = require "resty.hmac"

版权和许可

此模块根据 BSD 许可证授权。

版权所有 (C) 2012-2021，Thought Foundry Inc。

保留所有权利。

在满足以下条件的情况下，允许以源代码和二进制形式重新分发和使用，无论是否修改。

• 源代码的重新分发必须保留上述版权声明、此条件列表以及以下免责声明。

• 二进制形式的重新分发必须在随分发提供的文档和/或其他材料中复制上述版权声明、此条件列表以及以下免责声明。

本软件由版权持有人和贡献者“按原样”提供，并且不提供任何明示或暗示的担保，包括但不限于适销性和适用于特定用途的暗示担保。在任何情况下，版权持有人或贡献者均不对任何直接的、间接的、附带的、特殊的、惩罚性的或后果性的损害（包括但不限于替代商品或服务的采购；使用、数据或利润损失；或业务中断）负责，无论这些损害是基于任何责任理论引起的，无论是在合同中、严格责任中，还是在侵权行为（包括疏忽或其他）中，即使已被告知此类损害的可能性。

另请参阅

• ngx_lua 模块：http://wiki.nginx.org/HttpLuaModule