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

Версия выпуска: Edge for Private Cloud v4.53.01.02 Patch Release и более поздние версии.

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

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

Обзор

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

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

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

Предварительные требования

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

1. Требования к версии программного обеспечения

  • Для работы кластера Apigee Edge for Private Cloud должна использоваться версия 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 for Private Cloud, функция FIPS должна быть отключена.
  • Клиент HSM и Security World должны быть установлены и настроены на всех узлах обработчика сообщений.
  • Важно: Эти действия должен выполнить пользователь apigee .

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

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

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

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

2. Полный режим HSM

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

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

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

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

apigee-service edge-message-processor stop

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

Убедитесь, что файл данных хранилища ключей HSM (содержащий ссылки на ключи, загруженные в HSM) присутствует на узле обработчика сообщений и принадлежит пользователю 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 или policies). Используйте префикс hsmref:// для ссылок на хранилища, управляемые HSM, и ref:// (или стандартное имя ссылки) для хранилищ программного обеспечения.

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

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

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

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

<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. Скопируйте новый файл данных хранилища ключей на узлы обработчика сообщений и установите права доступа для 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. Перезапустите обработчик сообщений на каждом узле: 
    apigee-service edge-message-processor restart
  5. Обновите конфигурацию API-прокси, чтобы использовать новый hsmref://new_keystore_ref , и выполните развертывание.

Отключение HSM в глобальном режиме

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

  1. Обновите все активные прокси-серверы, использующие hsmref:// чтобы они применяли стандартные ссылки на программное обеспечение ( ref:// ).
  2. На каждом узле обработчика сообщений отредактируйте файл /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 на подключенных узлах обработчика сообщений.

Загрузка хранилищ ключей/доверенных хранилищ в 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 .

Справочная информация об ошибке

Код ошибки Статус HTTP Описание / Причина
entities.HsmConfigNotEnabled 500 API-прокси попытался использовать hsmref:// во время выполнения, но HSM отключен глобально ( conf_system_apigee.hsm.enabled=false ) в обработчике сообщений.

Entrust и nShield являются товарными знаками или зарегистрированными товарными знаками корпорации Entrust или ее дочерних компаний. Все остальные товарные знаки являются собственностью их соответствующих владельцев.

,

Версия выпуска: Edge for Private Cloud v4.53.01.02 Patch Release и более поздние версии.

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

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

Обзор

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

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

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

Предварительные требования

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

1. Требования к версии программного обеспечения

  • Для работы кластера Apigee Edge for Private Cloud должна использоваться версия 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 for Private Cloud, функция FIPS должна быть отключена.
  • Клиент HSM и Security World должны быть установлены и настроены на всех узлах обработчика сообщений.
  • Важно: Эти действия должен выполнить пользователь apigee .

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

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

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

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

2. Полный режим HSM

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

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

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

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

apigee-service edge-message-processor stop

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

Убедитесь, что файл данных хранилища ключей HSM (содержащий ссылки на ключи, загруженные в HSM) присутствует на узле обработчика сообщений и принадлежит пользователю 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 или policies). Используйте префикс hsmref:// для ссылок на хранилища, управляемые HSM, и ref:// (или стандартное имя ссылки) для хранилищ программного обеспечения.

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

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

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

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

<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. Скопируйте новый файл данных хранилища ключей на узлы обработчика сообщений и установите права доступа для 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. Перезапустите обработчик сообщений на каждом узле: 
    apigee-service edge-message-processor restart
  5. Обновите конфигурацию API-прокси, чтобы использовать новый hsmref://new_keystore_ref , и выполните развертывание.

Отключение HSM в глобальном режиме

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

  1. Обновите все активные прокси-серверы, использующие hsmref:// чтобы они применяли стандартные ссылки на программное обеспечение ( ref:// ).
  2. На каждом узле обработчика сообщений отредактируйте файл /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 на подключенных узлах обработчика сообщений.

Загрузка хранилищ ключей/доверенных хранилищ в 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 .

Справочная информация об ошибке

Код ошибки Статус HTTP Описание / Причина
entities.HsmConfigNotEnabled 500 API-прокси попытался использовать hsmref:// во время выполнения, но HSM отключен глобально ( conf_system_apigee.hsm.enabled=false ) в обработчике сообщений.

Entrust и nShield являются товарными знаками или зарегистрированными товарными знаками корпорации Entrust или ее дочерних компаний. Все остальные товарные знаки являются собственностью их соответствующих владельцев.