BugFree.Security.Key 1.1.2026.118-beta1029

BugFree.Security.Key

企业级密钥全生命周期管理组件，支持对称和非对称密钥的存储、轮换和泄露检测

概述

BugFree.Security.Key 是 BugFree 框架的密钥管理组件，提供密钥的完整生命周期管理功能。采用完全委托模式，零依赖 BugFree.Security，专注于密钥的存储、轮换、访问控制和策略管理。

核心特性

• 🔐 全生命周期管理：密钥创建、存储、轮换、归档、销毁
• 🔄 自动轮换：基于时间、使用次数或策略的自动密钥轮换
• 💾 多种存储后端：文件存储（默认）、内存存储
• 📊 密钥版本控制：支持多版本密钥共存，加密用最新，解密用指定版本
• 🎯 完全委托模式：零依赖 BugFree.Security，算法实现由调用方提供
• 🚀 依赖注入友好：原生支持 Microsoft.Extensions.DependencyInjection
• 📝 访问审计：可选的密钥访问日志记录
• 🔍 泄露检测：密钥泄露标记和响应机制

目标框架

• net8.0 和 net10.0 多目标框架

设计理念

完全委托模式：本组件不依赖任何加密算法实现，密钥的生成完全由调用方通过委托提供。这使得组件可以与任何加密库（如 BugFree.Security、BouncyCastle、系统 API 等）无缝集成。

架构设计

核心组件

BugFree.Security.Key
├── KeyManager                 # 统一门面（对外主要接口）
├── Abstractions/
│   ├── IKeyManager            # 密钥管理器接口
│   ├── IKeyStore              # 密钥存储接口
│   ├── IKeyResolver           # 密钥解析器接口
│   ├── IKeyRotator            # 密钥轮换器接口
│   ├── IKeyPolicyEvaluator    # 密钥策略评估器接口
│   └── KeyGenerator.cs        # 委托类型定义
├── Core/
│   ├── DefaultKeyResolver     # 默认密钥解析器实现
│   ├── DefaultKeyRotator      # 默认密钥轮换器实现
│   ├── DefaultKeyPolicyEvaluator  # 默认策略评估器实现
│   └── Store/
│       ├── FileKeyStore       # 文件存储实现（默认）
│       └── MemoryKeyStore     # 内存存储实现
├── Models/
│   ├── KeyRecord              # 密钥记录（含密钥材料）
│   ├── KeyMetadata            # 密钥元数据（不含密钥材料）
│   ├── KeyPolicy              # 密钥策略
│   ├── KeyStatus              # 密钥状态枚举
│   └── KeyPurpose             # 密钥用途枚举
└── ServiceCollectionExtensions.cs     # DI 扩展方法

设计模式

• 门面模式（Facade）：KeyManager 作为统一入口，封装内部复杂性
• 策略模式（Strategy）：通过 IKeyStore 支持多种存储后端
• 委托模式（Delegate）：密钥生成由调用方提供，实现零依赖
• 仓库模式（Repository）：IKeyStore 提供密钥持久化抽象
• 工厂模式（Factory）：通过 DI 动态创建组件实例

核心概念

密钥生命周期

创建 → Active（活跃） → DecryptOnly（仅解密，已轮换） → Retired（退役） → 销毁
                           ↓
                        Compromised（已泄露） → 强制轮换

密钥状态（KeyStatus）

密钥用途（KeyPurpose）

密钥策略（KeyPolicy）

public class KeyPolicy
{
    /// <summary>轮换间隔，默认 90 天</summary>
    public TimeSpan RotationInterval { get; set; } = TimeSpan.FromDays(90);

    /// <summary>最大使用次数，默认 1000 次</summary>
    public Int32 MaxUsageCount { get; set; } = 1000;

    /// <summary>过期日期，可选</summary>
    public DateTime? ExpirationDate { get; set; }

    /// <summary>是否启用自动轮换，默认 true</summary>
    public Boolean EnableAutoRotation { get; set; } = true;
}

存储实现

文件存储（FileKeyStore）：

