Southbound Hardware Security Module Integration Guide for Apigee Edge for Private Cloud

Release-Version:Edge for Private Cloud v4.53.01.02 Patch Release und höher.

Auf dieser Seite wird erläutert, wie Sie Southbound-TLS-Verbindungen (von Apigee Message Processors zu Backend-Zieldiensten) mit Entrust nShield® 5c-Netzwerk-Hardware Security Modules (HSMs) konfigurieren.

Haftungsausschluss für Inhalte von Dritten:Auf dieser Seite werden Konfigurationsschritte für Entrust nShield-Hardware im Zusammenhang mit der Apigee Edge-Integration beschrieben. Diese Schritte basieren auf Standardintegrationsmustern und dienen nur zu Informationszwecken. Entrust-Konfigurationen können vom Hersteller geändert werden. Die maßgeblichen Spezifikationen, Sicherheitskonfigurationen und aktuellen Hardwareanforderungen finden Sie im offiziellen Entrust-Dokumentationsportal.

Übersicht

Hardware Security Modules (HSMs) bieten eine dedizierte, gehärtete Umgebung für die sichere Schlüsselspeicherung und kryptografische Vorgänge. Durch die Integration von Apigee Edge for Private Cloud mit Entrust nShield-HSMs können Sie die privaten Schlüssel schützen, die bei Southbound-TLS- und mTLS-Handshakes verwendet werden.

Apigee unterstützt die HSM-Integration für ausgehenden Southbound-HTTPS-Traffic für die folgenden Komponenten:

• Zielendpunkte
• Zielserver
• ServiceCallout-Richtlinien
• MessageLogging-Richtlinien
• JavaScript-Richtlinien

Vorbereitung

Prüfen Sie vor der Konfiguration der HSM-Integration, ob die folgenden Voraussetzungen erfüllt sind:

1. Anforderungen an die Softwareversion

• Auf dem Apigee Edge for Private Cloud-Cluster muss Version 4.53.01.02 oder höher ausgeführt werden.
• Die HSM-Integration ist nativ in den folgenden RPM-Versionen (oder höher) enthalten:
  • 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. Konfiguration von Infrastruktur und Betriebssystem

• Auf dem Betriebssystem, auf dem der Edge for Private Cloud-Cluster gehostet wird, muss FIPS deaktiviert sein.
• Der HSM-Client und Security World müssen auf allen Message Processor-Knoten installiert und konfiguriert sein.
• Wichtig:Diese Schritte müssen vom Nutzer apigee ausgeführt werden.

Prüfen Sie, ob die HSM-Clientinstallation korrekt konfiguriert ist und vom Nutzer apigee aufgerufen werden kann. Führen Sie dazu den Standardtest für die JCA/JCE CSP-Installation aus, der in der offiziellen Entrust nShield-Dokumentation beschrieben ist. Achten Sie darauf, dass dieser Test auf allen Message Processor-Knoten erfolgreich abgeschlossen wird.

Unterstützte Konfigurationen

Sie können Apigee so konfigurieren, dass HSM in zwei Modi verwendet wird:

1. HSM-Mischmodus (empfohlen)

In diesem Modus werden nur die privaten Schlüssel (Keystore) im HSM gespeichert, während die vertrauenswürdigen Zertifikate (Truststore) in den Standardspeichern der Apigee-Software verbleiben.

2. Vollständiger HSM-Modus

In diesem Modus werden sowohl der Keystore (private Schlüssel) als auch der Truststore (vertrauenswürdige Zertifikate) im HSM gespeichert. Dieser Modus wird unterstützt, kann aber zu zusätzlicher Latenz führen.

Schritt 1: HSM auf Message Processors aktivieren

Führen Sie diese Schritte auf jedem Message Processor-Knoten einzeln aus:

1. Message Processor beenden

apigee-service edge-message-processor stop

2. HSM-Keystore-Datendatei prüfen

Achten Sie darauf, dass die HSM-Keystore-Datendatei (mit Verweis auf die im HSM geladenen Schlüssel) auf dem Message Processor-Knoten vorhanden ist und dem Nutzer apigee gehört:

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

3. HSM-Konfigurationsdatei erstellen

Erstellen oder aktualisieren Sie die Konfigurationsdatei unter /opt/apigee/hsm-config.properties. Definieren Sie den Speicherort und die Passwörter für die HSM-Keystores und optionalen Truststores.

Beispielkonfiguration (unterstützt sowohl gemischte als auch vollständige HSM-Proxys):

# 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

Legen Sie die richtigen Berechtigungen fest:

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

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

4. Message Processor-Eigenschaften konfigurieren

