Panduan Integrasi Modul Keamanan Hardware Southbound untuk Apigee Edge untuk Private Cloud

Versi Rilis: Edge untuk Private Cloud v4.53.01.02 Patch Release dan yang lebih baru.

Halaman ini menjelaskan cara mengonfigurasi koneksi TLS southbound (dari Pemroses Pesan Apigee ke layanan target backend) menggunakan Modul Keamanan Hardware (HSM) jaringan Entrust nShield® 5c.

Penafian Konten Pihak Ketiga: Halaman ini menyediakan langkah-langkah konfigurasi untuk hardware Entrust nShield terkait dengan integrasi Apigee Edge. Langkah-langkah ini didasarkan pada pola integrasi standar dan disediakan hanya untuk tujuan informasi. Konfigurasi Entrust dapat berubah sewaktu-waktu oleh produsen. Lihat Portal Dokumentasi Entrust resmi untuk mengetahui spesifikasi yang berwenang, konfigurasi keamanan, dan persyaratan hardware saat ini.

Ringkasan

Modul Keamanan Hardware (HSM) menyediakan lingkungan khusus yang diperkuat untuk penyimpanan kunci yang aman dan operasi kriptografi. Dengan mengintegrasikan Apigee Edge untuk Private Cloud dengan HSM Entrust nShield, Anda dapat mengamankan kunci pribadi yang digunakan dalam TLS southbound dan handshake mTLS.

Apigee mendukung integrasi HSM untuk traffic HTTPS southbound keluar di seluruh komponen berikut:

• Endpoint Target
• Server Target
• Kebijakan Service Callout
• Kebijakan Pencatatan Log Pesan
• Kebijakan JavaScript

Prasyarat

Pastikan prasyarat berikut terpenuhi sebelum mengonfigurasi integrasi HSM:

1. Persyaratan Versi Software

• Cluster Apigee Edge untuk Private Cloud harus berjalan di versi 4.53.01.02 atau yang lebih tinggi.
• Integrasi HSM disertakan secara native dalam versi RPM berikut (atau yang lebih tinggi):
  • 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. Konfigurasi infrastruktur dan sistem operasi

• OS yang menghosting cluster Edge untuk Private Cloud harus menonaktifkan FIPS.
• Klien HSM dan Security World harus diinstal dan dikonfigurasi di semua node Pemroses Pesan.
• Penting: Langkah-langkah ini harus dilakukan oleh pengguna apigee.

Pastikan penginstalan klien HSM dikonfigurasi dengan benar dan dapat diakses oleh pengguna apigee dengan menjalankan pengujian penginstalan CSP JCA/JCE standar yang disediakan dalam dokumentasi Entrust nShield resmi. Pastikan pengujian ini berhasil diselesaikan di semua node Pemroses Pesan.

Konfigurasi yang Didukung

Anda dapat mengonfigurasi Apigee untuk menggunakan HSM dalam dua mode:

1. Mode Campuran HSM (Direkomendasikan)

Dalam mode ini, hanya kunci pribadi (KeyStore) yang disimpan di HSM, sedangkan sertifikat tepercaya (TrustStore) tetap berada di penyimpanan software Apigee standar.

2. Mode HSM Penuh

Dalam mode ini, KeyStore (kunci pribadi) dan TrustStore (sertifikat tepercaya) disimpan di HSM. Mode ini didukung, tetapi dapat menimbulkan latensi tambahan.

Langkah 1: Mengaktifkan HSM di Pemroses Pesan

Lakukan langkah-langkah berikut di setiap node Pemroses Pesan, satu per satu:

1. Menghentikan Pemroses Pesan

apigee-service edge-message-processor stop

2. Memverifikasi File Data Keystore HSM

Pastikan File Data Keystore HSM (yang mereferensikan kunci yang dimuat di HSM) ada di node Pemroses Pesan dan dimiliki oleh pengguna apigee:

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

3. Membuat File Konfigurasi HSM

Buat atau perbarui file konfigurasi di /opt/apigee/hsm-config.properties. Tentukan lokasi dan sandi untuk keystore HSM dan (opsional) truststore.

Contoh konfigurasi (mendukung proxy HSM campuran dan penuh):

# 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

Tetapkan izin yang benar:

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

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

4. Mengonfigurasi Properti Pemroses Pesan

