RuoVea.ExCrypt 8.0.1.2

🔐 RuoVea.ExCrypt

一站式 .NET 加密工具库 — 集成 AES、TripleDES、RSA、SHA-1/256/384/512、HMAC、MD5、Base64 等 14+ 种加密/哈希算法，提供静态方法与流畅的 string 扩展方法，并内置中、英、法、日、粤语、越南语等 7 种语言的异常提示。

📖 目录

• 📋 概览
• 📦 安装
• ⚡ 30 秒快速开始
• 🧩 核心场景
  • 场景一：对称加密（AES）
  • 场景二：哈希与数据完整性
  • 场景三：消息认证码（HMAC）
  • 场景四：非对称加密（RSA）
  • 场景五：Base64 编解码
  • 场景六：机器密钥生成
  • 场景七：流畅扩展方法
• ⚙️ 配置选项详解
• 🛡️ 错误处理与日志
• 🧵 线程安全
• 📊 算法速查表
• 🌍 国际化
• 🗺️ 版本迁移指南

📋 概览

RuoVea.ExCrypt 为 .NET 开发者提供了开箱即用的加密原语封装，避免直接操作 CryptoStream / KeySize / Padding 的繁琐细节。

 ┌──────────────────────────────────────────────────┐
 │              RuoVea.ExCrypt                       │
 ├──────────────────────────────────────────────────┤
 │  对称加密        哈希             HMAC            │
 │  ├─ AES (CBC/ECB) ├─ SHA-1       ├─ HMAC-SHA1    │
 │  └─ TripleDES     ├─ SHA-256     ├─ HMAC-SHA256  │
 │                   ├─ SHA-384     ├─ HMAC-SHA384  │
 │  非对称加密        ├─ SHA-512     ├─ HMAC-SHA512  │
 │  └─ RSA           └─ MD5         └─ HMAC-MD5     │
 │                                                   │
 │  编码              密钥生成        扩展方法        │
 │  └─ Base64         ├─ MachineKey  └─ string.*     │
 │                    └─ AES/DES KeyGen              │
 ├──────────────────────────────────────────────────┤
 │  国际化: zh-CN | zh-TW | zh-HK | en | fr | ja | vi│
 └──────────────────────────────────────────────────┘

设计原则

📦 安装

.NET CLI

# .NET 8.0
dotnet add package RuoVea.ExCrypt --version 8.0.1.1

# .NET 10.0
dotnet add package RuoVea.ExCrypt --version 10.0.0.0

Package Manager

Install-Package RuoVea.ExCrypt -Version 8.0.1.1

PackageReference

<PackageReference Include="RuoVea.ExCrypt" Version="8.0.1.1" />

支持的 Target Framework

⚡ 30 秒快速开始

1. 导入命名空间

using RuoVea.ExCrypt;                      // 所有加密类
using RuoVea.ExCrypt.Encryptions.Domain;   // AESKey, EnumMD5Length, RSAKey 等

2. 第一行加密代码

// <inheritdoc cref="AESCrypt.AESEncrypt(string, string, string)"/>
// 生成密钥 & 加密
var aesKey = AESCrypt.CreateAesKey();
string cipher = AESCrypt.AESEncrypt("Hello, 世界!", aesKey.Key, aesKey.IV);

// <inheritdoc cref="AESCrypt.AESDecrypt(string, string, string)"/>
string plain = AESCrypt.AESDecrypt(cipher, aesKey.Key, aesKey.IV);
Console.WriteLine(plain); // "Hello, 世界!"

3. 使用扩展方法（更流畅）

// <inheritdoc cref="StringExtensions.ToAESEncrypt"/>
string cipher = "敏感数据".ToAESEncrypt("your-32-char-key-here!!!!!!!");

// <inheritdoc cref="StringExtensions.ToMD5Encrypt"/>
string hash   = "password123".ToMD5Encrypt(EnumMD5Length.L32);

// <inheritdoc cref="StringExtensions.ToRSAEncrpyt"/>
string rsaEnc = "机密".ToRSAEncrpyt(publicKeyXml);

30 秒内你完成了: 密钥生成 → AES-256-CBC 加密 → Base64 编码输出 → 解密还原。以及 MD5 哈希和 RSA 加密。

🧩 核心场景

场景一：对称加密（AES）

┌──────────┐     AESEncrypt(data, key, vector)     ┌──────────────┐
│  明文     │ ──────────────────────────────────▶  │  Base64 密文  │
│ (string)  │                                       │  (string)     │
└──────────┘                                       └──────┬───────┘
                                                          │
                                                  AESDecrypt(cipher, key, vector)
                                                          │
                                                          ▼
                                                  ┌──────────────┐
                                                  │  明文 (string)│
                                                  └──────────────┘

