Tworzenie magazynów kluczy i magazynów zaufania dla Private Cloud w wersji 4.17.09 lub starszej

Przeglądasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X.
Informacje

Ten dokument opisuje, jak tworzyć, modyfikować i usuwać magazyny kluczy oraz magazyny zaufania dla Edge dla Private Cloud w wersji 4.17.09 i starszych.

Informacje o magazynach kluczy i magazynach zaufania

Magazyny kluczy i magazyny zaufania definiują repozytoria certyfikatów bezpieczeństwa używane do szyfrowania TLS. Główna różnica między nimi polega na tym, gdzie są używane podczas uzgadniania połączenia TLS:

  • Magazyn kluczy zawiera certyfikat TLS i klucz prywatny używane do identyfikowania jednostki podczas uzgadniania połączenia TLS.

    W przypadku jednokierunkowego protokołu TLS, gdy klient łączy się z punktem końcowym TLS na serwerze, magazyn kluczy serwera przedstawia klientowi certyfikat serwera (certyfikat publiczny). Klient weryfikuje certyfikat w urzędzie certyfikacji, takim jak Symantec lub VeriSign.

    W przypadku dwukierunkowego protokołu TLS zarówno klient, jak i serwer utrzymują magazyn kluczy z własnym certyfikatem i kluczem prywatnym służącym do wzajemnego uwierzytelniania.
  • W truststore znajdują się certyfikaty używane do weryfikowania certyfikatów otrzymanych w ramach hakowania połączeń TLS.

    W przypadku jednokierunkowego protokołu TLS magazyn zaufania nie jest wymagany, jeśli certyfikat jest podpisany przez ważny urząd certyfikacji. Jeśli certyfikat odebrany przez klienta TLS jest podpisany przez ważny urząd certyfikacji, klient wysyła do urzędu certyfikacji żądanie uwierzytelnienia certyfikatu. Klient TLS zazwyczaj używa magazynu zaufania do weryfikacji certyfikatów podpisanych samodzielnie z serwera TLS lub certyfikatów, które nie są podpisane przez zaufany urząd certyfikacji. W tym scenariuszu klient wypełnia swój magazyn zaufanych certyfikatów zaufanymi certyfikatami. Następnie, gdy klient otrzyma certyfikat serwera, przychodzący certyfikat jest sprawdzany pod kątem zgodności z certyfikatami w jego magazynie zaufania.

    Na przykład klient TLS łączy się z serwerem TLS, na którym serwer używa certyfikatu podpisanego samodzielnie. Ponieważ jest to certyfikat podpisany samodzielnie, klient nie może go zweryfikować w urzędzie certyfikacji. Zamiast tego klient wczytuje samodzielnie podpisany certyfikat serwera do magazynu zaufanych certyfikatów. Następnie, gdy klient próbuje połączyć się z serwerem, korzysta ze swojego magazynu zaufanych certyfikatów, aby zweryfikować certyfikat otrzymany z serwera.

    W przypadku dwukierunkowego protokołu TLS zarówno klient TLS, jak i serwer TLS mogą korzystać z magazynu zaufania. Magazyn zaufania jest wymagany w przypadku wykonywania dwukierunkowego protokołu TLS, gdy Edge działa jako serwer TLS.

Certyfikaty mogą być wystawiane przez urząd certyfikacji (CA) lub samodzielnie podpisane przez Ciebie. Jeśli masz dostęp do urzędu certyfikacji, postępuj zgodnie z podanymi przez niego instrukcjami generowania kluczy i wystawiania certyfikatów. Jeśli nie masz dostępu do urzędu certyfikacji, możesz wygenerować certyfikat podpisany samodzielnie za pomocą jednego z wielu dostępnych publicznie bezpłatnych narzędzi, takich jak opensl.

Wdrażanie magazynu kluczy i magazynu zaufania w Edge

