Taiizor/Lucinda
GitHub: Taiizor/Lucinda
一个为 .NET 平台提供的端到端加密库，完整实现 Signal Protocol 协议栈，支持前向安全、群组加密和多种密码学原语。
Stars: 31 | Forks: 2
# Lucinda
[](https://www.nuget.org/packages/Lucinda/)
[](https://opensource.org/licenses/MIT)
一个全面的 .NET 端到端加密 (E2EE) 库，提供安全的加密操作，包括对称/非对称加密、密钥交换、数字签名和安全的密钥管理。
## 功能特性
- **对称加密**
- AES-GCM (Galois/Counter Mode) - 认证加密
- AES-CBC (Cipher Block Chaining)，可选 HMAC 认证
- 支持 128、192 和 256 位密钥
- **非对称加密**
- 使用 OAEP 填充的 RSA 加密
- 支持 2048、3072 和 4096 位密钥
- 混合加密 (RSA + AES-GCM)
- **密钥交换**
- ECDH (Elliptic Curve Diffie-Hellman)
- 支持 P-256、P-384 和 P-521 曲线
- **数字签名**
- 使用 PSS 或 PKCS#1 v1.5 填充的 RSA 签名
- ECDSA (Elliptic Curve Digital Signature Algorithm)
- **密钥派生**
- PBKDF2 (Password-Based Key Derivation Function 2)
- HKDF (HMAC-based Key Derivation Function)
- **安全密钥存储**
- 内存中密钥存储，支持安全清除
- 可扩展接口，支持自定义存储后端
- **类 Signal Protocol 安全消息传递**
- X3DH (Extended Triple Diffie-Hellman) 密钥协商
- 用于前向安全消息传递的 Double Ratchet 算法
- 用于异步会话建立的预密钥束
- **Header 加密**：保护消息元数据（ratchet 密钥、计数器）
- **Sender Keys 协议**：通过 `GroupSession` 实现高效群组消息传递
- 前向保密：如果密钥泄露，过往消息依然安全
- 泄露后安全：泄露后的未来消息将恢复安全
- **可扩展性**：`ICurve25519` 和 `IEdDSA` 接口支持自定义加密提供程序
## 支持的平台
| Platform | Version |
|----------|---------|
| .NET Standard | 2.0, 2.1 |
| .NET Framework | 4.8, 4.8.1 |
| .NET | 6.0, 7.0, 8.0, 9.0, 10.0 |
## 安装
```
dotnet add package Lucinda
```
或通过 NuGet Package Manager 安装：
```
Install-Package Lucinda
```
## 快速开始
### 高级 API
`EndToEndEncryption` 类为常见的 E2EE 场景提供了简化的 API：
```
using Lucinda;
// Create an E2EE instance
using var e2ee = new EndToEndEncryption();
// Generate key pairs for Alice and Bob
var aliceKeyPair = e2ee.GenerateKeyPair();
var bobKeyPair = e2ee.GenerateKeyPair();
// Alice encrypts a message for Bob
var encrypted = e2ee.EncryptMessage("Hello, Bob!", bobKeyPair.Value.PublicKey);
// Bob decrypts the message
var decrypted = e2ee.DecryptMessage(encrypted.Value, bobKeyPair.Value.PrivateKey);
Console.WriteLine(decrypted.Value); // "Hello, Bob!"
```
### 类 Signal Protocol 安全消息传递
`SecureMessaging` 类通过 X3DH 和 Double Ratchet 提供类 Signal Protocol 的安全性：
```
using Lucinda;
// Alice and Bob setup
using var alice = new SecureMessaging();
using var bob = new SecureMessaging();
alice.GenerateIdentityKeyPair();
bob.GenerateIdentityKeyPair();
bob.GeneratePreKeyBundle();
// Alice initiates session with Bob's pre-key bundle
var bobBundle = bob.GetPublicPreKeyBundle();
alice.InitializeSession("bob", bobBundle.Value);
// Bob creates session from Alice's initial contact
var initialMessage = alice.GetInitialMessageData("bob");
bob.CreateSessionFromInitialMessage("alice", initialMessage.Value);
// Send encrypted messages with forward secrecy
var encrypted = alice.SendMessage("bob", "Hello with forward secrecy!");
var decrypted = bob.ReceiveMessage("alice", encrypted.Value);
Console.WriteLine(decrypted.Value); // "Hello with forward secrecy!"
```
### 群组消息传递
```
using Lucinda.Protocol.SenderKeys;
// Create group sessions for each participant
using var alice = new GroupSession("my-group-123", "alice");
using var bob = new GroupSession("my-group-123", "bob");
using var charlie = new GroupSession("my-group-123", "charlie");
// Initialize sender keys
alice.Initialize();
bob.Initialize();
charlie.Initialize();
// Exchange distribution messages (each participant shares their sender key)
var aliceDist = alice.CreateDistributionMessage();
var bobDist = bob.CreateDistributionMessage();
alice.ProcessDistributionMessage("bob", bobDist.Value);
bob.ProcessDistributionMessage("alice", aliceDist.Value);
// Alice sends encrypted message to the group (single encryption for all recipients)
var groupMessage = alice.Encrypt(Encoding.UTF8.GetBytes("Hello group!"));
// Bob decrypts the group message
var decrypted = bob.Decrypt(groupMessage.Value);
Console.WriteLine(Encoding.UTF8.GetString(decrypted.Value)); // "Hello group!"
```
### 对称加密 (AES-GCM)
```
using Lucinda.Symmetric;
// Generate a new key
using var aes = new AesGcmEncryption(256); // 256-bit key
// Encrypt data
var plaintext = "Sensitive data"u8.ToArray();
var encrypted = aes.Encrypt(plaintext);
// Decrypt data
var decrypted = aes.Decrypt(encrypted.Value);
// With associated data (AAD)
var metadata = "header"u8.ToArray();
var encryptedWithAad = aes.Encrypt(plaintext, metadata);
var decryptedWithAad = aes.Decrypt(encryptedWithAad.Value, metadata);
```
### 混合加密 (RSA + AES)
```
using Lucinda.Asymmetric;
using var hybrid = new RsaAesHybridEncryption();
// Generate a key pair
var keyPair = hybrid.GenerateKeyPair();
// Encrypt (anyone with the public key can encrypt)
var data = "Large amount of data..."u8.ToArray();
var encrypted = hybrid.Encrypt(data, keyPair.Value.PublicKey);
// Decrypt (only the private key holder can decrypt)
var decrypted = hybrid.Decrypt(encrypted.Value, keyPair.Value.PrivateKey);
```
### 数字签名
```
using Lucinda.Signatures;
// ECDSA signatures
using var signer = new EcdsaSignature();
var keyPair = signer.GenerateKeyPair();
var data = "Data to sign"u8.ToArray();
// Sign
var signature = signer.Sign(data);
// Verify
var isValid = signer.Verify(data, signature.Value);
Console.WriteLine(isValid.Value); // true
```
### 从密码派生密钥
```
using Lucinda.KeyDerivation;
using var pbkdf2 = new Pbkdf2KeyDerivation();
// Derive a key from a password
var password = "MySecretPassword";
var salt = SecureRandom.GenerateSalt(32);
var derivedKey = pbkdf2.DeriveKey(password, salt, iterations: 600000, derivedKeyLength: 32);
// Use derivedKey.Value for encryption
```
### HKDF 密钥派生
```
using Lucinda.KeyDerivation;
using var hkdf = new HkdfKeyDerivation();
// Derive keys from a shared secret
var sharedSecret = new byte[32]; // From key exchange
var salt = SecureRandom.GenerateSalt(32);
var info = "encryption-key"u8.ToArray();
var encryptionKey = hkdf.DeriveKey(sharedSecret, salt, info, 32);
```
### 密钥交换 (ECDH)
```
using Lucinda.KeyExchange;
// Alice generates her key pair
using var aliceEcdh = new EcdhKeyExchange();
var alicePublicKey = aliceEcdh.GetPublicKey();
// Bob generates his key pair
using var bobEcdh = new EcdhKeyExchange();
var bobPublicKey = bobEcdh.GetPublicKey();
// Both derive the same shared secret
var aliceSharedSecret = aliceEcdh.DeriveSharedSecret(bobPublicKey.Value);
var bobSharedSecret = bobEcdh.DeriveSharedSecret(alicePublicKey.Value);
// aliceSharedSecret == bobSharedSecret
```
### 加密并签名 (完整 E2EE)
```
using Lucinda;
using var e2ee = new EndToEndEncryption();
// Generate keys
var senderSigningKeyPair = e2ee.GenerateSigningKeyPair();
var recipientKeyPair = e2ee.GenerateKeyPair();
var message = "Authenticated and encrypted message"u8.ToArray();
// Encrypt and sign
var signedEncrypted = e2ee.EncryptAndSign(
message,
recipientKeyPair.Value.PublicKey,
senderSigningKeyPair.Value.PrivateKey);
// Verify and decrypt
var decrypted = e2ee.VerifyAndDecrypt(
signedEncrypted.Value,
recipientKeyPair.Value.PrivateKey,
senderSigningKeyPair.Value.PublicKey);
if (decrypted.IsSuccess)
{
Console.WriteLine("Message verified and decrypted!");
}
```
## 错误处理
所有加密操作返回一个封装成功或失败的 `CryptoResult`：
```
var result = aes.Encrypt(data);
if (result.IsSuccess)
{
var encrypted = result.Value;
// Use encrypted data
}
else
{
Console.WriteLine($"Error: {result.Error}");
}
// Or use pattern matching
result.Match(
onSuccess: data => ProcessData(data),
onFailure: error => HandleError(error)
);
```
## 安全注意事项
1. **密钥管理**：始终安全地存储和保护私钥。
2. **随机数生成**：该库使用 `System.Security.Cryptography.RandomNumberGenerator` 生成加密安全的随机数。
3. **内存安全**：敏感数据（密钥、明文）在可能的情况下会从内存中清除。
4. **认证加密**：使用 AES-GCM 或在 AES-CBC 中启用 HMAC 以确保数据完整性。
5. **密钥大小**：生产环境中请至少使用 2048 位的 RSA 密钥和 256 位的 AES 密钥。
6. **密码哈希**：基于密码的密钥派生请使用至少 600,000 次迭代的 PBKDF2。
## API 参考
### 主要类
| Class | Description |
|-------|-------------|
| `EndToEndEncryption` | 高级 E2EE 操作 |
| `AesGcmEncryption` | AES-GCM 认证加密 |
| `AesCbcEncryption` | AES-CBC 加密 |
| `RsaEncryption` | RSA 非对称加密 |
| `RsaAesHybridEncryption` | 混合 RSA+AES 加密 |
| `EcdhKeyExchange` | ECDH 密钥交换 |
| `RsaSignature` | RSA 数字签名 |
| `EcdsaSignature` | ECDSA 数字签名 |
| `Pbkdf2KeyDerivation` | 基于密码的密钥派生 |
| `HkdfKeyDerivation` | HKDF 密钥派生 |
| `InMemoryKeyStorage` | 安全的内存密钥存储 |
| `SecureMessaging` | 类 Signal Protocol 安全消息传递 |
| `X3DHKeyAgreement` | X3DH 密钥协商协议 |
| `DoubleRatchet` | Double Ratchet 算法 |
| `HeaderEncryption` | 用于元数据保护的 Header 加密 |
| `GroupSession` | 用于群组消息传递的 Sender Keys 协议 |
### 接口
| Interface | Description |
|-----------|-------------|
| `ISymmetricEncryption` | 对称加密协定 |
| `IAsymmetricEncryption` | 非对称加密协定 |
| `IHybridEncryption` | 混合加密协定 |
| `IKeyExchange` | 密钥交换协定 |
| `IDigitalSignature` | 数字签名协定 |
| `IKeyDerivation` | 密钥派生协定 |
| `ISecureKeyStorage` | 安全密钥存储协定 |
| `IX3DHKeyAgreement` | X3DH 密钥协商协定 |
| `IDoubleRatchet` | Double Ratchet 协定 |
| `IKdfChain` | KDF 链操作协定 |
| `ISessionStorage` | 会话存储协定 |
| `IHeaderEncryption` | Header 加密协定 |
| `IGroupSession` | 群组消息传递会话协定 |
| `ICurve25519` | X25519 密钥交换协定（可扩展性） |
| `IEdDSA` | Ed25519 签名协定（可扩展性） |
## 许可证
本项目采用 MIT 许可证授权 - 详见 [LICENSE](LICENSE) 文件。
## 贡献
欢迎贡献！请随时提交 Pull Request。
## 致谢
- 基于 .NET 的 `System.Security.Cryptography` 命名空间构建
- 遵循现代密码学最佳实践
标签：AES-GCM, CVE, DNS 反向解析, Double Ratchet, E2EE, ECDH, ECDSA, HKDF, NET Framework, NET Standard, NuGet, PBKDF2, RSA, Signal Protocol, X3DH, YAML, 云配置检测, 前向保密, 多人体追踪, 安全库, 安全通讯, 密码学, 密钥交换, 对称加密, 库, 应急响应, 手动系统调用, 数字签名, 端到端加密, 组播加密, 网络安全, 自动化审计, 隐私保护, 非对称加密