Руководство по интеграции аппаратного модуля безопасности с Apigee Edge для частного облака

Версия: Edge для частного облака версии 4.53.01.02 и более поздние.

На этой странице рассказывается, как настроить исходящие TLS-подключения (от процессоров сообщений Apigee к целевым серверным сервисам) с помощью сетевых аппаратных модулей безопасности (HSM) Entrust nShield® 5c.

Заявление об отказе от ответственности за сторонний контент. На этой странице приведены инструкции по настройке оборудования Entrust nShield для интеграции с Apigee Edge. Эти шаги основаны на стандартных шаблонах интеграции и предоставляются только в информационных целях. Конфигурации Entrust могут быть изменены производителем. Официальные спецификации, настройки безопасности и актуальные требования к оборудованию можно найти на портале документации Entrust.

Обзор

Аппаратные модули безопасности (HSM) предоставляют выделенную защищенную среду для безопасного хранения ключей и криптографических операций. Интегрировав Apigee Edge для частного облака с HSM Entrust nShield, вы сможете защитить закрытые ключи, используемые при подтверждении TLS и mTLS на стороне сервера.

Apigee поддерживает интеграцию HSM для исходящего HTTPS-трафика в следующих компонентах:

• Целевые конечные точки
• Целевые серверы
• Правила в отношении уточнений для услуг
• Правила ведения журналов сообщений
• Правила использования JavaScript

Требования

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

1. Требования к версии ПО

• Кластер Apigee Edge для частного облака должен работать под управлением версии 4.53.01.02 или более поздней.
• Интеграция с HSM изначально включена в следующие версии RPM (или более поздние):
  • edge-management-server-4.53.01-0.0.60380.noarch.rpm
  • edge-message-processor-4.53.01-0.0.60380.noarch.rpm
  • edge-gateway-4.53.01-0.0.60380.noarch.rpm

2. Конфигурация инфраструктуры и операционной системы

• В ОС, на которой размещен кластер Edge для частного облака, должен быть отключен режим FIPS.
• Клиент HSM и Security World должны быть установлены и настроены на всех узлах Message Processor.
• Важно! Эти действия должен выполнить пользователь apigee.

Убедитесь, что клиент HSM настроен правильно и доступен пользователю apigee. Для этого запустите стандартный тест установки CSP JCA/JCE, описанный в официальной документации Entrust nShield. Убедитесь, что этот тест успешно завершен на всех узлах Message Processor.

Поддерживаемые конфигурации

Вы можете настроить Apigee на использование HSM в двух режимах:

1. Смешанный режим HSM (рекомендуется)

В этом режиме в HSM хранятся только закрытые ключи (KeyStore), а доверенные сертификаты (TrustStore) остаются в стандартных хранилищах ПО Apigee.

2. Полнофункциональный режим HSM

В этом режиме и хранилище ключей (закрытые ключи), и хранилище доверенных сертификатов хранятся в HSM. Этот режим поддерживается, но может привести к дополнительным задержкам.

Шаг 1. Включите HSM на процессорах сообщений

Выполните следующие действия на каждом узле Message Processor по очереди:

1. Как остановить обработчик сообщений

apigee-service edge-message-processor stop

2. Как проверить файл данных хранилища ключей HSM

Убедитесь, что файл данных хранилища ключей HSM (со ссылками на ключи, загруженные в HSM) присутствует на узле Message Processor и принадлежит пользователю apigee:

chown apigee:apigee /opt/apigee/{name_of_the_Keystore_Data_File}

3. Как создать файл конфигурации HSM

Создайте или обновите файл конфигурации в каталоге /opt/apigee/hsm-config.properties. Укажите местоположение и пароли для хранилищ ключей HSM и (при необходимости) хранилищ доверенных сертификатов.

Пример конфигурации (поддерживает как смешанные, так и полные прокси-серверы HSM):

# HSM KeyStore Reference
hsm.property.unique_keystore_ref1.keystore.file.location=/opt/apigee/ks.keystore
hsm.property.unique_keystore_ref1.keystore.password=keystore_password

# HSM TrustStore Reference (Optional, only needed for Full HSM Mode)
hsm.property.unique_truststore_ref1.truststore.file.location=/opt/apigee/ts.truststore
hsm.property.unique_truststore_ref1.truststore.password=truststore_password

Установите правильные разрешения:

chown apigee:apigee /opt/apigee/hsm-config.properties

chmod 600 /opt/apigee/hsm-config.properties

4. Как настроить свойства обработчика сообщений

Создайте или измените файл /opt/apigee/customer/application/message-processor.properties и добавьте в него следующие данные:

# Enable HSM Integration
conf_system_apigee.hsm.enabled=true

# HSM Configuration File Path
conf_system_apigee.hsm.properties.file=/opt/apigee/hsm-config.properties

# Advanced Custom HSM Port Support (Optional, default is 9000/9001)
# conf_system_apigee.hsm.priv_port=9001
# conf_system_apigee.hsm.nonpriv_port=9000

Убедитесь, что право собственности указано правильно.

