Créer des keystores et des Truststores à l'aide de l'API de gestion Edge

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

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

Introduction

Pour configurer une fonctionnalité qui repose sur une infrastructure à clé publique, telle que TLS, vous devez créer des keystores et des truststores qui fournissent les clés et les certificats numériques nécessaires.

Pour une introduction aux keystores, aux truststores et aux alias, consultez la section Keystores et truststores.

Créer un keystore

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 :

  1. Utilisez l'appel d'API de cette section pour créer le keystore.
  2. Créez un alias et importez une paire certificat/clé dans l'alias. La façon dont vous importez le certificat et la clé dépend du format de la paire certificat/clé. Les sections suivantes décrivent comment importer chaque type de paire certificat/clé :

Pour créer un keystore, spécifiez son nom dans l'API Créer un keystore ou un truststore. Le nom du keystore ne peut contenir que des caractères alphanumériques :

curl -X POST -u orgAdminEmail:password -H "Content-Type: text/xml" \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores \
-d '<KeyStore name="myKeystore"/>'

Exemple de réponse :

{
  "certs" : [ ],
  "keys" : [ ],
  "name" : "myKeystore"
}

Importer un certificat et une clé en tant que fichier JAR

Vous devez d'abord créer un fichier JAR avec votre clé privée, votre certificat et un fichier manifeste. Le fichier JAR doit contenir les fichiers et répertoires suivants :

/META-INF/descriptor.properties
myCert.pem
myKey.pem

Un fichier JAR de keystore ne peut contenir que ces trois fichiers. Si vous disposez d'une chaîne de certificats, tous les certificats de la chaîne doivent être ajoutés dans un seul fichier PEM, où le dernier certificat doit être signé par une autorité de certification racine. Les certificats doivent être ajoutés au fichier PEM dans le bon ordre, avec une ligne vide entre chaque certificat, ce qui signifie :

cert -> intermediate cert(1) -> intermediate cert(2) -> … -> root

Dans le répertoire contenant votre paire de clés et votre certificat, créez un répertoire nommé /META-INF. Créez ensuite un fichier nommé descriptor.properties dans /META-INF avec le contenu suivant :

certFile={myCertificate}.pem
keyFile={myKey}.pem

Générez le fichier JAR contenant votre paire de clés et votre certificat :

jar -cf myKeystore.jar myCert.pem myKey.pem

Ajoutez descriptor.properties à votre fichier JAR :

jar -uf myKeystore.jar META-INF/descriptor.properties

Vous pouvez maintenant importer vos fichiers JAR contenant un certificat et une clé privée à l'aide de l'API Créer un alias à partir d'un fichier JAR ou PKCS :

curl -u orgAdminEmail:password -X POST -H "Content-Type: multipart/form-data" -F file="@myKeystore.jar" -F password={key_pword} \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases?alias={alias_name}&format=keycertjar"

où l'option -F spécifie le chemin d'accès au fichier JAR.

Dans cet appel, vous spécifiez :

  • alias_name : identifie le certificat et la clé dans le keystore. Lorsque vous créez un hôte virtuel, vous référencez le certificat et la clé par leur nom d'alias.
  • key_pword : mot de passe de la clé privée. Omettez ce paramètre si la clé privée n'a pas de mot de passe.

Vérifiez que votre keystore a été importé correctement :

curl -u orgAdminEmail:password -X GET\
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}

Exemple de réponse :

{  
 "certs" : [ "myCertificate" ],
 "keys" : [ "myKey" ],
 "name" : "myKeystore"
}

Importer un certificat et une clé en tant que fichiers PEM

Importez des fichiers PEM contenant un certificat et une clé privée à l'aide de l'API Créer un alias à partir de fichiers PEM de certificat et de clé :

curl -u orgAdminEmail:password -X POST -H "Content-Type: multipart/form-data" -F keyFile="@server.key" -F certFile="@signed.crt" \
-F password={key_pword} \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases?alias={alias_name}&format=keycertfile"

où l'option -F spécifie les chemins d'accès aux fichiers PEM.

Dans cet appel, vous spécifiez :

  • alias_name : identifie le certificat et la clé dans le keystore. Lorsque vous créez un hôte virtuel, vous référencez le certificat et la clé par leur nom d'alias.
  • key_pword : mot de passe de la clé privée. Omettez ce paramètre si la clé privée n'a pas de mot de passe.

Vérifiez que votre keystore a été importé correctement :

curl -u orgAdminEmail:password -X GET\
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}

Exemple de réponse :

{  
 "certs" : [ "myCertificate" ],
 "keys" : [ "myKey" ],
 "name" : "myKeystore"
}

Importer un certificat et une clé en tant que fichier PKCS12/PFX fichier

Importez un fichier PKCS12/PFX contenant un certificat et une clé privée à l'aide de l'API Créer un alias à partir d'un fichier JAR ou PKCS :

