Vous consultez la documentation d'Apigee Edge.
Consultez la
documentation Apigee X. en savoir plus
Ce document explique comment créer, modifier et supprimer des keystores et des Truststores pour Edge for the Private Cloud version 4.17.09 et versions antérieures.
À propos des keystores et des Truststores
Les keystores et les Truststores définissent des dépôts de certificats de sécurité utilisés pour le chiffrement TLS. La principale différence entre les deux réside dans leur utilisation dans le processus de handshake TLS:
- Un keystore contient un certificat TLS et une clé privée permettant d'identifier l'entité lors du handshake TLS.
Avec le protocole TLS unidirectionnel, lorsqu'un client se connecte au point de terminaison TLS sur le serveur, le keystore du serveur présente le certificat du serveur (certificat public) au client. Le client valide ensuite ce certificat auprès d'une autorité de certification, telle que Symantec ou VeriSign.
Avec le protocole TLS bidirectionnel, le client et le serveur gèrent un keystore avec leur propre certificat et leur propre clé privée, utilisés pour l'authentification mutuelle. - Un truststore contient des certificats utilisés pour vérifier les certificats reçus dans le cadre du handshake TLS.
Avec le protocole TLS unidirectionnel, aucun magasin de confiance n'est requis si le certificat est signé par une autorité de certification valide. Si le certificat reçu par un client TLS est signé par une autorité de certification valide, le client envoie une requête à l'autorité de certification pour authentifier le certificat. Un client TLS utilise généralement un Truststore pour valider les certificats autosignés reçus du serveur TLS ou les certificats qui ne sont pas signés par une autorité de certification de confiance. Dans ce scénario, le client remplit son magasin de confiance avec les certificats approuvés. Ensuite, lorsque le client reçoit un certificat de serveur, le certificat entrant est validé par rapport aux certificats dans son Truststore.
Par exemple, un client TLS se connecte à un serveur TLS sur lequel le serveur utilise un certificat autosigné. Comme il s'agit d'un certificat autosigné, le client ne peut pas le valider auprès d'une autorité de certification. Au lieu de cela, le client précharge le certificat autosigné du serveur dans son Truststore. Ensuite, lorsque le client tente de se connecter au serveur, il valide le certificat reçu du serveur à l'aide de son Truststore.
Pour le protocole TLS bidirectionnel, le client TLS et le serveur TLS peuvent tous deux utiliser un magasin de confiance. Un Truststore est requis lors de l'exécution d'une authentification TLS bidirectionnelle lorsque Edge agit en tant que serveur TLS.
Les certificats peuvent être émis par une autorité de certification (CA) ou être autosignés par la clé privée que vous générez. Si vous avez accès à une autorité de certification, suivez les instructions qu'elle vous fournit pour générer des clés et émettre des certificats. Si vous n'avez pas accès à une autorité de certification, vous pouvez générer un certificat autosigné à l'aide de l'un des nombreux outils sans frais disponibles au public, tels qu'Openssl.
Implémenter un keystore et un truststore sur Edge
Sur Edge, un keystore contient un ou plusieurs fichiers JAR, où le fichier JAR contient:
- Certificat TLS sous forme de fichier PEM : certificat signé par une autorité de certification, chaîne de certificats dans laquelle le dernier certificat est signé par une autorité de certification ou certificat autosigné.
- Clé privée sous forme de fichier PEM. Edge prend en charge des tailles de clé allant jusqu'à 2 048 bits. La phrase secrète est facultative.
Un Truststore est semblable à un keystore, sauf qu'il ne contient que des certificats sous forme de fichier PEM, mais pas de clés privées.
Si le certificat fait partie d'une chaîne, le keystore/truststore doit contenir tous les certificats de la chaîne, qu'il s'agisse de fichiers PEM individuels ou d'un fichier unique. Si vous n'utilisez qu'un seul fichier, les certificats doivent être dans l'ordre où le premier certificat du fichier est le certificat utilisé pour TLS, suivi de la chaîne de certificats, dans l'ordre, jusqu'au certificat CA. Vous devez insérer une ligne vide entre chaque certificat du fichier.
Edge fournit une API que vous utilisez pour créer des keystores et des Truststores. Les API proprement dites sont identiques. La différence est que lorsque vous créez un keystore, vous transmettez un fichier JAR contenant le certificat et la clé privée. Lorsque vous créez un Truststore, vous ne transmettez le certificat que sous la forme d'un fichier PEM.
À propos du format des fichiers de certificat et de clé
Les exemples de ce document présentent la clé et le certificat TLS définis sous forme de fichiers PEM, qui sont conformes au format X.509. Si votre certificat ou votre clé privée n'est pas défini par un fichier PEM, vous pouvez le convertir en fichier PEM à l'aide d'utilitaires tels qu'openssl.
Toutefois, de nombreux fichiers .crt et .key sont déjà au format PEM. Si ces fichiers sont des fichiers texte et sont entourés:
-----BEGIN CERTIFICATE----- -----END CERTIFICATE-----
ou :
-----BEGIN ENCRYPTED PRIVATE KEY----- -----END ENCRYPTED PRIVATE KEY-----
Les fichiers sont ensuite compatibles avec le format PEM, et vous pouvez les utiliser dans un keystore ou un magasin de clés de confiance sans les convertir en fichier PEM.
Si vous disposez d'une chaîne de certificats et que vous souhaitez l'utiliser dans un keystore ou un Truststore, vous pouvez combiner tous les certificats dans un seul fichier PEM avec une nouvelle ligne entre chaque certificat. Les certificats doivent être en ordre, et le dernier 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-----
Obtenir des informations sur un keystore existant
Recherchez les éventuels keystores existants dans votre environnement à l'aide de l'API List Keystores and Truststores:
curl -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores \
-u email:password
Pour les clients Cloud, un keystore par défaut est fourni aux organisations bénéficiant d'un essai sans frais dans les environnements de test et de production. Les résultats suivants doivent s'afficher 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 créez généralement 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 or Truststore (Obtenir un keystore ou un Truststore). Pour un client cloud, vous devez voir un seul certificat TLS de serveur. Il s'agit du certificat par défaut fourni par Apigee Edge pour les comptes d'essai sans frais.
curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/freetrial \
-u email:password
La réponse doit se présenter comme suit:
{
"certs" : [ "wildcard.apigee.net.crt" ],
"keys" : [ "freetrial" ],
"name" : "freetrial"
}
Vous pouvez également afficher ces informations dans l'interface utilisateur de gestion Edge:
- Connectez-vous à l'interface utilisateur de gestion Edge à l'adresse https://enterprise.apigee.com (cloud) ou
http://<ms-ip>:9000(sur site), où<ms-ip>correspond à l'adresse IP du nœud du serveur de gestion. - Dans le menu de l'interface utilisateur de gestion Edge, sélectionnez Admin > Certificats TLS.
Obtenir les détails du certificat TLS
Vous pouvez utiliser l'API Get Cert Details from a Keystore ou Truststore pour afficher les détails des certificats TLS dans le keystore, tels que la date d'expiration et l'émetteur. Commencez par obtenir le nom du certificat qui vous intéresse. Cet exemple extrait des informations pour le keystore appelé "freetrial".
curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/freetrial \
-u email:password
Exemple de réponse :
{
"certs" : [ "wildcard.apigee.net.crt" ],
"keys" : [ "freetrial" ],
"name" : "freetrial"
}
Utilisez ensuite la valeur de la propriété certs pour obtenir les détails du certificat:
curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/freetrial/certs/wildcard.apigee.net.crt \
-u email:password
Exemple de réponse :
{
"certInfo" : [ {
"expiryDate" : "Wed, 23 Apr 2014 20:50:02 UTC",
"isValid" : "Yes",
"issuer" : "CN=Go Daddy Secure Certificate Authority - G2, OU=http://certs.godaddy.com/repository/, O="GoDaddy.com, Inc.", L=Scottsdale, ST=Arizona, C=US",
"subject" : CN=*.example.apigee.net, OU=Domain Control Validated",
"subjectAlternativeNames" : ["*.example.apigee.net","*.example.apigee.net" ],
"validFrom" : "Tue, 15 Apr 2014 09:17:03 UTC",
"version" : 3
} ],
"name" : "example.apigee.net.crt"
}
Vous pouvez également afficher ces informations dans l'interface utilisateur de gestion Edge:
- Connectez-vous à l'interface utilisateur de gestion Edge à l'adresse https://enterprise.apigee.com (cloud) ou
http://<ms-ip>:9000(sur site), où<ms-ip>correspond à l'adresse IP du nœud du serveur de gestion. - Dans le menu de l'interface utilisateur de gestion Edge, sélectionnez Admin > Certificats TLS.
Dans l'interface utilisateur Edge, vous pouvez spécifier le délai à l'avance indiqué par Edge qu'un certificat va expirer. Par défaut, l'interface utilisateur met en évidence les certificats qui doivent expirer dans les 10 prochains jours.
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.
La création d'un keystore s'effectue en deux étapes:
- Créez un fichier JAR contenant votre certificat et votre clé privée.
- Créez le keystore et importez le fichier JAR.
Créer un fichier JAR contenant votre certificat et votre clé privée
Créez 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
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 descripteur.properties à votre fichier JAR:
jar -uf myKeystore.jar META-INF/descriptor.properties
Créer le keystore et importer le fichier JAR
Pour créer un keystore dans un environnement, il vous suffit de spécifier son nom dans l'API Create a Keystore or Truststore (Créer un keystore ou un Truststore). Le nom ne peut contenir que des caractères alphanumériques:
curl -X POST -H "Content-Type: text/xml" \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores \
-d '<KeyStore name="myKeystore"/>' -u email:password
Exemple de réponse :
{
"certs" : [ ],
"keys" : [ ],
"name" : "myKeystore"
}
Après avoir créé un keystore nommé dans un environnement, vous pouvez importer vos fichiers JAR contenant un certificat et une clé privée à l'aide de l'API Upload a JAR file to a Keystore (Importer un fichier JAR dans un keystore) :
curl -X POST -H "Content-Type: multipart/form-data" \
-F file="@myKeystore.jar" -F password={key_pass} \ "https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/{myKeystore}/keys?alias={key_alias}" \
-u email:password
où l'option -F spécifie le chemin d'accès au fichier JAR.
Dans cet appel, vous spécifiez deux paramètres de requête:
alias: 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.password: mot de passe de la clé privée. Omettez ce paramètre si la clé privée n'est associée à aucun mot de passe.
Vérifiez que votre keystore a été importé correctement:
curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myKeystore \
-u email:password
Exemple de réponse :
{
"certs" : [ "myCertificate" ],
"keys" : [ "myKey" ],
"name" : "myKeystore"
}
Créer un magasin de confiance
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 transmettez le fichier de certificat au format PEM et non au format JAR.
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 en incluant une nouvelle ligne entre chaque certificat du 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 magasin de confiance 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 -X POST -H "Content-Type: text/xml" -d \
'<KeyStore name="myTruststore"/>' \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores \
-u email:password
Importez le certificat sous forme de fichier PEM dans le Truststore à l'aide de l'API Upload a Certificate to a Truststore (Importer un certificat dans un Truststore) :
curl -X POST -H "Content-Type: multipart/form-data" -F file="@trust.pem" \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myTruststore/certs?alias=myTruststore \
-u email:password
où l'option -F spécifie le chemin d'accès au fichier PEM.
Supprimer un keystore ou un magasin de confiance
Vous pouvez supprimer un keystore ou un Truststore à l'aide de l'API Supprimer un keystore ou un Truststore:
curl -X DELETE \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myKeystoreName \
-u email:password
Exemple de réponse :
{
"certs" : [ ],
"keys" : [ ],
"name" : "myKeystoreName"
}
Si vous supprimez un keystore ou un truststore 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/le serveur cible échoueront.