跳转到内容

ChaCha20Poly1305Helper

ChaCha20Poly1305Helper 是一个静态帮助类,封装了 ChaCha20-Poly1305 AEAD 认证加密的常用操作。net8.0 下使用 BCL ChaCha20Poly1305,netstandard2.1 下回退至 BouncyCastle 实现。输出格式为 密文 || 16 字节 Tag,解密时取末尾 16 字节作为 Tag 进行校验。

  • 🏷️ AEAD 认证加密 — 同时保证机密性与完整性,Tag 校验失败抛出 CryptographicException
  • 📦 统一输出格式 — 密文 || 16 字节 Tag 拼接返回,便于传输与存储
  • 🔑 密钥规范化 — 字符串重载自动将密钥规范化为 256 位、nonce 为 96 位
  • 📋 双双重载 — 提供 string 与 byte[] 两套重载
  • 🔄 跨平台一致 — 多目标 netstandard2.1 + net8.0,polyfill 统一行为
  • 🎲 密钥与 nonce 生成 — 内置 GenerateKey / GenerateNonce 工具方法
namespace Chet.Security;
public static class ChaCha20Poly1305Helper

加密 UTF-8 明文,返回 Base64 密文(密文 || 16 字节 Tag)。密钥规范化为 256 位,nonce 规范化为 96 位。

public static string Encrypt(string plain, string key, string nonce)
参数名类型描述
plainstring明文字符串
keystring密钥(任意长度,将规范化为 256 位)
noncestring12 字节 nonce(任意长度,将规范化为 96 位)

返回值: Base64 编码的 密文 || Tag。

示例:

using Chet.Security;
string cipher = ChaCha20Poly1305Helper.Encrypt("hello world", "my-password", "my-nonce");

解密 Base64 密文(密文 || 16 字节 Tag)为 UTF-8 明文。密钥规范化为 256 位,nonce 规范化为 96 位。

public static string Decrypt(string cipherBase64, string key, string nonce)
参数名类型描述
cipherBase64stringBase64 编码的 `密文
keystring密钥(任意长度,将规范化为 256 位)
noncestring12 字节 nonce(任意长度,将规范化为 96 位)

返回值: UTF-8 明文字符串。

示例:

using Chet.Security;
string cipher = ChaCha20Poly1305Helper.Encrypt("hello world", "my-password", "my-nonce");
string plain = ChaCha20Poly1305Helper.Decrypt(cipher, "my-password", "my-nonce");

加密字节数组,返回 密文 || 16 字节 Tag。

public static byte[] Encrypt(byte[] plain, byte[] key, byte[] nonce)
参数名类型描述
plainbyte[]明文字节数组
keybyte[]32 字节密钥
noncebyte[]12 字节 nonce

返回值: 密文与 16 字节 Tag 的拼接字节数组。

示例:

using Chet.Security;
byte[] key = Convert.FromBase64String(ChaCha20Poly1305Helper.GenerateKey());
byte[] nonce = Convert.FromBase64String(ChaCha20Poly1305Helper.GenerateNonce());
byte[] cipher = ChaCha20Poly1305Helper.Encrypt(
System.Text.Encoding.UTF8.GetBytes("hello"), key, nonce);

解密密文(密文 || 16 字节 Tag)。Tag 校验失败时抛出 CryptographicException。

public static byte[] Decrypt(byte[] cipher, byte[] key, byte[] nonce)
参数名类型描述
cipherbyte[]密文与 16 字节 Tag 的拼接字节数组
keybyte[]32 字节密钥
noncebyte[]12 字节 nonce

返回值: 明文字节数组。

示例:

using Chet.Security;
byte[] key = Convert.FromBase64String(ChaCha20Poly1305Helper.GenerateKey());
byte[] nonce = Convert.FromBase64String(ChaCha20Poly1305Helper.GenerateNonce());
byte[] cipher = ChaCha20Poly1305Helper.Encrypt(
System.Text.Encoding.UTF8.GetBytes("hello"), key, nonce);
byte[] plain = ChaCha20Poly1305Helper.Decrypt(cipher, key, nonce);

生成 12 字节随机 nonce,返回 Base64 字符串。

public static string GenerateNonce()

返回值: Base64 编码的 12 字节 nonce。

示例:

using Chet.Security;
string nonce = ChaCha20Poly1305Helper.GenerateNonce();

生成 32 字节随机密钥,返回 Base64 字符串。

public static string GenerateKey()

返回值: Base64 编码的 32 字节密钥。

示例:

using Chet.Security;
string key = ChaCha20Poly1305Helper.GenerateKey();