Membuat keystore dan truststore menggunakan Edge management API

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.

Pengantar

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

Untuk pengantar keystore, truststore, dan alias, lihat Keystore dan Truststore.

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.

Untuk membuat keystore di lingkungan:

  1. Gunakan panggilan API di bagian ini untuk membuat keystore.
  2. Buat alias dan upload pasangan sertifikat/kunci ke alias. Cara mengunggah sertifikat dan didasarkan pada format pasangan sertifikat/kunci. Bagian berikut menjelaskan cara mengupload setiap jenis pasangan sertifikat/kunci:

Untuk membuat keystore, tentukan nama keystore ke bagian Create a Keystore atau Truststore API. Nama keystore hanya boleh berisi karakter alfanumerik:

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

Contoh respons:

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

Upload sertifikat dan kunci sebagai file JAR

Anda harus membuat file JAR terlebih dahulu dengan kunci pribadi, sertifikat, dan manifes Anda. JAR file harus berisi file dan direktori berikut:

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

JAR keystore hanya bisa berisi tiga file tersebut. Jika Anda memiliki rantai sertifikat, semua sertifikat dalam rantai harus ditambahkan ke satu file PEM, di mana sertifikat terakhir harus ditandatangani oleh CA {i>root<i}. Sertifikat harus ditambahkan ke file PEM dalam urutan yang benar, dengan baris kosong di antara setiap sertifikat, artinya:

cert -> intermediate cert(1) -> intermediate cert(2) -> … -> root

Di direktori yang berisi pasangan kunci dan sertifikat Anda, buat direktori dengan nama /META-INF. Kemudian, buat file bernama deskriptor.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

Sekarang Anda dapat mengunggah file JAR yang berisi sertifikat dan kunci pribadi menggunakan perintah Buat alias dari file JAR atau PKCS API:

curl -u orgAdminEmail:password -X POST -H "Content-Type: multipart/form-data" -F file="@myKeystore.jar" -F password={key_pword} \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases?alias={alias_name}&format=keycertjar"

di mana opsi -F menentukan jalur ke file JAR.

Dalam panggilan ini, Anda menentukan:

  • alias_name - Mengidentifikasi sertifikat dan kunci di toko kunci. Saat Anda membuat {i>host<i} virtual, Anda mereferensikan sertifikat dan kunci berdasarkan nama alias.
  • key_pword - Sandi untuk kunci pribadi. Hapus parameter ini jika kunci pribadi tidak memiliki {i>password<i}.

Pastikan keystore Anda diupload dengan benar:

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

Contoh respons:

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

Upload sertifikat dan kunci sebagai file PEM

Upload file PEM yang berisi sertifikat dan kunci pribadi dengan menggunakan perintah Buat alias dari sertifikat dan file PEM utama API:

curl -u orgAdminEmail:password -X POST -H "Content-Type: multipart/form-data" -F keyFile="@server.key" -F certFile="@signed.crt" \
-F password={key_pword} \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases?alias={alias_name}&format=keycertfile"

dengan opsi -F menentukan jalur ke file PEM.

Dalam panggilan ini, Anda menentukan:

  • alias_name - Mengidentifikasi sertifikat dan kunci di toko kunci. Saat Anda membuat {i>host<i} virtual, Anda mereferensikan sertifikat dan kunci berdasarkan nama alias.
  • key_pword - Sandi untuk kunci pribadi. Hapus parameter ini jika kunci pribadi tidak memiliki {i>password<i}.

Pastikan keystore Anda diupload dengan benar:

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

Contoh respons:

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

Upload sertifikat dan kunci sebagai PKCS12/PFX file

Upload file PKCS12/PFX yang berisi sertifikat dan kunci pribadi dengan menggunakan Buat alias dari file JAR atau PKCS API:

curl -u orgAdminEmail:password -X POST -H "Content-Type: multipart/form-data" \
-F file="@myKeystore.p12" -F password={key_pword} \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases?alias={alias_name}&format=pkcs12"

di mana opsi -F menentukan jalur ke file P12.

