Java Entegrasyonu

sslTrus, JDK ile birlikte gelen jarsigner aracıyla birlikte kullanılabilen sslTrusJarsigner Java Provider sunar ve uzak kod imzalama hizmeti aracılığıyla Java JAR dosyası imzalamayı tamamlar.

İmzalama sürecinde, kod imzalama özel anahtarı her zaman bulut HSM'de saklanır. Yerel taraf, imzalanacak verileri ve imza yapısını oluşturmaktan sorumludur ve sslTrusJarsigner Provider aracılığıyla özel anahtar imzasını tamamlamak için uzak hizmeti çağırır.

JAR imzalamanın yanı sıra sslTrusJarsigner, XML dijital imza senaryolarında kullanılabilen XMLDSig imzalama yeteneği de sağlar.

Hazırlık

Kullanmadan önce şunları hazırlayın:

• JDK 8 veya üzeri.
• sslTrusJarsigner-<version>.jar.
• Access Key.
• Access Secret.
• Sertifika numarası (Cert Code).
• İmzalanacak JAR dosyası veya XML dosyası.

Bu makaledeki örneklerde yer alan <version>, erişim kimlik bilgileri, sertifika numarası ve dosya yollarının gerçek değerlerle değiştirilmesi gerekir.

sslTrusJarsigner'ı indirin

sslTrusJarsigner yayın sayfasından en son yayın paketini indirin ve arşivden çıkarın.

Yayın paketi şunları içerir:

sslTrusJarsigner-<version>.jar
SHA-256 校验文件

Doğrulamadan önce SHA-256 sağlama dosyasını kullanarak sslTrusJarsigner-<version>.jar bütünlüğünü doğrulamanız önerilir.

Çalışma ortamını kontrol edin

Öncelikle Java ve JDK ile birlikte gelen jarsigner aracının normal şekilde kullanılabildiğini doğrulayın:

java -version
jarsigner -help

sslTrus Jarsigner sürümünü kontrol edin:

java -jar sslTrusJarsigner-<version>.jar --version

Yardımı görüntüleyin:

java -jar sslTrusJarsigner-<version>.jar --help

jarsigner komutu mevcut değilse, yalnızca Java Runtime içeren bir çalışma ortamı değil, tam JDK kurulu olduğundan emin olun.

Erişim kimlik bilgilerini yapılandırma

sslTrusJarsigner, uzak kod imzalama hizmetinin erişim kimlik bilgilerini ve sertifika numarasını ortam değişkenleri aracılığıyla okur.

Linux ve macOS

export SSLTRUS_JARSIGNER_ACCESS_KEY="YOUR_ACCESS_KEY"
export SSLTRUS_JARSIGNER_ACCESS_SECRET="YOUR_ACCESS_SECRET"
export SSLTRUS_JARSIGNER_CERT_CODE="YOUR_CERT_CODE"

Windows PowerShell

$env:SSLTRUS_JARSIGNER_ACCESS_KEY = "YOUR_ACCESS_KEY"
$env:SSLTRUS_JARSIGNER_ACCESS_SECRET = "YOUR_ACCESS_SECRET"
$env:SSLTRUS_JARSIGNER_CERT_CODE = "YOUR_CERT_CODE"

Özel bir servis adresi sağlanmışsa, SSLTRUS_JARSIGNER_URL de ayarlanmalıdır.

Linux ve macOS:

export SSLTRUS_JARSIGNER_URL="YOUR_SERVICE_URL"

Windows PowerShell：

$env:SSLTRUS_JARSIGNER_URL = "YOUR_SERVICE_URL"

Özel bir servis adresi sağlanmadıysa bu değişkenin ayarlanması gerekmez.

Access Secret hassas bir kimlik bilgisidir ve kaynak koduna, genel yapılandırma dosyalarına veya derleme günlüklerine yazılmamalıdır. Otomasyon ortamlarında CI/CD Secret veya diğer kimlik bilgisi yönetim mekanizmaları aracılığıyla enjekte edilmesi önerilir.

JAR İmzalama

sslTrusJarsigner, Java Security Provider mekanizması üzerinden standart jarsigner aracıyla entegre edilir.

