Python için Azure Key Vault Anahtarları istemci kitaplığı - sürüm 4.8.0
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
- Azure aboneliği
- Python 3.7 veya üzeri
- Mevcut bir Azure Key Vault. Bir tane oluşturmanız gerekiyorsa, bu belgedeki adımları izleyerek Azure CLI'yı kullanarak bunu yapabilirsiniz.
- Yönetilen HSM kullanılıyorsa, mevcut bir yönetilen HSM Key Vault. Yönetilen HSM oluşturmanız gerekiyorsa, bu belgedeki adımları izleyerek Azure CLI'yı kullanarak bunu yapabilirsiniz.
İ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
KeyClientiç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
- Anahtar alma
- Mevcut anahtarı güncelleştirme
- Bir anahtarı silme
- Otomatik anahtar döndürmeyi yapılandırma
- Liste anahtarları
- Şifreleme işlemleri gerçekleştirme
- Zaman Uyumsuz API
- Zaman uyumsuz olarak anahtar oluşturma
- Anahtarları zaman uyumsuz olarak listeleme
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.
Azure SDK for Python