Wyświetlasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. info
Z tego dokumentu dowiesz się, jak tworzyć, modyfikować i usuwać magazyny kluczy i magazyny zaufanych certyfikatów w przypadku Edge w chmurze i Edge w chmurze prywatnej w wersji 4.18.01 i nowszych.
Wprowadzenie
Aby skonfigurować funkcje, które opierają się na infrastrukturze klucza publicznego, takie jak TLS, musisz utworzyć magazyny kluczy i magazyny zaufanych certyfikatów, które zapewniają niezbędne klucze i certyfikaty cyfrowe.
Wprowadzenie do magazynów kluczy, magazynów zaufanych certyfikatów i aliasów znajdziesz w artykule Magazyny kluczy i magazyny zaufanych certyfikatów.
Tworzenie magazynu kluczy
Magazyn kluczy jest specyficzny dla środowiska w 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 utworzyć go w obu tych środowiskach.
Aby utworzyć magazyn kluczy w środowisku:
- Aby utworzyć magazyn kluczy, użyj wywołania interfejsu API w tej sekcji.
- Utwórz alias i prześlij do niego parę certyfikat/klucz. Sposób przesyłania certyfikatu i klucza zależy od formatu pary certyfikat/klucz. W sekcjach poniżej znajdziesz informacje o tym, jak przesyłać poszczególne typy par certyfikatów i kluczy:
Aby utworzyć magazyn kluczy, podaj jego nazwę w interfejsie API Create a Keystore or Truststore (Tworzenie magazynu kluczy lub magazynu zaufanych certyfikatów). Nazwa magazynu kluczy może zawierać tylko znaki alfanumeryczne:
curl -X POST -u orgAdminEmail:password -H "Content-Type: text/xml" \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores \
-d '<KeyStore name="myKeystore"/>'Przykładowa odpowiedź:
{ "certs" : [ ], "keys" : [ ], "name" : "myKeystore" }
Przesyłanie certyfikatu i klucza jako pliku JAR
Najpierw musisz utworzyć plik JAR z kluczem prywatnym, certyfikatem i manifestem. Plik JAR musi zawierać te pliki i katalogi:
/META-INF/descriptor.properties myCert.pem myKey.pem
Plik JAR magazynu kluczy może zawierać tylko te 3 pliki. Jeśli masz łańcuch certyfikatów, wszystkie certyfikaty w łańcuchu muszą być dołączone do jednego pliku PEM, a ostatni certyfikat powinien być podpisany przez główny urząd certyfikacji. Certyfikaty muszą być dołączone do pliku PEM w odpowiedniej kolejności, z pustym wierszem między nimi, czyli:
cert -> intermediate cert(1) -> intermediate cert(2) -> … -> root
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 descriptor.properties do pliku JAR:
jar -uf myKeystore.jar META-INF/descriptor.properties
Możesz teraz przesyłać pliki JAR zawierające certyfikat i klucz prywatny za pomocą interfejsu API Create an alias from a JAR or PKCS file (Utwórz alias z pliku JAR lub PKCS):
curl -u orgAdminEmail:password -X POST -H "Content-Type: multipart/form-data" -F file="@myKeystore.jar" -F password={key_pword} \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases?alias={alias_name}&format=keycertjar"
gdzie opcja -F określa ścieżkę do pliku JAR.
W tym wywołaniu określasz:
alias_name– identyfikuje certyfikat i klucz w magazynie kluczy. Podczas tworzenia hosta wirtualnego odwołujesz się do certyfikatu i klucza za pomocą nazwy aliasu.key_pword– hasło klucza prywatnego. Pomiń ten parametr, jeśli klucz prywatny nie ma hasła.
Sprawdź, czy magazyn kluczy został przesłany prawidłowo:
curl -u orgAdminEmail:password -X GET\
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}
Przykładowa odpowiedź:
{ "certs" : [ "myCertificate" ], "keys" : [ "myKey" ], "name" : "myKeystore" }
Prześlij certyfikat i klucz jako pliki PEM
Prześlij pliki PEM zawierające certyfikat i klucz prywatny, korzystając z interfejsu API Create an alias from certificate and key PEM files:
curl -u orgAdminEmail:password -X POST -H "Content-Type: multipart/form-data" -F keyFile="@server.key" -F certFile="@signed.crt" \
-F password={key_pword} \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases?alias={alias_name}&format=keycertfile"
gdzie opcja -F określa ścieżki do plików PEM.
W tym wywołaniu określasz:
alias_name– identyfikuje certyfikat i klucz w magazynie kluczy. Podczas tworzenia hosta wirtualnego odwołujesz się do certyfikatu i klucza za pomocą nazwy aliasu.key_pword– hasło klucza prywatnego. Pomiń ten parametr, jeśli klucz prywatny nie ma hasła.
Sprawdź, czy magazyn kluczy został przesłany prawidłowo:
curl -u orgAdminEmail:password -X GET\
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}
Przykładowa odpowiedź:
{ "certs" : [ "myCertificate" ], "keys" : [ "myKey" ], "name" : "myKeystore" }
Prześlij certyfikat i klucz jako plik PKCS12/PFX.
Prześlij plik PKCS12/PFX zawierający certyfikat i klucz prywatny, korzystając z interfejsu API Create an alias from a JAR or PKCS file:
curl -u orgAdminEmail:password -X POST -H "Content-Type: multipart/form-data" \
-F file="@myKeystore.p12" -F password={key_pword} \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases?alias={alias_name}&format=pkcs12"
gdzie opcja -F określa ścieżkę do pliku P12.
W tym wywołaniu określasz:
alias_name– identyfikuje certyfikat i klucz w magazynie kluczy. Podczas tworzenia hosta wirtualnego odwołujesz się do certyfikatu i klucza za pomocą nazwy aliasu.key_pword– hasło klucza prywatnego. Pomiń ten parametr, jeśli klucz prywatny nie ma hasła.
Sprawdź, czy magazyn kluczy został przesłany prawidłowo:
curl -u orgAdminEmail:password -X GET\
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}
Przykładowa odpowiedź:
{ "certs" : [ "myCertificate" ], "keys" : [ "myKey" ], "name" : "myKeystore" }
Tworzenie i przesyłanie certyfikatu z podpisem własnym i klucza
Możesz użyć interfejsu Create an alias by generating a self-signed certificate API, aby utworzyć podpisany samodzielnie certyfikat i klucz oraz przesłać je do aliasu. Poniższe wywołanie zawiera tylko informacje wymagane do utworzenia certyfikatu z podpisem własnym. Możesz zmodyfikować to wywołanie, aby dodać dodatkowe informacje:
curl -u orgAdminEmail:password -X POST --header "Content-Type: application/json" \
-d "{
"alias": "selfsigned",
"subject": {
"commonName": "mycert"
}
}" \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases?format=selfsignedcert"
Odpowiedź powinna wyglądać tak:
{ "alias": "selfsigned", "certsInfo": { "certInfo": [ { "basicConstraints": "CA:FALSE", "expiryDate": 1491497204000, "isValid": "Yes", "issuer": "CN=mycert", "publicKey": "RSA Public Key, 2048 bits", "serialNumber": "00:d1:b4:78:e1", "sigAlgName": "SHA256withRSA", "subject": "CN=mycert", "subjectAlternativeNames": [], "validFrom": 1459961204000, "version": 3 } ], "certName": "selfsigned-cert" }, "keyName": "selfsigned" }
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 do magazynu zaufanych certyfikatów przesyłasz tylko plik certyfikatu w formacie 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. Pomiędzy poszczególnymi certyfikatami w pliku musisz wstawić pusty wiersz.
Jeśli chcesz przesłać kilka certyfikatów podpisanych samodzielnie, które nie są częścią łańcucha, użyj tej samej metody: jeśli chcesz zaufać kilku certyfikatom, prześlij je w jednym pliku.
Ostateczny certyfikat jest zwykle podpisywany 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 TLS uwierzytelnianie klienta zakończy się powodzeniem, gdy serwer wyśle do klienta certyfikat 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 pliku client_cert_2 do magazynu zaufanych certyfikatów. Magazyn zaufanych certyfikatów nadal zawiera certyfikaty client_cert_1 i ca_cert.
Gdy serwer przekaże certyfikat client_cert_2 w ramach uzgadniania połączenia TLS, żądanie zostanie zrealizowane. Dzieje się tak, ponieważ Edge zezwala na pomyślną weryfikację TLS, gdy certyfikat client_cert_2 nie istnieje w magazynie zaufanych certyfikatów, ale został podpisany przez certyfikat, który w nim jest. Jeśli usuniesz certyfikat CA ca_cert z magazynu zaufanych certyfikatów, weryfikacja TLS nie powiedzie się.
Utwórz w środowisku pusty magazyn zaufanych certyfikatów, korzystając z interfejsu API Create a Keystore or Truststore, którego używasz do tworzenia magazynu kluczy:
curl -u orgAdminEmail:password -X POST -H "Content-Type: text/xml" \
-d '<KeyStore name="myTruststore"/>' \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores
Po utworzeniu magazynu zaufanych certyfikatów prześlij do niego certyfikat jako plik PEM, korzystając z interfejsu API Create an alias from a certificate PEM file:
curl -u orgAdminEmail:password -X POST -H "Content-Type: multipart/form-data" -F certFile="@cert.pem" \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/myTruststore/aliases?alias=myTruststore&format=keycertfile"
gdzie opcja -F określa ścieżkę do pliku PEM.
Sprawdzanie szczegółowych informacji o istniejącym magazynie kluczy lub magazynie zaufanych certyfikatów
Sprawdź, czy w Twoim środowisku są już jakieś magazyny kluczy, korzystając z interfejsu API List Keystores and Truststores (Lista magazynów kluczy i magazynów zaufanych certyfikatów):
curl -u orgAdminEmail:password -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores
W przypadku klientów korzystających z chmury domyślny magazyn kluczy jest udostępniany bezpłatnie organizacjom korzystającym z bezpłatnego okresu próbnego w środowiskach testowym i produkcyjnym. W przypadku obu środowisk powinny się wyświetlić te wyniki:
[ "freetrial" ]
Możesz użyć tego domyślnego magazynu kluczy do testowania interfejsów API i przekazywania ich na ścieżkę produkcyjną, ale przed wdrożeniem na ścieżce produkcyjnej zwykle tworzysz własny magazyn kluczy z własnym certyfikatem i kluczem.
W przypadku klientów korzystających z chmury prywatnej 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 chmury powinien być widoczny jeden certyfikat TLS serwera – domyślny certyfikat, który Apigee Edge udostępnia na potrzeby bezpłatnych kont próbnych.
curl -u orgAdminEmail:password -X GET\
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/freetrial
Odpowiedź powinna wyglądać tak:
{ "certs" : [ "wildcard.apigee.net.crt" ], "keys" : [ "freetrial" ], "name" : "freetrial" }
Wyświetlanie szczegółowych informacji o aliasie
Aby uzyskać listę wszystkich aliasów dla magazynów kluczy, użyj interfejsu API List aliases:
curl -u orgAdminEmail:password -X GET \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases"
Odpowiedź powinna wyglądać tak:
[ "alias1", "alias2", "alias3", ]
Aby uzyskać wszystkie informacje o aliasie, takie jak data ważności i wydawca, użyj interfejsu Get alias i określ nazwę aliasu:
curl -u orgAdminEmail:password -X GET \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases/{alias_name}"
Odpowiedź powinna wyglądać tak:
{ "alias": "alias1", "certsInfo": { "certInfo": [ { "basicConstraints": "CA:TRUE", "expiryDate": 1459371335000, "isValid": "No", "issuer": "EMAILADDRESS=foo@bar.com, CN=smg, OU=doc, O=Internet Widgits Pty Ltd, L=noho, ST=Some-State, C=AU", "publicKey": "RSA Public Key, 1024 bits", "serialNumber": "00:86:a0:9b:5b:91:a9:fe:92", "sigAlgName": "SHA256withRSA", "subject": "EMAILADDRESS=foo@bar.com, CN=smg, OU=doc, O=Internet Widgits Pty Ltd, L=noho, ST=Some-State, C=AU", "subjectAlternativeNames": [], "validFrom": 1456779335000, "version": 3 } ], "certName": "new\-cert" }, "keyName": "newssl20" }
Aby pobrać certyfikat dla aliasu, użyj interfejsu API Export a certificate for an alias:
curl -u orgAdminEmail:password -X GET \
"https://api.enterprise.apigee.com/v1/e/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases/{alias_name}/certificate"
Odpowiedź powinna wyglądać tak:
-----BEGIN CERTIFICATE----- MIIDojCCAwugAwIBAgIJAIagm1uRqf6SMA0GCSqGSIb3DQEBCwUAMIGTMQswCQYD ... RBUkaTe/570sLHY0tvkIm5tEX36ESw== -----END CERTIFICATE-----
Jeśli masz certyfikat, który utracił ważność, i chcesz go odnowić, możesz pobrać żądanie podpisania certyfikatu. Następnie wysyłasz CSR do urzędu certyfikacji, aby uzyskać nowy certyfikat. Aby wygenerować CSR dla aliasu, użyj interfejsu API Generate a CSR for an alias:
curl -u orgAdminEmail:password -X GET \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases/{alias_name}/csr"
Odpowiedź powinna wyglądać tak:
-----BEGIN CERTIFICATE REQUEST----- MIIB1DCCAT0CAQAwgZMxCzAJBgNVBAYTAkFVMRMwEQYDVQQIEwpTb21lLVN0YXRl ... RF5RMytbkxkvPxIE17mDKJH0d8aekv/iEOItZ+BtQg+EibMUkkjTzQ== -----END CERTIFICATE REQUEST-----
Dodawanie certyfikatu do magazynu zaufanych certyfikatów na potrzeby dwukierunkowego protokołu TLS
W przypadku korzystania z dwukierunkowego protokołu TLS dla połączeń przychodzących, czyli żądań do interfejsu API wysyłanych do Edge, magazyn zaufanych certyfikatów zawiera certyfikat lub łańcuch certyfikatów urzędu certyfikacji dla każdego klienta, który może wysyłać żądania do Edge.
Podczas wstępnej konfiguracji magazynu zaufanych certyfikatów możesz dodać wszystkie certyfikaty znanych klientów. Z czasem możesz jednak chcieć dodać do magazynu zaufanych certyfikatów dodatkowe certyfikaty w miarę dodawania nowych klientów.
Aby dodać nowe certyfikaty do magazynu zaufanych certyfikatów używanego w przypadku dwukierunkowego protokołu TLS:
- Upewnij się, że w hoście wirtualnym używasz odwołania do magazynu zaufanych certyfikatów.
- Prześlij nowy certyfikat do magazynu zaufanych certyfikatów, postępując zgodnie z instrukcjami w sekcji Tworzenie magazynu zaufanych certyfikatów.
Zaktualizuj odwołanie do magazynu zaufanych certyfikatów, aby ustawić tę samą wartość. Ta aktualizacja powoduje ponowne załadowanie przez Edge’a magazynu zaufanych certyfikatów i nowego certyfikatu.
Więcej informacji znajdziesz w artykule Modyfikowanie odniesienia.
Usuwanie magazynu kluczy/magazynu zaufanych certyfikatów lub aliasu
Usuwając magazyn kluczy lub magazyn zaufanych certyfikatów albo alias, musisz zachować ostrożność. Jeśli usuniesz magazyn kluczy, magazyn zaufanych certyfikatów lub alias używany przez host wirtualny, docelowy punkt końcowy lub serwer docelowy, wszystkie wywołania interfejsu API przez host wirtualny lub docelowy punkt końcowy/serwer docelowy zakończą się niepowodzeniem.
Zazwyczaj proces usuwania magazynu kluczy lub magazynu zaufanych certyfikatów albo aliasu wygląda tak:
- Utwórz nowy magazyn kluczy lub magazyn zaufanych certyfikatów albo alias, jak opisano powyżej.
- W przypadku połączeń przychodzących, czyli żądań interfejsu API wysyłanych do Edge, zaktualizuj konfigurację hosta wirtualnego, aby odwoływała się do nowego magazynu kluczy i aliasu klucza.
- W przypadku połączeń wychodzących, czyli z Apigee do serwera backendu:
- Zaktualizuj konfigurację TargetEndpoint dla wszystkich serwerów proxy interfejsu API, które odwoływały się do starego magazynu kluczy i aliasu klucza, aby odwoływały się do nowego magazynu kluczy i aliasu klucza. Jeśli element TargetEndpoint odwołuje się do serwera docelowego, zaktualizuj definicję serwera docelowego, aby odwoływała się do nowego magazynu kluczy i aliasu klucza.
- Jeśli magazyn kluczy i magazyn zaufanych certyfikatów są przywoływane bezpośrednio z definicji TargetEndpoint, musisz ponownie wdrożyć serwer proxy. Jeśli TargetEndpoint odwołuje się do definicji TargetServer, a definicja TargetServer odwołuje się do magazynu kluczy i magazynu zaufanych certyfikatów, nie musisz ponownie wdrażać serwera proxy.
- Sprawdź, czy serwery proxy interfejsu API działają prawidłowo.
- Usuń magazyn kluczy lub magazyn zaufanych certyfikatów albo alias.
Więcej informacji znajdziesz w artykule Aktualizowanie certyfikatu w aliasie.
Usuwanie magazynu kluczy lub magazynu zaufanych certyfikatów
Możesz usunąć magazyn kluczy lub magazyn zaufanych certyfikatów za pomocą interfejsu API Delete a Keystore or Truststore (Usuń magazyn kluczy lub magazyn zaufanych certyfikatów):
curl -u orgAdminEmail:password -X DELETE \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/myKeystoreName
Jeśli usuniesz i ponownie utworzysz magazyn kluczy lub magazyn zaufanych certyfikatów używany przez hosta wirtualnego, musisz ponownie wdrożyć serwery proxy interfejsu API.
Usuwanie aliasu
Alias możesz usunąć z magazynu kluczy lub magazynu zaufanych certyfikatów za pomocą interfejsu API Delete alias:
curl -u orgAdminEmail:password -X DELETE \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/myKeystoreName/aliases/{alias_name}