Ana içeriğe geç

sslTrusJarsigner Kullanım Kılavuzu

Hazırlık​

Kullanmadan önce hazırlayın:

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

Bu makaledeki <version>, kimlik bilgileri, sertifika numarası 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 sağlama dosyası

Kullanmadan önce sağlama dosyasına göre JAR dosyasının bütünlüğünü doğrulamanız önerilir.

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

Java, jarsigner ve araç dosyaları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"

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, lütfen bu değişkeni ayarlamayın.

İmza​

Aşağıdaki örnek, app-unsigned.jar imzalandıktan sonra app-signed.jar olarak kaydedilir. Sabit parametreleri örnekteki gibi aynen kullanın.

JDK 9 veya daha yüksek 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 bir 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 aynı olmalıdır.
  • Orijinal JAR'ın üzerine yazmamak için her zaman -signedjar ile yeni bir dosya oluşturmanız önerilir.
  • Zaman damgası gerekmiyorsa -tsa ve sonrasındaki adresi silebilirsiniz.

XML İmzalama (XMLDSig)​

TIMS/1E XML'i, XML Digital Signature (XMLDSig) enveloped imza oluşturmak için sign-xml komutunu kullanır. Özel anahtar yalnızca uzak imzalama hizmetinde saklanmaya devam eder; araç XMLDSig için gereken özet ve imza yapısını yerel olarak oluşturur, ardından RSA imzası uzak hizmet 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"

İmza Formatı​

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

ÖğeSabit Değer
İmza TürüEnveloped signature
İmza KapsamıXML belgesinin tamamı, 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ına veya SignatureValue oluşturmasına gerek yoktur. Araç, uzak sertifikanın yaprak sertifikasını kullanarak KeyInfo/X509Data doldurur ve XML’e son SignatureValue yazar.

Tam Sertifika Zincirini Dahil Etme​

Varsayılan çıktı, XML boyutunu küçültmek ve yaygın TIMS/1E dosyalarıyla tutarlılığı sağlamak için yalnızca yaprak sertifikayı içerir. Alıcı taraf, XML içinde ara sertifika zincirinin bulunmasını istiyorsa 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ı verilmediğinde 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ı doğrulanamayan dosyaların oluşmasını önlemek için tekrarlanan imzalamayı reddeder.
  • Şu anda yalnızca tüm belge için enveloped imza desteklenir; detached imza, öğ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 dayanan 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 neden olur. Her zaman orijinal girdi dosyasını koruyun ve imza sonucunu yeni bir çıktı dosyasına yazın.

Doğrulama Dosyası Oluşturma​

İmzalamadan sonra doğrulama için gereken 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"

verify.jks yalnızca imza doğrulama amacıyla kullanılır; imza gerçekleştirmek için kullanılamaz.

İmza 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​

Erişim Anahtarı, Erişim Sırrı veya sertifika numarası eksik uyarısı​

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

Geçersiz seçenek: -providerPath uyarısı​

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

com.racent.codesign.SSLTrusProvider yüklenemiyor uyarısı​

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'in JAVA_HOME değerinin tam JDK'yi gösterip göstermediğini.

Sertifika veya alias bulunamadı uyarısı​

Lütfen kontrol edin:

  • Sertifika numarasının doğru olup olmadığını.
  • Komutun sonundaki sertifika numarasının ortam değişkeniyle tutarlı 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ı, 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ülemiyorsa lütfen tam hata bilgisini saklayın ve teknik destekle iletişime geçin. Hata bilgisini göndermeden önce lütfen kimlik bilgilerini silin veya gizleyin.

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

Mevcut ağın komuttaki zaman damgası adresine erişebildiğinden emin olun. İş koşulları izin veriyorsa -tsa ve sonrasındaki adresi geçici olarak silip imzalamayı yeniden çalıştırarak sorunu tespit edebilirsiniz.

Güvenlik Notları​

  • Gerçek Erişim Sırrını kaynak kodda, belgelerde, paylaşılan komut dosyalarında veya imajlarda 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 korumalı gizli değişkenler aracılığıyla 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 dosyasını saklamanız önerilir.
En son tarihinde güncellendi