Клиентская библиотека Ключей Key Vault Azure для Python версии 4.8.0
Azure Key Vault помогает в решении следующих проблем:
- Управление криптографическими ключами (эта библиотека) — создание, хранение и управление доступом к ключам, используемым для шифрования данных.
- Управление секретами (azure-keyvault-secrets) — безопасное хранение и контроль доступа к маркерам, паролям, сертификатам, ключам API и другим секретам.
- Управление сертификатами (azure-keyvault-certificates) — создание, администрирование и развертывание общедоступных и частных сертификатов SSL/TLS
- Администрирование хранилища (azure-keyvault-administration) — управление доступом на основе ролей (RBAC), а также параметры резервного копирования и восстановления на уровне хранилища.
Исходный код | Пакет (PyPI) | Пакет (Conda) | Справочная документация по | API Документация по продукту | Образцы
Заявление об отказе
Поддержка пакетов Python пакета Azure SDK для Python 2.7 завершилась 1 января 2022 г. Дополнительные сведения и вопросы см. в https://github.com/Azure/azure-sdk-for-python/issues/20691разделе .
Для использования этого пакета требуется Python 3.7 или более поздней версии. Дополнительные сведения см. в статье Политика поддержки версий Пакета AZURE SDK для Python.
Начало работы
Установка пакета
Установите azure-keyvault-keys и azure-identity с помощью pip:
pip install azure-keyvault-keys azure-identity
Azure-identity используется для проверки подлинности Azure Active Directory, как показано ниже.
Предварительные требования
- Подписка Azure
- Python версии 3.7 или выше
- Существующий Key Vault Azure. Если вам нужно создать ее, это можно сделать с помощью Azure CLI, выполнив действия, описанные в этом документе.
- Если используется управляемый модуль HSM, существующий Key Vault управляемый модуль HSM. Если вам нужно создать управляемый модуль HSM, это можно сделать с помощью Azure CLI, выполнив действия, описанные в этом документе.
Аутентификация клиента
Для взаимодействия со службой azure Key Vault потребуется экземпляр KeyClient, а также URL-адрес хранилища и объект учетных данных. В этом документе демонстрируется использование DefaultAzureCredential, который подходит для большинства сценариев, включая локальные среды разработки и рабочие среды. Мы рекомендуем использовать управляемое удостоверение для проверки подлинности в рабочих средах.
Дополнительные сведения о других методах проверки подлинности и соответствующих типах учетных данных см. в документации по azure-identity .
Создание клиента
После настройки среды для DefaultAzureCredential для использования подходящего метода проверки подлинности можно создать клиент ключа (заменив значение VAULT_URL URL-адресом хранилища):
VAULT_URL = os.environ["VAULT_URL"]
credential = DefaultAzureCredential()
client = KeyClient(vault_url=VAULT_URL, credential=credential)
ПРИМЕЧАНИЕ: Вместо этого импортируйте
azure.keyvault.keys.aioKeyClientдля асинхронного клиента.
Основные понятия
Ключи
Azure Key Vault могут создавать и хранить ключи RSA и эллиптических кривых. При необходимости их можно защитить с помощью аппаратных модулей безопасности (HSM). Azure Key Vault также могут выполнять криптографические операции с ними. Дополнительные сведения о ключах и поддерживаемых операциях и алгоритмах см. в документации по Key Vault.
KeyClient может создавать ключи в хранилище, получать существующие ключи из хранилища, обновлять метаданные ключей и удалять ключи, как показано в примерах ниже.
Примеры
В этом разделе содержатся фрагменты кода, охватывающие распространенные задачи:
- Создание ключа
- Получение ключа
- Обновление существующего ключа
- Удаление ключа
- Настройка автоматической смены ключей
- получение списка ключей;
- Выполнение криптографических операций
- Асинхронный API
- Асинхронное создание ключа
- Асинхронный список ключей
Создание ключа
create_rsa_key и create_ec_key создать ключи RSA и эллиптических кривых в хранилище соответственно. Если ключ с таким же именем уже существует, создается новая версия этого ключа.
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)
Получение ключа
get_key извлекает ключ, ранее сохраненный в хранилище.
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)
Обновление существующего ключа
update_key_properties обновляет свойства ключа, ранее хранящегося в 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)
Удаление ключа
begin_delete_key запросы Key Vault удаления ключа, возвращая средство опроса, которое позволяет дождаться завершения удаления. Ожидание полезно, если в хранилище включено обратимое удаление и вы хотите как можно скорее очистить (окончательно удалить) ключ. Если обратимое удаление отключено, begin_delete_key само по себе является постоянным.
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)
Настройка автоматической смены ключей
update_key_rotation_policy позволяет настроить автоматическую смену ключей, указав политику смены. Кроме того, rotate_key позволяет менять ключ по запросу, создавая новую версию данного ключа.
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")
получение списка ключей;
list_properties_of_keys перечислены свойства всех ключей в хранилище клиента.
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)
Криптографические операции
CryptographyClient позволяет выполнять криптографические операции (шифрование/расшифровка, упаковка/распаковка, подписывание/проверка) с помощью определенного ключа.
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)
Дополнительные сведения об API шифрования см. в документации по пакету .
Асинхронный API
Эта библиотека включает полный набор асинхронных API. Чтобы использовать их, необходимо сначала установить асинхронный транспорт, например aiohttp. Дополнительные сведения см. в документации по azure-core .
Асинхронные клиенты и учетные данные должны быть закрыты, если они больше не нужны. Эти объекты являются диспетчерами асинхронного контекста и определяют асинхронные close методы. Пример:
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:
...
Асинхронное создание ключа
create_rsa_key и create_ec_key создать ключи RSA и эллиптических кривых в хранилище соответственно. Если ключ с таким же именем уже существует, создается новая версия ключа.
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)
Асинхронный список ключей
list_properties_of_keys перечислены свойства всех ключей в хранилище клиента.
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)
Устранение неполадок
azure-keyvault-keys Дополнительные сведения о том, как диагностировать различные сценарии сбоев, см. в руководстве по устранению неполадок.
Общее
Key Vault клиенты вызывают исключения, определенные в azure-core. Например, при попытке получить ключ, который не существует в хранилище, KeyClient вызовет 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)
Ведение журнала
Эта библиотека использует стандартную библиотеку ведения журнала для ведения журнала. Основные сведения о сеансах HTTP (URL-адреса, заголовки и т. д.) регистрируются на уровне INFO.
Подробное ведение журнала на уровне DEBUG, включая тексты запросов и ответов и неотредактированные заголовки, можно включить на клиенте с помощью аргумента 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)
Аналогичным образом с помощью параметра logging_enable можно включить подробное журналирование для отдельной операции (даже если этот режим не включен в клиенте):
client.get_key("my-key", logging_enable=True)
Дальнейшие действия
Несколько примеров доступны в репозитории GitHub пакета Azure SDK для Python.
Ниже приведен пример кода для дополнительных сценариев Key Vault: | Файл | Описание | |-------------|-------------| | hello_world.py (асинхронная версия) | Создание, получение, обновление и удаление ключей | list_operations.py (асинхронная версия) | Основные операции со списком для ключей | | backup_restore_operations.py (асинхронная версия) | резервное копирование и восстановление ключей | | recover_purge_operations.py (асинхронная версия) | Восстановление и очистка ключей | | send_request.py | send_request использование метода клиента |
Дополнительная документация
Более подробную документацию по azure Key Vault см. в справочной документации по API.
Участие
На этом проекте приветствуются публикации и предложения. Для участия в большинстве процессов по разработке документации необходимо принять лицензионное соглашение участника (CLA), в котором указывается, что вы предоставляете нам права на использование ваших публикаций. Для получения подробных сведений посетите веб-страницу https://cla.microsoft.com.
При отправке запроса на включение внесенных изменений CLA-бот автоматически определит необходимость предоставления соглашения CLA и соответствующего оформления запроса на включение внесенных изменений (например, добавление метки, комментария). Просто следуйте инструкциям бота. Будет достаточно выполнить их один раз для всех репозиториев, поддерживающих соглашение CLA.
В рамках этого проекта действуют правила поведения в отношении продуктов с открытым исходным кодом Майкрософт. Дополнительные сведения: Вопросы и ответы по правилам поведения. С любыми другими вопросами или комментариями обращайтесь по адресу opencode@microsoft.com.
Azure SDK for Python
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по