azure-security-keyvault-keys-dotnet

用途

Azure.Security.KeyVault.Keys 是面向 .NET 的客户端库，用于在 Azure Key Vault 和 Managed HSM 中管理加密密钥。它把密钥管理与密码学操作分成两个客户端：KeyClient 负责密钥生命周期管理，CryptographyClient 负责实际的加密、解密、签名、验签、包装与解包等操作。

安装

dotnet add package Azure.Security.KeyVault.Keys
dotnet add package Azure.Identity

当前版本：4.7.0（stable）。

环境变量

KEY_VAULT_NAME=<your-key-vault-name>
# 或完整 URI
AZURE_KEYVAULT_URL=https://<vault-name>.vault.azure.net

客户端层级

KeyClient（密钥管理）

CreateKey / CreateRsaKey / CreateEcKey
GetKey / GetKeys
UpdateKeyProperties
DeleteKey / PurgeDeletedKey
BackupKey / RestoreKey
GetCryptographyClient() → CryptographyClient

CryptographyClient（密码学操作）

Encrypt / Decrypt
WrapKey / UnwrapKey
Sign / Verify
SignData / VerifyData

KeyResolver（密钥解析）

Resolve(keyId) → CryptographyClient

身份验证

推荐使用 DefaultAzureCredential：

using Azure.Identity;
using Azure.Security.KeyVault.Keys;

var keyVaultName = Environment.GetEnvironmentVariable("KEY_VAULT_NAME");
var kvUri = $"https://{keyVaultName}.vault.azure.net";

var client = new KeyClient(new Uri(kvUri), new DefaultAzureCredential());

也可使用服务主体：

var credential = new ClientSecretCredential(
    tenantId: "<tenant-id>",
    clientId: "<client-id>",
    clientSecret: "<client-secret>");

var client = new KeyClient(new Uri(kvUri), credential);

密钥管理

创建密钥：可创建 RSA、EC、Oct（对称）密钥，并设置密钥大小、曲线、是否 HSM 保护、过期时间、生效时间、启用状态与允许的密钥操作。

获取密钥：可获取指定密钥的最新版本或指定版本，可列出所有密钥及某个密钥的所有版本。

更新密钥属性：可修改过期时间、标签等属性。

删除与清除：支持启动删除操作、等待完成、立即清除（软删除启用时）、恢复已删除密钥。

备份与还原：可将密钥备份为字节数组并写入文件，也可从备份数据还原密钥。

密码学操作

可从 KeyClient 获取 CryptographyClient，也可直接用密钥 ID 创建。支持：

加密与解密（如 RsaOaep256）
密钥包装与解包（如 RsaOaep256）
签名与验签（SignData/VerifyData 内部计算哈希，Sign/Verify 针对预计算哈希）

密钥解析

KeyResolver 可按密钥 ID 解析出 CryptographyClient，便于在只知道密钥 URI 时执行密码学操作。

密钥轮换

支持 RotateKeyAsync 创建新版本，并可获取与更新密钥轮换策略，例如设置有效期与在到期前轮换的生命周期动作。

密钥类型参考

KeyClient（密钥管理操作）、CryptographyClient（密码学操作）、KeyResolver（解析密钥 ID）、KeyVaultKey（含密钥材料的密钥）、KeyProperties（密钥元数据）、CreateRsaKeyOptions、CreateEcKeyOptions、CreateOctKeyOptions、EncryptResult、DecryptResult、SignResult、VerifyResult、WrapResult、UnwrapResult。

算法参考

加密算法：RsaOaep、RsaOaep256、Rsa15（旧版）、A128Gcm、A256Gcm。

签名算法：RS256、RS384、RS512、PS256、ES256、ES384、ES512。

密钥包装算法：RsaOaep、RsaOaep256、A128KW、A256KW。

最佳实践

使用托管标识，优先 DefaultAzureCredential 而非密钥
启用软删除，防止误删
敏感密钥使用 HSM 保护（HardwareProtected = true）
实施密钥轮换，使用自动轮换策略
限制密钥操作，仅启用所需的 KeyOperations
始终设置过期时间
生产环境固定使用特定版本
缓存 CryptographyClient 以复用

错误处理

可通过捕获 RequestFailedException 并按状态码处理，例如 404 表示密钥未找到，403 表示访问被拒绝（检查 RBAC 权限）。

所需 RBAC 角色

Key Vault Crypto Officer：完整密钥管理
Key Vault Crypto User：使用密钥执行密码学操作
Key Vault Reader：读取密钥元数据

参考链接

NuGet 包：https://www.nuget.org/packages/Azure.Security.KeyVault.Keys
API 参考：https://learn.microsoft.com/dotnet/api/azure.security.keyvault.keys
快速入门：https://learn.microsoft.com/azure/key-vault/keys/quick-create-net
GitHub 源码：https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/keyvault/Azure.Security.KeyVault.Keys

适用场景

当任务明确涉及在 .NET 中管理 Azure Key Vault 或 Managed HSM 的加密密钥，或执行加密、解密、签名、验签、密钥包装与解包等操作时适用。

限制

仅在任务与上述范围明确匹配时使用。不应将输出视为环境特定验证、测试或专家评审的替代。若缺少必要输入、权限、安全边界或成功标准，应停止并请求澄清。

技能介绍

用途

安装