Dalam panggilan ini, Anda menentukan:

  • alias_name - Mengidentifikasi sertifikat dan kunci di toko kunci. Saat Anda membuat {i>host<i} virtual, Anda mereferensikan sertifikat dan kunci berdasarkan nama alias.
  • key_pword - Sandi untuk kunci pribadi. Hapus parameter ini jika kunci pribadi tidak memiliki {i>password<i}.

Pastikan keystore Anda diupload dengan benar:

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

Contoh respons:

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

Membuat dan mengupload sertifikat yang ditandatangani sendiri, dan tombol

Anda dapat menggunakan Buat alias dengan membuat API sertifikat yang ditandatangani sendiri untuk membuat sertifikat yang ditandatangani sendiri dan dan mengunggahnya ke sebuah alias. Panggilan berikut hanya menentukan informasi yang diperlukan untuk membuat sertifikat yang ditandatangani sendiri. Anda dapat mengubah panggilan ini untuk menambahkan informasi tambahan:

curl -u orgAdminEmail:password -X POST --header "Content-Type: application/json"  \
-d "{
    "alias": "selfsigned",
    "subject": {
        "commonName": "mycert"
    }
}" \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases?format=selfsignedcert"

Respons akan muncul sebagai:

{
  "alias": "selfsigned",
  "certsInfo": {
    "certInfo": [
      {
        "basicConstraints": "CA:FALSE",
        "expiryDate": 1491497204000,
        "isValid": "Yes",
        "issuer": "CN=mycert",
        "publicKey": "RSA Public Key, 2048 bits",
        "serialNumber": "00:d1:b4:78:e1",
        "sigAlgName": "SHA256withRSA",
        "subject": "CN=mycert",
        "subjectAlternativeNames": [],
        "validFrom": 1459961204000,
        "version": 3
      }
    ],
    "certName": "selfsigned-cert"
  },
  "keyName": "selfsigned"
}

Membuat truststore

API yang Anda gunakan untuk membuat truststore sama dengan API yang digunakan untuk membuat keystore. Tujuan satu-satunya perbedaan adalah Anda hanya mengupload file sertifikat, sebagai file PEM, ke truststore.

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. Anda harus menyisipkan kolom kosong di antara setiap sertifikat dalam file.

Jika Anda ingin mengupload beberapa sertifikat yang ditandatangani sendiri yang bukan bagian dari rantai, gunakan teknik yang sama: jika ada beberapa sertifikat yang ingin Anda percayai, unggah dalam satu file.

Sertifikat final biasanya ditandatangani oleh penerbit sertifikat. Misalnya, di kolom truststore, mengupload sertifikat klien,client_cert_1, dan penerbit sertifikat klien sertifikat, {i>ca_cert<i}.

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 sertifikat yang sama, ca_cert. Namun, Anda tidak mengupload client_cert_2 ke truststore. {i>Truststore<i} masih berisi client_cert_1 dan ca_cert.

Saat server meneruskan client_cert_2 sebagai bagian dari handshake TLS, permintaan akan berhasil. Ini adalah 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 -u orgAdminEmail:password -X POST -H "Content-Type: text/xml" \
-d '<KeyStore name="myTruststore"/>' \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores

Setelah Anda membuat truststore, upload sertifikat sebagai file PEM ke truststore dengan menggunakan Buat alias dari API file PEM sertifikat:

curl -u orgAdminEmail:password -X POST -H "Content-Type: multipart/form-data" -F certFile="@cert.pem" \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/myTruststore/aliases?alias=myTruststore&format=keycertfile"

dengan opsi -F menentukan jalur ke file PEM.

Dapatkan detail tentang lokasi yang sudah ada keystore atau truststore

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

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

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 -u orgAdminEmail:password -X GET\
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/freetrial

Respons akan muncul sebagai:

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

Mendapatkan detail tentang alias

Dapatkan daftar semua alias untuk keystore dengan menggunakan Daftar alias API:

curl -u orgAdminEmail:password -X GET \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases"

Respons akan muncul sebagai:

[
  "alias1",
  "alias2",
  "alias3",
]

