Metadata-Version: 2.4
Name: axwvcrypt
Version: 0.1.1
Summary: A secure file encryption tool with ChaCha20, PBKDF2/Scrypt, streaming, and no logs.
Author-email: AXWV <axwv01@gmail.com>
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pycryptodome>=3.23.0
Dynamic: license-file


# axwvcrypt — 安全文件加密工具

[![PyPI version](https://badge.fury.io/py/axwvcrypt.svg)](https://pypi.org/project/axwvcrypt/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

`axwvcrypt` 是一个用 Python 编写的文件加密/解密命令行工具，基于 **ChaCha20 流加密**，支持 **PBKDF2** 和 **Scrypt** 密钥派生，具有**流式分块处理**（支持超大文件）、**可选压缩**、**文件伪装**和**双因子认证**（密钥文件）功能。

**设计目标**：  
- ✅ **完全静默**：成功时无任何输出，错误仅返回非零退出码，不产生日志。  
- ✅ **错误密码不报错**：仅输出乱码文件，不泄露任何信息。  
- ✅ **高安全性**：使用现代密码学原语，抗暴力破解。  
- ✅ **易于使用**：命令简洁，自动生成强密码，自动识别加密参数。

---

## 功能特性

- **加密算法**：ChaCha20 流加密（无填充，安全高效，Google/Cloudflare 广泛使用）。  
- **密钥派生函数**：
  - **PBKDF2**（默认，200 万次迭代，抗暴力破解）。  
  - **Scrypt**（内存硬函数，抗 GPU/ASIC 攻击，通过 `--kdf scrypt` 启用）。  
- **流式处理**：1MB 分块加密/解密，内存占用恒定，支持任意大小文件。  
- **可选压缩**：加密前 zlib 压缩（`--compress`），适合文本或可压缩数据。  
- **文件伪装**：在密文头部插入 JPG/PNG/ZIP 魔术字节（`--pretend`），使加密文件看起来像常见格式。  
- **双因子认证**：额外指定一个密钥文件（`--keyfile`），其哈希值与密码混合，需同时拥有才能正确解密。  
- **自动生成强密码**：未指定 `-s` 时，自动生成 24 位（可调）强随机密码（含大小写、数字、特殊符号），并打印到标准输出。  
- **完全静默**：成功无任何输出，错误仅返回非零退出码，不记录日志。  
- **错误密码行为**：解密时若密码错误，不会报错，而是生成一个乱码文件（长度与原始文件相同），不泄露任何信息。

---

## 安装

### 从 PyPI 安装（推荐）
```bash
pip install axwvcrypt
```

从源码安装

```bash
git clone https://github.com/AXWV/axwvcrypt.git
cd axwvcrypt
pip install .
```

---

使用方法

安装后，命令行执行 axcrt。

基本命令

```bash
# 加密（自动生成密码）
axcrt -e 文件.txt

# 加密（自定义密码）
axcrt -e 文件.txt -s "你的密码"

# 解密（必须提供密码）
axcrt -d 文件.aenc -s "你的密码"
```

高级选项

参数 说明
-e, --encrypt 加密模式（需指定输入文件）
-d, --decrypt 解密模式（需指定 .aenc 文件）
-s, --seed 密码（加密时可省略以自动生成）
--kdf {pbkdf2,scrypt} 密钥派生函数（默认 pbkdf2）
--keyfile FILE 双因子认证密钥文件路径
--pretend {jpg,png,zip} 伪装成图片或压缩包（在密文头部插入对应魔术字节）
--compress 启用压缩（加密前压缩，适合文本）
--generate-seed 仅生成随机密码，不加密文件
--seed-length N 随机密码长度（默认 24）
--help 显示帮助信息

示例

```bash
# 加密并伪装成 JPG
axcrt -e secret.txt --pretend jpg -s "mypass"

# 使用 Scrypt KDF 加密
axcrt -e data.bin --kdf scrypt -s "strongpass"

# 加密并启用压缩（适合文本）
axcrt -e document.txt --compress -s "pass"

# 双因子认证（需同时提供密钥文件）
axcrt -e important.pdf --keyfile key.bin -s "pass"

# 解密（自动识别加密时使用的 KDF 和压缩状态）
axcrt -d secret.aenc -s "mypass"

# 解密（如果加密时用了 keyfile，解密也必须提供）
axcrt -d important.aenc --keyfile key.bin -s "pass"
```

---

输出文件

· 加密后：生成与原文件同名的 .aenc 文件（例如 document.txt → document.aenc）。
· 解密后：生成与原 .aenc 文件同名的 .dec 文件（例如 document.aenc → document.aenc.dec）。
· 自动生成密码：加密时若未指定 -s，会打印一个 24 位随机密码到标准输出，请务必保存。

---

安全性说明

加密强度

· ChaCha20：流加密，密钥长度 256 位，无已知实际攻击，被广泛用于 TLS、WireGuard 等协议。
· PBKDF2：200 万次迭代，有效防御离线字典攻击。
· Scrypt：内存硬函数（N=2^20, r=8, p=1），约占用 128MB 内存，大幅增加 GPU/ASIC 暴力破解成本。

密钥管理

· 密钥完全由用户提供的 seed（和可选的 keyfile）派生，脚本不存储任何密钥或密码。
· 每次加密使用独立的随机盐（16 字节）和 nonce（12 字节），确保相同文件、相同密码产生不同密文。

错误处理

· 解密时密钥错误不会报错，而是生成乱码文件，避免攻击者通过错误信息判断密钥是否正确（防止 Oracle 攻击）。

无日志

· 脚本不创建任何日志文件，不向标准错误输出信息（仅在内部错误时退出码非零），最大限度减少信息泄漏。

---

开源许可证

本项目采用 MIT 许可证，详见 LICENSE 文件。
您可以自由使用、修改、分发，甚至用于商业项目，仅需保留原始版权声明。

---

贡献

欢迎提交 Issue 和 Pull Request。
请确保代码符合 PEP 8 风格，并添加必要的测试（如果有）。

---

作者

AXWV · axwv01@gmail.com

致谢

· pycryptodome 提供底层加密实现。
· 本工具受 Cryptography.io 和 Libsodium 设计启发。

---

常见问题

Q: 如果忘记密码，能否恢复文件？
A: 不能。密码是唯一解密凭证，请妥善保存。若密码丢失，无法恢复数据。

Q: 加密文件能否被破解？
A: 在合理密码强度（≥12 位随机字符）下，暴力破解在现有计算能力下不可行。请使用强密码。

Q: 是否支持文件夹加密？
A: 当前版本仅支持单文件。如需加密文件夹，可先打包为 tar/zip 再加密。

Q: 为什么错误密码解密不报错？
A: 这是设计选择，旨在防止攻击者通过错误信息区分密钥正确性（防止 Padding Oracle 等攻击），同时满足“无日志、不泄露”的需求。

---

Happy encrypting! 🔐
