Créer des keystores et des magasins de confiance à l'aide de l'interface utilisateur Edge

Vous consultez la documentation Apigee Edge.
Accédez à la documentation Apigee X.

Ce document explique comment créer, modifier et supprimer des keystores et des truststores pour Edge pour le cloud et pour Edge pour le Private Cloud versions 4.18.01 et ultérieures.

À propos des keystores/truststores et des hôtes virtuels pour Edge Cloud

Pour créer des keystores/truststores pour Edge Cloud, vous devez respecter toutes les règles concernant l'utilisation d'hôtes virtuels. Par exemple, avec des hôtes virtuels dans le cloud :

• Les hôtes virtuels doivent utiliser TLS.
• Les hôtes virtuels ne peuvent utiliser que le port 443.
• Vous devez utiliser un certificat TLS signé. Les certificats non signés ne sont pas autorisés pour les hôtes virtuels dans le cloud.
• Le nom de domaine spécifié par le certificat TLS doit correspondre à l'alias d'hôte de l'hôte virtuel.

En savoir plus :

• À propos de TLS/SSL
• Utiliser TLS avec Edge
• Questions fréquentes sur la configuration des hôtes virtuels
• À propos des hôtes virtuels

Implémenter des keystores et des truststores dans Edge

Pour configurer des fonctionnalités qui reposent sur l'infrastructure à clé publique, comme TLS, vous devez créer des keystores et des truststores contenant les clés et les certificats numériques nécessaires.

Dans Edge, les keystores et les truststores sont tous deux représentés par une entité keystore qui contient un ou plusieurs alias. En d'autres termes, il n'existe aucune différence d'implémentation entre un keystore et un truststore sur Edge.

La différence entre les keystores et les truststores provient des types d'entrées qu'ils contiennent et de la manière dont ils sont utilisés dans le handshake TLS :

• keystore : entité keystore contenant un ou plusieurs alias, où chaque alias contient une paire certificat/clé.
• Truststore : entité keystore contenant un ou plusieurs alias, où chaque alias ne contient qu'un certificat.

Lorsque vous configurez TLS pour un hôte virtuel ou un point de terminaison cible, les keystores et les truststores jouent des rôles différents dans le processus d'établissement de liaison TLS. Lorsque vous configurez un hôte virtuel ou un point de terminaison cible, vous spécifiez les keystores et les truststores séparément dans la balise <SSLInfo>, comme indiqué ci-dessous pour un hôte virtuel :

<VirtualHost name="myTLSVHost"> 
    <HostAliases> 
        <HostAlias>apiTLS.myCompany.com</HostAlias> 
    </HostAliases> 
    <Interfaces/> 
    <Port>9006</Port> 
    <SSLInfo> 
        <Enabled>true</Enabled> 
        <ClientAuthEnabled>false</ClientAuthEnabled> 
        <KeyStore>ref://keystoreref</KeyStore> 
        <KeyAlias>myKeyAlias</KeyAlias> 
    </SSLInfo>
</VirtualHost>

Dans cet exemple, vous spécifiez le nom du keystore et l'alias utilisés par l'hôte virtuel pour son keystore TLS. Vous utilisez une référence pour spécifier le nom du keystore afin de pouvoir le modifier ultérieurement lorsque le certificat expirera. L'alias contient une paire certificat/clé utilisée pour identifier l'hôte virtuel auprès d'un client TLS accédant à l'hôte virtuel. Dans cet exemple, aucun truststore n'est requis.

Si un truststore est requis, par exemple pour une configuration TLS bidirectionnelle, utilisez le tag <TrustStore> pour spécifier le truststore :

<VirtualHost name="myTLSVHost"> 
    <HostAliases> 
        <HostAlias>apiTLS.myCompany.com</HostAlias> 
    </HostAliases> 
    <Interfaces/> 
    <Port>9006</Port> 
    <SSLInfo> 
        <Enabled>true</Enabled> 
        <ClientAuthEnabled>true</ClientAuthEnabled> 
        <KeyStore>ref://keystoreref</KeyStore> 
        <KeyAlias>myKeyAlias</KeyAlias> 
        <TrustStore>ref://truststoreref</TrustStore>
    </SSLInfo>
</VirtualHost>

