Bibliothèque de client Azure Key Vault Keys pour Python - version 4.8.0

Python 3.7 ou version ultérieure est requis pour utiliser ce package. Pour plus d’informations, reportez-vous à la stratégie de prise en charge des versions du Kit de développement logiciel (SDK) Azure pour Python.

Prise en main

Installer le package

Installez azure-keyvault-keys et azure-identity avec pip :

pip install azure-keyvault-keys azure-identity

azure-identity est utilisé pour l’authentification Azure Active Directory, comme illustré ci-dessous.

Prérequis

• Un abonnement Azure
• Python 3.7 ou version ultérieure
• Un Key Vault Azure existant. Si vous devez en créer un, vous pouvez le faire à l’aide d’Azure CLI en suivant les étapes décrites dans ce document.
• Si vous utilisez un HSM managé, un HSM managé Key Vault existant. Si vous devez créer un HSM managé, vous pouvez le faire à l’aide d’Azure CLI en suivant les étapes décrites dans ce document.

Authentifier le client

Pour interagir avec le service Azure Key Vault, vous avez besoin d’une instance d’un KeyClient, ainsi que d’une URL de coffre et d’un objet d’informations d’identification. Ce document illustre l’utilisation d’une valeur DefaultAzureCredential, qui convient à la plupart des scénarios, y compris les environnements de développement et de production locaux. Nous vous recommandons d’utiliser une identité managée pour l’authentification dans les environnements de production.

Consultez la documentation azure-identity pour plus d’informations sur les autres méthodes d’authentification et leurs types d’informations d’identification correspondants.

Créer un client

Après avoir configuré votre environnement pour que DefaultAzureCredential utilise une méthode d’authentification appropriée, vous pouvez effectuer les opérations suivantes pour créer un client de clé (en remplaçant la valeur de VAULT_URL par l’URL de votre coffre) :

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

NOTE: Pour un client asynchrone, importez azure.keyvault.keys.aioà la KeyClient place.

Concepts clés

Touches

Azure Key Vault pouvez créer et stocker des clés rsa et de courbe elliptique. Les deux peuvent éventuellement être protégés par des modules de sécurité matériels (HSM). Azure Key Vault peuvent également effectuer des opérations de chiffrement avec eux. Pour plus d’informations sur les clés et les opérations et algorithmes pris en charge, consultez la documentation Key Vault.

KeyClient peut créer des clés dans le coffre, obtenir des clés existantes à partir du coffre, mettre à jour les métadonnées de clé et supprimer des clés, comme indiqué dans les exemples ci-dessous.

Exemples

Cette section contient des extraits de code couvrant les tâches courantes :

• Création d’une clé
• Récupérer une clé
• Mettre à jour une clé existante
• Suppression d’une clé
• Configurer la rotation automatique des clés
• Afficher la liste des clés
• Effectuer des opérations de chiffrement
• API asynchrone
• Créer une clé de manière asynchrone
• Lister les clés de manière asynchrone

Créer une clé

create_rsa_key et create_ec_key créer des clés de courbes RSA et elliptique dans le coffre, respectivement. Si une clé portant le même nom existe déjà, une nouvelle version de cette clé est créée.

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)

Récupérer une clé

get_key récupère une clé précédemment stockée dans le coffre.

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)

Mettre à jour une clé existante

update_key_properties met à jour les propriétés d’une clé précédemment stockée dans le 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)

Supprimer une clé

begin_delete_key demande Key Vault supprimer une clé, en retournant un pollneur qui vous permet d’attendre la fin de la suppression. L’attente est utile lorsque la suppression réversible est activée dans le coffre et que vous souhaitez vider (supprimer définitivement) la clé dès que possible. Lorsque la suppression réversible est désactivée, begin_delete_key elle-même est 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)

Configurer la rotation automatique des clés

update_key_rotation_policy vous permet de configurer la rotation automatique des clés pour une clé en spécifiant une stratégie de rotation. En outre, rotate_key vous permet de faire pivoter une clé à la demande en créant une nouvelle version de la clé donnée.

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

Afficher la liste des clés

list_properties_of_keys répertorie les propriétés de toutes les clés dans le coffre du 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)

Opérations de chiffrement

CryptographyClient active les opérations de chiffrement (chiffre/déchiffrement, wrap/unwrap, sign/verify) à l’aide d’une clé particulière.

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)

Pour plus d’informations sur l’API de chiffrement, consultez la documentation du package .

API asynchrone

Cette bibliothèque inclut un ensemble complet d’API asynchrones. Pour les utiliser, vous devez d’abord installer un transport asynchrone, tel que aiohttp. Pour plus d’informations, consultez la documentation azure-core .

Les clients et les informations d’identification asynchrones doivent être fermés lorsqu’ils ne sont plus nécessaires. Ces objets sont des gestionnaires de contexte asynchrones et définissent des méthodes asynchrones close . Par exemple :

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:
    ...

Créer une clé de manière asynchrone

create_rsa_key et create_ec_key créer des clés de courbes RSA et elliptique dans le coffre, respectivement. Si une clé portant le même nom existe déjà, une nouvelle version de la clé est créée.

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)

Lister les clés de manière asynchrone

list_properties_of_keys répertorie les propriétés de toutes les clés dans le coffre du 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)

Dépannage

Consultez le azure-keyvault-keysguide de résolution des problèmes pour plus d’informations sur la façon de diagnostiquer différents scénarios d’échec.

Général

Key Vault clients déclenchent des exceptions définies dans azure-core. Par exemple, si vous essayez d’obtenir une clé qui n’existe pas dans le coffre, KeyClient déclenche 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)

Journalisation

Cette bibliothèque utilise la bibliothèque de journalisation standard pour la journalisation. Les informations de base sur les sessions HTTP (URL, en-têtes, etc.) sont enregistrées au niveau INFO.

La journalisation détaillée au niveau DEBUG, y compris les corps de requête/réponse et les en-têtes non expurgés, peut être activée sur un client avec l’argument 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)

De la même façon, logging_enable peut activer la journalisation détaillée pour une seule opération, même quand elle n’est pas activée pour le client :

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

Étapes suivantes

Plusieurs exemples sont disponibles dans le référentiel GitHub du Kit de développement logiciel (SDK) Azure pour Python. Ceux-ci fournissent un exemple de code pour des scénarios de Key Vault supplémentaires : | Fichier | Description | |-------------|-------------| | hello_world.py (version asynchrone) | créer/obtenir/mettre à jour/supprimer des clés | | list_operations.py (version asynchrone) | opérations de liste de base pour les clés | | backup_restore_operations.py (version asynchrone) | sauvegarder et récupérer des clés | | recover_purge_operations.py (version asynchrone) | récupérer et vider les clés | | send_request.py | utiliser la send_request méthode cliente |

Documentation complémentaire

Pour obtenir une documentation plus complète sur Azure Key Vault, consultez la documentation de référence sur les API.

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, visitez https://cla.microsoft.com.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.