Ana içeriğe geç

sslTrusJarsigner Kullanım Kılavuzu

Hazırlık​

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

  • JDK 8 veya üzeri 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 makaledeki <version>、kimlik bilgilerini、sertifika numarasını ve dosya yollarını gerçek değerlerle değiştirin.

İndirme​

En son yayın 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ç 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üle:

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 için:

export SSLTRUS_JARSIGNER_URL="YOUR_SERVICE_URL"

Windows PowerShell：

$env:SSLTRUS_JARSIGNER_URL = "YOUR_SERVICE_URL"

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

İmzalama​

Aşağıdaki örnek, app-unsigned.jar dosyasını imzalayıp app-signed.jar olarak kaydeder. Sabit parametreleri örnekte gösterildiği şekilde kullanın.

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​

Öncelikle JAVA_HOME öğesinin tam bir JDK 8'i 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.
  • Yeni dosyalar üretmek için her zaman -signedjar kullanılması önerilir; böylece orijinal JAR dosyasının üzerine yazılması önlenir.
  • Zaman damgası gerekmiyorsa, -tsa ve sonrasındaki adres silinebilir.

XML İmzalama (XMLDSig)​

TIMS/1E XML, sign-xml komutu ile XML Digital Signature (XMLDSig) enveloped imzası oluşturur. Özel anahtar yalnızca uzak imza hizmetinde kalır; araç, XMLDSig için gereken özet ve imza yapısını yerel olarak üretir ve 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 Biçimi​

Üretilen imza, XMLDSig standart ad alanını kullanır http://www.w3.org/2000/09/xmldsig# ve Signature düğümü, çıktı dosyasına kök düğümün son alt öğesi olarak yazılır. Geçerli imza profili şu şekilde sabitlenmiştir:

ÖğeSabit Değer
İmza TürüEnveloped signature (Sarmalayıcı İmza)
İmza KapsamıTüm XML belgesi, Reference URI=""
Reference Transform (Başvuru Dönüşümü)Enveloped Signature Transform (Sarmalayıcı İmza Dönüşümü)
Canonicalization (Kanonikleştirme)Inclusive Canonical XML 1.0
Özet AlgoritmasıSHA-256
İmza AlgoritmasıRSA-SHA256
KeyInfoX509Data, varsayılan olarak yaprak sertifikayı içerir

Arayanın özeti kendisinin hesaplaması veya SignatureValue oluşturması gerekmez. Araç, uzak sertifikanın yaprak sertifikasını kullanarak KeyInfo/X509Data öğesini doldurur ve XML'e nihai SignatureValue öğesini yazar.

Tam Sertifika Zincirinin Dahil Edilmesi​

Varsayılan çıktı yalnızca yaprak sertifikayı içerir; bu, XML boyutunu küçültür ve yaygın TIMS/1E dosyalarıyla uyumluluğu korur. Alıcı taraf XML içinde ara sertifika zincirinin de 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ı sağlanmadığında SSLTRUS_JARSIGNER_CERT_CODE kullanılır.

Giriş ve Kullanım Kısıtlamaları​

  • Giriş, biçimi doğru bir XML olmalı ve kök düğüm içermelidir.
  • Giriş dosyası zaten bir XMLDSig Signature düğümü içeremez; araç, imza kapsamı doğrulanamayan dosyalar oluşturmamak için tekrarlanan imzaları reddeder.
  • Şu anda yalnızca belgenin tamamı için enveloped imza desteklenir; detached signature, öğe kimliğine göre imzalama veya özel XMLDSig profili desteklenmez.
  • Araç, XML dış varlıklarını ve harici DTD yüklemeyi devre dışı bırakır; bu nedenle dış varlık genişletmesine bağlı XML'ler kabul edilmez.
  • İmza tamamlandıktan sonra XML'in yapısını, metnini, niteliklerini 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. Orijinal giriş dosyasını her zaman saklayın 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 imzayı doğrulamak için kullanılır, imza işlemini gerçekleştirmek için kullanılamaz.

İmzayı Doğrulama​

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

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

Yalnızca JAR dosyasının imza bilgilerini görüntülemek için:

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

Sıkça Sorulan Sorular​

Erişim Anahtarı, Erişim Gizli Anahtarı veya Sertifika Numarası Eksik Uyarısı​

Lütfen geçerli 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 Uyarısı​

Şu anda JDK 8 kullanıyorsunuz. Lütfen bu makaledeki 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'ya işaret edip etmediğini.

Sertifika veya Alias Bulunamıyor 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 eşleşip eşleşmediğini.
  • Geçerli kimlik bilgilerinin bu sertifikayı kullanma yetkisine sahip olup olmadığını.

İmzalama İsteği Başarısız Oldu​

Lütfen kontrol edin:

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

Sorun hâlâ çözülmezse, lütfen tam hata mesajını saklayın ve teknik desteğe başvurun. Hata mesajını göndermeden önce kimlik bilgilerini silin veya karartın.

Zaman Damgası Başarısız Oldu​

Lütfen geçerli ağın komuttaki zaman damgası adresine erişebildiğini doğrulayın. İş akışınız izin veriyorsa, sorunu bulmak için -tsa ve sonrasındaki adresi geçici olarak silip yeniden imzalama işlemini gerçekleştirebilirsiniz.

Güvenlik Önlemleri​

  • Kaynak kodda, belgelerde, paylaşılan betiklerde veya görüntülerde gerçek Erişim Gizli Anahtarı'nı saklamayın.
  • Kimlik bilgilerini içeren komut satırlarını, terminal geçmişini veya işlem hattı günlüklerini başkalarıyla paylaşmayın.
  • Otomasyon ortamlarında kimlik bilgilerini enjekte etmek için korumalı anahtar değişkenleri kullanın.
  • 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