Klientská knihovna Klíčů Azure Key Vault pro Python – verze 4.8.0

  • Článek

Azure Key Vault pomáhá vyřešit následující problémy:

  • Správa kryptografických klíčů (tato knihovna) – vytváření, ukládání a řízení přístupu ke klíčům používaným k šifrování dat
  • Správa tajných kódů (azure-keyvault-secrets) – bezpečné ukládání a řízení přístupu k tokenům, heslům, certifikátům, klíčům rozhraní API a dalším tajným klíčům
  • Správa certifikátů (azure-keyvault-certificates) – vytváření, správa a nasazování veřejných a privátních certifikátů SSL/TLS
  • Správa trezoru (azure-keyvault-administration) – řízení přístupu na základě role (RBAC) a možnosti zálohování a obnovení na úrovni trezoru

Zdrojový kód | Balíček (PyPI) | Balíček (Conda) | Referenční dokumentace k | rozhraní API Dokumentace k | produktu Vzorky

Právní omezení

Podpora balíčků Azure SDK Python pro Python 2.7 skončila 1. ledna 2022. Další informace a dotazy najdete v tématu https://github.com/Azure/azure-sdk-for-python/issues/20691.

K použití tohoto balíčku se vyžaduje Python 3.7 nebo novější. Další podrobnosti najdete v tématu Věnovaném zásadám podpory verzí sady Azure SDK pro Python.

Začínáme

Instalace balíčku

Nainstalujte azure-keyvault-keys a azure-identity pomocí pipu:

pip install azure-keyvault-keys azure-identity

azure-identity se používá pro ověřování Azure Active Directory, jak je znázorněno níže.

Požadavky

Ověření klienta

Abyste mohli pracovat se službou Azure Key Vault, budete potřebovat instanci KeyClient, adresu URL trezoru a objekt přihlašovacích údajů. Tento dokument ukazuje použití DefaultAzureCredential, které je vhodné pro většinu scénářů, včetně místních vývojových a produkčních prostředí. Pro ověřování v produkčních prostředích doporučujeme používat spravovanou identitu .

Další informace o dalších metodách ověřování a jejich odpovídajících typech přihlašovacích údajů najdete v dokumentaci azure-identity .

Vytvoření klienta

Po konfiguraci prostředí pro DefaultAzureCredential pro použití vhodné metody ověřování můžete následujícím způsobem vytvořit klienta klíče (hodnotu nahraďte VAULT_URL adresou URL trezoru):

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

POZNÁMKA: V případě asynchronního klienta místo toho importujte azure.keyvault.keys.aio.KeyClient

Klíčové koncepty

Klíče

Azure Key Vault může vytvářet a ukládat klíče RSA a eliptické křivky. Volitelně je možné chránit moduly hardwarového zabezpečení (HSM). Azure Key Vault s nimi také může provádět kryptografické operace. Další informace o klíčích a podporovaných operacích a algoritmech najdete v dokumentaci k Key Vault.

KeyClient může vytvářet klíče v trezoru, získávat existující klíče z trezoru, aktualizovat metadata klíčů a odstraňovat klíče, jak je znázorněno v následujících příkladech .

Příklady

Tato část obsahuje fragmenty kódu, které pokrývají běžné úlohy:

Vytvoření klíče

create_rsa_key a create_ec_key v trezoru vytvořit klíče RSA a eliptické křivky. Pokud klíč se stejným názvem již existuje, vytvoří se nová verze tohoto klíč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)

Načtení klíče

get_key načte klíč dříve uložený v trezoru.

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)

Aktualizace existujícího klíče

update_key_properties aktualizuje vlastnosti klíče dříve uloženého v 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)

Odstranění klíče

begin_delete_key žádosti Key Vault odstranit klíč a vrátit poller, který vám umožní počkat na dokončení odstranění. Čekání je užitečné, když je v trezoru povolené obnovitelné odstranění a chcete klíč co nejdříve vymazat (trvale odstranit). Pokud je obnovitelné odstranění zakázané, begin_delete_key je samo trvalé.

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)

