Membuat keystore dan truststore menggunakan UI Edge

Anda sedang melihat dokumentasi Apigee Edge.
Buka Dokumentasi Apigee X. info

Dokumen ini menjelaskan cara membuat, memodifikasi, dan menghapus keystore dan truststore untuk Edge untuk Cloud dan Edge untuk Private Cloud versi 4.18.01 dan yang lebih baru.

Tentang keystore/truststore dan host virtual untuk Edge Cloud

Proses pembuatan keystore/truststore untuk Edge Cloud mengharuskan Anda mengikuti semua aturan tentang penggunaan host virtual. Misalnya, dengan host virtual di Cloud:

• Host virtual harus menggunakan TLS.
• Host virtual hanya dapat menggunakan port 443.
• Anda harus menggunakan sertifikat TLS yang ditandatangani. Sertifikat yang tidak ditandatangani tidak diizinkan untuk digunakan dengan host virtual di Cloud.
• Nama domain yang ditentukan oleh sertifikat TLS harus cocok dengan alias host virtual host.

Pelajari lebih lanjut:

• Tentang TLS/SSL
• Menggunakan TLS dengan Edge
• FAQ Mengonfigurasi Host Virtual
• Tentang host virtual

Menerapkan keystore dan truststore di Edge

Untuk mengonfigurasi fungsi yang bergantung pada infrastruktur kunci publik, seperti TLS, Anda perlu membuat keystore dan truststore yang berisi kunci dan sertifikat digital yang diperlukan.

Di Edge, keystore dan truststore diwakili oleh entitas keystore yang berisi satu atau beberapa alias. Artinya, tidak ada perbedaan penerapan antara keystore dan truststore di Edge.

Perbedaan antara keystore dan truststore berasal dari jenis entri yang dikandungnya dan cara entri tersebut digunakan dalam TLS handshaking:

• keystore - entitas keystore yang berisi satu atau beberapa alias, dengan setiap alias berisi pasangan sertifikat/kunci.
• truststore - entitas keystore yang berisi satu atau beberapa alias, dengan setiap alias hanya berisi sertifikat.

Saat mengonfigurasi TLS untuk host virtual atau endpoint target, keystore dan truststore menyediakan peran yang berbeda dalam proses {i>handshake<i} TLS. Saat mengonfigurasi host atau target virtual Anda akan menentukan keystore dan truststore secara terpisah di <SSLInfo> seperti yang ditunjukkan di bawah ini untuk host virtual:

<VirtualHost name="myTLSVHost"> 
    <HostAliases> 
        <HostAlias>apiTLS.myCompany.com</HostAlias> 
    </HostAliases> 
    <Interfaces/> 
    <Port>9006</Port> 
    <SSLInfo> 
        <Enabled>true</Enabled> 
        <ClientAuthEnabled>false</ClientAuthEnabled> 
        <KeyStore>ref://keystoreref</KeyStore> 
        <KeyAlias>myKeyAlias</KeyAlias> 
    </SSLInfo>
</VirtualHost>

Dalam contoh ini, Anda menentukan nama keystore dan alias yang digunakan oleh host virtual untuk keystore TLS-nya. Anda menggunakan referensi untuk menentukan nama keystore sehingga Anda dapat mengubahnya nanti ketika sertifikat kedaluwarsa. Alias berisi pasangan kunci/sertifikat yang digunakan untuk mengidentifikasi host virtual ke klien TLS yang mengakses host virtual. Dalam contoh ini, tidak diperlukan truststore.

Jika truststore diperlukan, misalnya untuk konfigurasi TLS 2 arah, gunakan tag <TrustStore> untuk menentukan truststore:

<VirtualHost name="myTLSVHost"> 
    <HostAliases> 
        <HostAlias>apiTLS.myCompany.com</HostAlias> 
    </HostAliases> 
    <Interfaces/> 
    <Port>9006</Port> 
    <SSLInfo> 
        <Enabled>true</Enabled> 
        <ClientAuthEnabled>true</ClientAuthEnabled> 
        <KeyStore>ref://keystoreref</KeyStore> 
        <KeyAlias>myKeyAlias</KeyAlias> 
        <TrustStore>ref://truststoreref</TrustStore>
    </SSLInfo>