• 每个 KeyId + Version 对应一个 JSON 文件
• 文件命名规则：{keyId}_v{version}.json
• 默认存储目录：AppContext.BaseDirectory/KeyStore
• 支持自定义存储目录
• 使用内存缓存提高读取性能

快速开始

基础用法

1. 配置密钥管理服务

using BugFree.Security.Key;
using BugFree.Security.Key.Core.Store;
using Microsoft.Extensions.DependencyInjection;

// 配置依赖注入
var services = new ServiceCollection();

// 方式一：使用默认文件存储（推荐）
services.AddKeyManagement();

// 方式二：指定自定义密钥存储
services.AddKeyManagement(
    keyStore: new FileKeyStore("./custom-keys")
);

// 方式三：使用内存存储（仅用于开发/测试）
services.AddKeyManagement(
    keyStore: new MemoryKeyStore()
);

var serviceProvider = services.BuildServiceProvider();
var keyManager = serviceProvider.GetRequiredService<IKeyManager>();

2. 对称密钥管理

using System.Security.Cryptography;
using BugFree.Security.Key;

// 确保（或创建）对称密钥（自动轮换）
var keyRecord = keyManager.EnsureFreshSymmetricKey(
    keyId: "user-data-key",
    keyGenerator: () =>
    {
        // 委托给调用方生成密钥（零依赖 BugFree.Security）
        var algorithm = "AES-GCM";
        var keySize = 32; // AES-256
        return (algorithm, RandomNumberGenerator.GetBytes(keySize));
    },
    policy: new KeyPolicy
    {
        RotationInterval = TimeSpan.FromDays(90),
        MaxUsageCount = 1000,
        EnableAutoRotation = true
    }
);

Console.WriteLine($"Key ID: {keyRecord.KeyId}");
Console.WriteLine($"Version: {keyRecord.Version}");
Console.WriteLine($"Algorithm: {keyRecord.AlgorithmName}");
Console.WriteLine($"Status: {keyRecord.Metadata.Status}");
Console.WriteLine($"Created: {keyRecord.Metadata.CreatedAt}");

// 获取密钥用于加密（最新 Active 状态）
var encryptionKey = keyManager.ResolveForEncryption("user-data-key");

// 获取指定版本的密钥用于解密（支持 DecryptOnly 状态）
var decryptionKey = keyManager.ResolveForDecryption("user-data-key", version: 1);

// 检查是否需要轮换
var shouldRotate = keyManager.ShouldRotateKey("user-data-key");
Console.WriteLine($"Should rotate: {shouldRotate}");

3. 非对称密钥管理

// 确保（或创建）非对称密钥对（自动轮换）
var keyRecord = keyManager.EnsureFreshAsymmetricKey(
    keyId: "signing-key",
    keyGenerator: () =>
    {
        // 委托给调用方生成密钥对
        // 这里可以使用 BugFree.Security 或其他库
        var asymmetricService = AsymmetricService.Instance;
        var keyPair = asymmetricService.GenerateKeyPair(
            KeyPairGeneratorProviderType.ECDSA
        );
        return ("ECDSA", keyPair.PublicKey, keyPair.PrivateKey);
    },
    policy: new KeyPolicy
    {
        RotationInterval = TimeSpan.FromDays(180),
        EnableAutoRotation = true
    }
);

Console.WriteLine($"Key ID: {keyRecord.KeyId}");
Console.WriteLine($"Version: {keyRecord.Version}");
Console.WriteLine($"Has Public Key: {keyRecord.PublicKey != null}");
Console.WriteLine($"Has Private Key: {keyRecord.PrivateKey != null}");

// 获取密钥用于签名（最新 Active 状态）
var signingKey = keyManager.ResolveForSigning("signing-key");

// 获取指定版本的密钥用于验签（支持 DecryptOnly 状态）
var verificationKey = keyManager.ResolveForVerification("signing-key", version: 1);

4. 密钥查询和管理

// 获取所有密钥的元数据
var allKeys = keyManager.GetAllKeys();
foreach (var metadata in allKeys)
{
    Console.WriteLine($"Key: {metadata.KeyId}, Version: {metadata.Version}, Status: {metadata.Status}");
}