Erstellen oder bearbeiten Sie /opt/apigee/customer/application/message-processor.properties und fügen Sie Folgendes hinzu:

# 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

Achten Sie auf die richtige Inhaberschaft:

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

5. Neu konfigurieren und neu starten

apigee-service edge-message-processor configure

apigee-service edge-message-processor restart

6. Initialisierung prüfen

Suchen Sie im Systemlog /opt/apigee/var/log/edge-message-processor/logs/system.log nach Nachrichten über eine erfolgreiche Initialisierung:

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

Schritt 2: API-Proxys konfigurieren

Aktualisieren Sie den Block SSLInfo in der API-Proxy-Konfiguration (TargetEndpoint, ServiceCallout oder Richtlinien). Verwenden Sie das Präfix hsmref:// für HSM-verwaltete Speicher und ref:// (oder den Standardreferenznamen) für Softwarespeicher.

1. HSM-Mischmoduskonfiguration (empfohlen)

Verwendet HSM für den Keystore (Clientauthentifizierung) und Software für den Truststore.

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

2. Vollständige HSM-Konfiguration

Verwendet HSM für Keystore und Truststore.

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

Umgehung der Validierung zur Bereitstellungszeit

Um die Bereitstellung zu erleichtern, ohne private Schlüssel in die Cassandra-Datenbank von Apigee hochladen zu müssen, umgeht Apigee während der Bereitstellung automatisch die Prüfungen auf die Existenz von Keystore/Truststore in der Umgebung für alle Verweise, die mit dem Präfix hsmref:// beginnen.

Vorgänge: Neue HSM-Keystores/Truststores hinzufügen

So fügen Sie einer vorhandenen aktiven Umgebung einen neuen HSM-Keystore oder -Truststore hinzu:

1. Laden Sie die Schlüssel/Zertifikate in das physische HSM (siehe Keystores/Truststores in HSM laden).
2. Kopieren Sie die neue Keystore-Datendatei auf die Message Processor-Knoten und legen Sie die Inhaberschaft auf apigee fest.
3. Aktualisieren Sie /opt/apigee/hsm-config.properties auf allen Message Processor-Knoten mit dem neuen Verweis:

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

4. Starten Sie den Message Processor auf jedem Knoten neu:

   apigee-service edge-message-processor restart

5. Aktualisieren Sie die API-Proxy-Konfiguration, um hsmref://new_keystore_ref zu verwenden, und stellen Sie sie bereit.

HSM global deaktivieren

So deaktivieren Sie HSM:

1. Aktualisieren Sie alle aktiven Proxys, die hsmref:// verwenden, so dass sie Standardsoftwareverweise (ref://) verwenden.
2. Bearbeiten Sie auf jedem Message Processor-Knoten /opt/apigee/customer/application/message-processor.properties und legen Sie Folgendes fest:

   conf_system_apigee.hsm.enabled=false

3. Konfigurieren Sie den Message Processor neu und starten Sie ihn neu:

   apigee-service edge-message-processor configure

   apigee-service edge-message-processor restart

Einschränkungen und Vorbehalte

• Unterstützte Hardware:Beschränkt auf Entrust nShield 5c-Netzwerk-HSMs.
• Wartung:Kunden sind für die Wartung von HSM-Servern und -Clients verantwortlich.
• Latenz:Aufgrund von Netzwerkverhandlungen mit dem HSM kann es zu zusätzlicher Latenz kommen. Durch die Verwendung des HSM-Mischmodus wird dies bis zu einem gewissen Grad gemildert.
• HSM-Neustart:Wenn der HSM-Hardserver neu gestartet wird, müssen Sie edge-message-processor auf den verbundenen Message Processor-Knoten neu starten.

Keystores/Truststores in HSM laden

Die genauen keytool Befehle, die zum Importieren eines PKCS12-Keystores oder eines PEM-Zertifikats in das HSM erforderlich sind, finden Sie im offiziellen Entrust nShield-Dokumentationsportal.

Damit die Kompatibilität mit Apigee gewährleistet ist, müssen die resultierenden HSM-Keystore-Dateien die folgenden Anforderungen erfüllen:

• Verzeichnis: Muss unter /opt/apigee/ gespeichert werden (z.B. /opt/apigee/hsmks.keystore)
• Berechtigungen: Muss dem Nutzer apigee gehören (chown apigee:apigee /opt/apigee/<filename>)
• Lesbarkeit:Muss vom Dienst edge-message-processor gelesen werden können.

Fehlerreferenz

Rechtliche Hinweise

Entrust und nShield sind Marken oder eingetragene Marken der Entrust Corporation oder ihrer Tochtergesellschaften. Alle anderen Marken sind Eigentum der jeweiligen Inhaber.