Sage.Encryption 1.0.0.1

Sage.Encryption

概述

Sage.Encryption是一个功能强大的.NET加密库，提供了简单易用的API来实现数据加密、解密和安全存储。该库支持多种加密算法和模式，包括AES-CBC和AES-GCM，同时提供了Windows平台上的安全数据存储功能。

功能特点

• 支持AES-CBC和AES-GCM加密算法
• 提供同步和异步API
• 支持字符串和字节数组的加密和解密
• 提供Base64和十六进制编码的扩展方法
• 基于Windows DPAPI的安全数据存储
• 完全支持AOT编译
• 简单易用的API设计

安装

通过NuGet包管理器安装：

Install-Package Sage.Encryption

或者使用.NET CLI：

dotnet add package Sage.Encryption

使用示例

基本加密和解密

使用AES-CBC加密

// 创建AES加密服务实例（使用密码和盐值）
using var encryptionService = new AesEncryptionService("your-secure-password", "your-salt-value");

// 加密字符串
string plainText = "需要加密的敏感数据";
string encryptedBase64 = encryptionService.EncryptToBase64String(plainText);

// 解密字符串
string decryptedText = encryptionService.DecryptFromBase64String(encryptedBase64);

使用AES-GCM加密（更安全的选择）

// 创建AES-GCM加密服务实例
using var encryptionService = new AesGcmEncryptionService("your-secure-password", "your-salt-value");

// 加密字符串
string plainText = "需要加密的敏感数据";
string encryptedHex = encryptionService.EncryptToHexString(plainText);

// 解密字符串
string decryptedText = encryptionService.DecryptFromHexString(encryptedHex);

异步加密和解密

// 创建加密服务实例
using var encryptionService = new AesGcmEncryptionService("your-secure-password", "your-salt-value");

// 异步加密
string plainText = "需要加密的敏感数据";
string encryptedBase64 = await encryptionService.EncryptToBase64StringAsync(plainText);

// 异步解密
string decryptedText = await encryptionService.DecryptFromBase64StringAsync(encryptedBase64);

使用随机生成的密钥和IV

// 生成随机密钥和IV
var (key, iv) = AesEncryptionService.GenerateRandomKeyAndIv();

// 使用生成的密钥和IV创建加密服务
using var encryptionService = new AesEncryptionService(key, iv);

// 加密数据
string plainText = "需要加密的敏感数据";
byte[] encryptedBytes = encryptionService.Encrypt(plainText);

// 解密数据
string decryptedText = encryptionService.DecryptToString(encryptedBytes);

依赖注入配置

在ASP.NET Core或其他支持依赖注入的应用程序中，可以这样配置加密服务：

// 在Program.cs或Startup.cs中

// 添加配置
builder.Services.Configure<EncryptionOptions>(builder.Configuration.GetSection(EncryptionOptions.SectionName));

// 注册AES-GCM加密服务（推荐）
builder.Services.AddSingleton<IEncryptionService>(provider => {
    var options = provider.GetRequiredService<IOptions<EncryptionOptions>>().Value;
    return new AesGcmEncryptionService(options.Password, options.Salt, options.Iterations);
});

// 或者注册AES-CBC加密服务
// builder.Services.AddSingleton<IEncryptionService>(provider => {
//     var options = provider.GetRequiredService<IOptions<EncryptionOptions>>().Value;
//     return new AesEncryptionService(options.Password, options.Salt, options.Iterations);
// });

在appsettings.json中配置：

{
  "Encryption": {
    "Password": "your-secure-password",
    "Salt": "your-salt-value",
    "Iterations": 10000
  }
}

使用Windows安全数据存储

在Windows平台上，可以使用WindowsSecureDataStorage类安全地存储敏感数据：

// 创建源生成的JSON上下文
[JsonSerializable(typeof(UserCredentials))]
public partial class AppJsonContext : JsonSerializerContext { }

// 定义数据模型
public class UserCredentials
{
    public string Username { get; set; } = "";
    public string Password { get; set; } = "";
    public string ApiKey { get; set; } = "";
}

// 使用安全存储
var secureStorage = new WindowsSecureDataStorage("YourCompany", "YourApp");

// 存储数据
var credentials = new UserCredentials
{
    Username = "user@example.com",
    Password = "secure-password",
    ApiKey = "api-key-value"
};

secureStorage.SaveData("user-credentials", credentials, AppJsonContext.Default.UserCredentials);

// 读取数据
if (secureStorage.TryGetData("user-credentials", AppJsonContext.Default.UserCredentials, out var savedCredentials))
{
    Console.WriteLine($"Username: {savedCredentials.Username}");
    Console.WriteLine($"API Key: {savedCredentials.ApiKey}");
}

// 更新数据
secureStorage.UpdateData(
    "user-credentials",
    cred => {
        cred.ApiKey = "new-api-key";
        return cred;
    },
    new UserCredentials(),
    AppJsonContext.Default.UserCredentials
);

// 检查数据是否存在
bool exists = secureStorage.DataExists("user-credentials");

// 删除数据
secureStorage.DeleteData("user-credentials");

最佳实践

1. 选择合适的加密算法：对于需要更高安全性的场景，推荐使用AesGcmEncryptionService，它提供了认证加密功能。

2. 安全管理密钥：不要在代码中硬编码密钥和盐值，应该使用配置系统或环境变量来管理这些敏感信息。

3. 使用using语句：加密服务类实现了IDisposable接口，使用完毕后应当正确释放资源。

4. 异常处理：在生产环境中，应当妥善处理加密和解密过程中可能出现的异常。

5. 密码强度：使用足够强度的密码和盐值，避免使用简单或可预测的值。

注意事项

• WindowsSecureDataStorage仅在Windows平台上可用，它使用Windows DPAPI进行数据保护。
• 加密数据的安全性取决于密钥的安全性，请确保妥善保管密钥。
• 在使用AesGcmEncryptionService时，每次加密操作都会生成随机nonce，这意味着即使是相同的明文，每次加密后的密文也会不同。

许可证

本项目采用 Apache 2.0 许可证。详情请参阅 LICENSE 文件。

贡献

欢迎提交问题报告和改进建议。如果您想贡献代码，请提交拉取请求。

作者

• LiuPengLai - 甲壳虫科技 欢迎提交问题和功能请求。 QQ Group: 1054304346