sslTrusJarsigner Benutzerhandbuch

Vorbereitung

Bitte bereiten Sie Folgendes vor:

• JDK 8 oder höher.
• sslTrusJarsigner-<version>.jar.
• Access Key, Access Secret und Zertifikatsnummer.
• Die zu signierende JAR-Datei oder TIMS/1E XML-Datei.

Bitte ersetzen Sie <version>, Anmeldeinformationen, Zertifikatsnummer und Dateipfade in diesem Dokument durch die tatsächlichen Werte.

Herunterladen

Laden Sie das neueste Release-Paket über die folgende Seite herunter:

Neuestes Paket herunterladen

Nach dem Herunterladen und Entpacken der ZIP-Datei erhalten Sie:

• sslTrusJarsigner-<version>.jar
• SHA-256-Prüfdatei

Es wird empfohlen, die Integrität der JAR-Datei vor der Verwendung anhand der Prüfdatei zu überprüfen.

Laufzeitumgebung überprüfen

Führen Sie den folgenden Befehl aus, um zu bestätigen, dass Java, jarsigner und die Werkzeugdateien verfügbar sind:

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

Hilfeinformationen anzeigen:

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

Anmeldeinformationen konfigurieren

Linux und 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"

Wenn das Servicepersonal eine dedizierte Dienstadresse bereitgestellt hat, muss außerdem Folgendes festgelegt werden:

Linux und macOS:

export SSLTRUS_JARSIGNER_URL="YOUR_SERVICE_URL"

Windows PowerShell:

$env:SSLTRUS_JARSIGNER_URL = "YOUR_SERVICE_URL"

Wenn keine dedizierte Dienstadresse angegeben ist, setzen Sie diese Variable bitte nicht.

Signatur

Im folgenden Beispiel wird app-unsigned.jar signiert und anschließend als app-signed.jar gespeichert. Feste Parameter verwenden Sie bitte unverändert wie im Beispiel.

JDK 9 oder höher

Linux und 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

Bitte stellen Sie zunächst sicher, dass JAVA_HOME auf das vollständige JDK 8 verweist.

Linux und 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"

Hinweis

• Die Zertifikatsnummer am Ende des Befehls muss mit SSLTRUS_JARSIGNER_CERT_CODE übereinstimmen.
• Es wird empfohlen, immer -signedjar zu verwenden, um neue Dateien zu generieren und ein Überschreiben der ursprünglichen JAR zu vermeiden.
• Wenn kein Zeitstempel benötigt wird, können Sie -tsa und die darauf folgende Adresse löschen.

XML signieren (XMLDSig)

TIMS/1E XML verwendet den Befehl sign-xml, um eine XML Digital Signature (XMLDSig) enveloped Signatur zu generieren. Der private Schlüssel verbleibt weiterhin ausschließlich im Remote-Signaturdienst; das Tool erstellt lokal die für XMLDSig erforderlichen Digest- und Signaturstrukturen, und der Remote-Dienst führt anschließend die RSA-Signatur durch.

Linux und 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"

Signaturformat

Die erzeugte Signatur verwendet den XMLDSig-Standardnamespace http://www.w3.org/2000/09/xmldsig#, der Knoten Signature wird als letzter Kindknoten des Wurzelknotens in die Ausgabedatei geschrieben. Das aktuelle Signaturprofil ist wie folgt festgelegt:

Element	Fester Wert
Signaturtyp	Enveloped Signature
Signaturbereich	Gesamtes XML-Dokument, Reference URI=""
Reference Transform	Enveloped Signature Transform
Canonicalization	Inclusive Canonical XML 1.0
Digest-Algorithmus	SHA-256
Signaturalgorithmus	RSA-SHA256
KeyInfo	X509Data, standardmäßig mit Blattzertifikat

Der Aufrufer muss weder den Digest selbst berechnen noch SignatureValue konstruieren. Das Tool füllt KeyInfo/X509Data mit dem Blattzertifikat des Remote-Zertifikats und schreibt die endgültige SignatureValue in das XML.

Vollständige Zertifikatskette einbeziehen

Standardmäßig enthält die Ausgabe nur das Blattzertifikat, um das XML-Volumen zu reduzieren und die Konsistenz mit gängigen TIMS/1E-Dateien zu wahren. Falls der Empfänger verlangt, dass die Zwischenzertifikatskette in der XML enthalten ist, fügen Sie am Ende des Befehls --full-chain hinzu:

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

--full-chain wirkt sich nur auf die Zertifikatsliste in KeyInfo/X509Data aus und ändert weder den Signaturbereich, den Digest-Algorithmus noch den Signaturalgorithmus. Diese Option kann vor oder nach der Zertifikatsnummer angegeben werden; ist keine Zertifikatsnummer angegeben, wird SSLTRUS_JARSIGNER_CERT_CODE verwendet.

