Клиентская библиотека Ключей Key Vault Azure для Python версии 4.8.0

Для использования этого пакета требуется 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.