Java Keytool İle Kod İmzalama Sertifikası İçin CSR Nasıl Oluşturulur

Java Development Kit (JDK) ile birlikte gelen keytool aracı, bir Java keystore içinde bir anahtar çifti oluşturur ve bunu bir CSR (Sertifika İmzalama Talebi) haline getirir; bu, bir Sertifika Otoritesinin (CA) sertifika vermeden önce kimliğinizi tespit etmek için okuduğu kodlanmış bloktur. Kod imzalama için keytool’un yasal olarak ne amaçla kullanılabileceği 1 Haziran 2023’te değişti. Bu kılavuz önce kuralı belirtir, ardından hâlâ doğru olan keytool komutlarını ele alır: dahili imzalama için bir yazılım keystore’una karşı ve PKCS#11 üzerinden bir donanım token’ına veya HSM’ye karşı.

Kod imzalama anahtarları donanım üzerinde oluşturulmalıdır

1 Haziran 2023‘ten bu yana, CA/Browser Forum Kod İmzalama Temel Gereksinimleri, herkese açık güvenilir her kod imzalama sertifikasının özel anahtarının, FIPS 140-2 Seviye 2, Common Criteria EAL4+ veya eşdeğer bir standardı karşılayan bir donanım kripto modülünde oluşturulmasını ve saklanmasını şart koşmaktadır. Anahtar, dışa aktarılamaz olmalıdır. Bu, hem standart (Organizasyon Doğrulama) sertifikaları hem de Genişletilmiş Doğrulama sertifikaları için geçerlidir. EV kod imzalama her zaman donanım gerektirmiştir; 2023 değişikliği aynı kuralı standart sertifikalara da genişletmiştir. Aynı gereksinimler, kod imzalama sertifikaları için minimum anahtar boyutunu RSA 3072 olarak belirlemiştir ve bu, 1 Haziran 2021’den bu yana yürürlüktedir.

Bu sayfa için sonucu doğrudandır. keytool’un dizüstü bilgisayarınızda veya sunucunuzda oluşturduğu bir keystore dosyası, ister PKCS12 ister eski JKS formatında olsun, bir yazılım anahtarı içerir. Bundan oluşturulan bir CSR, kod imzalama sertifikası için herkese açık bir Sertifika Otoritesi tarafından kabul edilmez. Sertifika Otoriteleri, bu ürünler için tarayıcı tabanlı anahtar oluşturmayı ve indirilebilir anahtar dosyalarını desteklemeyi bırakmıştır. Anahtarınız artık şu iki yerden birinde ortaya çıkar:

• CA’nın size gönderdiği önceden yapılandırılmış bir token. CA, anahtar çiftini ve CSR’yi kendi tarafında sertifikalı bir USB token üzerinde oluşturur, verilen sertifikayı bunun üzerine yükler ve token’ı size postalar. Sizin oluşturmanız gereken bir CSR yoktur.
• Kendi HSM’niz veya token’ınız, anahtar tasdiki (attestation) ile. Anahtarı cihazın içinde oluşturursunuz, bundan bir CSR üretirsiniz ve anahtarın uyumlu donanım üzerinde oluşturulduğunu ve dışa aktarılamayacağını CA’ya kanıtlayan bir tasdik dosyası gönderirsiniz. Her iki parça da gereklidir; geçerli tasdiki olmayan bir CSR reddedilir.

Hangi yolun geçerli olduğuna sipariş verirken karar verilir. Karşılaştırma için kod imzalama sertifikası teslim yöntemlerine bakın. Zaten uyumlu donanımınız varsa, cihazınıza uygun kılavuzu izleyin: YubiKey 5 FIPS CSR oluşturma ve tasdik veya Luna Network Attached HSM v7.x CSR ve tasdik kılavuzu.

keytool’un hâlâ uygun olduğu yerler

Yukarıdakilerin hiçbiri keytool’u devre dışı bırakmaz. Üç durumda hâlâ doğru araçtır ve yalnızca ilki herkese açık bir CA’ya gönderebileceğiniz bir CSR üretir:

• Token’ınıza veya HSM’nize PKCS#11 ön yüzü olarak. keytool, PKCS#11’i doğal olarak konuşur. Onu satıcınızın PKCS#11 kütüphanesine yönlendirin ve anahtar cihazdan asla çıkmaz; bu arada tanıdık -certreq komutu yine de CSR’yi üretir. Komutlar aşağıdaki donanım bölümündedir.
• Dahili veya kurumsal imzalama için. Kurum içi yazılımı kendi organizasyonunuzun CA’sı ile imzalıyorsanız, anahtar depolamayı yöneten şey herkese açık Temel Gereksinimler değil, dahili politikanızdır. Bir yazılım keystore’u orada normal bir seçimdir.
• Prova için. Konu adını ilk denemede doğru almak, önce bir kullan-at keystore’a karşı istemleri bir kez çalıştırmışsanız daha kolaydır.

