Biblioteka klienta kluczy usługi Azure Key Vault Dla języka Python — wersja 4.8.0

Usługa Azure Key Vault pomaga rozwiązać następujące problemy:

• Zarządzanie kluczami kryptograficznymi (ta biblioteka) — tworzenie, przechowywanie i kontrolowanie dostępu do kluczy używanych do szyfrowania danych
• Zarządzanie wpisami tajnymi (azure-keyvault-secrets) — bezpieczne przechowywanie i kontrolowanie dostępu do tokenów, haseł, certyfikatów, kluczy interfejsu API i innych wpisów tajnych
• Zarządzanie certyfikatami (azure-keyvault-certificates) — tworzenie i wdrażanie publicznych i prywatnych certyfikatów SSL/TLS oraz zarządzanie nimi
• Administracja magazynem (azure-keyvault-administration) — kontrola dostępu oparta na rolach (RBAC) i opcje tworzenia kopii zapasowych i przywracania na poziomie magazynu

Kod | źródłowy Pakiet (PyPI) | Pakiet (Conda) | Dokumentacja referencyjna interfejsu | API Dokumentacja | produktu Próbki

Zrzeczenie odpowiedzialności

Obsługa pakietów języka Python zestawu Azure SDK dla języka Python 2.7 została zakończona 01 stycznia 2022 r. Aby uzyskać więcej informacji i pytań, zobacz https://github.com/Azure/azure-sdk-for-python/issues/20691.

Do korzystania z tego pakietu wymagany jest język Python w wersji 3.7 lub nowszej. Aby uzyskać więcej informacji, zapoznaj się z zasadami obsługi wersji zestawu Azure SDK dla języka Python.

Wprowadzenie

Instalowanie pakietu

Zainstaluj usługę azure-keyvault-keys i azure-identity przy użyciu narzędzia pip:

pip install azure-keyvault-keys azure-identity

usługa azure-identity jest używana do uwierzytelniania usługi Azure Active Directory, jak pokazano poniżej.

Wymagania wstępne

• Subskrypcja platformy Azure
• Język Python w wersji 3.7 lub nowszej
• Istniejąca usługa Azure Key Vault. Jeśli musisz go utworzyć, możesz to zrobić za pomocą interfejsu wiersza polecenia platformy Azure, wykonując kroki opisane w tym dokumencie.
• W przypadku korzystania z zarządzanego modułu HSM istniejący Key Vault zarządzany moduł HSM. Jeśli musisz utworzyć zarządzany moduł HSM, możesz to zrobić przy użyciu interfejsu wiersza polecenia platformy Azure, wykonując kroki opisane w tym dokumencie.

Uwierzytelnianie klienta

Aby móc korzystać z usługi Azure Key Vault, potrzebne będzie wystąpienie obiektu KeyClient, a także adres URL magazynu i obiekt poświadczeń. W tym dokumencie pokazano, jak używać wartości DefaultAzureCredential, która jest odpowiednia dla większości scenariuszy, w tym lokalnych środowisk programistycznych i produkcyjnych. Zalecamy używanie tożsamości zarządzanej do uwierzytelniania w środowiskach produkcyjnych.

Aby uzyskać więcej informacji na temat innych metod uwierzytelniania i odpowiednich typów poświadczeń, zobacz dokumentację tożsamości platformy Azure .

Tworzenie klienta

Po skonfigurowaniu środowiska domyślnegoAzureCredential do użycia odpowiedniej metody uwierzytelniania można wykonać następujące czynności, aby utworzyć klienta klucza (zastępując wartość VAULT_URL adresem URL magazynu):

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

UWAGA: W przypadku klienta asynchronicznego zaimportuj azure.keyvault.keys.aiozamiast tego .s KeyClient .

Kluczowe pojęcia

Klucze

Usługa Azure Key Vault może tworzyć i przechowywać klucze krzywej RSA i wielokroptycznej. Oba te moduły mogą być opcjonalnie chronione przez sprzętowe moduły zabezpieczeń (HSM). Usługa Azure Key Vault może również wykonywać operacje kryptograficzne z nimi. Aby uzyskać więcej informacji na temat kluczy i obsługiwanych operacji i algorytmów, zobacz dokumentację Key Vault.

Obiekt KeyClient może tworzyć klucze w magazynie, pobierać istniejące klucze z magazynu, aktualizować metadane kluczy i usuwać klucze, jak pokazano w poniższych przykładach .

Przykłady

Ta sekcja zawiera fragmenty kodu obejmujące typowe zadania:

• Utwórz klucz
• Pobieranie klucza
• Aktualizowanie istniejącego klucza
• Usuń klucz
• Konfigurowanie automatycznej rotacji kluczy
• Wyświetlanie listy kluczy
• Wykonywanie operacji kryptograficznych
• Interfejs API asynchroniczny
• Asynchronicznie utwórz klucz
• Klucze listy asynchronicznej

Utwórz klucz

create_rsa_key i create_ec_key utworzyć odpowiednio klucze krzywej RSA i wielokroptycznej w magazynie. Jeśli klucz o tej samej nazwie już istnieje, zostanie utworzona nowa wersja tego klucza.

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)

Pobieranie klucza

get_key pobiera klucz wcześniej przechowywany w magazynie.

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)

Aktualizowanie istniejącego klucza

update_key_properties aktualizuje właściwości klucza wcześniej przechowywanego w 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)

Usuń klucz

