Quickstart: libreria client di HSM gestito di Azure Key Vault per Python

Inizia con la libreria client di HSM gestito di Azure Key Vault per Python. Il modulo di protezione hardware gestito è un servizio cloud completamente gestito, a disponibilità elevata, a tenant singolo e conforme agli standard che consente di proteggere le chiavi crittografiche per le applicazioni cloud, usando moduli di protezione hardware convalidati FIPS 140-3 di livello 3 . Per ulteriori informazioni sull'HSM gestito, consultare la Panoramica.

In questa guida introduttiva si apprenderà come accedere ed eseguire operazioni di crittografia sulle chiavi in un modulo di protezione hardware gestito usando la libreria client Python.

Risorse della libreria client dell'HSM gestito:

documentazione di riferimento API | Codice sorgente della libreria | Package (PyPI)

Prerequisiti

Configurare l'ambiente locale

Questa guida introduttiva usa la libreria di identità Azure con interfaccia della riga di comando di Azure per eseguire l'autenticazione ai servizi di Azure. Gli sviluppatori possono anche usare Visual Studio Code per autenticare le chiamate. Per altre informazioni, vedere Authenticate the client with Azure Identity client library.

Accedere a Azure

Eseguire il az login comando per accedere:

az login

Creare una cartella di progetto e un ambiente virtuale

  1. Creare una cartella progetto e accedervi.

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

  2. Creare e attivare un ambiente virtuale:

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

Installare i pacchetti

Installare le librerie client di identità di Azure e delle chiavi di Key Vault.

pip install azure-identity azure-keyvault-keys

Creare il codice di esempio

Creare un file denominato mhsm_keys.py con il codice seguente. Sostituisci <hsm-name> con il nome del tuo HSM gestito e <key-name> con un nome di chiave esistente.

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!")

Eseguire l'applicazione

Eseguire l'applicazione:

python mhsm_keys.py

L'output dovrebbe essere simile al seguente:

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!

Informazioni sul codice

Autenticazione con DefaultAzureCredential

DefaultAzureCredential seleziona automaticamente le credenziali appropriate in base all'ambiente:

Ambiente Credenziali usate
Funzioni, Servizio app e Macchine virtuali di Azure Identità gestita assegnata dal sistema o assegnata dall'utente
servizio Azure Kubernetes Identità del carico di lavoro
Sviluppo locale credenziali di interfaccia della riga di comando di Azure, Visual Studio o VS Code
Pipeline CI/CD Federazione o entità servizio dell'identità del carico di lavoro

La verifica delle credenziali controlla queste fonti in ordine:

  1. Variabili di ambiente
  2. Identità del carico di lavoro
  3. Identità gestita
  4. interfaccia della riga di comando di Azure
  5. Azure PowerShell
  6. credenziali di Visual Studio/VS Code

Per i carichi di lavoro di produzione in Azure, le identità gestite sono fortemente consigliate perché eliminano completamente la gestione delle credenziali.

Operazioni chiave

La KeyClient classe fornisce metodi per:

  • Creare, ottenere, aggiornare ed eliminare chiavi
  • Elencare le chiavi e le versioni delle chiavi
  • Eseguire il backup e il ripristino delle chiavi

La CryptographyClient classe fornisce operazioni di crittografia:

  • Crittografare e decrittografare i dati
  • Firmare e verificare le firme
  • Eseguire e annullare il wrapping delle chiavi

Assegnare ruoli di HSM gestito

Per consentire all'applicazione di accedere alle chiavi, assegnare il ruolo di Controllo degli accessi in base al ruolo locale di HSM gestito corretto alla propria identità gestita. Sostituire <vm-name>, <resource-group>e <hsm-name> con i valori effettivi.

# 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

Per altre informazioni su ruoli e autorizzazioni, vedere Ruoli predefiniti RBAC locali di HSM gestito.

Pulire le risorse

Quando non sono più necessari, eliminare il gruppo di risorse e tutte le risorse correlate:

az group delete --name <resource-group>

Avviso

L'eliminazione del gruppo di risorse attiva lo stato di eliminazione temporanea per il modulo di protezione hardware gestito. L'HSM gestito continua a essere fatturato fino a quando non viene eliminato definitivamente. Vedere Eliminazione temporanea e protezione dall'eliminazione dell'HSM gestito

Passaggi successivi

  • Last updated on