1. 先把 crypto 模块的边界摸清楚再动手写第一行加解密代码第一次认真翻 crypto 模块的文档是被一次代码审计打回来的。当时我用它给用户手机号做了加密存储密钥写在配置文件里createCipheriv选了aes-128-cbcIV 图省事直接用了全零自我感觉“加密了就行”。审计同学只回了一句话这跟没加密的区别只在于攻击者需要多花十分钟。那次之后我才明白加密和解密这件事难点从来不在 API 怎么调而在于你得先知道自己在解决哪一类问题是要保密别人看不懂、要完整性别人改不了、要身份确认确认是谁发的还是要口令校验确认登录的人知道密码。crypto 模块把这些能力都塞在一个命名空间里长得还都挺像一不小心就会拿锤子去拧螺丝。这篇内容适合两类人看一类是刚接触 Node.js crypto 模块、想搞明白createHash、createCipheriv、sign这些 API 到底该在什么场合用的开发者另一类是已经用了几年但每次写加解密都得回去翻自己半年前的代码、复制粘贴一遍再改改的工程师。我会把踩过的坑、参数背后的算术、跨语言互通时的坑点都摊开讲代码尽量给到可以直接抄走运行的完整版本。1.1 三层能力摘要、对称、非对称先分清再动手crypto 模块提供的功能看起来零散其实可以归到三个层次上每一个层次解决的问题完全不同。摘要类是单向的代表 API 是createHash和createHmac。它的输出无法反推回输入用途是校验数据有没有被改过、两个大文件是不是同一份、口令是不是对得上。很多人第一次接触“MD5 加密”这个概念就是从这里开始的但严格来说它不叫加密叫哈希因为没有解密这一步——本质上不存在“MD5 解密”网上那些所谓的解谜站点干的其实是暴力枚举彩虹表比对输入只要稍微长一点就无能为力。对称加密类是双向的代表 API 是createCipheriv和createDecipheriv。加密和解密用同一把密钥速度快适合加密大块数据比如用户的身份证号、一段聊天记录、一个上传的文件。它的问题是密钥分发你要把密钥安全地送到解密方手里。非对称类的代表是generateKeyPairSync、publicEncrypt、privateDecrypt、sign、verify。公钥加密私钥解密或者私钥签名公钥验签解决了密钥分发问题但性能比对称加密差好几个数量级而且能加密的明文长度有硬上限。实际工程里几乎不会只用其中一层。最常见的组合是用非对称加密把一把临时生成的对称密钥传给对方然后双方用这把对称密钥加密真正的业务数据。这个模式叫信封加密后面第 5 节会展开讲怎么落地。1.2 crypto 是 OpenSSL 的一层绑定不是它自己实现的算法这一点很关键因为它决定了你遇到的大部分报错该往哪个方向查。Node.js 的 crypto 模块本身并不包含 AES、RSA、SHA 这些算法的实现代码它是通过内部绑定调用 OpenSSL 这个 C 语言密码学库。你在 JavaScript 里写的crypto.createCipheriv(aes-256-gcm, ...)最终会落到 OpenSSL 的EVP_EncryptInit_ex之类的函数上。这个事实带来三个直接后果。第一算法名字符串的合法性由 OpenSSL 决定。你写aes-256-gcm能跑写aes_256_gcm就报Digest method not supported或者Unknown cipher。想查当前环境支持哪些算法直接跑crypto.getCiphers()和crypto.getHashes()打印出来看比翻文档快。第二Node 版本升级会带来 OpenSSL 版本跃迁。Node 17 之后底层换到了 OpenSSL 3一批老算法被挪进了 legacy provider默认不可用。这就是为什么很多老项目升级 Node 之后会突然冒出error:0308010C:digital envelope routines::unsupported——代码一行没改底层把des-ecb、md4这类算法默认关掉了。要么改算法要么在启动参数里挂上 legacy provider前者是正解。第三某些行为在不同平台上有细微差异。同一段代码在 Linux 上跑得好好的换到某些系统上算法的默认参数可能不一样。如果你要做跨平台部署参数尽量显式传全别依赖默认值。1.3 搜报错之前先确认自己在哪个生态里crypto这个名字在各语言生态里被反复使用导致网上搜“crypto 报错”出来的结果经常驴唇不对马嘴。我自己就干过一次蠢事排查了半天 Node 的加密逻辑最后发现报错来自另一个服务是 Java 侧的java.lang.NoClassDefFoundError: org/apache/hadoop/crypto——那是 Hadoop 依赖打包时的类缺失问题跟 Node 一点关系都没有。类似的还有Python 里pycryptodome提供了Crypto包导入时的大小写和 Node 完全不同有些移动端和嵌入式场景会把加密相关的组件也命名成 crypto浏览器端有window.cryptoWeb Crypto API它的 API 风格是 Promise 加subtle命名空间跟 Node 的 crypto 模块长得完全不一样虽然 Node 后来也把globalThis.crypto补上了但两套 API 混用会让人非常困惑。所以排查加解密问题的第一步永远是确认报错来自哪个运行时、哪个库、哪个版本。把这个确认清楚能省掉一半的无效搜索时间。1.4 有一条线不能越只处理你有权限处理的数据加解密技术本身是中性的但用途有边界。我给自己定的规矩很简单只对自己拥有或已获授权处理的数据做加解密包括自己系统的数据、自己生成的文件、自己项目的配置。不参与绕过他人技术保护措施的行为不帮助他人解开本不该他持有的加密内容。这条线不是道德说教而是实打实的风险控制。绕过别人的保护机制往往同时触碰多个法律条款为了一点技术好奇心去趟这个浑水性价比极低。后面讲的所有内容都建立在这个前提上。2. AES 对称加密为什么我把默认答案换成了 AES-256-GCM如果今天你在项目里只需要记一条关于对称加密的结论那就是新写的代码里默认用aes-256-gcm。这不是因为它新而是因为它在设计上同时给到了保密性和完整性而老一代的aes-128-cbc只能给保密性——攻击者可以在不知道密钥的情况下篡改你的密文解密后你还浑然不觉。2.1 从 ECB 踩到 CBC再换到 GCM一段分组模式的进化史先说说为什么不能用 ECB。ECB 模式的做法是把明文按 16 字节切成块每块独立加密。问题在于相同的明文块会产生完全相同的密文块于是整段密文的统计特征被完整保留下来。经典的演示是用 ECB 加密一张纯色背景的图片加密后图片轮廓依然清晰可辨。用在结构化数据上同理如果你的字段里有很多重复值比如性别、状态码攻击者光看密文分布就能猜出不少信息。CBC 模式解决了这个问题每一块明文先和前一块的密文做异或再加密相同的明文块在不同位置会产生不同密文。为此它需要一个初始向量 IV 来启动这个链条。CBC 的坑在于它本身不提供完整性保护而且如果 IV 在多次加密中重复使用攻击者可以通过对比密文差异推导出明文关系这就是 BEAST 那类攻击的基本思路。GCM 是 AEAD带关联数据的认证加密模式它一次输出两个东西密文和一个 16 字节的认证标签 authTag。解密时除了密钥和 IV 要对authTag 也必须对得上任何一个字节的篡改都会导致解密直接抛错。这意味着你不需要再额外算一个 HMAC 来保证完整性。这里有个必须记住的坑GCM 的 IV 绝对不能重复使用。同一个密钥下如果两段不同的明文用了相同的 IV攻击者能通过认证标签的数学关系反推出密钥相关材料这是灾难级的。GCM 的 IV 规范推荐长度是 12 字节96 位用crypto.randomBytes(12)随机生成碰撞概率在合理的调用量下可以忽略。各模式的对比大致是这样模式保密性完整性IV 要求建议ECB弱模式泄露无无新代码不要用CBC是无16 字节随机不可复用兼容老系统时才用CTR是无计数器不可复用需要流式且自带完整性校验时慎用GCM是是authTag12 字节随机绝不可复用默认选择2.2 Key、IV、AuthTag、AAD四个角色各自的职责很多人第一次写 GCM 会觉得参数太多记不住其实把每个东西的职责想清楚就顺了。Key是从口令派生出或由密钥管理系统下发的秘密。AES-256 要求正好 32 字节不是“32 个字符”。如果你直接把一个字符串当 key 传进去Node 会按 UTF-8 编码成字节只要字符串的字节长度不对就会报Invalid key length。中文口令尤其容易踩这个坑一个汉字 UTF-8 占 3 字节10 个汉字就是 30 字节离 32 差两个字节而你从字符数上根本看不出来。IV初始向量是每次加密都要重新随机生成的值它不需要保密可以直接和密文拼在一起传输。它的作用是让同一把密钥在多次加密中产生不同的密文。GCM 用 12 字节。AuthTag认证标签加密完成后通过cipher.getAuthTag()取出默认 16 字节。它必须和密文一起保存或传输解密前通过decipher.setAuthTag(tag)塞回去。忘记取 authTag 或者传输时丢了它是新手最常见的错误症状是解密时抛Unsupported state or unable to authenticate data。AADAdditional Authenticated Data附加认证数据可选参数。它的特点是参与完整性校验但不被加密。典型用途是放协议版本号、租户 ID、数据主键这类需要公开但必须防篡改的元信息。如果攻击者把版本号从 v1 改成 v2 来诱导你走老逻辑AAD 会让他没法得逞。2.3 一份可以直接抄走的 AES-256-GCM 实现下面这段是我现在项目里用的版本把版本号放进 AAD把 IV、Tag、密文按固定顺序打包成一个 base64 字符串好处是存储层只需要一个字段就能装下全部信息。const crypto require(crypto); // 从口令派生 32 字节密钥。salt 必须是每个口令独立随机生成的不能固定 function deriveKey(password, salt, keylen 32) { return crypto.scryptSync(password, Buffer.from(salt, hex), keylen, { N: 1 15, // 32768CPU/内存开销参数 r: 8, // 块大小 p: 1, // 并行度 maxmem: 64 * 1024 * 1024, }); } // 打包格式[版本 2B][IV 12B][Tag 16B][密文 ...] function seal(plaintext, key) { const iv crypto.randomBytes(12); const cipher crypto.createCipheriv(aes-256-gcm, key, iv); const aad Buffer.from(v1, utf8); cipher.setAAD(aad); const body Buffer.concat([ cipher.update(plaintext, utf8), cipher.final(), ]); const tag cipher.getAuthTag(); return Buffer.concat([aad, iv, tag, body]).toString(base64); } function open(packed, key) { const buf Buffer.from(packed, base64); if (buf.length 30) throw new Error(密文长度异常); const aad buf.subarray(0, 2); const iv buf.subarray(2, 14); const tag buf.subarray(14, 30); const body buf.subarray(30); const decipher crypto.createDecipheriv(aes-256-gcm, key, iv); decipher.setAAD(aad); decipher.setAuthTag(tag); return Buffer.concat([decipher.update(body), decipher.final()]).toString(utf8); } module.exports { deriveKey, seal, open };用法和验证const { deriveKey, seal, open } require(./aesgcm); const salt crypto.randomBytes(16); const key deriveKey(my-strong-passphrase, salt.toString(hex)); const token seal(13800138000, key); console.log(token); console.log(open(token, key)); // 13800138000 // 篡改一个字符解密必然失败 const tampered token.slice(0, -2) AA; try { open(tampered, key); } catch (e) { console.log(认证失败:, e.message); }这段代码里有几个设计选择值得说明。为什么版本号放在最前面而不是放到密文尾部因为解析时需要先读版本号决定用哪套解包逻辑放前面可以边读边判断不用把整个 Buffer 切一遍。为什么 AAD 用固定的v1而不是拼接更多字段因为 AAD 越长每次校验的开销越大而它保护的信息本身是公开的长度控制在够用就好。2.4 报错信息对照表把症状和根因对上号加解密的报错信息大多比较抽象我把这些年遇到过的整理成一张表出问题时可以按症状反查。报错关键词真实原因排查动作Invalid key length密钥字节数与算法不匹配aes-256 需 32 字节打印Buffer.from(key).length别按字符数判断Invalid IV lengthIV 长度与加密时不一致GCM 通常应为 12 字节确认解密时取出的 IV 偏移正确Unsupported state or unable to authenticate dataauthTag 不匹配、密钥错误、AAD 不一致、密文被截断逐项比对 tag 是否为完整 16 字节、AAD 是否一致bad decryptCBC 模式下密钥错误或填充被破坏确认密钥与填充方式检查密文是否被截断Cannot read properties of undefined (reading setAuthTag)解密端没有从密文里解析出 tag检查打包格式与切片偏移digital envelope routines::unsupported使用了被 OpenSSL 3 移除的旧算法换用aes-256-gcm或升级相关依赖ERR_CRYPTO_INVALID_KEY_OBJECT_TYPE该用私钥的地方传了公钥或格式不匹配检查密钥类型与 PEM 头一个实测的小技巧遇到认证失败时先把密钥、IV、tag 的十六进制值都打印出来跟加密端的日志逐一对比。绝大多数情况下根本不是算法问题而是某一处切片偏移错了 2 个字节或者 AAD 在加密端是v1、解密端写成了V1。3. 哈希这条线MD5 只能当校验码口令必须用慢哈希哈希函数在 crypto 模块里存在感很强因为它用起来最无脑crypto.createHash(md5).update(data).digest(hex)一行完事。也正因为无脑它被滥用的程度最高。我在线上代码里见过用 MD5 存用户密码、用 MD5 做接口签名、用 MD5 生成订单号的这三件事各有各的问题。3.1 hash 和 hmac 不是一回事用错了等于没校验createHash是纯哈希任何人拿到数据和算法都能算出相同结果。它适合做两件事校验数据完整性比如下载文件后比对哈希值、给数据生成一个短的指纹比如给 URL 参数生成缓存键。createHmac是带密钥的哈希也叫消息认证码。它在计算过程中混入了一把密钥没有密钥的人算不出正确结果。它适合做接口签名、Webhook 验签、内部服务之间的请求认证。两者的区别在安全上是决定性的。如果你用纯哈希做接口签名攻击者拿到你的签名算法后可以直接构造任意请求并算出合法签名签名机制形同虚设。这类事故我在实际项目里遇到过不止一次代码大概长这样// 反面教材用纯哈希当签名 const sign crypto.createHash(md5).update(secret payload secret).digest(hex);看起来像是“把密钥掺进去了”但 MD5 的迭代结构决定了这种拼接方式在特定长度下存在长度扩展攻击的风险而且 MD5 本身早就不抗碰撞了。正确的写法是const crypto require(crypto); function hmacSign(payload, key) { return crypto.createHmac(sha256, key).update(payload, utf8).digest(hex); } function hmacVerify(payload, key, signature) { const expected hmacSign(payload, key); const a Buffer.from(expected, utf8); const b Buffer.from(signature, utf8); if (a.length ! b.length) return false; return crypto.timingSafeEqual(a, b); }注意最后那个timingSafeEqual。普通的字符串比较会在第一个不同字符处提前返回攻击者可以通过测量响应时间的微小差异一个字节一个字节地把签名猜出来。这个攻击在局域网环境里是可行的timingSafeEqual就是为了消除这种时间侧信道而存在的。用它之前必须先判断长度相等否则函数本身会抛异常——这是它的一个使用前提文档里写了但很容易被忽略。3.2 存口令为什么必须用 scrypt 或 pbkdf2参数怎么定把 MD5 换成 SHA-256 来存密码是不是就安全了不是。原因在于MD5 和 SHA-256 都是为“快”而设计的一块普通的显卡每秒能算几十亿次 SHA-256。如果你的数据库泄露了攻击者用一张常见口令表跑一遍几小时内就能把大部分口令还原出来。真正的解法是使用专门为存口令设计的慢哈希scrypt和pbkdf2。它们的核心思想是通过大量计算和内存访问让单次计算的开销变大。攻击者要跑 10 亿次组合从几小时变成几十年成本上就不划算了。Node 的crypto.scryptSync有三个关键参数参数含义我的常用取值影响NCPU/内存成本必须是 2 的幂32768即 115内存用量约 128 × N × r 字节r块大小8同时影响内存与计算量p并行度1主要影响 CPU 时间maxmem允许的最大内存64MB默认 32MB容易不够这里有个很容易踩的坑当 N 取 32768、r 取 8 时理论内存需求是 128 × 32768 × 8 33.5MB正好超过 Node 默认的 32MB 上限会直接抛出memory limit exceeded。解决办法就是把maxmem显式调大比如设成 64MB。我见过有人为了绕开这个限制把 N 调小到 16384其实是把安全强度降下来了正确做法是提高 maxmem。如果要用 PBKDF2推荐参数是 HMAC-SHA256 加至少 60 万次迭代。迭代次数不是越大越好而是要结合你的服务器承受能力来定。我的经验测法是在目标机器上写个循环测出单次校验耗时控制在 100 到 200 毫秒之间。低于 50 毫秒说明强度可能不够高于 500 毫秒说明登录接口会成为吞吐瓶颈尤其在并发登录时会有明显体感。还有个必须注意的点scryptSync是同步的会阻塞事件循环。如果我前面说的单次 100 毫秒成立那么在一个单线程的 Node 服务里一次登录校验就会让其他所有请求排队 100 毫秒。生产环境的登录接口一定要用异步版本crypto.scrypt回调或 Promise 包装把计算放到 libuv 的线程池里别用 Sync 版本。存库时的结构建议是scrypt$N$r$p$salt$hash把参数也一起存下来。这样将来你想调整参数强度时老数据仍然能按原来的参数验证通过用户下次登录成功后再用新参数重新生成一遍实现平滑升级。3.3 大文件校验流式哈希与内存占用的取舍如果要对一个 2GB 的日志文件算哈希用fs.readFileSync读进来再update你的进程内存会瞬间飙到 2GB 以上大概率被系统干掉。正确做法是流式处理const fs require(fs); const crypto require(crypto); function sha256File(path) { return new Promise((resolve, reject) { const hash crypto.createHash(sha256); fs.createReadStream(path, { highWaterMark: 1024 * 1024 }) .on(data, (chunk) hash.update(chunk)) .on(end, () resolve(hash.digest(hex))) .on(error, reject); }); }这里我把highWaterMark设成了 1MB比默认的 64KB 大。原因是哈希计算是纯 CPU 操作非常快真正的瓶颈在磁盘 IO 的读写切换次数上。块太小会导致频繁的系统调用块太大则每次分配的内存多、GC 压力上升。1MB 到 4MB 这个区间在实际测试里表现比较均衡具体值可以看你机器的页大小和磁盘类型微调。顺带说一个实际场景给上传的文件做去重时先算哈希再比对是最简单的办法但如果两个文件只差一个字节哈希完全不同去重就失效了。这时候需要的是内容定义分块或者局部敏感哈希那就超出 crypto 模块的范围了得换专门的库。4. 非对称加密与签名RSA 有个绕不过去的长度天花板对称加密好用但密钥怎么送到对方手里是个死结。非对称加密就是为这个场景设计的公钥可以随便公开私钥自己留着任何人用你的公钥加密的数据只有你的私钥能解开。4.1 RSA 加密的 190 字节上限以及为什么不能硬塞第一次用crypto.publicEncrypt加密一段用户信息很多人会直接抛data too large for key size。这不是 bug是 RSA 的数学结构决定的。RSA 加密的本质是一次模幂运算明文必须先转换成一个小于模数 N 的整数。2048 位密钥意味着模数是 2048 位也就是 256 字节。但你不能把 256 字节全用上因为填充方案也要占位置。用 OAEP 加 SHA-256 填充时可用空间的计算方式是最大明文长度 模长字节数 - 2 × 哈希长度 - 2 256 - 2 × 32 - 2 190 字节190 字节大概是 63 个汉字。这个数字记住很有用它能直接告诉你“RSA 加密用户资料”这个思路行不通。那实际怎么做标准方案还是信封加密随机生成一把 AES 密钥用它加密业务数据再用 RSA 公钥加密这把 AES 密钥。接收方先用自己的私钥解出 AES 密钥再用它解密数据。整个流程里 RSA 只处理 32 字节的密钥远远没到 190 字节的上限。const crypto require(crypto); // 生成一对 2048 位 RSA 密钥推荐 PKCS#8 和 SPKI 格式 const { publicKey, privateKey } crypto.generateKeyPairSync(rsa, { modulusLength: 2048, publicKeyEncoding: { type: spki, format: pem }, privateKeyEncoding: { type: pkcs8, format: pem }, }); // 信封加密 const dek crypto.randomBytes(32); const iv crypto.randomBytes(12); const cipher crypto.createCipheriv(aes-256-gcm, dek, iv); const body Buffer.concat([cipher.update(需要保护的业务数据, utf8), cipher.final()]); const tag cipher.getAuthTag(); const wrappedKey crypto.publicEncrypt( { key: publicKey, padding: crypto.constants.RSA_PKCS1_OAEP_PADDING, oaepHash: sha256 }, dek ); // 解密侧 const unwrapped crypto.privateDecrypt( { key: privateKey, padding: crypto.constants.RSA_PKCS1_OAEP_PADDING, oaepHash: sha256 }, wrappedKey ); const decipher crypto.createDecipheriv(aes-256-gcm, unwrapped, iv); decipher.setAuthTag(tag); console.log(Buffer.concat([decipher.update(body), decipher.final()]).toString(utf8));密钥长度怎么选2024 年的建议是至少 2048 位3072 位更稳妥。1024 位已经明确不安全不要再用。4096 位不是不行但签名和验签的耗时会明显上升在高频调用的场景里不划算。填充方式上加密用 OAEP签名用 PSS。老的RSA_PKCS1_PADDING存在一些已知的攻击面新代码不要用。Node 里对应的常量是RSA_PKCS1_OAEP_PADDING和RSA_PKCS1_PSS_PADDING。4.2 别再说“用私钥加密”签名用的是一套独立的 API“私钥加密、公钥解密”这个说法在早期教材里很常见但它在密码学上是不严谨的而且会导致错误的技术选型。原因有两点一是私钥加密可以理解为对任意数据都成立理论上存在伪造风险二是很多实现里私钥加密的填充方式和公钥加密不同跨语言调用时对不上。正确的做法是用专门的签名接口const data Buffer.from(order20240101amount100, utf8); const signature crypto.sign(sha256, data, { key: privateKey, padding: crypto.constants.RSA_PKCS1_PSS_PADDING, saltLength: crypto.constants.RSA_PSS_SALTLEN_DIGEST, }); const ok crypto.verify(sha256, data, { key: publicKey, padding: crypto.constants.RSA_PKCS1_PSS_PADDING, saltLength: crypto.constants.RSA_PSS_SALTLEN_DIGEST, }, signature); console.log(ok); // true签名的语义很清晰证明这份数据是由持有私钥的人发出的并且中途没有被篡改。它和加密是两件独立的事可以同时使用先对数据签名证明来源再对称加密保护内容。如果项目里不需要考虑和老的 RSA 系统兼容我更推荐直接用 Ed25519const { publicKey, privateKey } crypto.generateKeyPairSync(ed25519); const sig crypto.sign(null, Buffer.from(payload), privateKey); const valid crypto.verify(null, Buffer.from(payload), publicKey, sig);Ed25519 的密钥更短、签名更快、实现上更难出错sign的第一个参数传null是因为算法本身已经确定了哈希方式。现在新做系统只要上下游都支持我基本都选它。4.3 密钥格式PEM、DER、PKCS#1、PKCS#8 到底怎么换算跨系统对接时密钥格式不一致是仅次于参数不一致的第二大坑。常见的有这么几种格式标识PEM 头内容PKCS#1 私钥BEGIN RSA PRIVATE KEY只包含 RSA 参数不支持其他算法PKCS#8 私钥BEGIN PRIVATE KEY通用的私钥容器可装 RSA、EC、Ed25519PKCS#1 公钥BEGIN RSA PUBLIC KEY老格式不少 Java 工具默认导出这个SPKI 公钥BEGIN PUBLIC KEY通用公钥格式Node 的spki就是它Node 的generateKeyPairSync里私钥编码类型选pkcs8、公钥选spki这是兼容性最好的组合。但如果对方给你的是 PKCS#1 的私钥你直接喂给crypto.createPrivateKey可能会报error:0909006C:PEM routines:get_name:no start line之类的错。转换命令很简单# PKCS#1 私钥转 PKCS#8 openssl pkcs8 -topk8 -nocrypt -in rsa_pkcs1.pem -out rsa_pkcs8.pem # PKCS#8 私钥转 PKCS#1加 -traditional openssl rsa -in rsa_pkcs8.pem -traditional -out rsa_pkcs1.pem # 从证书里导出 SPKI 公钥 openssl x509 -in cert.pem -pubkey -noout pub_spki.pem如果密钥是 JWK 格式很多身份认证服务的标准格式Node 可以直接导入不需要转换const keyObject crypto.createPrivateKey({ key: jwkObject, format: jwk });这个能力从 Node 15 开始提供之前只能自己手写 Base64URL 解码来拼 DER 结构非常麻烦。如果你的项目还在用老版本升级到这个版本以上能省不少事。5. 从能跑到敢上线加解密落地时真正会出问题的几件事代码写通了只是第一步。我经历过几次事故没有一次是算法用错全是工程细节出了问题。5.1 密钥管理配置文件里放密钥是最贵的一课前面所有例子里我都在用变量传密钥这是刻意的。把密钥写进代码仓库是最常见也最危险的错误。代码仓库的访问权限通常比生产环境宽松得多一次误操作把仓库设成公开密钥就彻底暴露了。就算仓库是私有的历史提交记录里也永远留着那串密钥删掉文件是没用的必须做提交历史重写。我现在遵循的一套做法是这样的。第一层密钥不落代码。开发环境从环境变量读生产环境从密钥管理服务读。启动时做一次初始化把密钥加载到内存里进程别的地方只从内存拿。第二层做密钥轮换能力。这就是我在第 2 节那段代码里把版本号放进 AAD 的原因。将来要换密钥只需要解密时先读版本号从密钥表里挑对应版本的那一把新数据用新版加密老数据在下次写入时自然迁移。没有版本号的话换密钥就意味着一次全量数据迁移还得停机。第三层把加解密封装在一个模块里业务代码永远碰不到createCipheriv。这个约定的价值在于将来要换算法、换密钥来源、加监控埋点都只需要改一个文件。我见过最糟糕的情况是加密逻辑散落在十几个文件里有的用 CBC 有的用 GCM有的密钥从环境变量读有的硬编码最后没人敢动。如果你用的是云上的密钥管理服务还能拿到一个额外好处加解密操作本身会留下审计日志谁在什么时候调用了哪把密钥都有记录。对于合规要求比较严的行业这个日志的价值不比加密本身低。5.2 跨语言互通加密能跑通不代表对方能解开这是最让人抓狂的一类问题Node 这边加密成功Java 那边解密报错两边的开发各执一词都觉得自己没问题。根据我的排查经验跨语言对不上的原因八成集中在这几个点上。第一个是 IV 和 Tag 在报文里的位置和顺序。Node 习惯把 tag 放在密文后面很多示例代码就是这么写的Java 的Cipher默认把 tag 附在密文末尾Python 的 pycryptodome 则需要你单独取出。三边一旦约定不一致就会解密失败。统一约定一个明确的打包格式写成文档发给对方比来回猜测高效得多。第二个是 RSA OAEP 的 MGF1 哈希。Node 里oaepHash: sha256会把 OAEP 摘要和 MGF1 摘要都设成 SHA-256。而 Java 里写RSA/ECB/OAEPWithSHA-256AndMGF1Padding某些提供者的 MGF1 默认仍然用 SHA-1结果就是一边加密另一边解不开。Java 侧需要用OAEPParameterSpec显式把 MGF1 也指定为 SHA-256 才能对齐。这个坑我踩过一次排查了半天最后是靠对比两边的报错栈才定位到。第三个是 CBC 的填充命名。Node 的aes-256-cbc默认使用 PKCS#7 填充Java 里叫PKCS5PaddingPython 里叫pad。名字不同实际行为是一样的但文档表述不一致经常误导人以为需要额外处理。第四个是 HMAC 的输入形式。Node 的update接受 BufferJava 的Mac接受byte[]。如果上游把待签名的内容做了一次 hex 编码再传过去而下游是对原始字节做签名结果自然对不上。签名前先约定清楚签的是原始字节还是编码后的字符串。把这几条做成一张对照表团队里谁接入新语言都能直接查能力Node 写法其他语言对应高频不一致点AES-256-GCMaes-256-gcmJavaAES/GCM/NoPadding、PythonAES.MODE_GCMtag 拼接位置、IV 长度AES-256-CBCaes-256-cbcJavaAES/CBC/PKCS5Padding填充名称、IV 长度 16 字节RSA-OAEPoaepHash: sha256JavaOAEPParameterSpecMGF1 默认哈希不同RSA 签名RSA_PKCS1_PSS_PADDINGJavaRSASSA-PSSsaltLength 取值PBKDF2pbkdf2SyncPythonhashlib.pbkdf2_hmac迭代次数、salt 编码HMACcreateHmacJavaMac.getInstance输入是原始字节还是编码字符串5.3 大文件与并发什么时候该换成流式接口处理几个 G 的文件时createCipheriv加一次性update会把整个文件读进内存这个前面已经说过了要用流const fs require(fs); const crypto require(crypto); const { pipeline } require(stream/promises); async function encryptFile(src, dest, key) { const iv crypto.randomBytes(12); const cipher crypto.createCipheriv(aes-256-gcm, key, iv); await pipeline( fs.createReadStream(src), cipher, fs.createWriteStream(dest) ); return { iv: iv.toString(hex), tag: cipher.getAuthTag().toString(hex) }; }但这里有个 GCM 特有的问题必须提醒流式解密时authTag 只有在整条流读完才能验证。也就是说如果你边解密边把明文写出去那么在验证失败之前可能已经写了几百 MB 的不可信数据。对于安全要求高的场景稳妥做法是把密文完整解密到临时文件并验证通过后再改名或者改用分块加密每块独立生成 IV 和 tag逐块验证。代价是报文体积会略大但流式场景下更安全。另一个常被忽略的是并发下的性能表现。加密本身是 CPU 密集型操作Node 的主线程只有一条大量同步加密会拖垮整个服务的响应时间。我的做法是把批量加解密任务丢到worker_threads里跑主线程只负责调度和 IO。至于createCipheriv本身没有异步版本这是因为它单次调用的开销相对可控真正的耗时来自数据量本身用工作线程分担才是对症下药。5.4 上线前我会过一遍的自检清单最后把自己每次上线前会确认的几条列出来都是吃过亏之后加上的。密钥是不是从配置中心或环境变量来的仓库里搜不到任何硬编码的密钥字符串。每个加密操作生成的 IV 是不是crypto.randomBytes有没有哪个分支偷懒用了固定值。authTag 是不是被完整地保存或传输了长度是不是 16 字节。解密失败时的异常是不是被正确捕获了有没有直接把异常堆栈返回给前端。存口令用的哈希参数是不是记录在数据里了能不能支持将来调参。有没有对解密出来的数据做类型和长度校验防止解密成功但内容异常的情况。跨语言接口有没有一份双方确认过的格式文档包含字段顺序、编码方式、填充方案。我个人的体会是加解密这件事的难点分布得很不平均真正花在算法原理上的时间不到两成剩下八成都在密钥怎么管、格式怎么约定、异常怎么处理、性能怎么扛这些看起来不那么密码学的地方。把这几件事想明白了crypto 模块其实就那么几个 API剩下的都是工程功夫。