Быстрое начало: библиотека клиента управляемого HSM Azure Key Vault для Python

Начало работы с клиентской библиотекой управляемого модуля HSM Azure Key Vault для Python. Управляемый модуль HSM — это полностью управляемая, высокодоступная, однотенантная и совместимая со стандартами облачная служба, которая позволяет защитить криптографические ключи для облачных приложений с помощью FIPS 140-3 уровня 3 , проверенных HSM. Дополнительные сведения об управляемом HSM см. в обзоре.

Из этого краткого руководства вы узнаете, как получить доступ к ключам в управляемом HSM и выполнять криптографические операции с помощью клиентской библиотеки Python.

Ресурсы клиентской библиотеки управляемых HSM:

справочная документация API | Библиотека исходный код | Package (PyPI)

Необходимые условия

Настройка локальной среды

В этом кратком руководстве используется библиотека Azure Identity и Azure CLI для проверки подлинности в службах Azure. Разработчики также могут использовать Visual Studio Code для проверки подлинности своих вызовов. Дополнительные сведения см. в разделе Аутентификация клиента с помощью клиентской библиотеки Azure Identity.

Вход в Azure

az login Выполните команду для входа:

az login

Создание папки проекта и виртуальной среды

  1. Создайте папку проекта и перейдите к ней:

    mkdir mhsm-python-app && cd mhsm-python-app

  2. Создайте и активируйте виртуальную среду:

    python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Установка пакетов

Установите клиентские библиотеки ключей Azure Identity и Key Vault Key:

pip install azure-identity azure-keyvault-keys

Создание примера кода

Создайте файл с именем mhsm_keys.py со следующим кодом. Замените <hsm-name> управляемым именем HSM и <key-name> существующим именем ключа.

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient
from azure.keyvault.keys.crypto import CryptographyClient, EncryptionAlgorithm

# Use DefaultAzureCredential for automatic credential selection
credential = DefaultAzureCredential()

# Connect to Managed HSM - replace with your HSM URI
hsm_uri = "https://<hsm-name>.managedhsm.azure.net"
key_client = KeyClient(vault_url=hsm_uri, credential=credential)

# Get a key reference
key_name = "<key-name>"
print(f"Retrieving key '{key_name}' from Managed HSM...")
key = key_client.get_key(key_name)
print(f"Key retrieved. Key type: {key.key_type}")

# Perform cryptographic operations
crypto_client = CryptographyClient(key, credential)

# Encrypt data
plaintext = b"Hello, Managed HSM!"
print(f"\nOriginal text: {plaintext.decode()}")

encrypt_result = crypto_client.encrypt(EncryptionAlgorithm.rsa_oaep_256, plaintext)
print(f"Encrypted (hex): {encrypt_result.ciphertext.hex()[:64]}...")

# Decrypt data
decrypt_result = crypto_client.decrypt(EncryptionAlgorithm.rsa_oaep_256, encrypt_result.ciphertext)
print(f"Decrypted text: {decrypt_result.plaintext.decode()}")

print("\nDone!")

Запуск приложения

Запустите приложение:

python mhsm_keys.py

Выходные данные должны выглядеть примерно так:

Retrieving key 'myrsakey' from Managed HSM...
Key retrieved. Key type: RSA-HSM

Original text: Hello, Managed HSM!
Encrypted (hex): 5a8f3b2c1d4e5f6a7b8c9d0e1f2a3b4c...
Decrypted text: Hello, Managed HSM!

Done!

Общие сведения о коде

Проверка подлинности с помощью DefaultAzureCredential

DefaultAzureCredential автоматически выбирает соответствующие учетные данные в зависимости от среды:

Окружающая среда Использованные учетные данные
Azure Виртуальные Машины, Служба Приложений, Функции Назначаемое системой или назначаемое пользователем управляемое удостоверение
Служба Azure Kubernetes Идентификация рабочей нагрузки
Локальная разработка учетные данные Azure CLI, Visual Studio или VS Code
Конвейеры CI/CD Федерация удостоверений идентификаций рабочей нагрузки или служебный принципал

Данные аутентификации проверяются в следующих источниках в порядке:

  1. Переменные среды
  2. Идентификация рабочей нагрузки
  3. Манажируемая идентичность
  4. Azure CLI
  5. Azure PowerShell
  6. Учетные данные Visual Studio/VS Code

Для рабочих нагрузок в Azure настоятельно рекомендуется использовать управляемые удостоверения, так как они полностью устраняют управление учетными данными.

Ключевые операции

Класс KeyClient предоставляет методы для:

  • Создание, получение, обновление и удаление ключей
  • Список ключей и их версий
  • Резервное копирование и восстановление ключей

Класс CryptographyClient предоставляет криптографические операции:

  • Шифрование и расшифровка данных
  • Подписи и проверка подписей
  • Упаковка и распаковка ключей

Назначение ролей в управляемых системах HSM

Для того чтобы ваше приложение имело доступ к ключам, назначьте управляемой идентичности соответствующую локальную роль RBAC для управляемого HSM. Замените <vm-name>, <resource-group>а <hsm-name> также фактическими значениями.

# Get the principal ID of your managed identity
principalId=$(az vm identity show --name <vm-name> --resource-group <resource-group> --query principalId -o tsv)

# Assign the Crypto User role for key operations
az keyvault role assignment create \
    --hsm-name <hsm-name> \
    --role "Managed HSM Crypto User" \
    --assignee $principalId \
    --scope /keys

Для получения дополнительной информации о ролях и разрешениях см. раздел Встроенные роли локального RBAC для управляемого HSM.

Очистите ресурсы

При отсутствии необходимости удалите группу ресурсов и все связанные ресурсы:

az group delete --name <resource-group>

Предупреждение

При удалении группы ресурсов управляемый модуль HSM переходит в состояние мягкого удаления. Управляемый модуль HSM продолжает выставляться на счет до тех пор, пока он не будет удален. См. статью Обратимое удаление и защита от очистки для управляемых модулей HSM.

Дальнейшие действия

  • Last updated on