零依赖Excel加密hucre如何用WebCrypto实现Agile密码保护【免费下载链接】hucreZero-dependency spreadsheet engine. Read write XLSX, CSV, ODS. Pure TypeScript, works everywhere.项目地址: https://gitcode.com/gh_mirrors/hu/hucrehucre 是一个零依赖的电子表格引擎能读取和写入 XLSX、CSV、ODS 等格式全部用纯 TypeScript 编写。除了基础的读写能力它还有一个常被忽视的硬核功能——Excel 文件加密通过平台原生的 WebCrypto API 实现 ECMA-376Agile 密码保护Excel 2010 采用的加密方案在 Node、Deno、Bun、Cloudflare Workers 乃至浏览器里都能直接运行不需要引入任何密码学第三方库。什么是 Agile 加密当你用 Excel 给文件设置密码时从 2010 版本起Excel 默认使用的就是Agile 加密定义于 ECMA-376 标准细节由 [MS-OFFCRYPTO] 规范描述。它的核心配方是AES-256-CBC加密文件内容SHA-512哈希派生密钥默认迭代100,000 次称为 spin countHMAC-SHA512校验数据完整性防止密文被篡改整体打包进OLE2/CFB 复合二进制容器而不是普通的 ZIPhucre 对这一整套流程做了完整的加密与解密实现源码集中在 src/xlsx/crypto/ 目录下的两个文件文件职责src/xlsx/crypto/agile.tsAgile 密码学的全部逻辑密钥派生、AES-CBC 分段加解密、HMAC 校验src/xlsx/crypto/cfb.ts最小化的 OLE2/CFB 容器读写器加密与解密各一行 API对使用者来说Agile 加密被封装得非常轻——写文件时多传一个encryption选项读文件时多传一个password选项就完事了import { writeXlsx, readXlsx } from hucre // 写一个带密码保护的 XLSX const encrypted await writeXlsx({ sheets: [{ name: Secret, rows: [[pin, 1234]] }], encryption: { password: hunter2 }, }) // 带上密码读回来 const wb await readXlsx(encrypted, { password: hunter2 })这套选项在所有读取入口都生效read()会自动探测容器类型并透明解密readObjects()和streamXlsxRows()同样支持传password往返编辑路径saveXlsx(wb, { encryption: { password } })也走同一个加密器见 src/xlsx/roundtrip.ts。密钥是如何从密码中变出来的密码本身不能直接当密钥用。hucre 按 MS-OFFCRYPTO 规范实现了完整的派生链核心在 passwordChain加盐随机生成 16 字节的盐值与 UTF-16LE 编码的密码拼接后做首次 SHA-512迭代拉伸用 4 字节计数器反复哈希默认循环 100,000 次spinCount让暴力破解的成本线性放大——这就是为什么加密一个文件会有可感知的耗时派生多组块密钥从哈希链上再派生出 verifier 密钥、密钥加密密钥、数据密钥等各司其职随机密钥包裹真正的包密钥secretKey是随机生成的 32 字节用上面的派生密钥 AES-CBC 加密后存进EncryptionInfo元数据中。解密时则反过来用你输入的密码重走一遍派生链解出随机验证输入和它的哈希值两者对上才认为密码正确见 deriveSecretKey否则抛出DecryptionError。密文怎么存——分段 AES-CBC 完整性校验Excel 的文件体按4096 字节分段每段用独立的 IV 做 AES-CBC 加密IV 由盐值加段索引哈希而来见 encryptPackage。这里有个精巧的工程细节WebCrypto 的 AES-CBC总是强制 PKCS#7 填充而 OOXML 的分段是裸的块对齐数据。hucre 用两个经典技巧绕过它——解密时追加一个精心构造的密文块诱使 WebCrypto 把填充块剥掉加密时则丢弃尾部填充块代码开头的注释 agile.ts 解释得很清楚。此外hucre 还会验证dataIntegrity元素里的 HMAC解出 HMAC 密钥后对整条EncryptedPackage流计算 HMAC-SHA512不匹配就拒绝输出见 verifyDataIntegrity。这意味着密文哪怕被篡改一个字节也不会静默地给你一份损坏的数据。安全细节不只是能加解密几个容易被忽略的防线hucre 都做了DoS 防护spinCount来自不受信任的文件。恶意文件可以谎报一个天文数字的迭代次数把 CPU 钉死几分钟。hucre 设了上限 MAX_SPIN_COUNT 10,000,000Office 自己只用 10 万超上限直接拒绝解密零依赖所有密码原语直接调用crypto.subtle.digest、crypto.subtle.encrypt和crypto.getRandomValues见 WebCrypto 原语层没有任何 WASM 或纯 JS 的 AES 实现——这也是它能在 Cloudflare Workers 和浏览器里跑的原因清晰的错误分层忘了传密码抛 EncryptedFileError密码错误或数据损坏抛 DecryptionError两者语义分明方便你在 UI 里分别提示需要密码和密码不对兼容 Excel 默认参数加密默认使用 Excel 原生的 100,000 次迭代产出的文件可被 Excel 直接打开测试里也有专门的用例验证这个默认值下的端到端互通encryption.test.ts。验证加密文件到底长什么样从 test/encryption.test.ts 可以看到完整的行为契约加密输出是 OLE2 容器而非 ZIPisOle2Container(enc)断言为 true无密码读取 →EncryptedFileError错误密码 →DecryptionErroropenXlsxsaveXlsx可以换密码用第一个密码打开、用第二个密码重新保存旧密码随即失效CFB 容器读写器对小型流mini-stream和大型流都做了往返验证。小结hucre 把一套工业级的 Office 文件加密——OLE2 容器、AES-256-CBC 分段、SHA-512 密钥拉伸、HMAC 完整性校验——完整地装进了零依赖的 TypeScript 里全部密码运算借力平台自带的 WebCrypto。对使用者的最终体现却极简写时传一个password读时传一个password。如果你的项目需要给电子表格加上真正的密码保护又不想为此引入一堆二进制依赖src/xlsx/crypto/ 值得仔细读一读。【免费下载链接】hucreZero-dependency spreadsheet engine. Read write XLSX, CSV, ODS. Pure TypeScript, works everywhere.项目地址: https://gitcode.com/gh_mirrors/hu/hucre创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考