Başlamadan önce bilinmesi gereken bir sınırlama: keytool, anahtar tasdiki (attestation) üretmez. Tasdik, token veya HSM satıcısının kendi araçları tarafından üretilir; bu nedenle PKCS#11 yolunda bile bu dosya için satıcı aracını, CSR için ise yalnızca keytool’u kullanırsınız.

CSR’yi keytool ile oluşturun

CSR’nizi zaten oluşturduysanız ve Sertifika Otoritesi sertifikayı verdiyse, doğrudan CA yanıtını içe aktarma bölümüne geçin; bu adım, takma ad (alias) eşleşmediğinde sessizce başarısız olur.

keytool, JDK ile birlikte gelir; bu nedenle henüz yoksa önce güncel bir JDK kurun. JDK 25 mevcut uzun süreli destek sürümüdür ve JDK 26 mevcut kısa süreli sürümdür. Aşağıdaki komutlar JDK 17 ve sonrasında çalışır; önemli olan sürüm farklılıkları meydana geldikleri yerlerde belirtilmiştir. Aracın yolunuzda olduğunu doğrulayın:

java -version
keytool -help
jarsigner -version

Tek başına bir Java Runtime Environment yeterli değildir ve çalışan bir keytool, bir JDK’ye sahip olduğunuzun kanıtı değildir: eski Oracle JRE 8, keytool‘u içerir ama jarsigner‘ı içermez. Şimdi her üç komutu da çalıştırın. İlk ikisi yanıt verirse ama üçüncüsü vermezse, bir JRE üzerindesiniz demektir ve o noktada bir JDK kurmak, bunu imzalamaya geçtiğinizde keşfetmekten daha kolaydır.

Adım 1: Keystore’u ve anahtar çiftini oluşturun

Bunu bir terminalde veya Windows’ta Komut İstemi ya da PowerShell’de, keystore dosyasının bulunmasını istediğiniz dizinden çalıştırın:

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

Bu komuttaki dört ayrıntı eski talimatlardan farklıdır ve her biri önemlidir:

• -genkeypair, -genkey değil. Eski -genkey yazımı hâlâ çalışır ve keytool bununla ilgili bir uyarı yazdırmaz, ancak bu yalnızca kaynak kodda bir eski (legacy) takma ad olarak korunmaktadır ve artık JDK dokümantasyonunda hiçbir yerde görünmez. -genkeypair yazın.
• -storetype PKCS12, JKS değil. JKS, Oracle’ın tescilli keystore formatıdır. PKCS12, endüstri standardı olanıdır ve Java 9’dan bu yana JDK varsayılanı olmuştur. Yine de bir JKS keystore oluşturursanız, keytool ona dokunan her komutta sizi uyarır: “JKS keystore uses a proprietary format. It is recommended to migrate to PKCS12 which is an industry standard format.”
• Dosya adı formatı belirlemez. Bir dosyayı keystore.jks olarak adlandırmak onu bir JKS keystore’u yapmaz. keytool, türü -storetype‘tan alır, ya da bunu atladığınızda JDK’nin güvenlik dosyasındaki keystore.type özelliğinden alır. JDK 9 ve sonrasında bu özellik pkcs12‘dir; bu nedenle -storetype olmadan keystore.jks’e yazan bir komut, sessizce yanıltıcı bir adı olan bir PKCS12 dosyası üretir.
• -keysize 3072, 2048 değil. Temel Gereksinimler, kod imzalama için minimum RSA 3072 belirler; bu nedenle 2048 bitlik bir talep reddedilir. Güncel JDK’ler RSA için varsayılan olarak 3072 kullanır, ancak JDK 17 ve öncesi varsayılan olarak 2048 kullanır; bu nedenle seçeneği açıkça belirtin ve komut her yerde aynı şekilde davransın.

Örnekteki codesign takma adı, keystore içindeki bu girişin etiketidir. Tanıyacağınız bir şey seçin ve not edin: sonraki her komut buna ihtiyaç duyar ve bir uyumsuzluk, aşağıda açıklanan sertifika içe aktarma işlemini bozan şeydir.

