Condividi tramite

Libreria client di Chiavi di Azure Key Vault per Python - versione 4.8.0

  • Articolo

Azure Key Vault contribuisce a risolvere i problemi seguenti:

  • Gestione delle chiavi crittografiche (questa libreria): creare, archiviare e controllare l'accesso alle chiavi usate per crittografare i dati
  • Gestione dei segreti (azure-keyvault-secrets): archiviare e controllare in modo sicuro l'accesso a token, password, certificati, chiavi API e altri segreti
  • Gestione dei certificati (azure-keyvault-certificates): creare, gestire e distribuire certificati SSL/TLS pubblici e privati
  • Amministrazione dell'insieme di credenziali (azure-keyvault-administration): controllo degli accessi in base al ruolo e opzioni di backup e ripristino a livello di insieme di credenziali

Codice | sorgente Pacchetto (PyPI) | Pacchetto (Conda) | Documentazione | di riferimento sulle APIDocumentazione | del prodotto Campioni

Dichiarazione di non responsabilità

Il supporto dei pacchetti Python di Azure SDK per Python 2.7 è terminato il 01 gennaio 2022. Per altre informazioni e domande, vedere https://github.com/Azure/azure-sdk-for-python/issues/20691.

Python 3.7 o versione successiva è necessario per usare questo pacchetto. Per altre informazioni, vedere Criteri di supporto per la versione di Azure SDK per Python.

Introduzione

Installare il pacchetto

Installare azure-keyvault-keys e azure-identity con pip:

pip install azure-keyvault-keys azure-identity

azure-identity viene usato per l'autenticazione di Azure Active Directory, come illustrato di seguito.

Prerequisiti

Autenticare il client

Per interagire con il servizio Azure Key Vault, è necessaria un'istanza di KeyClient, nonché un URL dell'insieme di credenziali e un oggetto credenziale. Questo documento illustra l'uso di un oggetto DefaultAzureCredential, appropriato per la maggior parte degli scenari, inclusi gli ambienti di sviluppo e produzione locali. È consigliabile usare un'identità gestita per l'autenticazione negli ambienti di produzione.

Per altre informazioni su altri metodi di autenticazione e sui tipi di credenziali corrispondenti, vedere la documentazione di azure-identity .

Creare un client

Dopo aver configurato l'ambiente per DefaultAzureCredential per l'uso di un metodo di autenticazione appropriato, è possibile eseguire le operazioni seguenti per creare un client di chiavi (sostituendo il valore di VAULT_URL con l'URL dell'insieme di credenziali):

VAULT_URL = os.environ["VAULT_URL"]
credential = DefaultAzureCredential()
client = KeyClient(vault_url=VAULT_URL, credential=credential)

NOTA: Per un client asincrono, importare azure.keyvault.keys.aioinvece .KeyClient

Concetti chiave

Chiavi

Azure Key Vault può creare e archiviare chiavi RSA e curve ellittiche. Entrambi possono essere protetti facoltativamente da moduli di protezione hardware.Both can optionally be protected by hardware security modules (HSMs). Azure Key Vault può anche eseguire operazioni di crittografia. Per altre informazioni sulle chiavi e sulle operazioni e sugli algoritmi supportati, vedere la documentazione di Key Vault.

KeyClient può creare chiavi nell'insieme di credenziali, ottenere le chiavi esistenti dall'insieme di credenziali, aggiornare i metadati della chiave ed eliminare le chiavi, come illustrato negli esempi seguenti.

Esempio

Questa sezione contiene frammenti di codice relativi alle attività comuni:

Creare una chiave

create_rsa_key e create_ec_key creare rispettivamente chiavi RSA e curva ellittica nell'insieme di credenziali. Se esiste già una chiave con lo stesso nome, viene creata una nuova versione di tale chiave.

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient

credential = DefaultAzureCredential()

key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

# Create an RSA key
rsa_key = key_client.create_rsa_key("rsa-key-name", size=2048)
print(rsa_key.name)
print(rsa_key.key_type)

