Pustaka klien Azure Key Vault Keys untuk Python - versi 4.8.0
Azure Key Vault membantu menyelesaikan masalah berikut:
- Manajemen kunci kriptografi (pustaka ini) - membuat, menyimpan, dan mengontrol akses ke kunci yang digunakan untuk mengenkripsi data Anda
- Manajemen rahasia (azure-keyvault-secrets) - menyimpan dan mengontrol akses ke token, kata sandi, sertifikat, kunci API, dan rahasia lainnya dengan aman
- Manajemen sertifikat (azure-keyvault-certificates) - membuat, mengelola, dan menyebarkan sertifikat SSL/TLS publik dan privat
- Administrasi vault (azure-keyvault-administration) - kontrol akses berbasis peran (RBAC), dan opsi pencadangan dan pemulihan tingkat vault
Kode sumber | Paket (PyPI) | Paket (Conda) | Dokumentasi | referensi API Dokumentasi | produk Sampel
Pengelakan
Dukungan paket Azure SDK Python untuk Python 2.7 telah berakhir 01 Januari 2022. Untuk informasi dan pertanyaan lebih lanjut, silakan merujuk ke https://github.com/Azure/azure-sdk-for-python/issues/20691.
Python 3.7 atau yang lebih baru diharuskan untuk menggunakan paket ini. Untuk detail selengkapnya, silakan lihat kebijakan dukungan versi Azure SDK for Python.
Memulai
Menginstal paket
Instal azure-keyvault-keys dan azure-identity dengan pip:
pip install azure-keyvault-keys azure-identity
azure-identity digunakan untuk autentikasi Azure Active Directory seperti yang ditunjukkan di bawah ini.
Prasyarat
- Langganan Azure
- Python 3.7 atau yang lebih baru
- Azure Key Vault yang sudah ada. Jika Anda perlu membuatnya, Anda bisa melakukannya menggunakan Azure CLI dengan mengikuti langkah-langkah dalam dokumen ini.
- Jika menggunakan HSM Terkelola, HSM Terkelola Key Vault yang ada. Jika Anda perlu membuat HSM Terkelola, Anda bisa melakukannya menggunakan Azure CLI dengan mengikuti langkah-langkah dalam dokumen ini.
Mengautentikasi klien
Untuk berinteraksi dengan layanan Azure Key Vault, Anda memerlukan instans KeyClient, serta url vault dan objek kredensial. Dokumen ini menunjukkan penggunaan DefaultAzureCredential, yang sesuai untuk sebagian besar skenario, termasuk lingkungan pengembangan dan produksi lokal. Sebaiknya gunakan identitas terkelola untuk autentikasi di lingkungan produksi.
Lihat dokumentasi azure-identity untuk informasi selengkapnya tentang metode autentikasi lain dan jenis kredensial yang sesuai.
Membuat klien
Setelah mengonfigurasi lingkungan Anda untuk DefaultAzureCredential untuk menggunakan metode autentikasi yang sesuai, Anda dapat melakukan hal berikut untuk membuat klien kunci (mengganti nilai VAULT_URL dengan URL vault Anda):
VAULT_URL = os.environ["VAULT_URL"]
credential = DefaultAzureCredential()
client = KeyClient(vault_url=VAULT_URL, credential=credential)
CATATAN: Untuk klien asinkron, impor
azure.keyvault.keys.aiosebagai gantinyaKeyClient.
Konsep utama
Kunci
Azure Key Vault dapat membuat dan menyimpan RSA dan kunci kurva elips. Keduanya secara opsional dapat dilindungi oleh modul keamanan perangkat keras (HSM). Azure Key Vault juga dapat melakukan operasi kriptografi dengannya. Untuk informasi selengkapnya tentang kunci dan operasi dan algoritma yang didukung, lihat dokumentasi Key Vault.
KeyClient dapat membuat kunci di brankas, mendapatkan kunci yang ada dari vault, memperbarui metadata kunci, dan menghapus kunci, seperti yang ditunjukkan pada contoh di bawah ini.
Contoh
Bagian ini berisi cuplikan kode yang mencakup tugas umum:
- Membuat kunci
- Mengambil kunci
- Memperbarui kunci yang ada
- Menghapus kunci
- Mengonfigurasi rotasi kunci otomatis
- Membuat daftar kunci
- Melakukan operasi kriptografi
- API Asinkron
- Membuat kunci secara asinkron
- Mencantumkan kunci secara asinkron
Membuat kunci
create_rsa_key dan create_ec_key masing-masing membuat kunci RSA dan kurva elips di brankas. Jika kunci dengan nama yang sama sudah ada, versi baru kunci tersebut dibuat.
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)
Mengambil kunci
get_key mengambil kunci yang sebelumnya disimpan di 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)
key = key_client.get_key("key-name")
print(key.name)
Memperbarui kunci yang ada
update_key_properties memperbarui properti kunci yang sebelumnya disimpan di 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)
Menghapus kunci
begin_delete_key permintaan Key Vault menghapus kunci, mengembalikan poller yang memungkinkan Anda menunggu penghapusan selesai. Menunggu sangat membantu ketika vault mengaktifkan penghapusan sementara , dan Anda ingin menghapus menyeluruh (menghapus secara permanen) kunci sesegera mungkin. Ketika penghapusan sementara dinonaktifkan, begin_delete_key itu sendiri bersifat permanen.
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)
Mengonfigurasi rotasi kunci otomatis
update_key_rotation_policy memungkinkan Anda mengonfigurasi rotasi kunci otomatis untuk kunci dengan menentukan kebijakan rotasi. Selain itu, rotate_key memungkinkan Anda memutar kunci sesuai permintaan dengan membuat versi baru dari kunci yang diberikan.
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")
Membuat daftar kunci
list_properties_of_keys mencantumkan properti semua kunci di vault klien.
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)
Operasi kriptografi
CryptographyClient memungkinkan operasi kriptografi (enkripsi/dekripsi, bungkus/bongkar, tanda tangani/verifikasi) menggunakan kunci tertentu.
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)
Lihat dokumentasi paket untuk detail selengkapnya tentang API kriptografi.
API Asinkron
Pustaka ini mencakup sekumpulan API asinkron lengkap. Untuk menggunakannya, Anda harus menginstal transportasi asinkron terlebih dahulu, seperti aiohttp. Lihat dokumentasi azure-core untuk informasi selengkapnya.
Klien dan kredensial asinkron harus ditutup ketika tidak lagi diperlukan. Objek ini adalah manajer konteks asinkron dan menentukan metode asinkron close . Contohnya:
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:
...
Membuat kunci secara asinkron
create_rsa_key dan create_ec_key masing-masing membuat kunci RSA dan kurva elips di brankas. Jika kunci dengan nama yang sama sudah ada, versi baru kunci akan dibuat.
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)
Mencantumkan kunci secara asinkron
list_properties_of_keys mencantumkan properti semua kunci di vault klien.
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)
Pemecahan Masalah
azure-keyvault-keys Lihat panduan pemecahan masalah untuk detail tentang cara mendiagnosis berbagai skenario kegagalan.
Umum
Key Vault klien meningkatkan pengecualian yang ditentukan dalam azure-core. Misalnya, jika Anda mencoba mendapatkan kunci yang tidak ada di vault, KeyClient akan menaikkan 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)
Pembuatan Log
Pustaka ini menggunakan pustaka pengelogan standar untuk pengelogan. Informasi dasar tentang sesi HTTP (URL, header, dll.) dicatat di tingkat INFO.
Pengelogan tingkat DEBUG terperinci, termasuk isi permintaan/respons dan header yang tidak diredaktifkan, dapat diaktifkan pada klien dengan logging_enable argumen :
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)
Demikian pula, logging_enable dapat mengaktifkan pengelogan mendetail untuk satu operasi, meskipun tidak diaktifkan untuk klien:
client.get_key("my-key", logging_enable=True)
Langkah berikutnya
Beberapa sampel tersedia di repositori GitHub Azure SDK for Python.
Ini memberikan contoh kode untuk skenario Key Vault tambahan: | File | Deskripsi | |-------------|-------------| | hello_world.py (versi asinkron) | membuat/mendapatkan/memperbarui/menghapus kunci | | list_operations.py (versi asinkron) | operasi daftar dasar untuk kunci | | backup_restore_operations.py (versi asinkron) | mencadangkan dan memulihkan kunci | | recover_purge_operations.py (versi asinkron) | memulihkan dan menghapus menyeluruh kunci | | send_request.py | send_request gunakan metode klien |
Dokumentasi tambahan
Untuk dokumentasi yang lebih luas tentang Azure Key Vault, lihat dokumentasi referensi API.
Berkontribusi
Proyek ini menyambut baik kontribusi dan saran. Sebagian besar kontribusi mengharuskan Anda menyetujui Perjanjian Lisensi Kontributor (CLA) yang menyatakan bahwa Anda memiliki hak untuk, dan benar-benar melakukannya, memberi kami hak untuk menggunakan kontribusi Anda. Untuk detailnya, kunjungi https://cla.microsoft.com.
Ketika Anda mengirimkan permintaan tarik, CLA-bot akan secara otomatis menentukan apakah Anda perlu memberikan CLA dan menghias PR dengan tepat (misalnya, label, komentar). Cukup ikuti instruksi yang diberikan oleh bot. Anda hanya perlu melakukan ini sekali di semua repos menggunakan CLA kami.
Proyek ini telah mengadopsi Kode Etik Sumber Terbuka Microsoft. Untuk informasi selengkapnya, lihat FAQ Kode Etik atau hubungi opencode@microsoft.com untuk mengajukan pertanyaan atau komentar tambahan.
Azure SDK for Python
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk