Guide d'intégration du module matériel de sécurité en aval pour Apigee Edge for Private Cloud

Version de la version : version du correctif Edge pour le cloud privé v4.53.01.02 et versions ultérieures.

Cette page explique comment configurer des connexions TLS en aval (des processeurs de messages Apigee aux services cibles de backend) à l'aide des modules de sécurité matériels (HSM) réseau Entrust nShield® 5c.

Avis de non-responsabilité concernant les contenus tiers : cette page fournit les étapes de configuration du matériel Entrust nShield en lien avec l'intégration d'Apigee Edge. Ces étapes sont basées sur des modèles d'intégration standards et sont fournies à titre informatif uniquement. Les configurations Entrust peuvent être modifiées par le fabricant. Veuillez consulter le portail de documentation officiel d'Entrust pour obtenir des spécifications faisant autorité, des configurations de sécurité et les exigences matérielles actuelles.

Présentation

Les modules de sécurité matériels (HSM) fournissent un environnement dédié et renforcé pour le stockage sécurisé des clés et les opérations cryptographiques. En intégrant Apigee Edge pour le cloud privé aux HSM Entrust nShield, vous pouvez sécuriser les clés privées utilisées dans les handshakes TLS et mTLS en aval.

Apigee est compatible avec l'intégration HSM pour le trafic HTTPS sortant en aval sur les composants suivants :

• Points de terminaison cibles
• Serveurs cibles
• Règles d'appel de service
• Règles de journalisation des messages
• Règles JavaScript

Prérequis

Avant de configurer l'intégration HSM, assurez-vous que les conditions préalables suivantes sont remplies :

1. Exigences concernant la version du logiciel

• Le cluster Apigee Edge pour le cloud privé doit être exécuté sur la version 4.53.01.02 ou ultérieure.
• L'intégration HSM est incluse de manière native dans les versions RPM suivantes (ou ultérieures) :
  • 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. Configuration de l'infrastructure et du système d'exploitation

• FIPS doit être désactivé sur le système d'exploitation hébergeant le cluster Edge pour le cloud privé.
• Le client HSM et Security World doivent être installés et configurés sur tous les nœuds du processeur de messages.
• Important : Ces étapes doivent être effectuées par l'utilisateur apigee.

Vérifiez que l'installation du client HSM est correctement configurée et accessible par l'utilisateur apigee en exécutant le test d'installation standard JCA/JCE CSP fourni dans la documentation officielle d'Entrust nShield. Assurez-vous que ce test se termine correctement sur tous les nœuds du processeur de messages.

Configurations compatibles

Vous pouvez configurer Apigee pour qu'il utilise HSM de deux manières :

1. Mode mixte HSM (recommandé)

Dans ce mode, seules les clés privées (KeyStore) sont stockées dans le HSM, tandis que les certificats approuvés (TrustStore) restent dans les magasins de logiciels Apigee standards.

2. Mode HSM complet

Dans ce mode, le KeyStore (clés privées) et le TrustStore (certificats approuvés) sont stockés dans le HSM. Ce mode est compatible, mais il peut introduire une latence supplémentaire.

Étape 1 : Activer le HSM sur les processeurs de messages

Effectuez ces étapes sur chaque nœud du processeur de messages, un à la fois :

1. Arrêter le processeur de messages

apigee-service edge-message-processor stop

2. Vérifier le fichier de données du keystore HSM

Assurez-vous que le fichier de données du keystore HSM (qui fait référence aux clés chargées dans le HSM) est présent sur le nœud du processeur de messages et qu'il appartient à l'utilisateur apigee :

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

3. Créer le fichier de configuration HSM

Créez ou mettez à jour le fichier de configuration dans /opt/apigee/hsm-config.properties. Définissez l'emplacement et les mots de passe des keystores HSM et (facultativement) des truststores.

Exemple de configuration (compatible avec les proxys HSM mixtes et complets) :

# 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

Définissez les autorisations appropriées :

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

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

4. Configurer les propriétés du processeur de messages

