Краткое руководство. Создание первого внешнего ключа с помощью Azure CLI (предварительная версия)

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

Если вы предпочитаете использовать портал Azure, см. краткое руководство. Создание первого внешнего ключа с помощью портала Azure.

Prerequisites

Прежде чем начать, вам понадобится следующее:

• Существующий управляемый HSM, развернутый в любом общедоступном регионе Azure, с включённым внешним управлением ключами для подписки вашей группой по работе с учётной записью Microsoft. Обратитесь к вашей команде по работе с клиентом, чтобы запросить активацию. Чтобы создать управляемый HSM, см. Краткое руководство: подготовка и активация управляемого HSM с помощью Azure CLI.
• Рабочий прокси-сервер EKM, доступный из Azure. Прокси-сервер должен реализовать спецификацию API прокси-сервера EKM. Сведения о поддерживаемых поставщиках см. в разделе "Что такое управляемое управление внешними ключами HSM?".
• Ключ, созданный во внешнем HSM с известным внешним идентификатором ключа. Идентификатор внешнего ключа — это идентификатор прокси-сервера, который используется для поиска ключа.
• Корневой сертификат УЦ (в формате PEM), который подписал TLS-сертификат сервера вашего прокси-сервера.
• Azure CLI версии 2.x с установленным последним keyvault расширением. Запустите az extension add --name keyvault или az extension update --name keyvault, чтобы получить последнюю версию.
• Роль Managed HSM EKM Administrator для управления подключениями к внешней системе управления ключами и роль Managed HSM Crypto User для создания и использования ключей. Инструкции по назначению ролей см. в разделе "Управление доступом управляемого устройства HSM".

Вход в Azure

az login

Выберите подписку, если у вас несколько подписок:

az account set --subscription "<subscription-id>"

Отображение сертификата клиента управляемого модуля HSM

Управляемый HSM предъявляет сертификат клиента X.509 вашему прокси EKM при каждом входящем соединении по взаимному TLS (mTLS). Перед созданием подключения к внешнему управлению ключами получите общее имя (CN) субъекта сертификата и сертификат корневого центра сертификации, а затем добавьте их в список разрешённых на вашем прокси-сервере. Именно так прокси-сервер проверяет, что подключение исходит от вашего Managed HSM, а не от произвольного клиента.

az keyvault ekm-connection certificate show --hsm-name <Managed HSM Name>

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

{
  "caCertificates": [
    "MIIDj...<truncated>...MrY="
  ],
  "subjectCommonName": "contoso.managedhsmclient.azure.net"
}

Настройте прокси-сервер так, чтобы он доверял подключениям, которые используют сертификат с subjectCommonName и восходят к одному из сертификатов в списке caCertificates, приведённом выше. Точные шаги зависят от поставщика прокси-сервера.

Создайте подключение к внешнему управлению ключами

Подключение внешнего управления ключами привязывает управляемый HSM к одному прокси-серверу EKM. Он содержит прокси-адрес, привязку доверия ЦС сервера и дополнительный префикс пути.

az keyvault ekm-connection create \
    --hsm-name <Managed HSM Name> \
    --host <EKMProxy Host> \
    --server-ca-certificate <Root cert> \
    [--path-prefix <prefix>]

Справочник по параметрам:

• --hsm-name: Это имя вашего управляемого модуля HSM.
• --host: полное доменное имя узла вашего EKM Proxy. Например: proxy.contoso.com. Прокси-сервер должен прослушивать TCP-порт 443; Нестандартный порт не поддерживается в предварительной версии.
• --server-ca-certificate: указывает путь к файлу сертификата корневого ЦС формата PEM или DER, используемого для проверки TLS-сертификата сервера прокси.
• --path-prefix (необязательно): префикс пути URL-адреса, если прокси-сервер мультиплексирует несколько клиентов или пулов по пути. Например: /contoso/prod.

Проверка подключения

После создания подключения убедитесь, что управляемый HSM может получить доступ к прокси-серверу:

az keyvault ekm-connection check --hsm-name <Managed HSM Name>

Эта команда обращается к конечной точке прокси-сервера /info через настроенное подключение. Успешные выходные данные выглядят примерно так:

{
  "apiVersion": "1.0",
  "ekmProduct": "Contoso HSM v1.0.0",
  "ekmVendor": "Contoso HSM",
  "proxyName": "Contoso Proxy Service",
  "proxyVendor": "Contoso Proxy"
}

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

Создание внешнего ключа

Создайте ссылку на ключ управляемого HSM, которая указывает на внешний ключ в вашем HSM. В Managed HSM не создается никакой ключевой материал — эта команда регистрирует ссылку на существующий ключ, который определяется его внешним идентификатором ключа.

az keyvault key create \
    --external-key-id <external-key-identifier> \
    --hsm-name <Managed HSM Name> \
    --name <key-ref-name>

