Спецификация BYOK

Статья
08/07/2024

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

Сценарий

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

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

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

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

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

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

быть ключом RSA-HSM (4096-, 3072- или 2048-разрядным);
иметь фиксированный параметр key_ops (ТОЛЬКО "import"), т. е. быть пригодным только для использования во время BYOK;
находиться в том же хранилище ключей, в которое будет импортирован целевой ключ.

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

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

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

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

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

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

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

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

Примечание.

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

Создание KEK

С помощью команды az keyvault key create создайте ключ KEK, указав для него import в качестве операции с ключами. Запишите идентификатор ключа "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

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

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

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

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

в случае ключа 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-объект с зашифрованными данными.

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

Если используется CKM_RSA_AES_KEY_WRAP_PAD, сериализованный BLOB-объект передачи ключа в формате 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 = прямой режим, то есть указанный ребенок используется для непосредственной защиты шифра, который является точным представлением CKM_RSA_AES_KEY_WRAP
generator — информационное поле, определяющее имя и версию средства BYOK, а также изготовителя и модель исходного HSM. Эти сведения предназначены для использования при устранении неполадок и поддержке.

BLOB-объект в формате 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.

Ссылки

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

Следующие шаги

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

Поделиться через