Sie sehen sich die Dokumentation zu Apigee Edge an.
Sehen Sie sich die Apigee X-Dokumentation an. info
In diesem Dokument wird beschrieben, wie Sie Schlüssel- und Vertrauensspeicher für Edge für die Private Cloud-Version 4.17.09 und niedriger erstellen, ändern und löschen.
Schlüsselspeicher und Truststores
Schlüsselspeicher und Truststores definieren Repositories von Sicherheitszertifikaten für die TLS-Verschlüsselung. Der Hauptunterschied zwischen den beiden besteht darin, wo sie im TLS-Handshake-Prozess verwendet werden:
- Ein Schlüsselspeicher enthält ein TLS-Zertifikat und einen privaten Schlüssel, mit denen die Entität während des TLS-Handshakes identifiziert wird.
Bei einer Einweg-TLS-Verbindung stellt der Schlüsselspeicher des Servers dem Client das Zertifikat des Servers (öffentliches Zertifikat) zur Verfügung, wenn ein Client eine Verbindung zum TLS-Endpunkt des Servers herstellt. Der Client validiert dieses Zertifikat dann bei einer Zertifizierungsstelle (Certificate Authority, CA), z. B. Symantec oder VeriSign.
Bei bidirektionaler TLS verwalten sowohl der Client als auch der Server einen Schlüsselspeicher mit eigenem Zertifikat und privatem Schlüssel, die für die gegenseitige Authentifizierung verwendet werden. - Ein Truststore enthält Zertifikate, mit denen Zertifikate überprüft werden, die im Rahmen des TLS-Handshakes empfangen wurden.
Bei einer einseitigen TLS-Verbindung ist kein Truststore erforderlich, wenn das Zertifikat von einer gültigen Zertifizierungsstelle signiert ist. Wenn das von einem TLS-Client empfangene Zertifikat von einer gültigen Zertifizierungsstelle signiert ist, sendet der Client eine Anfrage an die Zertifizierungsstelle, um das Zertifikat zu authentifizieren. Ein TLS-Client verwendet in der Regel einen Truststore, um selbst signierte Zertifikate zu validieren, die vom TLS-Server empfangen wurden, oder Zertifikate, die nicht von einer vertrauenswürdigen Zertifizierungsstelle signiert wurden. In diesem Szenario füllt der Client seinen Truststore mit vertrauenswürdigen Zertifikaten. Wenn der Client dann ein Serverzertifikat empfängt, wird das eingehende Zertifikat mit den Zertifikaten in seinem Truststore validiert.
Ein TLS-Client stellt beispielsweise eine Verbindung zu einem TLS-Server her, auf dem ein selbstsigniertes Zertifikat verwendet wird. Da es sich um ein selbst signiertes Zertifikat handelt, kann der Client es nicht bei einer Zertifizierungsstelle validieren. Stattdessen lädt der Client das selbst signierte Zertifikat des Servers in seinen Truststore vor. Wenn der Client dann versucht, eine Verbindung zum Server herzustellen, verwendet er seinen Truststore, um das vom Server empfangene Zertifikat zu validieren.
Bei bidirektionaler TLS-Verschlüsselung können sowohl der TLS-Client als auch der TLS-Server einen Truststore verwenden. Ein Truststore ist erforderlich, wenn bidirektionale TLS-Verbindungen verwendet werden und Edge als TLS-Server fungiert.
Zertifikate können von einer Zertifizierungsstelle ausgestellt oder selbst signiert werden, indem Sie den privaten Schlüssel generieren. Wenn Sie Zugriff auf eine Zertifizierungsstelle haben, folgen Sie der Anleitung der Zertifizierungsstelle zum Generieren von Schlüsseln und Ausstellen von Zertifikaten. Wenn Sie keinen Zugriff auf eine Zertifizierungsstelle haben, können Sie ein selbst signiertes Zertifikat mit einem der vielen öffentlich verfügbaren kostenlosen Tools wie openssl generieren.
Schlüsselspeicher und Truststore in Edge implementieren
In Edge enthält ein Keystore eine oder mehrere JAR-Dateien, die Folgendes enthalten:
- TLS-Zertifikat als PEM-Datei – entweder ein von einer Zertifizierungsstelle signiertes Zertifikat, eine Zertifikatskette, deren letztes Zertifikat von einer Zertifizierungsstelle signiert ist, oder ein selbst signiertes Zertifikat.
- Privater Schlüssel als PEM-Datei. Edge unterstützt Schlüsselgrößen bis zu 2.048 Bit. Eine Passphrase ist optional.
Ein Truststore ähnelt einem Schlüsselspeicher, enthält aber nur Zertifikate als PEM-Datei, keine privaten Schlüssel.
Wenn das Zertifikat Teil einer Kette ist, muss der Schlüsselspeicher/Truststore alle Zertifikate in der Kette enthalten, entweder als einzelne PEM-Dateien oder als einzelne Datei. Wenn Sie eine einzelne Datei verwenden, müssen die Zertifikate in der richtigen Reihenfolge sein. Das erste Zertifikat in der Datei ist das für TLS verwendete Zertifikat, gefolgt von der Zertifikatskette bis zum CA-Zertifikat. Zwischen den einzelnen Zertifikaten in der Datei muss eine leere Zeile eingefügt werden.
Edge bietet eine API, mit der Sie Schlüsselspeicher und Truststores erstellen können. Die eigentlichen APIs sind identisch. Der Unterschied besteht darin, dass Sie beim Erstellen eines Schlüsselspeichers eine JAR-Datei mit dem Zertifikat und dem privaten Schlüssel übergeben. Wenn Sie einen Truststore erstellen, übergeben Sie nur das Zertifikat als PEM-Datei.
Format der Zertifikats- und Schlüsseldateien
In den Beispielen in diesem Dokument sind das TLS-Zertifikat und der Schlüssel als PEM-Dateien definiert, die dem X.509-Format entsprechen. Wenn Ihr Zertifikat oder Ihr privater Schlüssel nicht durch eine PEM-Datei definiert ist, können Sie ihn mithilfe von Dienstprogrammen wie openssl in eine PEM-Datei konvertieren.
Viele .crt- und .key-Dateien liegen jedoch bereits im PEM-Format vor. Wenn diese Dateien Textdateien sind und in Folgendes eingebettet sind:
-----BEGIN CERTIFICATE----- -----END CERTIFICATE-----
oder
-----BEGIN ENCRYPTED PRIVATE KEY----- -----END ENCRYPTED PRIVATE KEY-----
Die Dateien sind dann mit dem PEM-Format kompatibel und können in einem Schlüssel- oder Vertrauensspeicher verwendet werden, ohne dass sie in eine PEM-Datei konvertiert werden müssen.
Wenn Sie eine Zertifikatskette haben und diese in einem Schlüsselspeicher oder Truststore verwenden möchten, können Sie alle Zertifikate in einer einzigen PEM-Datei mit einer neuen Zeile zwischen den einzelnen Zertifikaten kombinieren. Die Zertifikate müssen in der richtigen Reihenfolge sein und das letzte Zertifikat muss ein Stammzertifikat oder ein von einem Stammzertifikat signiertes Zwischenzertifikat sein:
-----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-----
Details zu einem vorhandenen Schlüsselspeicher abrufen
Prüfen Sie mit der List Keystores and Truststores API, ob in Ihrer Umgebung bereits Schlüsselspeicher vorhanden sind:
curl -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores \
-u email:password
Für Cloud-Kunden wird in der Test- und Produktionsumgebung ein Standard-Schlüsselspeicher für Organisationen mit kostenlosem Testzeitraum bereitgestellt. Für diesen Aufruf sollten Sie in beiden Umgebungen die folgenden Ergebnisse sehen:
[ "freetrial" ]
Sie können diesen Standard-Keystore verwenden, um Ihre APIs zu testen und in die Produktion zu verschieben. Normalerweise erstellen Sie jedoch vor dem Produktionsbereitstellen einen eigenen Keystore mit Ihrem eigenen Zertifikat und Schlüssel.
Bei Kunden mit Private Cloud ist das zurückgegebene Array leer, bis Sie Ihren ersten Schlüsselspeicher erstellt haben.
Prüfen Sie den Inhalt des Keystores mit der API „Get a Keystore or Truststore“. Als Cloud-Kunde sollten Sie ein einzelnes Server-TLS-Zertifikat sehen – das Standardzertifikat, das Apigee Edge für kostenlose Testkonten bereitstellt.
curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/freetrial \
-u email:password
Die Antwort sollte so aussehen:
{
"certs" : [ "wildcard.apigee.net.crt" ],
"keys" : [ "freetrial" ],
"name" : "freetrial"
}
Sie können diese Informationen auch in der Edge-Verwaltungsoberfläche aufrufen:
- Melden Sie sich unter https://enterprise.apigee.com (Cloud) oder
http://<ms-ip>:9000(On-Premises) an der Edge-Verwaltungsoberfläche an. Dabei ist<ms-ip>die IP-Adresse des Management Server-Knotens. - Wählen Sie im Menü der Edge-Verwaltungsoberfläche Verwaltung > TLS-Zertifikate aus.
Details zum TLS-Zertifikat abrufen
Mit der API Zertifikatsdetails aus einem Schlüsselspeicher oder Truststore abrufen können Sie Details zu TLS-Zertifikaten im Schlüsselspeicher aufrufen, z. B. das Ablaufdatum und den Aussteller. Ermitteln Sie zuerst den Namen des Zertifikats, an dem Sie interessiert sind. In diesem Beispiel werden Informationen für den Schlüsselspeicher „freetrial“ abgerufen.
curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/freetrial \
-u email:password
Beispielantwort:
{
"certs" : [ "wildcard.apigee.net.crt" ],
"keys" : [ "freetrial" ],
"name" : "freetrial"
}
Verwenden Sie dann den Wert der Property „certs“, um die Zertifikatsdetails abzurufen:
curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/freetrial/certs/wildcard.apigee.net.crt \
-u email:password
Beispielantwort:
{
"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"
}
Sie können diese Informationen auch in der Edge-Verwaltungsoberfläche aufrufen:
- Melden Sie sich unter https://enterprise.apigee.com (Cloud) oder
http://<ms-ip>:9000(On-Premises) in der Edge-Verwaltungsoberfläche an. Dabei ist<ms-ip>die IP-Adresse des Management Server-Knotens. - Wählen Sie im Menü der Edge-Verwaltungsoberfläche Verwaltung > TLS-Zertifikate aus.
In der Edge-Benutzeroberfläche können Sie angeben, wie lange im Voraus Edge anzeigt, dass ein Zertifikat abläuft. Standardmäßig werden in der Benutzeroberfläche alle Zertifikate hervorgehoben, die in den nächsten 10 Tagen ablaufen.
Schlüsselspeicher erstellen
Ein Schlüsselspeicher ist für eine Umgebung in Ihrer Organisation spezifisch, z. B. für die Test- oder Produktionsumgebung. Wenn Sie den Schlüsselspeicher also in einer Testumgebung testen möchten, bevor Sie ihn in Ihrer Produktionsumgebung bereitstellen, müssen Sie ihn in beiden Umgebungen erstellen.
Das Erstellen eines Schlüsselspeichers erfolgt in zwei Schritten:
- Erstellen Sie eine JAR-Datei mit Ihrem Zertifikat und Ihrem privaten Schlüssel.
- Erstellen Sie den Schlüsselspeicher und laden Sie die JAR-Datei hoch.
JAR-Datei mit Zertifikat und privatem Schlüssel erstellen
Erstellen Sie eine JAR-Datei mit Ihrem privaten Schlüssel, Ihrem Zertifikat und einem Manifest. Die JAR-Datei muss die folgenden Dateien und Verzeichnisse enthalten:
/META-INF/descriptor.properties myCert.pem myKey.pem
Erstellen Sie im Verzeichnis mit Ihrem Schlüsselpaar und Zertifikat ein Verzeichnis mit dem Namen /META-INF. Erstellen Sie dann eine Datei mit dem Namen descriptor.properties in /META-INF mit folgendem Inhalt:
certFile={myCertificate}.pem
keyFile={myKey}.pem
Generieren Sie die JAR-Datei mit Ihrem Schlüsselpaar und Zertifikat:
jar -cf myKeystore.jar myCert.pem myKey.pem
Fügen Sie der JAR-Datei descriptor.properties hinzu:
jar -uf myKeystore.jar META-INF/descriptor.properties
Schlüsselspeicher erstellen und JAR-Datei hochladen
Wenn Sie einen Schlüsselspeicher in einer Umgebung erstellen möchten, müssen Sie der API Create a Keystore or Truststore (Schlüsselspeicher oder Truststore erstellen) nur den Namen des Schlüsselspeichers angeben. Der Name darf nur alphanumerische Zeichen enthalten:
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
Beispielantwort:
{
"certs" : [ ],
"keys" : [ ],
"name" : "myKeystore"
}
Nachdem Sie einen benannten Schlüsselspeicher in einer Umgebung erstellt haben, können Sie Ihre JAR-Dateien, die ein Zertifikat und einen privaten Schlüssel enthalten, mit der API JAR-Datei in einen Schlüsselspeicher hochladen hochladen:
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
Dabei gibt die Option -F den Pfad zur JAR-Datei an.
In diesem Aufruf geben Sie zwei Abfrageparameter an:
alias– Identifiziert das Zertifikat und den Schlüssel im Schlüsselspeicher. Wenn Sie einen virtuellen Host erstellen, müssen Sie das Zertifikat und den Schlüssel mit dem Aliasnamen referenzieren.password– das Passwort für den privaten Schlüssel. Lassen Sie diesen Parameter weg, wenn der private Schlüssel kein Passwort hat.
Prüfen Sie, ob der Schlüsselspeicher richtig hochgeladen wurde:
curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myKeystore \
-u email:password
Beispielantwort:
{
"certs" : [ "myCertificate" ],
"keys" : [ "myKey" ],
"name" : "myKeystore"
}
Truststore erstellen
Die APIs, die Sie zum Erstellen eines Truststores verwenden, sind dieselben wie zum Erstellen eines Schlüsselspeichers. Der einzige Unterschied besteht darin, dass Sie die Zertifikatsdatei als PEM-Datei anstelle einer JAR-Datei übergeben.
Wenn das Zertifikat Teil einer Kette ist, müssen Sie entweder alle Zertifikate in der Kette separat in den Truststore hochladen oder eine einzelne Datei mit allen Zertifikaten erstellen. Fügen Sie zwischen den einzelnen Zertifikaten in der Datei eine neue Zeile ein. Das endgültige Zertifikat wird in der Regel vom Aussteller des Zertifikats signiert. Sie laden beispielsweise ein Clientzertifikat (client_cert_1) und das Zertifikat des Ausstellers des Clientzertifikats (ca_cert) in den Truststore hoch.
Bei der TLS-Zwei-Wege-Authentifizierung ist die Clientauthentifizierung erfolgreich, wenn der Server im Rahmen des TLS-Handshake-Prozesses client_cert_1 an den Client sendet.
Alternativ haben Sie ein zweites Zertifikat, client_cert_2, das von demselben Zertifikat, ca_cert, signiert wurde. Sie laden client_cert_2 jedoch nicht in den Truststore hoch. Der Truststore enthält weiterhin client_cert_1 und ca_cert.
Wenn der Server client_cert_2 im Rahmen des TLS-Handshakes übergibt, ist die Anfrage erfolgreich. Das liegt daran, dass Edge die TLS-Überprüfung zulässt, wenn client_cert_2 nicht im Truststore vorhanden ist, aber von einem Zertifikat signiert wurde, das im Truststore vorhanden ist. Wenn Sie das CA-Zertifikat ca_cert aus dem Truststore entfernen, schlägt die TLS-Überprüfung fehl.
Erstellen Sie einen leeren Truststore in der Umgebung mit der API zum Erstellen eines Keystores oder Truststores, derselben API, mit der Sie einen Keystore erstellen:
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
Laden Sie das Zertifikat mit der API Zertifikat in einen Truststore hochladen als PEM-Datei in den Truststore hoch:
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
Dabei gibt die Option -F den Pfad zur PEM-Datei an.
Schlüsselspeicher oder Truststore löschen
Sie können einen Schlüsselspeicher oder einen Vertrauensspeicher mit der API Delete a Keystore or Truststore löschen:
curl -X DELETE \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myKeystoreName \
-u email:password
Beispielantwort:
{
"certs" : [ ],
"keys" : [ ],
"name" : "myKeystoreName"
}
Wenn Sie einen Schlüsselspeicher oder Truststore löschen, der von einem virtuellen Host oder Zielendpunkt/Ziel/Server verwendet wird, schlagen alle API-Aufrufe über den virtuellen Host oder Zielendpunkt/Zielserver fehl.