Python için Azure Key Vault Anahtarları istemci kitaplığı - sürüm 4.8.0

  • Makale

Azure Key Vault aşağıdaki sorunların çözülmesine yardımcı olur:

  • Şifreleme anahtarı yönetimi (bu kitaplık) - verilerinizi şifrelemek için kullanılan anahtarlara erişimi oluşturma, depolama ve denetleme
  • Gizli dizi yönetimi (azure-keyvault-secrets) - belirteçlere, parolalara, sertifikalara, API anahtarlarına ve diğer gizli dizilere erişimi güvenli bir şekilde depolayın ve denetleyin
  • Sertifika yönetimi (azure-keyvault-certificates) - genel ve özel SSL/TLS sertifikaları oluşturma, yönetme ve dağıtma
  • Kasa yönetimi (azure-keyvault-administration) - rol tabanlı erişim denetimi (RBAC) ve kasa düzeyinde yedekleme ve geri yükleme seçenekleri

Kaynak kodu | Paket (PyPI) | Paket (Conda) | API başvuru belgeleri | Ürün belgeleri | Örnekleri

Bildirim

Python 2.7 için Azure SDK Python paketleri desteği 01 Ocak 2022'de sona erdi. Daha fazla bilgi ve soru için bkz https://github.com/Azure/azure-sdk-for-python/issues/20691. .

Bu paketi kullanmak için Python 3.7 veya üzeri gereklidir. Daha fazla ayrıntı için lütfen Python için Azure SDK sürüm desteği ilkesine bakın.

Başlarken

Paketi yükleme

pip ile azure-keyvault-keys ve azure-identity yükleyin:

pip install azure-keyvault-keys azure-identity

azure-identity , aşağıda gösterildiği gibi Azure Active Directory kimlik doğrulaması için kullanılır.

Önkoşullar

İstemcinin kimliğini doğrulama

Azure Key Vault hizmetiyle etkileşim kurmak için bir KeyClient örneğinin yanı sıra kasa url'si ve kimlik bilgisi nesnesi gerekir. Bu belgede, yerel geliştirme ve üretim ortamları dahil olmak üzere çoğu senaryo için uygun olan DefaultAzureCredential kullanımı gösterilmektedir. Üretim ortamlarında kimlik doğrulaması için yönetilen kimlik kullanmanızı öneririz.

Diğer kimlik doğrulama yöntemleri ve ilgili kimlik bilgileri türleri hakkında daha fazla bilgi için bkz. azure-identity belgeleri.

İstemci oluşturma

Ortamınızı DefaultAzureCredential için uygun bir kimlik doğrulama yöntemi kullanacak şekilde yapılandırdıktan sonra, bir anahtar istemcisi oluşturmak için aşağıdakileri yapabilirsiniz (değerini VAULT_URL kasanızın URL'si ile değiştirerek):

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

NOT: Zaman uyumsuz bir istemci için bunun yerine 'leri KeyClient içeri aktarabilirsinizazure.keyvault.keys.aio.

Önemli kavramlar

Anahtarlar

Azure Key Vault RSA ve üç nokta eğrisi anahtarları oluşturabilir ve depolayabilir. her ikisi de isteğe bağlı olarak donanım güvenlik modülleri (HSM' ler) tarafından korunabilir. Azure Key Vault bunlarla şifreleme işlemleri de gerçekleştirebilir. Anahtarlar, desteklenen işlemler ve algoritmalar hakkında daha fazla bilgi için Key Vault belgelerine bakın.

KeyClient , aşağıdaki örneklerde gösterildiği gibi kasada anahtar oluşturabilir, kasadan mevcut anahtarları alabilir, anahtar meta verilerini güncelleştirebilir ve anahtarları silebilir.

Örnekler

Bu bölüm, yaygın görevleri kapsayan kod parçacıkları içerir:

Bir anahtar oluşturma

create_rsa_key ve create_ec_key sırasıyla kasada RSA ve üç nokta eğrisi anahtarları oluşturur. Aynı ada sahip bir anahtar zaten varsa, bu anahtarın yeni bir sürümü oluşturulur.

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)

Anahtar alma

get_key daha önce Kasada depolanan bir anahtarı alır.

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)

Mevcut anahtarı güncelleştirme

update_key_properties, daha önce Key Vault depolanan bir anahtarın özelliklerini güncelleştirir.

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)

Bir anahtarı silme

begin_delete_key istekleri Key Vault bir anahtarı silip silme işleminin bitmesini beklemenizi sağlayan bir poller döndürür. Kasada geçici silme etkinleştirildiğinde ve anahtarı mümkün olan en kısa sürede temizlemek (kalıcı olarak silmek) istediğinizde beklemek yararlı olur. Geçici silme devre dışı bırakıldığında, begin_delete_key kendisi kalıcı olur.

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)

Otomatik anahtar döndürmeyi yapılandırma

