Skip to content

Latest commit

 

History

History
59 lines (42 loc) · 3.59 KB

COMPRESSION.md

File metadata and controls

59 lines (42 loc) · 3.59 KB

Zstandard 压缩实现

当前支持可选压缩的普通文件和目录。目录模式将整个 Index + File Data 作为一个连续压缩载荷,认证、解压和目录结构校验完成后才发布恢复目录,见 目录实现。 CLI 使用 compress 或 -z 开启压缩,默认无压缩,也可显式写 no-compress。 解密自动读取压缩状态,不要求再次指定压缩选项。

层次与协议

FileCrypt::Compression 位于 include/filecrypt/compression/ 和 src/compression/zstd/, 只依赖 Zstandard,不理解文件路径、协议版本、Registry 编号或密码学。 Reader 回调填充给定缓冲区,返回读取长度,零表示结束;Writer 回调完整消费给定数据, 读取、写入或数据处理失败通过异常传播,应用层负责事务清理。

v1 应用层设置 Header 的 Bit 14,写入 Compression ID 0x0001 和长度为零的参数。 压缩等级、窗口、线程等实现策略不写入 Metadata;Header 与压缩 Metadata 仍包含在 AAD 中。 现有 v1 格式定义和 Registry 编号保持不变。

加密与解密

加密按“文件 → Zstandard → AEAD → 密文”流式处理,当前 CLI 压缩等级为 3, 创建一个不使用外部字典、带内容校验和的标准帧。 压缩层使用固定的 64 KiB 输入和输出缓冲区,退出时擦除这两个缓冲区。 AEAD 长度限制计数压缩结果,包含帧头与校验和,不能用压缩前文件大小提前拒绝。

压缩解密分两阶段:

  1. 将解密结果写入权限受限的临时文件,完整验证 AEAD Tag。
  2. 认证成功后通过原有独占句柄回读压缩内容,解压到另一个受限输出事务,完整解压成功才提交。

第一阶段的事务始终不提交,认证失败不会调用解压器;解压失败、资源超限或输出提交冲突时, 两个临时文件都自动清理。该方式需要保存压缩中间载荷和解压输出的临时磁盘空间。 无压缩解密仍沿用原来的单个输出事务。

解压接受标准 Zstandard 帧序列,包括拼接帧和标准跳过帧,不提供外部字典。 空载荷、截断帧、损坏的内容校验和和无效尾随数据均拒绝;合法的空内容帧可以还原空文件。

运行资源策略

策略 当前默认值 CLI
累计解压输出 16 GiB max-output-bytes N
解压窗口 64 MiB max-window-kib N

输出限制在写入输出回调之前检查,累计覆盖全部帧,不对每个帧重置。 窗口通过 Zstandard 解码参数在分配窗口之前限制,允许 1 KiB 到 1 GiB 的二次幂; 它不是整个进程内存上限,解码上下文和固定缓冲区仍占用额外内存。 CLI 输出上限为正的 64 位整数,库接口允许零,表示只接受空输出。

这些是可调整的运行策略,不是 v1 格式常数;当前默认值仍可通过跨平台实际使用评估。 它们只约束压缩载荷的解压。原有 KDF 资源限制及 AEAD 消息长度检查继续生效。

构建与测试

开发构建需要 Zstandard >= 1.5.2;Linux 发布从固定的 Zstandard 1.5.7 源码构建静态库并校验 SHA-256, 保持正式 Artifact 只有一个可执行文件。MSVC 通过 vcpkg 安装 zstd:x64-windows。

压缩单元测试覆盖与原生 Zstandard API 互操作、空文件、随机数据、分块边界、拼接与跳过帧、 截断与损坏、窗口和累计输出限制。文件与 CLI 测试覆盖两种算法的压缩往返、认证先于解压、 认证有效但压缩载荷畸形、资源超限、已有输出保护和临时文件清理。