Bir ECDSA anahtarına da izin verilir. P-256 tercih ediyorsanız RSA seçeneklerinin yerine -keyalg EC -groupname secp256r1 kullanın ve sipariş ettiğiniz ürünün ECDSA’yı desteklediğini CA’nızla doğrulayın.

Adım 2: Ayırt edici adınızı (distinguished name) oluşturan istemleri yanıtlayın

keytool, iki kez bir keystore parolası ister, ardından tam olarak bu sırayla altı soru sorar. Sıra önemlidir: ikinci istem organizasyonu değil, organizasyon birimini sorar ve eski kılavuzlar bunu yanlış listeler; bu nedenle oraya şirket adını yazan bir okuyucu, bunu adın yanlış bileşenine koymuş olur.

• Adınız ve soyadınız nedir? Kullanılan ifadeye rağmen bu, Ortak Ad (CN) haline gelir. Kod imzalama sertifikası için CN, kullanıcıların göreceği yayıncı kimliğidir; bu nedenle organizasyonunuzun tam yasal adını veya bireysel bir sertifika için kendi tam yasal adınızı girin. Buraya bir alan adı girmeyin.
• Organizasyon biriminizin adı nedir? Örneğin IT gibi departman. Bunu atlamak için Enter’a basmayın: keytool o zaman ada gerçek Unknown değerini yazar ve OU=Unknown, CSR’nizde sonlanır. Hiçbir organizasyon birimi istemiyorsanız, aşağıdaki -dname formunu kullanın ve OU bileşenini dizeden çıkarın.
• Organizasyonunuzun adı nedir? Resmi kayıtlarda göründüğü şekilde yazılmış, kayıtlı yasal ad. CA bunu kamuya açık kayıtlara karşı doğrular.
• Şehir veya bölgenizin adı nedir? Kayıt şehri, tam olarak yazılmış.
• Eyalet veya ilinizin adı nedir? Kısaltma değil, tam ad.
• Bu birim için iki harfli ülke kodu nedir? ISO kodu, örneğin US.

keytool ardından oluşturulan adı geri yazdırır ve onaylamanızı ister:

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

Varsayılan yanıt no‘dur; bu nedenle Enter’a basmak sizi altı sorunun tamamına geri gönderir. Kabul etmek için yes yazın. Önce satırı dikkatlice okuyun: bu, yalnızca Ortak Ad değil, tüm ayırt edici addır ve her bileşeni CSR’ye girer.

Bir PKCS12 keystore’unda ayrı bir anahtar parolası yoktur. Eski kılavuzlar bu adımı “anahtar için bir parola girin” ile bitirir; bu JKS davranışıdır. Bir PKCS12 keystore’unda anahtar parolası, store parolasıdır ve farklı bir değerle -keypass geçirirseniz keytool bunu size söyler: “Different store and key passwords not supported for PKCS12 KeyStores. Ignoring user-specified -keypass value.”

İstemleri tamamen atlamak için, tüm adı -dname ile sağlayın. Değeri tek bir çift düz tırnak işareti içinde tutun:

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"

-storepass‘i komut satırından çıkarın ve keytool’un bunu istemesine izin verin. Bir parolayı bağımsız değişken olarak geçirmek, onu kabuk (shell) geçmişinize yazar ve çalışan işlemleri listeleyebilen herkese açık hale getirir.

Adım 3: CSR’yi oluşturun

Keystore artık bir özel anahtar ve geçici, kendinden imzalı bir sertifika içerir. Bu girişi bir sertifika talebine dönüştürün:

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

İstendiğinde keystore parolasını girin. Burada -storetype‘a ihtiyacınız yoktur: keytool, zaten var olan bir keystore dosyasının formatını algılar. Takma ad, 1. adımdaki ile aynı olmalıdır, çünkü CSR o girişin özel anahtarıyla imzalanır.

Bu komut bir özel anahtar oluşturmaz. Anahtar 1. adımda oluşturuldu ve keystore içinde kalır; bu nedenle keystore dosyası ve parolası artık anahtarın kendisi kadar hassastır. Her ikisine de sahip olan herkes sizin adınıza yazılım imzalayabilir.

Adım 4: Göndermeden önce CSR’yi kontrol edin

Reddedilen bir CSR, bir doğrulama döngüsüne mal olur; bu nedenle onu çözün ve geri okuyun:

keytool -printcertreq -file codesign.csr