// 获取指定密钥的所有版本
var versions = keyManager.GetKeyVersions("user-data-key");
foreach (var metadata in versions)
{
    Console.WriteLine($"Version {metadata.Version}: {metadata.Status}, Created: {metadata.CreatedAt}");
}

// 获取指定版本的密钥记录（包含密钥材料）
var key = keyManager.GetKey("user-data-key", version: 1);
if (key != null)
{
    Console.WriteLine($"Algorithm: {key.AlgorithmName}");
    Console.WriteLine($"Has Key: {key.Key != null}");
}

// 删除指定版本的密钥
keyManager.DeleteKey("user-data-key", version: 1);

// 删除密钥的所有版本
keyManager.DeleteKey("user-data-key");

与 BugFree.Security 集成

using BugFree.Security;
using BugFree.Security.Key;
using Microsoft.Extensions.DependencyInjection;

// 配置密钥管理服务
var services = new ServiceCollection();
services.AddKeyManagement();
var serviceProvider = services.BuildServiceProvider();
var keyManager = serviceProvider.GetRequiredService<IKeyManager>();

// 创建 KeyedCryptoService（自动轮换密钥）
var cryptoService = new KeyedCryptoService(keyManager);

// 对称加密（自动使用最新密钥）
var result = cryptoService.Encrypt(
    SymmetricType.AesGcm,
    "user-data-key",
    Encoding.UTF8.GetBytes("Sensitive Data")
);

Console.WriteLine($"Encrypted with key version: {result.Version}");

// 对称解密（指定密钥版本）
var decrypted = cryptoService.Decrypt(
    SymmetricType.AesGcm,
    result.Value.Ciphertext,
    "user-data-key",
    result.Version,
    new SymmetricDecryptOptions
    {
        Nonce = result.Value.Nonce,
        Tag = result.Value.Tag
    }
);

// 非对称签名（自动使用最新密钥）
var signature = cryptoService.Sign(
    SignatureProviderType.ECDSA,
    KeyPairGeneratorProviderType.ECDSA,
    Encoding.UTF8.GetBytes("Important Document"),
    "signing-key"
);

// 验签（指定密钥版本）
var isValid = cryptoService.Verify(
    SignatureProviderType.ECDSA,
    Encoding.UTF8.GetBytes("Important Document"),
    signature.Value,
    "signing-key",
    signature.Version
);

高级用法

自定义密钥存储

using BugFree.Security.Key.Abstractions;

// 实现 IKeyStore 接口
public class CustomKeyStore : IKeyStore
{
    public KeyStoreType StoreType => KeyStoreType.Custom;

    public KeyRecord? GetKey(string keyId, int version)
    {
        // 从自定义存储中读取密钥
        throw new NotImplementedException();
    }

    public KeyRecord? GetLatestKey(string keyId)
    {
        // 获取最新版本的密钥
        throw new NotImplementedException();
    }

    public KeyMetadata? GetMetadata(string keyId, int version)
    {
        // 获取密钥元数据
        throw new NotImplementedException();
    }

    public void Save(KeyRecord key)
    {
        // 保存密钥到自定义后端
        throw new NotImplementedException();
    }

    public void Delete(KeyRecord key)
    {
        // 从自定义后端删除密钥
        throw new NotImplementedException();
    }

    public IEnumerable<KeyMetadata> GetAllMetadata()
    {
        // 返回所有密钥的元数据
        throw new NotImplementedException();
    }

    public void RemoveExpired(Func<KeyMetadata, bool> expired)
    {
        // 移除过期记录
        throw new NotImplementedException();
    }
}

// 注册自定义存储
services.AddSingleton<IKeyStore, CustomKeyStore>();

自定义密钥策略评估器

using BugFree.Security.Key.Abstractions;

public class CustomKeyPolicyEvaluator : IKeyPolicyEvaluator
{
    public bool ShouldRotate(KeyRecord key)
    {
        // 自定义轮换逻辑
        if (key.Metadata.UsageCount >= key.Metadata.Policy.MaxUsageCount)
            return true;

        if (key.Metadata.CreatedAt.Add(key.Metadata.Policy.RotationInterval) <= DateTime.UtcNow)
            return true;

        if (key.Metadata.Policy.ExpirationDate.HasValue &&
            key.Metadata.Policy.ExpirationDate.Value <= DateTime.UtcNow)
            return true;

        // 添加自定义条件
        if (IsCompromised(key))
            return true;

        return false;
    }

