kdserra/CryptoUtility
GitHub: kdserra/CryptoUtility
CryptoUtility 是一个简化并统一 .NET 密码学操作的加密库，通过干净的接口和自动化的加密信封，让开发者轻松安全地使用现代加密算法。
Stars: 0 | Forks: 0
# 🔐 CryptoUtility
[](https://www.nuget.org/packages/CryptoUtility)
[](https://dotnet.microsoft.com)
[](https://github.com/kdserra/CryptoUtility/blob/master/LICENSE.md)
[](https://github.com/kdserra/CryptoUtility/actions/workflows/builder.yml)
# ❓ 为什么选择 CryptoUtility？
众所周知，标准的密码学 API 通常非常复杂、包含大量样板代码，且极易被错误配置。正因如此，开发者往往默认使用像 `AES-CBC` 这样较旧、安全性较低的选项，仅仅是因为像 `AES-GCM` 这样的现代认证加密算法更难配置。
CryptoUtility 通过提供以下功能弥补了这一差距：
## ⚡ 尖端的安全性，简洁的 API
借助 CryptoUtility，执行如 **AES-256-GCM** 或 **ChaCha20-Poly1305** 等高安全性认证加密（AEAD）就像运行无状态加密算法一样简单。所有复杂的逻辑——例如安全的 nonce 生成、认证标签处理和关联数据验证——都会被自动管理。
## 🧩 统一的接口
我们定义了干净、统一的接口，如 `ISymmetricCipher`、`IAsymmetricCipher`、`IHashProvider`、`IKeyAgreement` 和 `IPasswordKdf`。
这对于构建模块化的应用程序系统（例如 `SaveManager` 或网络层）来说非常强大。你的高层管理器可以直接依赖 `ISymmetricCipher`，而无需绑定到具体的实现。你可以仅用一行代码将整个加密算法从 AES 切换到 ChaCha20，而无需重写业务逻辑。
## 📦 自动加密信封
对于对称加密和混合加密，CryptoUtility 会在底层使用 `MemoryPack`（一种超快的二进制序列化器），自动将加密的有效载荷、随机 nonce 和认证标签打包成序列化的加密信封。你将获得一个可以直接传输的字节数组或 Base64 字符串。在解密时，系统会自动解析该信封。
# ✨ 功能特性
* **统一的 API 设计**：加密、解密、签名、密钥协商和哈希采用一致的语法模式。
* **内置实用工具**：提供开箱即用的辅助方法，支持无缝的 **Base64 字符串操作**，并可通过 `Cipher.GenerateKey()` **轻松生成密钥**。
* **对称加密（AEAD）**：支持现代标准，包括 **AES-256-GCM**、**AES-192-GCM**、**AES-128-GCM**、**ChaCha20-Poly1305** 等。
* **混合加密**：结合使用 RSA 公钥与底层 AES-256-GCM 的速度，轻松加密大型有效载荷。
* **非对称加密与签名**：完全支持 **RSA-2048**、**RSA-4096** 和椭圆曲线数字签名（**ECDSA**）。
* **密钥协商（ECDH）**：利用椭圆曲线 Diffie-Hellman 在开放通道上建立安全的会话密钥。
* **哈希与校验和**：SHA-2/3，快速的非加密哈希（xxHash32/64/128），以及完整性校验和（CRC-32、CRC-64）。
# 🚀 快速开始
## 1️⃣ 对称加密（AES-256-GCM）
### 🔤 Base64 字符串工作流
```
using CryptoUtility;
// 1. Generate a secure, random key as a Base64 string
string base64Key = Aes256Gcm.GenerateKeyBase64();
// 2. Encrypt plaintext into a self-contained Base64 envelope
string plaintext = "Confidential customer details...";
var (encSuccess, envelope) = Aes256Gcm.EncryptBase64(base64Key, plaintext);
if (encSuccess)
{
// 3. Decrypt with a single call
var (decSuccess, decryptedText) = Aes256Gcm.DecryptBase64(base64Key, envelope);
Console.WriteLine($"Decrypted: {decryptedText}"); // Confidential customer details...
}
```
### 📦 字节数组工作流
```
using CryptoUtility;
// 1. Generate key and plaintext bytes
byte[] key = Aes256Gcm.GenerateKey();
byte[] plaintext = "Hello World"u8.ToArray();
// 2. Encrypt and Decrypt
var (encSuccess, ciphertext) = Aes256Gcm.Encrypt(key, plaintext);
var (decSuccess, decrypted) = Aes256Gcm.Decrypt(key, ciphertext);
```
## 2️⃣ 混合非对称加密（RSA-4096 + AES）
```
using CryptoUtility;
// Generate public/private keypair
var (publicKey, privateKey) = Rsa4096.GenerateKeyPairBase64();
// Encrypt payload using the PUBLIC key
string largePayload = "Highly confidential PDF database dump...";
var (encSuccess, envelope) = Rsa4096.HybridEncryptBase64(Aes256Gcm.Shared, publicKey, largePayload);
// Decrypt payload using the PRIVATE key
var (decSuccess, decryptedPayload) = Rsa4096.HybridDecryptBase64(Aes256Gcm.Shared, privateKey, envelope);
```
## 3️⃣ 密钥协商与混合 ECDH
```
using CryptoUtility;
// 1. Establish KeyPairs for Alice and Bob
var (alicePub, alicePriv) = Ecdh.GenerateKeyPair();
var (bobPub, bobPriv) = Ecdh.GenerateKeyPair();
// 2. Alice and Bob derive the SAME shared secret
var (_, aliceSecret) = Ecdh.DeriveSharedSecret(alicePriv, bobPub);
var (_, bobSecret) = Ecdh.DeriveSharedSecret(bobPriv, alicePub);
// 3. Configure KDF parameters for session security
byte[] kdfSalt = "session-salt"u8.ToArray();
byte[] kdfInfo = "session-context-info"u8.ToArray();
// 4. Encrypt and Decrypt using derived secrets
var (_, ciphertext) = Ecdh.Encrypt(Aes256Gcm.Shared, Hkdf.Shared, aliceSecret, "Hi Bob!", kdfSalt, kdfInfo);
var (_, decrypted) = Ecdh.Decrypt(Aes256Gcm.Shared, Hkdf.Shared, bobSecret, ciphertext, kdfSalt, kdfInfo);
```
# 📚 密码学 API 参考
## 对称加密（AEAD — 推荐）
| 算法 | 实现方式 | 程序包 | 备注 |
|------------|----------------|----------|------|
| Aes256Gcm | .NET 内置 / BouncyCastle | CryptoUtility / CryptoUtility.BouncyCastle | 行业标准。 |
| Aes192Gcm | .NET 内置 / BouncyCastle| CryptoUtility / CryptoUtility.BouncyCastle | 较短密钥长度的变体。 |
| Aes128Gcm | .NET 内置 / BouncyCastle | CryptoUtility / CryptoUtility.BouncyCastle | 速度快，支持广泛。 |
| ChaCha20Poly1305 | .NET 内置 / NaCl.Core | CryptoUtility / CryptoUtility.NaCl | 强大，在纯软件系统中效率高 |
| XChaCha20Poly1305 | NaCl.Core | CryptoUtility.NaCl | 扩展 nonce 变体，nonce 处理更安全 |
## 对称加密（非 AEAD）
| 算法 | 实现方式 | 程序包 | 备注 |
|------------|----------------|----------|----------------|
| Salsa20 | NaCl.Core | CryptoUtility.NaCl | 无认证 |
| ChaCha20 | NaCl.Core | CryptoUtility.NaCl | 无认证 |
| XChaCha20 | NaCl.Core | CryptoUtility.NaCl | 无认证 |
| XorCipher | 自定义 | CryptoUtility.Extras | 仅作混淆，不安全 |
## 非对称加密
| 算法 | 实现方式 | 程序包 | 备注 |
|------------|----------------|----------|----------|
| Rsa1024 | .NET 内置 | CryptoUtility | 不安全 |
| Rsa2048 | .NET 内置 | CryptoUtility | 最低可接受标准 |
| Rsa3072 | .NET 内置 | CryptoUtility | 推荐 |
| Rsa4096 | .NET 内置 | CryptoUtility | 成本高，安全裕度高 |
## 数字签名
| 算法 | 实现方式 | 程序包 | 备注 |
|------------|----------------|----------|------|
| Ecdsa | .NET 内置 | CryptoUtility | 消息完整性与身份认证 |
## 密钥协商
| 算法 | 实现方式 | 程序包 | 备注 |
|------------|----------------|----------|--------|
| Ecdh | .NET 内置 | CryptoUtility | 共享密钥推导 |
## 密钥派生函数
| 算法 | 实现方式 | 程序包 | 备注 |
|------------|----------------|----------|------|
| Hkdf | .NET 内置 / HKDF.Standard | CryptoUtility / CryptoUtility.HkdfStandard | 标准密钥扩展。 |
## 基于密码的密钥派生函数
| 算法 | 实现方式 | 程序包 | 备注 |
|------------|----------------|----------|------|
| Pbkdf2 | .NET 内置 | CryptoUtility | 基于密码的密钥派生 |
## 哈希与校验和
### 加密哈希
| 算法 | 实现方式 | 程序包 | 备注 |
|------------|----------------|----------|------|
| Sha256 | .NET 内置 | CryptoUtility | 安全哈希函数 |
| Sha384 | .NET 内置 | CryptoUtility | 安全哈希函数 |
| Sha512 | .NET 内置 | CryptoUtility | 安全哈希函数 |
| Sha3_256 | .NET 内置 | CryptoUtility | 现代的 SHA-3 变体 |
| Sha3_384 | .NET 内置 | CryptoUtility | 现代的 SHA-3 变体 |
| Sha3_512 | .NET 内置 | CryptoUtility | 现代的 SHA-3 变体 |
| Sha1 | .NET 内置 | CryptoUtility | 已弃用，不安全 |
### 非加密哈希 / 校验和
| 算法 | 实现方式 | 程序包 | 备注 |
|------------|----------------|----------|------|
| Crc32 | System.IO.Hashing | CryptoUtility.Extras | 仅用于完整性校验 |
| Crc64 | System.IO.Hashing | CryptoUtility.Extras | 仅用于完整性校验 |
| XxHash32 | System.IO.Hashing | CryptoUtility.Extras | 高速哈希 |
| XxHash64 | System.IO.Hashing | CryptoUtility.Extras | 高速哈希 |
| XxHash128 | System.IO.Hashing | CryptoUtility.Extras | 高速哈希 |
## 📝 API 注意事项
推荐使用官方的 .NET 实现，因为它们通常支持硬件加速且拥有最好的支持，但它们通常较少支持跨平台；如果你使用的是旧版本的 .NET（例如 Unity 开发者），这一点就很重要。在这种情况下，请考虑使用 BouncyCastle 或提供你所需实现的特定用途库。
随着时间推移，本库的目标是支持并统一所有流行的密码学概念与实现。
## 🎭 消歧义
为了保持 API 的简洁性，本库选择让所有的算法类使用相同的名称，并旨在通过命名空间和命名空间别名来进行消歧义。
# 🛡️ 安全最佳实践
* **禁止静态 nonce**：CryptoUtility 会为每次对称加密生成唯一的、密码学安全的随机 nonce。
* **认证优先**：我们默认使用 AEAD（带关联数据的认证加密）密码，以防止位翻转攻击（bit-flipping）和填充预言攻击。
* **内存清理**：敏感的派生密钥在使用后会立即从系统内存中清零。
* **标准实现**：我们不自行编写自定义的密码学算法。我们封装了标准的、经过行业验证的实现，除非某些算法尚无可用实现。
# 📦 安装说明
将 NuGet 程序包添加到你的项目中：
```
dotnet add package CryptoUtility
```
# 📄 许可证
该项目基于 MIT 许可证授权。详情请参阅 [LICENSE.md](LICENSE.md)。
标签：AES, ChaCha20, 加密库, 多人体追踪, 密码学, 手动系统调用