curl -u orgAdminEmail:password -X POST -H "Content-Type: multipart/form-data" \
-F file="@myKeystore.p12" -F password={key_pword} \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases?alias={alias_name}&format=pkcs12"

où l'option -F spécifie le chemin d'accès au fichier P12.

Dans cet appel, vous spécifiez :

  • alias_name : identifie le certificat et la clé dans le keystore. Lorsque vous créez un hôte virtuel, vous référencez le certificat et la clé par leur nom d'alias.
  • key_pword : mot de passe de la clé privée. Omettez ce paramètre si la clé privée n'a pas de mot de passe.

Vérifiez que votre keystore a été importé correctement :

curl -u orgAdminEmail:password -X GET\
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}

Exemple de réponse :

{  
 "certs" : [ "myCertificate" ],
 "keys" : [ "myKey" ],
 "name" : "myKeystore"
}

Créer et importer un certificat et une clé autosignés

Vous pouvez utiliser l'API Créer un alias en générant un certificat autosigné pour créer un certificat et une clé autosignés, puis les importer dans un alias. L'appel suivant ne spécifie que les informations requises pour créer le certificat autosigné. Vous pouvez modifier cet appel pour ajouter des informations supplémentaires :

curl -u orgAdminEmail:password -X POST --header "Content-Type: application/json"  \
-d "{
    "alias": "selfsigned",
    "subject": {
        "commonName": "mycert"
    }
}" \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases?format=selfsignedcert"

La réponse doit se présenter comme suit :

{
  "alias": "selfsigned",
  "certsInfo": {
    "certInfo": [
      {
        "basicConstraints": "CA:FALSE",
        "expiryDate": 1491497204000,
        "isValid": "Yes",
        "issuer": "CN=mycert",
        "publicKey": "RSA Public Key, 2048 bits",
        "serialNumber": "00:d1:b4:78:e1",
        "sigAlgName": "SHA256withRSA",
        "subject": "CN=mycert",
        "subjectAlternativeNames": [],
        "validFrom": 1459961204000,
        "version": 3
      }
    ],
    "certName": "selfsigned-cert"
  },
  "keyName": "selfsigned"
}

Créer un truststore

Les API que vous utilisez pour créer un truststore sont les mêmes que celles utilisées pour créer un keystore. La seule différence est que vous n'importez qu'un fichier de certificat, au format PEM, dans le truststore.

Si le certificat fait partie d'une chaîne, vous devez soit importer séparément tous les certificats de la chaîne dans le truststore, soit créer un fichier unique contenant tous les certificats. Vous devez insérer une ligne vide entre chaque certificat du fichier.

Si vous souhaitez importer plusieurs certificats autosignés qui ne font pas partie d'une chaîne, utilisez la même technique : s'il existe plusieurs certificats auxquels vous souhaitez faire confiance, importez-les dans un seul fichier.

Le certificat final est généralement signé par l'émetteur du certificat. Par exemple, dans le truststore, 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 négociation TLS.

Vous disposez également d'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 contient toujours client_cert_1 et ca_cert.

Lorsque le serveur transmet client_cert_2 dans le cadre de la négociation TLS, la requête aboutit. En effet, Edge autorise la validation TLS à réussir 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 d'autorité de certification , ca_cert, du truststore, la validation TLS échoue.

Créez un truststore vide dans l'environnement à l'aide de l'API Créer un Keystore ou Truststore, la même API que celle que vous utilisez pour créer un keystore :

curl -u orgAdminEmail:password -X POST -H "Content-Type: text/xml" \
-d '<KeyStore name="myTruststore"/>' \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores

Une fois le truststore créé, importez le certificat en tant que fichier PEM dans le truststore en utilisant l' API Créer un alias à partir d'un fichier PEM de certificat :

curl -u orgAdminEmail:password -X POST -H "Content-Type: multipart/form-data" -F certFile="@cert.pem" \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/myTruststore/aliases?alias=myTruststore&format=keycertfile"

où l'option -F spécifie le chemin d'accès au fichier PEM.

Obtenir des détails sur un keystore ou un truststore existant

Vérifiez si des keystores existent dans votre environnement à l'aide de l'API Répertorier les keystores et les truststores :

curl -u orgAdminEmail:password -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores

Pour les clients cloud, un keystore par défaut est fourni pour les organisations d'essai sans frais dans les environnements de test et de production. Les résultats suivants devraient s'afficher pour cet appel dans les deux environnements :

[ "freetrial" ]

Vous pouvez utiliser ce keystore par défaut pour tester vos API et les déployer en production, mais vous créez généralement votre propre keystore, avec votre propre certificat et votre propre clé, avant de déployer en production.

Pour les clients du cloud privé, le tableau renvoyé est vide jusqu'à ce que vous créiez votre premier keystore.

