Azure.Security.KeyVault.Keys 4.6.0

Azure 密钥保管库 .NET 密钥客户端库

Azure 密钥保管库是一种云服务，提供用于加密数据的密钥的安全存储。可以保持多个密钥以及相同密钥的多个版本在 Azure 密钥保管库中。Azure 密钥保管库中的加密密钥表示为 JSON Web Key (JWK) 对象。

Azure 密钥保管库托管 HSM 是一种完全托管、高可用性、单租户、符合标准规范的云服务，它能够让您使用经过 FIPS 140-2 级别 3 验证的 HSM 保障您的云应用程序中的加密密钥。

Azure 密钥保管库密钥库客户端支持 RSA 密钥和椭圆曲线 (EC) 密钥，每个都与硬件安全模块 (HSM) 的相应支持。它提供创建、检索、更新、删除、清除、备份、还原和列出密钥及其版本的操作。

源代码 | 包 (NuGet) | API 参考文档 | 产品文档 | 示例 | 迁移指南

入门

安装包

使用 NuGet 安装 Azure Key Vault 密钥客户端库 for .NET

dotnet add package Azure.Security.KeyVault.Keys

先决条件

• 一个 Azure 订阅。
• 已存在的 Azure Key Vault。如果您需要创建 Azure Key Vault，可以使用 Azure 门户或 Azure CLI。
• 对现有 Azure Key Vault 的授权，使用 RBAC（推荐）或 访问控制。

如果正在创建标准 Key Vault 资源，运行以下 CLI 命令，并将 <your-resource-group-name> 和 <your-key-vault-name> 替换为您自己的唯一名称

az keyvault create --resource-group <your-resource-group-name> --name <your-key-vault-name>

如果您正在创建托管 HSM 资源，运行以下 CLI 命令

az keyvault create --hsm-name <your-key-vault-name> --resource-group <your-resource-group-name> --administrators <your-user-object-id> --location <your-azure-location>

要获取 <your-user-object-id>，您可以运行以下 CLI 命令

az ad user show --id <your-user-principal> --query id

认证客户端

为了与 Azure Key Vault 服务交互，您需要创建 KeyClient 类的实例。您需要一个 保险库 URL，您在门户中可能将其看作“DNS 名称”，以及用于实例化客户端对象的凭据。

下面的示例使用了 DefaultAzureCredential，这在大多数场景下都是合适的，包括本地开发和生产环境使用托管标识认证。此外，我们建议在生产环境中使用托管标识进行认证。您可以在 Azure Identity 文档中找到有关不同认证方法和相应凭据类型的更多信息。

要使用下面的 DefaultAzureCredential 提供者或其他由 Azure SDK 提供的凭据提供者，您必须首先安装 Azure.Identity 包

dotnet add package Azure.Identity

激活您的托管 HSM

本节仅适用于创建托管 HSM 的情况。所有数据平面命令将在 HSM 激活之前禁用。您将无法创建密钥或分配角色。只有创建命令期间指定的管理员可以激活 HSM。要激活 HSM，您必须下载安全域。

要激活您的 HSM，您需要

• 至少 3 个 RSA 密钥对（最多 10 个）
• 指定解密安全域所需的最小密钥数量（法定人数）

要激活 HSM，您需要将至少 3 个（最多 10 个）RSA 公钥发送到 HSM。HSM 使用这些密钥加密安全域并将其发送回。一旦成功下载此安全域，您的 HSM 就可以使用了。您还需要指定法定人数，即解密安全域所需的最小私钥数量。

以下示例展示了如何使用 openssl 生成 3 个自签名证书。

openssl req -newkey rsa:2048 -nodes -keyout cert_0.key -x509 -days 365 -out cert_0.cer
openssl req -newkey rsa:2048 -nodes -keyout cert_1.key -x509 -days 365 -out cert_1.cer
openssl req -newkey rsa:2048 -nodes -keyout cert_2.key -x509 -days 365 -out cert_2.cer

使用 az keyvault security-domain download 命令下载安全域并激活您的托管 HSM。以下示例使用 3 个 RSA 密钥对（本命令只需要公钥）并将法定人数设置为 2。

