通过

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

适用于 .NET 的 Azure KeyVault 管理客户端库 - 版本 4.3.0

  • 项目

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

Azure 密钥保管库管理库客户端支持管理任务，例如完整备份/还原和密钥级基于角色的访问控制 (RBAC) 。

源代码 | 包 (NuGet) | 产品文档 | 样品

入门

安装包

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

dotnet add package Azure.Security.KeyVault.Administration

先决条件

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

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

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

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

dotnet add package Azure.Identity

激活托管 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-managed-hsm-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

控制对托管 HSM 的访问

在创建期间分配的指定管理员将自动添加到“托管 HSM 管理员” 内置角色，这些管理员能够下载安全域 和管理数据平面访问的角色以及其他有限权限。

若要对密钥执行其他操作，需要将主体分配给其他角色，例如“托管 HSM 加密用户”，后者可以执行非破坏性密钥操作：

az keyvault role assignment create --hsm-name <your-managed-hsm-name> --role "Managed HSM Crypto User" --scope / --assignee-object-id <principal-or-user-object-ID> --assignee-principal-type <principal-type>

请阅读正确保护托管 HSM 的 最佳做法 。

创建 KeyVaultAccessControlClient

实例化 以 DefaultAzureCredential 传递给 KeyVaultAccessControlClient。 如果多个客户端将使用相同的标识进行身份验证，则可以将令牌凭据的同一实例用于这些客户端。

KeyVaultAccessControlClient client = new KeyVaultAccessControlClient(new Uri(managedHsmUrl), new DefaultAzureCredential());

创建 KeyVaultBackupClient

实例化 以 DefaultAzureCredential 传递给 KeyVaultBackupClient。 如果多个客户端将使用相同的标识进行身份验证，则可以将令牌凭据的同一实例用于这些客户端。

KeyVaultBackupClient client = new KeyVaultBackupClient(new Uri(managedHsmUrl), new DefaultAzureCredential());

创建 KeyVaultSettingClient

实例化 以 DefaultAzureCredential 传递给 KeyVaultSettingsClient。 如果多个客户端将使用相同的标识进行身份验证，则可以将令牌凭据的同一实例用于这些客户端。

KeyVaultSettingsClient client = new KeyVaultSettingsClient(new Uri(managedHsmUrl), new DefaultAzureCredential());

关键概念

KeyVaultRoleDefinition

是 KeyVaultRoleDefinition 权限的集合。 角色定义定义可执行的操作，例如读取、写入和删除。 它还可以定义从允许的操作中排除的操作。

KeyVaultRoleDefinitions 可以列出并指定为 的一 KeyVaultRoleAssignment部分。

KeyVaultRoleAssignment

是 KeyVaultRoleAssignment KeyVaultRoleDefinition 与服务主体的关联。 可以创建、列出、单独提取和删除它们。

KeyVaultAccessControlClient

提供 KeyVaultAccessControlClient 同步和异步操作，允许管理 KeyVaultRoleDefinition 和 KeyVaultRoleAssignment 对象。

KeyVaultBackupClient

提供 KeyVaultBackupClient 同步和异步操作，用于执行完整密钥备份、完整密钥还原和选择性密钥还原。

BackupOperation

表示 BackupOperation 完整密钥备份的长时间运行操作。

RestoreOperation

表示 RestoreOperation 完整密钥和选择性密钥还原的长时间运行操作。

线程安全

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

其他概念

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

示例

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

以下部分提供了使用client上面为访问控制或备份客户端创建的多个代码片段，涵盖了一些最常见的 Azure 密钥保管库访问控制相关任务：

同步示例

异步示例

疑难解答

有关如何诊断各种故障方案的详细信息，请参阅故障排除 指南 。

常规

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

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

try
{
    KeyVaultRoleAssignment roleAssignment = client.GetRoleAssignment(KeyVaultRoleScope.Global, "example-name");
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.ToString());
}

Azure.RequestFailedException: Service request failed.
Status: 404 (Not Found)

Content:
{"error":{"code":"RoleAssignmentNotFound","message":"Requested role assignment not found (Activity ID: a67f09f4-b68e-11ea-bd6d-0242ac120006)"}}

Headers:
X-Content-Type-Options: REDACTED
x-ms-request-id: a67f09f4-b68e-11ea-bd6d-0242ac120006
Content-Length: 143
Content-Type: application/json

设置控制台日志记录

查看日志的最简单方法是启用控制台日志记录。 若要创建将消息输出到控制台的 Azure SDK 日志侦听器，请使用 AzureEventSourceListener.CreateConsoleLogger 方法。

// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

若要详细了解其他日志记录机制，请参阅 此处。

后续步骤

参考我们的示例帮助自己入门。

贡献

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

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

曝光数