Membuat keystore dan truststore menggunakan Edge management API

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.

Pengantar

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

Untuk pengantar keystore, trustore, dan alias, lihat Keystore dan Trustore.

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.

Untuk membuat keystore di lingkungan:

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

Untuk membuat keystore, tentukan nama keystore ke API Create a Keystore or Truststore. 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"
}

Mengupload sertifikat dan kunci sebagai file JAR

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

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

JAR keystore hanya dapat berisi tiga file tersebut. Jika Anda memiliki rantai sertifikat, semua sertifikat dalam rantai harus ditambahkan ke dalam satu file PEM, dengan sertifikat terakhir harus ditandatangani oleh CA root. Sertifikat harus ditambahkan ke file PEM dalam urutan yang benar, dengan baris kosong di antara setiap sertifikat, yang berarti:

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

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

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

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"

dengan opsi -F menentukan jalur ke file JAR.

Dalam panggilan ini, Anda menentukan:

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

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"
}

Mengupload sertifikat dan kunci sebagai file PEM

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

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

Dalam panggilan ini, Anda menentukan:

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

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"
}

Mengupload sertifikat dan kunci sebagai file PKCS12/PFX

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

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"

dengan opsi -F yang menentukan jalur ke file P12.

Dalam panggilan ini, Anda menentukan:

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

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 dan kunci yang ditandatangani sendiri

Anda dapat menggunakan API Buat alias dengan membuat sertifikat yang ditandatangani sendiri untuk membuat sertifikat dan kunci yang ditandatangani sendiri, lalu menguploadnya ke 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"

Responsnya akan muncul seperti:

{
  "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 yang digunakan untuk membuat keystore. Satu-satunya perbedaannya adalah Anda hanya mengupload file sertifikat, sebagai file PEM, ke truststore.

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. Anda harus menyisipkan baris 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, upload sertifikat tersebut dalam satu 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 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. 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 -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 membuat truststore, upload sertifikat sebagai file PEM ke truststore dengan menggunakan Buat alias dari file PEM sertifikat API:

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

Mendapatkan detail tentang keystore atau truststore yang ada

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

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

Responsnya akan muncul seperti:

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

Mendapatkan detail tentang alias

Dapatkan daftar semua alias untuk keystore dengan menggunakan List aliases API:

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

Responsnya akan muncul seperti:

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

Untuk mendapatkan semua informasi tentang alias, seperti tanggal habis masa berlaku dan penerbit, gunakan API Get alias 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}"

Responsnya akan muncul seperti:

{
  "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 mendownload sertifikat untuk alias, gunakan API Mengekspor sertifikat untuk alias:

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"

Responsnya akan muncul seperti:

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

Jika 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. Untuk membuat CSR untuk alias, gunakan API Buat CSR untuk 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"

Responsnya akan muncul seperti:

-----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, 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 di Buat 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.
    3. Pastikan proxy API Anda berfungsi dengan benar.
    4. Hapus keystore/truststore atau alias.

Lihat Memperbarui sertifikat dalam alias untuk mengetahui informasi selengkapnya.

Menghapus keystore atau truststore

Anda dapat menghapus keystore atau truststore menggunakan Delete a Keystore or 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 sedang digunakan oleh host virtual, Anda harus men-deploy ulang proxy API.

Menghapus alias

Anda dapat menghapus alias di keystore atau truststore menggunakan Delete 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}