# FileGuardApp

**Repository Path**: Dulexe/file-guard-app

## Basic Information

- **Project Name**: FileGuardApp
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: LGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-26
- **Last Updated**: 2025-11-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FileGuard 文件加密工具 - 使用说明文档

## 📋 项目概述

**FileGuard** 是一个基于 .NET 10 开发的本地文件加密工具，使用先进的加密算法保护您的敏感文件。工具采用 AOT 编译，生成单个可执行文件，无需安装，开箱即用。

## 🛠️ 技术特性

### 加密算法
- **密钥派生**: Argon2id (抗 GPU/ASIC 攻击)
- **文件加密**: AES-256-GCM (认证加密)
- **密钥管理**: 会话式密钥派生

### 安全特性
- ✅ 前向保密 - 每次程序运行使用不同密钥
- ✅ 认证加密 - 防止数据篡改
- ✅ 安全内存管理 - 程序退出自动清理密钥
- ✅ 文件完整性验证

### 性能优化
- 🚀 AOT 原生编译 - 快速启动，单个可执行文件
- 📦 分块处理 - 支持超大文件加密
- 🔄 并行处理 - 多文件同时加密
- 💾 流式处理 - 低内存占用

## 📁 项目结构

```
FileGuard/
├── FileGuard.csproj          # 项目配置文件
├── Program.cs                # 主程序入口
├── Models/                   # 数据模型
│   ├── FileHeader.cs        # 加密文件头结构
│   └── EncryptionResult.cs  # 操作结果模型
├── Services/                 # 业务服务
│   ├── FileEncryptionService.cs    # 加密服务
│   ├── FileDecryptionService.cs    # 解密服务
│   ├── FileDiscoveryService.cs     # 文件发现服务
│   ├── PasswordService.cs          # 密码处理服务
│   └── SessionService.cs           # 会话管理服务
└── Utilities/
    └── CryptoUtils.cs       # 加密工具类
```

## 🔐 加密原理

### 加密流程
1. **会话初始化**
   - 程序启动生成随机盐值
   - 用户密码 + 盐值 → Argon2id → KEK (密钥加密密钥)

2. **文件加密**
   ```
   原文件 → 生成随机FEK → AES-GCM加密 → 加密文件内容
   FEK + KEK → AES-GCM加密 → 加密的FEK
   文件头(元数据) + 加密的FEK + 加密内容 → .newbit文件
   ```

3. **文件格式**
   ```
   [文件头] + [加密的文件内容]
   ┌─────────────────────────────────────────────┐
   │ 魔法数字 │ 版本 │ 文件名 │ 文件大小 │ 盐值 │  │
   │ 加密的FEK │ 认证标签 │ Nonce │ 加密内容块... │
   └─────────────────────────────────────────────┘
   ```

### 文件头结构
| 字段 | 大小 | 说明 |
|------|------|------|
| MagicNumber | 8字节 | 文件标识 "FGARD10\0" |
| Version | 1字节 | 版本号 (1) |
| OriginalFileNameLength | 4字节 | 原始文件名长度 |
| OriginalFileName | 变长 | UTF-8 编码的原始文件名 |
| OriginalFileSize | 8字节 | 原始文件大小 |
| SessionSalt | 16字节 | 会话盐值 |
| EncryptedFEK | 32字节 | 加密的文件加密密钥 |
| AuthTag | 16字节 | 认证标签 |
| Nonce | 12字节 | 随机数 |

## 🚀 使用方法

### 系统要求
- **操作系统**: Windows 10/11, Linux, macOS
- **运行时**: .NET 10 或 AOT 编译版本
- **权限**: 文件读写权限

### 快速开始

1. **准备文件**
   ```bash
   # 将需要加密的文件放在程序同一目录
   # 文件结构示例:
   # FileGuard.exe
   # ├── document.pdf
   # ├── photo.jpg
   # └── data.xlsx
   ```

2. **运行程序**
   ```bash
   # 直接运行
   ./FileGuard

   # 或使用AOT编译版本
   ./FileGuard
   ```

3. **操作流程**
   ```
   → 显示欢迎界面
   → 输入并确认加密密码
   → 选择操作菜单
   → 执行加密/解密
   → 查看操作结果
   ```

### 菜单选项

1. **🔒 加密当前目录文件**
   - 加密所有非 .newbit 文件
   - 自动跳过程序自身和被占用文件
   - 生成 .newbit 加密文件，删除原文件

2. **🔓 解密当前目录文件**
   - 解密所有 .newbit 文件
   - 需要输入加密时使用的密码
   - 恢复原始文件名和内容