# Create an elliptic curve key
ec_key = key_client.create_ec_key("ec-key-name", curve="P-256")
print(ec_key.name)
print(ec_key.key_type)

Recuperare una chiave

get_key recupera una chiave archiviata in precedenza nell'insieme di credenziali.

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient

credential = DefaultAzureCredential()

key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
key = key_client.get_key("key-name")
print(key.name)

Aggiornare una chiave esistente

update_key_properties aggiorna le proprietà di una chiave archiviata in precedenza nel Key Vault.

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient

credential = DefaultAzureCredential()

key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

# we will now disable the key for further use
updated_key = key_client.update_key_properties("key-name", enabled=False)

print(updated_key.name)
print(updated_key.properties.enabled)

Eliminare una chiave

begin_delete_key richieste Key Vault eliminare una chiave, restituendo un poller che consente di attendere il completamento dell'eliminazione. L'attesa è utile quando l'insieme di credenziali ha abilitato l'eliminazione temporanea e si vuole eliminare definitivamente la chiave il prima possibile. Quando l'eliminazione temporanea è disabilitata, begin_delete_key è permanente.

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient

credential = DefaultAzureCredential()

key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
deleted_key = key_client.begin_delete_key("key-name").result()

print(deleted_key.name)
print(deleted_key.deleted_date)

Configurare la rotazione automatica delle chiavi

update_key_rotation_policy consente di configurare la rotazione automatica delle chiavi per una chiave specificando un criterio di rotazione. Inoltre, rotate_key consente di ruotare una chiave su richiesta creando una nuova versione della chiave specificata.

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient, KeyRotationLifetimeAction, KeyRotationPolicyAction

credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

# Set the key's automated rotation policy to rotate the key 30 days before the key expires
actions = [KeyRotationLifetimeAction(KeyRotationPolicyAction.ROTATE, time_before_expiry="P30D")]
# You may also specify the duration after which the newly rotated key will expire
# In this example, any new key versions will expire after 90 days
updated_policy = key_client.update_key_rotation_policy("key-name", expires_in="P90D", lifetime_actions=actions)

# You can get the current rotation policy for a key with get_key_rotation_policy
current_policy = key_client.get_key_rotation_policy("key-name")

# Finally, you can rotate a key on-demand by creating a new version of the key
rotated_key = key_client.rotate_key("key-name")

List keys

list_properties_of_keys elenca le proprietà di tutte le chiavi nell'insieme di credenziali del client.

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient

credential = DefaultAzureCredential()

key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
keys = key_client.list_properties_of_keys()

for key in keys:
    # the list doesn't include values or versions of the keys
    print(key.name)

Operazioni crittografiche

CryptographyClient abilita le operazioni di crittografia (crittografia/decrittografia, wrapping/annullamento del wrapping, firma/verifica) usando una chiave specifica.

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

credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

key = key_client.get_key("key-name")
crypto_client = CryptographyClient(key, credential=credential)
plaintext = b"plaintext"

result = crypto_client.encrypt(EncryptionAlgorithm.rsa_oaep, plaintext)
decrypted = crypto_client.decrypt(result.algorithm, result.ciphertext)

Per altri dettagli sull'API di crittografia, vedere la documentazione del pacchetto .

API asincrona

Questa libreria include un set completo di API asincrone. Per usarli, è prima necessario installare un trasporto asincrono, ad esempio aiohttp. Per altre informazioni, vedere la documentazione di azure-core .

I client e le credenziali asincroni devono essere chiusi quando non sono più necessari. Questi oggetti sono gestori di contesti asincroni e definiscono metodi asincroni close . Ad esempio:

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.keys.aio import KeyClient

credential = DefaultAzureCredential()

# call close when the client and credential are no longer needed
client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
...
await client.close()
await credential.close()

# alternatively, use them as async context managers (contextlib.AsyncExitStack can help)
client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
async with client:
  async with credential:
    ...

Creare in modo asincrono una chiave