    private bool IsCompromised(KeyRecord key)
    {
        // 检查密钥是否泄露
        return key.Metadata.Status == KeyStatus.Compromised;
    }
}

// 注册自定义评估器
services.AddSingleton<IKeyPolicyEvaluator, CustomKeyPolicyEvaluator>();

密钥泄露检测和响应

// 标记密钥为已泄露
var key = keyManager.GetKey("signing-key", version: 1);
if (key != null)
{
    key.Metadata.Status = KeyStatus.Compromised;
    key.Metadata.RevokedAt = DateTime.UtcNow;
    key.Metadata.RevocationReason = "Key compromise detected";

    // 保存更新
    // keyManager 需要暴露 Save 方法或通过其他方式更新

    // 强制轮换（通过 EnsureFreshAsymmetricKey）
    var newKey = keyManager.EnsureFreshAsymmetricKey(
        "signing-key",
        keyGenerator: () =>
        {
            var asymmetricService = AsymmetricService.Instance;
            var keyPair = asymmetricService.GenerateKeyPair(
                KeyPairGeneratorProviderType.ECDSA
            );
            return ("ECDSA", keyPair.PublicKey, keyPair.PrivateKey);
        },
        policy: new KeyPolicy { EnableAutoRotation = true }
    );

    Console.WriteLine($"Rotated to version: {newKey.Version}");
}

直接使用 KeyManager（不通过 DI）

// 不使用 DI，直接创建 KeyManager
var keyManager = new KeyManager(
    keyStore: new FileKeyStore("./custom-keys"),
    keyResolver: null,  // 使用默认
    keyRotator: null,    // 使用默认
    keyPolicyEvaluator: null  // 使用默认
);

// 使用方式相同
var keyRecord = keyManager.EnsureFreshSymmetricKey(
    "my-key",
    () => ("AES", RandomNumberGenerator.GetBytes(32))
);

安全注意事项

密钥存储

• ✅ 文件存储：默认使用文件存储，密钥以 JSON 格式保存到磁盘
• ✅ 访问控制：确保密钥存储目录有正确的文件系统权限（仅允许应用程序访问）
• ✅ 生产环境：推荐使用专业密钥管理服务（HSM/KMS）
• ❌ 内存存储：仅用于开发和测试，不适用于生产环境（应用重启后丢失）

密钥轮换

• ✅ 定期轮换：推荐对称密钥 90 天，非对称密钥 180 天
• ✅ 使用次数限制：设置合理的 MaxUsageCount 防止密钥过度使用
• ✅ 平滑轮换：新密钥用于加密，旧密钥保留用于解密历史数据
• ⚠️ 归档策略：制定密钥归档和销毁策略
• ⚠️ 保留期限：旧密钥必须保留足够长时间以解密历史数据

密钥访问

• ✅ 访问审计：启用 EnableAccessLogging 记录密钥访问
• ✅ 最小权限：仅授予必要的密钥访问权限
• ✅ 密钥分离：加密密钥和签名密钥分离使用
• ❌ 日志记录：禁止在日志中输出密钥材料
• ❌ 异常处理：密钥访问异常不应泄露密钥信息

密钥生成

• ✅ 强随机数：使用 RandomNumberGenerator 或 RandomNumberGenerator.GetBytes 生成密钥
• ✅ 密钥长度：AES 推荐 256 位（32 字节），RSA 推荐 2048 位以上
• ✅ 算法选择：优先使用 AES-GCM、ECDSA、Ed25519 等现代算法
• ✅ 唯一性：每个密钥 ID 应该有唯一且描述性的名称

最佳实践

1. 密钥命名规范

// 好的命名（包含用途和环境）
"user-data-encryption-prod"
"api-signing-key-staging"
"session-key-cache"
"database-encryption-primary"

// 避免的命名（过于简单或含糊）
"key1"
"test"
"my-key"
"encryption"

