Biblioteca de clientes do Azure Key Vault Keys para Python – versão 4.8.0

  • Artigo

O Azure Key Vault ajuda a resolver os problemas a seguir:

  • Gerenciamento de chaves criptográficas (esta biblioteca) – criar, armazenar e controlar o acesso às chaves usadas para criptografar seus dados
  • Gerenciamento de segredos (azure-keyvault-secrets) – armazenar e controlar com segurança o acesso a tokens, senhas, certificados, chaves de API e outros segredos
  • Gerenciamento de certificados (azure-keyvault-certificates) – criar, gerenciar e implantar certificados SSL/TLS públicos e privados
  • Administração do cofre (azure-keyvault-administration) – RBAC (controle de acesso baseado em função) e opções de backup e restauração no nível do cofre

Código-fonte | Pacote (PyPI) | Pacote (Conda) | Documentação | de referência da APIDocumentação do produto | Amostras

Aviso de isenção de responsabilidade

O suporte a pacotes python do SDK do Azure para Python 2.7 terminou em 01 de janeiro de 2022. Para obter mais informações, consulte https://github.com/Azure/azure-sdk-for-python/issues/20691.

É necessário ter o Python 3.7 ou posterior para usar esse pacote. Para obter mais detalhes, consulte a política de suporte do SDK do Azure para Python.

Introdução

Instalar o pacote

Instale azure-keyvault-keys e azure-identity com pip:

pip install azure-keyvault-keys azure-identity

azure-identity é usado para autenticação do Azure Active Directory, conforme demonstrado abaixo.

Pré-requisitos

Autenticar o cliente

Para interagir com o serviço Key Vault do Azure, você precisará de uma instância de um KeyClient, bem como uma URL do cofre e um objeto de credencial. Este documento demonstra o uso de um DefaultAzureCredential, que é apropriado para a maioria dos cenários, incluindo ambientes locais de desenvolvimento e produção. É recomendável usar uma identidade gerenciada para autenticação em ambientes de produção.

Consulte a documentação de identidade do azure para obter mais informações sobre outros métodos de autenticação e seus tipos de credencial correspondentes.

Criar um cliente

Depois de configurar seu ambiente para o DefaultAzureCredential usar um método adequado de autenticação, você pode fazer o seguinte para criar um cliente de chave (substituindo o valor de VAULT_URL pela URL do cofre):

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

NOTA: Para um cliente assíncrono, importe azure.keyvault.keys.aioem KeyClient vez disso.

Principais conceitos

Teclas

Os Key Vault do Azure podem criar e armazenar chaves de curva elípticas e RSA. Opcionalmente, ambos podem ser protegidos por HSMs (módulos de segurança de hardware). Os Key Vault do Azure também podem executar operações criptográficas com eles. Para obter mais informações sobre chaves e algoritmos e operações com suporte, consulte a documentação do Key Vault.

KeyClient pode criar chaves no cofre, obter chaves existentes do cofre, atualizar metadados de chave e excluir chaves, conforme mostrado nos exemplos abaixo.

Exemplos

Esta seção contém snippets de código que abrangem tarefas comuns:

Criar uma chave

create_rsa_key e create_ec_key criar chaves de curva Elíptica e RSA no cofre, respectivamente. Se uma chave com o mesmo nome já existir, uma nova versão dessa chave será criada.

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)

Recuperar uma chave

get_key recupera uma chave armazenada anteriormente no Cofre.

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)

Atualizar uma chave existente

update_key_properties atualiza as propriedades de uma chave armazenada anteriormente no 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)

Excluir uma chave

begin_delete_key solicita Key Vault excluir uma chave, retornando um sondador que permite aguardar a conclusão da exclusão. Aguardar é útil quando o cofre tem a exclusão temporária habilitada e você deseja limpar (excluir permanentemente) a chave o mais rápido possível. Quando a exclusão reversível é desabilitada, begin_delete_key ela é 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)

Configurar a rotação automática de chaves

update_key_rotation_policy permite configurar a rotação automática de chaves para uma chave especificando uma política de rotação. Além disso, rotate_key permite girar uma chave sob demanda criando uma nova versão da chave fornecida.

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

Listar chaves

list_properties_of_keys lista as propriedades de todas as chaves no cofre do 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)

Operações de criptografia

CryptographyClient habilita operações criptográficas (criptografar/descriptografar, encapsular/desencapsar, assinar/verificar) usando uma chave específica.

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 a documentação do pacote para obter mais detalhes sobre a API de criptografia.

API assíncrona

Essa biblioteca inclui um conjunto completo de APIs assíncronas. Para usá-los, primeiro você deve instalar um transporte assíncrono, como aiohttp. Confira a documentação do azure-core para obter mais informações.

Clientes e credenciais assíncronos devem ser fechados quando não forem mais necessários. Esses objetos são gerenciadores de contexto assíncronos e definem métodos assíncronos close . Por exemplo:

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

Criar uma chave de forma assíncrona

create_rsa_key e create_ec_key criar chaves de curva Elíptica e RSA no cofre, respectivamente. Se uma chave com o mesmo nome já existir, uma nova versão da chave será criada.

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)

Listar chaves de forma assíncrona

list_properties_of_keys lista as propriedades de todas as chaves no cofre do 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)

Solução de problemas

Consulte o azure-keyvault-keysguia de solução de problemas para obter detalhes sobre como diagnosticar vários cenários de falha.

Geral

Key Vault clientes geram exceções definidas no azure-core. Por exemplo, se você tentar obter uma chave que não existe no cofre, KeyClient aciona 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 em log

Essa biblioteca usa a biblioteca de log padrão para registro em log. Informações básicas sobre sessões HTTP (URLs, cabeçalhos etc.) são registradas no nível INFO.

O log detalhado do nível DEBUG, incluindo corpos de solicitação/resposta e cabeçalhos não redigidos, pode ser habilitado em um cliente com o 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)

Da mesma forma, logging_enable pode habilitar o log detalhado para uma operação individual, mesmo quando ela não está habilitada para o cliente:

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

Próximas etapas

Vários exemplos estão disponíveis no repositório gitHub do SDK do Azure para Python. Eles fornecem código de exemplo para cenários de Key Vault adicionais: | Arquivo | Descrição | |-------------|-------------| | hello_world.py (versão assíncrona) | criar/obter/atualizar/excluir chaves | | list_operations.py (versão assíncrona) | operações básicas de lista para chaves | | backup_restore_operations.py (versão assíncrona) | fazer backup e recuperar chaves | | recover_purge_operations.py (versão assíncrona) | recuperar e limpar chaves | | send_request.py | usar o send_request método cliente |

Documentação adicional

Para obter uma documentação mais abrangente sobre Key Vault do Azure, consulte a documentação de referência da API.

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite https://cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o código de conduta ou entre em contato com opencode@microsoft.com para enviar outras perguntas ou comentários.

Impressões