使用 Azure CLI 管理托管 HSM
注意
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。
登录 Azure
若要使用 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 最佳做法