Vous consultez la documentation d'Apigee Edge.
Accédez à la documentation sur Apigee X. info
Ce document explique comment créer, modifier et supprimer des keystores et des truststores pour Edge pour Private Cloud version 4.17.09 et antérieure.
À propos des keystores et des truststores
Les keystores et les truststores définissent les dépôts de certificats de sécurité utilisés pour le chiffrement TLS. La principale différence entre les deux est l'endroit où elles sont utilisées dans le processus d'établissement de la liaison TLS:
- Un keystore contient un certificat TLS et une clé privée utilisés pour identifier l'entité lors du handshake TLS.
Dans le TLS à sens unique, 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 (AC), telle que Symantec ou VeriSign.
Dans le TLS à deux voies, le client et le serveur gèrent tous deux 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 valider les certificats reçus lors du handshake TLS.
Dans le TLS à sens unique, un truststore n'est pas nécessaire 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 truststore avec les certificats qu'il approuve. Ensuite, lorsque le client reçoit un certificat de serveur, le certificat entrant est validé par rapport aux certificats de son truststore.
Par exemple, un client TLS se connecte à un serveur TLS où 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. À la place, le client précharge le certificat autosigné du serveur dans son truststore. Ensuite, lorsque le client tente de se connecter au serveur, il utilise son truststore pour valider le certificat reçu du serveur.
Pour le TLS bidirectionnel, le client TLS et le serveur TLS peuvent utiliser un truststore. Un truststore est requis lorsque vous effectuez un TLS bidirectionnel lorsque Edge agit en tant que serveur TLS.
Les certificats peuvent être émis par une autorité de certification (AC) 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 fournies par votre autorité de certification 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 publiquement, tels que openssl.
Implémenter un keystore et un truststore sur Edge
Dans Edge, un keystore contient un ou plusieurs fichiers JAR, dans lesquels le fichier JAR contient:
- Certificat TLS au format PEM : certificat signé par une autorité de certification (CA), chaîne de certificats dont le dernier est signé par une autorité de certification ou certificat autosigné.
- Clé privée au format PEM Edge prend en charge des tailles de clé allant jusqu'à 2 048 bits. Une phrase secrète est facultative.
Un truststore est semblable à un keystore, mais il ne contient que des certificats au format PEM, et non 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, soit sous forme de fichiers PEM individuels, soit sous forme de fichier unique. Si vous utilisez un seul fichier, les certificats doivent être dans l'ordre, le premier certificat du fichier étant celui 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 pouvez utiliser pour créer des keystores et des truststores. Les API réelles sont les mêmes. 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 que le certificat sous forme de fichier PEM.
À propos du format des fichiers de certificat et de clé
Les exemples de ce document montrent le certificat et la clé TLS définis en tant que 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 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 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 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-----
Obtenir des informations sur un keystore existant
Recherchez les magasins de clés 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 pour les organisations participant à l'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 créez généralement votre propre keystore, avec votre propre certificat et votre propre clé, avant de les 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 Obtenir un keystore ou un truststore. Pour un client cloud, vous devriez voir un seul certificat TLS de serveur, le 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 devrait se présenter comme suit:
{
"certs" : [ "wildcard.apigee.net.crt" ],
"keys" : [ "freetrial" ],
"name" : "freetrial"
}
Vous pouvez également consulter ces informations dans l'interface utilisateur de gestion Edge:
- Connectez-vous à l'UI de gestion Edge sur https://enterprise.apigee.com (cloud) ou
http://<ms-ip>:9000(sur site), où<ms-ip>est l'adresse IP du nœud du serveur de gestion. - Dans le menu de l'interface utilisateur de gestion d'Edge, sélectionnez Admin > Certificats TLS.
Obtenir les détails d'un certificat TLS
Vous pouvez utiliser l'API Obtenir les détails du certificat à partir d'un keystore ou d'un truststore pour afficher des informations sur les certificats TLS dans le keystore, telles 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 consulter ces informations dans l'interface utilisateur de gestion Edge:
- Connectez-vous à l'UI de gestion Edge sur https://enterprise.apigee.com (cloud) ou
http://<ms-ip>:9000(sur site), où<ms-ip>est l'adresse IP du nœud du serveur de gestion. - Dans le menu de l'interface utilisateur de gestion d'Edge, sélectionnez Admin > Certificats TLS.
Dans l'interface utilisateur d'Edge, vous pouvez spécifier à quel moment Edge indique qu'un certificat va expirer. Par défaut, l'UI met en surbrillance les certificats dont l'expiration est prévue 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 se fait 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éez 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 descriptor.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 à 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 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 keystore. Lorsque vous créez un hôte virtuel, vous référencez le certificat et la clé par leur nom d'alias.password: mot de passe de la clé privée. Omettre ce paramètre si la clé privée n'est associée à aucun mot de passe.
Vérifiez que votre keystore a bien été importé:
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 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 transmettez le fichier de certificat en tant que fichier PEM au lieu d'un fichier 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. Incluez une nouvelle ligne entre chaque certificat dans le 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 à deux voies, l'authentification du client aboutit 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 truststore contient toujours client_cert_1 et ca_cert.
Lorsque le serveur transmet client_cert_2 lors du handshake TLS, la requête aboutit. En effet, Edge permet 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 de l'autorité de certification, ca_cert, du truststore, la validation TLS échoue.
Créez un truststore vide dans l'environnement à l'aide de 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 en tant que fichier PEM dans le truststore à l'aide de l'API 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 truststore
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/serveur cible, tous les appels d'API via l'hôte virtuel ou le point de terminaison/serveur cible échoueront.