🔹 AES-CBC 模式（推荐）

// <inheritdoc cref="AESCrypt.CreateAesKey"/>
AESKey keyMaterial = AESCrypt.CreateAesKey();

// <inheritdoc cref="AESCrypt.AESEncrypt(string, string, string)"/>
// 输出: Base64 编码的密文字符串
string encrypted = AESCrypt.AESEncrypt(
    data:   "订单金额: ¥1,280.00",
    key:    keyMaterial.Key,   // 32 字符
    vector: keyMaterial.IV     // 16 字符
);

// <inheritdoc cref="AESCrypt.AESDecrypt(string, string, string)"/>
string decrypted = AESCrypt.AESDecrypt(encrypted, keyMaterial.Key, keyMaterial.IV);
// decrypted == "订单金额: ¥1,280.00"

// 字节级加解密（适用于二进制数据）
byte[] imageBytes = File.ReadAllBytes("avatar.png");

// <inheritdoc cref="AESCrypt.AESEncrypt(byte[], string, string)"/>
byte[] encryptedBytes = AESCrypt.AESEncrypt(imageBytes, keyMaterial.Key, keyMaterial.IV);

// <inheritdoc cref="AESCrypt.AESDecrypt(byte[], string, string)"/>
byte[] decryptedBytes = AESCrypt.AESDecrypt(encryptedBytes, keyMaterial.Key, keyMaterial.IV);

❗ 性能陷阱: AES-CBC 模式下每次加密都会 CreateEncryptor，适合离散调用。若需高频加密（> 1000次/秒），考虑用 Aes.Create() 复用实例自行管理。

🔹 AES-ECB 模式（兼容旧系统）

// <inheritdoc cref="AESCrypt.AESEncrypt(string, string)"/>
// ECB 模式：无需 IV，仅需 32 字符密钥
string encrypted = AESCrypt.AESEncrypt("兼容旧系统数据", "your-32-characters-key-right-here");
string decrypted = AESCrypt.AESDecrypt(encrypted, "your-32-characters-key-right-here");

⚠️ 安全警告: ECB 模式不隐藏数据模式，相同明文块产生相同密文块。仅用于兼容旧系统，新项目请使用 CBC 模式。

场景二：哈希与数据完整性

┌────────┐   SHA-1/256/384/512/MD5    ┌──────────────┐
│  输入   │ ───────────────────────▶  │  十六进制哈希  │
│ string  │                            │  (string)     │
└────────┘                            └──────────────┘
用例: 密码存储、文件指纹、数据去重、区块链

// <inheritdoc cref="SHA256Crypt.Encrypt"/>
string sha256Hash = SHA256Crypt.Encrypt("需要哈希的数据");

// <inheritdoc cref="SHA384Crypt.Encrypt"/>
string sha384Hash = SHA384Crypt.Encrypt("需要哈希的数据");

// <inheritdoc cref="SHA512Crypt.Encrypt"/>
string sha512Hash = SHA512Crypt.Encrypt("需要哈希的数据");

// <inheritdoc cref="SHA1Crypt.Encrypt"/>
string sha1Hash   = SHA1Crypt.Encrypt("兼容旧系统的 SHA-1");

MD5（三合一）

// <inheritdoc cref="Md5Crypt.Encrypt"/>
// 标准 32 位 MD5（十六进制大写）
string md5_32 = Md5Crypt.Encrypt("input", EnumMD5Length.L32);

// 截断 16 位 MD5（取中间 8 字节，16 个十六进制字符）
string md5_16 = Md5Crypt.Encrypt("input", EnumMD5Length.L16);

// <inheritdoc cref="Md5Crypt.Hash"/>
// 32 位 MD5（小写）—— 已改为 UTF-8 编码，跨平台一致
string md5Lower = Md5Crypt.Hash("input");

// <inheritdoc cref="Md5Crypt.JsMD5"/>
// JsMD5（小写，兼容前端 JavaScript MD5 库）
string jsMd5 = Md5Crypt.JsMD5("input");

✅ 已修复: Md5Crypt.Hash 已改用 Encoding.UTF8 替代 Encoding.Default，跨平台哈希结果一致。

场景三：消息认证码（HMAC）

┌────────┐    HMAC(algorithm, key)     ┌──────────────┐
│  消息   │ ────────────────────────▶  │  HMAC 签名    │
│ string  │                            │  (十六进制)    │
│  + key  │                            └──────────────┘
└────────┘  用例: API 签名、防篡改令牌、JWT

// <inheritdoc cref="HMACSHA256Crypt.Encrypt"/>
string hmacSha256 = HMACSHA256Crypt.Encrypt(
    srcString: "GET\n/api/orders\n1700000000",
    key:       "your-api-secret"
);

