Membuat keystore dan truststore untuk Private Cloud versi 4.17.09 dan yang lebih lama

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 Private Cloud versi 4.17.09 dan yang lebih lama.

Tentang keystore dan truststore

Keystore dan truststore menentukan repositori sertifikat keamanan yang digunakan untuk enkripsi TLS. Perbedaan utama antara keduanya adalah tempat penggunaannya dalam proses TLS handshaking:

  • Keystore berisi sertifikat TLS dan kunci pribadi yang digunakan untuk mengidentifikasi entitas selama TLS handshake.

    Dalam TLS satu arah, saat klien terhubung ke endpoint TLS di server, keystore server akan memberikan sertifikat server (sertifikat publik) kepada klien. Klien kemudian memvalidasi sertifikat tersebut dengan Certificate Authority (CA), seperti Symantec atau VeriSign.

    Dalam TLS dua arah, klien dan server mempertahankan keystore dengan sertifikat dan kunci pribadi mereka sendiri yang digunakan untuk autentikasi bersama.
  • truststore berisi sertifikat yang digunakan untuk memverifikasi sertifikat yang diterima sebagai bagian dari TLS handshake.

    Dalam TLS satu arah, truststore tidak diperlukan jika sertifikat ditandatangani oleh CA yang valid. Jika sertifikat yang diterima oleh klien TLS ditandatangani oleh CA yang valid, klien akan membuat permintaan ke CA untuk mengautentikasi sertifikat. Klien TLS biasanya menggunakan truststore untuk memvalidasi sertifikat yang ditandatangani sendiri yang diterima dari server TLS, atau sertifikat yang tidak ditandatangani oleh CA tepercaya. Dalam skenario ini, klien mengisi truststore-nya dengan sertifikat yang dipercayainya. Kemudian, saat klien menerima sertifikat server, sertifikat yang masuk akan divalidasi berdasarkan sertifikat di truststore-nya.

    Misalnya, klien TLS terhubung ke server TLS yang menggunakan sertifikat yang ditandatangani sendiri. Karena merupakan sertifikat yang ditandatangani sendiri, klien tidak dapat memvalidasinya dengan CA. Sebagai gantinya, klien memuat sebelumnya sertifikat yang ditandatangani sendiri oleh server ke dalam truststore-nya. Kemudian, saat klien mencoba terhubung ke server, klien menggunakan truststore-nya untuk memvalidasi sertifikat yang diterima dari server.

    Untuk TLS dua arah, klien TLS dan server TLS dapat menggunakan truststore. Truststore diperlukan saat melakukan TLS dua arah ketika Edge bertindak sebagai server TLS.

Sertifikat dapat diterbitkan oleh certificate authority (CA), atau dapat ditandatangani sendiri oleh kunci pribadi yang Anda buat. Jika Anda memiliki akses ke CA, ikuti petunjuk yang diberikan oleh CA Anda untuk membuat kunci dan menerbitkan sertifikat. Jika tidak memiliki akses ke CA, Anda dapat membuat sertifikat yang ditandatangani sendiri menggunakan salah satu dari banyak alat gratis yang tersedia secara publik, seperti openssl.

Menerapkan keystore dan truststore di Edge

Di Edge, keystore berisi satu atau beberapa file JAR, dengan file JAR 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.
  • Kunci pribadi sebagai file PEM. Edge mendukung ukuran kunci hingga 2048 bit. Frasa sandi bersifat opsional.

Truststore mirip dengan keystore, kecuali karena hanya berisi sertifikat sebagai file PEM, tetapi tidak ada kunci pribadi.

Jika sertifikat adalah bagian dari rantai, maka keystore/truststore harus berisi semua sertifikat dalam rantai, baik sebagai file PEM individual maupun sebagai satu file. Jika Anda menggunakan satu file, maka sertifikat harus berurutan dengan sertifikat pertama dalam file adalah sertifikat yang digunakan untuk TLS, diikuti oleh rantai sertifikat, secara berurutan, ke sertifikat CA. Anda harus menyisipkan baris kosong di antara setiap sertifikat dalam file.

Edge menyediakan API yang Anda gunakan untuk membuat keystore dan truststore. API sebenarnya sama. Perbedaannya adalah saat Anda membuat keystore, Anda meneruskan file JAR yang berisi sertifikat dan kunci pribadi. Saat membuat truststore, Anda hanya meneruskan sertifikat sebagai file PEM.

