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

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

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

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

托管 HSM 客户端库资源：

API 参考文档 | 库源代码 | 包 (PyPI)

先决条件

设置本地环境

本快速入门使用 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 根据环境自动选择相应的凭据：

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

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

  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 软删除和清除保护

后续步骤

  • Last updated on