// <inheritdoc cref="HMACSHA512Crypt.Encrypt"/>
string hmacSha512 = HMACSHA512Crypt.Encrypt("payload", "key");

// <inheritdoc cref="HMACSHA1Crypt.Encrypt"/>
string hmacSha1   = HMACSHA1Crypt.Encrypt("payload", "key");

// <inheritdoc cref="HMACSHA384Crypt.Encrypt"/>
string hmacSha384 = HMACSHA384Crypt.Encrypt("payload", "key");

// <inheritdoc cref="Md5Crypt.HMACMD5"/>
string hmacMd5    = Md5Crypt.HMACMD5("payload", "key");

API 签名验证示例

// <inheritdoc>
public static class ApiSignatureValidator
{
    /// <summary>
    /// 使用 HMAC-SHA256 生成 API 请求签名
    /// </summary>
    public static string Sign(string method, string path, long timestamp, string secret)
    {
        var payload = $"{method}\n{path}\n{timestamp}";
        return HMACSHA256Crypt.Encrypt(payload, secret);
    }

    /// <summary>
    /// 验证签名（恒定时间比较以避免时序攻击）
    /// </summary>
    public static bool Verify(string signature, string method, string path,
        long timestamp, string secret, TimeSpan maxAge)
    {
        // 1. 检查时间戳新鲜度（防重放攻击）
        var requestTime = DateTimeOffset.FromUnixTimeSeconds(timestamp);
        if (DateTimeOffset.UtcNow - requestTime > maxAge)
            return false;

        // 2. 重新计算签名并比较
        var expected = Sign(method, path, timestamp, secret);
        return CryptographicOperations.FixedTimeEquals(
            Encoding.UTF8.GetBytes(expected),
            Encoding.UTF8.GetBytes(signature));
    }
}

场景四：非对称加密（RSA）

┌──────────┐                                      ┌──────────┐
│  发送方   │  ① 获取公钥                           │  接收方   │
│          │ ◀─────────────────────────────────   │          │
│          │                                      │          │
│          │  ② RSA.Encrypt(data, publicKey)       │          │
│          │ ─────────────────────────────────▶   │          │
│          │      (Base64 密文)                     │          │
│          │                                      │          │
│          │                         ③ RSA.Decrypt(cipher, privateKey)
│          │                                      │          │
└──────────┘                                      └──────────┘

// <inheritdoc cref="RSACrypt.GenerateSecretKey"/>
// 生成密钥对（返回 ValueTuple）
(string publicKey, string privateKey) = RSACrypt.GenerateSecretKey(keySize: 2048);

// 保存私钥（安全存储！切勿提交到版本控制）
await File.WriteAllTextAsync("private.key", privateKey);

// <inheritdoc cref="RSACrypt.Encrypt"/>
string cipher = RSACrypt.Encrypt(
    text:      "AES 会话密钥: x7K9mP2qR5vW8zB3",
    publicKey: publicKey,
    keySize:   2048
);

// <inheritdoc cref="RSACrypt.Decrypt"/>
string sessionKey = RSACrypt.Decrypt(
    text:       cipher,
    privateKey: privateKey,
    keySize:    2048
);

自定义 RSA XML 密钥格式

// <inheritdoc cref="RSAKeyExtensions.ToLvccXmlString"/>
using var rsa = RSA.Create();
string customXml = rsa.ToLvccXmlString(includePrivateParameters: true);

// <inheritdoc cref="RSAKeyExtensions.FromLvccXmlString"/>
using var rsa2 = RSA.Create();
rsa2.FromLvccXmlString(customXml);

⚠️ 线程安全: RSACrypt 为纯静态方法，每次调用都创建新的 RSACryptoServiceProvider 实例，因此天然线程安全。

❗ 性能陷阱: RSA 加密/解密是 CPU 密集型操作。对于大量数据，推荐混合加密：用 RSA 加密 AES 密钥，用 AES 加密实际数据。

场景五：Base64 编解码

// <inheritdoc cref="Base64Crypt.Base64Encrypt(string)"/>
// 默认 UTF-8 编码
string encoded = Base64Crypt.Base64Encrypt("Hello, 世界!");
// → "SGVsbG8sIOS4lueVjCE="

// <inheritdoc cref="Base64Crypt.Base64Decrypt(string)"/>
string decoded = Base64Crypt.Base64Decrypt(encoded);
// → "Hello, 世界!"

// 自定义编码
string encodedGbk = Base64Crypt.Base64Encrypt("中文", Encoding.GetEncoding("GBK"));
string decodedGbk = Base64Crypt.Base64Decrypt(encodedGbk, Encoding.GetEncoding("GBK"));

