Guida all'integrazione del modulo di sicurezza hardware southbound per Apigee Edge for Private Cloud

Versione di rilascio: Edge for Private Cloud v4.53.01.02 Patch Release e versioni successive.

Questa pagina spiega come configurare le connessioni TLS in direzione sud (dai processori di messaggi Apigee ai servizi di destinazione di backend) utilizzando i moduli di sicurezza hardware (HSM) di rete Entrust nShield® 5c.

Dichiarazione di non responsabilità per i contenuti di terze parti: questa pagina fornisce i passaggi di configurazione dell'hardware Entrust nShield in relazione all'integrazione di Apigee Edge. Questi passaggi si basano su pattern di integrazione standard e vengono forniti solo a scopo informativo. Le configurazioni di Entrust sono soggette a modifiche da parte del produttore. Consulta il portale della documentazione ufficiale di Entrust per specifiche autorevoli, configurazioni di sicurezza e requisiti hardware attuali.

Panoramica

I moduli di sicurezza hardware (HSM) forniscono un ambiente dedicato e protetto per l'archiviazione sicura delle chiavi e le operazioni di crittografia. Integrando Apigee Edge for Private Cloud con gli HSM Entrust nShield, puoi proteggere le chiavi private utilizzate negli handshake TLS e mTLS in direzione sud.

Apigee supporta l'integrazione HSM per il traffico HTTPS in direzione sud in uscita tra i seguenti componenti:

• Endpoint di destinazione
• Server di destinazione
• Policy Service Callout
• Policy di logging dei messaggi
• Policy JavaScript

Prerequisiti

Prima di configurare l'integrazione HSM, assicurati che siano soddisfatti i seguenti prerequisiti:

1. Requisiti della versione software

• Il cluster Apigee Edge for Private Cloud deve essere in esecuzione sulla versione 4.53.01.02 o successive.
• L'integrazione HSM è inclusa in modo nativo nelle seguenti versioni RPM (o successive):
  • 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. Configurazione dell'infrastruttura e del sistema operativo

• Il sistema operativo che ospita il cluster Edge for Private Cloud deve avere FIPS disabilitato.
• Il client HSM e Security World devono essere installati e configurati su tutti i nodi del processore di messaggi.
• Importante: questi passaggi devono essere eseguiti dall'utente apigee.

Verifica che l'installazione del client HSM sia configurata correttamente e accessibile all'utente apigee eseguendo il test di installazione CSP JCA/JCE standard fornito nella documentazione ufficiale di Entrust nShield. Assicurati che questo test venga completato correttamente su tutti i nodi del processore di messaggi.

Configurazioni supportate

Puoi configurare Apigee per utilizzare HSM in due modalità:

1. Modalità mista HSM (consigliata)

In questa modalità, solo le chiavi private (KeyStore) vengono archiviate nell'HSM, mentre i certificati attendibili (TrustStore) rimangono negli store software Apigee standard.

2. Modalità HSM completa

In questa modalità, sia il KeyStore (chiavi private) sia il TrustStore (certificati attendibili) vengono archiviati nell'HSM. Questa modalità è supportata, ma potrebbe introdurre una latenza aggiuntiva.

Passaggio 1: attiva HSM sui processori di messaggi

Esegui questi passaggi su ogni nodo del processore di messaggi, uno alla volta:

1. Arresta il processore di messaggi

apigee-service edge-message-processor stop

2. Verifica il file di dati del KeyStore HSM

Assicurati che il file di dati del KeyStore HSM (che fa riferimento alle chiavi caricate in HSM) sia presente nel nodo del processore di messaggi e di proprietà dell'utente apigee:

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

3. Crea il file di configurazione HSM

Crea o aggiorna il file di configurazione in /opt/apigee/hsm-config.properties. Definisci la località e le password per i keystore HSM e (facoltativamente) i truststore.

Esempio di configurazione (che supporta sia i proxy HSM misti sia quelli completi):

# 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

Imposta le autorizzazioni corrette:

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

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