update_key_rotation_policy , bir döndürme ilkesi belirterek bir anahtar için otomatik anahtar döndürmeyi yapılandırmanıza olanak tanır. Ayrıca , rotate_key verilen anahtarın yeni bir sürümünü oluşturarak bir anahtarı isteğe bağlı olarak döndürmenize olanak tanır.

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

Liste anahtarları

list_properties_of_keys , istemcinin kasasındaki tüm anahtarların özelliklerini listeler.

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)

Şifreleme işlemleri

CryptographyClient , belirli bir anahtarı kullanarak şifreleme işlemlerini (şifreleme/şifre çözme, sarmalama/kaldırma, imzalama/doğrulama) etkinleştirir.

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)

Şifreleme API'sinin diğer ayrıntıları için paket belgelerine bakın.

Zaman Uyumsuz API

Bu kitaplık tam bir zaman uyumsuz API kümesi içerir. Bunları kullanmak için önce aiohttp gibi bir zaman uyumsuz aktarım yüklemeniz gerekir. Daha fazla bilgi için bkz. azure-core belgeleri .

Zaman uyumsuz istemciler ve kimlik bilgileri artık gerekli olmadığında kapatılmalıdır. Bu nesneler zaman uyumsuz bağlam yöneticileridir ve zaman uyumsuz close yöntemler tanımlar. Örneğin:

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

Zaman uyumsuz olarak anahtar oluşturma

create_rsa_key ve create_ec_key sırasıyla kasada RSA ve üç nokta eğrisi anahtarları oluşturur. Aynı ada sahip bir anahtar zaten varsa, anahtarın yeni bir sürümü oluşturulur.

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)

Anahtarları zaman uyumsuz olarak listeleme

list_properties_of_keys , istemcinin kasasındaki tüm anahtarların özelliklerini listeler.

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)

Sorun giderme

azure-keyvault-keys Çeşitli hata senaryolarını tanılama hakkında ayrıntılı bilgi için sorun giderme kılavuzuna bakın.

Genel

Key Vault istemcileri azure-core'da tanımlanan özel durumları tetikler. Örneğin, kasada mevcut olmayan bir anahtar almaya çalışırsanız , KeyClientResourceNotFoundError'ı yükseltir:

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)

Günlüğe Kaydetme

Bu kitaplık, günlüğe kaydetme için standart günlük kitaplığını kullanır. HTTP oturumlarıyla ilgili temel bilgiler (URL'ler, üst bilgiler vb.) BİlGİ düzeyinde günlüğe kaydedilir.

İstek/yanıt gövdeleri ve kaydedilmemiş üst bilgiler de dahil olmak üzere ayrıntılı HATA AYıKLAMA düzeyi günlüğe kaydetme, bir istemcide şu bağımsız değişkenle logging_enable etkinleştirilebilir:

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)

Benzer şekilde, logging_enable istemci için etkinleştirilmemiş olsa bile tek bir işlem için ayrıntılı günlüğe kaydetmeyi etkinleştirebilir:

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

Sonraki adımlar

Python için Azure SDK GitHub deposunda çeşitli örnekler mevcuttur. Bunlar ek Key Vault senaryoları için örnek kod sağlar: | Dosya | Açıklama | |-------------|-------------| | hello_world.py (zaman uyumsuz sürüm) | anahtarları oluşturma/alma/güncelleştirme/silme | | list_operations.py (zaman uyumsuz sürüm) | anahtarlar için temel liste işlemleri | | backup_restore_operations.py (zaman uyumsuz sürüm) | anahtarları yedekleme ve kurtarma | | recover_purge_operations.py (zaman uyumsuz sürüm) | anahtarları kurtarma ve temizleme | | send_request.py | send_request| istemci yöntemini kullanma

Diğer belgeler

Azure Key Vault hakkında daha kapsamlı belgeler için API başvuru belgelerine bakın.

Katkıda bulunma

Bu proje, katkı ve önerilere açıktır. Çoğu durumda, sağladığınız katkıyı kullanmamız için bize hak tanıma hakkına sahip olduğunuzu ve bu hakkı bize tanıdığınızı bildiren bir Katkıda Bulunan Lisans Sözleşmesi’ni (CLA) kabul etmeniz gerekir. Ayrıntılar için bkz. https://cla.microsoft.com.

Bir çekme isteği gönderdiğinizde, CLA robotu bir CLA sağlamanız gerekip gerekmediğini otomatik olarak belirler ve çekme isteğini uygun şekilde donatır (örn. etiket, açıklama). Robot tarafından sağlanan yönergeleri izlemeniz yeterlidir. Bu işlemi, CLA’mızı kullanarak tüm depolarda yalnızca bir kere yapmanız gerekir.

Bu proje Microsoft Open Source Code of Conduct (Microsoft Açık Kaynak Kullanım Kuralları) belgesinde listelenen kurallara uygundur. Daha fazla bilgi için Kullanım Kuralları hakkında SSS bölümüne bakın veya başka soru ya da görüşleriniz olursa opencode@microsoft.com ile iletişime geçin.

İzlenimler