Skip to content
fzgmaPublic

About

使用密码加密和恢复本地文件的跨平台 C++23 命令行工具。

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

28 Commits

Folders and files

Repository files navigation

FileCrypt

使用密码加密和恢复本地文件的跨平台 C++23 命令行工具。

FileCrypt 支持文件与目录加解密、可选 Zstandard 压缩、完整性验证、密码修改和随机密码生成。使用 Argon2id 派生密钥,并通过 AEAD 验证文件完整性。

面向 Windows 和 Linux,目前提供 CLI。下载:GitHub Releases。构建与发布验证进度见 TODO。

1. 功能

  • 文件与目录加解密:保存文件内容;目录模式还保存目录树与空目录。
  • 认证加密:支持 AES-256-GCM 和 XChaCha20-Poly1305,使用 Argon2id 派生密钥。
  • 可选压缩:使用 Zstandard 压缩,解密时自动识别。
  • 文件验证与密码修改:验证加密内容,或在认证通过后更换密码。
  • 随机密码生成:使用系统安全随机源生成密码。
  • 扩展名恢复与信息查看:支持登记的扩展名(包括部分复合后缀),无需密码查看公开文件信息。
  • 输出保护与 Unicode 路径:默认拒绝覆盖已有目标,支持中文、空格和 emoji 文件名。

2. 快速开始

Windows

下载 Windows 程序。可将 filecrypt-windows-x86_64.exe 重命名为 filecrypt.exe。

# 加密 photo.png,生成 backup.fcry
.\filecrypt -e photo.png backup

# 解密 backup.fcry,恢复为 restored.png
.\filecrypt -d backup restored

# 查看公开信息与帮助
.\filecrypt -i backup.fcry
.\filecrypt -h

Linux

下载 Linux 程序后:

mv filecrypt-linux-x86_64 filecrypt
chmod +x filecrypt

./filecrypt -e photo.png backup
./filecrypt -d backup restored
./filecrypt -h

Linux 发布目标为 x86-64、glibc 2.34+,暂不支持 Alpine/musl。

加密时需要输入并确认密码,解密时输入一次;终端密码输入隐藏回显。忘记密码将无法恢复文件,FileCrypt 无法重置或绕过密码。

3. 常用命令

命令 简写 用途
encrypt -e 加密文件或目录
decrypt -d 解密文件或恢复目录
info -i 查看公开信息,不验证文件真实性
verify -v 完整验证加密内容,不发布恢复文件
rekey -r 修改密码,另存或显式替换原文件
password -g 生成随机密码
help — 查看总览或指定命令帮助
-h — 查看总览
sample — 生成格式示例,不执行真实加密

详细用法使用 filecrypt help <完整命令名>,资源上限使用 filecrypt help limits;帮助目标不接受命令简写,-h 不接受参数。

算法与压缩

默认使用 AES-256-GCM,不压缩。

# 使用 XChaCha20-Poly1305
.\filecrypt -e input.txt backup -a xchacha

# 启用 Zstandard 压缩
.\filecrypt -e input.txt backup -z

解密时会自动读取算法和压缩状态。

目录加解密

输入为目录时自动使用目录布局:

.\filecrypt -e .\documents backup -z
.\filecrypt -d backup .\restored

restored 就是恢复后的根目录,不会额外套一层 documents。加密输出必须放在源目录之外。

验证与修改密码

# 完整验证
.\filecrypt verify backup.fcry

# 另存为新文件,保留原文件
.\filecrypt rekey backup.fcry backup-new.fcry

# 显式替换原文件
.\filecrypt rekey backup.fcry --replace

verify 会检查认证,并按文件类型检查压缩数据或目录结构;验证过程不生成最终恢复文件。rekey 需要依次输入旧密码、新密码并确认新密码。替换原文件不保证磁盘旧数据被安全擦除。

生成随机密码

.\filecrypt password
.\filecrypt -g length 24 charset readable

length 默认为 12,可设为 8–64;charset 可选 alnum、readable 或 symbols。密码只显示一次,请自行安全保存。

加解密命令的前两个参数固定为输入、输出路径,其后才解析选项。没有后缀的加密输出会自动补 .fcry;解密输出默认恢复文件中记录的扩展名,显式指定的后缀则原样保留。

4. 从源码构建

要求 CMake 3.24+、C++23 编译器、Botan 3 和 Zstandard 1.5.2+。Botan 必须与所用编译器工具链兼容;依赖安装在非默认位置时,可设置 CMAKE_PREFIX_PATH。

cmake -S . -B build
cmake --build build
ctest --test-dir build --output-on-failure

Visual Studio 等多配置生成器构建时增加 --config Release,测试时增加 -C Release。开发构建默认使用共享依赖库,运行时需确保相关库可被加载。

发布构建与平台验证流程见 Linux 发布政策 和 Windows MSVC 发布。

5. 限制与安全说明

  • 密码无法重置或绕过。 请安全保存密码。
  • 单文件不保存完整原始文件名,只记录已登记的扩展名;未登记类型记为 Unknown。目录名称与树结构保存在加密 Index 中。
  • File Type 位于公开 Header;info 无需密码,但不验证文件真实性。
  • v1 使用单条 AEAD 消息,载荷受所选算法的消息长度上限约束;超出限制时拒绝处理。
  • 目录仅支持普通文件和目录;不保存链接关系、时间戳或原始权限,也不支持恢复到已有目录并合并。
  • 首版拒绝符号链接、Windows junction/reparse point 和其他特殊对象。源目录在加密期间应保持不变。
  • 压缩解密和目录恢复可能需要额外临时磁盘空间,并受资源上限约束。
  • Windows 名称限制、文件系统大小写规则和路径长度限制可能导致跨平台恢复失败;不会自动改名。
  • magic 检测只提供文件类型提示,不校验完整内容;未识别的无后缀文件记为 Unknown。
  • 不接受命令行明文密码;管道密码输入需使用 UTF-8。

资源限制参数及默认值见 压缩实现 和 目录实现与运行策略。

6. 文档

格式与安全

压缩与目录

开发与发布

7. 开源协议

GNU General Public License v3.0

About

使用密码加密和恢复本地文件的跨平台 C++23 命令行工具。

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages