Azure Key Vault Keys-klientbibliotek för Python – version 4.8.0

Azure Key Vault kan hjälpa dig att lösa följande problem:

• Hantering av kryptografiska nycklar (det här biblioteket) – skapa, lagra och kontrollera åtkomsten till de nycklar som används för att kryptera dina data
• Hantering av hemligheter (azure-keyvault-secrets) – lagra och kontrollera åtkomsten till token, lösenord, certifikat, API-nycklar och andra hemligheter på ett säkert sätt
• Certifikathantering (azure-keyvault-certificates) – skapa, hantera och distribuera offentliga och privata SSL/TLS-certifikat
• Valvadministration (azure-keyvault-administration) – rollbaserad åtkomstkontroll (RBAC) och alternativ för säkerhetskopiering och återställning på valvnivå

| Källkod Paket (PyPI) | Paket (Conda) | API-referensdokumentation | Produktdokumentation | Prover

Friskrivning

Stöd för Azure SDK Python-paket för Python 2.7 upphörde den 1 januari 2022. Mer information och frågor finns i https://github.com/Azure/azure-sdk-for-python/issues/20691.

Python 3.7 eller senare krävs för att använda det här paketet. Mer information finns i Supportprincip för Azure SDK för Python-version.

Komma igång

Installera paketet

Installera azure-keyvault-keys och azure-identity med pip:

pip install azure-keyvault-keys azure-identity

azure-identity används för Azure Active Directory-autentisering enligt nedan.

Förutsättningar

• En Azure-prenumeration
• Python 3.7 eller senare
• En befintlig Azure-Key Vault. Om du behöver skapa en kan du göra det med hjälp av Azure CLI genom att följa stegen i det här dokumentet.
• Om du använder Managed HSM, en befintlig Key Vault Managed HSM. Om du behöver skapa en hanterad HSM kan du göra det med hjälp av Azure CLI genom att följa stegen i det här dokumentet.

Autentisera klienten

För att interagera med Azure Key Vault-tjänsten behöver du en instans av en KeyClient, samt en valv-URL och ett autentiseringsobjekt. Det här dokumentet visar hur du använder en DefaultAzureCredential, som är lämplig för de flesta scenarier, inklusive lokala utvecklings- och produktionsmiljöer. Vi rekommenderar att du använder en hanterad identitet för autentisering i produktionsmiljöer.

Mer information om andra autentiseringsmetoder och deras motsvarande typer av autentiseringsuppgifter finns i dokumentationen om azure-identity .

Skapa en klient

När du har konfigurerat din miljö för DefaultAzureCredential för att använda en lämplig autentiseringsmetod kan du göra följande för att skapa en nyckelklient (ersätta värdet VAULT_URL för med valvets URL):

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

OBSERVERA: För en asynkron klient importerar du azure.keyvault.keys.aiodem KeyClient i stället.

Viktiga begrepp

Nycklar

Azure Key Vault kan skapa och lagra RSA- och elliptiska kurvnycklar. Båda kan också skyddas av maskinvarusäkerhetsmoduler (HSM). Azure Key Vault kan också utföra kryptografiska åtgärder med dem. Mer information om nycklar och åtgärder och algoritmer som stöds finns i Key Vault dokumentationen.

KeyClient kan skapa nycklar i valvet, hämta befintliga nycklar från valvet, uppdatera nyckelmetadata och ta bort nycklar, enligt exemplen nedan.

Exempel

Det här avsnittet innehåller kodfragment som omfattar vanliga uppgifter:

• Skapa en nyckel
• Hämta en nyckel
• Uppdatera en befintlig nyckel
• Ta bort en nyckel
• Konfigurera automatisk nyckelrotation
• Listnycklar
• Utföra kryptografiska åtgärder
• Asynkront API
• Skapa en nyckel asynkront
• Asynkront lista nycklar

Skapa en nyckel

create_rsa_key och create_ec_key skapa RSA- respektive elliptiska kurvnycklar i valvet. Om det redan finns en nyckel med samma namn skapas en ny version av nyckeln.

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)

Hämta en nyckel

get_key hämtar en nyckel som tidigare lagrats i valvet.

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)

Uppdatera en befintlig nyckel

update_key_properties uppdaterar egenskaperna för en nyckel som tidigare lagrats i 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)

