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

使用 Azure CLI 管理托管 HSM

注意

Key Vault 支持两种类型的资源：保管库和托管 HSM。 本文介绍托管 HSM。 若要了解如何管理保管库，请参阅使用 Azure CLI 管理密钥保管库。

有关托管 HSM 的概述，请参阅什么是托管 HSM？

如果没有 Azure 订阅，请在开始之前创建一个免费帐户。

先决条件

若要完成本文中的步骤，必须准备好以下项：

• Microsoft Azure 订阅。 如果没有，可以注册免费试用版。
• Azure CLI 版本 2.25.0 或更高版本。 运行 az --version 即可查找版本。 如需进行安装或升级，请参阅安装 Azure CLI。
• 订阅中的托管 HSM。 请参阅快速入门：使用 Azure CLI 预配和激活托管 HSM，预配和激活托管 HSM。

Azure Cloud Shell

Azure 托管 Azure Cloud Shell（一个可通过浏览器使用的交互式 shell 环境）。 可以将 Bash 或 PowerShell 与 Cloud Shell 配合使用来使用 Azure 服务。 可以使用 Cloud Shell 预安装的命令来运行本文中的代码，而不必在本地环境中安装任何内容。

若要启动 Azure Cloud Shell，请执行以下操作：

选项	示例/链接
选择代码或命令块右上角的“试用”。 选择“试用”不会自动将代码或命令复制到 Cloud Shell。
转到 https://shell.azure.com 或选择启动 Cloud Shell 按钮可在浏览器中打开 Cloud Shell。
选择 Azure 门户右上角菜单栏上的 Cloud Shell 按钮。

若要使用 Azure Cloud Shell，请执行以下操作：

1. 启动 Cloud Shell。

2. 选择代码块（或命令块）上的“复制”按钮以复制代码或命令。

3. 在 Windows 和 Linux 上选择 Ctrl+Shift+V，或在 macOS 上选择 Cmd+Shift+V 将代码或命令粘贴到 Cloud Shell 会话中。

4. 选择“Enter”运行代码或命令。

登录 Azure

若要使用 CLI 登录到 Azure，可以键入：

az login

若要详细了解通过 CLI 使用的登录选项，请参阅使用 Azure CLI 登录

注意

下面所有命令都显示了两种使用方法。 一种使用 --hsm-name 和 --name（对于密钥名称）参数，而另一种使用 --id 参数，你可在其中指定整个 URL，包括密钥名称（如果适用）。 如果调用方（用户或应用程序）没有控制平面的读取访问权限，而且只有数据平面的受限访问权限，则后一种方法非常有用。

注意

与密钥材料的某些交互需要特定的本地 RBAC 权限。 有关内置本地 RBAC 角色和权限的完整列表，请参阅托管 HSM 本地 RBAC 内置角色。 若要将这些权限分配给用户，请参阅对托管 HSM 的安全访问

创建 HSM 密钥

注意

无法导出生成或导入到托管 HSM 中的密钥。 请参阅建议的最佳做法，了解密钥便携性和持续性。

使用 az keyvault key create 命令来创建密钥。

创建 RSA 密钥

下面的示例演示如何创建一个 3072 位 RSA 密钥，该密钥将仅用于 wrapKey、unwrapKey 操作 (--ops) 。

az keyvault key create --hsm-name ContosoMHSM --name myrsakey --ops wrapKey unwrapKey --kty RSA-HSM --size 3072

## OR
# Note the key name (myrsakey) in the URI

az keyvault key create --id https://ContosoMHSM.managedhsm.azure.net/keys/myrsakey --ops wrapKey unwrapKey --kty RSA-HSM --size 3072

请注意，get 操作仅返回公钥和密钥属性。 它不会返回私钥（对于非对称密钥）或密钥材料（对于对称密钥）。

创建 EC 密钥

下面的示例演示如何创建包含 P-256 曲线的 EC 密钥，该密钥将仅用于 sign 和 verify 操作 (--ops)，并有两个标记 usage 和 appname 。 标记有助于你将其他元数据添加到密钥，以便进行跟踪和管理。

az keyvault key create --hsm-name ContosoMHSM --name myec256key --ops sign verify  --tags ‘usage=signing] appname=myapp’ --kty EC-HSM --curve P-256

## OR
# Note the key name (myec256key) in the URI

az keyvault key create --id https://ContosoMHSM.managedhsm.azure.net/keys/myec256key --ops sign verify  --tags ‘usage=signing] appname=myapp’ --kty EC-HSM --curve P-256

创建 256 位对称密钥

下面的示例演示如何创建一个 256 位对称密钥，该密钥将仅用于 encrypt 和 decrypt 操作 (--ops) 。

az keyvault key create --hsm-name ContosoMHSM --name myaeskey --ops encrypt decrypt  --tags --kty oct-HSM --size 256

