Azure.Security.KeyVault.Administration 4.4.0

Azure KeyVault Administration客户端库，适用于.NET

Azure Key Vault Managed HSM是一种全面管理、高可用性、单租户、符合标准的安全云服务，您可以使用FIPS 140-2 Level 3验证的HSM来保护您云应用程序的加密密钥。

Azure Key Vault管理库客户端支持像完全备份/还原和基于角色的密钥级访问控制（RBAC）等管理任务。

源代码 | 包（NuGet） | 产品文档 | 示例

入门

安装包

使用NuGet安装Azure Key Vault管理客户端库对于.NET

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 Identity文档中找到有关不同认证方式和相应凭据类型的更多信息。

要使用以下示例中的DefaultAzureCredential提供程序或与其他Azure SDK一起提供的其他凭据提供程序，您必须首先安装Azure.Identity软件包

dotnet add package Azure.Identity

激活您的托管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-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 是一组权限的集合。角色定义定义了可以执行的操作，例如读取、写入和删除。它还可以定义从允许的操作中排除的操作。

可以将 KeyVaultRoleDefinition 列出，并作为 KeyVaultRoleAssignment 的一部分进行指定。

KeyVaultRoleAssignment

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

KeyVaultAccessControlClient

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

KeyVaultBackupClient

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

BackupOperation

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

RestoreOperation

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

线程安全

我们保证所有客户端实例方法都是线程安全的，并且互相独立（指南）。这确保了推荐复用客户端实例总是安全的，即使是在线程之间。

其他概念

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

示例

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

以下部分提供了几个代码片段，使用上面创建的 client 对象进行访问控制或备份客户端的操作，涵盖了某些最常用的 Azure Key Vault 访问控制相关任务。

同步示例

• 访问控制
  • 列出所有角色定义
  • 列出所有角色分配
  • 创建角色分配
  • 获取角色分配
  • 删除角色分配
• 备份和还原
  • 执行完整密钥备份
  • 执行完整密钥还原

异步示例

• 访问控制
  • 列出所有角色定义
  • 列出所有角色分配
  • 创建角色分配
  • 获取角色分配
  • 删除角色分配
• 备份和还原
  • 执行完整密钥备份
  • 执行完整密钥还原

问题调试

查看我们的 问题调试指南 了解如何诊断各种故障情况。

一般

当您使用 .NET SDK 与 Azure Key Vault Administration 库交互时，服务返回的错误与 REST API 请求返回的相同 HTTP 状态代码相对应。

例如，如果您尝试检索在您的 Azure Key Vault 中不存在的角色分配，则会返回一个 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 开源行为守则。有关更多信息，请参阅行为守则常见问题解答或通过[email protected]联系以提出任何额外的问题或意见。