Dans cet exemple, la balise <TrustStore> ne fait référence qu'à un keystore et ne spécifie pas d'alias particulier. Chaque alias du keystore contient un certificat ou une chaîne de certificats qui est utilisé dans le processus d'établissement de liaison TLS.

Formats de certificat acceptés

* Nous vous recommandons d'utiliser PEM si possible.

Utiliser des keystores PKCS12 avec Edge pour le cloud privé 4.53.00 ou version ultérieure

Si vous utilisez Edge pour le cloud privé 4.53.00 ou version ultérieure, vous ne devez utiliser qu'un keystore PKCS12 pour importer des clés et des certificats associés dans Apigee. Pour obtenir de l'aide concernant la conversion de vos clés et certificats existants au format PKCS12/PFX, consultez Convertir des certificats au format compatible.

À propos de l'implémentation d'un alias

Sur Edge, un keystore contient un ou plusieurs alias, où chaque alias contient :

• Certificat TLS au format PEM ou PKCS12/PFX : il peut s'agir d'un certificat signé par une autorité de certification (CA), d'un fichier contenant une chaîne de certificats dont le dernier est signé par une autorité de certification ou d'un certificat autosigné.
• Clé privée sous forme de fichier PEM ou PKCS12/PFX. Edge accepte les clés d'une taille maximale de 2 048 bits. Une phrase secrète est facultative.

Sur Edge, un truststore contient un ou plusieurs alias, où chaque alias contient :

• Certificat TLS au format PEM : il peut s'agir d'un certificat signé par une autorité de certification (CA), d'une chaîne de certificats dont le dernier est signé par une CA ou d'un certificat autosigné.

Edge fournit une UI et une API que vous utilisez pour créer des keystores, des alias, importer des paires certificat/clé et mettre à jour des certificats. L'UI et l'API que vous utilisez pour créer un truststore sont les mêmes que celles que vous utilisez pour créer un keystore. La différence est que, lorsque vous créez un truststore, vous créez des alias qui ne contiennent qu'un certificat.

À propos du format des fichiers de certificat et de clé

Vous pouvez représenter les certificats et les clés sous forme de fichiers PEM ou PKCS12/PFX. Les fichiers PEM sont conformes au format X.509. Si votre certificat ou votre clé privée ne sont pas définis par un fichier PEM, vous pouvez les convertir en fichier PEM à l'aide d'utilitaires tels que openssl.

Toutefois, de nombreux fichiers .crt et .key sont déjà au format PEM. Si ces fichiers sont des fichiers texte et sont inclus dans :

-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----

ou :

-----BEGIN ENCRYPTED PRIVATE KEY-----
-----END ENCRYPTED PRIVATE KEY-----

Les fichiers sont alors compatibles avec le format PEM et vous pouvez les utiliser dans un keystore ou un truststore sans les convertir au format PEM.

À propos des chaînes de certificats

Si un certificat fait partie d'une chaîne, vous le gérez différemment selon qu'il est utilisé dans un keystore ou un truststore :

• Keystore : si un certificat fait partie d'une chaîne, vous devez créer un fichier unique contenant tous les certificats de la chaîne. Les certificats doivent être dans l'ordre et le dernier certificat doit être un certificat racine ou un certificat intermédiaire signé par un certificat racine.
• Truststore : si un certificat fait partie d'une chaîne, vous devez soit créer un fichier unique contenant tous les certificats et l'importer dans un alias, soit importer séparément tous les certificats de la chaîne dans le truststore à l'aide d'un alias différent pour chaque certificat. Si vous les importez en tant que certificat unique, les certificats doivent être dans l'ordre et le dernier certificat doit être un certificat racine ou un certificat intermédiaire signé par un certificat racine.
• Si vous créez un fichier unique contenant plusieurs certificats, vous devez insérer une ligne vide entre chaque certificat.

Par exemple, vous pouvez combiner tous les certificats dans un seul fichier PEM. Les certificats doivent être dans l'ordre et le dernier certificat doit être un certificat racine ou un certificat intermédiaire signé par un certificat racine :

-----BEGIN CERTIFICATE----- 
(Your Primary TLS certificate) 
-----END CERTIFICATE----- 

