Membuat keystore dan truststore menggunakan UI Edge

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

Dokumen ini menjelaskan cara membuat, mengubah, dan menghapus keystore dan truststore untuk Edge untuk Cloud dan untuk 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 dari host virtual.

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 mengandalkan 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 entity 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 penggunaannya dalam handshake TLS:

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

Saat mengonfigurasi TLS untuk host virtual atau endpoint target, keystore dan truststore memberikan peran yang berbeda dalam proses TLS handshake. Saat mengonfigurasi endpoint target atau host virtual, Anda menentukan keystore dan truststore secara terpisah dalam tag <SSLInfo>, seperti yang ditunjukkan di bawah 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 saat sertifikat berakhir masa berlakunya. Alias berisi pasangan sertifikat/kunci yang digunakan untuk mengidentifikasi host virtual ke klien TLS yang mengakses host virtual. Dalam contoh ini, tidak ada truststore yang diperlukan.

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, tidak menentukan alias tertentu. Setiap alias di keystore berisi sertifikat, atau rantai sertifikat, yang digunakan sebagai bagian dari proses TLS handshake.

Format sertifikat yang didukung

* Sebaiknya gunakan PEM jika memungkinkan.

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

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

Tentang penerapan 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 certificate authority (CA), file yang berisi rantai sertifikat dengan 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 yang sertifikat terakhirnya ditandatangani oleh CA, atau sertifikat yang ditandatangani sendiri.

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

Tentang format file sertifikat dan kunci

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

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

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

atau:

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

Kemudian, file tersebut kompatibel dengan format PEM dan Anda dapat menggunakannya di keystore atau truststore tanpa mengonversinya ke file PEM.

Tentang rantai sertifikat

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

• Keystore - Jika sertifikat adalah bagian dari rantai, Anda harus membuat satu file yang berisi semua sertifikat dalam rantai. Sertifikat harus berurutan dan sertifikat terakhir harus berupa sertifikat root atau sertifikat perantara yang ditandatangani oleh sertifikat root.
• Truststore - Jika sertifikat adalah bagian dari rantai, Anda harus membuat satu file yang berisi semua sertifikat dan mengupload file tersebut ke alias, atau mengupload semua sertifikat dalam rantai secara terpisah ke truststore menggunakan alias yang berbeda untuk setiap sertifikat. Jika Anda menguploadnya sebagai satu sertifikat, sertifikat harus berurutan dan sertifikat terakhir harus berupa sertifikat root atau sertifikat perantara yang ditandatangani oleh sertifikat root.
• Jika Anda 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 sertifikat root atau sertifikat intermediate yang ditandatangani oleh sertifikat root:

-----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 ditampilkan sebagai file PKCS12/PFX, Anda dapat menggunakan perintah 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 bekerja dengan 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 autentikasi TLS dua arah, autentikasi klien berhasil saat server mengirim client_cert_1 ke klien sebagai bagian dari proses TLS handshake.

Atau, Anda memiliki sertifikat kedua, client_cert_2, yang ditandatangani oleh sertifikat yang sama, 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 mengizinkan 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, verifikasi TLS akan gagal.

Pertimbangan FIPS

Jika Anda 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 Keystores

Halaman TLS Keystores ditampilkan:

Seperti yang ditunjukkan pada gambar sebelumnya, halaman TLS Keystores 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 TLS Keystores.
2. Pilih Lingkungan (biasanya prod atau test).
3. Klik baris yang terkait dengan alias yang ingin Anda lihat.

   Detail untuk sertifikat dan kunci alias 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 Anda memiliki sertifikat yang masa berlakunya telah berakhir dan ingin memperbaruinya, Anda dapat mendownload Permintaan Penandatanganan Sertifikat (CSR). Kemudian, Anda mengirim CSR ke CA untuk mendapatkan sertifikat baru.
   • Perbarui sertifikat. Perhatian: Jika Anda memperbarui sertifikat yang saat ini digunakan oleh host virtual atau server target/endpoint target, Anda harus menghubungi Dukungan Apigee Edge untuk memulai ulang Router dan Pemroses Pesan. Cara yang direkomendasikan untuk memperbarui sertifikat adalah:
     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 Memperbarui sertifikat TLS untuk Cloud untuk mengetahui informasi selengkapnya.
     4. Hapus alias. Catatan: Jika Anda menghapus alias, dan saat ini digunakan oleh host virtual atau endpoint target, maka host virtual atau endpoint target akan gagal.

