Ana içeriğe geç

sslTrusJarsigner Kullanım Kılavuzu

Hazırlık​

Kullanmadan önce hazırlayın:

  • JDK 8 veya daha yüksek bir sürüm.
  • sslTrusJarsigner-<version>.jar.
  • Access Key, Access Secret ve sertifika numarası.
  • İmzalanacak JAR dosyası veya TIMS/1E XML dosyası.

Lütfen bu metindeki <version>, kimlik bilgilerini, sertifika numarasını ve dosya yollarını gerçek değerlerle değiştirin.

İndirme​

En son sürüm paketini aşağıdaki sayfadan indirin:

En son paketi indir

ZIP dosyasını indirip açtıktan sonra şunları elde edersiniz:

  • sslTrusJarsigner-<version>.jar
  • SHA-256 doğrulama dosyası

Kullanmadan önce doğrulama dosyasına göre JAR dosyasının bütünlüğünü kontrol etmeniz önerilir.

Çalışma ortamını kontrol etme​

Java, jarsigner ve araç dosyasının kullanılabilir olduğunu doğrulamak için aşağıdaki komutu çalıştırın:

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

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

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

Kimlik Bilgilerini Yapılandırma​

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"

Yetkili personel özel bir servis adresi sağladıysa, ayrıca şunu da ayarlamanız gerekir:

Linux ve macOS:

export SSLTRUS_JARSIGNER_URL="YOUR_SERVICE_URL"

Windows PowerShell：

$env:SSLTRUS_JARSIGNER_URL = "YOUR_SERVICE_URL"

Özel bir hizmet adresi sağlanmadığında, bu değişkeni ayarlamayın.

İmza​

Aşağıdaki örnek, app-unsigned.jar imzaladıktan sonra app-signed.jar olarak kaydeder. Sabit parametreleri örnekte gösterildiği gibi kullanın.

JDK 9 veya daha yeni 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​

Lütfen önce JAVA_HOME öğesinin eksiksiz JDK 8'e işaret ettiğini doğrulayın.

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"
Dikkat
  • Komutun sonundaki sertifika numarası SSLTRUS_JARSIGNER_CERT_CODE ile eşleşmelidir.
  • Orijinal JAR'ın üzerine yazılmasını önlemek için her zaman -signedjar kullanarak yeni bir dosya oluşturmanız önerilir.
  • Zaman damgası gerekmiyorsa -tsa ve sonrasındaki adresi silebilirsiniz.

XML İmzalama (XMLDSig)​

TIMS/1E XML, XML Digital Signature (XMLDSig) enveloped imzayı oluşturmak için sign-xml komutunu kullanır. Özel anahtar yalnızca uzak imza hizmetinde tutulmaya devam eder; araç XMLDSig için gerekli özet ve imza yapısını yerelde oluşturur, ardından uzak hizmet RSA imzalamasını tamamlar.

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"

İmza Formatı​

Oluşturulan imza, XMLDSig standart ad alanını http://www.w3.org/2000/09/xmldsig# kullanır ve Signature düğümü, kök düğümün son alt düğümü olarak çıktı dosyasına yazılır. Geçerli imza profili aşağıdaki gibi sabittir:

ÖğeSabit Değer
İmza TürüEnveloped signature
İmza KapsamıTüm XML belgesi, Reference URI=""
Reference TransformEnveloped Signature Transform
CanonicalizationInclusive Canonical XML 1.0
Özet AlgoritmasıSHA-256
İmza AlgoritmasıRSA-SHA256
KeyInfoX509Data, varsayılan olarak yaprak sertifikayı içerir

Çağıran tarafın özeti kendisi hesaplaması veya SignatureValue oluşturması gerekmez. Araç, uzak sertifikanın yaprak sertifikasını kullanarak KeyInfo/X509Data alanını doldurur ve XML’e nihai SignatureValue değerini yazar.

Tam Sertifika Zincirini Dahil Etme​

Varsayılan çıktı yalnızca yaprak sertifikayı içerir; bu, XML boyutunu azaltır ve yaygın TIMS/1E dosyalarıyla tutarlılık sağlar. Alıcı taraf, XML içinde ara sertifika zincirinin bulunmasını talep ediyorsa komutun sonuna --full-chain ekleyin:

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