</VirtualHost>

Dalam contoh ini, tag <TrustStore> hanya mereferensikan keystore, memang tidak menyebutkan alias tertentu. Setiap alias di keystore berisi sertifikat, atau rantai sertifikat, yang digunakan sebagai bagian dari proses TLS handshaking.

Format sertifikat yang didukung

* Sebaiknya gunakan PEM jika memungkinkan.

Menggunakan keystore PKCS12 dengan Edge untuk Private Cloud 4.53.00 atau yang lebih baru

Jika menggunakan Edge untuk Private Cloud 4.53.00 atau yang lebih baru, Anda sebaiknya hanya menggunakan keystore PKCS12 untuk mengupload kunci dan sertifikat terkait ke Apigee. Untuk mendapatkan bantuan terkait mengonversi kunci dan sertifikat yang ada ke format PKCS12/PFX, lihat Mengonversi sertifikat ke format yang didukung.

Tentang menerapkan alias

Di Edge, keystore berisi satu atau beberapa alias, dengan setiap alias berisi:

• Sertifikat TLS sebagai file PEM atau PKCS12/PFX - baik sertifikat yang ditandatangani oleh sertifikat authority (CA), file yang berisi rantai sertifikat tempat sertifikat terakhir ditandatangani oleh CA, atau sertifikat yang ditandatangani sendiri.
• Kunci pribadi sebagai file PEM atau PKCS12/PFX. Edge mendukung ukuran kunci hingga 2048 bit. Frasa sandi bersifat opsional.

Di Edge, truststore berisi satu atau beberapa alias, dengan setiap alias berisi:

• Sertifikat TLS sebagai file PEM - baik sertifikat yang ditandatangani oleh certificate authority (CA), rantai sertifikat dengan sertifikat terakhir ditandatangani oleh CA, atau sertifikat yang ditandatangani sendiri.

Edge menyediakan UI dan API yang Anda gunakan untuk membuat keystore, membuat alias, mengupload sertifikat/kunci pasangan, dan memperbarui sertifikat. UI dan API yang Anda gunakan untuk membuat truststore sama dengan yang Anda gunakan untuk membuat keystore. Perbedaannya adalah saat membuat truststore, Anda membuat alias yang hanya berisi sertifikat.

Tentang format sertifikat dan kunci file

Anda dapat mewakili sertifikat dan kunci sebagai file PEM atau sebagai file PKCS12/PFX. File PEM mematuhi format X.509. Jika sertifikat atau kunci pribadi tidak ditentukan oleh file PEM, Anda dapat mengonversinya ke file PEM menggunakan utilitas seperti openssl.

Namun, banyak file .crt dan file .key sudah dalam format PEM. Jika file ini berupa teks file, dan disertakan dalam:

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

atau:

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

File tersebut akan kompatibel dengan format PEM dan Anda dapat menggunakannya dalam keystore atau truststore tanpa mengonversinya menjadi file PEM.

Tentang jaringan sertifikat

Jika sertifikat adalah bagian dari rantai, Anda menanganinya secara berbeda berdasarkan apakah sertifikat tersebut digunakan dalam keystore atau di truststore:

• Keystore - Jika sertifikat adalah bagian dari rantai, Anda harus membuat satu file yang berisi semua sertifikat dalam rantai tersebut. Sertifikat harus berurutan dan sertifikat terakhir harus berupa root atau sertifikat perantara yang ditandatangani oleh sertifikat {i>root<i}.
• Truststore - Jika sertifikat adalah bagian dari rantai, Anda harus membuat satu file yang berisi semua sertifikat dan mengunggah file tersebut ke alias, atau unggah semua sertifikat dalam rantai secara terpisah ke truststore menggunakan alias yang berbeda untuk setiap sertifikat. Jika Anda mengunggahnya sebagai satu sertifikat, sertifikat harus berurutan dan sertifikat terakhir harus berupa {i>root certificate<i} atau sertifikat perantara yang ditandatangani oleh {i>root certificate<i}.
• Jika membuat satu file yang berisi beberapa sertifikat, Anda harus menyisipkan baris kosong di antara setiap sertifikat.

