Краткое руководство: клиентская библиотека Azure Key Vault для управляемого HSM в JavaScript

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

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

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

справочная документация API | Library source code | Package (npm)

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

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

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

Вход в Azure

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

az login

Создание папки проекта и инициализация

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

    mkdir mhsm-js-app && cd mhsm-js-app

  2. Инициализация проекта:

    npm init -y

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

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

npm install @azure/identity @azure/keyvault-keys

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

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

const { DefaultAzureCredential } = require("@azure/identity");
const { KeyClient, CryptographyClient } = require("@azure/keyvault-keys");

async function main() {
    // Use DefaultAzureCredential for automatic credential selection
    const credential = new DefaultAzureCredential();

    // Connect to Managed HSM - replace with your HSM URI
    const hsmUri = "https://<hsm-name>.managedhsm.azure.net";
    const keyClient = new KeyClient(hsmUri, credential);

    // Get a key reference
    const keyName = "<key-name>";
    console.log(`Retrieving key '${keyName}' from Managed HSM...`);
    const key = await keyClient.getKey(keyName);
    console.log(`Key retrieved. Key type: ${key.keyType}`);

    // Perform cryptographic operations
    const cryptoClient = new CryptographyClient(key, credential);

    // Encrypt data
    const plaintext = Buffer.from("Hello, Managed HSM!");
    console.log(`\nOriginal text: ${plaintext.toString()}`);

    const encryptResult = await cryptoClient.encrypt("RSA-OAEP-256", plaintext);
    console.log(`Encrypted (base64): ${encryptResult.result.toString("base64").substring(0, 64)}...`);

    // Decrypt data
    const decryptResult = await cryptoClient.decrypt("RSA-OAEP-256", encryptResult.result);
    console.log(`Decrypted text: ${decryptResult.result.toString()}`);

    console.log("\nDone!");
}

main().catch((error) => {
    console.error("An error occurred:", error);
    process.exit(1);
});

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

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

node index.js

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

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

Original text: Hello, Managed HSM!
Encrypted (base64): NWE4ZjNiMmMxZDRlNWY2YTdiOGM5ZDBlMWYyYTNiNGM...
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