Guía de integración del módulo de seguridad de hardware de salida para Apigee Edge para la nube privada

Versión de lanzamiento: Versión de parche v4.53.01.02 de Edge para la nube privada y versiones posteriores.

En esta página, se explica cómo configurar conexiones TLS de salida (desde los procesadores de mensajes de Apigee a los servicios de destino de backend) con módulos de seguridad de hardware (HSM) de red Entrust nShield® 5c.

Descargo de responsabilidad sobre el contenido de terceros: En esta página, se proporcionan los pasos de configuración para el hardware de Entrust nShield en relación con la integración de Apigee Edge. Estos pasos se basan en patrones de integración estándar y se proporcionan solo con fines informativos. El fabricante puede cambiar las configuraciones de Entrust. Consulta el portal oficial de documentación de Entrust para obtener especificaciones autorizadas, configuraciones de seguridad y requisitos de hardware actuales.

Descripción general

Los módulos de seguridad de hardware (HSM) proporcionan un entorno dedicado y reforzado para el almacenamiento seguro de claves y las operaciones criptográficas. Si integras Apigee Edge para la nube privada con HSM de Entrust nShield, puedes proteger las claves privadas que se usan en los protocolos de enlace TLS y mTLS de salida.

Apigee admite la integración de HSM para el tráfico HTTPS de salida en los siguientes componentes:

• Extremos de destino
• Servidores de destino
• Políticas de texto destacado de servicio
• Políticas de registro de mensajes
• Políticas JavaScript

Requisitos previos

Asegúrate de que se cumplan los siguientes requisitos previos antes de configurar la integración de HSM:

1. Requisitos de la versión de software

• El clúster de Apigee Edge para la nube privada debe ejecutarse en la versión 4.53.01.02 o posterior.
• La integración de HSM se incluye de forma nativa en las siguientes versiones de RPM (o superiores):
  • 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. Configuración de la infraestructura y el sistema operativo

• El SO que aloja el clúster de Edge para la nube privada debe tener FIPS inhabilitado.
• El cliente de HSM y Security World deben estar instalados y configurados en todos los nodos de Message Processor.
• Importante: El usuario apigee debe realizar estos pasos.

Para verificar que la instalación del cliente de HSM esté configurada correctamente y que el usuario apigee pueda acceder a ella, ejecuta la prueba de instalación estándar de JCA/JCE CSP que se proporciona en la documentación oficial de Entrust nShield. Asegúrate de que esta prueba se complete correctamente en todos los nodos de Message Processor.

Parámetros de configuración admitidos

Puedes configurar Apigee para que use HSM en dos modos:

1. Modo mixto de HSM (recomendado)

En este modo, solo las claves privadas (almacén de claves) se almacenan en el HSM, mientras que los certificados de confianza (almacén de confianza) permanecen en los almacenes de software estándar de Apigee.

2. Modo HSM completo

En este modo, tanto el almacén de claves (claves privadas) como el almacén de confianza (certificados de confianza) se almacenan en el HSM. Este modo es compatible, pero puede introducir latencia adicional.

Paso 1: Habilita el HSM en los procesadores de mensajes

Realiza estos pasos en cada nodo de Message Processor, uno a la vez:

1. Detén el procesador de mensajes

apigee-service edge-message-processor stop

2. Verifica el archivo de datos del almacén de claves de HSM

Asegúrate de que el archivo de datos del almacén de claves de HSM (que hace referencia a las claves cargadas en el HSM) esté presente en el nodo del Message Processor y que sea propiedad del usuario apigee:

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

3. Crea el archivo de configuración de HSM

Crea o actualiza el archivo de configuración en /opt/apigee/hsm-config.properties. Define la ubicación y las contraseñas de los almacenes de claves de HSM y (opcionalmente) los almacenes de confianza.

Configuración de ejemplo (admite proxies de HSM mixtos y completos):

# 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

Establece los permisos correctos:

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

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

4. Configura las propiedades del procesador de mensajes

Crea o edita /opt/apigee/customer/application/message-processor.properties y agrega lo siguiente:

# 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

Asegúrate de que la propiedad sea correcta:

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

5. Vuelve a configurar y reiniciar

apigee-service edge-message-processor configure

apigee-service edge-message-processor restart

6. Valida la inicialización

Verifica el registro del sistema /opt/apigee/var/log/edge-message-processor/logs/system.log en busca de mensajes de inicialización correctos:

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

Paso 2: Configura los proxies de API

Actualiza el bloque SSLInfo en la configuración del proxy de API (TargetEndpoint, ServiceCallout o políticas). Usa el prefijo hsmref:// para hacer referencia a los almacenes administrados por HSM y ref:// (o el nombre de referencia estándar) para los almacenes de software.

1. Configuración del modo mixto de HSM (recomendado)

Usa HSM para el almacén de claves (autenticación del cliente) y software para el almacén de confianza.

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

2. Configuración completa de HSM

Usa HSM para el almacén de claves y el almacén de confianza.

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

Omisión de la validación en el momento de la implementación

Para facilitar la implementación sin subir claves privadas a la base de datos de Cassandra de Apigee, Apigee omite automáticamente las verificaciones de existencia del almacén de claves o del almacén de certificados de confianza del entorno durante la implementación para cualquier referencia que comience con el prefijo hsmref://.

Operaciones: Agrega almacenes de claves o de confianza de HSM nuevos

Para agregar un almacén de claves o un almacén de certificados de confianza de HSM nuevo a un entorno en ejecución existente, haz lo siguiente:

1. Carga las claves o los certificados en el HSM físico (consulta Cómo cargar almacenes de claves o de confianza en el HSM).
2. Copia el nuevo archivo de datos del almacén de claves en los nodos de Message Processor y establece la propiedad en apigee.
3. Actualiza /opt/apigee/hsm-config.properties en todos los nodos de Message Processor con la nueva referencia:

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

4. Reinicia el Message Processor en cada nodo:

   apigee-service edge-message-processor restart

5. Actualiza la configuración del proxy de API para usar el nuevo hsmref://new_keystore_ref y realizar la implementación.

Inhabilita el HSM de forma global

Para inhabilitar el HSM, haz lo siguiente:

1. Actualiza todos los proxies activos que usen hsmref:// para usar referencias de software estándar (ref://).
2. En cada nodo de Message Processor, edita /opt/apigee/customer/application/message-processor.properties y establece lo siguiente:

   conf_system_apigee.hsm.enabled=false

3. Vuelve a configurar y reiniciar el procesador de mensajes:

   apigee-service edge-message-processor configure

   apigee-service edge-message-processor restart

Limitaciones y advertencias

• Hardware compatible: Se limita a los HSM de red Entrust nShield 5c.
• Mantenimiento: Los clientes son responsables del mantenimiento del servidor o cliente de HSM.
• Latencia: Es posible que se produzca latencia adicional debido a las negociaciones de red con el HSM. El uso del modo mixto de HSM mitiga esto hasta cierto punto.
• Reinicio de HSM: Si se reinicia el servidor de HSM, debes reiniciar el edge-message-processor en los nodos del procesador de mensajes conectados.

Cómo cargar almacenes de claves o de confianza en el HSM

Consulta el portal oficial de documentación de Entrust nShield para obtener los comandos keytool exactos necesarios para importar un almacén de claves PKCS12 o un certificado PEM al HSM.

Para garantizar la compatibilidad con Apigee, los archivos de almacén de claves de HSM resultantes deben cumplir con los siguientes requisitos:

• Directorio: Se debe guardar en /opt/apigee/ (p.ej., /opt/apigee/hsmks.keystore).
• Permisos: Debe ser propiedad del usuario apigee (chown apigee:apigee /opt/apigee/<filename>).
• Legibilidad: El servicio edge-message-processor debe poder leerlo.

Referencia de errores

Avisos legales

Entrust y nShield son marcas comerciales o marcas registradas de Entrust Corporation o sus afiliados. Todas las demás marcas comerciales son propiedad de sus respectivos dueños.