Aşağıdaki örnek:

app-unsigned.jar

İmzalandıktan sonra çıktı:

app-signed.jar

JDK 9 veya üzeri

Linux ve macOS:

jarsigner \
  -keystore NONE \
  -storetype SSLTRUS \
  -storepass SSLTRUS \
  -providerPath "sslTrusJarsigner-<version>.jar" \
  -providerClass com.racent.codesign.SSLTrusProvider \
  -sigalg SHA256withRSA \
  -tsa http://timestamp.sectigo.com \
  -signedjar "app-signed.jar" \
  "app-unsigned.jar" \
  "$SSLTRUS_JARSIGNER_CERT_CODE"

Windows PowerShell:

jarsigner `
  -keystore NONE `
  -storetype SSLTRUS `
  -storepass SSLTRUS `
  -providerPath "sslTrusJarsigner-<version>.jar" `
  -providerClass com.racent.codesign.SSLTrusProvider `
  -sigalg SHA256withRSA `
  -tsa http://timestamp.sectigo.com `
  -signedjar "app-signed.jar" `
  "app-unsigned.jar" `
  "$env:SSLTRUS_JARSIGNER_CERT_CODE"

JDK 8

JDK 8, Provider'ı JDK 9 ve daha yeni sürümlerden farklı bir şekilde yükler.

Önce şunları doğrulayın:

JAVA_HOME

Tam JDK 8 kurulum dizinini işaret edin.

Linux ve macOS:

jarsigner \
  -J-cp \
  -J"$JAVA_HOME/lib/tools.jar:sslTrusJarsigner-<version>.jar" \
  -keystore NONE \
  -storetype SSLTRUS \
  -storepass SSLTRUS \
  -providerClass com.racent.codesign.SSLTrusProvider \
  -sigalg SHA256withRSA \
  -tsa http://timestamp.sectigo.com \
  -signedjar "app-signed.jar" \
  "app-unsigned.jar" \
  "$SSLTRUS_JARSIGNER_CERT_CODE"

Windows PowerShell：

jarsigner `
  -J-cp `
  "-J$env:JAVA_HOME\lib\tools.jar;sslTrusJarsigner-<version>.jar" `
  -keystore NONE `
  -storetype SSLTRUS `
  -storepass SSLTRUS `
  -providerClass com.racent.codesign.SSLTrusProvider `
  -sigalg SHA256withRSA `
  -tsa http://timestamp.sectigo.com `
  -signedjar "app-signed.jar" `
  "app-unsigned.jar" `
  "$env:SSLTRUS_JARSIGNER_CERT_CODE"

Kullanırken dikkat edilmesi gerekenler:

• Komutun sonundaki sertifika numarası SSLTRUS_JARSIGNER_CERT_CODE ile aynı olmalıdır.
• Orijinal JAR'ın üzerine yazılmasını önlemek için -signedjar kullanarak yeni bir dosyaya çıktı almanız önerilir.
• Örnekte kod imzalama işlemi SHA256withRSA ile tamamlanmıştır.
• Zaman damgası gerekmiyorsa -tsa ve ondan sonraki zaman damgası adresini silebilirsiniz.

Zaman Damgası

Resmi olarak yayımlanan JAR imzalarına güvenilir bir zaman damgası eklenmesi önerilir.

Örnekte şu kullanılmıştır:

http://timestamp.sectigo.com

Karşılık gelen parametre:

-tsa http://timestamp.sectigo.com

Zaman damgası, imzanın gerçekleştiği zamanı kanıtlamak için kullanılır ve orijinal JAR dosyası zaman damgası sunucusuna yüklenmez.

Başka bir zaman damgası hizmeti kullanmanız gerekirse, -tsa sonrasındaki adresi, gerçek imza politikasına uygun TSA adresiyle değiştirebilirsiniz.

Farklı zaman damgası hizmetleri ve üretim ortamı seçimi hakkında bilgi için referanslara bakın.

XML İmzası

sslTrusJarsigner ayrıca XML dijital imza yeteneği de sunar.

XML dosyaları, sign-xml komutuyla XMLDSig Enveloped Signature üretebilir.

