Sie sehen die Dokumentation zu Apigee Edge.
Zur Apigee X-Dokumentation weitere Informationen
In diesem Dokument wird beschrieben, wie Sie Schlüsselspeicher und Truststores für Edge für die Private Cloud Version 4.17.09 und früher erstellen, ändern und löschen.
Schlüsselspeicher und Truststores
Schlüsselspeicher und Truststores definieren Repositories mit Sicherheitszertifikaten, die für die TLS-Verschlüsselung verwendet werden. Der Hauptunterschied zwischen den beiden besteht darin, wo sie im TLS-Handshake 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.
Wenn ein Client bei One-Way-TLS eine Verbindung zum TLS-Endpunkt auf dem Server herstellt, präsentiert der Schlüsselspeicher des Servers dem Client das Zertifikat des Servers (öffentliches Zertifikat). Der Client validiert dieses Zertifikat dann mit einer Zertifizierungsstelle (Certificate Authority, CA), z. B. Symantec oder VeriSign.
Bei der Zwei-Wege-TLS-Verschlüsselung unterhalten sowohl der Client als auch der Server einen Schlüsselspeicher mit eigenem Zertifikat und privatem Schlüssel, der für die gegenseitige Authentifizierung verwendet wird. - Ein truststore enthält Zertifikate, mit denen Zertifikate bestätigt werden, die im Rahmen des TLS-Handshakes empfangen werden.
Bei One-Way-TLS 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, stellt der Client eine Anfrage zur Authentifizierung des Zertifikats an die Zertifizierungsstelle. 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 den Truststore mit Zertifikaten, denen er vertraut. Wenn der Client dann ein Serverzertifikat empfängt, wird das eingehende Zertifikat anhand der Zertifikate im Truststore validiert.
Ein TLS-Client stellt beispielsweise eine Verbindung zu einem TLS-Server her, bei dem der Server ein selbst signiertes Zertifikat verwendet. Da es sich um ein selbst signiertes Zertifikat handelt, kann der Client es nicht mit einer Zertifizierungsstelle validieren. Stattdessen lädt der Client das selbst signierte Zertifikat des Servers vorab in seinen Truststore. Wenn der Client dann versucht, eine Verbindung zum Server herzustellen, verwendet er seinen Truststore, um das vom Server empfangene Zertifikat zu validieren.
Bei Zwei-Wege-TLS können sowohl der TLS-Client als auch der TLS-Server einen Truststore verwenden. Ein Truststore ist erforderlich, wenn Zwei-Wege-TLS ausgeführt wird, wenn Edge als TLS-Server fungiert.
Zertifikate können von einer Zertifizierungsstelle (Certificate Authority, CA) ausgestellt oder durch den von Ihnen generierten privaten Schlüssel selbst signiert werden. Wenn Sie Zugriff auf eine Zertifizierungsstelle haben, folgen Sie der Anleitung Ihrer Zertifizierungsstelle zum Generieren von Schlüsseln und zum Ausstellen von Zertifikaten. Wenn Sie keinen Zugriff auf eine Zertifizierungsstelle haben, können Sie mit einem der vielen öffentlich verfügbaren kostenlosen Tools wie openssl ein selbst signiertes Zertifikat generieren.
Schlüsselspeicher und Truststore in Edge implementieren
Auf Edge enthält ein Schlüsselspeicher eine oder mehrere JAR-Dateien, wobei die JAR-Datei Folgendes enthält:
- TLS-Zertifikat als PEM-Datei – entweder ein von einer Zertifizierungsstelle signiertes Zertifikat, eine Zertifikatskette, bei der das letzte Zertifikat von einer Zertifizierungsstelle signiert wurde, 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 jedoch nur Zertifikate als PEM-Datei, aber 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 angeordnet sein, wobei das erste Zertifikat in der Datei das für TLS verwendete Zertifikat ist, gefolgt von der Kette von Zertifikaten, die zum CA-Zertifikat führen. Sie müssen zwischen jedem Zertifikat in der Datei eine leere Zeile einfügen.
Edge bietet eine API, mit der Sie Schlüsselspeicher und Truststores erstellen können. Die tatsächlichen APIs sind identisch. Der Unterschied besteht darin, dass Sie beim Erstellen eines Schlüsselspeichers eine JAR-Datei übergeben, die das Zertifikat und den privaten Schlüssel enthält. Wenn Sie einen Truststore erstellen, übergeben Sie nur das Zertifikat als PEM-Datei.
Format der Zertifikat- und Schlüsseldateien
Die Beispiele in diesem Dokument zeigen das TLS-Zertifikat und den TLS-Schlüssel, die als PEM-Dateien im X.509-Format definiert sind. Wenn das Zertifikat oder der private Schlüssel nicht in einer PEM-Datei definiert ist, können Sie es mithilfe von Dienstprogrammen wie openssl in eine PEM-Datei konvertieren.
Viele CRT- und KEY-Dateien liegen jedoch bereits im PEM-Format vor. Wenn es sich bei diesen Dateien um Textdateien handelt, die in folgendem Ordner eingeschlossen sind:
-----BEGIN CERTIFICATE----- -----END CERTIFICATE-----
oder
-----BEGIN ENCRYPTED PRIVATE KEY----- -----END ENCRYPTED PRIVATE KEY-----
Dann sind die Dateien mit dem PEM-Format kompatibel und können in einem Schlüsselspeicher oder Truststore verwendet werden, ohne sie in eine PEM-Datei zu konvertieren.
Wenn Sie eine Zertifikatskette haben und diese Kette in einem Schlüsselspeicher oder Truststore verwenden möchten, können Sie alle Zertifikate in einer einzigen PEM-Datei mit einer neuen Zeile zwischen jedem Zertifikat kombinieren. Die Zertifikate müssen sortiert sein und das letzte Zertifikat muss ein Root-Zertifikat oder ein Zwischenzertifikat sein, das von einem Root-Zertifikat signiert wurde:
-----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 Ihre Umgebung auf vorhandene Schlüsselspeicher, indem Sie die API Keystores and Truststores auflisten verwenden:
curl -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores \
-u email:password
Für Cloud-Kunden wird ein Standardschlüsselspeicher für Organisationen zur kostenlosen Testversion sowohl in der Test- als auch in der Produktumgebung zur Verfügung gestellt. Für diesen Aufruf sollten Sie in beiden Umgebungen die folgenden Ergebnisse sehen:
[ "freetrial" ]
Sie können diesen Standardschlüsselspeicher verwenden, um Ihre APIs zu testen und in die Produktion zu übertragen. In der Regel erstellen Sie jedoch vor der Bereitstellung für die Produktion einen eigenen Schlüsselspeicher mit Ihrem eigenen Zertifikat und Schlüssel.
Für Private Cloud-Kunden ist das zurückgegebene Array leer, bis Sie Ihren ersten Schlüsselspeicher erstellen.
Prüfen Sie den Inhalt des Schlüsselspeichers mithilfe der API Schlüsselspeicher oder Truststore abrufen. Für Cloudkunden sollte ein TLS-Zertifikat für einen einzelnen Server angezeigt werden. Dies ist 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-Verwaltungs-UI ansehen:
- Melden Sie sich in der Edge-Management-Benutzeroberfläche unter https://enterprise.apigee.com (Cloud) oder
http://<ms-ip>:9000(lokal) an, wobei<ms-ip>die IP-Adresse des Management Server-Knotens ist. - Wählen Sie im Menü der Edge-Management-Benutzeroberfläche Admin > TLS Certificates (Verwaltung > TLS-Zertifikate) aus.
Details zum TLS-Zertifikat abrufen
Mit der API Zertifikatdetails 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. Rufen Sie zuerst den Namen des Zertifikats ab, an dem Sie interessiert sind. In diesem Beispiel werden Informationen für den Schlüsselspeicher mit dem Namen „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 des Attributs „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-Verwaltungs-UI ansehen:
- Melden Sie sich in der Edge-Verwaltungs-UI unter https://enterprise.apigee.com (Cloud) oder
http://<ms-ip>:9000(lokal) an, wobei<ms-ip>die IP-Adresse des Management Server-Knotens ist. - Wählen Sie im Menü der Edge-Management-Benutzeroberfläche Admin > TLS Certificates (Verwaltung > TLS-Zertifikate) aus.
In der Edge-Benutzeroberfläche können Sie angeben, wie weit im Voraus Edge anzeigt, dass ein Zertifikat abläuft. Standardmäßig werden in der UI alle Zertifikate hervorgehoben, die in den nächsten 10 Tagen ablaufen.
Schlüsselspeicher erstellen
Ein Schlüsselspeicher ist spezifisch für eine Umgebung in Ihrer Organisation, z. B. die Test- oder Produktionsumgebung. Wenn Sie den Schlüsselspeicher vor der Bereitstellung in Ihrer Produktionsumgebung in einer Testumgebung testen möchten, müssen Sie ihn daher in beiden Umgebungen erstellen.
Die Erstellung eines Schlüsselspeichers erfolgt in zwei Schritten:
- Erstellen Sie eine JAR-Datei, die Ihr Zertifikat und Ihren privaten Schlüssel enthält.
- Erstellen Sie den Schlüsselspeicher und laden Sie die JAR-Datei hoch.
Erstellen Sie eine JAR-Datei mit Ihrem Zertifikat und Ihrem privaten Schlüssel
Erstellen Sie eine JAR-Datei mit Ihrem privaten Schlüssel, dem Zertifikat und einem Manifest. Die JAR-Datei muss die folgenden Dateien und Verzeichnisse enthalten:
/META-INF/descriptor.properties myCert.pem myKey.pem
Erstellen Sie in dem Verzeichnis, das Ihr Schlüsselpaar und Ihr Zertifikat enthält, ein Verzeichnis mit dem Namen /META-INF. Erstellen Sie dann in /META-INF eine Datei mit dem Namen descriptor.properties und folgendem Inhalt:
certFile={myCertificate}.pem
keyFile={myKey}.pem
Generieren Sie die JAR-Datei, die Ihr Schlüsselpaar und das Zertifikat enthält:
jar -cf myKeystore.jar myCert.pem myKey.pem
Fügen Sie descriptor.properties Ihrer JAR-Datei 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 nur den Schlüsselspeichernamen für die API Schlüsselspeicher oder Truststore erstellen 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 Upload a JAR file to a Keystore 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, verweisen Sie auf das Zertifikat und den Schlüssel mit seinem Aliasnamen.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 Ihr Schlüsselspeicher korrekt 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 Truststore verwenden, sind die gleichen wie zum Erstellen eines Schlüsselspeichers. Der einzige Unterschied besteht darin, dass Sie die Zertifikatsdatei als PEM-Datei und nicht als 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 dann zwischen den einzelnen Zertifikaten in der Datei eine neue Zeile ein. Das endgültige Zertifikat wird in der Regel vom Aussteller des Zertifikats signiert. Laden Sie beispielsweise im Truststore das Clientzertifikat client_cert_1 und das Zertifikat des Ausstellers des Clientzertifikats ca_cert hoch.
Bei der Zwei-Wege-TLS-Authentifizierung ist die Clientauthentifizierung erfolgreich, wenn der Server im Rahmen des TLS-Handshakes client_cert_1 an den Client sendet.
Alternativ haben Sie ein zweites Zertifikat client_cert_2, das vom selben Zertifikat ca_cert signiert ist. 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. Dies 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. Verwenden Sie dazu die API, mit der Sie einen Schlüsselspeicher erstellen, Schlüsselspeicher oder Truststore 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 als PEM-Datei in den Truststore hoch. Verwenden Sie dazu die API Zertifikat in Truststore hochladen:
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
Mit der API zum Löschen eines Schlüsselspeichers oder Truststores können Sie einen Schlüsselspeicher oder 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.