Cara Membuat CSR untuk Code Signing Certificate Dengan Java Keytool

Utilitas keytool yang disertakan dengan Java Development Kit (JDK) membuat pasangan kunci di dalam keystore Java dan mengubahnya menjadi CSR (Certificate Signing Request), blok terenkode yang dibaca oleh Certificate Authority (CA) untuk mengidentifikasi Anda sebelum menerbitkan sertifikat. Untuk penandatanganan kode (code signing), penggunaan keytool yang sah secara hukum berubah pada 1 Juni 2023. Panduan ini menjelaskan aturannya terlebih dahulu, lalu membahas perintah keytool yang masih benar: terhadap keystore perangkat lunak untuk penandatanganan internal, dan terhadap token perangkat keras atau HSM melalui PKCS#11.

Kunci code signing harus dibuat pada perangkat keras

Sejak 1 Juni 2023, CA/Browser Forum Code Signing Baseline Requirements mewajibkan kunci privat untuk setiap sertifikat code signing yang dipercaya publik dibuat dan disimpan dalam modul kripto perangkat keras yang memenuhi standar FIPS 140-2 Level 2, Common Criteria EAL4+, atau standar setara lainnya. Kunci tersebut harus non-exportable (tidak dapat diekspor). Ini berlaku untuk sertifikat standar (Organization Validation) maupun sertifikat Extended Validation. EV code signing selalu memerlukan perangkat keras; perubahan tahun 2023 memperluas aturan yang sama ke sertifikat standar. Persyaratan yang sama juga menetapkan ukuran kunci minimum RSA 3072 untuk sertifikat code signing, berlaku sejak 1 Juni 2021.

Konsekuensi untuk halaman ini bersifat langsung. File keystore yang dibuat keytool di laptop atau server Anda, baik dalam format PKCS12 maupun format JKS yang lebih lama, menyimpan kunci perangkat lunak. CSR yang dihasilkan darinya tidak diterima oleh Certificate Authority publik untuk sertifikat code signing. Certificate Authority telah berhenti mendukung pembuatan kunci berbasis browser dan file kunci yang dapat diunduh untuk produk-produk ini. Kunci Anda sekarang berasal dari salah satu dari dua tempat:

• Token yang telah dikonfigurasi sebelumnya oleh CA. CA membuat pasangan kunci dan CSR pada token USB tersertifikasi di pihaknya, memuat sertifikat yang diterbitkan ke dalamnya, lalu mengirimkan token tersebut kepada Anda. Tidak ada CSR yang perlu Anda buat sendiri.
• HSM atau token milik Anda sendiri, dengan atestasi kunci. Anda membuat kunci di dalam perangkat, menghasilkan CSR darinya, dan mengirimkan file atestasi yang membuktikan kepada CA bahwa kunci tersebut dibuat pada perangkat keras yang sesuai standar dan tidak dapat diekspor. Kedua bagian ini diperlukan; CSR tanpa atestasi yang valid akan ditolak.

Jalur mana yang berlaku ditentukan saat Anda melakukan pemesanan. Untuk perbandingannya, lihat metode pengiriman sertifikat code signing. Jika Anda sudah memiliki perangkat keras yang sesuai standar, ikuti panduan untuk perangkat Anda: Pembuatan CSR dan atestasi YubiKey 5 FIPS atau panduan CSR dan atestasi Luna Network Attached HSM v7.x.

Di mana keytool masih relevan digunakan

Semua hal di atas tidak sepenuhnya mengesampingkan keytool. Keytool tetap menjadi alat yang tepat dalam tiga situasi, dan hanya yang pertama yang menghasilkan CSR yang dapat Anda kirim ke CA publik:

• Sebagai antarmuka PKCS#11 untuk token atau HSM Anda. keytool berbicara dalam bahasa PKCS#11 secara native. Arahkan ke pustaka PKCS#11 dari vendor Anda dan kunci tidak akan pernah keluar dari perangkat, sementara perintah -certreq yang sudah familiar tetap menghasilkan CSR. Perintah-perintahnya ada di bagian perangkat keras di bawah.
• Untuk penandatanganan internal atau perusahaan. Jika Anda menandatangani perangkat lunak internal dengan CA milik organisasi Anda sendiri, kebijakan internal Anda yang mengatur penyimpanan kunci, bukan Baseline Requirements publik. Keystore perangkat lunak adalah pilihan yang wajar dalam kasus ini.
• Untuk latihan. Mendapatkan nama subjek yang benar pada percobaan pertama akan lebih mudah jika Anda sudah menjalankan proses tanya-jawabnya sekali terhadap keystore sekali pakai.

Satu batasan yang perlu diketahui sebelum memulai: keytool tidak menghasilkan atestasi kunci. Atestasi dihasilkan oleh perangkat lunak bawaan dari vendor token atau HSM itu sendiri, jadi bahkan pada jalur PKCS#11 pun Anda akan menggunakan utilitas vendor untuk file tersebut dan keytool hanya untuk CSR.

Membuat CSR dengan keytool

Jika Anda sudah membuat CSR dan Certificate Authority sudah menerbitkan sertifikatnya, langsung lompat ke bagian mengimpor balasan CA, langkah yang gagal secara diam-diam ketika alias tidak cocok.

keytool sudah termasuk dalam JDK, jadi instal JDK terkini terlebih dahulu jika Anda belum memilikinya. JDK 25 adalah rilis long-term support (LTS) saat ini dan JDK 26 adalah rilis short-term saat ini. Perintah di bawah ini berjalan pada JDK 17 dan versi yang lebih baru, dan perbedaan versi yang perlu diperhatikan dicatat di tempat kemunculannya. Pastikan alat ini ada di path Anda:

java -version
keytool -help
jarsigner -version

Java Runtime Environment saja tidak cukup, dan keytool yang berfungsi bukan bukti bahwa Anda memiliki JDK: Oracle JRE 8 lama menyertakan keytool tetapi bukan jarsigner. Jalankan ketiga perintah tersebut sekarang. Jika dua perintah pertama merespons dan yang ketiga tidak, berarti Anda menggunakan JRE, dan menginstal JDK pada titik ini jauh lebih mudah daripada menemukannya saat Anda hendak menandatangani.

Langkah 1: Membuat keystore dan pasangan kunci

Jalankan ini di terminal, atau di Command Prompt atau PowerShell pada Windows, dari direktori tempat Anda ingin menyimpan file keystore:

keytool -genkeypair -alias codesign -keyalg RSA -keysize 3072 -storetype PKCS12 -keystore codesign.p12

Empat detail dalam perintah tersebut berbeda dari instruksi lama, dan masing-masing penting:

• -genkeypair, bukan -genkey. Ejaan lama -genkey masih berjalan dan keytool tidak menampilkan peringatan apa pun tentang itu, tetapi hanya dipertahankan dalam kode sumber sebagai alias warisan dan sudah tidak muncul lagi di mana pun dalam dokumentasi JDK. Tulis -genkeypair.
• -storetype PKCS12, bukan JKS. JKS adalah format keystore milik Oracle. PKCS12 adalah format standar industri dan telah menjadi default JDK sejak Java 9. Jika Anda tetap membuat keystore JKS, keytool akan memperingatkan setiap kali menjalankan perintah yang menyentuhnya: “The JKS keystore uses a proprietary format. It is recommended to migrate to PKCS12 which is an industry standard format.”
• Nama file tidak menentukan formatnya. Menamai sebuah file dengan keystore.jks tidak membuatnya menjadi keystore JKS. keytool mengambil tipenya dari -storetype, atau dari properti keystore.type di file security JDK jika Anda tidak menyertakannya. Pada JDK 9 dan versi setelahnya, properti tersebut adalah pkcs12, sehingga perintah yang menulis ke keystore.jks tanpa -storetype diam-diam menghasilkan file PKCS12 dengan nama yang menyesatkan.
• -keysize 3072, bukan 2048. Baseline Requirements menetapkan RSA 3072 sebagai minimum untuk code signing, sehingga permintaan 2048-bit akan ditolak. JDK saat ini menggunakan default 3072 untuk RSA, tetapi JDK 17 dan versi sebelumnya menggunakan default 2048, jadi sertakan opsi ini secara eksplisit agar perintahnya berperilaku sama di mana pun.