İmzalama sürecinde, XMLDSig için gereken özet ve imza yapısı yerel olarak oluşturulur; gerçek RSA özel anahtar imzası ise uzak kod imzalama hizmeti tarafından tamamlanır.

Linux ve macOS

java -jar sslTrusJarsigner-<version>.jar \
  sign-xml \
  "input.xml" \
  "signed.xml" \
  "$SSLTRUS_JARSIGNER_CERT_CODE"

Windows PowerShell

java -jar sslTrusJarsigner-<version>.jar `
  sign-xml `
  "input.xml" `
  "signed.xml" `
  "$env:SSLTRUS_JARSIGNER_CERT_CODE"

Varsayılan çıktı KeyInfo yalnızca yaprak sertifikayı içerir. Alıcı taraf, XML içinde tam sertifika zincirinin bulunmasını istiyorsa, komutun sonuna --full-chain parametresini ekleyebilirsiniz.

Yürütme tamamlandıktan sonra:

input.xml

Orijinal XML dosyası için,

signed.xml

Türkçe: XML dijital imzası içeren çıktı dosyası için.

Kod imzalama özel anahtarı XML dosyasına yazılmaz ve yerel bilgisayara kaydedilmez.

Doğrulama Dosyası Oluşturma

İmzalama tamamlandıktan sonra, imzayı doğrulamak için kullanılabilecek bir JKS dosyası oluşturulabilir.

Linux ve macOS:

java -jar sslTrusJarsigner-<version>.jar \
  generate-keystore \
  "$SSLTRUS_JARSIGNER_CERT_CODE" \
  "verify.jks" \
  "SSLTRUS"

Windows PowerShell：

java -jar sslTrusJarsigner-<version>.jar `
  generate-keystore `
  "$env:SSLTRUS_JARSIGNER_CERT_CODE" `
  "verify.jks" `
  "SSLTRUS"

Oluşturuluyor:

verify.jks

Bu dosya yalnızca imza doğrulaması için kullanılır; kod imzalama işlemi gerçekleştirmek için kullanılamaz.

Kod imzalama özel anahtarı uzak HSM'de saklanmaya devam eder ve verify.jks içine yazılmaz.

JAR İmzasını Doğrulama

İmzayı doğrulamak için oluşturulan verify.jks kullanın:

jarsigner \
  -verify \
  -verbose \
  -certs \
  -keystore "verify.jks" \
  -storetype JKS \
  -storepass "SSLTRUS" \
  "app-signed.jar"

Yalnızca JAR içindeki mevcut imza bilgilerini görüntülemek istiyorsanız şunu çalıştırabilirsiniz:

jarsigner -verify -verbose -certs "app-signed.jar"

İmza doğrulama yalnızca mevcut imzayı kontrol eder; uzak özel anahtarı yeniden çağırarak imza işlemi gerçekleştirmez.

İmzalama Sayısı

Jarsigner'ın imzalama sayısı, gerçekte başarıyla tamamlanan uzak imzalama eylemlerine göre hesaplanır.

Genellikle:

İşlem	İmzalama Sayısı
Bir JAR dosyasını bir kez başarıyla imzalamak	1 kez
3 JAR dosyasını ayrı ayrı imzalamak	3 kez
Aynı JAR dosyasını tekrar imzalamak	tekrar 1 kez eklenir
jarsigner -verify imzayı doğrulamak	0 kez
verify.jks oluşturmak	0 kez

Bu nedenle imzalama sayısı, Java projesindeki kaynak kod dosyası sayısına değil, esas olarak gerçekte kaç kez başarılı imzalama işlemi yapıldığına bağlıdır.

Ayrıntılı kurallar için lütfen referans belgelere bakın.

Sık Sorulan Sorular

Access Key, Access Secret veya sertifika numarası eksik

Geçerli terminalde şunların ayarlandığından emin olun:

SSLTRUS_JARSIGNER_ACCESS_KEY
SSLTRUS_JARSIGNER_ACCESS_SECRET
SSLTRUS_JARSIGNER_CERT_CODE

Ortam değişkenlerini ayarladıktan sonra imzalama komutunu aynı terminal oturumunda çalıştırmanız gerekir.

