Java Entegrasyonu

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

İmzalama sürecinde kod imzalama özel anahtarı her zaman bulut HSM içinde saklanır. Yerel taraf imzalanacak verileri ve imza yapısını oluşturmaktan sorumludur ve sslTrusJarsigner Provider üzerinden ö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ılabilecek XMLDSig imzalama yeteneği de sunar.

Hazırlık

Kullanmadan önce lütfen şunları hazırlayın:

• JDK 8 veya daha yüksek sürüm.
• 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 tümü gerçek değerlerle değiştirilmelidir.

sslTrusJarsigner'ı indirme

sslTrusJarsigner yayın sayfasından en son yayın paketini indirin ve sıkıştırmayı açın.

Yayın paketi şunları içerir:

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

Kullanmadan önce dosyanın bütünlüğünü SHA-256 sağlama değeri ile doğrulamanız önerilir: sslTrusJarsigner-<version>.jar.

Çalışma Ortamını Kontrol Etme

Öncelikle Java ve JDK ile birlikte gelen jarsigner aracının düzgün çalıştığını doğrulayın:

java -version
jarsigner -help

sslTrusJarsigner 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şkeni ayarlamanız gerekmez.

Access Secret hassas bir kimlik bilgisidir; kaynak koda, genel yapılandırma dosyalarına veya derleme günlüklerine yazılmamalıdır. Otomasyon ortamlarında CI/CD Secret veya başka bir kimlik bilgisi yönetim mekanizması aracılığıyla enjekte edilmesi önerilir.

JAR İmzalama

sslTrusJarsigner, Java Security Provider mekanizması aracılığıyla standart jarsigner aracıyla entegre olur.

Aşağıdaki örnek şunları yapacaktır:

app-unsigned.jar

İmzalandıktan sonra çıktı:

app-signed.jar

JDK 9 veya daha yeni bir sürüm

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’ı yükleme biçimi JDK 9 ve daha yeni sürümlerden farklıdır.

Önce şunu doğrulayın:

JAVA_HOME

İşaret edilen dizin, tam JDK 8 kurulum dizini olmalıdır.

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ım sırasında 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 SHA256withRSA ile tamamlanmaktadır.
• Zaman damgası gerekmediğinde -tsa ve sonrasındaki zaman damgası adresi silinebilir.

Zaman Damgası

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

Örnekte kullanılan:

http://timestamp.sectigo.com

İlgili parametreler:

-tsa http://timestamp.sectigo.com

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

Başka bir zaman damgası hizmeti kullanmanız gerekiyorsa, -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 referans belgelere bakın.

XML İmzası

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

XML dosyaları, sign-xml komutuyla XMLDSig Enveloped Signature oluşturabilir.

İmzalama sürecinde ö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

İmzalı XML dosyaları 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 bir JKS dosyası oluşturabilirsiniz.

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şturun:

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ı hâlâ uzak HSM'de saklanır ve verify.jks içine yazılmaz.

JAR İmzasını Doğrulama

Oluşturulan verify.jks dosyasını kullanarak imzayı doğrulayı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ülemeniz gerekiyorsa ş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.

İmza Sayısı

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

Genellikle:

İşlem	İmza Sayısı
Bir JAR'ı bir kez başarıyla imzalama	1 kez
3 JAR'ı ayrı ayrı imzalama	3 kez
Aynı JAR'ı yeniden imzalama	1 kez daha eklenir
jarsigner -verify imza doğrulama	0 kez
verify.jks oluşturma	0 kez

Bu nedenle imza 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 materyale bakın.

Sık Sorulan Sorular

Access Key, Access Secret veya sertifika numarası eksik

Geçerli terminalde şunların ayarlandığını doğrulayın:

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ırmalısınız.

Invalid option: -providerPath

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

Invalid option: -providerPath

Genellikle mevcut kullanımın JDK 8 olduğunu gösterir.

JDK 8, JDK 9 ve daha yeni sürüm örneklerindeki -providerPath parametresini kullanmaz; bunun yerine bu makalede verilen JDK 8 komutunu kullanın.

SSLTrusProvider yüklenemedi

Yüklenemediğine dair bir uyarı görünüyorsa:

com.racent.codesign.SSLTrusProvider

Lütfen kontrol edin:

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

Sertifika veya alias bulunamadı

Lütfen kontrol edin:

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

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

Lütfen kontrol edin:

• Geçerli ağın uzaktan kod imzalama hizmetine erişip erişemediğini kontrol edin.
• Proxy, güvenlik duvarı ve DNS yapılandırmasının normal olup olmadığını kontrol edin.
• Access Key ve Access Secret'ın doğru olup olmadığını kontrol edin.
• Sertifika numarasının doğru olup olmadığını kontrol edin.
• Ö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ı kontrol edin.

Sorun giderirken tam hata bilgisi 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ğinden emin olun.

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

-tsa <URL>

Yeniden imzalayarak sorunun uzak kod imzalama aşamasında mı yoksa zaman damgası isteği aşamasında mı oluştuğunu belirleyin.

Güvenlik Notları

Java entegrasyonu sırasında aşağıdakilere dikkat edin:

• Access Secret hassas bir kimlik bilgisi olarak saklanmalıdır.
• Erişim kimlik bilgilerini Git deposuna göndermeyin.
• Loglarda tam Access Secret değerini görüntülemeyin.
• verify.jks yalnızca doğrulama için kullanılır, uzak imzalama için kullanılabilecek özel anahtar içermez.
• Yerel sslTrusJarsigner Provider, kod imzalama özel anahtarını saklamaz.
• Özel anahtar 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 kimlik bilgisi yönetim sistemi aracılığıyla enjekte edilmesi önerilir.

İlgili Entegrasyon Yöntemleri

İmzalanacak dosya Java JAR veya XML dosyası değilse, gerçek senaryoya göre diğer entegrasyon yöntemlerini seçebilirsiniz:

Senaryo	Entegrasyon Yöntemi
Komut satırı üzerinden EXE, DLL, MSI vb. dosyaları doğrudan imzalama	İstemci Aracı
Microsoft SignTool, Visual Studio vb. Windows araçları	Windows Provider
GitHub Actions, Electron Builder vb. otomatik derleme	CI/CD ve Derleme Araçları
Uzak imzalama istemcisini kendiniz geliştirme	API Entegrasyonu