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 keduanya digunakan dalam proses TLS handshake:

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

    Dalam TLS satu arah, saat klien terhubung ke endpoint TLS di server, keystore server akan menampilkan 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 dengan sertifikat yang dipercayainya. Kemudian, saat klien menerima sertifikat server, sertifikat yang masuk akan divalidasi dengan sertifikat di truststore-nya.

    Misalnya, klien TLS terhubung ke server TLS tempat server menggunakan sertifikat yang ditandatangani sendiri. Karena merupakan sertifikat yang ditandatangani sendiri, klien tidak dapat memvalidasinya dengan CA. Sebagai gantinya, klien memuat sertifikat server yang ditandatangani sendiri 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 saat 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 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 dengan sertifikat terakhir 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 bahwa truststore hanya berisi sertifikat sebagai file PEM, tetapi tidak berisi kunci pribadi.

Jika sertifikat adalah bagian dari rantai, keystore/truststore harus berisi semua sertifikat dalam rantai, baik sebagai file PEM individual maupun sebagai satu file. Jika Anda menggunakan satu file, sertifikat harus berurutan dengan sertifikat pertama dalam file adalah sertifikat yang digunakan untuk TLS, diikuti dengan 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 yang sebenarnya sama. Perbedaannya adalah saat 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 kunci dan sertifikat

Contoh dalam dokumen ini menunjukkan sertifikat dan kunci TLS yang ditentukan sebagai file PEM, yang 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 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 memiliki rantai sertifikat, dan ingin menggunakan rantai tersebut di keystore atau truststore, 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 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-----

Mendapatkan detail tentang keystore yang ada

Periksa keystore yang ada di lingkungan Anda 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 untuk kedua lingkungan:

[ "freetrial" ]

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

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

Periksa konten keystore menggunakan API Get a Keystore or Truststore. Untuk pelanggan cloud, Anda akan melihat satu sertifikat TLS server, yaitu 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 sebagai:

{
 "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 Server Pengelolaan.
  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 Server Pengelolaan.
  2. Di menu UI pengelolaan Edge, pilih Admin > TLS Certificates.

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

Membuat keystore

Keystore bersifat khusus untuk lingkungan di organisasi Anda, misalnya lingkungan pengujian atau produksi. Oleh karena itu, jika ingin menguji keystore di lingkungan pengujian sebelum men-deploynya ke lingkungan produksi, Anda harus membuatnya di kedua lingkungan tersebut.

Membuat keystore adalah proses dua langkah:

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

Membuat 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

Membuat keystore dan mengupload file JAR

Untuk membuat keystore di lingkungan, Anda hanya perlu menentukan nama keystore ke Create a Keystore or Truststore API. 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 API Upload file JAR ke Keystore:

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 menentukan jalur ke file JAR.

Dalam panggilan ini, Anda menentukan dua parameter kueri:

  • alias - Mengidentifikasi sertifikat dan kunci di keystore. Saat membuat host virtual, Anda mereferensikan sertifikat dan kunci dengan 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 perbedaan 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.

Saat 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 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 API Upload Sertifikat ke Truststore:

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 menentukan jalur ke file PEM.

Menghapus keystore atau truststore

Anda dapat menghapus keystore atau truststore menggunakan API Hapus Keystore atau Truststore:

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 endpoint/target/server target, semua panggilan API melalui host virtual atau endpoint/target server target akan gagal.