加密与签名

加密与签名

加密操作，包括加密、HMAC、JWT 和密钥派生。适配工作流使用。

加载

local crypto = require("crypto")

随机生成

随机字节

local bytes, err = crypto.random.bytes(32)

参数	类型	描述
length	integer	字节数（1 到 1,048,576）

返回值: string, error

随机字符串

local str, err = crypto.random.string(32)
local str, err = crypto.random.string(32, "0123456789abcdef")

参数	类型	描述
length	integer	字符串长度（1 到 1,048,576）
charset	string?	使用的字符集（默认：字母数字）

返回值: string, error

随机 UUID

local id, err = crypto.random.uuid()

返回值: string, error

HMAC

HMAC-SHA256

local hex, err = crypto.hmac.sha256(key, data)

参数	类型	描述
key	string	HMAC 密钥
data	string	要认证的数据

返回值: string, error

HMAC-SHA512

local hex, err = crypto.hmac.sha512(key, data)

参数	类型	描述
key	string	HMAC 密钥
data	string	要认证的数据

返回值: string, error

加密

AES-GCM {id=“encrypt-aes-gcm”}

local encrypted, err = crypto.encrypt.aes(data, key)
local encrypted, err = crypto.encrypt.aes(data, key, aad)

参数	类型	描述
data	string	要加密的明文
key	string	16、24 或 32 字节（AES-128/192/256）
aad	string?	附加认证数据

返回值: string, error（nonce 前置）

ChaCha20-Poly1305 {id=“encrypt-chacha20”}

local encrypted, err = crypto.encrypt.chacha20(data, key)
local encrypted, err = crypto.encrypt.chacha20(data, key, aad)

参数	类型	描述
data	string	要加密的明文
key	string	必须为 32 字节
aad	string?	附加认证数据

返回值: string, error

解密

AES-GCM {id=“decrypt-aes-gcm”}

local plaintext, err = crypto.decrypt.aes(encrypted, key)
local plaintext, err = crypto.decrypt.aes(encrypted, key, aad)

参数	类型	描述
data	string	来自 encrypt.aes 的加密数据
key	string	加密时使用的相同密钥
aad	string?	必须与加密时使用的 AAD 匹配

返回值: string, error

ChaCha20-Poly1305 {id=“decrypt-chacha20”}

local plaintext, err = crypto.decrypt.chacha20(encrypted, key)
local plaintext, err = crypto.decrypt.chacha20(encrypted, key, aad)

参数	类型	描述
data	string	来自 encrypt.chacha20 的加密数据
key	string	加密时使用的相同密钥
aad	string?	必须与加密时使用的 AAD 匹配

返回值: string, error

JWT

编码

local token, err = crypto.jwt.encode(payload, secret)
local token, err = crypto.jwt.encode(payload, secret, "HS256")
local token, err = crypto.jwt.encode(payload, private_key_pem, "RS256")

参数	类型	描述
payload	table	JWT 声明（_header 用于自定义头）
key	string	密钥（HMAC）或 PEM 私钥（RSA）
alg	string?	HS256、HS384、HS512、RS256（默认：HS256）

返回值: string, error

验证

local claims, err = crypto.jwt.verify(token, secret)
local claims, err = crypto.jwt.verify(token, secret, "HS256", false)
local claims, err = crypto.jwt.verify(token, public_key_pem, "RS256")

参数	类型	描述
token	string	要验证的 JWT 令牌
key	string	密钥（HMAC）或 PEM 公钥（RSA）
alg	string?	预期算法（默认：HS256）
require_exp	boolean?	验证过期时间（默认：true）

返回值: table, error

密钥派生

PBKDF2

local key, err = crypto.pbkdf2(password, salt, iterations, key_length)
local key, err = crypto.pbkdf2(password, salt, iterations, key_length, "sha512")

参数	类型	描述
password	string	密码/口令
salt	string	盐值
iterations	integer	迭代次数（最大 10,000,000）
key_length	integer	所需密钥长度（字节）
hash	string?	sha256 或 sha512（默认：sha256）

返回值: string, error

工具函数

常量时间比较

local equal = crypto.constant_time_compare(a, b)

参数	类型	描述
a	string	第一个字符串
b	string	第二个字符串

返回值: boolean

错误

条件	类型	可重试
无效的长度	errors.INVALID	否
空密钥	errors.INVALID	否
无效的密钥大小	errors.INVALID	否
解密失败	errors.INTERNAL	否
令牌已过期	errors.INTERNAL	否

参见 错误处理 了解如何处理错误。