Guia de integração do módulo de segurança de hardware de saída para o Apigee Edge para nuvem privada

Versão de lançamento:Edge para nuvem privada v4.53.01.02 e versões mais recentes.

Nesta página, explicamos como configurar conexões TLS de saída (dos processadores de mensagens da Apigee para serviços de destino de back-end) usando módulos de segurança de hardware (HSMs) de rede Entrust nShield® 5c.

Aviso de conteúdo de terceiros:esta página fornece etapas de configuração para o hardware Entrust nShield relacionadas à integração do Apigee Edge. Essas etapas são baseadas em padrões de integração padrão e são fornecidas apenas para fins informativos. As configurações do Entrust estão sujeitas a mudanças pelo fabricante. Consulte o Portal de documentação oficial do Entrust para conferir especificações autorizadas, configurações de segurança e requisitos de hardware atuais.

Visão geral

Os módulos de segurança de hardware (HSMs) oferecem um ambiente dedicado e reforçado para armazenamento seguro de chaves e operações criptográficas. Ao integrar o Apigee Edge para nuvem privada com HSMs Entrust nShield, você pode proteger as chaves privadas usadas em handshakes TLS e mTLS de saída.

A Apigee oferece suporte à integração de HSM para tráfego HTTPS de saída em todos os seguintes componentes:

• Endpoints de destino
• Servidores de destino
• Políticas de destaque de serviço
• Políticas de geração de registros de mensagens
• Políticas de JavaScript

Pré-requisitos

Verifique se os seguintes pré-requisitos foram atendidos antes de configurar a integração do HSM:

1. Requisitos de versão do software

• O cluster do Apigee Edge para nuvem privada precisa estar na versão 4.53.01.02 ou mais recente.
• A integração do HSM está incluída nativamente nas seguintes versões do RPM (ou mais recentes):
  • 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. Configuração de infraestrutura e sistema operacional

• O SO que hospeda o cluster do Edge para nuvem privada precisa ter o FIPS desativado.
• O cliente HSM e o Security World precisam ser instalados e configurados em todos os nós do processador de mensagens.
• Importante:essas etapas precisam ser realizadas pelo usuário apigee.

Verifique se a instalação do cliente HSM está configurada corretamente e acessível pelo usuário apigee executando o teste de instalação padrão do CSP JCA/JCE fornecido na documentação oficial do Entrust nShield. Verifique se esse teste é concluído com êxito em todos os nós do processador de mensagens.

Configurações aceitas

É possível configurar a Apigee para usar o HSM de duas maneiras:

1. Modo misto de HSM (recomendado)

Nesse modo, apenas as chaves privadas (KeyStore) são armazenadas no HSM, enquanto os certificados confiáveis (TrustStore) permanecem nos armazenamentos de software padrão da Apigee.

2. Modo HSM completo

Nesse modo, o KeyStore (chaves privadas) e o TrustStore (certificados confiáveis) são armazenados no HSM. Esse modo é aceito, mas pode introduzir latência adicional.

Etapa 1: ativar o HSM nos processadores de mensagens

Execute estas etapas em cada nó do processador de mensagens, um de cada vez:

1. Interromper o processador de mensagens

apigee-service edge-message-processor stop

2. Verificar o arquivo de dados do keystore do HSM

Verifique se o arquivo de dados do keystore do HSM (que faz referência às chaves carregadas no HSM) está presente no nó do processador de mensagens e pertence ao usuário apigee:

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

3. Criar o arquivo de configuração do HSM

Crie ou atualize o arquivo de configuração em /opt/apigee/hsm-config.properties. Defina o local e as senhas dos keystores do HSM e (opcionalmente) dos truststores.

Exemplo de configuração (com suporte a proxies HSM mistos e 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

Defina as permissões corretas:

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

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

4. Configurar propriedades do processador de mensagens

Crie ou edite /opt/apigee/customer/application/message-processor.properties e adicione o seguinte:

# 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

Verifique se a propriedade está correta:

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

5. Reconfigurar e reiniciar

apigee-service edge-message-processor configure

apigee-service edge-message-processor restart

6. Validar a inicialização

Verifique o registro do sistema /opt/apigee/var/log/edge-message-processor/logs/system.log para conferir mensagens de inicialização bem-sucedida:

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

Etapa 2: configurar proxies de API

Atualize o bloco SSLInfo na configuração do proxy de API (TargetEndpoint, ServiceCallout ou políticas). Use o hsmref:// prefixo para referenciar armazenamentos gerenciados pelo HSM e ref:// (ou nome de referência padrão) para armazenamentos de software.

1. Configuração do modo misto de HSM (recomendado)

Usa o HSM para KeyStore (autenticação do cliente) e o software para TrustStore.

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

2. Configuração completa do HSM

Usa o HSM para KeyStore e TrustStore.

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

Ignorar a validação no momento da implantação

Para facilitar a implantação sem fazer upload de chaves privadas para o banco de dados Cassandra da Apigee, a Apigee ignora automaticamente as verificações de existência do keystore/truststore do ambiente durante a implantação para qualquer referência que comece com o prefixo hsmref://.

Operações: como adicionar novos keystores/truststores do HSM

Para adicionar um novo keystore ou truststore do HSM a um ambiente em execução:

1. Carregue as chaves/certificados no HSM físico (consulte Como carregar keystores/truststores no HSM).
2. Copie o novo arquivo de dados do keystore para os nós do processador de mensagens e defina a propriedade como apigee.
3. Atualize /opt/apigee/hsm-config.properties em todos os nós do processador de mensagens com a nova referência:

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

4. Reinicie o processador de mensagens em cada nó:

   apigee-service edge-message-processor restart

5. Atualize a configuração do proxy de API para usar o novo hsmref://new_keystore_ref e implante.

Como desativar o HSM globalmente

Para desativar o HSM:

1. Atualize todos os proxies ativos que usam hsmref:// para usar referências de software padrão (ref://).
2. Em cada nó do processador de mensagens, edite /opt/apigee/customer/application/message-processor.properties e defina:

   conf_system_apigee.hsm.enabled=false

3. Reconfigure e reinicie o processador de mensagens:

   apigee-service edge-message-processor configure

   apigee-service edge-message-processor restart

Limitações e ressalvas

• Hardware com suporte:limitado a HSMs de rede Entrust nShield 5c.
• Manutenção:os clientes são responsáveis pela manutenção do servidor/cliente HSM.
• Latência:pode ocorrer latência adicional devido a negociações de rede com o HSM. O uso do modo misto de HSM atenua isso até certo ponto.
• Reinicialização do HSM:se o hardserver do HSM for reiniciado, você precisará reiniciar o edge-message-processor nos nós do processador de mensagens conectados.

Como carregar keystores/truststores no HSM

Consulte o Portal de documentação oficial do Entrust nShield para conferir os comandos keytool exatos necessários para importar um keystore PKCS12 ou um certificado PEM para o HSM.

Para garantir a compatibilidade com a Apigee, os arquivos de keystore do HSM resultantes precisam atender aos seguintes requisitos:

• Diretório: precisa ser salvo em /opt/apigee/ (por exemplo, /opt/apigee/hsmks.keystore)
• Permissões: precisam pertencer ao usuário apigee (chown apigee:apigee /opt/apigee/<filename>)
• Legibilidade:precisa ser legível pelo serviço edge-message-processor.

Referência de erros

Avisos legais

Entrust e nShield são marcas comerciais ou marcas registradas da Entrust Corporation ou de suas afiliadas. Todas as outras marcas registradas pertencem aos seus respectivos proprietários.