Eingabe- und Nutzungsbeschränkungen

• Die Eingabe muss wohlgeformtes XML sein und einen Wurzelknoten enthalten.
• Die Eingabedatei darf noch keinen XMLDSig-Knoten Signature enthalten; das Tool verweigert eine erneute Signierung, um Dateien zu vermeiden, bei denen der Signaturbereich nicht bestätigt werden kann.
• Derzeit wird nur die enveloped-Signatur des gesamten Dokuments unterstützt; detached signatures, Signaturen nach Element-ID oder benutzerdefinierte XMLDSig-Profile werden nicht unterstützt.
• Das Tool deaktiviert das Laden externer XML-Entities und externer DTDs und akzeptiert daher kein XML, das auf die Expansion externer Entities angewiesen ist.
• Ändern Sie nach der Signierung nicht Struktur, Text, Attribute oder Namespaces des XML; jede derartige Änderung führt zum Fehlschlagen der XMLDSig-Validierung. Bewahren Sie stets die ursprüngliche Eingabedatei auf und schreiben Sie das Signaturergebnis in eine neue Ausgabedatei.

Validierungsdatei erzeugen

Nach der Signierung kann die für die Validierung benötigte JKS-Datei erzeugt werden:

Linux und 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 dient nur zur Überprüfung der Signatur und kann nicht zum Signieren verwendet werden.

Signatur überprüfen

Verwenden Sie die generierte verify.jks, um die signierte JAR zu überprüfen:

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

Wenn Sie nur die Signaturinformationen der JAR-Datei anzeigen müssen:

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

Häufig gestellte Fragen

Hinweis auf fehlenden Access Key, Access Secret oder Zertifikatsnummer

Bitte stellen Sie sicher, dass die folgenden Umgebungsvariablen im aktuellen Terminal gesetzt sind:

• SSLTRUS_JARSIGNER_ACCESS_KEY
• SSLTRUS_JARSIGNER_ACCESS_SECRET
• SSLTRUS_JARSIGNER_CERT_CODE

Nachdem die Umgebungsvariablen gesetzt wurden, muss der Signaturbefehl im selben Terminalfenster ausgeführt werden.

Hinweis Ungültige Option: -providerPath

Sie verwenden derzeit JDK 8. Bitte verwenden Sie stattdessen den JDK-8-Signaturbefehl aus diesem Dokument.

Hinweis, dass com.racent.codesign.SSLTrusProvider nicht geladen werden kann

Bitte überprüfen Sie:

• ob der Pfad sslTrusJarsigner-<version>.jar korrekt ist.
• ob die Versionsnummer im Dateinamen mit der tatsächlichen Datei übereinstimmt.
• ob der JAVA_HOME von JDK 8 auf ein vollständiges JDK verweist.

Hinweis, dass das Zertifikat oder der Alias nicht gefunden wird

Bitte überprüfen Sie:

• ob die Zertifikatsnummer korrekt ist.
• ob die Zertifikatsnummer am Ende des Befehls mit der Umgebungsvariable übereinstimmt.
• ob die aktuellen Anmeldeinformationen berechtigt sind, dieses Zertifikat zu verwenden.

Signaturanfrage fehlgeschlagen

Bitte überprüfen Sie:

• Netzwerkverbindung, Proxy- und Firewall-Einstellungen.
• ob Anmeldeinformationen und Zertifikatsnummer korrekt sind.
• ob die dedizierte Dienstadresse gemäß den Angaben des Servicepersonals konfiguriert ist.

Wenn das Problem weiterhin besteht, bewahren Sie bitte die vollständige Fehlermeldung auf und wenden Sie sich an den technischen Support. Entfernen oder verdecken Sie vor dem Übermitteln der Fehlermeldung bitte alle Anmeldeinformationen.

Zeitstempel fehlgeschlagen

Bitte stellen Sie sicher, dass das aktuelle Netzwerk die Zeitstempeladresse im Befehl erreichen kann. Wenn es Ihr Geschäftsbetrieb erlaubt, können Sie -tsa und die darauf folgende Adresse vorübergehend entfernen und den Signaturvorgang erneut ausführen, um das Problem einzugrenzen.

Sicherheitshinweise

• Speichern Sie den echten Access Secret nicht in Quellcode, Dokumentation, gemeinsam genutzten Skripten oder Images.
• Geben Sie keine Befehlszeilen, Terminalverläufe oder Pipeline-Protokolle weiter, die Anmeldeinformationen enthalten.
• In automatisierten Umgebungen sollten Anmeldeinformationen über geschützte Schlüsselvariablen injiziert werden.
• Laden Sie Werkzeuge ausschließlich aus vertrauenswürdigen Veröffentlichungskanälen herunter und überprüfen Sie vor der Verwendung die Dateiintegrität.
• Es wird empfohlen, die ursprüngliche unsignierte JAR-Datei aufzubewahren.