Çıktıda üç şeyi doğrulayın. Subject satırı, doğru bileşenlerde detaylarınızı listelemelidir; O içinde yasal organizasyon adı, CN içinde yayıncı kimliği olmalıdır. Genel anahtar satırı 3072-bit RSA key veya daha büyük okumalıdır. İmza algoritması bir SHA-2 algoritması olmalıdır: güncel JDK’ler 3072 bitlik bir RSA talebini SHA384withRSA ile imzalar, eski olanlar SHA256withRSA kullanır ve her ikisi de uygundur. Bu algoritma yalnızca özel anahtarı elinizde bulundurduğunuzu kanıtlar ve CA’nın sertifikanızı imzalamak için kullanacağı algoritma değildir.

Aynı alanları bir tarayıcıda okumak için talebi CSR çözücümüze de yapıştırabilirsiniz.

Talebi gönderdiğinizde, dosyayı düz metin bir düzenleyicide açın ve ilk ve son satırlar dahil her şeyi kopyalayın. keytool bu tam işaretleri her iki tarafta beş kısa çizgi ile yazar:

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

NEW CERTIFICATE REQUEST ifadesi keytool çıktısı için normaldir ve kayıt formları bunu kabul eder. Düzenleyiciniz herhangi bir kısa çizgi dizisini uzun bir tire ile değiştirdiyse, talep reddedilir: işaretleri düz kısa çizgiler olarak yeniden yazın veya dosyayı bunun yerine bir kod düzenleyiciyle kopyalayın.

Bir token veya HSM üzerinde keytool ile CSR oluşturun

Bu, herkese açık bir CA’nın işlem yapabileceği bir CSR üreten yoldur. keytool, SunPKCS11 sağlayıcısı üzerinden bir donanım token’ıyla konuşur; bu nedenle anahtar çifti cihaz içinde oluşturulur ve asla bir dosya olarak var olmaz. Token’ınızı adlandıran ve satıcınızın kurduğu PKCS#11 kütüphanesine işaret eden küçük bir yapılandırma dosyası, örneğin token.cfg, yazarak başlayın:

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

Bu iki satır, name ve library, gerekli olan tek satırlardır. Kütüphane yolu, satıcıya özgüdür ve işletim sistemine göre değişir; bu nedenle bunu bu örnekten değil, token belgelerinizden alın. Windows’ta bu, sistem dizini altındaki bir DLL’dir. slot satırı olmadan, sağlayıcı cihazın bildirdiği ilk yuvaya (slot) bağlanır; bu, tek bir token takılıyken istediğiniz şeydir. Birden fazla okuyucunuz veya token’ınız varsa, sıfırdan sayarak o listedeki konumla slotListIndex ekleyin, ya da satıcı aracınızın yazdırdığı sayısal yuva kimliğiyle slot ekleyin. Dosyada bu ikisinden yalnızca biri görünebilir ve bir yuva kimliği bir liste konumuyla aynı sayı değildir; bu nedenle slot = 0‘ı tahmin etmeyin.

Cihazda neler olduğunu listeleyin. Token, takma adı sağlar; bu nedenle her şeyden önce buna ihtiyacınız var:

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

Keystore bir dosya olmadığında -keystore NONE gereklidir ve parola istemi token PIN’ini sormaktadır. keytool ayrıca -providerClass ve -providerArg çiftinin yerine -addprovider SunPKCS11 -providerarg token.cfg‘yi de kabul eder; her iki form da çalışır ve Sertifika Otoritesi belgeleri genellikle eski olanı gösterir.

Takma ad elinizde olduğunda, anahtarı cihaz üzerinde oluşturun ve ardından buna karşı CSR’yi talep edin:

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

İki uyarı geçerlidir. Bazı token’lar PKCS#11 üzerinden anahtar oluşturmaya izin vermez ve satıcının kendi aracını kullanmanızı bekler, ki bu sorun değildir: keytool yine de satıcı aracının oluşturduğu bir anahtara karşı CSR’yi oluşturabilir. Ve keytool, CA’nızın isteyeceği tasdik dosyasını üretemez; bu nedenle bunu YubiKey veya Luna HSM kılavuzunu izleyerek anahtarla aynı zamanda satıcı araçlarıyla üretin.

CA yanıtını aynı takma ada içe aktarın

Sertifika geldiğinde, CSR’yi oluşturan girişe geri gitmesi gerekir. Onu başka bir yere içe aktarırsanız, keytool yine de başarı bildirir ve imzalayamayan bir keystore üretir; bu nedenle herhangi bir şey çalıştırmadan önce bu bölümü okuyun.