3. **📊 查看目录信息**
   - 显示文件统计信息
   - 普通文件 vs 加密文件数量
   - 文件类型分布

4. **🔄 重新输入密码**
   - 重新初始化会话
   - 更新加密密码

5. **❌ 退出程序**
   - 安全清理内存中的密钥
   - 退出应用程序

## 🔧 编译和发布

### 开发编译
```bash
# 恢复依赖
dotnet restore

# 调试编译
dotnet build

# 运行测试
dotnet run
```

### AOT 发布
```bash
# Windows x64
dotnet publish -c Release -r win-x64 --self-contained -o ./publish/win-x64

# Linux x64
dotnet publish -c Release -r linux-x64 --self-contained -o ./publish/linux-x64

# macOS x64
dotnet publish -c Release -r osx-x64 --self-contained -o ./publish/osx-x64

# 最小体积发布
dotnet publish -c Release -r win-x64 --self-contained -p:PublishSingleFile=true -p:EnableCompressionInSingleFile=true -o ./publish
```

### 发布文件说明
```
publish/
├── FileGuard.exe          # Windows 可执行文件 (AOT)
├── FileGuard              # Linux/macOS 可执行文件
└── *.newbit               # 加密文件示例
```

## ⚠️ 重要注意事项

### 密码安全
- 🔑 **牢记密码**: 密码是解密的唯一凭证，丢失无法恢复
- 🔄 **会话密码**: 每次程序启动可使用不同密码
- 🚫 **密码强度**: 建议使用强密码，包含大小写字母、数字、符号

### 文件管理
- 📁 **备份原文件**: 加密前建议备份重要文件
- 🔒 **文件占用**: 被占用的文件会自动跳过
- ⚡ **大文件支持**: 支持超大文件分块加密
- 🛡️ **程序自身**: 自动跳过程序文件，避免自加密

### 安全警告
- 🚨 **测试解密**: 首次使用建议先加密测试文件并验证解密
- 💾 **多备份**: 重要文件加密前保留多个副本
- 🔐 **环境安全**: 在可信环境中进行加解密操作

## 🔄 恢复流程

### 正常恢复
1. 运行 FileGuard
2. 输入加密时使用的密码
3. 选择"解密当前目录文件"
4. 等待解密完成

### 紧急恢复
如果程序无法运行：
1. 安装 .NET 10 运行时
2. 重新编译源代码
3. 使用相同密码解密

### 文件修复
如果加密文件损坏：
- ❌ 认证标签验证失败 → 文件可能被篡改
- ❌ 魔法数字不匹配 → 非 FileGuard 加密文件
- ❌ 文件大小异常 → 文件可能不完整

## 📊 性能指标

### 加密性能
| 文件大小 | 加密时间 | 内存占用 |
|----------|----------|----------|
| 1 MB | < 1秒 | ~10 MB |
| 100 MB | ~5秒 | ~50 MB |
| 1 GB | ~30秒 | ~100 MB |
| 10 GB | ~5分钟 | ~200 MB |

### 格式兼容性
- ✅ 所有文件类型支持
- ✅ 中英文文件名支持
- ✅ 特殊字符文件名支持
- ✅ 超大文件支持 (TB级别)

## 🐛 故障排除

### 常见问题

**Q: 解密时提示"认证标签不匹配"**
A: 密码错误或文件被篡改，请确认使用正确的密码

**Q: 文件被跳过未加密**
A: 文件可能被其他程序占用，关闭相关程序后重试

**Q: 程序无法启动**
A: 确保系统支持 .NET 10 或使用 AOT 编译版本

**Q: 解密后文件损坏**
A: 加密文件可能不完整，请使用备份文件

### 日志信息
程序会显示详细的操作日志：
- ✅ 成功操作及文件列表
- ⚠️ 跳过文件及原因
- ❌ 失败操作及错误信息
- 📊 性能统计和耗时

## 📄 许可证和版权

### 开源协议
本项目采用 MIT 许可证，允许自由使用、修改和分发。

### 免责声明
本工具按"原样"提供，作者不对数据丢失承担任何责任。使用前请务必备份重要文件。

## 🔗 技术支持

### 问题反馈
如遇技术问题，请提供：
1. 操作系统版本
2. .NET 版本信息
3. 错误日志截图
4. 复现步骤描述

### 版本更新
- **v1.0.0**: 基础加密解密功能
- 计划功能: 选择性加密、密码提示、批量操作

---

**FileGuard** - 您的文件，您的控制 🔒

*最后更新: 2025年*