-----BEGIN CERTIFICATE----- 
(Intermediate certificate) 
-----END CERTIFICATE-----
 
-----BEGIN CERTIFICATE----- 
(Root certificate or intermediate certificate signed by a root certificate) 
-----END CERTIFICATE-----

Si vos certificats sont représentés sous forme de fichiers PKCS12/PFX, vous pouvez utiliser la commande openssl pour créer un fichier PKCS12/PFX à partir d'une chaîne de certificats, comme indiqué ci-dessous :

openssl pkcs12 -export -out certificate.pfx -inkey privateKey.key -in certificate.crt -certfile CACert.crt

Lorsque vous utilisez des chaînes de certificats dans un truststore, vous n'avez pas toujours besoin d'importer tous les certificats de la chaîne. Par exemple, vous importez un certificat client, client_cert_1, et le certificat de l'émetteur du certificat client, ca_cert.

Lors de l'authentification TLS bidirectionnelle, l'authentification du client réussit lorsque le serveur envoie client_cert_1 au client dans le cadre du processus de handshake TLS.

Vous pouvez également utiliser un deuxième certificat, client_cert_2, signé par le même certificat, ca_cert. Toutefois, vous n'importez pas client_cert_2 dans le truststore. Le truststore ne contient toujours que client_cert_1 et ca_cert.

Lorsque le serveur transmet client_cert_2 lors du handshake TLS, la requête aboutit. En effet, Edge autorise la validation TLS lorsque client_cert_2 n'existe pas dans le truststore, mais a été signé par un certificat qui existe dans le truststore. Si vous supprimez le certificat CA, ca_cert, du truststore, la validation TLS échoue.

Remarques concernant la norme FIPS

Si vous utilisez Edge pour le cloud privé 4.53.00 ou version ultérieure sur un système d'exploitation compatible FIPS, vous ne devez utiliser qu'un keystore PKCS12 pour importer des clés et des certificats associés dans Apigee.

Explorer la page "TLS Keystores"

La page "TLS Keystores" (Keystores TLS) s'affiche :

Comme le montre la figure précédente, la page "Magasins de clés TLS" vous permet d'effectuer les opérations suivantes :

• Sélectionnez un environnement
• Créer un keystore et un alias
• Tester et supprimer les keystores
• Afficher et supprimer les alias

Afficher un alias

Pour afficher un alias :

1. Accédez à la page "TLS Keystores" (Keystores TLS).
2. Sélectionnez l'environnement (généralement prod ou test).
3. Cliquez sur la ligne associée à l'alias que vous souhaitez afficher.

   Les détails du certificat et de la clé de l'alias s'affichent.
   
   Vous pouvez consulter toutes les informations sur l'alias, y compris la date d'expiration.

4. Gérez le certificat à l'aide des boutons en haut de la page pour :
   • Téléchargez le certificat au format PEM.
   • Générez une CSR. Si votre certificat a expiré et que vous souhaitez le renouveler, vous pouvez télécharger une demande de signature de certificat (CSR). Vous envoyez ensuite la CSR à votre AC pour obtenir un nouveau certificat.
   • Mettre à jour un certificat Attention : Si vous mettez à jour un certificat actuellement utilisé par un hôte virtuel ou un serveur cible/point de terminaison cible, vous devez contacter l'assistance Apigee Edge pour redémarrer les routeurs et les processeurs de messages. La méthode recommandée pour mettre à jour un certificat est la suivante :
     1. Créez un keystore ou un truststore.
     2. Ajoutez le nouveau certificat au nouveau keystore ou truststore.
     3. Mettez à jour la référence dans l'hôte virtuel ou le serveur cible/point de terminaison cible vers le keystore ou le truststore. Pour en savoir plus, consultez Mettre à jour un certificat TLS pour le cloud.
     4. Supprimez l'alias. Remarque : Si vous supprimez un alias actuellement utilisé par un hôte virtuel ou un point de terminaison cible, l'hôte virtuel ou le point de terminaison cible échoueront.

Créer un keystore/truststore et un alias

Vous pouvez créer un keystore à utiliser comme keystore TLS ou comme truststore TLS. Un keystore est spécifique à un environnement de votre organisation, par exemple l'environnement de test ou de production. Par conséquent, si vous souhaitez tester le keystore dans un environnement de test avant de le déployer dans votre environnement de production, vous devez le créer dans les deux environnements.

