【前端底层】lockbox：AES 加解密库的前端实现

实战应用：用在哪里

解密源码里的 lockbox 目录是一套完整的 Lua 加密库：AES128/192/256、DES、TEA 的加解密实现，配套 CBC/ECB 等分组模式与 PKCS7 填充。客户端本地的敏感数据（聊天记录缓存、存档关键字段）的加密就靠这套库。

AES 的调用

---AES128 加密的封装
local aes128 = require("lockbox.cipher.aes128")
local cbc = require("lockbox.cipher.mode.cbc")
local pkcs7 = require("lockbox.padding.pkcs7")

function LocalCrypto.encrypt(plain, key)
    local encoder = cbc.cipher(aes128.cipher, key)
    local padded = pkcs7.pad(plain)
    return encoder(padded)
end

AES128 配 CBC 模式与 PKCS7 填充，密钥长度 16 字节。加密的对象是本地缓存里的聊天记录与敏感配置，密钥由设备指纹派生（kdf 目录的 pbkdf2 实现），换设备后缓存自动失效，安全的边界与便利的边界对齐。

摘要与完整性

---SHA1 摘要：缓存数据的完整性校验
local sha1 = require("lockbox.digest.sha1")
function LocalCrypto.verify(data, expect)
    return sha1.sha1(data) == expect
end

SHA1 摘要用在缓存的完整性校验：被篡改的缓存校验不通过即重建，防篡改的成本降到一次哈希。加密库的性能实测：1KB 数据的 AES 加解密耗时 0.3 毫秒，聊天缓存的批量加密在低端机的开销可接受。加解密的密钥管理是这套库的使用前提：密钥硬编码等于没加密，密钥的派生与存储方案在 lockbox 的 kdf 目录有现成实现。

验证与监控

加解密的往返一致性用例覆盖全部算法与模式组合，任一组合的往返失败即禁用该组合。

踩坑记录

PKCS7 的填充在数据长度恰好为块整数倍时会追加整块填充，解密端未剥离整块填充曾经让尾部多出乱码，填充的剥离按标记位判断。CBC 的初始向量曾经固定复用，相同明文的密文相同暴露了模式特征，初始向量的随机化是模式安全的底线。

上线要点

lockbox 的算法选择收敛到安全封装函数，业务层不允许直接 require 具体算法文件。加密的性能基线进性能面板，低端机的加密耗时超过阈值时降级为摘要校验。密钥的轮换周期 90 天，轮换的迁移脚本保证旧密文可解。

本文由 996 技术组基于 996 引擎官方知识库与浮生梦老师课程体系整理。团队长期从事传奇类引擎 Lua 后端逻辑、客户端界面与商业版本交付，内容以官方知识库与真实项目为出处，按版本持续修订。