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, memodifikasi, 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 TLS enkripsi. Perbedaan utama antara keduanya adalah di mana mereka digunakan dalam handshake TLS proses:

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

    Di 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 dengan Certificate Authority (CA), seperti Symantec atau VeriSign.

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

    Di 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, lalu klien membuat permintaan ke CA untuk mengotentikasi 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 {i>truststore<i} dengan sertifikat yang dipercaya. Kemudian, ketika klien menerima sertifikat server, sertifikat yang masuk akan memvalidasi dengan sertifikat di truststore-nya.

    Misalnya, klien TLS terhubung ke server TLS di mana server menggunakan tanda tangan elektronik, CA {i>root<i}. Karena merupakan sertifikat yang ditandatangani sendiri, klien tidak dapat memvalidasinya dengan CA. Sebagai gantinya, klien mempramuat sertifikat yang ditandatangani sendiri oleh server ke truststore-nya. Lalu: ketika klien mencoba untuk terhubung ke server, klien menggunakan {i>truststore<i} untuk memvalidasi sertifikat yang diterima dari server.

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

Sertifikat dapat diterbitkan oleh otoritas sertifikat (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 untuk umum, seperti openssl.

Mengimplementasikan 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 yang ditandatangani sendiri sertifikat.
  • Kunci pribadi sebagai file PEM. Edge mendukung ukuran kunci hingga 2048 bit. Frasa sandi adalah opsional.

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

Jika sertifikat adalah bagian dari rantai, keystore/truststore harus berisi semua sertifikat di rantai, baik sebagai file PEM terpisah atau sebagai satu file. Jika Anda menggunakan satu file, maka sertifikat harus berurutan di mana sertifikat pertama dalam file adalah sertifikat yang digunakan untuk TLS 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 yang sebenarnya adalah hal yang sama. Perbedaannya adalah saat membuat keystore, Anda meneruskan file JAR yang berisi cert 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 dengan format X.509. Jika sertifikat atau kunci pribadi tidak ditentukan oleh file PEM, Anda dapat mengonversi 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.

Jika Anda memiliki rantai sertifikat, dan ingin menggunakan rantai itu di keystore atau truststore, Anda dapat menggabungkan semua sertifikat menjadi satu file PEM dengan satu baris baru di antara setiap sertifikat. Tujuan sertifikat harus berurutan dan sertifikat terakhir harus berupa root certificate atau intermediate cert 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 sudah ada

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

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 kedua platform lingkungan pengujian dan produksi. Anda akan melihat hasil berikut untuk panggilan ini untuk keduanya lingkungan:

[ "freetrial" ]

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

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

Periksa konten keystore menggunakan tombol Mendapatkan Keystore atau Truststore API. Untuk pelanggan cloud, Anda akan melihat TLS server tunggal certificate--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

Respons 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 (lokal), dengan <ms-ip> adalah IP ke node Server Pengelolaan.
  2. Di menu UI pengelolaan Edge, pilih Admin > TLS.

Mendapatkan detail sertifikat TLS

Anda dapat menggunakan Dapatkan Detail Sertifikat dari Keystore atau Truststore API untuk melihat detail tentang sertifikat TLS di keystore, seperti tanggal habis masa berlaku dan penerbit. Pertama, dapatkan nama sertifikat di yang Anda minati. Contoh ini mengambil informasi untuk keystore yang dipanggil "uji coba gratis".

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 sertifikat 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 (lokal), dengan <ms-ip> adalah IP ke node Server Pengelolaan.
  2. Di menu UI pengelolaan Edge, pilih Admin > TLS Sertifikat.

Di UI Edge, Anda dapat menentukan seberapa jauh Edge menunjukkan bahwa sertifikat berjalan masa berlaku habis. Secara default, UI menandai sertifikat apa pun yang dijadwalkan berakhir masa berlakunya hari.

Membuat keystore

Keystore khusus untuk lingkungan di organisasi Anda, misalnya untuk pengujian atau produksi lingkungan fleksibel App Engine. Oleh karena itu, jika Anda ingin menguji keystore di lingkungan pengujian sebelum men-deploy 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.

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 dengan nama /META-INF. Kemudian, buat file disebut descriptor.properties dalam /META-INF dengan hal berikut konten:

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 deskriptor.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 bagian Buat Keystore atau 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 bisa mengupload file JAR yang berisi sertifikat dan kunci pribadi dengan menggunakan perintah Upload file JAR ke 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

saat opsi -F menentukan jalur ke file JAR.

Dalam panggilan ini, Anda menetapkan dua parameter kueri:

  • alias - Mengidentifikasi sertifikat dan kunci di dalam {i>key store<i}. Saat Anda membuat {i>host<i} 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. Tujuan satu-satunya perbedaan adalah Anda meneruskan file sertifikat sebagai file PEM, bukan file JAR.

Jika sertifikat merupakan bagian dari suatu 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 final biasanya ditandatangani oleh penerbit sertifikat. Sebagai misalnya, di truststore, Anda mengupload sertifikat klien, client_cert_1, dan sertifikat klien sertifikat penerbit, ca_cert.

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

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

Saat server meneruskan client_cert_2 sebagai bagian dari handshake TLS, permintaan berhasil. Hal ini karena Edge memungkinkan verifikasi TLS berhasil saat client_cert_2 tidak ada di {i>truststore<i} tetapi ditandatangani oleh sertifikat yang ada di truststore. Jika Anda menghapus CA sertifikat, ca_cert, dari truststore maka verifikasi TLS gagal.

Buat truststore kosong di lingkungan menggunakan Membuat Keystore atau 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 dengan menggunakan Upload Sertifikat ke 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

saat opsi -F menentukan jalur ke file PEM.

Menghapus keystore atau truststore

Anda dapat menghapus keystore atau truststore dengan menggunakan Menghapus Keystore atau 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 target atau host virtual endpoint/target/server, semua panggilan API melalui virtual host atau server endpoint/target akan gagal..