Tentang format file sertifikat dan kunci

Contoh dalam dokumen ini menunjukkan sertifikat dan kunci TLS yang ditentukan sebagai file PEM, yang 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.

Jika Anda memiliki rantai sertifikat, dan ingin menggunakan rantai tersebut di keystore atau truststore, maka Anda dapat menggabungkan semua sertifikat ke dalam satu file PEM dengan baris baru di antara setiap sertifikat. Sertifikat harus berurutan dan sertifikat terakhir harus berupa sertifikat root atau intermediate certificate 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-----

Mendapatkan detail tentang keystore yang ada

Periksa lingkungan Anda untuk menemukan keystore yang ada menggunakan API List Keystores and Truststores:

curl -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores \
-u email:password

Untuk pelanggan cloud, keystore default disediakan untuk organisasi uji coba gratis di lingkungan pengujian dan produksi. Anda akan melihat hasil berikut untuk panggilan ini di kedua lingkungan:

[ "freetrial" ]

Anda dapat menggunakan keystore default ini untuk menguji API dan mengirimkan API ke produksi, tetapi biasanya Anda membuat keystore sendiri, dengan sertifikat dan kunci Anda sendiri, sebelum men-deploy ke produksi.

Untuk pelanggan Private Cloud, array yang ditampilkan akan kosong hingga Anda membuat keystore pertama.

Periksa isi keystore menggunakan API Get a Keystore or Truststore. Untuk pelanggan cloud, Anda akan melihat satu sertifikat TLS server--sertifikat default yang disediakan Apigee Edge untuk akun uji coba gratis.

curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/freetrial \
-u email:password

Responsnya akan muncul seperti:

{
 "certs" : [ "wildcard.apigee.net.crt" ],
 "keys" : [ "freetrial" ],
 "name" : "freetrial"
}

Anda juga dapat melihat informasi ini di UI pengelolaan Edge:

  1. Login ke UI pengelolaan Edge di https://enterprise.apigee.com (cloud) atau http://<ms-ip>:9000 (on-premise), dengan <ms-ip> adalah alamat IP node Management Server.
  2. Di menu UI pengelolaan Edge, pilih Admin > TLS Certificates.

Mendapatkan detail sertifikat TLS

Anda dapat menggunakan API Get Cert Details from a Keystore or Truststore untuk melihat detail tentang sertifikat TLS di keystore, seperti tanggal habis masa berlaku dan penerbit. Pertama, dapatkan nama sertifikat yang Anda minati. Contoh ini mengambil informasi untuk keystore yang disebut "freetrial".

curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/freetrial \
-u email:password

Contoh respons:

{
 "certs" : [ "wildcard.apigee.net.crt" ],
 "keys" : [ "freetrial" ],
 "name" : "freetrial"
}

Kemudian, gunakan nilai properti certs untuk mendapatkan detail sertifikat:

curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/freetrial/certs/wildcard.apigee.net.crt \
-u email:password

Contoh respons:

{
 "certInfo" : [ {
   "expiryDate" : "Wed, 23 Apr 2014 20:50:02 UTC",
   "isValid" : "Yes",
   "issuer" : "CN=Go Daddy Secure Certificate Authority - G2, OU=http://certs.godaddy.com/repository/, O=&quot;GoDaddy.com, Inc.&quot;, L=Scottsdale, ST=Arizona, C=US",
   "subject" : CN=*.example.apigee.net, OU=Domain Control Validated",
   "subjectAlternativeNames" : ["*.example.apigee.net","*.example.apigee.net" ],
   "validFrom" : "Tue, 15 Apr 2014 09:17:03 UTC",
   "version" : 3
 } ],
 "name" : "example.apigee.net.crt"
}

Anda juga dapat melihat informasi ini di UI pengelolaan Edge:

  1. Login ke UI pengelolaan Edge di https://enterprise.apigee.com (cloud) atau http://<ms-ip>:9000 (on-premise), dengan <ms-ip> adalah alamat IP node Management Server.
  2. Di menu UI pengelolaan Edge, pilih Admin > TLS Certificates.

Di UI Edge, Anda dapat menentukan seberapa jauh Edge menunjukkan bahwa sertifikat akan berakhir. Secara default, UI menandai sertifikat yang dijadwalkan akan berakhir dalam 10 hari ke depan.