场景六：机器密钥生成

// <inheritdoc cref="MachineKey.CreateDecryptionKey"/>
// 解密密钥：长度 16–48（推荐 48）
string decryptionKey = MachineKey.CreateDecryptionKey(length: 48);

// <inheritdoc cref="MachineKey.CreateValidationKey"/>
// 验证密钥：长度 48–128（推荐 128）
string validationKey = MachineKey.CreateValidationKey(length: 128);

使用 RandomNumberGenerator.Create() 生成密码学安全的随机字节，适用于 ASP.NET machineKey 配置场景。

场景七：流畅扩展方法

using RuoVea.ExCrypt; // 扩展方法在此命名空间

// <inheritdoc cref="StringExtensions.ToMD5Encrypt"/>
string md5_32 = "hello".ToMD5Encrypt();                // 默认 32 位
string md5_16 = "hello".ToMD5Encrypt(EnumMD5Length.L16);

// <inheritdoc cref="StringExtensions.ToAESEncrypt"/>
string aesEnc = "敏感数据".ToAESEncrypt("your-32-char-key-here!!!!!!!");

// <inheritdoc cref="StringExtensions.ToAESDecrypt"/>
string aesDec = aesEnc.ToAESDecrypt("your-32-char-key-here!!!!!!!");

// <inheritdoc cref="StringExtensions.ToDESCEncrypt"/>
string desEnc = "数据".ToDESCEncrypt("your-24-char-key-right-here");

// <inheritdoc cref="StringExtensions.ToDESCDecrypt"/>
string desDec = desEnc.ToDESCDecrypt("your-24-char-key-right-here");

// <inheritdoc cref="StringExtensions.ToRSAEncrpyt"/>
string rsaEnc = "机密".ToRSAEncrpyt(publicKey);

// <inheritdoc cref="StringExtensions.ToRSADecrypt"/>
string rsaDec = rsaEnc.ToRSADecrypt(privateKey);

⚙️ 配置选项详解

AES 配置

TripleDES 配置

RSA 配置

MD5 配置

MachineKey 配置

🛡️ 错误处理与日志

异常体系

所有公共 API 在入参不合法时会抛出 ArgumentException（含本地化消息）：

// AES 密钥长度错误 → ArgumentException
//   → "密钥的长度必须等于32。"
//   → "The length of key must equal to 32."
//   → "La longueur de key doit être égale à 32."
AESCrypt.AESEncrypt("data", "too-short"); // ❌ ArgumentException

加密失败静默处理

AES 和 TripleDES 的 Encrypt/Decrypt 方法在 CryptoStream 异常时返回 null（而非抛出），由调用方决定如何处理：

// <inheritdoc>
string result = AESCrypt.AESDecrypt(malformedCipher, key, iv);

if (result == null)
{
    // 记录日志并降级
    _logger.LogWarning("AES 解密失败，密文可能已损坏或密钥不匹配");
    return FallbackValue;
}

推荐日志模式

// <inheritdoc>
using Microsoft.Extensions.Logging;

public class SecureDataService
{
    private readonly ILogger<SecureDataService> _logger;

    public SecureDataService(ILogger<SecureDataService> logger) => _logger = logger;

    public string? DecryptSafe(string cipher, string key, string iv)
    {
        try
        {
            var result = AESCrypt.AESDecrypt(cipher, key, iv);
            if (result == null)
                _logger.LogWarning("AES 解密返回 null，密文: {CipherPreview}...",
                    cipher[..Math.Min(cipher.Length, 16)]);
            return result;
        }
        catch (ArgumentException ex)
        {
            _logger.LogError(ex, "AES 解密参数校验失败");
            throw; // 参数错误应当暴露给调用方
        }
        catch (FormatException ex)
        {
            _logger.LogError(ex, "Base64 解密时密文格式非法");
            return null;
        }
    }
}

🧵 线程安全

CreateAesKey() / CreateDesKey() / CreateDesIv() 内部已加锁保护，多线程安全。

📊 算法速查表

🌍 国际化

错误消息支持以下语言，根据 CultureInfo.CurrentUICulture 自动切换：

// 当前线程 UI 文化为 fr-FR 时：
// ArgumentException → "La longueur de key doit être égale à 32."
AESCrypt.AESEncrypt("data", "short-key");

🗺️ 版本迁移指南

从旧自研加密代码迁移

v8.0.x → v10.0.x

• API 无变化。v10.0.x 仅在 net10.0 TFM 上编译，所有公开 API 签名保持一致。
• 包引用依赖 Portable.BouncyCastle 1.9.0 目前未被实际使用（保留以备未来扩展）。

📄 License

MIT License © RuoVea

🔗 相关资源: NuGet Gallery · 问题反馈