Misalnya, Anda dapat menggabungkan semua sertifikat ke dalam satu file PEM. Sertifikat harus dalam urutan dan sertifikat terakhir harus berupa root certificate atau intermediate certificate yang ditandatangani oleh root certificate:

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

Jika sertifikat Anda dinyatakan sebagai file PKCS12/PFX, Anda dapat menggunakan openssl untuk membuat file PKCS12/PFX dari rantai sertifikat, seperti yang ditunjukkan di bawah ini:

openssl pkcs12 -export -out certificate.pfx -inkey privateKey.key -in certificate.crt -certfile CACert.crt

Saat menggunakan rantai sertifikat di truststore, Anda tidak selalu harus mengupload semua sertifikat dalam rantai. Misalnya, Anda mengupload sertifikat klien, client_cert_1, dan sertifikat penerbit sertifikat klien, ca_cert.

Selama otentikasi TLS dua arah, otentikasi klien berhasil ketika server mengirim client_cert_1 ke klien sebagai bagian dari proses handshake TLS.

Atau, Anda memiliki sertifikat kedua, client_cert_2, yang ditandatangani oleh ca_cert. Namun, Anda tidak mengupload client_cert_2 ke truststore. Truststore masih hanya berisi client_cert_1 dan ca_cert.

Jika server meneruskan client_cert_2 sebagai bagian dari TLS handshake, permintaan akan berhasil. Hal ini karena Edge memungkinkan verifikasi TLS berhasil saat client_cert_2 tidak ada di truststore, tetapi ditandatangani oleh sertifikat yang ada di truststore. Jika Anda menghapus sertifikat CA, ca_cert, dari truststore, lalu verifikasi TLS gagal.

Pertimbangan FIPS

Jika menggunakan Edge for Private Cloud 4.53.00 atau yang lebih baru di sistem operasi yang mendukung FIPS, Anda hanya boleh menggunakan keystore PKCS12 untuk mengupload kunci dan sertifikat terkait ke Apigee.

Menjelajahi halaman TLS Keystore

Halaman Keystore TLS akan ditampilkan:

Seperti yang ditandai pada gambar sebelumnya, halaman TLS Keystore memungkinkan Anda untuk:

• Pilih lingkungan
• Membuat keystore dan alias
• Menguji dan menghapus keystore
• Melihat dan menghapus alias

Melihat alias

Untuk melihat alias:

1. Akses halaman Keystore TLS.
2. Pilih Lingkungan (biasanya prod atau test).
3. Klik baris yang terkait dengan alias yang ingin Anda lihat.

   Detail untuk kunci dan sertifikat alias akan ditampilkan.
   
   Anda dapat melihat semua informasi tentang alias, termasuk tanggal habis masa berlakunya.

4. Kelola sertifikat menggunakan tombol di bagian atas halaman untuk:
   • Download sertifikat sebagai file PEM.
   • Buat CSR. Jika memiliki sertifikat yang sudah tidak berlaku dan ingin memperpanjangnya, Anda dapat mendownload Permintaan Penandatanganan Sertifikat (CSR). Anda kemudian mengirim CSR ke CA Anda untuk mendapatkan sertifikat.
   • Perbarui sertifikat. Perhatian: Jika Anda mengupdate sertifikat yang saat ini digunakan oleh host virtual atau server target/endpoint target, Anda harus menghubungi Dukungan Apigee Edge untuk memulai ulang Router dan Message Processor. Cara yang direkomendasikan untuk mengupdate sertifikat adalah dengan:
     1. Buat keystore atau truststore baru.
     2. Tambahkan sertifikat baru ke keystore atau truststore baru.
     3. Perbarui referensi di host virtual atau server target/endpoint target ke keystore atau truststore. Lihat Perbarui sertifikat TLS untuk Cloud untuk mendapatkan informasi lebih lanjut.
     4. Hapus alias. Catatan: Jika Anda menghapus alias, dan saat ini digunakan oleh host virtual atau endpoint target, host virtual atau endpoint target akan gagal.

