feat: 添加命令行接口与文档,改进错误处理

- 使用 argparse 提供 encrypt/decrypt 子命令,支持交互式密码与分卷大小解析
- 增加输入目录检查、密码错误提示和分卷识别容错
- 添加 .gitignore、LICENSE 和 README.md
- 将 CFB 模式迁移至 decrepit 模块并提取加密参数常量
这个提交包含在:
2026-08-20 16:16:45 +08:00
父节点 b0779c5b07
当前提交 9f00a2d36d
共修改 5 个文件,包含 235 行新增和 36 行删除
+96
查看文件
@@ -0,0 +1,96 @@
# File Encrypt
一个基于密码的命令行文件加密工具,使用 [`cryptography`](https://pypi.org/project/cryptography/) 库实现。对目录内文件执行 **压缩 → 加密 → 分卷存储**,并可完整还原。
## 功能特性
- **密钥派生**:PBKDF2-HMAC(SHA256)从密码派生 32 字节 AES 密钥,随机 salt,迭代 100,000 次,抵御暴力破解。
- **AES 加密**:AES-256-CFB 模式,每个文件使用随机 IV(初始化向量)。
- **压缩**:加密前用 `zlib` 压缩,减小体积。
- **分卷存储**:加密后数据超过分卷大小时自动切分为多个 `.partN` 文件;否则保存为单个 `.enc` 文件。
- **批量处理**:递归加密/解密整个目录。
- **命令行友好**:密码通过参数或交互式输入,绝不写入源码;分卷大小支持 `KB/MB/GB` 后缀。
## 工作原理
**加密**:读文件 → `zlib` 压缩 → 随机 salt + PBKDF2 派生密钥 → 随机 IV + AES-CFB 加密 → 按 `volume_size` 分卷(salt 写入首个分卷)或存为单个 `.enc`(`salt + 密文`)。
**解密**:读取目录下所有分卷(或单个 `.enc`)拼接 → 取 salt 派生密钥 → AES 解密 → `zlib` 解压 → 还原原文件。
参数常量(`main.py` 顶部):
| 常量 | 默认值 | 说明 |
| --- | --- | --- |
| `SALT_SIZE` | 16 | salt 字节数 |
| `IV_SIZE` | 16 | IV 字节数 |
| `KEY_SIZE` | 32 | AES 密钥长度(256 位) |
| `PBKDF2_ITERATIONS` | 100000 | 密钥派生迭代次数 |
## 环境要求
- Python 3.7+
- `cryptography` 库
## 安装
```bash
pip install -r requirements.txt
```
## 使用方法
```bash
# 加密:将 ./data 加密输出到 ./encrypted
python main.py encrypt ./data ./encrypted -p your_password -v 10MB
# 解密:从 ./encrypted 还原到 ./decrypted
python main.py decrypt ./encrypted ./decrypted -p your_password
# 省略 -p 时交互式输入密码(推荐,避免密码出现在命令行历史)
python main.py encrypt ./data ./encrypted
```
### 参数说明
| 参数 | 说明 |
| --- | --- |
| `action` | `encrypt` 或 `decrypt`(子命令) |
| `source` | 加密时为源目录;解密时为加密数据目录 |
| `output` | 加密时为输出目录;解密时为还原输出目录 |
| `-p, --password` | 密码。省略则交互式输入 |
| `-v, --volume-size` | 分卷大小,支持 `KB/MB/GB` 后缀,默认 `10MB` |
## 目录结构
```
.
├── main.py # 主程序(命令行入口)
├── requirements.txt # 依赖声明
├── LICENSE # MIT 许可证
├── .gitignore
├── data/ # 待加密的原始数据(示例)
├── encrypted/ # 加密输出(运行后生成,已被 git 忽略)
└── decrypted/ # 解密输出(运行后生成,已被 git 忽略)
```
加密输出结构:
```
encrypted/
└── <原文件名>/
├── <原文件名>.enc # 未分卷(数据小于分卷大小)
└── <原文件名>.part1 # 分卷:首个分卷含 salt
<原文件名>.part2 # 其余分卷
...
```
## 注意事项
- **密码是解密的唯一凭据,请务必妥善保管;忘记密码无法恢复数据。**
- 解密需提供与加密完全相同的密码,密码错误会提示 `Failed to decrypt ... Wrong password or corrupted data.`。
- salt 与 IV 已随密文写入文件,无需单独保存。
- 当前为单文件实现,适合学习与小批量文件加密;对超大文件采用全量读入内存,后续可改为流式处理。
## License
[MIT](./LICENSE)