快速入门：适用于Python的Azure Key Vault托管HSM客户端库

开始使用 Azure Key Vault 托管 HSM 的 Python 客户端库。托管 HSM 是一种完全托管、高度可用、符合标准的单租户云服务，可用于使用 FIPS 140-3 级别 3 验证的 HSM 来保护云应用程序的加密密钥。有关托管 HSM 的详细信息，请查看概述。

在本快速入门中，你将了解如何使用 Python 客户端库访问和执行托管 HSM 中的密钥的加密操作。

托管 HSM 客户端库资源：

API 参考文档 | 库源代码 | 软件包（PyPI）

先决条件

一个Azure订阅。免费创建一个。
预配和激活的托管 HSM。请参阅 Quickstart：使用 Azure CLI 预配和激活托管 HSM。
在托管 HSM 中创建的密钥。请参阅托管 HSM 中的“管理密钥”。
具有托管标识的Azure资源（例如 VM、应用服务或Azure 函数），或用于本地开发的Azure CLI。
必须为托管标识分配适当的托管 HSM 本地 RBAC 角色。请参阅安全访问托管的 HSM。

Python 3.8+

设置本地环境

本快速入门使用 Azure 身份验证库与 Azure CLI 来为 Azure 服务进行身份验证。开发人员还可以使用Visual Studio Code对调用进行身份验证。有关详细信息，请参阅使用Azure标识客户端库对客户端进行身份验证。

az login运行命令以登录：

az login

创建项目文件夹和虚拟环境

创建项目文件夹并导航到它：

mkdir mhsm-python-app && cd mhsm-python-app

创建和激活虚拟环境：

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

安装软件包

安装Azure标识和Key Vault密钥客户端库：

pip install azure-identity azure-keyvault-keys

创建示例代码

创建包含以下代码的文件 mhsm_keys.py 。将 <hsm-name> 替换为托管 HSM 名称，并将 <key-name> 替换为现有的密钥名称。

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient
from azure.keyvault.keys.crypto import CryptographyClient, EncryptionAlgorithm

# Use DefaultAzureCredential for automatic credential selection
credential = DefaultAzureCredential()

# Connect to Managed HSM - replace with your HSM URI
hsm_uri = "https://<hsm-name>.managedhsm.chinacloudapi.cn"
key_client = KeyClient(vault_url=hsm_uri, credential=credential)

# Get a key reference
key_name = "<key-name>"
print(f"Retrieving key '{key_name}' from Managed HSM...")
key = key_client.get_key(key_name)
print(f"Key retrieved. Key type: {key.key_type}")

# Perform cryptographic operations
crypto_client = CryptographyClient(key, credential)

# Encrypt data
plaintext = b"Hello, Managed HSM!"
print(f"\nOriginal text: {plaintext.decode()}")

encrypt_result = crypto_client.encrypt(EncryptionAlgorithm.rsa_oaep_256, plaintext)
print(f"Encrypted (hex): {encrypt_result.ciphertext.hex()[:64]}...")

# Decrypt data
decrypt_result = crypto_client.decrypt(EncryptionAlgorithm.rsa_oaep_256, encrypt_result.ciphertext)
print(f"Decrypted text: {decrypt_result.plaintext.decode()}")

print("\nDone!")

运行应用程序

运行应用程序：

python mhsm_keys.py

此时会看到与下面类似的输出：

Retrieving key 'myrsakey' from Managed HSM...
Key retrieved. Key type: RSA-HSM

Original text: Hello, Managed HSM!
Encrypted (hex): 5a8f3b2c1d4e5f6a7b8c9d0e1f2a3b4c...
Decrypted text: Hello, Managed HSM!

Done!

了解数据

使用 DefaultAzureCredential 进行身份验证

DefaultAzureCredential 根据环境自动选择相应的凭据：

环境	使用的凭据
Azure VM、应用服务、函数	系统分配的或用户分配的托管标识
Azure Kubernetes 服务	工作负载标识
地方发展	Azure CLI、Visual Studio 或 VS Code 凭据
CI/CD 管道	工作负荷标识联合或服务主体

凭证按顺序检查这些来源：

环境变量
工作负载标识
托管标识
Azure CLI
Azure PowerShell
Visual Studio/VS Code 凭证

对于Azure中的生产工作负荷，强烈建议使用托管标识，因为它们完全消除了凭据管理。

关键操作

该 KeyClient 类提供以下方法：

创建、获取、更新和删除密钥
列出密钥和密钥版本
备份和还原密钥

该 CryptographyClient 类提供加密操作：

加密和解密数据
签名和验证签名
包装和解包密钥

分配托管 HSM 角色

若要使您的应用程序访问密钥，请将适当的本地 RBAC 角色分配给您的托管 HSM 标识:

# Get the principal ID of your managed identity
principalId=$(az vm identity show --name myVM --resource-group myRG --query principalId -o tsv)

# Assign the Crypto User role for key operations
az keyvault role assignment create \
    --hsm-name ContosoMHSM \
    --role "Managed HSM Crypto User" \
    --assignee $principalId \
    --scope /keys

若需了解角色和权限的更多信息，请参阅托管 HSM 本地 RBAC 内置角色。

清理资源

如果不再需要资源组和所有相关资源，请将其删除：

az group delete --name <resource-group>

警告

删除资源组会将托管 HSM 置于软删除状态。托管 HSM 将继续计费，直到被清理为止。请参阅托管 HSM 软删除和清除保护

后续步骤

Last updated on 2026-04-17

共用方式為