4. Configura le proprietà del processore di messaggi

Crea o modifica /opt/apigee/customer/application/message-processor.properties e aggiungi quanto segue:

# 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

Assicurati che la proprietà sia corretta:

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

5. Riconfigura e riavvia

apigee-service edge-message-processor configure

apigee-service edge-message-processor restart

6. Convalida l'inizializzazione

Controlla il log di sistema /opt/apigee/var/log/edge-message-processor/logs/system.log per i messaggi di inizializzazione riuscita:

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

Passaggio 2: configura i proxy API

Aggiorna il blocco SSLInfo nella configurazione del proxy API (TargetEndpoint, ServiceCallout o policy). Utilizza il prefisso hsmref:// per fare riferimento agli store gestiti da HSM e ref:// (o il nome di riferimento standard) per gli store software.

1. Configurazione della modalità mista HSM (consigliata)

Utilizza HSM per KeyStore (autenticazione client) e software per TrustStore.

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

2. Configurazione HSM completa

Utilizza HSM sia per KeyStore sia per TrustStore.

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

Bypass della convalida in fase di deployment

Per facilitare il deployment senza caricare le chiavi private nel database Cassandra di Apigee, Apigee esegue automaticamente il bypass dei controlli di esistenza di keystore/truststore dell'ambiente durante il deployment per qualsiasi riferimento che inizia con il prefisso hsmref://.

Operazioni: aggiunta di nuovi keystore/truststore HSM

Per aggiungere un nuovo keystore o truststore HSM a un ambiente in esecuzione esistente:

1. Carica le chiavi/i certificati nell'HSM fisico (vedi Caricare keystore/truststore in HSM).
2. Copia il nuovo file di dati del keystore nei nodi del processore di messaggi e imposta la proprietà su apigee.
3. Aggiorna /opt/apigee/hsm-config.properties su tutti i nodi del processore di messaggi con il nuovo riferimento:

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

4. Riavvia il processore di messaggi su ogni nodo:

   apigee-service edge-message-processor restart

5. Aggiorna la configurazione del proxy API in modo che utilizzi il nuovo hsmref://new_keystore_ref ed esegui il deployment.

Disattivare HSM a livello globale

Per disattivare HSM:

1. Aggiorna tutti i proxy attivi che utilizzano hsmref:// in modo che utilizzino i riferimenti software standard (ref://).
2. Su ogni nodo del processore di messaggi, modifica /opt/apigee/customer/application/message-processor.properties e imposta:

   conf_system_apigee.hsm.enabled=false

3. Riconfigura e riavvia il processore di messaggi:

   apigee-service edge-message-processor configure

   apigee-service edge-message-processor restart

Limiti e avvertenze

• Hardware supportato: limitato agli HSM di rete Entrust nShield 5c.
• Manutenzione: i clienti sono responsabili della manutenzione del server/client HSM.
• Latenza: potrebbe verificarsi una latenza aggiuntiva a causa delle negoziazioni di rete con l'HSM. L'utilizzo della modalità mista HSM mitiga in parte questo problema.
• Riavvio HSM: se il server HSM viene riavviato, devi riavviare edge-message-processor sui nodi del processore di messaggi connessi.

Caricare keystore/truststore in HSM

Consulta il portale della documentazione ufficiale di Entrust nShield per i comandi keytool esatti necessari per importare un keystore PKCS12 o un certificato PEM nell'HSM.

Per garantire la compatibilità con Apigee, i file del keystore HSM risultanti devono soddisfare i seguenti requisiti:

• Directory: deve essere salvata in /opt/apigee/ (ad es. /opt/apigee/hsmks.keystore)
• Autorizzazioni: deve essere di proprietà dell'utente apigee (chown apigee:apigee /opt/apigee/<filename>)
• Leggibilità: deve essere leggibile dal servizio edge-message-processor.

Messaggi di errore

Note legali

Entrust e nShield sono marchi o marchi registrati di Entrust Corporation o delle sue società affiliate. Tutti gli altri marchi appartengono ai rispettivi proprietari.