Pour créer un keystore dans un environnement, il vous suffit de spécifier son nom. Après avoir créé un keystore nommé dans un environnement, vous pouvez créer des alias et importer une paire certificat/clé (keystore) ou un certificat uniquement (truststore) dans l'alias.

Pour créer un keystore :

1. Accédez à la page "TLS Keystores" (Keystores TLS).
2. Sélectionnez l'environnement (généralement prod ou test).
3. Cliquez sur + Keystore.
4. Spécifiez le nom du keystore. Le nom ne peut contenir que des caractères alphanumériques.
5. Cliquez sur Add Keystore (Ajouter un keystore). Le nouveau keystore apparaît dans la liste.
6. Suivez l'une des procédures suivantes pour ajouter un alias. Consultez également Formats de fichiers de certificat acceptés.
   • Créer un alias à partir d'un certificat (truststore uniquement)
   • Créer un alias à partir d'un fichier JAR (keystore uniquement)
   • Créer un alias à partir d'un certificat et d'une clé (keystore uniquement)
   • Créer un alias à partir d'un fichier PKCS12/PFX (keystore uniquement)
   • Créer un alias à partir d'un certificat autosigné (keystore uniquement)

Créer un alias à partir d'un certificat (truststore uniquement)

Pour créer un alias à partir d'un certificat :

1. Accédez à la page "TLS Keystores" (Keystores TLS).
2. Placez le curseur sur le keystore pour afficher le menu d'actions, puis cliquez sur +.
3. Spécifiez le nom de l'alias.
4. Sous "Détails du certificat", sélectionnez Certificat uniquement dans le menu déroulant "Type".
5. Cliquez sur Sélectionner un fichier à côté de Fichier de certificat, accédez au fichier PEM contenant le certificat, puis cliquez sur Ouvrir.
6. Par défaut, l'API vérifie que le certificat n'a pas expiré. Si vous le souhaitez, sélectionnez Autoriser un certificat expiré pour ignorer la validation.
7. Sélectionnez Enregistrer pour importer le certificat et créer l'alias.

Créer un alias à partir d'un fichier JAR (keystore uniquement)

Pour créer un alias à partir d'un fichier JAR :

1. Accédez à la page "TLS Keystores" (Keystores TLS).
2. Placez le curseur sur le keystore pour afficher le menu d'actions, puis cliquez sur +.
3. Spécifiez le nom de l'alias.
4. Sous "Détails du certificat", sélectionnez Fichier JAR dans le menu déroulant "Type".
5. Cliquez sur Choisir le fichier à côté de Fichier JAR, accédez au fichier JAR contenant le certificat et la clé, puis cliquez sur Ouvrir.
6. Si la clé est protégée par un mot de passe, spécifiez-le dans le champ Mot de passe. Si la clé n'est pas protégée par un mot de passe, laissez ce champ vide.
7. Par défaut, l'API vérifie que le certificat n'a pas expiré. Si vous le souhaitez, sélectionnez Autoriser un certificat expiré pour ignorer la validation.
8. Sélectionnez Enregistrer pour importer la clé et le certificat, et créer l'alias.

Créer un alias à partir d'un certificat et d'une clé (keystore uniquement)

Pour créer un alias à partir d'un certificat et d'une clé :

1. Accédez à la page "TLS Keystores" (Keystores TLS).
2. Placez le curseur sur le keystore pour afficher le menu d'actions, puis cliquez sur +.
3. Spécifiez le nom de l'alias.
4. Sous "Détails du certificat", sélectionnez Certificat et clé dans le menu déroulant "Type".
5. Cliquez sur Sélectionner un fichier à côté de Fichier de certificat, accédez au fichier PEM contenant le certificat, puis cliquez sur Ouvrir.
6. Si la clé est protégée par un mot de passe, spécifiez-le dans le champ Mot de passe de la clé. Si la clé n'est pas protégée par un mot de passe, laissez ce champ vide.
7. Cliquez sur Sélectionner un fichier à côté de Fichier de clé, accédez au fichier PEM contenant la clé, puis cliquez sur Ouvrir.
8. Par défaut, l'API vérifie que le certificat n'a pas expiré. Si vous le souhaitez, sélectionnez Autoriser un certificat expiré pour ignorer la validation.
9. Sélectionnez Enregistrer pour importer la clé et le certificat, et créer l'alias.