Önce CA’nın kök ve varsa ara sertifikalarını, her birini kendi takma adı altında içe aktarın:

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

keytool, depolamak üzere olduğu sertifikayı yazdırır ve varsayılan olarak no ile Bu sertifikaya güvenilsin mi? diye sorar; bu nedenle yes yazın. Yanıtlamadan önce parmak izini Sertifika Otoritenizin yayınladığı ile karşılaştırın.

Kök içe aktarmayı atlayın ve bir sonraki komut, nedeni hakkında hiçbir ipucu vermeyen bir mesajla başarısız olur:

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

Şimdi verilen sertifikanızı 1. adımda kullandığınız aynı takma adla içe aktarın:

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

İstediğiniz mesaj Certificate reply was installed in keystore‘dur. Bu, keytool’un o takma ad altında var olan bir özel anahtarı tanıdığı ve verilen sertifikayı ve zincirini buna eklediği anlamına gelir.

Bunun yerine yeni bir takma ad icat ederseniz, keytool dosyayı kabul eder ve Certificate was added to keystore yazdırır. Bu, başarı gibi görünür ama değildir. keytool, sertifikayı arkasında hiçbir özel anahtar olmadan bağımsız, güvenilir bir giriş olarak depolamıştır ve bu giriş asla hiçbir şey imzalayamaz. Bu arada, orijinal takma ad, 1. adımdan kalan geçici, kendinden imzalı sertifikayı hâlâ tutmaktadır. Hangisine sahip olduğunuzu kontrol edin:

keytool -list -keystore codesign.p12

İmzalama takma adınız PrivateKeyEntry olarak listelenmelidir. trustedCertEntry olarak gösterilen bir takma ad, yukarıda açıklanan hatadır. Onu keytool -delete -alias wrongalias -keystore codesign.p12 ile silin ve içe aktarımı doğru takma ada karşı tekrarlayın. Girişin şimdi tek bir kendinden imzalı sertifika yerine tam bir sertifika zinciri taşıdığını doğrulamak için list komutuna -v ekleyin.

Bir donanım token’ında çoğu durumda içe aktarılacak hiçbir şey yoktur, çünkü CA sertifikayı göndermeden önce cihaza yükler. CA’nız, kendi HSM’nizde oluşturduğunuz bir anahtar için size bir sertifika dosyası gönderirse, önceki bölümdeki PKCS#11 seçenekleriyle aynı -importcert komutunu kullanın.

Sertifika ile bir JAR dosyasını imzalayın

Bir kod imzalama sertifikasını bir Java keystore’una koymanın amacı, yine JDK ile birlikte gelen jarsigner ile JAR dosyalarını imzalamaktır. Sertifika doğru takma ad altında kuruluysa:

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

Her zaman Sertifika Otoritenizin yayınladığı zaman damgası URL’siyle -tsa‘yı geçirin. Bir zaman damgası, JAR’ın sertifika hâlâ geçerliyken imzalandığını kaydeder; böylece sertifika süresi dolduktan sonra bile imza çalışmaya devam eder. Bir tane olmadan, yazılımınızın her kopyası, sertifikanın süresinin dolduğu gün doğrulanmayı durdurur.

Anahtar bir token üzerinde yaşadığında, jarsigner’ı tam olarak keytool’un yaptığı gibi PKCS#11’e yönlendirin:

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

Token’ın tam sertifika zinciri için çok az alanı varsa, bunu -certchain ile ayrıca sağlayın. Sonrasında sonucu kontrol edin:

jarsigner -verify -verbose -certs application.jar

Başarılı bir çalıştırma, imzalayanın ayırt edici adı ve zaman damgası detaylarıyla birlikte jar verified yazdırır. Güncel JDK’ler varsayılan özet algoritması olarak SHA-384 kullanır; bu nedenle -digestalg veya -sigalg‘ı elle ayarlamanız nadiren gerekir.

Bu talebi oluşturmanın diğer yolları OpenSSL, CertReq, Microsoft Management Console ve macOS Keychain Access kılavuzlarında ele alınmıştır ve aynı donanım kuralı bunların hepsi için geçerlidir. Ayrıca tüm kod imzalama eğitimlerimize ve kod imzalama sertifikaları için CSR oluşturma genel bakışına bakın. Kod imzalama yerine bir web sitesi sertifikası için keytool CSR’sine ihtiyacınız varsa, bunun yerine Tomcat veya JBoss kılavuzunu izleyin.

Sıkça Sorulan Sorular