NOFX 端到端加密系统实战:RSA-OAEP 混合加密、AES-GCM 存储加密与零破坏升级
NOFX 端到端加密系统实战:RSA-OAEP 混合加密、AES-GCM 存储加密与零破坏升级
导读
本文以 NOFX(AI 交易终端,覆盖美股、大宗商品、外汇与加密货币)仓库中的 ENCRYPTION_README.md 为核心,结合 crypto/crypto.go、api/crypto_handler.go、web/src/lib/crypto.ts 等源码,完整拆解这套"前端两阶段输入 + 传输层 RSA-4096/RSA-OAEP-2048 混合加密 + 存储层 AES-256-GCM 数据库加密"的三层安全体系。读完本文,你将掌握:如何在 NOFX 中启用传输加密与存储加密、密钥如何生成与配置、EncryptedString 如何让 GORM 模型自动加解密、为何系统刻意不提供解密接口,以及如何完成数据迁移、测试与回滚。
一、整体架构:三层安全防线
原文档用一张 ASCII 架构图概括了这套加密体系的层次结构,核心思想是"敏感数据在任何停留点都不以明文存在":
┌─────────────────────────────────────────────────────────┐
│ Three-Layer Security │
├─────────────────────────────────────────────────────────┤
│ Frontend: Two-stage input + clipboard obfuscation │
│ Transport: RSA-4096 + AES-256-GCM encryption │
│ Storage: Database encryption + audit logs │
└─────────────────────────────────────────────────────────┘
三个层次各司其职:
- 前端层(浏览器):通过"两阶段输入 + 剪贴板混淆"减少密钥在输入、粘贴环节的暴露面。实现位于 web/src/lib/crypto.ts(
generateObfuscation、validatePrivateKeyFormat)与 web/src/components/common/WebCryptoEnvironmentCheck.tsx。 - 传输层(浏览器 → 服务器):前端用服务器 RSA 公钥以混合加密方式加密敏感字段(AES-256-GCM 加密数据 + RSA-OAEP 包裹 AES 密钥),后端在配置更新接口内解密。
- 存储层(数据库):落库前的所有 API Key、Secret、Passphrase 等字段自动 AES-GCM 加密,读取时自动解密(GORM 自定义类型
EncryptedString)。
关于算法位数的说明:原文档标注传输层为 RSA-4096,而当前仓库源码中 crypto/crypto.go 的
GenerateKeyPair实际生成的是 2048 位 RSA 密钥,api/crypto_handler.go 返回的algorithm字段也明确为RSA-OAEP-2048。本文后续以源码为准,介绍 RSA-OAEP-2048 的具体实现。
二、快速上手:五分钟完成部署
原文档给出了一键部署流程,前提是仓库中存在 deploy_encryption.sh 与 scripts/migrate_encryption.go。需要说明的是:当前仓库实际并未包含这两个文件(crypto/ 目录仅有 crypto.go,scripts/ 目录仅有 optimize/ 子目录),因此在实际部署时请以 main.go 中的真实初始化流程为准。整体步骤对应如下:
# 1. 生成密钥并写入 .env(见下文"密钥管理"一节)
# 2. 启动应用(main.go 会自动初始化加密服务并注册路由)
go run main.go
启动时观察日志,正常情况下依次输出:
✅ Configuration loaded
🔐 Initializing encryption service...
✅ Encryption service initialized successfully
关键点:加密服务的初始化必须先于数据库初始化。main.go 中明确注释 Initialize encryption service BEFORE database (so EncryptedString can decrypt on read),因为 EncryptedString 在从数据库读取字段时要依赖全局加密服务执行解密,顺序颠倒会导致读取时解密失败。这一点在 cli.go 的 openStoreForCLI(本地管理员子命令如 reset-password 复用的初始化路径)中同样被遵守。
2.1 环境变量配置(必须项)
加密服务强依赖两个环境变量,缺失时 NewCryptoService() 会直接返回错误(见 crypto/crypto.go):
| 环境变量 | 说明 | 加载逻辑 |
|---|---|---|
RSA_PRIVATE_KEY |
RSA 私钥(PEM 格式) | 支持 \n 转义为真实换行;兼容 RSA PRIVATE KEY(PKCS#1)与 PRIVATE KEY(PKCS#8)两种 PEM 块 |
DATA_ENCRYPTION_KEY |
AES 数据加密密钥(Base64/Hex) | 依次尝试 Base64 标准/原始编码、Hex 解码;若均失败则取 SHA-256 哈希作为 32 字节密钥 |
2.2 可选项:传输加密开关
传输加密默认关闭(TRANSPORT_ENCRYPTION 未设置时 TransportEncryption=false),原因是便于 HTTP/IP 直连部署。config/config.go 中注释明确:开启需要 HTTPS 或 localhost 环境,仅当 TRANSPORT_ENCRYPTION=true 时启用:
# .env
TRANSPORT_ENCRYPTION=true
关闭状态下,api/crypto_handler.go 的 HandleGetPublicKey 返回空公钥与 transport_encryption: false,前端 web/src/lib/crypto.ts 与 web/src/lib/api/config.ts 会据此跳过加密流程。
三、传输层加密原理:RSA-OAEP + AES-256-GCM 混合加密
3.1 为什么要混合加密
RSA 适合加密小块数据(如密钥),不适合加密大段明文;AES-GCM 适合高速加密任意长度数据,但密钥分发困难。混合加密取两者之长:用 AES-256-GCM 加密真实数据,再用 RSA-OAEP 加密这次会话的 AES 密钥,服务器私钥只在解密 AES 密钥时被使用一次。
3.2 密文载荷结构
前后端约定的密文结构定义在 crypto/crypto.go 与 web/src/lib/crypto.ts:
{
"wrappedKey": "RSA-OAEP 包裹的 256 位 AES 密钥(base64url)",
"iv": "12 字节随机 IV(base64url)",
"ciphertext": "AES-GCM 密文,含 128 位认证标签(base64url)",
"aad": "附加认证数据,含 userId/sessionId/ts/purpose(base64url)",
"ts": "Unix 秒级时间戳,用于防重放"
}
3.3 前端加密流程(WebCrypto API)
web/src/lib/crypto.ts 的 encryptSensitiveData 完整实现七步流程:
crypto.subtle.generateKey生成 256 位 AES-GCM 会话密钥;crypto.getRandomValues生成 12 字节随机 IV(GCM 推荐 nonce 长度);- 构造 AAD 对象(
userId、sessionId、ts、purpose: 'sensitive_data_encryption'),随密文一起参与认证——任何人篡改 AAD 都会导致解密失败; - 用 AES-GCM 加密明文,
tagLength: 128附带 16 字节认证标签; exportKey('raw')导出 AES 密钥字节;- 用服务器公钥
RSA-OAEP(SHA-256)加密 AES 密钥得到wrappedKey; - 全部字段经
arrayBufferToBase64Url编码(+→-、/→_、去=)。
前端公钥导入使用 SPKI 格式(web/src/lib/crypto.ts),从 PEM 中剥离头尾与空白后以 crypto.subtle.importKey('spki', ...) 加载。
3.4 服务端解密流程与防重放
服务端 DecryptPayload(crypto/crypto.go)是逆向的对称过程,其中有两处值得关注的安全强化:
- 时间戳校验(防重放):
ts == 0直接拒绝;elapsed > 5*time.Minute || elapsed < -1*time.Minute判定过期或时钟偏移异常(允许 1 分钟前向偏移容忍)。注释中记录了一段历史教训:早期版本在ts缺失/为 0 时会完全跳过该校验,导致截获的密文可被无限重放;当前实现强制要求客户端盖章时间戳。 - RSA-OAEP 解密 + AES-GCM 认证:
rsa.DecryptOAEP(sha256.New(), ...)解开 AES 密钥,再以gcm.Open(nil, iv, ciphertext, aad)完成解密与完整性认证,AAD 不一致即失败。
四、存储层加密:EncryptedString 让 GORM 自动加解密
这是"零破坏变更"的核心:敏感字段的类型从 string 换成自定义类型 crypto.EncryptedString(crypto/crypto.go),所有读写自动加解密,业务代码几乎无需改动。
4.1 自动加密(写入)
实现 driver.Valuer 接口的 Value() 方法在字段写入数据库时被调用:
- 空值直接返回;
- 有全局加密服务时执行
EncryptForStorage; - 失败即中止(fail closed):加密失败返回错误,绝不允许把明文静默写入数据库——源码注释强调"a misconfigured/broken crypto service cannot leak credentials into the database in cleartext"。
4.2 自动解密(读取)
实现 sql.Scanner 接口的 Scan() 方法在读取时被调用:仅当值带 ENC:v1: 前缀时尝试解密;解密失败时返回原始值而非报错(保证历史明文数据仍可读取,这是向后兼容的关键设计);无加密前缀的值原样返回。
4.3 存储格式
密文格式为 ENC:v1:base64(nonce):base64(ciphertext)(crypto/crypto.go),常量定义见 crypto/crypto.go。EncryptForStorage 支持传入 AAD 分段(composeAAD 以 | 连接),可将 userId、exchangeId 等上下文绑定到密文,进一步防篡改。同时该函数对已加密值幂等(isEncryptedStorageValue 命中前缀则原样返回),避免重复加密。
4.4 实际应用位置
从源码看,以下模型的关键字段已切换为 EncryptedString:
- store/exchange.go:
APIKey、SecretKey、Passphrase、AsterPrivateKey、LighterPrivateKey、LighterAPIKeyPrivateKey; - store/ai_model.go:AI 模型
APIKey。
写入侧(如 store/exchange.go 的更新逻辑)统一将明文字段转换为 crypto.EncryptedString(...) 后交给 GORM;读取侧(如 manager/trader_manager.go、api/handler_trader_status.go)再通过 String() 取回明文使用。
五、API 边界:只暴露公钥,绝不暴露解密接口
加密相关路由只注册了两个 GET 端点(api/server.go):
| 端点 | 处理器 | 说明 |
|---|---|---|
GET /api/crypto/config |
HandleGetCryptoConfig |
返回 {"transport_encryption": bool},供前端判断是否走加密流程 |
GET /api/crypto/public-key |
HandleGetPublicKey |
返回 public_key(PEM)、algorithm: "RSA-OAEP-2048"、transport_encryption |
为什么没有解密端点? 这是整套设计中最关键的安全决策。api/crypto_handler.go 的注释直接点明:传输加密是单向的——客户端向服务器公钥加密敏感字段,服务器在已认证的配置更新接口内部调用 cryptoService.DecryptSensitiveData(见 api/handler_exchange.go 与 api/handler_ai_model.go)完成解密。如果暴露一个通用解密路由,服务器就会变成"解密预言机(decryption oracle)":任何未认证调用者都能用截获的密文换回明文(交易所/API 凭据),整个传输加密层形同虚设。
这一约束在前端同样成立:web/src/lib/crypto.ts 明确注释"客户端不存在解密辅助函数"——单向加密意味着前端解密既无用又是反模式。而 api/server_test.go 中还有一个专门的回归测试:对 POST /api/crypto/decrypt 发起请求并断言必须返回 404,防止未来有人无意中注册了解密预言机路由。
六、前端集成与两阶段输入
6.1 集成示例
原文档给出的前端集成流程(以保存交易所配置为例)在仓库中对应 web/src/lib/api/config.ts 的实现:
import { CryptoService } from '../lib/crypto';
// 1. 获取服务器公钥(内部会同步 transport_encryption 标志)
const publicKey = await CryptoService.fetchPublicKey();
// 2. 初始化并加密敏感字段
await CryptoService.initialize(publicKey);
const payload = await CryptoService.encryptSensitiveData(apiKey);
// 3. 将密文载荷发给后端
await api.post('/api/exchange/config', {
encrypted_key: payload,
});
6.2 两阶段输入与剪贴板混淆
"两阶段输入"指把私钥等敏感数据的录入拆成多次、短时存在,配合 web/src/lib/crypto.ts 的 generateObfuscation()(生成 32 字节随机十六进制字符串用于混淆)降低剪贴板嗅探风险;validatePrivateKeyFormat 负责在本地先校验 EVM 私钥格式(64 位十六进制,可选 0x 前缀,对应服务端 api/crypto_handler.go 的 isValidPrivateKey)。
6.3 运行环境自检
由于 WebCrypto 的 crypto.subtle 仅在安全上下文(HTTPS 或 localhost)可用,web/src/lib/crypto.ts 提供了 diagnoseWebCryptoEnvironment(),返回浏览器环境、isSecureContext、hasSubtleCrypto 等诊断信息;web/src/components/common/WebCryptoEnvironmentCheck.tsx 在前端据此提示用户升级到 HTTPS 环境。
七、密钥管理:生成、配置与轮换
7.1 密钥生成
仓库提供两个工具函数(crypto/crypto.go):
GenerateKeyPair():生成 RSA-2048 密钥对,返回 PEM 格式私钥(PKCS#1RSA PRIVATE KEY)与公钥(PUBLIC KEY);GenerateDataKey():生成 32 字节(256 位)AES 密钥,返回 Base64 编码。
服务端 NewCryptoService 从环境变量加载私钥与数据密钥(见 crypto/crypto.go):私钥若在 .env 中书写,需用 \n 表示换行(加载时自动替换还原);AES 密钥支持 Base64/Hex 两种编码,长度 16/24/32 字节直接采用,其他长度经 SHA-256 归一化为 32 字节(normalizeAESKey)。
对应的 .env 片段:
# 私钥(PEM,换行用 \n 转义)
RSA_PRIVATE_KEY=-----BEGIN RSA PRIVATE KEY-----\nMIIE...\n-----END RSA PRIVATE KEY-----
# AES 数据加密密钥(32 字节 Base64)
DATA_ENCRYPTION_KEY=<base64-encoded-32-bytes>
# 传输加密开关(需 HTTPS 或 localhost)
TRANSPORT_ENCRYPTION=true
7.2 密钥轮换
原文档提到"内置密钥轮换机制"(Key Rotation)。从源码看,存储格式中的 ENC:v1: 版本前缀(crypto/crypto.go)与 EncryptedPayload 中的可选 kid 字段(密钥标识)为多密钥共存与轮换预留了空间:轮换时可保留旧密钥仅用于解密历史数据、新密钥用于加密新数据。注意,实际轮换流程(旧数据重加密脚本)并未在当前仓库中以独立工具形式提供,实施时需自行编排。
八、数据迁移、测试与回滚
8.1 迁移策略
原文档描述的迁移工具 scripts/migrate_encryption.go 与 NewSecureStorage.MigrateToEncrypted() 在当前仓库中不存在,实际的兼容策略内置于 EncryptedString 本身:
- "自动迁移"即惰性加密:历史明文数据读取时原样返回(
Scan解密失败不报错),下次写入时经Value()自动加密落库——无需停机批量脚本; - 幂等写入:已带
ENC:v1:前缀的值不会重复加密; - 零破坏:原文档声明"Modified Files: None (backward compatible, no breaking changes)",与上述源码设计一致。
8.2 测试
原文档建议运行:
go test ./crypto -v
并预期输出 RSA 密钥对生成、AES 加解密、混合加密三组用例。当前仓库 crypto/ 目录仅包含 crypto/crypto.go(无独立测试文件),但加密体系的安全约束在别处有明确测试覆盖,最典型的是 api/server_test.go 对"解密预言机路由不存在"的回归断言。此外 api/handler_exchange_test.go 等测试直接构造 crypto.EncryptedString(...) 字段,验证了模型层的加解密行为。
8.3 回滚
原文档给出的回滚路径是:
# 恢复备份数据库
cp data.db.backup data.db
# 注释掉 main.go 中加密初始化相关代码,重新启动
go run main.go
结合源码补充两点:其一,EncryptedString.Scan 对无法解密的值会回退返回原文,因此即使加密服务暂时不可用,进程也能以"读原样"的方式容错;其二,回滚前务必保留私钥与数据密钥,否则已加密数据将无法解密。需要强调的是,cp data.db.backup data.db 只是文档示例,实际操作中恢复前应确认 data.db.backup 存在且未过期,禁止在运行中直接覆盖数据库文件。
九、成本与注意事项(以文档声明为限)
原文档给出了如下成本估算,其中部分数字未在当前仓库中找到可验证依据,仅作为文档声明转述,请以实际部署测量为准:
- 开发成本:0(文档称已实现,无需额外开发);
- 运行时开销:文档两处表述不一("<25ms/次操作"与"<0.1ms/次操作"),考虑到 AES-GCM 为硬件加速友好的对称算法、RSA-OAEP 仅在写入敏感配置时使用,实际开销通常可忽略,但具体数值依赖硬件与数据规模;
- 存储成本:文档称约 +30%(Base64 编码、IV、认证标签等开销所致,密文
ENC:v1:前缀及 base64 膨胀是主要来源); - 维护成本:文档称极低(自动加密 + 惰性迁移,无需人工批量作业)。
部署注意要点
- 初始化顺序:加密服务必须先于数据库初始化(main.go);
- HTTPS 前提:传输加密仅适合 HTTPS 或 localhost 部署(config/config.go),HTTP 公网直连场景请保持关闭;
- 密钥即安全边界:文档的安全收益表(剪贴板嗅探、浏览器扩展窃取、服务器被攻破)建立在私钥与数据密钥不泄露的前提下——数据库泄露不等于密钥泄露,这才是存储加密的意义所在;
- 密钥丢失后果:数据密钥丢失意味着已加密数据永久不可读,密钥管理与备份应与数据库备份同等重视。
十、小结
NOFX 的端到端加密体系可以概括为一句话:让敏感数据在任何停留点都以密文形式存在,且只允许单向解密。前端用 WebCrypto 完成混合加密与混淆输入,传输层用 RSA-OAEP-2048 包裹 AES-256-GCM 会话密钥,存储层用 EncryptedString 透明加解密 GORM 字段,而"绝不提供公开解密接口"这一边界守住了整套体系不被绕过。配合 ENC:v1: 版本前缀与惰性迁移,历史数据平滑过渡、零破坏升级——这套"前后端加密闭环 + 单向解密边界"的设计,值得任何需要保护用户凭据的交易或金融类应用参考。
继续深入可阅读仓库中的相关实现:crypto/crypto.go(全部密码学原语)、api/crypto_handler.go(API 边界设计)、web/src/lib/crypto.ts(前端加密模块)、api/server_test.go(解密预言机回归测试)。