Справочник по параметрам:

• --external-key-id: идентификатор внешнего ключа, зарегистрированный на прокси-сервере. Это идентификатор прокси-сервера, который используется для поиска правильного ключа во внешнем HSM.
• --hsm-name: Это имя вашего управляемого модуля HSM.
• --name: имя, которое вы хотите присвоить ссылке на ключ управляемого HSM. Это становится частью URI ключа, используемого Azure службами.

Команда возвращает URI-адрес ключа в виде https://<hsm-name>.managedhsm.azure.net/keys/<key-ref-name>/<version>. Используйте этот URI при настройке параметров управляемого клиентом ключа (CMK) в службах Azure.

Проверка оболочки или распаковки

Подтвердите сквозную интеграцию, выполнив полный цикл оборачивания и разворачивания. Фактические операции упаковки и распаковки выполняются на прокси-сервере и внешнем HSM— управляемый HSM направляет запрос и возвращает результат.

1. Создайте тело запроса для операции wrap. Задайте value для материала ключа в кодировке Base64url, который требуется упаковать.

   {
     "alg": "RSA-OAEP-256",
     "value": "<base64url-encoded-plaintext-key>"
   }
   

   Сохраните его как wrapkey.json. Для внешних ключей AES используйте "alg": "A256KW" вместо RSA-OAEP-256.

2. Вызовите конечную точку wrapkey в справочнике по вашему ключу:

   az rest --method POST \
       --uri "https://<Managed HSM Name>.managedhsm.azure.net/keys/<key-ref-name>/wrapkey?api-version=7.5" \
       --resource "https://managedhsm.azure.net" \
       --headers "Content-Type=application/json" \
       --body @wrapkey.json
   

   В ответе возвращаются версия ключа (kid) и поле value, содержащее обёрнутый ключ, закодированный в формате base64url. Скопируйте value для следующего шага.

3. Создайте текст запроса для операции распаковки, используя оболочку value из предыдущего шага:

   {
     "alg": "RSA-OAEP-256",
     "value": "<wrapped-value-from-previous-step>"
   }
   

   Сохраните его как unwrapkey.json.

4. Вызовите конечную точку unwrapkey , чтобы подтвердить правильность кругового пути:

   az rest --method POST \
       --uri "https://<Managed HSM Name>.managedhsm.azure.net/keys/<key-ref-name>/unwrapkey?api-version=7.5" \
       --resource "https://managedhsm.azure.net" \
       --headers "Content-Type=application/json" \
       --body @unwrapkey.json
   

   Успешный ответ возвращает исходный открытый текст value , который вы упаковали на первом шаге. Если операция разворачивания завершается сбоем, сведения о кодах ошибок прокси и способах их устранения см. в разделе Устранение неполадок при управлении внешними ключами в Managed HSM.

Просмотр журналов аудита

Каждый вызов EKM Proxy создает запись EkmProxyOperation в диагностических журналах Managed HSM. Чтобы запросить эти данные в Log Analytics:

AzureDiagnostics
| where ResourceProvider == "MICROSOFT.KEYVAULT"
| where OperationName contains "Ekm"
| project TimeGenerated, Resource, OperationName, requestUri_s, ResultType, ResultDescription

Журнал содержит тип операции (wrap или unwrap), идентификатор внешнего ключа, код состояния HTTP, возвращаемый прокси-сервером, и задержку приема-передачи. Полное руководство по ведению журнала и мониторингу, включая настройку оповещений и корреляцию журналов на стороне прокси-сервера, см. в разделе "Ведение журнала и мониторинг" для управления внешними ключами HSM.

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

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

1. Удалите ссылку на ключ управляемого HSM:

   az keyvault key delete \
       --hsm-name <Managed HSM Name> \
       --name <key-ref-name>
   

2. Удалите подключение к управлению внешними ключами:

   az keyvault ekm-connection delete \
       --hsm-name <Managed HSM Name>
   

Удаление ссылки на ключ управляемого HSM не влияет на ключевой материал во внешнем HSM. Этот ключ остается в вашем HSM, пока вы не удалите его там.

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

• Краткое руководство: создайте свой первый внешний ключ с помощью портала Azure — выполните те же действия в портале Azure
• Жизненный цикл внешнего ключа в управляемом управлении внешним ключом HSM — смена ключей, управление версиями и вывод внешних ключей
• Настройка сети и mTLS для управления внешними ключами в Managed HSM — подключение через общедоступный Интернет и ротация сертификатов
• Ведение журнала и мониторинг для управления внешними ключами HSM — правила генерации оповещений, запросы языка запросов Kusto (KQL) и корреляция журналов прокси-сервера
• Устранение неполадок управления внешними ключами HSM — коды ошибок, диагностика прокси-сервера и действия по исправлению