Untuk mendapatkan semua informasi tentang alias, seperti tanggal kedaluwarsa dan penerbit, gunakan Dapatkan alias API dan tentukan nama alias:

curl  -u orgAdminEmail:password -X GET \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases/{alias_name}"

Respons akan muncul sebagai:

{
  "alias": "alias1",
  "certsInfo": {
    "certInfo": [
      {
        "basicConstraints": "CA:TRUE",
        "expiryDate": 1459371335000,
        "isValid": "No",
        "issuer": "EMAILADDRESS=foo@bar.com, CN=smg, OU=doc, O=Internet Widgits Pty Ltd, L=noho, ST=Some-State, C=AU",
        "publicKey": "RSA Public Key, 1024 bits",
        "serialNumber": "00:86:a0:9b:5b:91:a9:fe:92",
        "sigAlgName": "SHA256withRSA",
        "subject": "EMAILADDRESS=foo@bar.com, CN=smg, OU=doc, O=Internet Widgits Pty Ltd, L=noho, ST=Some-State, C=AU",
        "subjectAlternativeNames": [],
        "validFrom": 1456779335000,
        "version": 3
      }
    ],
    "certName": "new\-cert"
  },
  "keyName": "newssl20"
}

Untuk mengunduh sertifikat bagi alias, gunakan Ekspor sertifikat untuk alias API:

curl -u orgAdminEmail:password -X GET \
"https://api.enterprise.apigee.com/v1/e/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases/{alias_name}/certificate"

Respons akan muncul sebagai:

-----BEGIN CERTIFICATE-----
MIIDojCCAwugAwIBAgIJAIagm1uRqf6SMA0GCSqGSIb3DQEBCwUAMIGTMQswCQYD
...
RBUkaTe/570sLHY0tvkIm5tEX36ESw==
-----END CERTIFICATE-----

Jika Anda memiliki sertifikat yang masa berlakunya habis dan ingin memperpanjangnya, Anda dapat mendownload fitur Penandatanganan Sertifikat Permintaan (CSR). Kemudian, Anda mengirimkan CSR ke CA Anda untuk mendapatkan sertifikat baru. Untuk membuat CSR untuk alias, gunakan Buat CSR untuk API alias:

curl -u orgAdminEmail:password -X GET \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases/{alias_name}/csr"

Respons akan muncul sebagai:

-----BEGIN CERTIFICATE REQUEST-----
MIIB1DCCAT0CAQAwgZMxCzAJBgNVBAYTAkFVMRMwEQYDVQQIEwpTb21lLVN0YXRl
...
RF5RMytbkxkvPxIE17mDKJH0d8aekv/iEOItZ+BtQg+EibMUkkjTzQ==
-----END CERTIFICATE REQUEST-----

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 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 di Membuat 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, artinya permintaan API ke Edge, perbarui konfigurasi host virtualnya 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 merujuk TargetServer, perbarui definisi TargetServer untuk mereferensikan keystore baru dan alias kunci.
    2. Jika keystore dan truststore direferensikan langsung dari TargetEndpoint maka Anda harus men-deploy ulang proxy tersebut. Jika TargetEndpoint mereferensikan Definisi TargetServer, dan definisi TargetServer merujuk pada keystore dan truststore, maka deployment ulang proxy tidak diperlukan.
    3. Pastikan proxy API Anda berfungsi dengan benar.
    4. Hapus keystore/truststore atau alias.

Lihat Perbarui sertifikat dengan alias untuk mengetahui informasi selengkapnya.

Menghapus keystore atau truststore

Anda dapat menghapus keystore atau truststore dengan menggunakan Menghapus Keystore atau Truststore API:

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

Jika Anda menghapus dan membuat ulang keystore atau truststore yang digunakan oleh host virtual, maka Anda harus men-deploy ulang proxy API.

Menghapus alias

Anda dapat menghapus alias di keystore atau truststore menggunakan parameter Menghapus alias API:

curl -u orgAdminEmail:password -X DELETE \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/myKeystoreName/aliases/{alias_name}