Invalid option: -providerPath

Aşağıdaki durum ortaya çıkarsa:

Invalid option: -providerPath

Genellikle şu anda JDK 8 kullanıldığını gösterir.

JDK 8, JDK 9 ve daha yüksek sürüm örneklerindeki -providerPath parametresini kullanmaz; lütfen bu makalede sağlanan JDK 8 komutunu kullanın.

SSLTrusProvider yüklenemiyor

Yüklenemediğine dair bir uyarı alırsanız:

com.racent.codesign.SSLTrusProvider

Lütfen kontrol edin:

• sslTrusJarsigner-<version>.jar yolunun doğru olup olmadığını.
• Dosya adındaki sürüm numarasının gerçek dosyayla eşleşip eşleşmediğini.
• JDK 8 ortamındaki JAVA_HOME öğesinin tam bir JDK'yı işaret edip etmediğini.

Sertifika veya alias bulunamadı

Lütfen kontrol edin:

• Sertifika numarasının doğru olup olmadığını.
• Komutun sonunda belirtilen sertifika numarasının SSLTRUS_JARSIGNER_CERT_CODE ile eşleşip eşleşmediğini.
• Geçerli Access Key ve Access Secret'ın bu sertifikayı kullanma iznine sahip olup olmadığını.

Uzak imzalama isteği başarısız oldu

Lütfen kontrol edin:

• Geçerli ağın uzak kod imzalama hizmetine erişip erişemediğini.
• Proxy, güvenlik duvarı ve DNS yapılandırmalarının normal olup olmadığını.
• Access Key ve Access Secret'ın doğru olup olmadığını.
• Sertifika numarasının doğru olup olmadığını.
• Özel hizmet adresi kullanılıyorsa SSLTRUS_JARSIGNER_URL öğesinin gerçek teslimat bilgilerine göre yapılandırılıp yapılandırılmadığını.

Sorunları araştırırken tam hata bilgileri saklanabilir, ancak günlükleri veya hata ekran görüntülerini göndermeden önce Access Secret gibi hassas kimlik bilgileri silinmeli veya maskelenmelidir.

Zaman damgası başarısız oldu

Geçerli ağın -tsa tarafından belirtilen zaman damgası sunucusuna erişebildiğini doğrulayın.

İş gereksinimleri izin veriyorsa, geçici olarak kaldırabilirsiniz:

-tsa <URL>

İmzalamayı tekrar çalıştırarak sorunun uzak kod imzalama aşamasında mı yoksa zaman damgası isteği aşamasında mı olduğunu belirleyin.

Güvenlik Notları

Java entegrasyonu sırasında şunlara dikkat edilmelidir:

• Access Secret hassas bir kimlik bilgisi olarak saklanmalıdır.
• Erişim kimlik bilgilerini Git deposuna göndermeyin.
• Günlüklere Access Secret'ın tamamını yazdırmayın.
• verify.jks yalnızca doğrulama içindir ve uzak imzalama için kullanılabilecek özel anahtar içermez.
• Yerel sslTrusJarsigner Provider, kod imzalama özel anahtarını saklamaz.
• Özel anahtarla imzalama işlemi her zaman uzak kod imzalama hizmeti tarafından gerçekleştirilir.
• Otomasyon ortamlarında erişim kimlik bilgilerinin CI/CD Secret veya özel bir kimlik bilgisi yönetim sistemi aracılığıyla enjekte edilmesi önerilir.

İlgili Entegrasyon Yöntemleri

İmzalanması gereken dosyalar Java JAR veya XML dosyaları değilse, gerçek senaryoya göre diğer entegrasyon yöntemleri seçilebilir:

Senaryo	Entegrasyon Yöntemi
EXE, DLL, MSI gibi dosyaları doğrudan komut satırından imzalama	İstemci Aracı
Microsoft SignTool, Visual Studio gibi Windows araçları	Windows Provider
GitHub Actions, Electron Builder gibi otomatik derleme süreçleri	CI/CD ve Derleme Araçları
Kendi uzak imzalama istemcinizi geliştirme	API Entegrasyonu