架构:版本隔离与共享基础能力 状态:当前实现与架构约束;v2 协议和接口尚未确定
错误类型、模块间传递边界与 CLI info 的 expected 实现见 错误语义与试点评估。首批已接入格式校验和信息读取,保留原异常接口与本架构的版本分发、认证及事务规则。
本文定义 FileCrypt 程序内部架构。
verify_file 通过版本分发复用解密的前缀读取及完整认证,不提供最终输出路径。普通未压缩文件直接丢弃明文;压缩或目录载荷使用 IO 层不可提交的受限临时文件,认证成功后才解压、校验目录索引。目录协议校验由 validate_directory_payload 与恢复流程共用,目标文件系统的名称限制仅在实际恢复时应用。
临时模式沿用输出事务的排他创建与权限规则,在系统临时目录暂存数据。Windows 使用关闭即删除,POSIX 创建后立即移除名称并保留句柄;临时模式禁止 commit()。既有解密仍通过最终输出事务提交结果。
rekey_file 接收旧密码、新密码及 RekeyOptions,通过版本分发执行流式换密。v1 保留算法、压缩状态、文件类型、目录索引和 KDF 参数,重新生成 Salt 与 Nonce;旧密文解密后直接通过安全内存块送入新加密器,不暂存解密载荷。旧文件完整认证通过后才能完成新标签;随后从同一受控临时文件句柄回读新密文,检查新认证、完整解压及目录结构,全部通过后才提交。
换密回读的载荷检查只用于本流程生成、对应旧内容已经完成认证的受控密文,不能用于放宽普通外部文件的认证顺序。压缩输出直接丢弃;目录仅缓存受限索引并累计归档长度,再检查索引、树及数据范围。另存沿用无覆盖事务;显式替换由平台层单独处理文件身份、临时输出与替换提交,不采用先删除原文件再移动的退路。
替换使用新文件的受限权限,不继承旧文件的 ACL 或其他元数据;其他硬链接仍引用旧对象。源路径及祖先链接被拒绝,提交前复核源快照;复核和替换不构成跨平台比较交换,不承诺排除全部并发修改。POSIX 替换完成后若目录 fsync 失败,应保留已发布状态并明确报告持久化未确认,不能伪称原文件仍未变化。
内部共用的辅助类型、工具函数与文件统一放在 src/utils/,例如资源所有权封装和小端整数编解码。按职责拆分文件,平台相关工具保持条件编译隔离,不引入 Format 对 Windows 或 IO 的依赖,也不作为公共 API 暴露。
src/utils/little_endian.hpp 集中固定宽度无符号整数的字节读写;Header、Metadata 与目录各自保留字段长度校验、错误诊断和游标推进,工具只接收已经确认有效的字段范围。可变长名称编码保持独立。
src/utils/win32_resource.hpp 提供安全描述符的独占指针与文件句柄所有者。平台创建代码通过 out_ptr 接收描述符,Source 在打开后立即接管句柄,验证后再转交祖先容器;成员析构顺序保证先关闭源文件、再释放祖先句柄。输出事务的显式关闭、提交检查和权限策略仍由平台实现负责。
src/utils/win32_directory_move.hpp 提供 Windows 目录无覆盖移动与有限重试,调用方在每次尝试前检查源对象身份;格式层不依赖此工具。
┌───────────────┐
│ CLI │
└───────┬───────┘
│
▼
┌──────────────────┐
│ Application │
│ │
│ Encrypt / Decrypt│
│ Inspect │
└───────┬──────────┘
│
┌─────────────────┼─────────────────┬──────────────────┐
▼ ▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─────────────┐
│ IO │ │ Format │ │ Crypto │ │ Compression │
└──────────┘ └──────────┘ └────┬─────┘ └──────┬──────┘
▼ ▼
Botan Zstd
核心原则:
- Application 负责业务流程编排。
- Format 负责 FileCrypt 文件格式。
- Crypto 负责密码学操作。
- Compression 负责流式压缩与受限解压。
- IO 负责文件读写与定位。
- Backend 负责调用具体第三方密码学库。
Format 不实现密码学。
Crypto 不理解 .fcry 文件格式。
IO 不理解加密逻辑。
include/filecrypt/
app/operations.hpp 公共操作与展示结果
format/detect.hpp 六字节版本识别
format/v1/ v1 Header、Metadata、Registry
io/file.hpp 共享文件操作
src/
main.cpp 平台程序入口
cli/ 参数、命令与展示
app/operations.cpp 公共操作与集中版本选择
app/v1/operations.cpp v1 信息读取与样本流程
app/v1/crypt.cpp v1 加解密、验证与换密
app/v1/directory.cpp v1 目录扫描与恢复
format/detect.cpp
format/v1/
io/
platform/
tests/
format/detect_test.cpp
format/v1/
cli/
Application 读取 FCRY + uint16 Version 后分发,不能先把未知版本按 v1 Header 解析。
format::detect_version 只检查前缀长度和 Magic,返回小端版本值,包括当前不支持的值。
它不维护程序支持的版本列表,不检查六字节以后的布局,也不执行认证。
src/app/operations.cpp 内部的 operations_for_version 集中维护版本与 VersionOperations
操作集合的映射,当前只注册 v1。info、verify、decrypt、rekey 根据识别值选择实现;
encrypt、sample 根据选项中的目标版本调用同一选择函数。不支持的版本统一抛出
FormatError(unsupported_format),不降级,也不创建输出;创建操作在检查输入路径前就完成版本选择。
当前注册项包含全部六个操作,不引入插件注册或未来版本的能力体系。
前缀读取与流交接仍由各公共操作完成:信息读取、验证和解密在同一 ifstream 上恢复到起点,
换密通过 SourceFile 读取并由 ReaderStreamBuffer 重放前缀,保留源句柄保护。
v1 操作接收从文件起点读取的流;v1 的 validate_context 继续独立检查版本必须为 1。
该检查属于 v1 格式契约,不是全程序的版本支持列表。
识别成功、格式结构合法、完整认证成功、载荷检查成功和输出发布是不同阶段。
识别结果只用于路由;info 保持 authenticated == false,has_payload 只表示存在后续字节。
v1 的字段布局、Registry 和 AAD 实现属于 filecrypt::format::v1;未来版本独立新增模块,
不复用 v1 的裸协议编号或强制继承 v1 解析对象。当前不创建 v2 空目录。
公开 FileInfo 只包含展示信息,不暴露 Header、Metadata 或协议偏移。
format/v1/aad.hpp 提供两种 build_aad 入口:创建时序列化逻辑对象,
读取时校验原始 Header 与完整 Metadata 后直接拼接原始字节。
结果固定为 Header + Metadata[0 : TagOffset],Padding 只包含一次,Tag 不参与。
对象入口允许 Tag 占位,真实 Tag 写回后 AAD 不变;原始 Header 输入必须恰好 32 bytes。
SampleOptions 和 EncryptOptions 显式携带创建版本,默认 v1;rekey 保持源文件版本,
不会随默认创建版本变化而升级格式。
CLI 的文件操作通过 Application;密码输入等终端能力由 CLI 调用对应模块。
Application 调用 Format、Crypto、Compression 和 IO;这些基础模块不依赖 v1 应用实现,Format、IO 彼此独立。
Crypto 与 Compression 提供不依赖文件协议编号的基础能力,版本流程负责转换与编排。 临时输出和清理由 IO 提供,允许提交的时机由版本流程决定;当前已实现 v1 可选压缩的文件及目录加解密。
当前 Crypto 内存能力已位于 include/filecrypt/crypto/crypto.hpp 与 src/crypto/botan/,
由独立 FileCrypt::Crypto 库提供,依赖 Botan 而不依赖 Format、IO 或 Application。
算法枚举表达密码操作,不等于文件协议 ID。密钥派生显式接收参数和调用者资源策略,
当前提供 Argon2id 1.3 的 32 字节输出;安全容器基于 Botan 的安全分配器。
CipherContext 的实现通过私有对象隔离 Botan AEAD 模式,消息大小计数在处理输入前检查,
内部只缓存不足一个更新粒度的尾部。增量明文未经最终认证;高层内存 decrypt
暂存明文,认证成功才返回,认证失败统一为 AuthenticationError。
最终认证或处理失败后清理底层状态,拒绝任何再次使用。
src/app/v1/crypt.cpp 负责文件及目录载荷读写:加密生成随机 Salt/Nonce,
构造 Header、Metadata 和 AAD,以 64 KiB 安全缓冲区流式处理,最后写回真实 Tag。
解密保留原始 Header 与 Metadata 的认证字节,转换 v1 参数给 Crypto,
未认证明文只写入 io::OutputTransaction,finish 成功后才提交。
启用压缩时,独立 FileCrypt::Compression 层在加密之前输出 Zstandard 帧,
AEAD 计数压缩后的消息长度。压缩解密先认证临时载荷,再通过同一受控 IO 句柄回读并受限解压到第二个输出事务,
完整解压成功后才提交;中间事务始终不发布。窗口和累计输出上限属于运行策略,见 压缩实现。
目录模式由 src/app/v1/directory.cpp 扫描并流式提供 Index + File Data;Format 的 directory.cpp 负责独立编解码、UTF-8 单组件名称、树与连续数据校验。SourceFile 不跟随源链接并检查快照;DirectoryTransaction 提供受限暂存树和原子无覆盖提交。恢复流程先完整认证,按需解压,再校验 Index 和实际载荷长度、执行平台名称检查,全部恢复成功后发布。版本无关运行上限位于 directory::Limits,见 目录实现。
输出事务在目标同目录排他创建临时文件,POSIX 权限为 0600,Windows 使用只允许 所有者和 SYSTEM 的受保护 DACL。写入、定位、刷新与不覆盖目标的提交由平台层完成, 所有失败路径自动清理临时输出;默认提交竞态不允许替换已有路径。换密的显式替换是独立流程,仅在完整认证与载荷检查通过后提交。 CLI 终端密码输入关闭回显,Windows 终端输入转换为 UTF-8,密码缓冲区使用安全容器。 加密确认密码,解密单次输入,换密依次读取旧密码、新密码及新密码确认,管道输入按行读取;最终目标参数策略仍属于运行配置。
CLI 是最外层入口。
CLI 完整命令和选项不带横线,简写带单横线;encrypt/-e、decrypt/-d、info/-i、
help/-h、rekey/-r 等价,算法通过 algorithm/-a 选择。加解密的输入、输出路径固定为命令后的
前两个参数,其余参数才按选项解析,避免路径与选项同名时产生歧义。
CLI 将 aes、xchacha 等名称转换为应用层选项,重复或冲突选项在读取密码前拒绝。
换密另存同样使用两个固定路径;出现 --replace 时只接受输入路径及资源选项。CLI 在读取密码前检查输入文件及另存目标,应用与平台层仍必须执行正式检查,不能依赖 CLI 预检查消除路径竞争。
加密输出路径和解密输入路径没有扩展名时,CLI 补上 .fcry,已有扩展名保留。
v1 应用层的 file_type.cpp 根据文件名选择登记扩展名,无后缀才使用 512-byte 有界 magic 检测,检测后恢复同一输入流位置;Format Registry 只提供编号映射。
CLI 解密请求恢复扩展名,v1 流程从同一次读取的 Header 计算实际目标,认证及解压成功后才提交。公共 decrypt_file 返回实际输出路径,默认保持调用者提供的路径;restore_extension 参数为 true 时启用无后缀路径补全,CLI 据返回值显示结果。
Windows CLI 使用 wmain 接收原生 UTF-16 参数,严格转换为 UTF-8 后统一解析,路径由 UTF-8 显式构造;
参数转换通过 string::resize_and_overwrite 填充普通字符串,回调不抛异常,转换失败在回调结束后报告;密码仍使用安全容器。
MinGW 链接时启用 -municode。真实控制台输出临时切换为 UTF-8 代码页,刷新后恢复原值;重定向输出保持 UTF-8 字节。
主要职责:
解析命令
解析参数
读取用户选项
调用 Application
显示结果
CLI 不负责:
AES
KDF
Header
Metadata
Archive
文件加密流程
Application 是业务流程控制层。
主要功能:
Encrypt
Decrypt
Inspect
Verify
Rekey
Sample
Application 负责协调:
IO
Format
Crypto
Compression
并根据输入决定 Plaintext 是:
Single File
还是:
Directory Archive
Application 不实现具体密码算法,也不实现具体格式序列化。
Format 层负责:
- Fixed Header
- Metadata
- Metadata Layout
- Directory Index
- 二进制序列化与反序列化
Format 层不调用密码学 Backend。
Header 表示 FileCrypt v1 的固定 32-byte Header:
Magic
Version
Flags
Algorithm
File Type
Metadata Length
Reserved
Header 类型表示逻辑字段;具体二进制布局由显式序列化器实现。
禁止依赖 C++ struct 的内存布局直接写文件。
format::v1::deserialize 校验输入长度和 Magic 后还原字段;版本、Flags、Reserved 和
容器类型等语义由 Metadata 的 validate_context 校验。单独还原 Header 不表示格式或认证通过。
Metadata 根据当前容器类型和 Header Flags 变化。
Flags.Bit14 是压缩状态的唯一来源:
Bit 14 = 0
→ 不压缩
→ Metadata 不存在 Compression ID / Parameters Length / Parameters
Bit 14 = 1
→ 压缩
→ Metadata 必须存在 Compression ID / Parameters Length / Parameters
未压缩:
KDF ID
KDF Parameters
Salt
Nonce
Padding
Authentication Tag
压缩:
Compression ID
Compression Parameters Length
Compression Parameters
KDF ID
KDF Parameters
Salt
Nonce
Padding
Authentication Tag
未压缩:
Index Length
KDF ID
KDF Parameters
Salt
Nonce
Padding
Authentication Tag
压缩:
Index Length
Compression ID
Compression Parameters Length
Compression Parameters
KDF ID
KDF Parameters
Salt
Nonce
Padding
Authentication Tag
因此 Metadata 不是一个对所有容器完全固定的 C++ struct。
MetadataLayout 的职责是:
根据当前 FileCrypt Version、Flags、KDF 和 Algorithm,计算 Metadata 的布局与长度;当
Flags.Bit14 = 1时,同时使用 Compression Definition。
其输入至少包括:
Version
Flags
KDF Definition
Algorithm Definition
Compression Definition(仅当 Flags.Bit14 = 1)
其中 Flags.Bit15 决定是否存在 Directory-specific Metadata(Index Length),Flags.Bit14 决定是否存在 Compression Metadata。
逻辑关系:
Version
Container Type
Compression
KDF ID
Algorithm ID
↓
Registries
↓
MetadataLayout
MetadataLayout 负责计算:
Compression Parameters Size
Compression Parameters Length Size(2 bytes,仅压缩时)
KDF Parameters Size
Salt Size
Nonce Size
Tag Size
Padding Size
Metadata Size
载荷偏移由调用方按 Header 大小和 Metadata 长度确定,不是 MetadataLayout 的成员:
MetadataSize = Metadata Fields + Padding + Authentication Tag
EncryptedRawOffset = 32 + MetadataSize
MetadataLayout 不负责:
保存 Metadata 内容
读取文件
写文件
执行 KDF
执行加密
Metadata 对象保存实际 Metadata 数据,例如:
Index Length(仅 Directory)
Compression ID / Parameters Length / Parameters(仅 Flags.Bit14 = 1)
KDF ID
KDF Parameters
Salt
Nonce
Authentication Tag
其中 Compression 状态本身不在 Metadata 中重复保存。是否存在 Compression 字段完全由 Header.Flags.Bit14 决定。
其中 Directory-specific 的 Index Length 由 Container Type 决定是否存在。
此处表示写入职责,实际入口是 format::v1::serialize_metadata,没有单独的 MetadataWriter 类。它负责:
按 MetadataLayout 将 Metadata 对象序列化为 FileCrypt Metadata。
包括:
Index Length(仅 Directory)
Compression ID / Parameters Length / Parameters(仅 Flags.Bit14 = 1)
KDF ID
KDF Parameters
Salt
Nonce
Zero Padding
Authentication Tag
实际存在的字段取决于当前 Container Type 和 Compression 状态。
Padding 由 serialize_metadata 最终生成。
此处表示读取职责,实际入口是 format::v1::deserialize_metadata,没有单独的 MetadataReader 类。
它首先根据 Header 中已经可用的信息确定外层布局:
Version
Flags
Algorithm
Metadata Length
随后按照 v1 固定字段顺序读取 Metadata 中的 KDF ID,以及在 Flags.Bit14 = 1 时读取 Compression ID,并查询对应 Registry 解析后续参数。
KDF Definition 和 Compression Definition 不作为“预先已知”的输入;它们由 Metadata 中各自的 ID 在解析过程中确定。
它只负责格式解析,不负责:
KDF
解密
Compression
Authentication
Directory Archive 的明文内容由 Directory Format 负责解释:
Entry
├── ID
├── Parent ID
├── Type
├── Data Offset
├── Data Length
├── Name Length
└── Name
Index 的结束由 Metadata 中的 Index Length 决定。
Directory Format 不增加第二个 Magic、Version 或独立 Archive Header。
内部 validate_index_sizes 在共用校验中分别累计 Index 编码长度和 File Data 总长度。
公开 validate_index 继续返回 File Data 总长度;serialize_index 仅按 Index 编码长度预留缓冲区,
文件内容大小不参与 Index 缓冲区的容量申请。
Algorithm Registry 建立:
Algorithm ID
↓
Algorithm Definition
Algorithm Definition 提供至少:
Key Size
Nonce Size
Tag Size
Max Message Size
Algorithm Registry 可以同时包含多个 AEAD 算法,例如 AES-GCM 与 XChaCha20-Poly1305。它们是并列的可选实现,并非只能保留一种。每个 .fcry 文件通过 Header 中的 Algorithm ID 选择一个具体算法。
MetadataLayout 使用协议定义计算布局;Application 的版本实现把协议编号转换为 Crypto 算法后创建 CipherContext。 Registry 不保存 Botan 对象或密码实现。
KDF Registry 建立:
KDF ID
↓
KDF Definition
KDF Definition 提供至少:
KDF Parameters Size
Salt Size
MetadataLayout 使用 KDF Registry 计算布局;Application 的版本实现转换协议参数后调用 Crypto。 Registry 不保存 KDF 实现。
Derived Key Size 从 Algorithm Definition 的 Key Size 得到,不作为 KDF 独立固定值,也不单独写入 Metadata。v1 的编号和字段长度统一以 REGISTRY_V1.md 为准。
Compression Registry 建立:
Compression ID
↓
Compression Definition
Compression Definition 提供至少:
Compression Parameters Size
只有 Flags.Bit14 = 1 时才查询 Compression Registry。
Registry 不保存压缩实现;版本流程负责调用独立 Compression 层。
Header 的 Flags.Bit14 只表示“是否压缩”;具体 Compression ID 和 Parameters 位于 Metadata。Header 不重复保存具体压缩算法信息。
当 Flags.Bit14 = 0 时,Metadata 中不得出现 Compression 字段,也不查询 Compression Registry。
CipherContext 负责流式 AEAD 加密/解密。
模型:
update()
update()
update()
...
finish()
加密:
Plaintext
↓
update()
↓
Ciphertext
最终:
finish()
↓
Authentication Tag
finish() 返回剩余输出和 Tag;解密时使用传入的 Tag 完成认证,成功结果不返回新 Tag。
CipherContext 不直接:
写文件
修改 Metadata
Seek
写 Header
Application 负责把返回的 Tag 写入 Metadata 对象。
启用压缩时,Application 将 Plaintext Stream 依次经过:
Plaintext
↓
Compression
↓
CipherContext
↓
Ciphertext
解密时反向:
Ciphertext
↓
CipherContext
↓
受控临时载荷 + Tag 认证
↓
Decompression
↓
Plaintext
Compression 层不理解 .fcry 文件格式。
IO 层提供文件与目录能力,包括:
read()
write()
seek()
size()
源对象检查与快照复核
受限临时文件与目录
无覆盖提交与显式替换
IO 层不知道:
FCRY
AES
KDF
Metadata
AAD
Directory Index
加密开始前,可以确定除 Authentication Tag 值之外的全部文件结构信息。
流程:
用户选项
↓
Application 根据目标版本选择创建实现
↓
读取输入类型
↓
确定 Container Type / Compression State
↓
Algorithm Registry
↓
KDF Registry
↓
Compression Registry(仅当 Flags.Bit14 = 1)
↓
生成 KDF Parameters
↓
生成 Salt
↓
生成 Nonce
↓
MetadataLayout
↓
计算 Metadata Length
↓
计算 EncryptedRawOffset
↓
构造 Header
↓
构造 Metadata(Tag 尚未知)
↓
构造 AAD
↓
写入 Header 与带占位 Tag 的 Metadata
↓
Plaintext
↓
Compression(如果启用)
↓
CipherContext::update()
↓
写 Ciphertext
↓
CipherContext::finish()
↓
得到 Authentication Tag
↓
写入 Metadata 对象
↓
Seek 到 Header 末尾
↓
回写带真实 Tag 的 Metadata
↓
Commit
读取六字节识别前缀
↓
Application 选择受支持版本实现,向其提供从起点读取的输入
↓
读取 v1 Header
↓
验证 Magic / Version / Flags
↓
确定 Container Type / Compression State
↓
查询 Algorithm Registry
↓
读取 Metadata 中用于识别布局的固定 ID 字段
↓
读取 KDF ID / Compression ID(若存在)
↓
查询 KDF / Compression Registry
↓
MetadataLayout
↓
按 Layout 解析完整 Metadata
↓
从原始 Header 与 Metadata 字节构造 AAD
↓
Password → KDF → Key
↓
输入当前位置已在载荷起点
↓
CipherContext
↓
受控临时载荷 + Tag 认证
↓
Decompression(如果启用)
↓
Single File / Directory Archive
认证失败时不得提交最终输出文件。
info 命令无需执行解密。
流程:
.fcry
↓
六字节识别前缀
↓
Application 选择受支持版本实现
↓
Header
↓
Version / Flags
↓
Container Type
↓
Compression
↓
Registry
↓
Metadata
↓
显示信息
结构样本可以只有 Header 与 Metadata;信息读取不会把存在载荷或格式解析成功解释为认证成功。
最终输出使用临时文件:
.filecrypt-随机后缀.tmp
成功完成加密并写回 Header / Metadata 后,才提交为:
output.fcry
解密同样在认证和输出完成后 Commit。
临时文件机制属于 Application / IO 层,不属于文件格式。
CLI
│
▼
Application
├── Format(版本识别与各版本格式)
├── Crypto → Botan
├── Compression → Zstd
└── IO → 平台文件系统接口
Application 是主要编排者。
避免出现:
Crypto → Format
Format → Crypto
IO → Crypto
IO → Format
Registry
↓
MetadataLayout
↓
Application 规划文件布局
↓
Compression(可选)
↓
Crypto 产生 Ciphertext
↓
Application 得到 Tag
↓
Format 最终写入 Header + Metadata
FileCrypt 的程序架构必须保持:
Format 负责“文件怎么表示”,Crypto 负责“数据怎么加密”,Application 负责“这些步骤怎么串起来”。