Membuat keystore/truststore dan alias

Anda dapat membuat keystore untuk digunakan sebagai TLS keystore atau TLS truststore. Keystore khusus 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 produksi, 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, Anda dapat membuat alias dan mengupload pasangan kunci/sertifikat (keystore) atau mengupload sertifikat saja (truststore) ke alias.

Untuk membuat keystore:

1. Akses halaman TLS Keystores.
2. Pilih Lingkungan (biasanya prod atau test).
3. Klik + Keystore.
4. Tentukan nama keystore. Nama hanya boleh berisi karakter alfanumerik.
5. Klik Tambahkan 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)
   • Membuat alias dari file PKCS12/PFX (khusus keystore)
   • Membuat alias dari sertifikat yang ditandatangani sendiri (khusus keystore)

Membuat alias dari sertifikat (khusus truststore )

Untuk membuat alias dari sertifikat:

1. Akses halaman TLS Keystores.
2. Posisikan kursor di atas keystore untuk menampilkan menu tindakan, lalu klik +.
3. Tentukan Nama Alias.
4. Di bagian Detail sertifikat, pilih Khusus Sertifikat di drop-down Jenis.
5. Klik Pilih File di samping File Sertifikat, buka file PEM yang berisi sertifikat, lalu klik Buka.
6. Secara default, API memeriksa untuk memastikan masa berlaku sertifikat belum habis. Pilih Izinkan Sertifikat yang Sudah Berakhir secara opsional 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 Keystores.
2. Posisikan kursor di atas keystore untuk menampilkan menu tindakan, lalu klik +.
3. Tentukan Nama Alias.
4. Di bagian Detail sertifikat, pilih File JAR di drop-down Jenis.
5. Klik Pilih File di samping File JAR, buka file JAR yang berisi sertifikat dan kunci, lalu klik Buka.
6. Jika kunci memiliki sandi, tentukan Sandi. Jika kunci tidak memiliki sandi, kosongkan kolom ini.
7. Secara default, API memeriksa untuk memastikan masa berlaku sertifikat belum habis. Pilih Izinkan Sertifikat yang Sudah Berakhir secara opsional untuk melewati validasi.
8. Pilih Simpan untuk mengupload kunci dan sertifikat serta membuat alias.

Membuat alias dari sertifikat dan kunci (khusus keystore)

Untuk membuat alias dari sertifikat dan kunci:

1. Akses halaman TLS Keystores.
2. Posisikan kursor di atas keystore untuk menampilkan menu tindakan, lalu klik +.
3. Tentukan Nama Alias.
4. Di bagian Detail sertifikat, pilih Sertifikat dan Kunci di drop-down Jenis.
5. Klik Pilih File di samping File Sertifikat, buka file PEM yang berisi sertifikat, lalu klik Buka.
6. Jika kunci memiliki sandi, tentukan Sandi Kunci. Jika kunci tidak memiliki sandi, kosongkan kolom ini.
7. Klik Pilih File di samping File Kunci, buka file PEM yang berisi kunci, lalu klik Buka.
8. Secara default, API memeriksa untuk memastikan masa berlaku sertifikat belum habis. Pilih Izinkan Sertifikat yang Sudah Berakhir secara opsional untuk melewati validasi.
9. Pilih Simpan untuk mengupload kunci dan sertifikat serta membuat alias.

Membuat alias dari file PKCS12/PFX (khusus keystore)

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

