NOFX 端到端加密系统实战:RSA-OAEP 混合加密、AES-GCM 存储加密与零破坏升级

原创2026-09-21 10:03:101,741 阅读
文章标签:AI Agent金融科技后端前端

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              │
└─────────────────────────────────────────────────────────┘

三个层次各司其职:

  1. 前端层(浏览器):通过"两阶段输入 + 剪贴板混淆"减少密钥在输入、粘贴环节的暴露面。实现位于 web/src/lib/crypto.ts(generateObfuscation、validatePrivateKeyFormat)与 web/src/components/common/WebCryptoEnvironmentCheck.tsx。
  2. 传输层(浏览器 → 服务器):前端用服务器 RSA 公钥以混合加密方式加密敏感字段(AES-256-GCM 加密数据 + RSA-OAEP 包裹 AES 密钥),后端在配置更新接口内解密。
  3. 存储层(数据库):落库前的所有 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 完整实现七步流程:

  1. crypto.subtle.generateKey 生成 256 位 AES-GCM 会话密钥;
  2. crypto.getRandomValues 生成 12 字节随机 IV(GCM 推荐 nonce 长度);
  3. 构造 AAD 对象(userId、sessionId、ts、purpose: 'sensitive_data_encryption'),随密文一起参与认证——任何人篡改 AAD 都会导致解密失败;
  4. 用 AES-GCM 加密明文,tagLength: 128 附带 16 字节认证标签;
  5. exportKey('raw') 导出 AES 密钥字节;
  6. 用服务器公钥 RSA-OAEP(SHA-256)加密 AES 密钥得到 wrappedKey;
  7. 全部字段经 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 的更新逻辑)统一将明文字段转换为 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#1 RSA 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 膨胀是主要来源);
  • 维护成本:文档称极低(自动加密 + 惰性迁移,无需人工批量作业)。

部署注意要点

  1. 初始化顺序:加密服务必须先于数据库初始化(main.go);
  2. HTTPS 前提:传输加密仅适合 HTTPS 或 localhost 部署(config/config.go),HTTP 公网直连场景请保持关闭;
  3. 密钥即安全边界:文档的安全收益表(剪贴板嗅探、浏览器扩展窃取、服务器被攻破)建立在私钥与数据密钥不泄露的前提下——数据库泄露不等于密钥泄露,这才是存储加密的意义所在;
  4. 密钥丢失后果:数据密钥丢失意味着已加密数据永久不可读,密钥管理与备份应与数据库备份同等重视。

十、小结

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(解密预言机回归测试)。

登录后查看全文
nofx