create_rsa_key e create_ec_key creare rispettivamente chiavi RSA e curva ellittica nell'insieme di credenziali. Se esiste già una chiave con lo stesso nome, viene creata una nuova versione della chiave.

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.keys.aio import KeyClient

credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

# Create an RSA key
rsa_key = await key_client.create_rsa_key("rsa-key-name", size=2048)
print(rsa_key.name)
print(rsa_key.key_type)

# Create an elliptic curve key
ec_key = await key_client.create_ec_key("ec-key-name", curve="P-256")
print(ec_key.name)
print(ec_key.key_type)

Elencare in modo asincrono le chiavi

list_properties_of_keys elenca le proprietà di tutte le chiavi nell'insieme di credenziali del client.

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.keys.aio import KeyClient

credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
keys = key_client.list_properties_of_keys()

async for key in keys:
    print(key.name)

Risoluzione dei problemi

Per informazioni dettagliate su come diagnosticare vari scenari di errore, vedere la azure-keyvault-keysguida alla risoluzione dei problemi .

Generale

Key Vault client generano eccezioni definite in azure-core. Ad esempio, se si tenta di ottenere una chiave che non esiste nell'insieme di credenziali, KeyClient genera ResourceNotFoundError:

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient
from azure.core.exceptions import ResourceNotFoundError

credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

try:
    key_client.get_key("which-does-not-exist")
except ResourceNotFoundError as e:
    print(e.message)

Registrazione

Questa libreria usa la libreria di registrazione standard per la registrazione. Le informazioni di base sulle sessioni HTTP (URL, intestazioni e così via) vengono registrate a livello di INFO.

La registrazione dettagliata a livello di DEBUG, inclusi i corpi di richiesta/risposta e le intestazioni non contrassegnate, può essere abilitata in un client con l'argomento logging_enable :

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient
import sys
import logging

# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

credential = DefaultAzureCredential()

# This client will log detailed information about its HTTP sessions, at DEBUG level
client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential, logging_enable=True)

Analogamente, logging_enable può abilitare la registrazione dettagliata per una singola operazione, anche quando non è abilitata per il client:

client.get_key("my-key", logging_enable=True)

Passaggi successivi

Sono disponibili diversi esempi nel repository GitHub di Azure SDK per Python. Questi forniscono codice di esempio per altri scenari di Key Vault: | File | Descrizione | |-------------|-------------| | hello_world.py (versione asincrona) | creare/ottenere/aggiornare/eliminare chiavi | | list_operations.py (versione asincrona) | operazioni di elenco di base per le chiavi | | backup_restore_operations.py (versione asincrona) | eseguire il backup e il ripristino delle chiavi | | recover_purge_operations.py (versione asincrona) | recuperare ed eliminare le chiavi | | send_request.py | utilizzare il send_request metodo client |

Documentazione aggiuntiva

Per una documentazione più completa su Azure Key Vault, vedere la documentazione di riferimento sulle API.

Contributo

In questo progetto sono benvenuti i contributi e i suggerimenti. Per la maggior parte dei contenuti è necessario sottoscrivere un contratto di licenza di collaborazione (CLA, Contributor License Agreement) che stabilisce che l'utente ha il diritto di concedere, e di fatto concede a Microsoft i diritti d'uso del suo contributo. Per informazioni dettagliate, vedere https://cla.microsoft.com.

Quando si invia una richiesta pull, un bot CLA determina automaticamente se è necessario specificare un contratto CLA e completare la richiesta pull in modo appropriato (ad esempio con un'etichetta e un commento). Seguire le istruzioni specificate dal bot. È sufficiente eseguire questa operazione una sola volta per tutti i repository che usano il contratto CLA Microsoft.

Questo progetto ha adottato il Codice di comportamento di Microsoft per l'open source. Per altre informazioni, vedere Code of Conduct FAQ (Domande frequenti sul Codice di comportamento) oppure contattare opencode@microsoft.com per eventuali altre domande o commenti.

Impression