az keyvault security-domain download --hsm-name <your-key-vault-name> --sd-wrapping-keys ./certs/cert_0.cer ./certs/cert_1.cer ./certs/cert_2.cer --sd-quorum 2 --security-domain-file ContosoMHSM-SD.json

创建 KeyClient

实例化一个 DefaultAzureCredential 传递给客户端。如果客户端将使用相同的标识进行认证，同一个令牌凭证实例可以用于多个客户端。

// Create a new key client using the default credential from Azure.Identity using environment variables previously set,
// including AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, and AZURE_TENANT_ID.
var client = new KeyClient(vaultUri: new Uri(vaultUrl), credential: new DefaultAzureCredential());

// Create a new key using the key client.
KeyVaultKey key = client.CreateKey("key-name", KeyType.Rsa);

// Retrieve a key using the key client.
key = client.GetKey("key-name");

创建CryptographyClient

在Azure Key Vault中创建了一个KeyVaultKey之后，您还可以创建CryptographyClient

// Create a new cryptography client using the same Key Vault or Managed HSM endpoint, service version,
// and options as the KeyClient created earlier.
CryptographyClient cryptoClient = client.GetCryptographyClient(key.Name, key.Properties.Version);

关键概念

KeyVaultKey

Azure Key Vault支持多种密钥类型和算法，并支持使用硬件安全模块(HSM)来保护高价值密钥。

KeyClient

SDK中存在一个提供同步和异步操作的KeyClient，允许根据应用程序用例选择客户端。初始化了KeyClient之后，您就可以与Azure Key Vault的主要资源类型进行交互。

CryptographyClient

SDK中存在一个提供同步和异步操作的CryptographyClient，允许根据应用程序用例选择客户端。初始化了CryptographyClient之后，您可以使用它来执行存储在Azure Key Vault中的密钥的加密操作。

线程安全