Vérifiez le contenu du keystore à l'aide de l'API Obtenir un keystore ou un truststore. Pour un client cloud, vous devriez voir un seul certificat TLS de serveur : le certificat par défaut qu'Apigee Edge fournit pour les comptes d'essai sans frais.

curl -u orgAdminEmail:password -X GET\
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/freetrial

La réponse doit se présenter comme suit :

{
 "certs" : [ "wildcard.apigee.net.crt" ],
 "keys" : [ "freetrial" ],
 "name" : "freetrial"
}

Obtenir des détails sur un alias

Obtenez la liste de tous les alias d'un keystore à l'aide de l'API Répertorier les alias :

curl -u orgAdminEmail:password -X GET \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases"

La réponse doit se présenter comme suit :

[
  "alias1",
  "alias2",
  "alias3",
]

Pour obtenir toutes les informations sur un alias, telles que la date d'expiration et l'émetteur, utilisez l'API Obtenir un alias et spécifiez le nom de l'alias :

curl  -u orgAdminEmail:password -X GET \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases/{alias_name}"

La réponse doit se présenter comme suit :

{
  "alias": "alias1",
  "certsInfo": {
    "certInfo": [
      {
        "basicConstraints": "CA:TRUE",
        "expiryDate": 1459371335000,
        "isValid": "No",
        "issuer": "EMAILADDRESS=foo@bar.com, CN=smg, OU=doc, O=Internet Widgits Pty Ltd, L=noho, ST=Some-State, C=AU",
        "publicKey": "RSA Public Key, 1024 bits",
        "serialNumber": "00:86:a0:9b:5b:91:a9:fe:92",
        "sigAlgName": "SHA256withRSA",
        "subject": "EMAILADDRESS=foo@bar.com, CN=smg, OU=doc, O=Internet Widgits Pty Ltd, L=noho, ST=Some-State, C=AU",
        "subjectAlternativeNames": [],
        "validFrom": 1456779335000,
        "version": 3
      }
    ],
    "certName": "new\-cert"
  },
  "keyName": "newssl20"
}

Pour télécharger le certificat d'un alias, utilisez l'API Exporter un certificat pour un alias :

curl -u orgAdminEmail:password -X GET \
"https://api.enterprise.apigee.com/v1/e/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases/{alias_name}/certificate"

La réponse doit se présenter comme suit :

-----BEGIN CERTIFICATE-----
MIIDojCCAwugAwIBAgIJAIagm1uRqf6SMA0GCSqGSIb3DQEBCwUAMIGTMQswCQYD
...
RBUkaTe/570sLHY0tvkIm5tEX36ESw==
-----END CERTIFICATE-----

Si vous disposez d'un certificat 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 autorité de certification pour obtenir un nouveau certificat. Pour générer une CSR pour un alias, utilisez l'API Générer une CSR pour un alias :

curl -u orgAdminEmail:password -X GET \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases/{alias_name}/csr"

La réponse doit se présenter comme suit :

-----BEGIN CERTIFICATE REQUEST-----
MIIB1DCCAT0CAQAwgZMxCzAJBgNVBAYTAkFVMRMwEQYDVQQIEwpTb21lLVN0YXRl
...
RF5RMytbkxkvPxIE17mDKJH0d8aekv/iEOItZ+BtQg+EibMUkkjTzQ==
-----END CERTIFICATE REQUEST-----

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és 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 de nouveaux clients.

Pour ajouter de nouveaux 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 la section Créer un truststore.

  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 la section 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 cible/serveur cible échoueront.

En règle générale, le processus que vous utilisez pour supprimer un keystore/truststore ou un alias est le suivant :

  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 référencer le nouveau keystore et l'alias de clé.
  3. Pour les connexions sortantes, c'est-à-dire d'Apigee vers un serveur 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 de référencer le nouveau keystore et le nouvel alias de clé. Si votre TargetEndpoint référence un TargetServer, mettez à jour la définition TargetServer pour référencer le nouveau keystore et le nouvel 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 référence une définition TargetServer, et que la définition TargetServer référence le keystore et le truststore, aucun redéploiement de proxy n'est nécessaire.
    3. Vérifiez que vos proxys d'API fonctionnent correctement.
    4. Supprimez le keystore/truststore ou l'alias.

Pour en savoir plus, consultez la section Mettre à jour le certificat dans un alias.

Supprimer un keystore ou un truststore

Vous pouvez supprimer un keystore ou un truststore à l'aide de l'API Supprimer un keystore ou un truststore :

curl -u orgAdminEmail:password -X DELETE \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/myKeystoreName

Si vous supprimez et recréez un keystore ou un truststore utilisé par un hôte virtuel, alors vous devez redéployer vos proxys d'API.

Supprimer un alias

Vous pouvez supprimer un alias dans un keystore ou un truststore à l'aide de l'API Supprimer un alias :

curl -u orgAdminEmail:password -X DELETE \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/myKeystoreName/aliases/{alias_name}