Membuat keystore/truststore dan alias

Anda dapat membuat keystore untuk digunakan sebagai keystore TLS atau truststore TLS. Keystore spesifik untuk lingkungan di organisasi Anda, misalnya lingkungan pengujian atau produksi. Oleh karena itu, jika Anda ingin menguji keystore di lingkungan pengujian sebelum men-deploy-nya ke lingkungan production, Anda harus membuatnya di kedua lingkungan tersebut.

Untuk membuat keystore di lingkungan, Anda hanya perlu menentukan nama keystore. Setelah Anda membuat keystore bernama di lingkungan, lalu Anda bisa membuat alias dan mengupload pasangan sertifikat/kunci (keystore) atau hanya mengupload sertifikat (truststore) ke alias.

Untuk membuat keystore:

1. Akses halaman TLS Keystore.
2. Pilih Lingkungan (biasanya prod atau test).
3. Klik + Keystore.
4. Tentukan nama keystore. Nama hanya boleh berisi karakter alfanumerik.
5. Klik Add Keystore. Keystore baru akan muncul dalam daftar.
6. Gunakan salah satu prosedur berikut untuk menambahkan alias. Lihat juga Format file sertifikat yang didukung.
   • Membuat alias dari sertifikat (khusus truststore)
   • Membuat alias dari file JAR (khusus keystore)
   • Membuat alias dari sertifikat dan kunci (khusus keystore)
   • Buat alias dari file PKCS12/PFX (hanya keystore)
   • Membuat alias dari sertifikat yang ditandatangani sendiri (khusus keystore)

Membuat alias dari sertifikat (khusus truststore)

Untuk membuat alias dari sertifikat:

1. Akses halaman Keystore TLS.
2. Posisikan kursor di atas keystore untuk menampilkan menu tindakan, lalu klik +.
3. Tentukan Alias Name.
4. Di bagian Certificate details, pilih Certificate Only di drop-down Type.
5. Klik Choose File di samping Certificate File, lalu buka File PEM yang berisi sertifikat, lalu klik Buka.
6. Secara default, API memeriksa untuk memastikan masa berlaku sertifikat belum habis. Secara opsional, pilih Izinkan Masa Berlaku Sertifikat Habis untuk melewati validasi.
7. Pilih Simpan untuk mengupload sertifikat dan membuat alias.

Membuat alias dari file JAR (khusus keystore)

Untuk membuat alias dari file JAR:

1. Akses halaman TLS Keystore.
2. Arahkan kursor ke keystore untuk menampilkan menu tindakan, lalu klik +.
3. Tentukan Alias Name.
4. Pada detail Certificate, pilih JAR File di drop-down Type.
5. Klik Choose File di samping JAR File, buka file JAR yang berisi sertifikat dan kunci, lalu klik Open.
6. Jika kunci memiliki sandi, tentukan Sandi. Jika kunci tidak memiliki sandi, kosongkan kolom ini.
7. Secara default, API akan memeriksa untuk memastikan masa berlaku sertifikat belum berakhir. Secara opsional, pilih Izinkan Masa Berlaku Sertifikat Habis untuk melewati validasi.
8. Pilih Save untuk mengupload kunci dan sertifikat, lalu membuat alias.

Membuat alias dari sertifikat dan kunci (khusus keystore)

Untuk membuat alias dari sertifikat dan kunci:

1. Akses halaman Keystore TLS.
2. Arahkan kursor ke keystore untuk menampilkan menu tindakan, lalu klik +.
3. Tentukan Alias Name.
4. Di bagian Detail sertifikat, pilih Sertifikat dan Kunci di drop-down Jenis.
5. Klik Choose File di samping Certificate File, buka file PEM yang berisi sertifikat, lalu klik Open.
6. Jika kunci memiliki sandi, tentukan Key Password. jika kuncinya tidak memiliki {i>password<i}, kosongkan bidang ini.
7. Klik Pilih File di samping File Kunci, buka file PEM yang berisi kunci, lalu klik Buka.
8. Secara default, API akan memeriksa untuk memastikan masa berlaku sertifikat belum berakhir. Secara opsional, pilih Izinkan Sertifikat yang Berakhir Masa Berlakunya untuk melewati validasi.
9. Pilih Save untuk mengupload kunci dan sertifikat, lalu membuat alias.