W Edge magazyn kluczy zawiera co najmniej 1 plik JAR, który zawiera:

  • Certyfikat TLS jako plik PEM – certyfikat podpisany przez urząd certyfikacji (CA), łańcuch certyfikatów, w którym ostatni certyfikat jest podpisany przez urząd certyfikacji, lub certyfikat podpisany samodzielnie.
  • Klucz prywatny jako plik PEM. Edge obsługuje rozmiar klucza do 2048 bitów. Hasło jest opcjonalne.

Magazyn zaufania jest podobny do magazynu kluczy, ale zawiera tylko certyfikaty w postaci pliku PEM, ale nie zawiera kluczy prywatnych.

Jeśli certyfikat jest częścią łańcucha, magazyn kluczy/magazyn zaufania musi zawierać wszystkie certyfikaty w łańcuchu – jako pojedyncze pliki PEM lub pojedynczy plik. Jeśli używasz jednego pliku, certyfikaty muszą być podane w kolejności, w której pierwszy certyfikat w pliku jest certyfikatem używany dla protokołu TLS, a następnie łańcuch certyfikatów kolejno do certyfikatu CA. Między każdym certyfikatem w pliku musisz wstawić pusty wiersz.

Edge udostępnia interfejs API, który służy do tworzenia magazynów kluczy i magazynów zaufania. Rzeczywiste interfejsy API są takie same. Różnica polega na tym, że podczas tworzenia magazynu kluczy należy przekazać plik JAR zawierający certyfikat i klucz prywatny. Podczas tworzenia magazynu zaufania przekazujesz tylko certyfikat jako plik PEM.

Informacje o formacie plików certyfikatu i klucza

Przykłady w tym dokumencie pokazują certyfikat i klucz TLS zdefiniowane jako pliki PEM, zgodne z formatem X.509. Jeśli Twój certyfikat lub klucz prywatny nie jest zdefiniowany w pliku PEM, możesz go przekonwertować na plik PEM za pomocą narzędzi takich jak opensl.

Jednak wiele plików .crt i .key jest już w formacie PEM. Jeśli są to pliki tekstowe i są ujęte w:

-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----

lub

-----BEGIN ENCRYPTED PRIVATE KEY-----
-----END ENCRYPTED PRIVATE KEY-----

Dzięki temu pliki będą zgodne z formatem PEM i możesz ich używać w magazynie kluczy lub zaufanych bazach bez konieczności konwertowania ich na plik PEM.

Jeśli masz łańcuch certyfikatów i chcesz używać tego łańcucha w magazynie kluczy lub magazynie zaufania, możesz połączyć wszystkie certyfikaty w jeden plik PEM z nowym wierszem między poszczególnymi certyfikatami. Certyfikaty muszą być wymienione we właściwej kolejności, a ostatni musi być certyfikatem głównym lub pośrednim podpisanym certyfikatem głównym:

-----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-----

Pobieranie informacji o istniejącym magazynie kluczy

Sprawdź w środowisku, czy istnieją istniejące magazyny kluczy, korzystając z interfejsu API List Keystores i Truststores:

curl -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores \
-u email:password

W przypadku klientów korzystających z chmury udostępniany jest domyślny magazyn kluczy dla organizacji korzystających z bezpłatnego okresu próbnego zarówno w środowiskach testowych, jak i produkcyjnych. Oto wyniki tego wywołania w obu środowiskach:

[ "freetrial" ]

Możesz używać tego domyślnego magazynu kluczy do testowania interfejsów API i przekazywać je do środowiska produkcyjnego, ale przed wdrożeniem w środowisku produkcyjnym zwykle tworzysz własny magazyn kluczy z własnym certyfikatem i kluczem.

W przypadku klientów Private Cloud zwracana tablica jest pusta, dopóki nie utworzysz pierwszego magazynu kluczy.

Sprawdź zawartość magazynu kluczy przy użyciu interfejsu API Get a Keystore lub Truststore. W przypadku klienta korzystającego z chmury powinien być widoczny certyfikat TLS z jednego serwera – domyślny certyfikat Apigee Edge udostępniany na potrzeby bezpłatnych kont próbnych.

curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/freetrial \
-u email:password

Odpowiedź powinna wyglądać tak:

{
 "certs" : [ "wildcard.apigee.net.crt" ],
 "keys" : [ "freetrial" ],
 "name" : "freetrial"
}

Te informacje możesz też wyświetlić w interfejsie zarządzania brzegiem:

  1. Zaloguj się w interfejsie zarządzania brzegowym na https://enterprise.apigee.com (w chmurze) lub http://<ms-ip>:9000 (lokalnie), gdzie <ms-ip> to adres IP węzła serwera zarządzania.
  2. W menu interfejsu zarządzania brzegiem sieci wybierz Administracja > Certyfikaty TLS.

Pobieranie szczegółów certyfikatu TLS

Za pomocą interfejsu API Pobierz szczegóły certyfikatu z magazynu kluczy lub Truststore możesz wyświetlić szczegółowe informacje o certyfikatach TLS w magazynie kluczy, takie jak data ważności i wystawca. Najpierw uzyskaj nazwę certyfikatu, który Cię interesuje. W tym przykładzie pobierasz informacje o magazynie kluczy o nazwie „freetrial”.

curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/freetrial \
-u email:password

Przykładowa odpowiedź:

{
 "certs" : [ "wildcard.apigee.net.crt" ],
 "keys" : [ "freetrial" ],
 "name" : "freetrial"
}

Następnie użyj wartości właściwości certs, aby uzyskać szczegóły certyfikatu:

curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/freetrial/certs/wildcard.apigee.net.crt \
-u email:password

Przykładowa odpowiedź:

{
 "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=&quot;GoDaddy.com, Inc.&quot;, 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"
}

Te informacje możesz też wyświetlić w interfejsie zarządzania brzegiem:

  1. Zaloguj się w interfejsie zarządzania brzegowym na https://enterprise.apigee.com (w chmurze) lub http://<ms-ip>:9000 (lokalny), gdzie <ms-ip> to adres IP węzła serwera zarządzania.
  2. W menu interfejsu zarządzania brzegiem sieci wybierz Administracja > Certyfikaty TLS.

W interfejsie użytkownika Edge możesz określić, z jakim wyprzedzeniem Edge oznacza ważność certyfikatu. Domyślnie interfejs wyróżnia wszystkie certyfikaty, które mają wygasnąć w ciągu najbliższych 10 dni.

Tworzenie magazynu kluczy

Magazyn kluczy jest specyficzny dla środowiska w organizacji, na przykład środowiska testowego lub produkcyjnego. Jeśli więc chcesz przetestować magazyn kluczy w środowisku testowym przed wdrożeniem go w środowisku produkcyjnym, musisz go utworzyć w obu środowiskach.

Tworzenie magazynu kluczy składa się z 2 etapów:

  1. Utwórz plik JAR zawierający certyfikat i klucz prywatny.
  2. Utwórz magazyn kluczy i prześlij plik JAR.

Tworzenie pliku JAR zawierającego certyfikat i klucz prywatny

Utwórz plik JAR z kluczem prywatnym, certyfikatem i plikiem manifestu. Plik JAR musi zawierać te pliki i katalogi:

/META-INF/descriptor.properties
myCert.pem
myKey.pem

W katalogu zawierającym parę kluczy i certyfikat utwórz katalog o nazwie /META-INF. Następnie w /META-INF utwórz plik o nazwie descriptor.properties z tą zawartością:

certFile={myCertificate}.pem
keyFile={myKey}.pem

Wygeneruj plik JAR zawierający parę kluczy i certyfikat:

jar -cf myKeystore.jar myCert.pem myKey.pem

Dodaj descriptor.properties do pliku JAR:

jar -uf myKeystore.jar META-INF/descriptor.properties

Utwórz magazyn kluczy i prześlij plik JAR

Aby utworzyć magazyn kluczy w środowisku, musisz podać jego nazwę w interfejsie API Create a Keystore lub Truststore. Nazwa może zawierać tylko znaki alfanumeryczne:

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

Przykładowa odpowiedź:

{
 "certs" : [ ],
 "keys" : [ ],
 "name" : "myKeystore"
}

Gdy utworzysz w środowisku nazwany magazyn kluczy, możesz przesłać pliki JAR zawierające certyfikat i klucz prywatny, korzystając z funkcji przesyłania pliku JAR do interfejsu API magazynu kluczy:

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

gdzie opcja -F określa ścieżkę do pliku JAR.

W wywołaniu tego żądania określasz 2 parametry zapytania:

  • alias – identyfikuje certyfikat i klucz w magazynie kluczy. Podczas tworzenia hosta wirtualnego odwołujesz się do certyfikatu i klucza za pomocą ich aliasu.
  • password – hasło klucza prywatnego. Pomiń ten parametr, jeśli klucz prywatny nie ma hasła.

Sprawdź, czy magazyn kluczy został prawidłowo przesłany:

curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myKeystore \
-u email:password

Przykładowa odpowiedź:

{  
 "certs" : [ "myCertificate" ],
 "keys" : [ "myKey" ],
 "name" : "myKeystore"
}

Tworzenie magazynu zaufania

Interfejsy API, których używasz do utworzenia magazynu kluczy, są takie same jak do utworzenia magazynu kluczy. Jedyną różnicą jest to, że należy przekazać plik certyfikatu jako plik PEM, a nie JAR.

Jeśli certyfikat jest częścią łańcucha, musisz przesłać wszystkie certyfikaty w łańcuchu oddzielnie do magazynu zaufania lub utworzyć jeden plik ze wszystkimi certyfikatami. Między poszczególnymi certyfikatami w tym pliku umieść nowy wiersz. Ostateczny certyfikat zwykle jest podpisywany przez jego wydawcę. Na przykład do magazynu zaufania przesyłasz certyfikat klienta (client_cert_1) i certyfikat wydawcy certyfikatu klienta (ca_cert).

Podczas dwukierunkowego uwierzytelniania TLS uwierzytelnianie klienta kończy się powodzeniem, gdy serwer wysyła do klienta client_cert_1 w ramach procesu uzgadniania połączenia TLS.

Możesz też mieć drugi certyfikat: client_cert_2, podpisany tym samym certyfikatem: ca_cert. Nie przesyłasz jednak client_cert_2 do magazynu zaufania. Magazyn zaufania nadal zawiera client_cert_1 i ca_cert.

Gdy serwer przekazuje client_cert_2 w ramach uzgadniania połączenia TLS, żądanie zostaje zrealizowane. Dzieje się tak, ponieważ Edge zezwala na pomyślną weryfikację TLS, gdy client_cert_2 nie istnieje w magazynie zaufania, ale została podpisana za pomocą certyfikatu istniejącego w magazynie zaufania. Jeśli usuniesz certyfikat CA (ca_cert) z magazynu zaufania, weryfikacja TLS zakończy się niepowodzeniem.

Utwórz w środowisku pusty magazyn zaufanych certyfikatów przy użyciu tego samego interfejsu API, którego używasz do utworzenia magazynu kluczy: Utwórz magazyn kluczy lub Truststore:

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

Prześlij certyfikat jako plik PEM do magazynu zaufania przy użyciu interfejsu API Prześlij certyfikat do 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

gdzie opcja -F określa ścieżkę do pliku PEM.

Usuwanie magazynu kluczy lub magazynu zaufanych certyfikatów

Magazyn kluczy lub magazyn zaufania możesz usunąć przy użyciu interfejsu API Delete a Keystore lub Truststore:

curl -X DELETE \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myKeystoreName \
-u email:password

Przykładowa odpowiedź:

{
 "certs" : [ ],
 "keys" : [ ],
 "name" : "myKeystoreName"
}

Jeśli usuniesz magazyn kluczy lub magazyn zaufania, który jest używany przez hosta wirtualny albo docelowy punkt końcowy/miejsce docelowe/serwer, wszystkie wywołania interfejsu API wysyłane przez hosta wirtualnego lub docelowy punkt końcowy/serwer docelowy zakończą się niepowodzeniem.