Skip to content

Latest commit

 

History

History
896 lines (685 loc) · 25.3 KB

ARCHITECTURE.md

File metadata and controls

896 lines (685 loc) · 25.3 KB

FileCrypt Architecture

架构:版本隔离与共享基础能力 状态:当前实现与架构约束;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 目录无覆盖移动与有限重试,调用方在每次尝试前检查源对象身份;格式层不依赖此工具。


1. 总体架构

                         ┌───────────────┐
                         │      CLI      │
                         └───────┬───────┘
                                 │
                                 ▼
                       ┌──────────────────┐
                       │   Application    │
                       │                  │
                       │ Encrypt / Decrypt│
                       │ Inspect          │
                       └───────┬──────────┘
                               │
             ┌─────────────────┼─────────────────┬──────────────────┐
             ▼                 ▼                 ▼                  ▼
       ┌──────────┐      ┌──────────┐      ┌──────────┐      ┌─────────────┐
       │   IO     │      │  Format  │      │  Crypto  │      │ Compression │
       └──────────┘      └──────────┘      └────┬─────┘      └──────┬──────┘
                                               ▼                    ▼
                                             Botan                 Zstd

核心原则:

  • Application 负责业务流程编排。
  • Format 负责 FileCrypt 文件格式。
  • Crypto 负责密码学操作。
  • Compression 负责流式压缩与受限解压。
  • IO 负责文件读写与定位。
  • Backend 负责调用具体第三方密码学库。

Format 不实现密码学。 Crypto 不理解 .fcry 文件格式。 IO 不理解加密逻辑。


2. 项目目录与版本边界

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,密码缓冲区使用安全容器。 加密确认密码,解密单次输入,换密依次读取旧密码、新密码及新密码确认,管道输入按行读取;最终目标参数策略仍属于运行配置。


3. CLI 层

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
文件加密流程

4. Application 层

Application 是业务流程控制层。

主要功能:

Encrypt
Decrypt
Inspect
Verify
Rekey
Sample

Application 负责协调:

IO
Format
Crypto
Compression

并根据输入决定 Plaintext 是:

Single File

还是:

Directory Archive

Application 不实现具体密码算法,也不实现具体格式序列化。


5. Format 层

Format 层负责:

  • Fixed Header
  • Metadata
  • Metadata Layout
  • Directory Index
  • 二进制序列化与反序列化

Format 层不调用密码学 Backend。


6. Header

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 不表示格式或认证通过。


7. Metadata

Metadata 根据当前容器类型和 Header Flags 变化。

Flags.Bit14 是压缩状态的唯一来源:

Bit 14 = 0
    → 不压缩
    → Metadata 不存在 Compression ID / Parameters Length / Parameters

Bit 14 = 1
    → 压缩
    → Metadata 必须存在 Compression ID / Parameters Length / Parameters

Single File

未压缩:

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

Directory Archive

未压缩:

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。


8. MetadataLayout

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
执行加密

9. Metadata

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 决定是否存在。


10. MetadataWriter

此处表示写入职责,实际入口是 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 最终生成。


11. MetadataReader

此处表示读取职责,实际入口是 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

12. Directory Format 层

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 缓冲区的容量申请。


13. Algorithm Registry

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 对象或密码实现。


14. KDF Registry

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 为准。


15. Compression Registry

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。


16. CipherContext

CipherContext 负责流式 AEAD 加密/解密。

模型:

update()
update()
update()
...
finish()

加密:

Plaintext
   ↓
update()
   ↓
Ciphertext

最终:

finish()
   ↓
Authentication Tag

finish() 返回剩余输出和 Tag;解密时使用传入的 Tag 完成认证,成功结果不返回新 Tag。

CipherContext 不直接:

写文件
修改 Metadata
Seek
写 Header

Application 负责把返回的 Tag 写入 Metadata 对象。


17. Compression Layer

启用压缩时,Application 将 Plaintext Stream 依次经过:

Plaintext
   ↓
Compression
   ↓
CipherContext
   ↓
Ciphertext

解密时反向:

Ciphertext
   ↓
CipherContext
   ↓
受控临时载荷 + Tag 认证
   ↓
Decompression
   ↓
Plaintext

Compression 层不理解 .fcry 文件格式。


18. IO 层

IO 层提供文件与目录能力,包括:

read()
write()
seek()
size()
源对象检查与快照复核
受限临时文件与目录
无覆盖提交与显式替换

IO 层不知道:

FCRY
AES
KDF
Metadata
AAD
Directory Index

19. Encrypt 流程

加密开始前,可以确定除 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

20. Decrypt 流程

读取六字节识别前缀
    ↓
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

认证失败时不得提交最终输出文件。


21. Inspect

info 命令无需执行解密。

流程:

.fcry
 ↓
六字节识别前缀
 ↓
Application 选择受支持版本实现
 ↓
Header
 ↓
Version / Flags
 ↓
Container Type
 ↓
Compression
 ↓
Registry
 ↓
Metadata
 ↓
显示信息

结构样本可以只有 Header 与 Metadata;信息读取不会把存在载荷或格式解析成功解释为认证成功。


22. 临时文件与 Commit

最终输出使用临时文件:

.filecrypt-随机后缀.tmp

成功完成加密并写回 Header / Metadata 后,才提交为:

output.fcry

解密同样在认证和输出完成后 Commit。

临时文件机制属于 Application / IO 层,不属于文件格式。


23. 核心依赖关系

CLI
 │
 ▼
Application
 ├── Format(版本识别与各版本格式)
 ├── Crypto → Botan
 ├── Compression → Zstd
 └── IO → 平台文件系统接口

Application 是主要编排者。

避免出现:

Crypto → Format
Format → Crypto
IO → Crypto
IO → Format

24. 核心原则

Registry
   ↓
MetadataLayout
   ↓
Application 规划文件布局
   ↓
Compression(可选)
   ↓
Crypto 产生 Ciphertext
   ↓
Application 得到 Tag
   ↓
Format 最终写入 Header + Metadata

FileCrypt 的程序架构必须保持:

Format 负责“文件怎么表示”,Crypto 负责“数据怎么加密”,Application 负责“这些步骤怎么串起来”。