--full-chain yalnızca KeyInfo/X509Data içindeki sertifika listesini etkiler; imza kapsamını, özet algoritmasını veya imza algoritmasını değiştirmez. Bu seçenek sertifika numarasından önce veya sonra yerleştirilebilir; sertifika numarası sağlanmadığında SSLTRUS_JARSIGNER_CERT_CODE kullanılır.

Girdi ve Kullanım Kısıtlamaları​

  • Girdi, doğru biçimlendirilmiş XML olmalı ve bir kök düğüm içermelidir.
  • Girdi dosyası zaten bir XMLDSig Signature düğümü içeremez; araç, imza kapsamı belirsiz dosyaların oluşmasını önlemek için yinelenen imzalamayı reddeder.
  • Şu anda yalnızca tüm belgenin enveloped imzası desteklenir; detached signature, öğe kimliğine göre imzalama veya özel XMLDSig profili desteklenmez.
  • Araç, XML harici varlıklarını ve harici DTD yüklemeyi devre dışı bırakır; bu nedenle harici varlık genişletmeye bağımlı XML kabul edilmez.
  • İmzalama tamamlandıktan sonra XML’in yapısını, metnini, özniteliklerini veya ad alanlarını değiştirmeyin; bu tür herhangi bir değişiklik XMLDSig doğrulamasının başarısız olmasına yol açar. Orijinal girdi dosyası her zaman korunmalı ve imzalama sonucu yeni bir çıktı dosyasına yazılmalıdır.

Doğrulama Dosyası Oluşturma​

İmzaladıktan sonra, doğrulama için gereken JKS dosyasını 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"

verify.jks yalnızca imzayı doğrulamak için kullanılır, imza oluşturmak için kullanılamaz.

İmzayı Doğrulama​

Oluşturulan verify.jks ile imzalanmış JAR'ı doğrulayın:

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

Yalnızca JAR imza bilgilerini görüntülemeniz gerekiyorsa:

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

SSS​

Access Key, Access Secret veya sertifika numarasının eksik olduğu belirtiliyor​

Lütfen mevcut terminalde aşağıdaki ortam değişkenlerinin 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 penceresinde çalıştırmanız gerekir.

Geçersiz seçenek: -providerPath belirtiliyor​

Şu anda JDK 8 kullanıyorsunuz. Lütfen bu makaledeki JDK 8 imzalama komutunu kullanın.

com.racent.codesign.SSLTrusProvider yüklenemediği belirtiliyor​

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 uyumlu olup olmadığını.
  • JDK 8'in JAVA_HOME tam bir JDK'yı işaret edip etmediğini.

Sertifika veya alias bulunamadığı belirtiliyor​

Lütfen kontrol edin:

  • Sertifika numarasının doğru olup olmadığını.
  • Komutun sonundaki sertifika numarasının ortam değişkeniyle uyumlu olup olmadığını.
  • Mevcut kimlik bilgisinin bu sertifikayı kullanma yetkisinin olup olmadığını.

İmzalama isteği başarısız oldu​

Lütfen kontrol edin:

  • Ağ bağlantısını, proxy ve güvenlik duvarı ayarlarını.
  • Kimlik bilgisi ve sertifika numarasının doğru olup olmadığını.
  • Özel servis adresinin servis yetkilisinin sağladığı içeriğe göre yapılandırılıp yapılandırılmadığını.

Sorun hâlâ çözülmezse lütfen eksiksiz hata bilgisini saklayın ve teknik destekle iletişime geçin. Hata bilgisini göndermeden önce kimlik bilgilerini silin veya gizleyin.

Zaman damgası başarısız oldu​

Lütfen mevcut ağın komuttaki zaman damgası adresine erişebildiğini doğrulayın. İşiniz izin veriyorsa sorunu belirlemek için -tsa ve sonrasındaki adresi geçici olarak silip imzalamayı yeniden çalıştırabilirsiniz.

Güvenlik notları​

  • Kaynak kodda, belgelerde, paylaşılan betiklerde veya imajlarda gerçek Access Secret saklamayın.
  • Kimlik bilgisi içeren komut satırlarını, terminal geçmişini veya ardışık düzen günlüklerini dışarıyla paylaşmayın.
  • Otomasyon ortamlarında kimlik bilgilerini korunan gizli anahtar değişkenleriyle enjekte edin.
  • Araçları güvenilir yayın kanallarından indirin ve kullanmadan önce dosya bütünlüğünü doğrulayın.
  • İmzasız orijinal JAR dosyalarının saklanması önerilir.
En son tarihinde güncellendi