Konfigurace automatické obměně klíčů

update_key_rotation_policy umožňuje nakonfigurovat automatické obměně klíčů pro klíč zadáním zásady obměně. Kromě toho rotate_key umožňuje obměňovat klíč na vyžádání vytvořením nové verze daného klíč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")

Výpis klíčů

list_properties_of_keys seznam vlastností všech klíčů v trezoru klienta.

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)

Kryptografické operace

CryptographyClient umožňuje kryptografické operace (šifrování/dešifrování, zabalení/rozbalení, podepsání/ověření) pomocí konkrétního klíče.

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)

Další podrobnosti o kryptografickém rozhraní API najdete v dokumentaci k balíčku .

Asynchronní rozhraní API

Tato knihovna obsahuje kompletní sadu asynchronních rozhraní API. Abyste je mohli používat, musíte nejprve nainstalovat asynchronní přenos, například aiohttp. Další informace najdete v dokumentaci k azure-core .

Asynchronní klienti a přihlašovací údaje by se měli zavřít, když už nejsou potřeba. Tyto objekty jsou asynchronní kontextové manažery a definují asynchronní close metody. Příklad:

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

Asynchronní vytvoření klíče

create_rsa_key a create_ec_key v trezoru vytvořit klíče RSA a eliptické křivky. Pokud klíč se stejným názvem již existuje, vytvoří se nová verze klíč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)

Asynchronní výpis klíčů

list_properties_of_keys seznam vlastností všech klíčů v trezoru klienta.

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)

Řešení potíží

azure-keyvault-keys Podrobnosti o tom, jak diagnostikovat různé scénáře selhání, najdete v průvodci odstraňováním potíží.

Obecné

Key Vault klienti vyvolávají výjimky definované v azure-core. Pokud se například pokusíte získat klíč, který v trezoru neexistuje, KeyClient vyvolá chybu 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)

protokolování

Tato knihovna používá pro protokolování standardní knihovnu protokolování . Základní informace o relacích HTTP (adresy URL, hlavičky atd.) se protokolují na úrovni INFO.

Podrobné protokolování úrovně LADĚNÍ, včetně těl požadavků/odpovědí a nereagovaných hlaviček, je možné povolit na klientovi s argumentem 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)

Podobně logging_enable může povolit podrobné protokolování pro jednu operaci, i když není povolené pro klienta:

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

Další kroky

V úložišti Azure SDK pro Python Na GitHubu je k dispozici několik ukázek. Příklady kódu pro další scénáře Key Vault: | Soubor | Popis | |-------------|-------------| | hello_world.py (asynchronní verze) | vytvoření,získání/aktualizace/odstranění klíčů | | list_operations.py (asynchronní verze) | základní operace se seznamem klíčů | | backup_restore_operations.py (asynchronní verze) | zálohování a obnovení klíčů | | recover_purge_operations.py (asynchronní verze) | obnovení a vymazání klíčů | | send_request.py | send_request použití metody klienta |

Další dokumentace

Rozsáhlejší dokumentaci k Azure Key Vault najdete v referenční dokumentaci k rozhraní API.

Přispívání

Tento projekt vítá příspěvky a návrhy. Většina příspěvků vyžaduje souhlas s licenční smlouvou s přispěvatelem (CLA), která stanoví, že máte právo udělit nám práva k používání vašeho příspěvku a skutečně tak činíte. Podrobnosti najdete tady: https://cla.microsoft.com

Při odesílání žádosti o přijetí změn robot CLA automaticky určí, jestli je potřeba poskytnout smlouvu CLA, a příslušným způsobem žádost o přijetí změn upraví (např. přidáním jmenovky nebo komentáře). Stačí postupovat podle pokynů robota. Pro všechna úložiště používající naši smlouvu CLA to stačí udělat jenom jednou.

Tento projekt přijal pravidla chování pro Microsoft Open Source. Další informace najdete v nejčastějších dotazech k pravidlům chování. V případě jakýchkoli dotazů nebo připomínek kontaktujte opencode@microsoft.com.

Imprese