Vous consultez la documentation Apigee Edge.
Accéder à la documentation d'Apigee X en savoir plus
Ce document explique comment créer, modifier et supprimer des keystores et des magasins de confiance pour Edge pour le cloud et Edge pour le cloud privé version 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 obtenir une présentation des keystores, des Truststores et des 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, procédez comme suit:
- Utilisez l'appel d'API dans cette section pour créer le keystore.
- Créez un alias et importez une paire certificat/clé dans l'alias. La manière 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 le nom du keystore 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 peut contenir uniquement 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 et séparés par une ligne vide, ce qui signifie que:
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. Ensuite, créez 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 Create an alias from a JAR or PKCS file (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 magasin de clés. Lorsque vous créez un hôte virtuel, vous référencez le certificat et la clé par son 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é correctement importé:
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é sous forme de fichiers PEM
Importez des fichiers PEM contenant un certificat et une clé privée à l'aide de l'API Créer un alias à partir des 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 magasin de clés. Lorsque vous créez un hôte virtuel, vous référencez le certificat et la clé par son 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é correctement importé:
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
Importez un fichier PKCS12/PFX contenant un certificat et une clé privée à l'aide de l'API Create an alias from a JAR or PKCS file (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 magasin de clés. Lorsque vous créez un hôte virtuel, vous référencez le certificat et la clé par son 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é correctement importé:
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 s'afficher 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 réside dans le fait que vous n'importez qu'un fichier de certificat, au format PEM, dans le Trustedstore.
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 Trustedstore, 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: si vous souhaitez approuver plusieurs certificats, 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.
Au cours 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 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 Trustedstore contient toujours client_cert_1 et ca_cert.
Lorsque le serveur transmet client_cert_2 dans le cadre d'un handshake TLS, la requête aboutit. En effet, Edge permet à la validation TLS de réussir lorsque client_cert_2 n'existe pas dans le truststore, mais qu'il a été signé par un certificat qui existe dans le truststore. Si vous supprimez le certificat CA (ca_cert) du Truststore, la validation TLS échouera.
Créez un Truststore vide dans l'environnement en utilisant Créer un keystore ou un 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
Après avoir créé le Truststore, importez le certificat en tant que fichier PEM dans le Truststore à l'aide de 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 informations sur un keystore ou un magasin de confiance existant
Vérifiez que votre environnement ne contient pas de keystores existants à l'aide de l'API Lister 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 bénéficiant d'un essai sans frais dans les environnements de test et de production. Vous devriez obtenir les résultats suivants pour cet appel pour les deux environnements:
[ "freetrial" ]
Vous pouvez utiliser ce keystore par défaut pour tester vos API et les déployer en production, mais vous devez généralement créer votre propre keystore, avec votre propre certificat et votre propre clé, avant de le déployer en production.
Pour les clients Private Cloud, 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 Get a Keystore ou Truststore. Pour un client cloud, vous devriez voir un certificat TLS de serveur unique : le certificat par défaut fourni par Apigee Edge 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 s'afficher comme suit:
{
"certs" : [ "wildcard.apigee.net.crt" ],
"keys" : [ "freetrial" ],
"name" : "freetrial"
}
Obtenir des informations sur un alias
Obtenez la liste de tous les alias d'un keystore à l'aide de l'API List pseudonymes:
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 s'afficher 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 Get 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 s'afficher 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 s'afficher comme suit:
-----BEGIN CERTIFICATE----- MIIDojCCAwugAwIBAgIJAIagm1uRqf6SMA0GCSqGSIb3DQEBCwUAMIGTMQswCQYD ... RBUkaTe/570sLHY0tvkIm5tEX36ESw== -----END CERTIFICATE-----
Si votre certificat est arrivé à expiration et que vous souhaitez le renouveler, vous pouvez télécharger une demande de signature de certificat. Vous envoyez ensuite la demande de signature de certificat à votre autorité de certification pour obtenir un nouveau certificat. Pour générer une requête de signature de certificat pour un alias, utilisez l'API Générer une requête de signature de certificat 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 s'afficher 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 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.
Lors de la configuration initiale du Truststore, vous pouvez ajouter tous les certificats des clients connus. Toutefois, au fil du temps, vous souhaiterez peut-être ajouter des certificats supplémentaires au truststore à mesure que vous ajoutez de nouveaux clients.
Pour ajouter de nouveaux certificats à un Truststore utilisé pour le protocole TLS bidirectionnel:
- Assurez-vous d'utiliser une référence au truststore dans l'hôte virtuel.
- Importez un nouveau certificat dans le Trustedstore comme décrit ci-dessus dans la section Créer un Truststore.
Mettez à jour la référence du Trustedstore pour la définir sur la même valeur. Cette mise à jour oblige Edge à actualiser le Truststore et le nouveau certificat.
Pour en savoir plus, consultez la section Modifier une référence.
Supprimer un keystore/un truststore ou un alias
Vous devez faire preuve de prudence lorsque vous supprimez un keystore/un 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/le serveur cible échoueront.
En règle générale, le processus que vous utilisez pour supprimer un keystore/truststore ou un alias se présente comme suit:
- Créez un keystore/un truststore ou un alias comme décrit ci-dessus.
- 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é.
- Pour les connexions sortantes, c'est-à-dire d'Apigee vers un serveur backend :
- Mettez à jour la configuration TargetEndpoint pour tous les proxys d'API faisant référence à l'ancien keystore et à l'alias de clé afin de référencer le nouveau keystore et l'alias de clé. Si votre TargetEndpoint fait référence à un TargetServer, mettez à jour la définition TargetServer pour référencer le nouveau keystore et l'alias de clé.
- Si le keystore et le magasin de confiance sont référencés directement à partir de la définition du TargetEndpoint, vous devez redéployer le proxy. Si le point de terminaison TargetEndpoint fait référence à une définition TargetServer et que la définition TargetServer fait référence au keystore et au magasin de confiance, aucun redéploiement du proxy n'est nécessaire.
- Vérifiez que vos proxys d'API fonctionnent correctement.
- Supprimez le keystore/le truststore ou l'alias.
Pour en savoir plus, consultez Mettre à jour le certificat dans un alias.
Supprimer un keystore ou un magasin de confiance
Vous pouvez supprimer un keystore ou un magasin de clés de confiance à 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 magasin de clés de confiance utilisé par un hôte virtuel, vous devez redéployer vos proxys d'API.
Supprimer un alias
Vous pouvez supprimer un alias dans un keystore ou un magasin de clés de confiance à l'aide de l'API Delete alias (Supprimer l'alias) :
curl -u orgAdminEmail:password -X DELETE \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/myKeystoreName/aliases/{alias_name}