使用 Azure CLI 管理托管 HSM

项目
2024/07/22

备注

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

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

如果没有 Azure 订阅，请在开始前创建一个试用版订阅。

先决条件

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

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

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

az cloud set -n AzureChinaCloud
az cloud set -n AzureChinaCloud
az login
# az cloud set -n AzureCloud   //means return to Public Azure.
# az cloud set -n AzureCloud   //means return to Public Azure.

若要详细了解通过 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.chinacloudapi.cn/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.chinacloudapi.cn/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.chinacloudapi.cn/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.chinacloudapi.cn/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.chinacloudapi.cn/

删除密钥

使用 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.chinacloudapi.cn/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.chinacloudapi.cn/

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

使用 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.chinacloudapi.cn/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.chinacloudapi.cn/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.chinacloudapi.cn/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.chinacloudapi.cn/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.chinacloudapi.cn/deletedKeys/myrsakey --pem-file mycert.key --password 'mypassword'

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

后续步骤

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

通过