你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 .NET 的 Azure 密钥保管库密钥客户端库 - 版本 4.5.0

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

Azure 密钥保管库 托管 HSM 是一种完全托管、高度可用、单租户且符合标准的云服务，可用于使用 FIPS 140-2 级别 3 验证 HSM 保护云应用程序的加密密钥。

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

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

入门

安装包

使用 NuGet 安装适用于 .NET 的 Azure 密钥保管库密钥客户端库：

dotnet add package Azure.Security.KeyVault.Keys

先决条件

• 一个 Azure 订阅。
• 现有的 Azure 密钥保管库。 如果需要创建 Azure 密钥保管库，可以使用 Azure 门户或 Azure CLI。
• 使用 RBAC (建议) 或访问控制授权现有 Azure 密钥保管库。

如果要创建标准密钥保管库资源，请运行以下 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 密钥保管库服务交互，需要创建 KeyClient 类的实例。 需要 保管库 URL（可能在门户中显示为“DNS 名称”）和用于实例化客户端对象的凭据。

下面显示的示例使用 ， DefaultAzureCredential它适用于大多数方案，包括使用托管标识身份验证的本地开发和生产环境。 此外，建议在生产环境中使用托管标识进行身份验证。 可以在 Azure 标识 文档中找到有关不同身份验证方式及其相应凭据类型的详细信息。

若要使用如下所示的 DefaultAzureCredential 提供程序或 Azure SDK 提供的其他凭据提供程序，必须先安装 Azure.Identity 包：

dotnet add package Azure.Identity

激活托管 HSM

本部分仅适用于创建托管 HSM 时。 在激活 HSM 之前，所有数据平面命令都处于禁用状态。 你将无法创建密钥或分配角色。 只有在 create 命令期间分配的指定管理员才能激活 HSM。 若要激活 HSM，必须下载安全域。

若要激活 HSM，你需要：

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

若要激活 HSM，请向 HSM 发送至少 3 个（最多 10 个）RSA 公钥。 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 密钥保管库中创建 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 密钥保管库 支持多种密钥类型和算法，并支持使用硬件安全模块 (HSM) 来获取高价值密钥。

KeyClient

KeyClient SDK 中存在提供同步和异步操作的 ，允许根据应用程序的用例选择客户端。 初始化 后，KeyClient可以与 Azure 密钥保管库中的主要资源类型进行交互。

CryptographyClient

CryptographyClient SDK 中存在提供同步和异步操作的 ，允许根据应用程序的用例选择客户端。 初始化 后，CryptographyClient可以使用它对 Azure 密钥保管库中存储的密钥执行加密操作。

线程安全

我们保证所有客户端实例方法都是线程安全的，并且相互独立， (准则) 。 这可确保重用客户端实例的建议始终是安全的，即使跨线程也是如此。

其他概念

客户端选项 | 访问响应 | 长时间运行的操作 | 处理失败 | 诊断 | 嘲笑 | 客户端生存期

示例

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

以下部分提供了使用client上面创建的 几个代码片段，涵盖了一些最常见的 Azure 密钥保管库关键服务相关任务：

同步示例

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

异步示例

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

创建密钥

创建要存储在 Azure 密钥保管库中的密钥。 如果已存在同名的密钥，则会创建该密钥的新版本。

// 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 密钥保管库中的密钥。

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

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

更新现有密钥

UpdateKeyProperties更新以前存储在 Azure 密钥保管库中的密钥。

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 密钥保管库中的密钥。 可以立即检索密钥，而无需等待操作完成。 如果未为 Azure 密钥保管库启用软删除，此操作将永久删除密钥。

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 密钥保管库中的所有密钥。

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

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

加密和解密

此示例创建 ，CryptographyClient并使用它在 Azure 密钥保管库 中使用密钥进行加密和解密。

// 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 与其同步 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 方法，而是返回 AsyncPageable<KeyProperties> 可与 语句一起使用的 await foreach ：

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 密钥保管库密钥的示例代码，包括：

  • 对预先计算的摘要进行签名，并使用签名和验证来验证签名
  • 对原始数据进行签名并使用 SignData 和 VerifyData 验证签名

• Sample6_WrapUnwrap.md - 使用 Azure 密钥保管库密钥的示例代码，包括：

  • 包装并解包对称密钥

其他文档

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

供稿

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

本项目欢迎贡献和建议。 大多数贡献要求你同意贡献者许可协议 (CLA)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。 有关详细信息，请访问 https://cla.microsoft.com 。

提交拉取请求时，CLA 机器人将自动确定你是否需要提供 CLA，并相应地修饰 PR（例如标签、注释）。 直接按机器人提供的说明操作。 只需使用 CLA 对所有存储库执行一次这样的操作。

此项目采用了 Microsoft 开放源代码行为准则。 有关详细信息，请参阅行为准则常见问题解答，或如果有任何其他问题或意见，请与 联系。