2. 密钥策略配置

// 生产环境策略
var productionPolicy = new KeyPolicy
{
    RotationInterval = TimeSpan.FromDays(90),
    MaxUsageCount = 1000,
    EnableAutoRotation = true,
    ExpirationDate = DateTime.UtcNow.AddYears(1)
};

// 开发环境策略
var developmentPolicy = new KeyPolicy
{
#if DEBUG
    RotationInterval = TimeSpan.FromSeconds(30),  // 便于测试
#else
    RotationInterval = TimeSpan.FromDays(90),
#endif
    MaxUsageCount = 10000,  // 宽松限制
    EnableAutoRotation = true
};

// 高安全场景策略
var highSecurityPolicy = new KeyPolicy
{
    RotationInterval = TimeSpan.FromDays(30),  // 更短的轮换周期
    MaxUsageCount = 100,  // 更严格的使用限制
    EnableAutoRotation = true,
    ExpirationDate = DateTime.UtcNow.AddMonths(6)
};

3. 密钥生命周期管理

// 1. 创建密钥（首次使用时）
var key = keyManager.EnsureFreshSymmetricKey(
    "my-encryption-key",
    () => ("AES-GCM", RandomNumberGenerator.GetBytes(32))
);

// 2. 使用密钥加密数据
var ciphertext = EncryptWithKey(key.Key, data);

// 3. 保存密钥版本号（与密文一起）
SaveToDatabase(ciphertext, key.Version);

// 4. 解密时使用相同版本
var storedKey = keyManager.GetKey("my-encryption-key", version);
if (storedKey != null)
{
    var plaintext = DecryptWithKey(storedKey.Key, ciphertext);
}

// 5. 定期轮换密钥（自动或手动）
if (keyManager.ShouldRotateKey("my-encryption-key"))
{
    var newKey = keyManager.EnsureFreshSymmetricKey(
        "my-encryption-key",
        () => ("AES-GCM", RandomNumberGenerator.GetBytes(32))
    );
    Console.WriteLine($"Rotated from version {newKey.Version - 1} to {newKey.Version}");
}

// 6. 归档旧密钥（保留足够长时间）
// 密钥不会被自动删除，需要手动归档或删除

// 7. 安全销毁过期密钥（当确定不再需要时）
keyManager.DeleteKey("my-encryption-key", version: 1);

4. 错误处理

try
{
    var key = keyManager.ResolveForEncryption("my-key");
    if (key.Metadata.Status != KeyStatus.Active)
    {
        throw new InvalidOperationException($"Key is not active: {key.Metadata.Status}");
    }
    // 使用密钥...
}
catch (KeyNotFoundException ex)
{
    // 密钥不存在，创建新密钥
    keyManager.EnsureFreshSymmetricKey(
        "my-key",
        () => ("AES", RandomNumberGenerator.GetBytes(32))
    );
}
catch (InvalidOperationException ex)
{
    // 密钥状态不正确（如已泄露或已退役）
    logger.LogError($"Key operation failed: {ex.Message}");
    // 通知管理员、创建新密钥、重新加密数据
}

依赖项

<PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.0" />
<PackageReference Include="Microsoft.Extensions.Options" Version="10.0.0" />

外部依赖说明

• Microsoft.Extensions.DependencyInjection.Abstractions：依赖注入抽象
• Microsoft.Extensions.Options：选项模式支持
• 零 BugFree.Security 依赖：密钥生成完全由调用方提供（委托模式）

路线图

相关组件

• BugFree.Security：安全加密组件库
• BugFree.Core：核心平台抽象和工具

贡献指南

• 提交 PR 前请确保添加相应的单元测试
• 若扩展 IKeyStore，请提供完整的文档和示例
• 密钥存储实现必须考虑线程安全性
• 遵循现有的代码风格和命名规范

许可证

本项目遵循 BugFree 框架的许可证。

联系方式

如有问题或建议，请联系邮箱：ligengrong@hotmail.com

最后更新: 2026-01-18 版本: 1.1.2026.118 目标框架: net8.0;net10.0 依赖: 零依赖 BugFree.Security（完全委托模式）