共用方式為

快速入門：適用於 Python 的 Azure Key Vault Managed HSM 用戶端程式庫

開始使用 Azure Key Vault 管理型 HSM Python 客戶端函式庫。 完整管理的 HSM 是一種高可用性的單租戶雲端服務，符合標準規範，可讓您使用 FIPS 140-3 等級 3 驗證的 HSM 來保護您的雲端應用程式的加密密鑰。 欲了解更多管理型HSM的資訊，請參閱 概述。

在這個快速入門中，你將學習如何使用 Python 用戶端函式庫，存取並執行管理型 HSM 金鑰的密碼運算。

受管理的 HSM 用戶端函式庫資源：

API 參考文件 | 程式庫原始碼 | 套件 (PyPI)

先決條件

設定您的本機環境

此快速入門使用Azure身份函式庫搭配Azure CLI來認證Azure服務。 開發者也可使用 Visual Studio Code 來驗證通話。 欲了解更多資訊，請參閱 Authenticate the client with Azure Identity 客戶端函式庫。

登入 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 Identity 和 金鑰保存庫 Keys 用戶端函式庫：

pip install azure-identity azure-keyvault-keys

建立範例程式碼

建立一個以以下代碼命名的 mhsm_keys.py 檔案。 將<hsm-name>替換為你的 Managed 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、App Service、Functions 系統指派或使用者指派的管理識別
Azure Kubernetes Service 工作負載身份識別
本地開發 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 角色

為了讓你的應用程式可以存取金鑰，請為你的受管身份指派適當的 Managed 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