Buat atau edit /opt/apigee/customer/application/message-processor.properties dan tambahkan hal berikut:

# 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

Pastikan kepemilikan yang benar:

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

5. Mengonfigurasi Ulang dan Memulai Ulang

apigee-service edge-message-processor configure

apigee-service edge-message-processor restart

6. Memvalidasi Inisialisasi

Periksa log sistem /opt/apigee/var/log/edge-message-processor/logs/system.log untuk mengetahui pesan inisialisasi yang berhasil:

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

Langkah 2: Mengonfigurasi Proxy API

Perbarui blok SSLInfo dalam konfigurasi proxy API (TargetEndpoint, ServiceCallout, atau kebijakan). Gunakan awalan hsmref:// untuk mereferensikan penyimpanan yang dikelola HSM, dan ref:// (atau nama referensi standar) untuk penyimpanan software.

1. Konfigurasi Mode Campuran HSM (Direkomendasikan)

Menggunakan HSM untuk KeyStore (autentikasi klien) dan Software untuk TrustStore.

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

2. Konfigurasi HSM Penuh

Menggunakan HSM untuk KeyStore dan TrustStore.

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

Melewati Validasi Waktu Deployment

Untuk memfasilitasi deployment tanpa mengupload kunci pribadi ke database Cassandra Apigee, Apigee secara otomatis melewati pemeriksaan keberadaan keystore/truststore lingkungan selama deployment untuk referensi apa pun yang dimulai dengan awalan hsmref://.

Operasi: Menambahkan Keystore/Truststore HSM Baru

Untuk menambahkan keystore atau truststore HSM baru ke lingkungan yang sudah berjalan:

1. Muat kunci/sertifikat ke HSM fisik (lihat Memuat Keystore/Truststore ke HSM).
2. Salin File Data Keystore baru ke node Pemroses Pesan dan tetapkan kepemilikan ke apigee.
3. Perbarui /opt/apigee/hsm-config.properties di semua node Pemroses Pesan dengan referensi baru:

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

4. Mulai ulang Pemroses Pesan di setiap node:

   apigee-service edge-message-processor restart

5. Perbarui konfigurasi proxy API untuk menggunakan hsmref://new_keystore_ref baru dan deploy.

Menonaktifkan HSM Secara Global

Untuk menonaktifkan HSM:

1. Perbarui semua proxy aktif yang menggunakan hsmref:// agar menggunakan referensi software standar (ref://).
2. Di setiap node Pemroses Pesan, edit /opt/apigee/customer/application/message-processor.properties dan tetapkan:

   conf_system_apigee.hsm.enabled=false

3. Konfigurasi ulang dan mulai ulang Pemroses Pesan:

   apigee-service edge-message-processor configure

   apigee-service edge-message-processor restart

Batasan dan Peringatan

• Hardware yang didukung: Terbatas untuk HSM jaringan Entrust nShield 5c.
• Pemeliharaan: Pelanggan bertanggung jawab atas pemeliharaan server/klien HSM.
• Latensi: Latensi tambahan dapat terjadi karena negosiasi jaringan dengan HSM. Penggunaan Mode Campuran HSM akan mengurangi hal ini hingga batas tertentu.
• Mulai Ulang HSM: Jika hardserver HSM dimulai ulang, Anda harus memulai ulang edge-message-processor di node Pemroses Pesan yang terhubung.

Memuat Keystore/Truststore ke HSM

Lihat Portal Dokumentasi Entrust nShield resmi untuk mengetahui perintah keytool yang tepat yang diperlukan untuk mengimpor keystore PKCS12 atau sertifikat PEM ke HSM.

Untuk memastikan kompatibilitas dengan Apigee, file keystore HSM yang dihasilkan harus memenuhi persyaratan berikut:

• Direktori: Harus disimpan ke /opt/apigee/ (misalnya, /opt/apigee/hsmks.keystore)
• Izin: Harus dimiliki oleh pengguna apigee (chown apigee:apigee /opt/apigee/<filename>)
• Keterbacaan: Harus dapat dibaca oleh layanan edge-message-processor.

Referensi Error

Pemberitahuan Masalah Hukum

Entrust dan nShield adalah merek dagang atau merek dagang terdaftar Entrust Corporation atau afiliasinya. Semua merek dagang lain merupakan hak milik dari pemiliknya masing-masing.