Alias, yaitu codesign dalam contoh ini, adalah label untuk entri ini di dalam keystore. Pilih sesuatu yang mudah Anda kenali, dan catatlah: setiap perintah berikutnya memerlukan alias ini, dan ketidakcocokan alias adalah penyebab kegagalan impor sertifikat yang dijelaskan lebih jauh di bawah.

Kunci ECDSA juga diperbolehkan. Ganti opsi RSA dengan -keyalg EC -groupname secp256r1 jika Anda lebih memilih P-256, dan konfirmasikan kepada CA Anda apakah produk yang Anda pesan mendukung ECDSA.

Langkah 2: Menjawab pertanyaan yang membentuk distinguished name Anda

keytool meminta kata sandi keystore dua kali, lalu mengajukan enam pertanyaan dalam urutan pasti ini. Urutan ini penting: pertanyaan kedua menanyakan tentang unit organisasi, bukan organisasi, dan panduan-panduan lama sering mencantumkannya secara keliru, sehingga pembaca yang mengetik nama perusahaan di sana akan menempatkannya pada komponen nama yang salah.

• What is your first and last name? Ini akan menjadi Common Name (CN), meskipun redaksinya demikian. Untuk sertifikat code signing, CN adalah identitas penerbit yang akan dilihat pengguna, jadi masukkan nama hukum organisasi Anda secara lengkap dan tepat, atau nama lengkap resmi Anda sendiri untuk sertifikat perorangan. Jangan masukkan nama domain di sini.
• What is the name of your organizational unit? Departemen, misalnya IT. Jangan menekan Enter untuk melewatinya: keytool kemudian menulis nilai literal Unknown ke dalam nama, dan OU=Unknown akan muncul dalam CSR Anda. Jika Anda tidak ingin ada unit organisasi sama sekali, gunakan bentuk -dname di bawah ini dan hilangkan komponen OU dari string tersebut.
• What is the name of your organization? Nama hukum terdaftar, dieja sebagaimana tercantum dalam catatan resmi. CA akan memverifikasi hal ini terhadap register publik.
• What is the name of your City or Locality? Kota tempat pendaftaran, ditulis lengkap.
• What is the name of your State or Province? Nama lengkap, bukan singkatan.
• What is the two-letter country code for this unit? Kode ISO, misalnya US.

keytool kemudian menampilkan kembali nama yang telah disusun dan meminta Anda untuk mengonfirmasinya:

Is CN=Example LLC, OU=IT, O=Example LLC, L=Miami, ST=Florida, C=US correct?
  [no]:

Jawaban default adalah no, sehingga menekan Enter akan membawa Anda kembali melalui keenam pertanyaan tersebut. Ketik yes untuk menyetujui. Baca baris tersebut dengan saksama terlebih dahulu: ini adalah keseluruhan distinguished name, bukan hanya Common Name, dan setiap komponen di dalamnya masuk ke dalam CSR.

Tidak ada kata sandi kunci terpisah pada keystore PKCS12. Panduan lama mengakhiri langkah ini dengan “masukkan kata sandi untuk kunci”, yang merupakan perilaku JKS. Pada keystore PKCS12, kata sandi kunci adalah kata sandi store, dan jika Anda menyertakan -keypass dengan nilai berbeda, keytool akan memberi tahu Anda: “Different store and key passwords not supported for PKCS12 KeyStores. Ignoring user-specified -keypass value.”

Untuk melewati semua pertanyaan tersebut, berikan nama lengkap dengan -dname. Simpan nilainya dalam satu pasang tanda kutip lurus:

keytool -genkeypair -alias codesign -keyalg RSA -keysize 3072 -storetype PKCS12 -keystore codesign.p12 -dname "CN=Example LLC, OU=IT, O=Example LLC, L=Miami, ST=Florida, C=US"

Jangan sertakan -storepass pada baris perintah dan biarkan keytool memintanya. Menyertakan kata sandi sebagai argumen akan menuliskannya ke riwayat shell Anda dan mengekspos kata sandi tersebut kepada siapa pun yang dapat melihat daftar proses yang sedang berjalan.

Langkah 3: Membuat CSR

Keystore sekarang menyimpan kunci privat dan sertifikat self-signed sementara. Ubah entri tersebut menjadi permintaan sertifikat:

keytool -certreq -alias codesign -keystore codesign.p12 -file codesign.csr

Masukkan kata sandi keystore ketika diminta. Anda tidak memerlukan -storetype di sini: keytool mendeteksi format file keystore yang sudah ada. Alias harus sama dengan yang digunakan pada langkah 1, karena CSR ditandatangani oleh kunci privat dari entri tersebut.

Perintah ini tidak membuat kunci privat. Kunci tersebut dibuat pada langkah 1 dan tetap berada di dalam keystore, itulah sebabnya file keystore dan kata sandinya kini sama sensitifnya dengan kunci itu sendiri. Siapa pun yang memegang keduanya dapat menandatangani perangkat lunak atas nama Anda.

Langkah 4: Periksa CSR sebelum mengirimkannya

CSR yang ditolak akan menghabiskan satu siklus validasi, jadi dekodekan dan bacalah kembali isinya:

keytool -printcertreq -file codesign.csr

Konfirmasi tiga hal dalam output tersebut. Baris Subject harus mencantumkan detail Anda pada komponen yang tepat, dengan nama hukum organisasi pada O dan identitas penerbit pada CN. Baris kunci publik harus menunjukkan 3072-bit RSA key atau lebih besar. Algoritma tanda tangan harus berupa algoritma SHA-2: JDK saat ini menandatangani permintaan RSA 3072-bit dengan SHA384withRSA dan versi yang lebih lama menggunakan SHA256withRSA, dan keduanya sama-sama baik. Algoritma itu hanya membuktikan bahwa Anda memegang kunci privat, dan itu bukan algoritma yang akan digunakan CA untuk menandatangani sertifikat Anda.

Anda juga dapat menempelkan permintaan tersebut ke CSR decoder kami untuk membaca kolom-kolom yang sama di dalam browser.

Saat Anda mengirimkan permintaan, buka file tersebut di editor teks biasa dan salin semuanya, termasuk baris pertama dan terakhir. keytool menuliskan penanda yang persis seperti ini, dengan lima tanda hubung di setiap sisinya:

-----BEGIN NEW CERTIFICATE REQUEST-----
MIID3TCCAkUCAQAwaDELMAkGA1UEBhMCVVMxEDAOBgNVBAgTB0Zsb3JpZGExDjAM
...base64 encoded request...
-----END NEW CERTIFICATE REQUEST-----

Redaksi NEW CERTIFICATE REQUEST adalah hal yang normal untuk output keytool dan formulir pendaftaran menerimanya. Jika editor Anda telah mengganti rangkaian tanda hubung dengan garis panjang, permintaan tersebut akan ditolak: ketik ulang penanda tersebut sebagai tanda hubung biasa atau salin file dengan editor kode sebagai gantinya.

Membuat CSR pada token atau HSM dengan keytool

Inilah jalur yang menghasilkan CSR yang dapat ditindaklanjuti oleh CA publik. keytool berkomunikasi dengan token perangkat keras melalui provider SunPKCS11, sehingga pasangan kunci dibuat di dalam perangkat dan tidak pernah ada sebagai file. Mulailah dengan menulis file konfigurasi kecil, misalnya token.cfg, yang menyebutkan nama token Anda dan menunjuk ke pustaka PKCS#11 yang diinstal oleh vendor Anda:

name = token
library = /usr/local/lib/libeToken.so

Kedua baris tersebut, name dan library, adalah satu-satunya yang wajib diisi. Path pustaka bersifat spesifik untuk setiap vendor dan berbeda menurut sistem operasi, jadi ambil dari dokumentasi token Anda, bukan dari contoh ini. Pada Windows, ini berupa file DLL di dalam direktori sistem. Tanpa baris slot, provider akan terhubung ke slot pertama yang dilaporkan oleh perangkat, yang merupakan pilihan yang tepat ketika hanya ada satu token yang terpasang. Jika Anda memiliki lebih dari satu reader atau token, tambahkan salah satu dari slotListIndex dengan posisi dalam daftar tersebut, dihitung mulai dari nol, atau slot dengan ID slot numerik yang ditampilkan oleh utilitas vendor Anda. Hanya salah satu dari keduanya yang boleh muncul dalam file tersebut, dan ID slot bukanlah angka yang sama dengan posisi dalam daftar, jadi jangan menebak-nebak dengan slot = 0.

Tampilkan daftar isi perangkat. Token menyediakan alias, jadi Anda memerlukan ini sebelum apa pun yang lain:

keytool -list -keystore NONE -storetype PKCS11 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg token.cfg

-keystore NONE diperlukan setiap kali keystore bukan sebuah file, dan permintaan kata sandi tersebut sebenarnya meminta PIN token. keytool juga menerima -addprovider SunPKCS11 -providerarg token.cfg sebagai pengganti pasangan -providerClass dan -providerArg; kedua bentuk ini berfungsi, dan dokumentasi Certificate Authority biasanya menampilkan bentuk yang lebih lama.

Dengan alias di tangan, buat kunci pada perangkat lalu ajukan permintaan CSR terhadapnya:

keytool -genkeypair -alias codesign -keyalg RSA -keysize 3072 -keystore NONE -storetype PKCS11 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg token.cfg -dname "CN=Example LLC, O=Example LLC, L=Miami, ST=Florida, C=US"

keytool -certreq -alias codesign -keystore NONE -storetype PKCS11 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg token.cfg -file codesign.csr

Ada dua catatan yang berlaku. Beberapa token tidak mengizinkan pembuatan kunci melalui PKCS#11 dan mengharuskan Anda menggunakan utilitas bawaan vendor, yang tidak masalah: keytool tetap dapat membuat CSR terhadap kunci yang dihasilkan oleh alat vendor tersebut. Dan keytool tidak dapat menghasilkan file atestasi yang akan diminta oleh CA Anda, jadi hasilkan file itu dengan perangkat lunak vendor pada saat yang sama dengan pembuatan kunci, mengikuti panduan YubiKey atau Luna HSM.

Mengimpor balasan CA ke alias yang sama

Ketika sertifikat tiba, sertifikat itu harus dimasukkan kembali ke entri yang menghasilkan CSR tersebut. Jika Anda mengimpornya ke tempat lain, keytool tetap melaporkan keberhasilan sementara menghasilkan keystore yang tidak dapat digunakan untuk menandatangani, jadi baca bagian ini sebelum menjalankan apa pun.

Impor terlebih dahulu sertifikat root dan sertifikat intermediate milik CA, masing-masing dengan aliasnya sendiri:

keytool -importcert -trustcacerts -alias caroot -file root.crt -keystore codesign.p12

keytool menampilkan sertifikat yang akan disimpannya dan bertanya Trust this certificate? dengan no sebagai default, jadi ketik yes. Periksa fingerprint-nya terhadap yang dipublikasikan oleh Certificate Authority Anda sebelum menjawab.

Jika Anda melewatkan impor root, perintah berikutnya akan gagal dengan pesan yang tidak memberi petunjuk apa pun tentang penyebabnya:

keytool error: java.lang.Exception: Failed to establish chain from reply

Sekarang impor sertifikat yang telah diterbitkan menggunakan alias yang sama seperti pada langkah 1:

keytool -importcert -alias codesign -file codesign.crt -keystore codesign.p12

Pesan yang Anda inginkan adalah Certificate reply was installed in keystore. Itu berarti keytool mengenali kunci privat yang sudah ada di bawah alias tersebut dan melampirkan sertifikat yang diterbitkan beserta rantainya ke sana.

Jika Anda malah membuat alias baru, keytool akan menerima file tersebut dan menampilkan Certificate was added to keystore. Ini terlihat seperti keberhasilan, padahal bukan. keytool telah menyimpan sertifikat sebagai entri tepercaya yang berdiri sendiri tanpa kunci privat di baliknya, dan entri itu tidak akan pernah bisa digunakan untuk menandatangani apa pun. Alias asli, sementara itu, masih menyimpan sertifikat self-signed sementara dari langkah 1. Periksa mana dari keduanya yang Anda miliki:

keytool -list -keystore codesign.p12

Alias penandatanganan Anda harus tercantum sebagai PrivateKeyEntry. Alias yang ditampilkan sebagai trustedCertEntry adalah kesalahan yang dijelaskan di atas. Hapus alias tersebut dengan keytool -delete -alias wrongalias -keystore codesign.p12 dan ulangi proses impor terhadap alias yang benar. Tambahkan -v pada perintah list untuk memastikan entri tersebut sekarang membawa rantai sertifikat lengkap, bukan hanya satu sertifikat self-signed.

Pada token perangkat keras biasanya tidak ada yang perlu diimpor, karena CA memuat sertifikat ke perangkat tersebut sebelum mengirimkannya. Jika CA Anda mengirimkan file sertifikat untuk kunci yang Anda buat pada HSM milik Anda sendiri, gunakan perintah -importcert yang sama dengan opsi PKCS#11 dari bagian sebelumnya.

Menandatangani file JAR dengan sertifikat

Tujuan menempatkan sertifikat code signing dalam keystore Java adalah untuk menandatangani file JAR dengan jarsigner, yang juga disertakan dengan JDK. Dengan sertifikat yang sudah terpasang di bawah alias yang benar:

jarsigner -keystore codesign.p12 -tsa https://your-ca-timestamp-url application.jar codesign

Selalu sertakan -tsa dengan URL timestamp yang dipublikasikan oleh Certificate Authority Anda. Timestamp mencatat bahwa JAR tersebut ditandatangani ketika sertifikat masih berlaku, sehingga tanda tangan tersebut tetap berfungsi setelah sertifikat kedaluwarsa. Tanpa itu, setiap salinan perangkat lunak Anda akan berhenti dapat divalidasi pada hari sertifikat tersebut berakhir masa berlakunya.

Ketika kunci berada pada token, arahkan jarsigner ke PKCS#11 persis seperti yang dilakukan keytool:

jarsigner -keystore NONE -storetype PKCS11 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg token.cfg -tsa https://your-ca-timestamp-url application.jar codesign

Jika token memiliki ruang yang terlalu sedikit untuk menampung seluruh rantai sertifikat, sediakan secara terpisah dengan -certchain. Periksa hasilnya setelahnya:

jarsigner -verify -verbose -certs application.jar

Proses yang berhasil akan menampilkan jar verified beserta distinguished name penanda tangan dan detail timestamp-nya. JDK saat ini menggunakan SHA-384 sebagai algoritma digest default, sehingga Anda jarang perlu mengatur -digestalg atau -sigalg secara manual.

Cara lain untuk membuat permintaan ini dibahas dalam panduan OpenSSL, CertReq, Microsoft Management Console, dan macOS Keychain Access, dan aturan perangkat keras yang sama berlaku untuk semuanya. Lihat juga kumpulan lengkap tutorial code signing kami dan gambaran umum pembuatan CSR untuk sertifikat code signing. Jika Anda memerlukan CSR keytool untuk sertifikat situs web, bukan untuk code signing, ikuti panduan Tomcat atau JBoss sebagai gantinya.

Pertanyaan yang Sering Diajukan