sslTrusJarsigner – Benutzerhandbuch

Vorbereitung

Bitte halten Sie vor der Verwendung Folgendes bereit:

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

Bitte ersetzen Sie <version>, die Zugangsdaten, die Zertifikatsnummer und die 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, vor der Verwendung die Integrität der JAR-Datei anhand der Prüfdatei zu überprüfen.

Laufzeitumgebung prü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"

Falls das Servicepersonal eine dedizierte Service-Adresse bereitgestellt hat, muss außerdem Folgendes eingerichtet werden:

Linux und macOS:

export SSLTRUS_JARSIGNER_URL="YOUR_SERVICE_URL"

Windows PowerShell:

$env:SSLTRUS_JARSIGNER_URL = "YOUR_SERVICE_URL"

Wenn keine dedizierte Dienstadresse bereitgestellt wird, setzen Sie diese Variable bitte nicht.

Signatur

Das folgende Beispiel signiert app-unsigned.jar und speichert es als app-signed.jar. 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 zuerst 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 eine neue Datei zu erzeugen und das Ü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) als enveloped Signatur zu erzeugen. Der private Schlüssel verbleibt weiterhin ausschließlich im Remote-Signaturdienst; das Tool erzeugt 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 generierte Signatur verwendet den XMLDSig-Standard-Namespace http://www.w3.org/2000/09/xmldsig#; der Signature-Knoten wird als letztes Kindelement des Wurzelknotens in die Ausgabedatei geschrieben. Das aktuelle Signaturprofil ist wie folgt festgelegt:

Element	Fester Wert
Signaturtyp	Enveloped Signature
Signaturumfang	Gesamtes XML-Dokument, Reference URI=""
Reference Transform	Enveloped Signature Transform
Kanonisierung	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 ein 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 die Blattzertifikate, um das XML-Volumen zu reduzieren und die Konsistenz mit gängigen TIMS/1E-Dateien zu wahren. Wenn der Empfänger verlangt, dass die Zwischenzertifikatskette im XML enthalten ist, fügen Sie bitte --full-chain am Ende des Befehls 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 lehnt doppelte Signaturen ab, um Dateien zu vermeiden, deren 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-Entitäten und externer DTDs und akzeptiert daher kein XML, das auf die Expansion externer Entitäten angewiesen ist.
• Ändern Sie nach der Signatur nicht mehr Struktur, Text, Attribute oder Namespaces des XML; jede solche Ä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 Signatur 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 das 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öchten:

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

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

Hinweis: com.racent.codesign.SSLTrusProvider kann nicht geladen werden

Bitte überprüfen Sie:

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

Hinweis: Zertifikat oder Alias nicht gefunden

Bitte überprüfen Sie:

• Ob die Zertifikatsnummer korrekt ist.
• Ob die Zertifikatsnummer am Ende des Befehls mit der Umgebungsvariable übereinstimmt.
• Ob die aktuellen Anmeldeinformationen zur Nutzung dieses Zertifikats berechtigt sind.

Signaturanforderung 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 Anmeldeinformationen, bevor Sie die Fehlermeldung übermitteln.

Zeitstempel fehlgeschlagen

Bitte stellen Sie sicher, dass das aktuelle Netzwerk die Zeitstempeladresse im Befehl erreichen kann. Wenn es geschäftlich zulässig ist, können Sie -tsa und die darauf folgende Adresse vorübergehend entfernen und die Signatur 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 Tools aus vertrauenswürdigen Veröffentlichungskanälen herunter und überprüfen Sie die Dateiintegrität vor der Verwendung.
• Es wird empfohlen, die unsignierte Original-JAR-Datei aufzubewahren.