Принесите вашу собственную спецификацию ключа

2025-06-17

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

Сценарий

Клиент Key Vault хотел бы безопасно передать ключ из локального устройства HSM за пределами Azure в HSM с поддержкой Azure Key Vault. Процесс импорта ключа, созданного за пределами Key Vault, называется "Принести собственный ключ" (BYOK).

Требования к этом процессу приведены ниже.

Ключ, подлежащий переносу, не должен ни в какой момент появляться вне HSM в виде обычного текста.
Вне HSM ключ, подлежащий переносу, всегда защищен ключом, хранимым в HSM Azure Key Vault.

Терминология

Имя ключа	Тип ключа	Происхождение	Описание
Ключ обмена ключами (KEK)	RSA	HSM Azure Key Vault	Защищенная модулем HSM пара ключей RSA, созданная в Azure Key Vault
Упаковочный ключ	AES (Стандарт шифрования данных)	HSM от поставщика	Временный ключ AES, созданный локальным устройством HSM
Целевой ключ	RSA, EC, AES (только управляемый HSM)	HSM от поставщика	Ключ для передачи в модуль HSM Azure Key Vault

Ключ обмена ключами: ключ с поддержкой HSM, который клиент создает в хранилище ключей, где импортируется ключ BYOK. KEK должен иметь следующие свойства:

Это ключ RSA-HSM (4096-разрядная или 3072-разрядная или 2048-разрядная версия)
Он имеет фиксированный параметр key_ops (Только import), который позволяет использовать его только во время Bring Your Own Key (BYOK).
Должен находиться в том же хранилище, где импортируется целевой ключ

Порядок действий пользователя

Чтобы перенести ключ, пользователь выполняет следующие действия.

Создает KEK.
Получает открытый ключ KEK.
С помощью средства BYOK, предоставленного поставщиком HSM, импортирует KEK в целевой HSM и экспортирует целевой ключ, защищенный KEK.
Импортирует защищенный целевой ключ в Azure Key Vault.

Для выполнения шага 3 клиенты используют средство BYOK и документацию, предоставляемые поставщиком HSM. Результатом работы этого средства является BLOB-объект передачи ключа (файл с расширением BYOK).

Ограничения на HSM

Существующий HSM может применять ограничения к управляемому им ключу, в том числе следующие:

возможно, потребуется настроить HSM, чтобы разрешить экспорт с упаковкой ключа;
Для того, чтобы HSM разрешал контролируемый экспорт, целевой ключ может потребоваться пометить как CKA_EXTRACTABLE.
В некоторых случаях ключ KEK и ключ-оболочка могут быть помечены как CKA_TRUSTED, что позволяет использовать его для упаковки ключей в HSM.

Настройка исходного HSM, вообще говоря, выходит за рамки данной спецификации. Корпорация Майкрософт предполагает, что поставщик HSM приложит к своему средство BYOK сопроводительную документацию с описанием порядка настройки HSM (если настройка требуется).

Замечание

Некоторые из этих действий можно выполнить с помощью других интерфейсов, таких как Azure PowerShell и портал Azure. Их также можно выполнить программно с помощью эквивалентных функций в Key Vault SDK.

Создание KEK

Используйте команду az keyvault key create, чтобы создать KEK с операциями ключа, установленными для импорта. Запишите идентификатор ключа "kid", возвращенный из этой команды.

az keyvault key create --kty RSA-HSM --size 4096 --name KEKforBYOK --ops import --vault-name ContosoKeyVaultHSM

Замечание

Службы поддерживают разные длины KEK; Например, SQL Azure поддерживает только длину ключей в 2048 или 3072 байтах. Ознакомьтесь с документацией вашего сервиса для получения подробной информации.

Получение открытого ключа KEK

Скачайте открытый ключ KEK и сохраните его в PEM-файле.

az keyvault key download --name KEKforBYOK --vault-name ContosoKeyVaultHSM --file KEKforBYOK.publickey.pem

Создание BLOB-объекта передачи ключей с помощью поставщика HSM, предоставленного средством BYOK

Клиент использует поставщик HSM, предоставленный средством BYOK для создания BLOB-объекта передачи ключей (хранящегося в виде файла byok). Открытый ключ KEK (как PEM-файл) является одним из входных данных этого средства.

BLOB-объект передачи ключа

В долгосрочной перспективе корпорация Майкрософт хотела бы использовать механизм PKCS#11 CKM_RSA_AES_KEY_WRAP для передачи целевого ключа в Azure Key Vault, так как этот механизм создает один большой двоичный объект и, что еще более важно, промежуточный ключ AES обрабатывается двумя HSM и гарантированно будет эфемерным. Этот механизм в настоящее время недоступен в некоторых HSM'ах, но сочетание защиты целевого ключа с использованием CKM_AES_KEY_WRAP_PAD и ключа AES и защиты этого ключа с использованием CKM_RSA_PKCS_OAEP создает аналогичный большой двоичный объект.