Créez ou modifiez /opt/apigee/customer/application/message-processor.properties et ajoutez les éléments suivants :

# 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

Assurez-vous que la propriété est correcte :

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

5. Reconfigurer et redémarrer

apigee-service edge-message-processor configure

apigee-service edge-message-processor restart

6. Valider l'initialisation

Recherchez les messages d'initialisation réussie dans le journal système /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

Étape 2 : Configurer les proxys d'API

Mettez à jour le bloc SSLInfo dans la configuration du proxy d'API (TargetEndpoint, ServiceCallout ou règles). Utilisez le préfixe hsmref:// pour faire référence aux magasins gérés par HSM, et ref:// (ou le nom de référence standard) pour les magasins de logiciels.

1. Configuration du mode mixte HSM (recommandé)

Utilise HSM pour le KeyStore (authentification du client) et le logiciel pour le TrustStore.

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

2. Configuration HSM complète

Utilise HSM pour le KeyStore et le TrustStore.

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

Contournement de la validation au moment du déploiement

Pour faciliter le déploiement sans importer de clés privées dans la base de données Cassandra d'Apigee, Apigee contourne automatiquement les vérifications d'existence du keystore/truststore de l'environnement lors du déploiement pour toute référence commençant par le préfixe hsmref://.

Opérations : Ajouter de nouveaux keystores/truststores HSM

Pour ajouter un nouveau keystore ou truststore HSM à un environnement d'exécution existant :

1. Chargez les clés/certificats dans le HSM physique (consultez Charger des keystores/truststores dans le HSM).
2. Copiez le nouveau fichier de données du keystore dans les nœuds du processeur de messages et définissez la propriété sur apigee.
3. Mettez à jour /opt/apigee/hsm-config.properties sur tous les nœuds du processeur de messages avec la nouvelle référence :

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

4. Redémarrez le processeur de messages sur chaque nœud :

   apigee-service edge-message-processor restart

5. Mettez à jour la configuration du proxy d'API pour utiliser le nouveau hsmref://new_keystore_ref et déployez-le.

Désactiver le HSM de manière globale

Pour désactiver le HSM :

1. Mettez à jour tous les proxys actifs à l'aide de hsmref:// pour utiliser des références logicielles standards (ref://).
2. Sur chaque nœud du processeur de messages, modifiez /opt/apigee/customer/application/message-processor.properties et définissez :

   conf_system_apigee.hsm.enabled=false

3. Reconfigurez et redémarrez le processeur de messages :

   apigee-service edge-message-processor configure

   apigee-service edge-message-processor restart

Limites et mises en garde

• Matériel compatible : limité aux HSM réseau Entrust nShield 5c.
• Maintenance : les clients sont responsables de la maintenance du serveur/client HSM.
• Latence : une latence supplémentaire peut se produire en raison des négociations réseau avec le HSM. L'utilisation du mode mixte HSM atténue ce problème dans une certaine mesure.
• Redémarrage du HSM : si le serveur HSM redémarre, vous devez redémarrer edge-message-processor sur les nœuds du processeur de messages connectés.

Charger des keystores/truststores dans le HSM

Consultez le portail de documentation officiel d'Entrust nShield pour connaître les commandes keytool exactes requises pour importer un keystore PKCS12 ou un certificat PEM dans le HSM.

Pour garantir la compatibilité avec Apigee, les fichiers de keystore HSM résultants doivent répondre aux exigences suivantes :

• Répertoire : doit être enregistré dans /opt/apigee/ (par exemple, /opt/apigee/hsmks.keystore)
• Autorisations : doit appartenir à l'utilisateur apigee (chown apigee:apigee /opt/apigee/<filename>)
• Lisibilité : doit être lisible par le service edge-message-processor.

Informations de référence sur les erreurs

Mentions légales

Entrust et nShield sont des marques ou des marques déposées d'Entrust Corporation ou de ses sociétés affiliées. Toutes les autres marques appartiennent à leurs propriétaires respectifs.