Przewodnik po integracji modułu HSM z Apigee Edge w chmurze prywatnej

Wersja: Edge for Private Cloud w wersji 4.53.01.02 (poprawka) lub nowszej.

Z tej strony dowiesz się, jak skonfigurować połączenia TLS wychodzące (z procesorów wiadomości Apigee do usług docelowych backendu) za pomocą sprzętowych modułów zabezpieczeń (HSM) Entrust nShield® 5c.

Zastrzeżenie dotyczące treści osób trzecich: ta strona zawiera instrukcje konfigurowania sprzętu Entrust nShield w kontekście integracji z Apigee Edge. Te instrukcje są oparte na standardowych wzorcach integracji i mają charakter wyłącznie informacyjny. Konfiguracje Entrust mogą ulec zmianie przez producenta. Aby uzyskać wiarygodne specyfikacje, konfiguracje zabezpieczeń i aktualne wymagania sprzętowe, zapoznaj się z oficjalnym portalem dokumentacji Entrust nShield.

Przegląd

Sprzętowe moduły zabezpieczeń (HSM) zapewniają dedykowane, zabezpieczone środowisko do bezpiecznego przechowywania kluczy i operacji kryptograficznych. Dzięki integracji Apigee Edge for Private Cloud z HSM Entrust nShield możesz zabezpieczyć klucze prywatne używane w uzgadnianiu połączenia TLS i mTLS.

Apigee obsługuje integrację z HSM w przypadku wychodzącego ruchu HTTPS w tych komponentach:

• Docelowe punkty końcowe
• Serwery docelowe
• Zasady wywołania usługi
• Zasady rejestrowania wiadomości
• Zasady JavaScript

Wymagania wstępne

Zanim skonfigurujesz integrację z HSM, upewnij się, że spełniasz te wymagania wstępne:

1. Wymagania dotyczące wersji oprogramowania

• Klaster Apigee Edge for Private Cloud musi działać w wersji 4.53.01.02 lub nowszej.
• Integracja z HSM jest natywnie dostępna w tych wersjach RPM (lub nowszych):
  • edge-management-server-4.53.01-0.0.60380.noarch.rpm
  • edge-message-processor-4.53.01-0.0.60380.noarch.rpm
  • edge-gateway-4.53.01-0.0.60380.noarch.rpm

2. Konfiguracja infrastruktury i systemu operacyjnego

• System operacyjny hostujący klaster Edge for Private Cloud musi mieć wyłączony FIPS.
• Klient HSM i Security World muszą być zainstalowane i skonfigurowane na wszystkich węzłach procesora komunikatów.
• Ważne: te czynności musi wykonać użytkownik apigee.

Sprawdź, czy instalacja klienta HSM jest prawidłowo skonfigurowana i dostępna dla użytkownika apigee, uruchamiając standardowy test instalacji JCA/JCE CSP opisany w oficjalnej dokumentacji Entrust nShield. Upewnij się, że ten test zakończy się pomyślnie na wszystkich węzłach procesora komunikatów.

Obsługiwane konfiguracje

Apigee można skonfigurować tak, aby korzystało z HSM w 2 trybach:

1. Tryb mieszany HSM (zalecany)

W tym trybie tylko klucze prywatne (KeyStore) są przechowywane w HSM, a zaufane certyfikaty (TrustStore) pozostają w standardowych magazynach oprogramowania Apigee.

2. Tryb pełny HSM

W tym trybie zarówno KeyStore (klucze prywatne), jak i TrustStore (zaufane certyfikaty) są przechowywane w HSM. Ten tryb jest obsługiwany, ale może powodować dodatkowe opóźnienia.

Krok 1. Włącz HSM na procesorach wiadomości

Wykonaj te czynności na każdym węźle procesora komunikatów, po kolei:

1. Zatrzymaj procesor komunikatów

apigee-service edge-message-processor stop

2. Sprawdź plik danych magazynu kluczy HSM

Upewnij się, że plik danych magazynu kluczy HSM (odwołujący się do kluczy załadowanych w HSM) znajduje się w węźle procesora komunikatów i jest własnością użytkownika apigee:

chown apigee:apigee /opt/apigee/{name_of_the_Keystore_Data_File}

3. Utwórz plik konfiguracji HSM

Utwórz lub zaktualizuj plik konfiguracji w lokalizacji /opt/apigee/hsm-config.properties. Określ lokalizację i hasła do magazynów kluczy HSM oraz (opcjonalnie) magazynów zaufania.

Przykładowa konfiguracja (obsługująca zarówno mieszane, jak i pełne proxy HSM):

# HSM KeyStore Reference
hsm.property.unique_keystore_ref1.keystore.file.location=/opt/apigee/ks.keystore
hsm.property.unique_keystore_ref1.keystore.password=keystore_password

# HSM TrustStore Reference (Optional, only needed for Full HSM Mode)
hsm.property.unique_truststore_ref1.truststore.file.location=/opt/apigee/ts.truststore
hsm.property.unique_truststore_ref1.truststore.password=truststore_password

Ustaw prawidłowe uprawnienia:

chown apigee:apigee /opt/apigee/hsm-config.properties

chmod 600 /opt/apigee/hsm-config.properties

4. Skonfiguruj właściwości procesora komunikatów

Utwórz lub edytuj plik /opt/apigee/customer/application/message-processor.properties i dodaj te informacje:

# Enable HSM Integration
conf_system_apigee.hsm.enabled=true

# HSM Configuration File Path
conf_system_apigee.hsm.properties.file=/opt/apigee/hsm-config.properties

# Advanced Custom HSM Port Support (Optional, default is 9000/9001)
# conf_system_apigee.hsm.priv_port=9001
# conf_system_apigee.hsm.nonpriv_port=9000

