Biblioteca cliente de Claves de Azure Key Vault para Python: versión 4.8.0
Azure Key Vault ayuda a solucionar los problemas siguientes:
- Administración de claves criptográficas (esta biblioteca): creación, almacenamiento y control del acceso a las claves usadas para cifrar los datos
- Administración de secretos (azure-keyvault-secrets): almacene y controle de forma segura el acceso a tokens, contraseñas, certificados, claves de API y otros secretos.
- Administración de certificados (azure-keyvault-certificates): creación, administración e implementación de certificados SSL/TLS públicos y privados
- Administración de almacenes (azure-keyvault-administration): control de acceso basado en rol (RBAC) y opciones de copia de seguridad y restauración de nivel de almacén
Código | fuente Paquete (PyPI) | Paquete (Conda) | Documentación | de referencia de API | Documentación del productoMuestras
Declinación de responsabilidades
Los paquetes de Python del SDK de Azure admiten Python 2.7 finalizó el 01 de enero de 2022. Para más información y preguntas, consulte https://github.com/Azure/azure-sdk-for-python/issues/20691.
Se requiere Python 3.7 o posterior para usar este paquete. Para obtener más información, consulte la directiva de compatibilidad de la versión del SDK de Azure para Python.
Introducción
Instalar el paquete
Instale azure-keyvault-keys y azure-identity con pip:
pip install azure-keyvault-keys azure-identity
azure-identity se usa para la autenticación de Azure Active Directory, como se muestra a continuación.
Requisitos previos
- Una suscripción de Azure
- Python 3.7 o versiones posteriores
- Una Key Vault de Azure existente. Si necesita crear una, puede hacerlo mediante la CLI de Azure siguiendo los pasos descritos en este documento.
- Si usa HSM administrado, un HSM administrado existente Key Vault. Si necesita crear un HSM administrado, puede hacerlo mediante la CLI de Azure siguiendo los pasos descritos en este documento.
Autenticar el cliente
Para interactuar con el servicio azure Key Vault, necesitará una instancia de KeyClient, así como una dirección URL del almacén y un objeto de credencial. En este documento se muestra el uso de defaultAzureCredential, que es adecuado para la mayoría de los escenarios, incluidos los entornos de desarrollo y producción locales. Se recomienda usar una identidad administrada para la autenticación en entornos de producción.
Consulte la documentación de azure-identity para obtener más información sobre otros métodos de autenticación y sus tipos de credenciales correspondientes.
Creación de un cliente
Después de configurar el entorno para que DefaultAzureCredential use un método adecuado de autenticación, puede hacer lo siguiente para crear un cliente de clave (reemplazando el valor de VAULT_URL por la dirección URL del almacén):
VAULT_URL = os.environ["VAULT_URL"]
credential = DefaultAzureCredential()
client = KeyClient(vault_url=VAULT_URL, credential=credential)
NOTA: Para un cliente asincrónico, importe
azure.keyvault.keys.aioenKeyClientsu lugar.
Conceptos clave
Teclas
Azure Key Vault puede crear y almacenar claves de curva RSA y elípticas. Ambos se pueden proteger opcionalmente mediante módulos de seguridad de hardware (HSM). Azure Key Vault también puede realizar operaciones criptográficas con ellos. Para obtener más información sobre las claves y las operaciones y algoritmos admitidos, consulte la documentación de Key Vault.
KeyClient puede crear claves en el almacén, obtener claves existentes del almacén, actualizar metadatos de clave y eliminar claves, como se muestra en los ejemplos siguientes.
Ejemplos
Esta sección contiene fragmentos de código que abarcan tareas comunes:
- Crear una clave
- Recuperación de una clave
- Actualización de una clave existente
- Eliminar una clave
- Configuración de la rotación automática de claves
- Enumeración de claves
- Realización de operaciones criptográficas
- API asincrónica
- Creación asincrónica de una clave
- Enumerar claves de forma asincrónica
Crear una clave
create_rsa_key y create_ec_key crear claves de curva RSA y elípticas en el almacén, respectivamente. Si ya existe una clave con el mismo nombre, se crea una nueva versión de esa clave.
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)
Recuperación de una clave
get_key recupera una clave almacenada anteriormente en el almacén.
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)
Actualización de una clave existente
update_key_properties actualiza las propiedades de una clave almacenada previamente en el 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)
Eliminación de una clave
begin_delete_key solicita Key Vault eliminar una clave, devolviendo un sondeo que permite esperar a que finalice la eliminación. La espera resulta útil cuando el almacén tiene habilitada la eliminación temporal y desea purgar (eliminar permanentemente) la clave lo antes posible. Cuando la eliminación temporal está deshabilitada, begin_delete_key es 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)
Configuración de la rotación automática de claves
update_key_rotation_policy permite configurar la rotación automática de claves para una clave mediante la especificación de una directiva de rotación. Además, rotate_key permite rotar una clave a petición mediante la creación de una nueva versión de la clave especificada.
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")
Enumeración de claves
list_properties_of_keys enumera las propiedades de todas las claves del almacén del cliente.
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)
Operaciones criptográficas
CryptographyClient permite operaciones criptográficas (cifrar/descifrar, encapsular/desencapsular, firmar/comprobar) mediante una clave determinada.
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)
Consulte la documentación del paquete para obtener más detalles de la API de criptografía.
API asincrónica
Esta biblioteca incluye un conjunto completo de API asincrónicas. Para usarlos, primero debe instalar un transporte asincrónico, como aiohttp. Consulte la documentación de azure-core para más información.
Los clientes y credenciales asincrónicos deben cerrarse cuando ya no sean necesarios. Estos objetos son administradores de contexto asincrónicos y definen métodos asincrónicos close . Por ejemplo:
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:
...
Creación asincrónica de una clave
create_rsa_key y create_ec_key crear claves de curva RSA y elípticas en el almacén, respectivamente. Si ya existe una clave con el mismo nombre, se crea una nueva versión de la clave.
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)
Enumerar claves de forma asincrónica
list_properties_of_keys enumera las propiedades de todas las claves del almacén del cliente.
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)
Solución de problemas
Consulte la azure-keyvault-keysguía de solución de problemas para obtener más información sobre cómo diagnosticar varios escenarios de error.
General
Key Vault los clientes generan excepciones definidas en azure-core. Por ejemplo, si intenta obtener una clave que no existe en el almacén, 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)
Registro
Esta biblioteca usa la biblioteca de registro estándar para el registro. La información básica sobre las sesiones HTTP (direcciones URL, encabezados, etc.) se registra en el nivel INFO.
El registro detallado de nivel de DEPURACIÓN, incluidos los cuerpos de solicitud/respuesta y los encabezados no aprobados, se puede habilitar en un cliente con el logging_enable argumento :
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)
Igualmente, logging_enable puede habilitar el registro detallado de una sola operación, aunque no esté habilitado para el cliente:
client.get_key("my-key", logging_enable=True)
Pasos siguientes
Hay varios ejemplos disponibles en el repositorio de GitHub del SDK de Azure para Python.
Estos proporcionan código de ejemplo para escenarios de Key Vault adicionales: | Archivo | Descripción | |-------------|-------------| | hello_world.py (versión asincrónica) | create/get/update/delete keys | | list_operations.py (versión asincrónica) | Operaciones básicas de lista para claves | | backup_restore_operations.py (versión asincrónica) | copia de seguridad y recuperación de claves | | recover_purge_operations.py (versión asincrónica) | recuperar y purgar claves | | send_request.py | usar el send_request método de cliente |
Documentación adicional
Para obtener documentación más amplia sobre Azure Key Vault, consulte la documentación de referencia de api.
Contribuciones
Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más detalles, visite https://cla.microsoft.com.
Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.
El proyecto ha adoptado el Código de conducta de código abierto de Microsoft. Para obtener más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.
Azure SDK for Python
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de