21 gmssl-国密算法
作者：沈园园 | 最后修改：2026-06-16
一、概述
GMSSL 是一个支持国家密码算法（国密算法） 的开源密码工具库，由中国科学院软件研究所等机构开发，兼容国际密码标准的同时，重点实现了我国自主设计的密码算法（SM 系列），广泛用于国内金融、政务、通信等需符合国家密码标准的领域。
1.1 GMSSL 核心功能
GMSSL 提供了与 OpenSSL 类似的功能，但特别强化了国密算法支持，主要包括：
- 国密算法实现（SM2/SM3/SM4 等）
- 证书管理（支持国密标准证书格式）
- 加密 / 解密、签名 / 验签、密钥交换等密码操作
1.2 核心国密算法（SM2/SM3/SM4）详解
1、SM2：椭圆曲线公钥密码算法
- 类型：非对称加密算法（公钥密码算法）
- 作用：替代 RSA、ECC 等国际算法，用于数字签名、密钥交换、公钥加密。
- 特点：
- 基于椭圆曲线密码（ECC），密钥长度 256 位（安全强度相当于 RSA 2048 位）。
- 签名和加密效率优于 RSA，相同安全级别下密钥更短，适合资源受限场景（如嵌入式设备）。
- 采用国家规定的椭圆曲线参数（SM2p256v1），确保算法合规性。
- 应用场景：电子签名（如合同签署）、身份认证、密钥协商（如 VPN 密钥交换）。
2、SM3：密码杂凑算法
- 类型：哈希算法（杂凑函数）
- 作用：替代 SHA-256 等，用于数据完整性校验、数字签名摘要生成。
- 特点：
- 输出固定长度 256 位（32 字节）哈希值。
- 具备强抗碰撞性（难以找到两个不同数据生成相同哈希值）。
- 计算效率与 SHA-256 相当，安全性满足国家密码标准。
- 应用场景：数字签名的摘要计算（与 SM2 配合使用）、数据校验（如文件完整性验证）、区块链交易哈希（部分国产区块链采用）。
3、SM4：分组密码算法
- 类型：对称加密算法
- 作用：替代 AES 等，用于敏感数据加密 / 解密。
- 特点：
- 分组长度 128 位，密钥长度 128 位，加密模式支持 ECB、CBC、GCM 等。
- 加密效率与 AES 相当，适合批量数据加密。
- 算法设计公开，安全性经过严格验证。
- 应用场景：数据库加密、文件加密、VPN 数据传输加密、政务系统敏感信息保护。
二、核心示例
1、核心示例是指：使用本库文件提供的核心API，开发的基础业务逻辑的演示代码；
2、核心示例的作用是：帮助开发者快速理解如何使用本库，所以核心示例的逻辑都比较简单；
3、更加完整和详细的demo，请参考 LuatOS仓库 中各个产品目录下的demo/gmssl
-- SM2签名和验签
if gmssl.sm2sign then
local originStr = string.fromHex("434477813974bf58f94bcf760833c2b40f77a5fc360485b0b9ed1bd9682edb45")
local pkx = "ABE87C924B7ECFDEA1748A06E89003C9F7F4DC5C3563873CE2CAE46F66DE8141"
local pky = "9514733D38CC026F2452A6A3A3A4DA0C28F864AFA5FE2C45E0EB6B761FBB5286"
local private = "129EDC282CD2E9C1144C2E7315F926D772BC96600D2771E8BE02060313FE00D5"
-- 不带id的情况,即默认id="1234567812345678"
local sig = gmssl.sm2sign(private, originStr, nil)
log.info("sm2sign", sig and sig:toHex())
if sig then
local ret = gmssl.sm2verify(pkx, pky, originStr, nil, sig)
log.info("sm2verify", ret or "false")
end
-- 带id的情况
local id = "1234"
local sig = gmssl.sm2sign(private, originStr, id)
log.info("sm2sign", sig and sig:toHex())
if sig then
local ret = gmssl.sm2verify(pkx, pky, originStr, id, sig)
log.info("sm2verify", ret or "false")
end
end
function sm2test(originStr, pkx, pky, private)
-- GMSSL默认格式
log.info("==== SM2 默认GMSSL模式")
local encodeStr = gmssl.sm2encrypt(pkx,pky,originStr)
log.info("sm2默认模式", "加密后", encodeStr and string.toHex(encodeStr))
if encodeStr then
log.info("sm2默认模式", "解密后", gmssl.sm2decrypt(private,encodeStr))
end
-- 网站兼容模式 https://i.goto327.top/CryptTools/SM2.aspx
-- 密文格式 C1C3C2, 新国标, 一般是这种
log.info("==== SM2 网站兼容模式")
local encodeStr = gmssl.sm2encrypt(pkx,pky,originStr, true)
log.info("sm2网站兼容模式 C1C3C2", "加密后", encodeStr and string.toHex(encodeStr))
if encodeStr then
log.info("sm2网站兼容模式 C1C3C2", "解密后", gmssl.sm2decrypt(private,encodeStr, true))
else
log.info("解密失败")
end
-- 密文格式 C1C2C3, 老国标, 老的Java库通常支持这种
log.info("==== SM2 网站兼容模式, 但C1C2C3")
local encodeStr = gmssl.sm2encrypt(pkx,pky,originStr, true, true)
log.info("sm2网站兼容模式 C1C2C3", "加密后", encodeStr and string.toHex(encodeStr))
if encodeStr then
log.info("sm2网站兼容模式 C1C2C3", "解密后", gmssl.sm2decrypt(private,encodeStr, true, true))
else
log.info("解密失败")
end
end
-- 未加密字符串
local originStr = "!!from LuatOS!!"
-- SM2 , 非对称加密, 类似于RSA,但属于椭圆算法
-- 就当前实现还是比较慢的
if gmssl.sm2encrypt then -- 部分BSP不支持
local pkx = "ABE87C924B7ECFDEA1748A06E89003C9F7F4DC5C3563873CE2CAE46F66DE8141"
local pky = "9514733D38CC026F2452A6A3A3A4DA0C28F864AFA5FE2C45E0EB6B761FBB5286"
local private = "129EDC282CD2E9C1144C2E7315F926D772BC96600D2771E8BE02060313FE00D5"
sm2test(originStr, pkx, pky, private)
end
-- SM密钥生成
if gmssl.sm2keygen then
log.info("SM2密钥生成测试")
originStr = "32wrniosadnfvnadsio;fasiow"
local pkx, pky, private = gmssl.sm2keygen()
sm2test(originStr, pkx, pky, private)
end
-- SM3 算法, hash类
if gmssl.sm3 then
log.info("=== SM3测试")
local encodeStr = gmssl.sm3("lqlq666lqlq946")
log.info("gmssl.sm3",string.toHex(encodeStr))
-- sm3算法,算HASH值,但带HMAC
local encodeStr = gmssl.sm3hmac("lqlq666lqlq946", "123")
log.info("gmssl.sm3hmac",string.toHex(encodeStr))
end
if gmssl.sm4encrypt then
log.info("=== SM4测试")
local passwd = "1234567890123456"
local iv = "1234567890666666"
-- SM4 算法, 对称加密
originStr = ">>SM4 ECB ZeroPadding test<<"
--加密模式：ECB；填充方式：ZeroPadding；密钥：1234567890123456；密钥长度：128 bit
encodeStr = gmssl.sm4encrypt("ECB", "ZERO", originStr, passwd)
log.info("sm4.ecb.zero", "加密后", string.toHex(encodeStr))
log.info("sm4.ecb.zero", "解密后", gmssl.sm4decrypt("ECB","ZERO",encodeStr,passwd))
originStr = ">>SM4 ECB Pkcs5Padding test<<"
--加密模式：ECB；填充方式：Pkcs5Padding；密钥：1234567890123456；密钥长度：128 bit
encodeStr = gmssl.sm4encrypt("ECB", "PKCS5", originStr, passwd)
log.info("sm4.ecb.pks5", "加密后", string.toHex(encodeStr))
log.info("sm4.ecb.pks5", "解密后", gmssl.sm4decrypt("ECB","PKCS5",encodeStr,passwd))
originStr = ">>SM4 CBC Pkcs5Padding test<<"
--加密模式：CBC；填充方式：Pkcs5Padding；密钥：1234567890123456；密钥长度：128 bit；偏移量：1234567890666666
encodeStr = gmssl.sm4encrypt("CBC","PKCS5", originStr, passwd, iv)
log.info("sm4.cbc.pks5", "加密后", string.toHex(encodeStr))
log.info("sm4.cbc.pks5", "解密后", gmssl.sm4decrypt("CBC","PKCS5",encodeStr,passwd, iv))
-- 完全对齐16字节的对比测试
originStr = "1234567890123456"
encodeStr = gmssl.sm4encrypt("ECB","PKCS7",originStr,passwd)
log.info("sm4.ecb.pkcs7", encodeStr:toHex())
encodeStr = gmssl.sm4encrypt("ECB","PKCS5",originStr,passwd)
log.info("sm4.ecb.pkcs5", encodeStr:toHex())
encodeStr = gmssl.sm4encrypt("ECB","ZERO",originStr,passwd)
log.info("sm4.ecb.zero", encodeStr:toHex())
encodeStr = gmssl.sm4encrypt("ECB","NONE",originStr,passwd)
log.info("sm4.ecb.none", encodeStr:toHex())
end
三、常量详解
核心库常量，顾名思义是由合宙 LuatOS 内核固件中定义的、不可重新赋值或修改的固定值，在脚本代码中不需要声明，可直接调用；
每个常量对应的常量取值仅做日志打印时查询使用，不要将这个常量取值用做具体的业务逻辑判断，因为LuatOS内核固件可能会变更每个常量对应的常量取值；
如果用做具体的业务逻辑判断，一旦常量取值发生改变，业务逻辑就会出错；
gmssl核心库没有常量。
四、函数详解
4.1 gmssl.sm2encrypt(pkx,pky,data, mode, mode2)
sm2算法加密
参数
pkx
参数含义：公钥x;
数据类型：string；
取值范围：64位HEX字符串；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例："ABE87C924B7ECFDEA1748A06E89003C9F7F4DC5C3563873CE2CAE46F66DE8141"；
pky
参数含义：公钥y;
数据类型：string；
取值范围：64位HEX字符串；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例："9514733D38CC026F2452A6A3A3A4DA0C28F864AFA5FE2C45E0EB6B761FBB5286"；
data
参数含义：待加密的数据;
数据类型：string；
取值范围：最长32字节, 非HEX字符串；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例："!!from LuatOS!!"；
mode
参数含义：输出模式;
数据类型：boolean；
取值范围：false-GMSSL默认格式DER, true-网站兼容模式；
是否必选：可选，默认false；
注意事项：暂无；
参数示例：false；
mode2
参数含义：标准版本;
数据类型：boolean；
取值范围：false-C1C3C2新国际, true-C1C2C3老国际. 仅"网站兼容模式"时有效；
是否必选：可选，默认false；
注意事项：暂无；
参数示例：false；
返回值 local encodeStr = gmssl.sm2encrypt(pkx,pky,data, mode, mode2)
encodeStr
含义说明：加密后的字符串, 原样输出,未经HEX转换. 若加密失败会返回nil或空字符串
数据类型：string；
取值范围：无特别限制；
注意事项：暂无；
返回示例：包含不可预见字符，可以通过string.toHex(encodeStr)打印，参考示例log打印值；
示例
function sm2test(originStr, pkx, pky, private)
-- GMSSL默认格式
log.info("==== SM2 默认GMSSL模式")
local encodeStr = gmssl.sm2encrypt(pkx,pky,originStr)
log.info("sm2默认模式", "加密后", encodeStr and string.toHex(encodeStr)) --307802200BD0D4294018F6266198E14A91B211E21BD9DC5EF30F94410F243BF63699CCD1022100C19FC89B11797A98A5F07A65FD0A61D77E3C18388DD55C5EBB9E303B96101BF90420849C7BED6B9904758F4BAE213079143B69E40748F3BA4ADDDFB4AA4E86522169040FC219443BADB86AC4032FD88D732001
-- 网站兼容模式 https://i.goto327.top/CryptTools/SM2.aspx
-- 密文格式 C1C3C2, 新国标, 一般是这种
log.info("==== SM2 网站兼容模式")
local encodeStr = gmssl.sm2encrypt(pkx,pky,originStr, true)
log.info("sm2网站兼容模式 C1C3C2", "加密后", encodeStr and string.toHex(encodeStr)) --54C684C778A183E30E27B104292AE7D228687788E48CEA23134C309AB20DBB6AFA11B8BE87062AC0F98FCCA6909AEB3ACDA772BDD7D79419DD32D416BE846807580BBFDEE2942F98CEC300FF65BC6DBF779D5D0DBA8E66231B7779CA6B8E8D4090BD7937A81DB2828323202FDB6BD6
-- 密文格式 C1C2C3, 老国标, 老的Java库通常支持这种
log.info("==== SM2 网站兼容模式, 但C1C2C3")
local encodeStr = gmssl.sm2encrypt(pkx,pky,originStr, true, true)
log.info("sm2网站兼容模式 C1C2C3", "加密后", encodeStr and string.toHex(encodeStr)) --04CA4F3C97A83EB2F71782818E0DE01FA25DD6619F5652F8AD7043262F47EED9F26E41D93D34135B845CDB4D6D2F8941BEB8994713AD8FB3A5BE9AC3AE514C72C856C552B2F06DF513C55846D2F42A7FA40D02523D0768E9CCC6C4D9220115B7B625F056BBD2486297BFA355B4776C03
end
-- 未加密字符串
local originStr = "!!from LuatOS!!"
-- SM2 , 非对称加密, 类似于RSA,但属于椭圆算法
-- 就当前实现还是比较慢的
if gmssl.sm2encrypt then -- 部分BSP不支持
local pkx = "ABE87C924B7ECFDEA1748A06E89003C9F7F4DC5C3563873CE2CAE46F66DE8141"
local pky = "9514733D38CC026F2452A6A3A3A4DA0C28F864AFA5FE2C45E0EB6B761FBB5286"
sm2test(originStr, pkx, pky, private)
end
4.2 gmssl.sm2decrypt(private,data,mode,mode2)
sm2算法解密
参数
private
参数含义：私钥;
数据类型：string；
取值范围：64位HEX字符串；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例："129EDC282CD2E9C1144C2E7315F926D772BC96600D2771E8BE02060313FE00D5"
data
参数含义：待解密的数据;
数据类型：string；
取值范围：原始数据,非HEX字符串；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例：参考示例log打印值；
mode
参数含义：输出模式;
数据类型：boolean；
取值范围：false-GMSSL默认格式DER, true-网站兼容模式；
是否必选：可选，默认false；
注意事项：暂无；
参数示例：false；
mode2
参数含义：标准版本;
数据类型：boolean；
取值范围：false-C1C3C2新国际, true-C1C2C3老国际. 仅"网站兼容模式"时有效；
是否必选：可选，默认false；
注意事项：暂无；
参数示例：false；
返回值 local decryptStr = gmssl.sm2decrypt(private,data,mode,mode2)
decryptStr
含义说明：解密后的字符串,未经HEX转换.若解密失败会返回nil或空字符串
数据类型：string或者nil；
取值范围：最长32字节, 非HEX字符串；
注意事项：暂无；
返回示例："!!from LuatOS!!"；
示例
function sm2test(originStr, pkx, pky, private)
-- GMSSL默认格式
log.info("==== SM2 默认GMSSL模式")
local encodeStr = gmssl.sm2encrypt(pkx,pky,originStr)
log.info("sm2默认模式", "加密后", encodeStr and string.toHex(encodeStr)) --307802200BD0D4294018F6266198E14A91B211E21BD9DC5EF30F94410F243BF63699CCD1022100C19FC89B11797A98A5F07A65FD0A61D77E3C18388DD55C5EBB9E303B96101BF90420849C7BED6B9904758F4BAE213079143B69E40748F3BA4ADDDFB4AA4E86522169040FC219443BADB86AC4032FD88D732001
if encodeStr then
log.info("sm2默认模式", "解密后", gmssl.sm2decrypt(private,encodeStr)) --!!from LuatOS!!
end
-- 网站兼容模式 https://i.goto327.top/CryptTools/SM2.aspx
-- 密文格式 C1C3C2, 新国标, 一般是这种
log.info("==== SM2 网站兼容模式")
local encodeStr = gmssl.sm2encrypt(pkx,pky,originStr, true)
log.info("sm2网站兼容模式 C1C3C2", "加密后", encodeStr and string.toHex(encodeStr)) --54C684C778A183E30E27B104292AE7D228687788E48CEA23134C309AB20DBB6AFA11B8BE87062AC0F98FCCA6909AEB3ACDA772BDD7D79419DD32D416BE846807580BBFDEE2942F98CEC300FF65BC6DBF779D5D0DBA8E66231B7779CA6B8E8D4090BD7937A81DB2828323202FDB6BD6
if encodeStr then
log.info("sm2网站兼容模式 C1C3C2", "解密后", gmssl.sm2decrypt(private,encodeStr, true)) --!!from LuatOS!!
else
log.info("解密失败")
end
-- 密文格式 C1C2C3, 老国标, 老的Java库通常支持这种
log.info("==== SM2 网站兼容模式, 但C1C2C3")
local encodeStr = gmssl.sm2encrypt(pkx,pky,originStr, true, true)
log.info("sm2网站兼容模式 C1C2C3", "加密后", encodeStr and string.toHex(encodeStr)) --04CA4F3C97A83EB2F71782818E0DE01FA25DD6619F5652F8AD7043262F47EED9F26E41D93D34135B845CDB4D6D2F8941BEB8994713AD8FB3A5BE9AC3AE514C72C856C552B2F06DF513C55846D2F42A7FA40D02523D0768E9CCC6C4D9220115B7B625F056BBD2486297BFA355B4776C03
if encodeStr then
log.info("sm2网站兼容模式 C1C2C3", "解密后", gmssl.sm2decrypt(private,encodeStr, true, true)) --!!from LuatOS!!
else
log.info("解密失败")
end
end
-- 未加密字符串
local originStr = "!!from LuatOS!!"
-- SM2 , 非对称加密, 类似于RSA,但属于椭圆算法
-- 就当前实现还是比较慢的
if gmssl.sm2encrypt then -- 部分BSP不支持
local pkx = "ABE87C924B7ECFDEA1748A06E89003C9F7F4DC5C3563873CE2CAE46F66DE8141"
local pky = "9514733D38CC026F2452A6A3A3A4DA0C28F864AFA5FE2C45E0EB6B761FBB5286"
local private = "129EDC282CD2E9C1144C2E7315F926D772BC96600D2771E8BE02060313FE00D5"
sm2test(originStr, pkx, pky, private)
end
4.3 gmssl.sm3(data)
sm3算法,算HASH值
参数
data
参数含义：待计算的数据;
数据类型：string；
取值范围：无特别限制；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例："lqlq666lqlq946"；
返回值 local encodeStr = gmssl.sm3(data)
encodeStr
含义说明：对应的hash值
数据类型：string；
取值范围：32字节, 非HEX字符串；
注意事项：暂无；
返回示例：包含不可预见字符，可以通过string.toHex(encodeStr)打印，参考示例log打印值；
示例
local encodeStr = gmssl.sm3("lqlq666lqlq946")
log.info("gmssl.sm3",string.toHex(encodeStr)) --E64FD76F4078E51DCA428323D3FADBD5D52723BBF1379184650DA5CE6002B2BF 64
4.4 gmssl.sm3hmac(data, key)
sm3算法,算HASH值,但带HMAC
参数
data
参数含义：待计算的数据;
数据类型：string；
取值范围：无特别限制；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例："lqlq666lqlq946"；
key
参数含义：HMAC密钥;
数据类型：string；
取值范围：无特别限制；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例："lqlq666lqlq946"；
返回值 local encodeStr = gmssl.sm3hmac(data, key)
encodeStr
含义说明：对应的hash值
数据类型：string；
取值范围：32字节, 非HEX字符串；
注意事项：暂无；
返回示例：包含不可预见字符，可以通过string.toHex(encodeStr)打印，参考示例log打印值；
示例
local encodeStr = gmssl.sm3hmac("lqlq666lqlq946", "123")
log.info("gmssl.sm3hmac",string.toHex(encodeStr)) --FBB67FC936777011AA70336F0F0B6305D529A97A87D8ECA8880472CD2C30A721 64
4.5 gmssl.sm4encrypt(mode,padding,originStr,password,iv)
SM4加密算法
参数
mode
参数含义：加密模式, "CBC"或"ECB";
数据类型：string；
取值范围："CBC"或"ECB"；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例："CBC"；
padding
参数含义：填充方式, "NONE","ZERO","PKCS5","PKCS7";
数据类型：string；
取值范围："NONE","ZERO","PKCS5","PKCS7"；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例："ZERO"；
originStr
参数含义：待加密的字符串;
数据类型：string；
取值范围：无特别限制；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例："SM4 ECB ZeroPadding test"；
password
参数含义：密钥;
数据类型：string；
取值范围：16字节；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例："1234567890123456"；
iv
参数含义：偏移量;
数据类型：string；
取值范围：16字节；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例："1234567890666666"；
返回值 local encodeStr = gmssl.sm4encrypt(mode,padding,originStr,password,iv)
encodeStr
含义说明：加密后的数据
数据类型：string；
取值范围：32字节；
注意事项：暂无；
返回示例：包含不可预见字符，可以通过string.toHex(encodeStr)打印，参考示例log打印值；
示例
local originStr = "SM4 ECB ZeroPadding test"
--加密模式：ECB；填充方式：ZeroPadding；密钥：1234567890123456；密钥长度：256 bit
local encodeStr = gmssl.sm4encrypt("ECB","ZERO",originStr,"1234567890123456")
print(originStr,"encrypt",string.toHex(encodeStr)) --25E56B0B42541C82DFFF7A49B0FF102A89CB0872D24A716108F044459CC07ADE 64
originStr = "SM4 ECB Pkcs5Padding test"
--加密模式：ECB；填充方式：Pkcs5Padding；密钥：1234567890123456；密钥长度：256 bit
encodeStr = gmssl.sm4encrypt("ECB","PKCS5",originStr,"1234567890123456")
print(originStr,"encrypt",string.toHex(encodeStr)) --DA2CBBB69D50083C2D989E8BFE4F8CC5146F205790485242B7DD8BE70D275CDF 64
originStr = "SM4 CBC Pkcs5Padding test"
--加密模式：CBC；填充方式：Pkcs5Padding；密钥：1234567890123456；密钥长度：256 bit；偏移量：1234567890666666
encodeStr = gmssl.sm4encrypt("CBC","PKCS5",originStr,"1234567890123456","1234567890666666")
print(originStr,"encrypt",string.toHex(encodeStr)) --774AF56064526E586F411550ACD2000F53DC70382E919FA361BA912976FEA9AE 64
4.6 gmssl.sm4decrypt(mode,padding,encodeStr,password,iv)
SM4解密算法
参数
mode
参数含义：加密模式, "CBC"或"ECB";
数据类型：string；
取值范围："CBC"或"ECB"；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例："CBC"；
padding
参数含义：填充方式, "NONE","ZERO","PKCS5","PKCS7";
数据类型：string；
取值范围："NONE","ZERO","PKCS5","PKCS7"；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例："ZERO"；
encodeStr
参数含义：加密的字符串;
数据类型：string；
取值范围：无特别限制；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例：包含不可预见字符，可以通过string.toHex(encodeStr)打印，参考示例log打印值；
password
参数含义：密钥;
数据类型：string；
取值范围：16字节；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例："1234567890123456"；
iv
参数含义：偏移量;
数据类型：string；
取值范围：16字节；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例："1234567890666666"；
返回值 local encodeStr = gmssl.sm4decrypt(mode,padding,encodeStr,password,iv)
encodeStr
含义说明：解密的字符串;
数据类型：string；
取值范围：无特别限制；
注意事项：暂无；
返回示例：包含不可预见字符，可以通过string.toHex(encodeStr)打印，参考示例log打印值；
示例
local originStr = "SM4 ECB ZeroPadding test"
--加密模式：ECB；填充方式：ZeroPadding；密钥：1234567890123456；
local encodeStr = gmssl.sm4encrypt("ECB","ZERO",originStr,"1234567890123456")
print(originStr,"encrypt",string.toHex(encodeStr)) --25E56B0B42541C82DFFF7A49B0FF102A89CB0872D24A716108F044459CC07ADE 64
log.info("gmssl.sm4decrypt",gmssl.sm4decrypt("ECB","ZERO",encodeStr,"1234567890123456")) --SM4 ECB ZeroPadding test
originStr = "SM4 ECB Pkcs5Padding test"
--加密模式：ECB；填充方式：Pkcs5Padding；密钥：1234567890123456；
encodeStr = gmssl.sm4encrypt("ECB","PKCS5",originStr,"1234567890123456")
print(originStr,"encrypt",string.toHex(encodeStr)) --DA2CBBB69D50083C2D989E8BFE4F8CC5146F205790485242B7DD8BE70D275CDF 64
log.info("gmssl.sm4decrypt",gmssl.sm4decrypt("ECB","PKCS5",encodeStr,"1234567890123456")) --SM4 ECB ZeroPadding test
originStr = "SM4 CBC Pkcs5Padding test"
--加密模式：CBC；填充方式：Pkcs5Padding；密钥：1234567890123456；偏移量：1234567890666666
encodeStr = gmssl.sm4encrypt("CBC","PKCS5",originStr,"1234567890123456","1234567890666666")
print(originStr,"encrypt",string.toHex(encodeStr)) --774AF56064526E586F411550ACD2000F53DC70382E919FA361BA912976FEA9AE 64
log.info("gmssl.sm4decrypt",gmssl.sm4decrypt("CBC","PKCS5",encodeStr,"1234567890123456","1234567890666666")) --SM4 ECB ZeroPadding test
4.7 gmssl.sm2sign(private,data,id)
sm2算法签名
参数
private
参数含义：私钥;
数据类型：string；
取值范围：64位HEX字符串；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例："129EDC282CD2E9C1144C2E7315F926D772BC96600D2771E8BE02060313FE00D5"；
data
参数含义：待计算的数据;
数据类型：string；
取值范围：原始数据,非HEX字符串；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例：string.fromHex("434477813974bf58f94bcf760833c2b40f77a5fc360485b0b9ed1bd9682edb45")；
id
参数含义：id值;
数据类型：string；
取值范围：非HEX字符串；
是否必选：可选,默认值"1234567812345678"；
注意事项：暂无；
参数示例："1234567812345678"；
返回值 local sig = gmssl.sm2sign(private,data,id)
sig
含义说明：签名字符串,未经HEX转换.若签名失败会返回nil
数据类型：string或者nil；
取值范围：64字节,非HEX字符串；
注意事项：暂无；
返回示例：包含不可预见字符，可以通过string.toHex(encodeStr)打印，参考示例log打印值；
示例
local originStr = string.fromHex("434477813974bf58f94bcf760833c2b40f77a5fc360485b0b9ed1bd9682edb45")
local private = "129EDC282CD2E9C1144C2E7315F926D772BC96600D2771E8BE02060313FE00D5"
-- 不带id的情况,即默认id="1234567812345678"
local sig = gmssl.sm2sign(private, originStr, nil)
log.info("sm2sign", sig and sig:toHex()) --A4AC17164509CBA01147455FDA13AB7A5E9AFAB0AEF21460C8D4B7F66750D44AC1F350B2A1148E2CBAF0180DBFB9BAFFFC2F998C213C6E28CC02D9F27702E627
-- 带id的情况
local id = "1234"
local sig = gmssl.sm2sign(private, originStr, id)
log.info("sm2sign", sig and sig:toHex()) --159EA7A9C98CC7F46381FE7DDE5D219FAFC20614737348C43D1A1B4BC922DC4552B80575F75A902EFF484E723F770D625EE18071F9179D722ED77EAD08BEC604
4.8 gmssl.sm2verify(pkx, pky, data, id, sig)
sm2算法验签
参数
pkx
参数含义：公钥X;
数据类型：string；
取值范围：64位HEX字符串；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例："ABE87C924B7ECFDEA1748A06E89003C9F7F4DC5C3563873CE2CAE46F66DE8141"；
pky
参数含义：公钥Y;
数据类型：string；
取值范围：64位HEX字符串；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例："9514733D38CC026F2452A6A3A3A4DA0C28F864AFA5FE2C45E0EB6B761FBB5286"；
data
参数含义：待计算的数据和sm2sign接口中的data参数内容保持一致;
数据类型：string；
取值范围：原始数据,非HEX字符串；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例：string.fromHex("434477813974bf58f94bcf760833c2b40f77a5fc360485b0b9ed1bd9682edb45")
id
参数含义：id值;
数据类型：string；
取值范围：非HEX字符串；
是否必选：可选,默认值"1234567812345678"；
注意事项：暂无；
参数示例："1234567812345678"；
sig
参数含义：签名数据;
数据类型：string；
取值范围：必须64字节,非HEX字符串；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例：string.fromHex("A4AC17164509CBA01147455FDA13AB7A5E9AFAB0AEF21460C8D4B7F66750D44AC1F350B2A1148E2CBAF0180DBFB9BAFFFC2F998C213C6E28CC02D9F27702E627")；
返回值 local ret = gmssl.sm2verify(pkx, pky, data, id, sig)
ret
含义说明：验证成功返回true,否则返回nil
数据类型：boolean或者nil；
取值范围：true或者nil；
注意事项：暂无；
返回示例：true；
示例
local originStr = string.fromHex("434477813974bf58f94bcf760833c2b40f77a5fc360485b0b9ed1bd9682edb45")
local pkx = "ABE87C924B7ECFDEA1748A06E89003C9F7F4DC5C3563873CE2CAE46F66DE8141"
local pky = "9514733D38CC026F2452A6A3A3A4DA0C28F864AFA5FE2C45E0EB6B761FBB5286"
local private = "129EDC282CD2E9C1144C2E7315F926D772BC96600D2771E8BE02060313FE00D5"
-- 不带id的情况,即默认id="1234567812345678"
local sig = gmssl.sm2sign(private, originStr, nil)
log.info("sm2sign", sig and sig:toHex()) --A4AC17164509CBA01147455FDA13AB7A5E9AFAB0AEF21460C8D4B7F66750D44AC1F350B2A1148E2CBAF0180DBFB9BAFFFC2F998C213C6E28CC02D9F27702E627
if sig then
local ret = gmssl.sm2verify(pkx, pky, originStr, nil, sig)
log.info("sm2verify", ret or "false") --true
end
-- 带id的情况
local id = "1234"
local sig = gmssl.sm2sign(private, originStr, id)
log.info("sm2sign", sig and sig:toHex()) --159EA7A9C98CC7F46381FE7DDE5D219FAFC20614737348C43D1A1B4BC922DC4552B80575F75A902EFF484E723F770D625EE18071F9179D722ED77EAD08BEC604
if sig then
local ret = gmssl.sm2verify(pkx, pky, originStr, id, sig)
log.info("sm2verify", ret or "false") --true
end
4.9 gmssl.sm2keygen()
SM2密钥生成
参数
无
返回值 local pkx, pky, private = gmssl.sm2keygen()
pkx
参数含义：公钥X;
数据类型：string；
取值范围：64位HEX字符串；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例："ABE87C924B7ECFDEA1748A06E89003C9F7F4DC5C3563873CE2CAE46F66DE8141"；
pky
参数含义：公钥Y;
数据类型：string；
取值范围：64位HEX字符串；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例："9514733D38CC026F2452A6A3A3A4DA0C28F864AFA5FE2C45E0EB6B761FBB5286"；
private
参数含义：私钥;
数据类型：string；
取值范围：64位HEX字符串；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例："129EDC282CD2E9C1144C2E7315F926D772BC96600D2771E8BE02060313FE00D5"
示例
-- 本函数于2025.8.27新增
-- 注意返回值是HEX字符串, 传递给sm2系列函数可以直接使用
-- 如果传递给服务器, 按格式需要, 可能需要 fromHex 操作
-- 提醒, 生成的密钥对请妥善保管
local pkx, pky, private = gmssl.sm2keygen()
log.info("sm2keygen", pkx) --A56FC6E48E08E15A79BABB0FC5F6DED1230AD7FFCCAF3A79956150CA777D3207
log.info("sm2keygen", pky) --E8D957337229CE9C0D263C719ABA65850F7BE6F98768249F3B0F030360207F31
log.info("sm2keygen", private) --752AE7572C3D54EEC67D89F7E12125512BDAFC3E023934EF542C914375066B2A
4.10 gmssl.sm2pointmul(k, px, py)
SM2标量点乘: R = k * P。已知椭圆曲线上一点P和一个整数k, 计算k个P相加的结果。常用于密钥交换协议中计算临时公钥的变换
新增于 2026.06.16
参数
k
参数含义：标量k;
数据类型：string；
取值范围：64位HEX字符串；
是否必选：必须传入此参数；
注意事项：k应在[1, n-1]范围内, n为SM2曲线阶；
参数示例："0000000000000000000000000000000000000000000000000000000000000002"；
px
参数含义：点P的x坐标;
数据类型：string；
取值范围：64位HEX字符串；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例："32C4AE2C1F1981195F9904466A39C9948FE30BBFF2660BE1715A4589334C74C7"；
py
参数含义：点P的y坐标;
数据类型：string；
取值范围：64位HEX字符串；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例："BC3736A2F4F6779C59BDCEE36B692153D0A9877CC62A474002DF32E52139F0A0"；
返回值 local rx, ry = gmssl.sm2pointmul(k, px, py)
rx
含义说明：结果点R的x坐标, 失败返回nil
数据类型：string；
取值范围：64位HEX字符串；
注意事项：暂无；
返回示例："32C4AE2C1F1981195F9904466A39C9948FE30BBFF2660BE1715A4589334C74C7"；
ry
含义说明：结果点R的y坐标, 失败返回nil
数据类型：string；
取值范围：64位HEX字符串；
注意事项：暂无；
返回示例："BC3736A2F4F6779C59BDCEE36B692153D0A9877CC62A474002DF32E52139F0A0"；
示例
-- 验证 [d]G == P (私钥*基点 == 公钥)
local xG = "32C4AE2C1F1981195F9904466A39C9948FE30BBFF2660BE1715A4589334C74C7"
local yG = "BC3736A2F4F6779C59BDCEE36B692153D0A9877CC62A474002DF32E52139F0A0"
local pkx, pky, private = gmssl.sm2keygen()
local rx, ry = gmssl.sm2pointmul(private, xG, yG)
log.info("sm2pointmul", rx == pkx and ry == pky) --true
-- 计算 [2]G
local k2 = "0000000000000000000000000000000000000000000000000000000000000002"
local rx2, ry2 = gmssl.sm2pointmul(k2, xG, yG)
log.info("[2]G.x", rx2) --32C4AE2C1F1981195F9904466A39C9948FE30BBFF2660BE1715A4589334C74C7
4.11 gmssl.sm2ecdh(private, peerPx, peerPy)
SM2 ECDH密钥协商: S = d * P (己方私钥 * 对方公钥)。双方各自用己方私钥和对方公钥计算, 得到相同的协商结果点, 用于派生共享对称密钥
新增于 2026.06.16
参数
private
参数含义：己方私钥;
数据类型：string；
取值范围：64位HEX字符串；
是否必选：必须传入此参数；
注意事项：私钥应在[1, n-1]范围内；
参数示例："D180FE37155E10983227A29F723893D7348A00CA4B06620BA9A2D31FC40E74A6"；
peerPx
参数含义：对方公钥X;
数据类型：string；
取值范围：64位HEX字符串；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例："CFACC1CCD6D4D2F8626ED14C4C43631E377536E3C7A8591CFABE8FB48B53BCD2"；
peerPy
参数含义：对方公钥Y;
数据类型：string；
取值范围：64位HEX字符串；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例："0901495ADEE795DFAF25A1E4141ED73233F9013628EBD56E369E3125A223AA25"；
返回值 local sx, sy = gmssl.sm2ecdh(private, peerPx, peerPy)
sx
含义说明：协商结果点的x坐标, 失败返回nil
数据类型：string；
取值范围：64位HEX字符串；
注意事项：暂无；
返回示例："58089A81B734BEDC10E17B65C1065CB87C9F720DBFF5D88135EFB6E4415C25F6"；
sy
含义说明：协商结果点的y坐标, 失败返回nil
数据类型：string；
取值范围：64位HEX字符串；
注意事项：暂无；
返回示例："9292BCF3E5A5AB4D26A0BB438182A0339375D591D8BAF9D143B0995604568688"；
示例
-- A方和B方各自生成密钥对
local pkxA, pkyA, privA = gmssl.sm2keygen()
local pkxB, pkyB, privB = gmssl.sm2keygen()
-- ECDH协商: 双方计算结果应一致
local sAx, sAy = gmssl.sm2ecdh(privA, pkxB, pkyB)
local sBx, sBy = gmssl.sm2ecdh(privB, pkxA, pkyA)
log.info("sm2ecdh", sAx == sBx and sAy == sBy) --true
4.12 gmssl.sm2pointadd(px1, py1, px2, py2)
SM2椭圆曲线点加: R = P + Q。已知曲线上两点P和Q, 计算它们的和点。和sm2pointmul配合使用, 常用于密钥交换协议中组合长期公钥和临时公钥
新增于 2026.06.16
参数
px1
参数含义：点P的x坐标;
数据类型：string；
取值范围：64位HEX字符串；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例："32C4AE2C1F1981195F9904466A39C9948FE30BBFF2660BE1715A4589334C74C7"；
py1
参数含义：点P的y坐标;
数据类型：string；
取值范围：64位HEX字符串；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例："BC3736A2F4F6779C59BDCEE36B692153D0A9877CC62A474002DF32E52139F0A0"；
px2
参数含义：点Q的x坐标;
数据类型：string；
取值范围：64位HEX字符串；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例："32C4AE2C1F1981195F9904466A39C9948FE30BBFF2660BE1715A4589334C74C7"；
py2
参数含义：点Q的y坐标;
数据类型：string；
取值范围：64位HEX字符串；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例："BC3736A2F4F6779C59BDCEE36B692153D0A9877CC62A474002DF32E52139F0A0"；
返回值 local rx, ry = gmssl.sm2pointadd(px1, py1, px2, py2)
rx
含义说明：结果点R的x坐标, 失败返回nil
数据类型：string；
取值范围：64位HEX字符串；
注意事项：暂无；
返回示例："32C4AE2C1F1981195F9904466A39C9948FE30BBFF2660BE1715A4589334C74C7"；
ry
含义说明：结果点R的y坐标, 失败返回nil
数据类型：string；
取值范围：64位HEX字符串；
注意事项：暂无；
返回示例："BC3736A2F4F6779C59BDCEE36B692153D0A9877CC62A474002DF32E52139F0A0"；
示例
-- 验证 G + G == [2]*G
local xG = "32C4AE2C1F1981195F9904466A39C9948FE30BBFF2660BE1715A4589334C74C7"
local yG = "BC3736A2F4F6779C59BDCEE36B692153D0A9877CC62A474002DF32E52139F0A0"
local k2 = "0000000000000000000000000000000000000000000000000000000000000002"
local dblx, dbly = gmssl.sm2pointmul(k2, xG, yG)
local addx, addy = gmssl.sm2pointadd(xG, yG, xG, yG)
log.info("sm2pointadd", addx == dblx and addy == dbly) --true
4.13 gmssl.sm2pointisoncurve(px, py)
判断点是否在SM2椭圆曲线上。用于密钥交换协议中对收到的临时公钥做合法性校验, 防止恶意构造的伪造公钥攻击
新增于 2026.06.16
参数
px
参数含义：点P的x坐标;
数据类型：string；
取值范围：64位HEX字符串；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例："32C4AE2C1F1981195F9904466A39C9948FE30BBFF2660BE1715A4589334C74C7"；
py
参数含义：点P的y坐标;
数据类型：string；
取值范围：64位HEX字符串；
是否必选：必须传入此参数；
注意事项：暂无；
参数示例："BC3736A2F4F6779C59BDCEE36B692153D0A9877CC62A474002DF32E52139F0A0"；
返回值 local ok = gmssl.sm2pointisoncurve(px, py)
ok
含义说明：点在曲线上返回true, 否则返回false
数据类型：boolean；
取值范围：true或false；
注意事项：暂无；
返回示例：true；
示例
-- 基点G在曲线上
local xG = "32C4AE2C1F1981195F9904466A39C9948FE30BBFF2660BE1715A4589334C74C7"
local yG = "BC3736A2F4F6779C59BDCEE36B692153D0A9877CC62A474002DF32E52139F0A0"
log.info("G on curve", gmssl.sm2pointisoncurve(xG, yG)) --true
-- (0,0)不在曲线上
local zero = "0000000000000000000000000000000000000000000000000000000000000000"
log.info("zero on curve", gmssl.sm2pointisoncurve(zero, zero)) --false
4.14 gmssl.sm2bnadd(a, b)
SM2曲线阶n取模加法: r = (a + b) mod n。对两个256-bit大整数相加后取模, 用于密钥交换协议中计算组合因子 t = (d + x̄*r) mod n
新增于 2026.06.16
参数
a
参数含义：操作数a;
数据类型：string；
取值范围：64位HEX字符串(256-bit大整数)；
是否必选：必须传入此参数；
注意事项：a应在[0, n-1]范围内；
参数示例："0000000000000000000000000000000000000000000000000000000000000001"；
b
参数含义：操作数b;
数据类型：string；
取值范围：64位HEX字符串(256-bit大整数)；
是否必选：必须传入此参数；
注意事项：b应在[0, n-1]范围内；
参数示例："0000000000000000000000000000000000000000000000000000000000000002"；
返回值 local r = gmssl.sm2bnadd(a, b)
r
含义说明：(a+b) mod SM2曲线阶n的结果
数据类型：string；
取值范围：64位HEX字符串；
注意事项：暂无；
返回示例："0000000000000000000000000000000000000000000000000000000000000003"；
示例
local one = "0000000000000000000000000000000000000000000000000000000000000001"
local two = "0000000000000000000000000000000000000000000000000000000000000002"
local r = gmssl.sm2bnadd(one, two)
log.info("sm2bnadd", r) --0000000000000000000000000000000000000000000000000000000000000003
4.15 gmssl.sm2bnmul(a, b)
SM2曲线阶n取模乘法: r = (a * b) mod n。对两个256-bit大整数相乘后取模, 和sm2bnadd配合使用计算密钥交换协议中的组合因子
新增于 2026.06.16
参数
a
参数含义：操作数a;
数据类型：string；
取值范围：64位HEX字符串(256-bit大整数)；
是否必选：必须传入此参数；
注意事项：a应在[0, n-1]范围内；
参数示例："0000000000000000000000000000000000000000000000000000000000000002"；
b
参数含义：操作数b;
数据类型：string；
取值范围：64位HEX字符串(256-bit大整数)；
是否必选：必须传入此参数；
注意事项：b应在[0, n-1]范围内；
参数示例："0000000000000000000000000000000000000000000000000000000000000003"；
返回值 local r = gmssl.sm2bnmul(a, b)
r
含义说明：(a*b) mod SM2曲线阶n的结果
数据类型：string；
取值范围：64位HEX字符串；
注意事项：暂无；
返回示例："0000000000000000000000000000000000000000000000000000000000000006"；
示例
local two = "0000000000000000000000000000000000000000000000000000000000000002"
local three = "0000000000000000000000000000000000000000000000000000000000000003"
local r = gmssl.sm2bnmul(two, three)
log.info("sm2bnmul", r) --0000000000000000000000000000000000000000000000000000000000000006
五、产品支持说明
不同产品的LuatOS固件，对gmssl核心库的支持情况如下：
1、Air780EX2/Air700ECP/Air780EPM/Air780EGP 1-2号、103-106号固件支持；
2、Air700ECH/Air780EHM/EHV/EGH/EGG/EHU/EHN/Air8000系列 所有固件都支持；
3、Air8101系列 101号、102号、103号、104号、106号固件支持；
4、Air1601 / Air1602 都支持；
各产品固件支持核心库列表详细说明参考下面链接：
Air780EX2/Air700ECP/Air780EPM/Air780EGP固件支持列表