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

Wyświetlasz dokumentację Apigee Edge.
Przejdź do dokumentacji Apigee X. info

Z tego dokumentu dowiesz się, jak tworzyć, modyfikować i usuwać magazyny kluczy oraz magazyny zaufania w Edge w wersji Private Cloud 4.17.09 i starszych.

Magazyny kluczy i magazyny zaufania

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

  • A magazyn kluczy zawiera certyfikat TLS i klucz prywatny używane do identyfikowania podmiotu 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). Następnie klient weryfikuje ten certyfikat za pomocą urzędu certyfikacji, np. Symantec lub VeriSign.

    W przypadku dwukierunkowego protokołu TLS zarówno klient, jak i serwer mają magazyn kluczy z własnym certyfikatem i kluczem prywatnym używanym do wzajemnego uwierzytelniania.
  • A truststore zawiera certyfikaty używane do weryfikowania certyfikatów otrzymanych w ramach uzgadniania połączenia TLS.

    W przypadku jednokierunkowego protokołu TLS magazyn zaufanych certyfikatów nie jest wymagany, jeśli certyfikat jest podpisany przez prawidłowy urząd certyfikacji. Jeśli certyfikat otrzymany przez klienta TLS jest podpisany przez prawidłowy urząd certyfikacji, klient wysyła do niego żądanie uwierzytelnienia certyfikatu. Klient protokołu TLS zwykle używa magazynu zaufanych certyfikatów do weryfikowania certyfikatów podpisanych samodzielnie otrzymanych z serwera protokołu TLS lub certyfikatów, które nie są podpisane przez zaufany urząd certyfikacji. W takim przypadku klient wypełnia swój magazyn zaufania certyfikatami, którym ufa. Gdy klient otrzyma certyfikat serwera, przychodzący certyfikat jest weryfikowany na podstawie certyfikatów w magazynie zaufanych certyfikatów.

    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ć za pomocą urzędu certyfikacji. Zamiast tego klient wstępnie wczytuje certyfikat serwera podpisany samodzielnie do swojego magazynu zaufanych certyfikatów. Gdy klient próbuje połączyć się z serwerem, używa magazynu zaufanych certyfikatów do weryfikowania certyfikatu otrzymanego z serwera.

    W przypadku dwukierunkowego protokołu TLS zarówno klient TLS, jak i serwer TLS mogą używać magazynu zaufanych certyfikatów. Magazyn zaufanych certyfikatów jest wymagany podczas wykonywania dwukierunkowego protokołu TLS, gdy Edge działa jako serwer TLS.

Certyfikaty mogą być wydawane przez urząd certyfikacji lub mogą być podpisane samodzielnie za pomocą wygenerowanego przez Ciebie klucza prywatnego. Jeśli masz dostęp do urzędu certyfikacji, postępuj zgodnie z instrukcjami podanymi przez twój urząd, aby wygenerować klucze i wydać certyfikaty. Jeśli nie masz dostępu do urzędu certyfikacji, możesz wygenerować certyfikat podpisany samodzielnie za pomocą jednego z wielu publicznie dostępnych bezpłatnych narzędzi, np. openssl.

Implementowanie 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 klucze o rozmiarze do 2048 bitów. Hasło jest opcjonalne.

Magazyn zaufanych certyfikatów jest podobny do magazynu kluczy, ale zawiera tylko certyfikaty jako pliki PEM, a nie klucze prywatne.

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

Edge udostępnia interfejs API, którego możesz używać 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 przekazujesz plik JAR zawierający certyfikat i klucz prywatny. Podczas tworzenia magazynu zaufanych certyfikatów przekazujesz tylko certyfikat jako plik PEM.

Format plików certyfikatów i kluczy

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

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

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

lub:

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

Pliki są zgodne z formatem PEM i można ich używać w magazynie kluczy lub magazynie zaufanych certyfikatów bez konwertowania ich na plik PEM.

Jeśli masz łańcuch certyfikatów i chcesz go użyć w magazynie kluczy lub magazynie zaufanych certyfikatów, to możesz połączyć wszystkie certyfikaty w jeden plik PEM z nowym wierszem między każdym certyfikatem. Certyfikaty muszą być w kolejności, a ostatni certyfikat musi być certyfikatem głównym lub certyfikatem pośrednim podpisanym przez certyfikat główny:

-----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 szczegółowych informacji o istniejącym magazynie kluczy

Sprawdź, czy w Twoim środowisku są jakieś magazyny kluczy, za pomocą interfejsu List Keystores and Truststores API:

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 w organizacjach korzystających z bezpłatnego okresu próbnego w środowiskach testowych i produkcyjnych udostępniany jest domyślny magazyn kluczy. W obu środowiskach powinny być widoczne te wyniki:

[ "freetrial" ]

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

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

Sprawdź zawartość magazynu kluczy za pomocą interfejsu Get a Keystore or Truststore API. W przypadku klienta korzystającego z chmury powinien być widoczny pojedynczy certyfikat serwera TLS – domyślny certyfikat udostępniany przez Apigee Edge w przypadku kont korzystających z bezpłatnego okresu próbnego.

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

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

Pobieranie szczegółowych informacji o certyfikacie TLS

Za pomocą interfejsu Get Cert Details from a Keystore or Truststore API 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. Ten przykład pobiera 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ółowe informacje o certyfikacie:

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

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

W interfejsie Edge możesz określić, z jakim wyprzedzeniem Edge ma informować o wygaśnięciu 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 Twojej organizacji, np. ś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 to proces dwuetapowy:

  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 manifestem. 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 utwórz w katalogu /META-INF 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 plik descriptor.properties do pliku JAR:

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

Tworzenie magazynu kluczy i przesyłanie pliku JAR

Aby utworzyć magazyn kluczy w środowisku, musisz tylko podać jego nazwę w interfejsie Create a Keystore or Truststore API. 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"
}

Po utworzeniu nazwanego magazynu kluczy w środowisku możesz przesłać pliki JAR, które zawierają certyfikat i klucz prywatny, za pomocą interfejsu Upload a JAR file to a Keystore API:

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 tym wywołaniu określasz 2 parametry zapytania:

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

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 zaufanych certyfikatów

Interfejsy API, których używasz do tworzenia magazynu zaufanych certyfikatów, są takie same jak te, których używasz do tworzenia magazynu kluczy. Jedyna różnica polega na tym, że zamiast pliku JAR przekazujesz plik certyfikatu jako plik PEM.

Jeśli certyfikat jest częścią łańcucha, musisz przesłać wszystkie certyfikaty w łańcuchu osobno do magazynu zaufanych certyfikatów lub utworzyć jeden plik zawierający wszystkie certyfikaty. Między każdym certyfikatem w pliku umieść nowy wiersz. Ostatni certyfikat jest zwykle podpisany przez wystawcę certyfikatu. Na przykład w magazynie zaufanych certyfikatów przesyłasz certyfikat klienta client_cert_1 i certyfikat wystawcy certyfikatu klienta ca_cert.

Podczas uwierzytelniania dwukierunkowego protokołu TLS uwierzytelnianie klienta zakończy się powodzeniem, gdy serwer wyśle client_cert_1 do klienta 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 przesyłasz client_cert_2 do magazynu zaufania. Magazyn zaufanych certyfikatów nadal zawiera client_cert_1 i ca_cert.

Gdy serwer przekaże client_cert_2 w ramach uzgadniania połączenia TLS, żądanie zakończy się powodzeniem. Dzieje się tak, ponieważ Edge zezwala na pomyślną weryfikację protokołu TLS, gdy client_cert_2 nie istnieje w magazynie zaufanych certyfikatów, ale został podpisany przez certyfikat, który istnieje w magazynie zaufanych certyfikatów. Jeśli usuniesz z magazynu zaufania certyfikat urzędu certyfikacji ca_cert, weryfikacja TLS nie powiedzie się.

Utwórz pusty magazyn zaufania w środowisku za pomocą interfejsu Create a Keystore or Truststore API, czyli tego samego interfejsu API, którego używasz do tworzenia magazynu kluczy:

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 za pomocą interfejsu Upload a Certificate to a Truststore API:

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ąć za pomocą interfejsu Delete a Keystore or Truststore API:

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 zaufanych certyfikatów używany przez hosta wirtualnego lub punkt końcowy/serwer docelowy, wszystkie wywołania interfejsu API przez hosta wirtualnego lub punkt końcowy/serwer docelowy nie powiodą się.