Biblioteca de cliente chaves do Azure Key Vault para Python – versão 4.8.0

O Azure Key Vault ajuda a resolver os seguintes problemas:

• Gestão de chaves criptográficas (esta biblioteca) – criar, armazenar e controlar o acesso às chaves utilizadas para encriptar os seus dados
• Gestão de segredos (azure-keyvault-secrets) – armazenar e controlar de forma segura o acesso a tokens, palavras-passe, certificados, chaves de API e outros segredos
• Gestão de certificados (azure-keyvault-certificates) – criar, gerir e implementar certificados SSL/TLS públicos e privados
• Administração do cofre (azure-keyvault-administration) – controlo de acesso baseado em funções (RBAC) e opções de cópia de segurança e restauro ao nível do cofre

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

Exclusão de Responsabilidade

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

O Python 3.7 ou posterior é necessário para utilizar este pacote. Para obter mais detalhes, veja Azure SDK for Python version support policy (Política de suporte de versões do Azure SDK 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 é utilizado para a autenticação do Azure Active Directory, conforme demonstrado abaixo.

Pré-requisitos

• Uma subscrição do Azure
• Python 3.7 ou posterior
• Um Azure Key Vault existente. Se precisar de criar uma, pode fazê-lo com a CLI do Azure ao seguir os passos neste documento.
• Se utilizar o HSM Gerido, um HSM Gerido Key Vault existente. Se precisar de criar um HSM Gerido, pode fazê-lo com a CLI do Azure ao seguir os passos neste documento.

Autenticar o cliente

Para interagir com o serviço Key Vault do Azure, precisará de uma instância de um KeyClient, bem como de um URL do cofre e de um objeto de credencial. Este documento demonstra a utilização de um DefaultAzureCredential, que é adequado para a maioria dos cenários, incluindo ambientes de desenvolvimento local e de produção. Recomendamos a utilização de uma identidade gerida para autenticação em ambientes de produção.

Veja a documentação do azure-identity para obter mais informações sobre outros métodos de autenticação e os respetivos tipos de credenciais correspondentes.

Criar um cliente

Depois de configurar o seu ambiente para o DefaultAzureCredential utilizar um método de autenticação adequado, pode fazer o seguinte para criar um cliente chave (substituindo o valor de VAULT_URL pelo 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.aio's KeyClient em vez disso.

Conceitos-chave

Chaves

O Azure Key Vault pode criar e armazenar teclas RSA e curvas elípticas. Opcionalmente, ambos podem ser protegidos por módulos de segurança de hardware (HSMs). O Azure Key Vault também pode realizar operações criptográficas com as mesmas. Para obter mais informações sobre chaves e operações e algoritmos suportados, veja a documentação do Key Vault.

O KeyClient pode criar chaves no cofre, obter chaves existentes a partir do cofre, atualizar metadados de chaves e eliminar chaves, conforme mostrado nos exemplos abaixo.

Exemplos

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

• Criar uma chave
• Obter uma chave
• Atualizar uma chave existente
• Eliminar uma chave
• Configurar a rotação automática de chaves
• Listar chaves
• Executar operações criptográficas
• API Assíncrona
• Criar uma chave de forma assíncrona
• Chaves de lista assíncronas

Criar uma chave

create_rsa_key e create_ec_key criar teclas RSA e curvas elípticas no cofre, respetivamente. Se já existir uma chave com o mesmo nome, será criada uma nova versão dessa chave.

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)

Obter uma chave

get_key obtém uma chave anteriormente armazenada 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 anteriormente armazenada 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)

Eliminar uma chave

begin_delete_key pedidos Key Vault eliminar uma chave, devolvendo um poller que lhe permite aguardar que a eliminação seja concluída. A espera é útil quando o cofre tem a eliminação recuperável ativada e pretende remover (eliminar permanentemente) a chave o mais rapidamente possível. Quando a eliminação recuperável é desativada, begin_delete_key a própria é 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-lhe configurar a rotação automática de chaves para uma chave ao especificar uma política de rotação. Além disso, rotate_key permite-lhe rodar uma chave a pedido ao criar uma nova versão da chave 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")

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 criptográficas

CryptographyClient permite operações criptográficas (encriptar/desencriptar, moldar/desembrulhar, assinar/verificar) com 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)

Veja a documentação do pacote para obter mais detalhes sobre a API de criptografia.

API Assíncrona

Esta biblioteca inclui um conjunto completo de APIs assíncronas. Para utilizá-los, primeiro tem de instalar um transporte assíncrono, como aiohttp. Veja a documentação do azure-core para obter mais informações.

Os clientes assíncronas e as credenciais devem ser fechados quando já não forem necessários. Estes objetos são gestores de contexto assíncrono e definem métodos assíncrono 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 teclas RSA e curvas elípticas no cofre, respetivamente. Se já existir uma chave com o mesmo nome, será criada uma nova versão da chave.

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)

Chaves de lista assíncronas

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)

Resolução de problemas

Veja o azure-keyvault-keysguia de resoluçã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 tentar obter uma chave que não existe no cofre, o KeyClient gera 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)

Registo

Esta biblioteca utiliza a biblioteca de registos padrão para registos. As informações básicas sobre as sessões HTTP (URLs, cabeçalhos, etc.) são registadas ao nível da INFO.

O registo ao nível de DEBUG detalhado, incluindo corpos de pedido/resposta e cabeçalhos não retotados, pode ser ativado num 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 ativar o registo detalhado para uma única operação, mesmo quando não está ativado para o cliente:

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

Passos seguintes

Estão disponíveis vários exemplos no repositório do GitHub do Azure SDK para Python. Estes fornecem código de exemplo para cenários de Key Vault adicionais: | Ficheiro | Descrição | |-------------|-------------| | hello_world.py (versão assíncrona) | criar/obter/atualizar/eliminar chaves | | list_operations.py (versão assíncrona) | operações de lista básicas para chaves | | backup_restore_operations.py (versão assíncrona) | fazer cópia de segurança e recuperar chaves | | recover_purge_operations.py (versão assíncrona) | recuperar e remover chaves | | send_request.py | utilizar o send_request método de cliente |

Documentação adicional

Para obter documentação mais extensa sobre o Azure Key Vault, veja a documentação de referência da API.

Contribuir

Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para mais detalhes, visite https://cla.microsoft.com.

Quando submete um pedido Pull, um bot do CLA determina automaticamente se tem de fornecer um CLA e decorar o PR de forma adequada (por exemplo, etiqueta, comentário). Só tem de seguir as instruções fornecidas pelo bot. Apenas terá de fazer isto uma vez em todos os repositórios com o nosso CLA.

Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para obter mais informações, veja a Code of Conduct FAQ (FAQ do Código de Conduta) ou envie um e-mail para opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.