begin_delete_key żądania Key Vault usunąć klucz, zwracając element poller, który umożliwia oczekiwanie na zakończenie usunięcia. Oczekiwanie jest przydatne, gdy magazyn ma włączone usuwanie nietrwałe i chcesz jak najszybciej przeczyścić (trwale usunąć) klucz. Gdy usuwanie nietrwałe jest wyłączone, begin_delete_key samo jest trwał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)
deleted_key = key_client.begin_delete_key("key-name").result()

print(deleted_key.name)
print(deleted_key.deleted_date)

Konfigurowanie automatycznej rotacji kluczy

update_key_rotation_policy umożliwia skonfigurowanie automatycznej rotacji kluczy dla klucza przez określenie zasad rotacji. Ponadto rotate_key umożliwia obracanie klucza na żądanie przez utworzenie nowej wersji danego klucza.

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

Wyświetlanie listy kluczy

list_properties_of_keys zawiera listę właściwości wszystkich kluczy w magazynie 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)

Operacje kryptograficzne

Program CryptographyClient umożliwia operacje kryptograficzne (szyfrowanie/odszyfrowywanie, zawijanie/odpakowywanie, podpisywanie/weryfikowanie) przy użyciu określonego klucza.

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)

Aby uzyskać więcej informacji na temat interfejsu API kryptografii, zobacz dokumentację pakietu .

Interfejs API asynchroniczny

Ta biblioteka zawiera kompletny zestaw asynchronicznych interfejsów API. Aby ich używać, należy najpierw zainstalować transport asynchroniczny, taki jak aiohttp. Aby uzyskać więcej informacji, zobacz dokumentację platformy azure-core .

Klienci asynchroniczny i poświadczenia powinny być zamknięte, gdy nie są już potrzebne. Te obiekty są asynchronicznych menedżerów kontekstów i definiują metody asynchroniczne close . Przykład:

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

Asynchronicznie utwórz klucz

create_rsa_key i create_ec_key utworzyć odpowiednio klucze krzywej RSA i wielokroptycznej w magazynie. Jeśli klucz o tej samej nazwie już istnieje, zostanie utworzona nowa wersja klucza.

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)

Klucze listy asynchronicznej

list_properties_of_keys zawiera listę właściwości wszystkich kluczy w magazynie 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)

Rozwiązywanie problemów

azure-keyvault-keys Aby uzyskać szczegółowe informacje na temat diagnozowania różnych scenariuszy awarii, zobacz przewodnik rozwiązywania problemów.

Ogólne

Key Vault klienci zgłaszają wyjątki zdefiniowane w usłudze azure-core. Jeśli na przykład spróbujesz uzyskać klucz, który nie istnieje w magazynie, program KeyClient zgłasza błąd 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)

Rejestrowanie

Ta biblioteka używa standardowej biblioteki rejestrowania do rejestrowania. Podstawowe informacje o sesjach HTTP (adresach URL, nagłówkach itp.) są rejestrowane na poziomie INFORMACJI.

Szczegółowe rejestrowanie na poziomie DEBUG, w tym treści żądań/odpowiedzi i nieredagowanych nagłówków, można włączyć na kliencie z 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)

Podobnie może logging_enable włączyć szczegółowe rejestrowanie dla pojedynczej operacji, nawet jeśli nie jest włączone dla klienta:

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

Następne kroki

Kilka przykładów jest dostępnych w repozytorium GitHub zestawu Azure SDK dla języka Python. Zawierają one przykładowy kod dla dodatkowych scenariuszy Key Vault: | Plik | Opis | |-------------|-------------| | hello_world.py (wersja asynchroniowa) | tworzenie/pobieranie/aktualizowanie/usuwanie kluczy | | list_operations.py (wersja asynchroniowa) | podstawowe operacje listy kluczy | | backup_restore_operations.py (wersja asynchroniowa) | tworzenie kopii zapasowej i odzyskiwanie kluczy | | recover_purge_operations.py (wersja asynchroniowa) | odzyskiwanie i przeczyszczanie kluczy | | send_request.py | send_request używanie metody klienta |

Dodatkowa dokumentacja

Aby uzyskać bardziej obszerną dokumentację dotyczącą usługi Azure Key Vault, zobacz dokumentację referencyjną interfejsu API.

Współtworzenie

W tym projekcie zachęcamy do współtworzenia i zgłaszania sugestii. Współtworzenie w większości przypadków wymaga zgody na umowę licencyjną dotyczącą współautorów (CLA, Contributor License Agreement), zgodnie z którą współautor ma prawo udzielić i faktycznie udziela nam praw do używania wytworzonej przez siebie zawartości. Aby uzyskać szczegółowe informacje, odwiedź stronę https://cla.microsoft.com.

Po przesłaniu żądania ściągnięcia robot CLA automatycznie określi, czy musisz przekazać umowę CLA, i doda odpowiednie informacje do tego żądania (na przykład etykietę czy komentarz). Po prostu postępuj zgodnie z instrukcjami robota. Wystarczy zrobić to raz dla wszystkich repozytoriów, w przypadku których jest używana nasza umowa CLA.

W tym projekcie przyjęto Kodeks postępowania oprogramowania Open Source firmy Microsoft. Aby uzyskać więcej informacji, zobacz artykuł Code of Conduct FAQ (Często zadawane pytania dotyczące kodeksu postępowania). Jeśli będziesz mieć jeszcze jakieś pytania lub komentarze, wyślij wiadomość e-mail na adres opencode@microsoft.com.