Membuat alias dari File PKCS12/PFX (hanya keystore)

Untuk membuat alias dari file PKCS12 yang berisi sertifikat dan kunci:

1. Akses halaman Keystore TLS.
2. Arahkan kursor ke keystore untuk menampilkan menu tindakan, lalu klik +.
3. Tentukan Alias Name.
4. Di bagian Certificate details, pilih PKCS12/PFX di drop-down Type.
5. Klik Choose File di samping PKCS12/PFX, buka file yang berisi kunci dan sertifikat, lalu klik Open.
6. Jika kunci memiliki sandi, tentukan Sandi untuk file PKCS12/PFX. jika kunci tidak memiliki sandi, kosongkan bidang ini.
7. Secara default, API akan memeriksa untuk memastikan masa berlaku sertifikat belum berakhir. Secara opsional, pilih Izinkan Sertifikat yang Berakhir Masa Berlakunya untuk melewati validasi.
8. Pilih Simpan untuk mengupload file dan membuat alias.

Membuat alias dari sertifikat yang ditandatangani sendiri (hanya keystore)

Untuk membuat alias yang menggunakan sertifikat yang ditandatangani sendiri, isi formulir dengan informasi yang diperlukan untuk membuat sertifikat. Edge kemudian membuat sertifikat dan pasangan kunci pribadi serta menguploadnya ke alias.

Untuk membuat alias dari sertifikat yang ditandatangani sendiri:

1. Akses halaman Keystore TLS.
2. Arahkan kursor ke keystore untuk menampilkan menu tindakan, lalu klik +.
3. Tentukan Alias Name.
4. Pada bagian Certificate details, pilih Self-Signed Certificate di drop-down Jenis.
5. Isi formulir menggunakan tabel di bawah.
6. Pilih Save untuk membuat pasangan kunci pribadi dan sertifikat serta menguploadnya ke alias.

Dalam sertifikat yang dihasilkan, Anda akan melihat kolom tambahan berikut:

• Penerbit
  Entitas yang menandatangani dan menerbitkan sertifikat. Untuk sertifikat yang ditandatangani sendiri, ini adalah CN yang Anda tentukan saat membuat sertifikat.
• Validitas
  Periode validitas sertifikat yang direpresentasikan sebagai dua tanggal: tanggal dimulainya periode validitas sertifikat dan tanggal berakhirnya periode validitas sertifikat. Keduanya dapat denkode sebagai nilai UTCTime atau GeneralizedTime.

Tabel berikut menjelaskan kolom formulir:

Menguji keystore atau truststore

Anda dapat menguji truststore dan keystore di UI Edge untuk memverifikasi bahwa keduanya dikonfigurasi dengan benar. Test Ui memvalidasi permintaan TLS dari Edge ke layanan backend. Layanan backend dapat dikonfigurasi untuk mendukung TLS satu arah atau dua arah.

Untuk menguji TLS satu arah:

1. Akses halaman TLS Keystore.
2. Pilih Lingkungan (biasanya prod atau test).
3. Posisikan kursor Anda di atas keystore TLS yang ingin diuji untuk menampilkan menu tindakan, lalu klik Test. Kotak dialog berikut akan muncul yang menampilkan nama truststore:
   
4. Masukkan nama host layanan backend.
5. Masukkan nomor port TLS (biasanya 443).
6. (Opsional) Tentukan Protokol atau Penyandian.
7. Pilih Uji.

Untuk menguji TLS dua arah:

1. Untuk truststore yang diinginkan, pilih tombol Test.
2. Di kotak dialog, pilih Two Way untuk SSL Test Type. Kotak dialog berikut akan muncul:
   