Créer un alias à partir d'un fichier PKCS12/PFX (keystore uniquement)

Pour créer un alias à partir d'un fichier PKCS12 contenant le certificat et la clé :

1. Accédez à la page "TLS Keystores" (Keystores TLS).
2. Placez le curseur sur le keystore pour afficher le menu d'actions, puis cliquez sur +.
3. Spécifiez le nom de l'alias.
4. Sous "Détails du certificat", sélectionnez PKCS12/PFX dans le menu déroulant "Type".
5. Cliquez sur Sélectionner un fichier à côté de PKCS12/PFX, accédez au fichier contenant la clé et le certificat, puis cliquez sur Ouvrir.
6. Si la clé est protégée par un mot de passe, spécifiez le mot de passe du fichier PKCS12/PFX. Si la clé n'a pas de mot de passe, laissez ce champ vide.
7. Par défaut, l'API vérifie que le certificat n'a pas expiré. Si vous le souhaitez, sélectionnez Autoriser un certificat expiré pour ignorer la validation.
8. Sélectionnez Enregistrer pour importer le fichier et créer l'alias.

Créer un alias à partir d'un certificat autosigné (keystore uniquement)

Pour créer un alias qui utilise un certificat autosigné, vous devez remplir un formulaire avec les informations nécessaires à la création du certificat. Edge crée ensuite le certificat et une paire de clés privées, puis les importe dans l'alias.

Pour créer un alias à partir d'un certificat autosigné :

1. Accédez à la page "TLS Keystores" (Keystores TLS).
2. Placez le curseur sur le keystore pour afficher le menu d'actions, puis cliquez sur +.
3. Spécifiez le nom de l'alias.
4. Sous "Détails du certificat", sélectionnez Certificat auto-signé dans le menu déroulant "Type".
5. Remplissez le formulaire en utilisant le tableau ci-dessous.
6. Sélectionnez Enregistrer pour créer la paire de clé privée et de certificat, et pour l'importer dans l'alias.

Dans le certificat généré, vous verrez les champs supplémentaires suivants :

• Émetteur
  Entité qui a signé et émis le certificat. Pour un certificat autosigné, il s'agit du CN que vous avez spécifié lors de la création du certificat.
• Validité
  Période de validité du certificat représentée par deux dates : la date de début et la date de fin de la période de validité du certificat. Les deux peuvent être encodés en tant que valeurs UTCTime ou GeneralizedTime.

Le tableau suivant décrit les champs du formulaire :

Tester un keystore ou un truststore

Vous pouvez tester votre truststore et votre keystore dans l'interface utilisateur Edge pour vérifier qu'ils sont correctement configurés. L'interface utilisateur de test valide une requête TLS d'Edge vers un service de backend. Le service de backend peut être configuré pour prendre en charge le protocole TLS unidirectionnel ou bidirectionnel.

Pour tester le protocole TLS unidirectionnel :

1. Accédez à la page "TLS Keystores" (Keystores TLS).
2. Sélectionnez l'environnement (généralement prod ou test).
3. Placez le curseur sur le keystore TLS que vous souhaitez tester pour afficher le menu d'actions, puis cliquez sur Tester. La boîte de dialogue suivante s'affiche et indique le nom du truststore :
   
4. Saisissez le nom d'hôte du service de backend.
5. Saisissez le numéro de port TLS (généralement 443).
6. Vous pouvez également spécifier des protocoles ou des algorithmes de chiffrement.
7. Sélectionnez Tester.

Pour tester le protocole TLS bidirectionnel :

1. Pour le truststore souhaité, sélectionnez le bouton Tester.
2. Dans la boîte de dialogue, sélectionnez Two Way (Bidirectionnel) pour le type de test SSL. La boîte de dialogue suivante s'affiche :
   