我们保证所有客户端实例方法都是线程安全的且相互独立（《[线程安全指南](https://azure.github.io/azure-sdk/dotnet_introduction.html#dotnet-service-methods-thread-safety)》）。这确保了复用客户端实例的推荐总是安全的，即使在不同的线程之间。

其他概念

客户端选项 | 访问响应 | 长时间运行操作 | 处理失败 | 诊断 | 模拟 | 客户端生命周期

示例

Azure.Security.KeyVault.Keys包支持同步和异步API。

以下部分提供了几个使用上面创建的client的代码片段，涵盖了与Azure Key Vault键相关的一些常见任务。

同步示例

• 创建一个密钥
• 检索一个密钥
• 更新现有密钥
• 删除一个密钥
• 删除和清除一个密钥
• 列出密钥
• 加密和解密

异步示例

• 异步创建一个密钥
• 异步列出密钥
• 异步删除一个密钥

创建一个密钥

创建一个要存储在Azure Key Vault中的密钥。如果已存在具有相同名称的密钥，则创建新版本的密钥。

// Create a key. Note that you can specify the type of key
// i.e. Elliptic curve, Hardware Elliptic Curve, RSA
KeyVaultKey key = client.CreateKey("key-name", KeyType.Rsa);

Console.WriteLine(key.Name);
Console.WriteLine(key.KeyType);

// Create a software RSA key
var rsaCreateKey = new CreateRsaKeyOptions("rsa-key-name", hardwareProtected: false);
KeyVaultKey rsaKey = client.CreateRsaKey(rsaCreateKey);

Console.WriteLine(rsaKey.Name);
Console.WriteLine(rsaKey.KeyType);

// Create a hardware Elliptic Curve key
// Because only premium Azure Key Vault supports HSM backed keys , please ensure your Azure Key Vault
// SKU is premium when you set "hardwareProtected" value to true
var echsmkey = new CreateEcKeyOptions("ec-key-name", hardwareProtected: true);
KeyVaultKey ecKey = client.CreateEcKey(echsmkey);

Console.WriteLine(ecKey.Name);
Console.WriteLine(ecKey.KeyType);

检索一个密钥

GetKey检索先前存储在Azure Key Vault中的密钥。

KeyVaultKey key = client.GetKey("key-name");

Console.WriteLine(key.Name);
Console.WriteLine(key.KeyType);

更新现有密钥

UpdateKeyProperties更新先前存储在Azure Key Vault中的密钥。

KeyVaultKey key = client.CreateKey("key-name", KeyType.Rsa);

// You can specify additional application-specific metadata in the form of tags.
key.Properties.Tags["foo"] = "updated tag";

KeyVaultKey updatedKey = client.UpdateKeyProperties(key.Properties);

Console.WriteLine(updatedKey.Name);
Console.WriteLine(updatedKey.Properties.Version);
Console.WriteLine(updatedKey.Properties.UpdatedOn);

删除一个密钥

StartDeleteKey启动一个长时间运行的操作以删除先前存储在Azure Key Vault中的密钥。您可以立即检索密钥，无需等待操作完成。当Azure Key Vault未启用软删除时，此操作永久删除密钥。

DeleteKeyOperation operation = client.StartDeleteKey("key-name");

DeletedKey key = operation.Value;
Console.WriteLine(key.Name);
Console.WriteLine(key.DeletedOn);

删除和清除一个密钥

您必须等待长时间运行的操作完成，然后再尝试清除或恢复密钥。

DeleteKeyOperation operation = client.StartDeleteKey("key-name");

// You only need to wait for completion if you want to purge or recover the key.
while (!operation.HasCompleted)
{
    Thread.Sleep(2000);

    operation.UpdateStatus();
}

DeletedKey key = operation.Value;
client.PurgeDeletedKey(key.Name);

列出密钥

此示例列出了指定Azure Key Vault中的所有密钥。

Pageable<KeyProperties> allKeys = client.GetPropertiesOfKeys();

foreach (KeyProperties keyProperties in allKeys)
{
    Console.WriteLine(keyProperties.Name);
}

加密和解密

此示例创建一个CryptographyClient并使用它来使用Azure Key Vault中的密钥进行加密和解密。

// Create a new cryptography client using the same Key Vault or Managed HSM endpoint, service version,
// and options as the KeyClient created earlier.
var cryptoClient = client.GetCryptographyClient(key.Name, key.Properties.Version);

byte[] plaintext = Encoding.UTF8.GetBytes("A single block of plaintext");

// encrypt the data using the algorithm RSAOAEP
EncryptResult encryptResult = cryptoClient.Encrypt(EncryptionAlgorithm.RsaOaep, plaintext);

// decrypt the encrypted data.
DecryptResult decryptResult = cryptoClient.Decrypt(EncryptionAlgorithm.RsaOaep, encryptResult.Ciphertext);

异步创建一个密钥

异步API与它们的同步版本完全相同，但异步方法带有典型的“Async”后缀，并返回Task。

// Create a key of any type
KeyVaultKey key = await client.CreateKeyAsync("key-name", KeyType.Rsa);

Console.WriteLine(key.Name);
Console.WriteLine(key.KeyType);

// Create a software RSA key
var rsaCreateKey = new CreateRsaKeyOptions("rsa-key-name", hardwareProtected: false);
KeyVaultKey rsaKey = await client.CreateRsaKeyAsync(rsaCreateKey);

Console.WriteLine(rsaKey.Name);
Console.WriteLine(rsaKey.KeyType);

// Create a hardware Elliptic Curve key
// Because only premium Azure Key Vault supports HSM backed keys , please ensure your Azure Key Vault
// SKU is premium when you set "hardwareProtected" value to true
var echsmkey = new CreateEcKeyOptions("ec-key-name", hardwareProtected: true);
KeyVaultKey ecKey = await client.CreateEcKeyAsync(echsmkey);

Console.WriteLine(ecKey.Name);
Console.WriteLine(ecKey.KeyType);

异步列出密钥

列出密钥不需要依赖GetPropertiesOfKeysAsync方法，而是返回一个你可以使用await foreach语句的AsyncPageable<KeyProperties>。

AsyncPageable<KeyProperties> allKeys = client.GetPropertiesOfKeysAsync();

await foreach (KeyProperties keyProperties in allKeys)
{
    Console.WriteLine(keyProperties.Name);
}

异步删除一个密钥

在异步删除密钥并在清除之前，你可以等候操作的WaitForCompletionAsync方法。默认情况下，它会无限循环，但你可以通过传递一个CancellationToken来取消它。

DeleteKeyOperation operation = await client.StartDeleteKeyAsync("key-name");

// You only need to wait for completion if you want to purge or recover the key.
await operation.WaitForCompletionAsync();

DeletedKey key = operation.Value;
await client.PurgeDeletedKeyAsync(key.Name);

故障排除

请参阅我们的故障排除指南，了解诊断各种失败场景的细节。

一般

当你使用.NET SDK与Azure密钥保管库密钥客户端库交互时，服务返回的错误对应于REST API请求返回的相同HTTP状态码。

例如，如果你尝试检索在Azure密钥保管库中不存在的密钥，则会返回404错误，表示“未找到”。

try
{
    KeyVaultKey key = client.GetKey("some_key");
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.ToString());
}