chown apigee:apigee /opt/apigee/customer/application/message-processor.properties

5. Настроить и перезапустить

apigee-service edge-message-processor configure

apigee-service edge-message-processor restart

6. Проверка инициализации

Проверьте системный журнал /opt/apigee/var/log/edge-message-processor/logs/system.log на наличие сообщений об успешной инициализации:

main INFO  SECURITY-CONTEXT - SSLPreEvaluationContext.isHSMConfigEnabled() : HSM_FLOW : HSM config is enabled
main INFO  SECURITY-CONTEXT - SSLPreEvaluationContext.loadProperties() : HSM_FLOW :  HSM config properties loaded from file /opt/apigee/hsm-config.properties

Шаг 2. Настройте прокси API

Обновите блок SSLInfo в конфигурации прокси-сервера API (TargetEndpoint, ServiceCallout или правила). Используйте префикс hsmref:// для магазинов, управляемых HSM, и ref:// (или стандартное название) для магазинов ПО.

1. Конфигурация смешанного режима HSM (рекомендуется)

Использует HSM для KeyStore (аутентификация клиента) и программное обеспечение для TrustStore.

<SSLInfo>
    <Enabled>true</Enabled>
    <ClientAuthEnabled>true</ClientAuthEnabled>
    <KeyStore>hsmref://unique_keystore_ref1</KeyStore>
    <TrustStore>ref://mySoftwareTrustStoreRef</TrustStore>
</SSLInfo>

2. Полная конфигурация HSM

Использует HSM для KeyStore и TrustStore.

<SSLInfo>
    <Enabled>true</Enabled>
    <ClientAuthEnabled>true</ClientAuthEnabled>
    <KeyStore>hsmref://unique_keystore_ref1</KeyStore>
    <TrustStore>hsmref://unique_truststore_ref1</TrustStore>
</SSLInfo>

Пропуск проверки во время развертывания

Чтобы упростить развертывание без загрузки частных ключей в базу данных Cassandra Apigee, Apigee автоматически пропускает проверки наличия хранилища ключей/доверенных сертификатов среды во время развертывания для любой ссылки, начинающейся с префикса hsmref://.

Операции: добавление новых хранилищ ключей HSM/доверенных хранилищ

Чтобы добавить новое хранилище ключей HSM или хранилище доверенных сертификатов в существующую работающую среду:

1. Загрузите ключи и сертификаты в физический HSM (см. раздел Загрузка хранилищ ключей и доверенных хранилищ в HSM).
2. Скопируйте новый файл данных хранилища ключей в узлы Message Processor и задайте владельца apigee.
3. Обновите /opt/apigee/hsm-config.properties на всех узлах Message Processor, используя новую ссылку:

   hsm.property.new_keystore_ref.keystore.file.location=/opt/apigee/new_ks.keystore
   hsm.property.new_keystore_ref.keystore.password=new_password
       

4. Перезапустите Message Processor на каждом узле:

   apigee-service edge-message-processor restart

5. Обновите конфигурацию прокси-сервера API, чтобы использовать новый элемент hsmref://new_keystore_ref, и разверните ее.

Как отключить HSM на уровне организации

Чтобы отключить HSM:

1. Обновите все активные прокси-серверы, используя hsmref://, чтобы использовать стандартные ссылки на ПО (ref://).
2. На каждом узле Message Processor измените файл /opt/apigee/customer/application/message-processor.properties и задайте следующие значения:

   conf_system_apigee.hsm.enabled=false

3. Перенастройте и перезапустите обработчик сообщений:

   apigee-service edge-message-processor configure

   apigee-service edge-message-processor restart

Ограничения

• Поддерживаемое оборудование. Ограничено сетевыми HSM Entrust nShield 5c.
• Обслуживание. Клиенты несут ответственность за обслуживание сервера/клиента HSM.
• Задержка. Дополнительная задержка может возникнуть из-за переговоров с HSM по сети. Использование смешанного режима HSM позволяет частично решить эту проблему.
• Перезапуск HSM. Если перезапускается аппаратный сервер HSM, необходимо перезапустить edge-message-processor на подключенных узлах Message Processor.

Как загрузить хранилища ключей и доверенных сертификатов в HSM

Чтобы узнать, какие именно команды keytool требуются для импорта хранилища ключей PKCS12 или сертификата PEM в HSM, ознакомьтесь с официальным порталом документации Entrust nShield.

Чтобы обеспечить совместимость с Apigee, полученные файлы хранилища ключей HSM должны соответствовать следующим требованиям:

• Каталог: должен быть сохранен в /opt/apigee/ (например, /opt/apigee/hsmks.keystore).
• Разрешения: должны принадлежать пользователю apigee (chown apigee:apigee /opt/apigee/<filename>).
• Читаемость. Файл должен быть читаемым для сервиса edge-message-processor.

Справочник по ошибкам

Юр. информация

Entrust и nShield – товарные знаки или зарегистрированные товарные знаки компании Entrust Corporation или ее аффилированных лиц. Все остальные товарные знаки являются собственностью их законных владельцев.