Sprawdź, czy własność jest prawidłowa:

chown apigee:apigee /opt/apigee/customer/application/message-processor.properties

5. Zmień konfigurację i uruchom ponownie

apigee-service edge-message-processor configure

apigee-service edge-message-processor restart

6. Sprawdź poprawność inicjowania

Sprawdź, czy w dzienniku systemowym /opt/apigee/var/log/edge-message-processor/logs/system.log znajdują się komunikaty o pomyślnym inicjowaniu:

main INFO  SECURITY-CONTEXT - SSLPreEvaluationContext.isHSMConfigEnabled() : HSM_FLOW : HSM config is enabled
main INFO  SECURITY-CONTEXT - SSLPreEvaluationContext.loadProperties() : HSM_FLOW :  HSM config properties loaded from file /opt/apigee/hsm-config.properties

Krok 2. Skonfiguruj proxy interfejsu API

Zaktualizuj blok SSLInfo w konfiguracji proxy interfejsu API (TargetEndpoint, ServiceCallout lub zasady). Użyj prefiksu hsmref://, aby odwoływać się do magazynów zarządzanych przez HSM, oraz ref:// (lub standardowej nazwy odwołania) w przypadku magazynów oprogramowania.

1. Konfiguracja trybu mieszanego HSM (zalecana)

Używa HSM w przypadku KeyStore (uwierzytelnianie klienta) i oprogramowania w przypadku TrustStore.

<SSLInfo>
    <Enabled>true</Enabled>
    <ClientAuthEnabled>true</ClientAuthEnabled>
    <KeyStore>hsmref://unique_keystore_ref1</KeyStore>
    <TrustStore>ref://mySoftwareTrustStoreRef</TrustStore>
</SSLInfo>

2. Pełna konfiguracja HSM

Używa HSM zarówno w przypadku KeyStore, jak i TrustStore.

<SSLInfo>
    <Enabled>true</Enabled>
    <ClientAuthEnabled>true</ClientAuthEnabled>
    <KeyStore>hsmref://unique_keystore_ref1</KeyStore>
    <TrustStore>hsmref://unique_truststore_ref1</TrustStore>
</SSLInfo>

Omijanie weryfikacji podczas wdrażania

Aby ułatwić wdrożenie bez przesyłania kluczy prywatnych do bazy danych Cassandra Apigee, Apigee automatycznie pomija sprawdzanie istnienia magazynu kluczy/magazynu zaufanych certyfikatów środowiska podczas wdrożenia w przypadku każdego odwołania zaczynającego się od prefiksu hsmref://.

Operacje: dodawanie nowych magazynów kluczy/magazynów zaufania HSM

Aby dodać nowy magazyn kluczy lub magazyn zaufania HSM do istniejącego działającego środowiska:

1. Załaduj klucze/certyfikaty do fizycznego HSM (patrz Ładowanie magazynów kluczy/magazynów zaufania do HSM).
2. Skopiuj nowy plik danych magazynu kluczy do węzłów procesora komunikatów i ustaw własność na apigee.
3. Zaktualizuj plik /opt/apigee/hsm-config.properties we wszystkich węzłach procesora komunikatów o nowe odwołanie:

   hsm.property.new_keystore_ref.keystore.file.location=/opt/apigee/new_ks.keystore
   hsm.property.new_keystore_ref.keystore.password=new_password
       

4. Uruchom ponownie procesor komunikatów w każdym węźle:

   apigee-service edge-message-processor restart

5. Zaktualizuj konfigurację proxy interfejsu API, aby używać nowego hsmref://new_keystore_ref, i wdróż.

Wyłączanie HSM globalnie

Aby wyłączyć HSM:

1. Zaktualizuj wszystkie aktywne proxy używające hsmref://, aby używały standardowych odwołań do oprogramowania (ref://).
2. W każdym węźle procesora komunikatów edytuj plik /opt/apigee/customer/application/message-processor.properties i ustaw:

   conf_system_apigee.hsm.enabled=false

3. Zmień konfigurację i uruchom ponownie procesor komunikatów:

   apigee-service edge-message-processor configure

   apigee-service edge-message-processor restart

Ograniczenia i ostrzeżenia

• Obsługiwany sprzęt: tylko sieciowe HSM Entrust nShield 5c.
• Konserwacja: klienci są odpowiedzialni za konserwację serwera/klienta HSM.
• Opóźnienie: mogą wystąpić dodatkowe opóźnienia spowodowane negocjacjami sieciowymi z HSM. W pewnym stopniu można je ograniczyć, korzystając z trybu mieszanego HSM.
• Ponowne uruchomienie HSM: jeśli serwer HSM zostanie ponownie uruchomiony, musisz ponownie uruchomić edge-message-processor w połączonych węzłach procesora komunikatów.

Ładowanie magazynów kluczy/magazynów zaufania do HSM

Aby uzyskać dokładne keytool polecenia wymagane do zaimportowania magazynu kluczy PKCS12 lub certyfikatu PEM do HSM, zapoznaj się z oficjalnym portalem dokumentacji Entrust nShield.

Aby zapewnić zgodność z Apigee, wynikowe pliki magazynu kluczy HSM muszą spełniać te wymagania:

• Katalog: musi być zapisany w lokalizacji /opt/apigee/ (np./opt/apigee/hsmks.keystore).
• Uprawnienia: muszą należeć do użytkownika apigee (chown apigee:apigee /opt/apigee/<filename>)
• Czytelność: musi być czytelny dla usługi edge-message-processor.

Informacje o błędach

Informacje prawne

Entrust i nShield są znakami towarowymi lub zastrzeżonymi znakami towarowymi firmy Entrust Corporation lub jej podmiotów stowarzyszonych. Wszystkie pozostałe znaki towarowe należą do ich właścicieli.