## OR
# Note the key name (myaeskey) in the URI

az keyvault key create --id https://ContosoMHSM.managedhsm.azure.net/keys/myaeskey --ops encrypt decrypt  --tags ‘usage=signing] appname=myapp’ --kty oct-HSM --size 256

查看密钥属性和标记

使用 az keyvault key show 命令查看密钥的属性、版本和标记。

az keyvault key show --hsm-name ContosoHSM --name myrsakey

## OR
# Note the key name (myaeskey) in the URI

az keyvault key show --id https://ContosoMHSM.managedhsm.azure.net/keys/myrsakey

列出密钥

使用 az keyvault key list 命令列出托管 HSM 内的所有密钥。

az keyvault key list --hsm-name ContosoHSM

## OR
# use full URI

az keyvault key list --id https://ContosoMHSM.managedhsm.azure.net/

删除密钥

使用 az keyvault key delete 命令删除托管 HSM 内的密钥。 请注意，软删除始终可用。 因此，删除的密钥将保留为已删除状态并且可恢复，但如果超过了保留天数，密钥将被清除（永久删除）而且无法恢复。

az keyvault key delete --hsm-name ContosoHSM --name myrsakey

## OR
# Note the key name (myaeskey) in the URI

az keyvault key delete --id https://ContosoMHSM.managedhsm.azure.net/keys/myrsakey

列出已删除的密钥

使用 az keyvault key list-deleted 命令列出托管 HSM 中处于已删除状态的所有密钥。

az keyvault key list-deleted --hsm-name ContosoHSM

## OR
# use full URI

az keyvault key list-deleted --id https://ContosoMHSM.managedhsm.azure.net/

恢复（撤销删除）已删除的密钥

使用 az keyvault key list-deleted 命令列出托管 HSM 中处于已删除状态的所有密钥。 如果在恢复已删除的密钥时需要使用--id 参数恢复（撤销删除）某个密钥，必须记下从 az keyvault key list-deleted 命令获取的已删除密钥的 recoveryId 值。

az keyvault key recover --hsm-name ContosoHSM --name myrsakey

## OR
# Note the key name (myaeskey) in the URI

az keyvault key recover --id https://ContosoMHSM.managedhsm.azure.net/deletedKeys/myrsakey

清除（永久删除）密钥

使用 az keyvault key purge 命令清除（永久删除）密钥。

注意

如果托管 HSM 启用了清除保护，则不允许执行清除操作。 保留期结束后，密钥将自动清除。

az keyvault key purge --hsm-name ContosoHSM --name myrsakey

## OR
# Note the key name (myaeskey) in the URI

az keyvault key purge --id https://ContosoMHSM.managedhsm.azure.net/deletedKeys/myrsakey

创建单个密钥备份

使用 az keyvault key backup 创建密钥备份。 备份文件是一个加密的 blob，以加密方式绑定到源 HSM 的安全域。 它只能在共享同一安全域的 HSM 中还原。 详细了解安全域。

az keyvault key backup --hsm-name ContosoHSM --name myrsakey --file myrsakey.backup

## OR
# Note the key name (myaeskey) in the URI

az keyvault key backup --id https://ContosoMHSM.managedhsm.azure.net/deletedKeys/myrsakey  --file myrsakey.backup

从备份中还原单个密钥

使用 az keyvault key restore 还原单个密钥。 创建备份的源 HSM 必须与要在其中还原密钥的目标 HSM 共享同一安全域。

注意

如果存在处于活动或已删除状态的同名密钥，还原将不会成功。

az keyvault key restore --hsm-name ContosoHSM --name myrsakey --file myrsakey.backup

## OR
# Note the key name (myaeskey) in the URI

az keyvault key restore --id https://ContosoMHSM.managedhsm.azure.net/deletedKeys/myrsakey --file myrsakey.backup

从文件中导入密钥

使用 az keyvault key import 命令从文件中导入密钥（仅限 RSA 和 EC）。 证书文件必须具有私钥，并且必须使用 PEM 编码（如 RFC 1421、1422、1423、1424 所定义）。

az keyvault key import --hsm-name ContosoHSM --name myrsakey --pem-file mycert.key --password 'mypassword'

## OR
# Note the key name (myaeskey) in the URI

az keyvault key recover --id https://ContosoMHSM.managedhsm.azure.net/deletedKeys/myrsakey --pem-file mycert.key --password 'mypassword'

若要将密钥从本地 HSM 导入到托管 HSM，请参阅将受 HSM 保护的密钥导入到托管 HSM (BYOK)

后续步骤

• 有关密钥保管库命令的完整 Azure CLI 参考，请参阅 Key Vault CLI 参考。
• 有关编程参考，请参阅 Azure 密钥保管库开发人员指南
• 详细了解托管 HSM 角色管理
• 详细了解托管 HSM 最佳做法