快速入门：适用于 Python 的 Azure 密钥保管库 托管 HSM 客户端库

Azure 密钥保管库 托管 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 Function），或用于本地开发的 Azure CLI。
• 必须为托管标识分配适当的托管 HSM 本地 RBAC 角色。 请参阅 安全访问托管的 HSM。

• Python 3.8+

设置本地环境

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

登录到 Azure

az login运行命令以登录：

az login

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

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

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

2. 创建和激活虚拟环境：

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

安装软件包

安装Azure标识和密钥保管库密钥客户端库：

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.azure.net"
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 根据环境自动选择相应的凭据：

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

1. 环境变量
2. 工作负载标识
3. 托管标识
4. Azure CLI
5. Azure PowerShell
6. Visual Studio/VS Code 凭据

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

关键操作

该 KeyClient 类提供以下方法：

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

该 CryptographyClient 类提供加密操作：

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

分配托管 HSM 角色

为了让应用程序访问密钥，请为托管标识分配适当的托管 HSM 本地 RBAC 角色。 替换<vm-name>、<resource-group>和<hsm-name>为实际值。

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

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

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

清理资源

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

az group delete --name <resource-group>

后续步骤

• 了解安全访问托管 HSM
• 配置 自动密钥轮换
• 查看托管 HSM 最佳做法
• 了解托管 HSM 本地 RBAC 内置角色