3. Spécifiez le nom du keystore utilisé dans le protocole TLS bidirectionnel.
4. Spécifiez le nom de l'alias dans le keystore contenant le certificat et la clé.
5. Saisissez le nom d'hôte du service de backend.
6. Saisissez le numéro de port TLS (généralement 443).
7. Vous pouvez également spécifier des protocoles ou des algorithmes de chiffrement.
8. Sélectionnez Tester.

Ajouter un certificat à un truststore pour le protocole TLS bidirectionnel

Lorsque vous utilisez le protocole TLS bidirectionnel pour les connexions entrantes, c'est-à-dire une requête API dans Edge, le truststore contient un certificat ou une chaîne d'autorité de certification pour chaque client autorisé à envoyer des requêtes à Edge.

Lorsque vous configurez initialement le truststore, vous pouvez ajouter tous les certificats des clients connus. Toutefois, au fil du temps, vous pouvez ajouter d'autres certificats au truststore à mesure que vous ajoutez des clients.

Pour ajouter des certificats à un truststore utilisé pour le protocole TLS bidirectionnel :

1. Assurez-vous d'utiliser une référence au truststore dans l'hôte virtuel.
2. Importez un nouveau certificat dans le truststore, comme décrit ci-dessus dans Créer un alias à partir d'un certificat (truststore uniquement).

3. Mettez à jour la référence du truststore pour définir la même valeur. Cette mise à jour entraîne le rechargement du truststore et du nouveau certificat par Edge.

   Pour en savoir plus, consultez Modifier une référence.

Supprimer un keystore/truststore ou un alias

Vous devez faire preuve de prudence lorsque vous supprimez un keystore/truststore ou un alias. Si vous supprimez un keystore, un truststore ou un alias utilisé par un hôte virtuel, un point de terminaison cible ou un serveur cible, tous les appels d'API via l'hôte virtuel ou le point de terminaison/serveur cible échoueront.

En règle générale, la procédure à suivre pour supprimer un keystore/truststore ou un alias est la suivante :

1. Créez un keystore/truststore ou un alias comme décrit ci-dessus.
2. Pour les connexions entrantes, c'est-à-dire une requête API dans Edge, mettez à jour la configuration de l'hôte virtuel pour faire référence au nouveau keystore et à l'alias de clé.
3. Pour les connexions sortantes, c'est-à-dire d'Apigee vers un serveur de backend :
   1. Mettez à jour la configuration TargetEndpoint pour tous les proxys d'API qui référençaient l'ancien keystore et l'ancien alias de clé afin qu'ils référencent le nouveau keystore et le nouvel alias de clé. Si votre TargetEndpoint fait référence à un TargetServer, mettez à jour la définition TargetServer pour qu'elle fasse référence au nouveau keystore et à l'alias de clé.
   2. Si le keystore et le truststore sont référencés directement à partir de la définition TargetEndpoint, vous devez redéployer le proxy. Si le TargetEndpoint fait référence à une définition TargetServer, et que celle-ci fait référence au keystore et au truststore, aucun redéploiement de proxy n'est nécessaire.
4. Vérifiez que vos proxys d'API fonctionnent correctement.
5. Supprimez le keystore/truststore ou l'alias.

Supprimer un keystore

Pour supprimer un keystore ou un truststore, placez le curseur dessus dans la liste pour afficher le menu d'actions, puis cliquez sur . Si vous supprimez un keystore ou un truststore utilisé par un hôte virtuel ou un point de terminaison/serveur cible, tous les appels d'API via l'hôte virtuel ou le point de terminaison/serveur cible échoueront.

Attention : Vous ne devez pas supprimer un keystore tant que vous n'avez pas converti vos hôtes virtuels et vos points de terminaison cibles/serveurs cibles pour qu'ils utilisent un nouveau keystore.

Supprimer un alias

Pour supprimer un alias, placez le curseur dessus dans la liste pour afficher le menu d'actions, puis cliquez sur . Si vous supprimez un alias utilisé par un hôte virtuel ou un point de terminaison cible/serveur cible, tous les appels d'API via l'hôte virtuel ou le point de terminaison cible/serveur cible échoueront.

Attention : Vous ne devez pas supprimer un alias tant que vous n'avez pas converti vos hôtes virtuels et vos points de terminaison cibles/serveurs cibles pour qu'ils utilisent un nouveau keystore et un nouvel alias.