你将注意到记录了额外的信息，例如操作的客户端请求ID。

Message:
    Azure.RequestFailedException : Service request failed.
    Status: 404 (Not Found)
Content:
    {"error":{"code":"KeyNotFound","message":"Key not found: some_key"}}

Headers:
    Cache-Control: no-cache
    Pragma: no-cache
    Server: Microsoft-IIS/10.0
    x-ms-keyvault-region: westus
    x-ms-request-id: 625f870e-10ea-41e5-8380-282e5cf768f2
    x-ms-keyvault-service-version: 1.1.0.866
    x-ms-keyvault-network-info: addr=131.107.174.199;act_addr_fam=InterNetwork;
    X-AspNet-Version: 4.0.30319
    X-Powered-By: ASP.NET
    Strict-Transport-Security: max-age=31536000;includeSubDomains
    X-Content-Type-Options: nosniff
    Date: Tue, 18 Jun 2019 16:02:11 GMT
    Content-Length: 75
    Content-Type: application/json; charset=utf-8
    Expires: -1

下一步

此GitHub存储库中提供了几个Azure密钥保管库密钥客户端库示例。这些示例提供了使用Azure密钥保管库时遇到的常见场景的示例代码。

• Sample1_HelloWorld.md - 涉及与Azure密钥保管库交互，包括

  • 创建一个密钥
  • 获取现有密钥
  • 更新现有密钥
  • 删除一个密钥

• Sample2_BackupAndRestore.md - 包含与Azure密钥保管库密钥一起工作的代码片段，包括

  • 备份和恢复密钥

• Sample3_GetKeys.md - 涉及与Azure密钥保管库密钥一起工作的示例代码，包括

  • 创建密钥
  • 列出密钥保管库中的所有密钥
  • 更新密钥保管库中的密钥
  • 列出指定密钥的版本
  • 从密钥保管库中删除密钥
  • 列出密钥保管库中的已删除密钥

• Sample4_EncryptDecrypt.md - 执行加密操作的示例代码，包括与Azure密钥保管库密钥一起工作

  • 使用CryptographyClient加密和解密数据

• Sample5_SignVerify.md - 涉及与Azure密钥保管库密钥一起工作的示例代码，包括

  • 使用签名和验证签名预先计算的消息摘要
  • 使用签名数据和验证数据签名和验证原始数据

• Sample6_WrapUnwrap.md - 涉及与Azure密钥保管库密钥一起工作的示例代码，包括

  • 包装和解包对称密钥

其他文档

• 有关Azure密钥保管库的更多广泛文档，请参阅API参考文档。
• 有关机密客户端库，请参阅Secrets客户端库。
• 有关证书客户端库，请参阅Certificates客户端库。

贡献

有关构建、测试和贡献这些库的详细信息，请参阅CONTRIBUTING.md。

此项目欢迎贡献和建议。大多数贡献都需要你同意一个贡献者许可协议（CLA），声明你有权利，实际上也确实授予我们使用你的贡献的权利。有关详细信息，请访问https://cla.microsoft.com。

当你提交拉取请求时，CLA-bot将自动判断你是否需要提供CLA，并相应地标记PR（例如：标签、评论）。只需按照bot提供的说明操作。你只需在整个使用我们CLAs的仓库中这样做一次。

本项目已采用微软开源行为准则。更多详细信息请参阅行为准则FAQ或通过[email protected]联系以获取任何附加问题或评论。