你当前正在访问 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 安装适用于 .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 开放源代码行为准则。 有关详细信息，请参阅行为准则常见问题解答，或如果有任何其他问题或意见，请与 联系。
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