Открытый текст целевого ключа зависит от его типа:

Для ключа RSA закрытый ключ ASN.1 DER, закодированный в виде [RFC3447], упакован в PKCS#8 [RFC5208]
Для ключа EC кодировка ASN.1 DER закрытого ключа [RFC5915] упакована в PKCS#8 [RFC5208]
Для октетного ключа необработанные байты ключа

Байты исходного ключа преобразуются по механизму CKM_RSA_AES_KEY_WRAP:

Эфемерный ключ AES создается и шифруется обернутым ключом RSA с использованием RSA-OAEP и SHA1.
закодированный исходный ключ шифруется с помощью ключа AES с упаковкой в ключ AES и заполнением;
зашифрованный ключ AES и зашифрованный исходный ключ сцепляются, и из них формируется конечный BLOB-объект с зашифрованными данными.

Формат большого двоичного объекта передачи использует компактную сериализацию веб-шифрования JSON (RFC7516) в качестве транспортного средства для доставки необходимых метаданных службе для правильной расшифровки.

Если используется CKM_RSA_AES_KEY_WRAP_PAD, сериализация JSON передаваемого блоба будет:

{
  "schema_version": "1.0.0",
  "header":
  {
    "kid": "<key identifier of the KEK>",
    "alg": "dir",
    "enc": "CKM_RSA_AES_KEY_WRAP"
  },
  "ciphertext":"BASE64URL(<ciphertext contents>)",
  "generator": "BYOK tool name and version; source HSM name and firmware version"
}

kid = ключевой идентификатор KEK. Для ключей Key Vault это выглядит следующим образом: https://ContosoKeyVaultHSM.vault.azure.net/keys/mykek/eba63d27e4e34e028839b53fac905621
alg = алгоритм.
dir = прямой режим, то есть ссылка на kid используется для непосредственной защиты шифротекста, который является точным представлением для CKM_RSA_AES_KEY_WRAP
генератор = информационное поле, которое обозначает имя и версию средства BYOK и исходного производителя И модели HSM. Эта информация предназначена для устранения неполадок и поддержки.

JSON объект хранится в файле с расширением ".byok", чтобы клиент Azure PowerShell или CLI правильно обрабатывал его при использовании команд "Add-AzKeyVaultKey" (PSH) или "az keyvault key import" (CLI).

Отправка BLOB-объекта передачи ключа для импорта HSM-key

Пользователи переносят файл blob передачи ключа (".byok") на сетевую рабочую станцию, а затем выполняют команду az keyvault key import для импорта этого blob-файла в Key Vault в качестве нового ключа с поддержкой HSM.

Чтобы импортировать ключ RSA, используйте следующую команду:

az keyvault key import --vault-name ContosoKeyVaultHSM --name ContosoFirstHSMkey --byok-file KeyTransferPackage-ContosoFirstHSMkey.byok --ops encrypt decrypt

Чтобы импортировать ключ EC, нужно указать тип ключа и имя кривой.

az keyvault key import --vault-name ContosoKeyVaultHSM --name ContosoFirstHSMkey --byok-file --kty EC-HSM --curve-name "P-256" KeyTransferPackage-ContosoFirstHSMkey.byok --ops sign verify

При выполнении этой команды он приводит к отправке запроса REST API следующим образом:

PUT https://contosokeyvaulthsm.vault.azure.net/keys/ContosoFirstHSMKey?api-version=7.0

Текст запроса при импорте ключа RSA:

{
  "key": {
    "kty": "RSA-HSM",
    "key_ops": [
      "decrypt",
      "encrypt"
    ],
    "key_hsm": "<Base64 encoded BYOK_BLOB>"
  },
  "attributes": {
    "enabled": true
  }
}

Текст запроса при импорте ключа EC:

{
  "key": {
    "kty": "EC-HSM",
    "crv": "P-256",
    "key_ops": [
      "sign",
      "verify"
    ],
    "key_hsm": "<Base64 encoded BYOK_BLOB>"
  },
  "attributes": {
    "enabled": true
  }
}

Значение "key_hsm" — это все содержимое keyTransferPackage-ContosoFirstHSMkey.byok, закодированное в формате Base64.

Ссылки

Руководство разработчика Key Vault

Дальнейшие шаги

Пошаговые инструкции по BYOK: импорт ключей, защищенных HSM, в Key Vault (BYOK)