# BugFree.Security

**Repository Path**: BugFree_1/BugFree.Security

## Basic Information

- **Project Name**: BugFree.Security
- **Description**: 面向 .NET 的现代安全加密库，统一封装对称/非对称加密、密码哈希、密钥管理及国密算法（SM2/SM3/SM4），支持依赖注入，安全优先，开箱即用。
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-16
- **Last Updated**: 2026-06-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BugFree.Security

![.NET](https://img.shields.io/badge/.NET-9.0-512BD4)
![License](https://img.shields.io/badge/license-MIT-green)
![Platform](https://img.shields.io/badge/platform-Windows%20|%20Linux%20|%20macOS-blue)

**BugFree.Security** 是一个面向 .NET 的现代、全面、统一的安全加密库，提供从对称/非对称加密、密码哈希到密钥管理的一站式解决方案。

---

## ✨ 特性

- **统一的 API 设计** — 所有加密操作通过抽象接口暴露，支持依赖注入，业务层零耦合
- **丰富的算法支持** — 覆盖国际主流算法（AES/RSA/ECDSA/ECDH/Ed25519/X25519）与国密算法（SM2/SM3/SM4）
- **密码哈希** — 内置 Argon2id（推荐）、BCrypt、scrypt、PBKDF2，开箱即用
- **哈希与校验** — 密码学哈希（SHA-2/SHA-3/SM3）、非密码学哈希（xxHash/MurmurHash/FNV）、校验和（CRC32/CRC64/Adler32）、HMAC
- **完善的密钥管理** — 支持密钥生成、版本管理、自动轮换、内存/文件两种存储方式，线程安全
- **安全优先** — 已弃用算法（DES/3DES/RC2/MD5/SHA-1/DSA）以 `[Obsolete]` 标记，引导开发者使用现代替代方案
- **高性能** — 利用 `ReadOnlySpan<byte>`、`ConcurrentDictionary` 缓存 Provider，最小化内存分配
- **安全内存管理** — `SafeKeyMaterialHandle` 确保密钥材料在使用后及时清理

---

## 📦 安装

```shell
dotnet add package BugFree.Security
```

或通过 NuGet 包管理器搜索 `BugFree.Security`。

> 当前目标框架：`net8.0`、`net10.0`

---

## 🚀 快速开始

### 1. 注册服务（依赖注入）

```csharp
using BugFree.Security;
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection();

// 按需注册所需服务
services.AddSymmetricCryptoService();       // 对称加密
services.AddAsymmetricCryptoService();      // 非对称加密
services.AddPasswordHashService();          // 密码哈希
services.AddCryptographicHashService();     // 密码学哈希
services.AddNonCryptographicHashService();  // 非密码学哈希
services.AddChecksumService();             // 校验和
services.AddHmacService();                 // HMAC
services.AddAsymmetricKeyManager();        // 非对称密钥管理
services.AddSymmetricKeyManager();         // 对称密钥管理
```

### 2. 对称加密

```csharp
var service = new SymmetricCryptoService();

// 生成密钥
var key = service.CreateKey(SymmetricType.AesGcm);

// 加密
var result = service.Encrypt(SymmetricType.AesGcm, plaintext, key);

// 解密
var decrypted = service.Decrypt(SymmetricType.AesGcm, result.Ciphertext, key,
    new SymmetricDecryptOptions { Nonce = result.Nonce, Tag = result.Tag, Aad = result.Aad });
```

### 3. 密码哈希

```csharp
var service = PasswordHashService.Default;

// 哈希（推荐 Argon2id）
var hash = service.HashPassword(PasswordHashType.Argon2id, "myPassword",
    new Argon2HashOptions { MemorySize = 19456, Iterations = 2, Parallelism = 1 });

// 验证
var isValid = service.VerifyPassword(PasswordHashType.Argon2id, "myPassword", hash);
```

### 4. 非对称加密与签名

```csharp
var service = AsymmetricCryptoService.Default;

// 生成密钥对
var (publicKey, privateKey) = service.GenerateKeyPair(KeyPairType.RSA);

// 加密
var ciphertext = service.Encrypt(AsymmetricEncryptionType.RSA, data, publicKey);

// 解密
var plaintext = service.Decrypt(AsymmetricEncryptionType.RSA, ciphertext, privateKey);

// 签名
var signature = service.Sign(SignatureType.RSA, data, privateKey);

// 验签
var verified = service.Verify(SignatureType.RSA, data, signature, publicKey);
```

### 5. 密钥管理

```csharp
// 使用内存密钥库
var keyManager = new SymmetricKeyManager(new MemoryKeyStore<SymmetricKeyRecord>());

// 自动轮换 - 获取密钥（如果过期自动生成新版本）
var key = keyManager.ResolveForKey("my-app-key",
    _ => SymmetricCryptoService.Default.CreateKey(SymmetricType.AesGcm));
```

---

## 🧩 架构概览

```
BugFree.Security
├── Abstractions/          # 抽象接口与类型定义
│   ├── Asymmetric/        #   非对称加密：IAsymmetricCryptoService、RSA/ECDSA/Ed25519/X25519/SM2
│   ├── Symmetric/         #   对称加密：ISymmetricCryptoService、AES/AES-GCM/DES/3DES/RC2/SM4
│   ├── Hash/              #   哈希
│   │   ├── Password/      #     密码哈希：Argon2id/BCrypt/scrypt/PBKDF2
│   │   ├── Cryptographic/ #     密码学哈希：SHA-2/SHA-3/SM3/MD5
│   │   ├── NonCryptographic/ # 非密码学哈希：xxHash/MurmurHash/FNV
│   │   ├── Hmac/          #     HMAC：HMAC-SHA256/384/512
│   │   └── Checksum/      #     校验和：CRC32/CRC64/Adler32
│   └── Key/               #   密钥管理：IKeyManager/IKeyStore/IKeyRotator/IKeyResolver
├── Core/                  # 核心算法实现
│   ├── Asymmetric/        #   RSA、DSA、ECDsa、ECDH、Ed25519、X25519、SM2
│   ├── Symmetric/         #   AES、AES-GCM、DES、3DES、RC2、SM4
│   ├── Hash/              #   各类哈希算法的具体 Provider
│   └── Key/               #   密钥解析器、轮换器、内存/文件存储
├── Services/              # 服务层（DI 注册用）
│   ├── AsymmetricCryptoService
│   ├── SymmetricCryptoService
│   ├── PasswordHashService
│   ├── CryptographicHashService
│   ├── NonCryptographicHashService
│   ├── ChecksumService
│   └── HmacService
├── Models/                # 数据模型
│   ├── KeyPair            #   密钥对
│   ├── HashResult         #   哈希结果
│   ├── SignatureResult    #   签名结果
│   └── Key/               #   密钥记录、策略、元数据
├── AsymmetricKeyManager.cs
├── SymmetricKeyManager.cs
├── KeyManagerBase.cs      # 密钥管理器基类
├── KeyLockCoordinator.cs  # 读写锁协调器
├── SafeKeyMaterialHandle.cs  # 安全内存句柄
└── ServiceCollectionExtension.cs  # DI 扩展方法
```

---

## 🔐 支持的算法

### 对称加密

| 算法 | 类型 | 状态 | 密钥长度 |
|------|------|------|---------|
| AES-256-CBC | `SymmetricType.Aes` | ✅ 推荐 | 16/24/32 bytes |
| AES-256-GCM | `SymmetricType.AesGcm` | ✅ **强烈推荐** | 16/24/32 bytes |
| SM4-CBC | `SymmetricType.Sm4` | ✅ 国密 | 16 bytes |
| DES | `SymmetricType.Des` | ❌ 已攻破 | 8 bytes |
| 3DES | `SymmetricType.TripleDes` | ❌ 已攻破 | 24 bytes |
| RC2 | `SymmetricType.Rc2` | ❌ 已攻破 | 16 bytes |

### 非对称加密 / 签名 / 密钥交换

| 算法 | 密钥对 | 加密 | 签名 | 密钥交换 |
|------|--------|------|------|---------|
| RSA | ✅ | ✅ | ✅ | - |
| ECDSA | ✅ | - | ✅ | - |
| ECDH | ✅ | - | - | ✅ |
| Ed25519 | ✅ | - | ✅ | - |
| X25519 | ✅ | - | - | ✅ |
| SM2 | ✅ | ✅ | ✅ | ✅ |
| DSA | ✅ | - | ❌ 已过时 | - |

### 密码哈希

| 算法 | 状态 |
|------|------|
| Argon2id | ✅ **强烈推荐** |
| Argon2d | ❌ 不推荐 |
| Argon2i | ❌ 不推荐 |
| BCrypt | ✅ 广泛使用 |
| scrypt | ✅ |
| PBKDF2 | ✅ |

### 密码学哈希

| 算法 | 状态 |
|------|------|
| SHA-256/384/512 | ✅ 推荐 |
| SHA3-256/384/512 | ✅ 推荐 |
| SM3 | ✅ 国密 |
| MD5 | ❌ 不安全 |
| SHA-1 | ❌ 已被攻破 |

### 非密码学哈希

xxHash3/32/64/128、MurmurHash2/3、FNV-1a

### 校验和 & HMAC

CRC32、CRC64、Adler32；HMAC-SHA256/384/512

---

## 🗝️ 密钥管理

BugFree.Security 提供完整的密钥生命周期管理：

| 功能 | 说明 |
|------|------|
| **密钥生成** | 支持对称密钥和非对称密钥对的自动生成 |
| **版本管理** | 每次轮换创建新版本，历史版本可追溯 |
| **自动轮换** | 基于时间间隔（默认 90 天）和最大使用次数 |
| **存储方式** | `MemoryKeyStore`（内存）/ `FileKeyStore`（文件） |
| **线程安全** | `KeyLockCoordinator` 提供每密钥粒度的读写锁 |
| **内存安全** | `SafeKeyMaterialHandle` 确保敏感材料及时归零 |

---

## 🇨🇳 国密算法（SM2/SM3/SM4）

国密算法基于 [BouncyCastle.Cryptography](https://www.nuget.org/packages/BouncyCastle.Cryptography) 实现，完全符合国家标准。

### SM2 — 非对称加密与签名

| 功能 | 说明 |
|------|------|
| **密钥对生成** | 基于 SM2 椭圆曲线（`sm2p256v1`），公钥 SubjectPublicKeyInfo / 私钥 PKCS#8（DER 编码） |
| **加密/解密** | 默认 C1C3C2 密文格式（标准推荐），可通过 `AsymmetricEncryptOptions.Sm2CiphertextFormat` 切换为 C1C2C3 |
| **签名/验签** | 默认 SM3 摘要，用户标识（ID）默认 `1234567812345678`（GB/T 32918 推荐值），支持自定义 ID |
| **密钥交换** | 基于 ECDH + HKDF-SM3 派生共享密钥，默认 32 字节，支持自定义长度和盐值 |

```csharp
var service = AsymmetricCryptoService.Default;

// 生成 SM2 密钥对
var keyPair = service.GenerateKeyPair(KeyPairType.SM2);

// 加密（默认 C1C3C2 格式）
var ciphertext = service.Encrypt(AsymmetricEncryptionType.SM2, plaintext, keyPair.PublicKey);
var decrypted = service.Decrypt(AsymmetricEncryptionType.SM2, ciphertext, keyPair.PrivateKey);

// 签名（使用默认 SM3 摘要和标准 ID）
var signature = service.Sign(SignatureType.SM2, data, keyPair.PrivateKey, null);
var verified = service.Verify(SignatureType.SM2, data, signature, keyPair.PublicKey, null);

// 自定义用户标识签名
var sig = service.Sign(SignatureType.SM2, data, keyPair.PrivateKey,
    new SignatureOptions { HashAlgorithm = "custom-user-id" });

// 密钥交换
var aliceKey = service.DeriveKey(KeyExchangeType.SM2, alice.PrivateKey, bob.PublicKey,
    new KeyExchangeOptions { DerivedKeySize = 48, Salt = salt });
```

### SM3 — 密码学哈希

| 属性 | 说明 |
|------|------|
| **输出长度** | 256 位（32 字节） |
| **安全性** | 与 SHA-256 相当 |
| **支持操作** | 哈希计算、带盐哈希、固定时间比较验证 |

```csharp
var service = CryptographicHashService.Default;

// 计算 SM3 哈希
var hash = service.ComputeHash(CryptographicHashType.SM3, data);

// 带盐哈希
var saltedHash = service.ComputeHash(CryptographicHashType.SM3, data, salt);

// 验证
var isValid = service.VerifyHash(CryptographicHashType.SM3, hash, data);
```

### SM4 — 对称加密

| 属性 | 说明 |
|------|------|
| **密钥长度** | 固定 128 位（16 字节） |
| **分组大小** | 128 位 |
| **模式** | CBC + PKCS7 填充 |
| **密文格式** | IV（16 字节）+ 密文 |

```csharp
var service = SymmetricCryptoService.Default;

// 生成 SM4 密钥（16 字节）
var key = service.CreateKey(SymmetricType.Sm4);

// 加密（自动随机 IV）
var result = service.Encrypt(SymmetricType.Sm4, plaintext, key);

// 解密
var decrypted = service.Decrypt(SymmetricType.Sm4, result.Ciphertext, key,
    new SymmetricDecryptOptions { IV = result.IV });
```

> ⚠️ **安全提示**：SM4-CBC 不提供完整性保护，建议配合 HMAC 或使用 AEAD 模式。

---

## 📋 测试覆盖

项目包含完善的单元测试套件 `BugFree.Security.TestProject`，覆盖：

- 对称加密服务测试
- 非对称加密服务测试
- 密码哈希服务测试
- 密码学哈希服务测试
- 非密码学哈希服务测试
- HMAC & 校验和服务测试
- 密钥管理测试（对称/非对称密钥管理器、内存/文件存储、安全句柄）
- 依赖注入扩展测试

---

## 🤝 参与贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支：`git checkout -b feat/your-feature`
3. 提交代码：`git commit -m "feat: add xxx"`
4. 推送分支：`git push origin feat/your-feature`
5. 创建 Pull Request

---

## 📄 许可证

本项目基于 MIT 许可证开源。