Ta bort en nyckel

begin_delete_key begär Key Vault ta bort en nyckel och returnerar en poller som gör att du kan vänta tills borttagningen har slutförts. Att vänta är användbart när mjuk borttagning är aktiverat för valvet och du vill rensa nyckeln (ta bort den permanent) så snart som möjligt. När mjuk borttagning är inaktiverat begin_delete_key är sig själv permanent.

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)

Konfigurera automatisk nyckelrotation

update_key_rotation_policy kan du konfigurera automatisk nyckelrotation för en nyckel genom att ange en rotationsprincip. Med rotate_key kan du dessutom rotera en nyckel på begäran genom att skapa en ny version av den angivna nyckeln.

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

Listnycklar

list_properties_of_keys visar egenskaperna för alla nycklar i klientens valv.

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)

Kryptografiska åtgärder

CryptographyClient möjliggör kryptografiska åtgärder (kryptera/dekryptera, omsluta/packa upp, signera/verifiera) med hjälp av en viss nyckel.

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)

Mer information om kryptografi-API:et finns i paketdokumentationen .

Asynkront API

Det här biblioteket innehåller en fullständig uppsättning asynkrona API:er. Om du vill använda dem måste du först installera en asynkron transport, till exempel aiohttp. Mer information finns i azure-core-dokumentationen .

Asynkrona klienter och autentiseringsuppgifter bör stängas när de inte längre behövs. Dessa objekt är asynkrona kontexthanterare och definierar asynkrona close metoder. Exempel:

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

Skapa en nyckel asynkront

create_rsa_key och create_ec_key skapa RSA- respektive elliptiska kurvnycklar i valvet. Om det redan finns en nyckel med samma namn skapas en ny version av nyckeln.

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)

Asynkront lista nycklar

list_properties_of_keys visar egenskaperna för alla nycklar i klientens valv.

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)

Felsökning

Mer information om hur du diagnostiserar olika felscenarier finns i azure-keyvault-keysfelsökningsguiden .

Allmänt

Key Vault klienter skapar undantag som definierats i azure-core. Om du till exempel försöker hämta en nyckel som inte finns i valvet genererar KeyClientResourceNotFoundError:

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)

Loggning

Det här biblioteket använder standardloggningsbiblioteket för loggning. Grundläggande information om HTTP-sessioner (URL:er, rubriker osv.) loggas på INFO-nivå.

Detaljerad loggning på FELSÖKNINGsnivå, inklusive begärande-/svarskroppar och oredigerade huvuden, kan aktiveras på en klient med logging_enable argumentet :

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)

logging_enable På samma sätt kan aktivera detaljerad loggning för en enda åtgärd, även om den inte är aktiverad för klienten:

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

Nästa steg

Det finns flera exempel i Azure SDK för Python GitHub-lagringsplatsen. Dessa ger exempelkod för ytterligare Key Vault scenarier: | Fil | Beskrivning | |-------------|-------------| | | hello_world.py (asynkron version) | skapa/hämta/uppdatera/ta bort nycklar | | list_operations.py (asynkron version) | grundläggande liståtgärder för nycklar | | backup_restore_operations.py (asynkron version) | Säkerhetskopiera och återställa nycklar | | recover_purge_operations.py (asynkron version) | återställa och rensa nycklar | | send_request.py | send_request använd klientmetoden |

Ytterligare dokumentation

Mer omfattande dokumentation om Azure Key Vault finns i API-referensdokumentationen.

Bidra

Det här projektet välkomnar bidrag och förslag. Merparten av bidragen kräver att du godkänner ett licensavtal för bidrag, där du deklarerar att du har behörighet att bevilja oss rättigheten att använda ditt bidrag, och att du dessutom uttryckligen gör så. Mer information finns på https://cla.microsoft.com.

När du skickar en pull-förfrågan avgör en CLA-robot automatiskt om du måste tillhandahålla ett licensavtal för bidrag med lämplig PR (t.ex. etikett eller kommentar). Följ bara robotens anvisningar. Du behöver bara göra detta en gång för alla repor som använder vårt licensavtal för bidrag.

Det här projektet använder sig av Microsofts uppförandekod för öppen källkod. Du hittar mer information i Vanliga frågor om uppförandekod eller kontakta opencode@microsoft.com för ytterligare frågor eller kommentarer.