1. Akses halaman TLS Keystores.
2. Posisikan kursor di atas keystore untuk menampilkan menu tindakan, lalu klik +.
3. Tentukan Nama Alias.
4. Di bagian Detail sertifikat, pilih PKCS12/PFX di drop-down Jenis.
5. Klik Pilih File di samping PKCS12/PFX, buka file yang berisi kunci dan sertifikat, lalu klik Buka.
6. Jika kunci memiliki sandi, tentukan Sandi untuk file PKCS12/PFX. Jika kunci tidak memiliki sandi, kosongkan kolom ini.
7. Secara default, API memeriksa untuk memastikan masa berlaku sertifikat belum habis. Pilih Izinkan Sertifikat yang Sudah Berakhir secara opsional untuk melewati validasi.
8. Pilih Simpan untuk mengupload file dan membuat alias.

Membuat alias dari sertifikat yang ditandatangani sendiri (khusus keystore)

Untuk membuat alias yang menggunakan sertifikat yang ditandatangani sendiri, Anda harus mengisi formulir dengan informasi yang diperlukan untuk membuat sertifikat. Edge kemudian membuat sertifikat dan pasangan kunci pribadi, lalu menguploadnya ke alias.

Untuk membuat alias dari sertifikat yang ditandatangani sendiri:

1. Akses halaman TLS Keystores.
2. Posisikan kursor di atas keystore untuk menampilkan menu tindakan, lalu klik +.
3. Tentukan Nama Alias.
4. Di bagian Detail sertifikat, pilih Sertifikat yang Ditandatangani Sendiri di drop-down Jenis.
5. Isi formulir menggunakan tabel di bawah.
6. Pilih Save untuk membuat pasangan kunci pribadi dan sertifikat, lalu menguploadnya ke alias.

Di sertifikat yang dibuat, 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 ditampilkan sebagai dua tanggal: tanggal dimulainya periode validitas sertifikat dan tanggal berakhirnya periode validitas sertifikat. Keduanya dapat dienkode 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. UI Pengujian 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 Keystores.
2. Pilih Lingkungan (biasanya prod atau test).
3. Posisikan kursor Anda di atas keystore TLS yang ingin Anda uji untuk menampilkan menu tindakan, lalu klik Uji. Kotak dialog berikut akan muncul dan menampilkan nama truststore:
   
4. Masukkan nama host layanan backend.
5. Masukkan nomor port TLS (biasanya 443).
6. Tentukan Protokol atau Cipher secara opsional.
7. Pilih Uji.

Untuk menguji TLS dua arah:

1. Untuk truststore yang diinginkan, pilih tombol Uji.
2. Dalam kotak dialog, pilih Two Way untuk SSL Test Type. Kotak dialog berikut akan muncul:
   
3. Tentukan nama keystore yang digunakan dalam 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. Tentukan Protokol atau Cipher secara opsional.
8. Pilih Uji.

Menambahkan sertifikat ke truststore untuk TLS dua arah

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

Saat mengonfigurasi truststore untuk pertama kalinya, Anda dapat menambahkan semua sertifikat untuk klien yang dikenal. 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 menyetelnya ke nilai yang sama. Pembaruan 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 host virtual, endpoint target, atau server target, semua panggilan API melalui host virtual atau endpoint target/server 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 alias kunci dan keystore baru.
3. Untuk koneksi keluar, yaitu dari Apigee ke server backend:
   1. Perbarui konfigurasi TargetEndpoint untuk semua proxy API yang mereferensikan keystore dan alias kunci lama agar 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 dirujuk langsung dari definisi TargetEndpoint, Anda harus men-deploy ulang proxy. Jika TargetEndpoint mereferensikan definisi TargetServer, dan definisi TargetServer mereferensikan keystore dan truststore, maka tidak perlu men-deploy 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 memosisikan kursor di atas keystore atau trustore dalam daftar untuk menampilkan menu tindakan dan mengklik . Jika Anda menghapus keystore atau truststore yang sedang 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 Anda mengonversi host virtual dan endpoint target/server target untuk menggunakan keystore baru.

Menghapus alias

Anda dapat menghapus alias dengan memosisikan kursor di atas alias dalam daftar untuk menampilkan menu tindakan dan mengklik . Jika Anda menghapus alias 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 alias hingga Anda mengonversi host virtual dan endpoint/server target untuk menggunakan keystore dan alias baru.