BugFree.Security 1.2.2026.613-beta1518

BugFree.Security

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 确保密钥材料在使用后及时清理

📦 安装

dotnet add package BugFree.Security

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

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

🚀 快速开始

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

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. 对称加密

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. 密码哈希

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. 非对称加密与签名

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. 密钥管理

// 使用内存密钥库
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 扩展方法

🔐 支持的算法

对称加密

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

密码哈希

密码学哈希

非密码学哈希

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

校验和 & HMAC

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

🗝️ 密钥管理

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

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

国密算法基于 BouncyCastle.Cryptography 实现，完全符合国家标准。

SM2 — 非对称加密与签名

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 — 密码学哈希

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 — 对称加密

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 许可证开源。