Membuat keystore

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.

Membuat keystore adalah proses dua langkah:

  1. Buat file JAR yang berisi sertifikat dan kunci pribadi Anda.
  2. Buat keystore dan upload File JAR.

Buat file JAR yang berisi sertifikat dan kunci pribadi Anda

Buat file JAR dengan kunci pribadi, sertifikat, dan manifes Anda. File JAR harus berisi file dan direktori berikut:

/META-INF/descriptor.properties
myCert.pem
myKey.pem

Di direktori yang berisi pasangan kunci dan sertifikat Anda, buat direktori bernama /META-INF. Kemudian, buat file bernama descriptor.properties di /META-INF dengan konten berikut:

certFile={myCertificate}.pem
keyFile={myKey}.pem

Buat file JAR yang berisi pasangan kunci dan sertifikat Anda:

jar -cf myKeystore.jar myCert.pem myKey.pem

Tambahkan descriptor.properties ke file JAR Anda:

jar -uf myKeystore.jar META-INF/descriptor.properties

Buat keystore dan upload file JAR

Untuk membuat keystore di lingkungan, Anda hanya perlu menentukan nama keystore ke API Create a Keystore or Truststore. Nama hanya boleh berisi karakter alfanumerik:

curl -X POST -H "Content-Type: text/xml" \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores \
-d '<KeyStore name="myKeystore"/>' -u email:password

Contoh respons:

{
 "certs" : [ ],
 "keys" : [ ],
 "name" : "myKeystore"
}

Setelah membuat keystore bernama di lingkungan, Anda dapat mengupload file JAR yang berisi sertifikat dan kunci pribadi menggunakan Upload a JAR file to a Keystore API:

curl -X POST -H "Content-Type: multipart/form-data" \
-F file="@myKeystore.jar" -F password={key_pass} \ "https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/{myKeystore}/keys?alias={key_alias}" \
-u email:password

dengan opsi -F yang menentukan jalur ke file JAR.

Dalam panggilan ini, Anda menentukan dua parameter kueri:

  • alias - Mengidentifikasi sertifikat dan kunci di penyimpanan kunci. Saat membuat host virtual, Anda mereferensikan sertifikat dan kunci berdasarkan nama aliasnya.
  • password - Sandi untuk kunci pribadi. Hapus parameter ini jika kunci pribadi tidak memiliki sandi.

Pastikan keystore Anda diupload dengan benar:

curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myKeystore \
-u email:password

Contoh respons:

{  
 "certs" : [ "myCertificate" ],
 "keys" : [ "myKey" ],
 "name" : "myKeystore"
}

Membuat truststore

API yang Anda gunakan untuk membuat truststore sama dengan yang digunakan untuk membuat keystore. Satu-satunya perbedaannya adalah Anda meneruskan file sertifikat sebagai file PEM, bukan file JAR.

Jika sertifikat adalah bagian dari rantai, Anda harus mengupload semua sertifikat dalam rantai secara terpisah ke truststore, atau membuat satu file yang berisi semua sertifikat. Sertakan baris baru di antara setiap sertifikat dalam file. Sertifikat akhir biasanya ditandatangani oleh penerbit sertifikat. Misalnya, di truststore, 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 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.

Buat truststore kosong di lingkungan dengan menggunakan Create a Keystore or Truststore, API yang sama dengan yang Anda gunakan untuk membuat keystore:

curl -X POST -H "Content-Type: text/xml" -d \
'<KeyStore name="myTruststore"/>' \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores \
-u email:password

Upload sertifikat sebagai file PEM ke truststore menggunakan Upload a Certificate to a Truststore API:

curl -X POST -H "Content-Type: multipart/form-data" -F file="@trust.pem" \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myTruststore/certs?alias=myTruststore \
-u email:password

dengan opsi -F yang menentukan jalur ke file PEM.

Menghapus keystore atau truststore

Anda dapat menghapus keystore atau truststore menggunakan Delete a Keystore or Truststore API:

curl -X DELETE \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myKeystoreName \
-u email:password

Contoh respons:

{
 "certs" : [ ],
 "keys" : [ ],
 "name" : "myKeystoreName"
}

Jika Anda menghapus keystore atau truststore yang digunakan oleh host virtual atau target endpoint/target/server, semua panggilan API melalui host virtual atau target endpoint/target server akan gagal.