3. Tentukan nama keystore yang digunakan di TLS dua arah.
4. Tentukan nama alias di keystore yang berisi sertifikat dan kunci.
5. Masukkan nama host layanan backend.
6. Masukkan nomor port TLS (biasanya 443).
7. (Opsional) Tentukan Protokol atau Penyandian.
8. Pilih Uji.

Menambahkan sertifikat ke truststore untuk TLS dua arah

Saat menggunakan TLS dua arah untuk koneksi masuk, artinya permintaan API ke Edge, truststore berisi sertifikat atau rantai CA untuk setiap klien yang diizinkan membuat permintaan ke Edge.

Saat pertama kali mengonfigurasi truststore, Anda dapat menambahkan semua sertifikat untuk klien yang diketahui. Namun, seiring waktu, Anda mungkin ingin menambahkan sertifikat tambahan ke truststore saat menambahkan klien baru.

Untuk menambahkan sertifikat baru ke truststore yang digunakan untuk TLS dua arah:

1. Pastikan Anda menggunakan referensi ke truststore di host virtual.
2. Upload sertifikat baru ke truststore seperti yang dijelaskan di atas dalam Membuat alias dari sertifikat (khusus truststore).

3. Perbarui referensi truststore untuk menetapkannya ke nilai yang sama. Update ini menyebabkan Edge memuat ulang truststore dan sertifikat baru.

   Lihat Mengubah referensi untuk mengetahui informasi selengkapnya.

Menghapus keystore/truststore atau alias

Anda harus berhati-hati saat menghapus keystore/truststore atau alias. Jika Anda menghapus keystore, truststore, atau alias yang digunakan oleh {i> virtual host<i}, titik akhir target, atau server target, semuanya Panggilan API melalui host virtual atau server endpoint/target target akan gagal.

Biasanya, proses yang Anda gunakan untuk menghapus keystore/truststore atau alias adalah:

1. Buat keystore/truststore atau alias baru seperti yang dijelaskan di atas.
2. Untuk koneksi masuk, yang berarti permintaan API ke Edge, perbarui konfigurasi host virtual untuk mereferensikan keystore dan alias kunci baru.
3. Untuk koneksi keluar, artinya dari Apigee ke server backend:
   1. Mengupdate konfigurasi TargetEndpoint untuk semua proxy API yang mereferensikan proxy lama keystore dan alias kunci untuk mereferensikan keystore dan alias kunci baru. Jika TargetEndpoint Anda mereferensikan TargetServer, perbarui definisi TargetServer untuk mereferensikan keystore dan alias kunci baru.
   2. Jika keystore dan truststore direferensikan langsung dari definisi TargetEndpoint, Anda harus men-deploy ulang proxy. Jika TargetEndpoint mereferensikan penentuan TargetServer, dan penentuan TargetServer mereferensikan keystore dan truststore, tidak perlu deployment ulang proxy.
4. Pastikan proxy API Anda berfungsi dengan benar.
5. Hapus keystore/truststore atau alias.

Menghapus keystore

Anda dapat menghapus keystore atau truststore dengan menempatkan kursor di atas keystore atau truststore dalam daftar untuk menampilkan menu tindakan dan mengklik . Jika Anda menghapus keystore atau truststore yang digunakan oleh host virtual atau endpoint target/server target, semua panggilan API melalui host virtual atau endpoint target/server target akan gagal.

Perhatian: Anda tidak boleh menghapus keystore hingga mengonversi host virtual dan endpoint target/server target untuk menggunakan keystore baru.

Menghapus alias

Anda dapat menghapus alias dengan mengarahkan kursor ke alias dalam daftar untuk menampilkan menu tindakan, lalu mengklik . Jika Anda menghapus alias yang digunakan oleh {i>host<i} virtual atau endpoint/server target target, semua panggilan API melalui host virtual atau endpoint/target target server akan gagal.

Perhatian: Anda tidak boleh menghapus alias hingga Anda mengonversi alias virtual Anda host dan endpoint/server target target untuk menggunakan keystore dan alias baru.