sslTrusJarsigner – Nutzungshandbuch

Vorbereitung

Bitte stellen Sie vor der Verwendung Folgendes bereit:

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

Ersetzen Sie <version>, Anmeldedaten, 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 prüfen

Führen Sie den folgenden Befehl aus, um sicherzustellen, 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

Konfiguration der Anmeldedaten

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 der Service-Mitarbeiter eine spezielle 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 kein dedizierter Dienstadressen-Endpunkt bereitgestellt wird, setzen Sie diese Variable bitte nicht.

Signatur

Das folgende Beispiel signiert app-unsigned.jar und speichert es als app-signed.jar. Bitte verwenden Sie die festen Parameter genau 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 bestätigen Sie zunächst, dass JAVA_HOME auf eine 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 zum Erzeugen neuer Dateien zu verwenden, um das ursprüngliche JAR nicht zu überschreiben.
• Wenn kein Zeitstempel benötigt wird, können -tsa und die darauffolgende Adresse entfernt werden.

XML-Signatur (XMLDSig)

TIMS/1E-XML verwendet den Befehl sign-xml, um eine XML Digital Signature (XMLDSig) enveloped Signatur zu erzeugen. Der private Schlüssel verbleibt weiterhin ausschließlich im Remote-Signaturdienst; das Tool erzeugt lokal die für XMLDSig erforderliche Prüfsumme und Signaturstruktur, während der Remote-Dienst die RSA-Signierung abschließt.

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-Standard-Namespace http://www.w3.org/2000/09/xmldsig#, wobei die Knoten Signature als letztes untergeordnetes Element des Stammknotens in die Ausgabedatei geschrieben werden. 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 einschließlich Blattzertifikat

Der Aufrufer muss keine Digest-Berechnung selbst durchführen oder SignatureValue konstruieren. Das Tool verwendet das Blattzertifikat des Remote-Zertifikats, um KeyInfo/X509Data zu füllen, und schreibt das endgültige SignatureValue in die XML-Datei.

Einschließlich vollständiger Zertifikatskette

Standardmäßig enthält die Ausgabe nur das Blattzertifikat, um die XML-Größe zu reduzieren und mit gängigen TIMS/1E-Dateien konsistent zu bleiben. Falls der Empfänger verlangt, dass die XML-Datei die Zwischenzertifikatskette enthält, 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 noch den Zusammenfassungsalgorithmus oder den Signaturalgorithmus. Diese Option kann vor oder nach der Zertifikatsnummer platziert werden; wenn keine Zertifikatsnummer angegeben wird, wird SSLTRUS_JARSIGNER_CERT_CODE verwendet.

Eingabe- und Nutzungsbeschränkungen

• Die Eingabe muss ein wohlgeformtes XML mit einem Wurzelknoten sein.
• Die Eingabedatei darf noch keinen XMLDSig-Signature-Knoten enthalten; das Tool lehnt doppelte Signaturen ab, um Dateien mit unklarem Signaturbereich zu vermeiden.
• Derzeit wird nur die enveloped Signatur für das gesamte Dokument unterstützt; detached signatures, Signaturen nach Element-ID oder benutzerdefinierte XMLDSig-Profile werden nicht unterstützt.
• Das Tool deaktiviert das Laden von XML-Entitäten und externen DTDs, daher werden XML-Dateien, die auf die Expansion externer Entitäten angewiesen sind, nicht akzeptiert.
• Nach der Signierung darf die Struktur, der Text, die Attribute oder die Namespaces des XML nicht weiter geändert werden; jede solche Änderung führt zum Fehlschlag der XMLDSig-Validierung. Die Original-Eingabedatei sollte stets aufbewahrt und das Signaturergebnis in eine neue Ausgabedatei geschrieben werden.

Validierungsdatei erstellen

Nach der Signierung kann die für die Validierung erforderliche JKS-Datei erstellt 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 wird nur zur Verifizierung der Signatur verwendet und kann nicht für die Durchführung der Signierung eingesetzt werden.

Signatur verifizieren

Verwenden Sie das generierte verify.jks, um das signierte JAR zu verifizieren:

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 im aktuellen Terminal die folgenden Umgebungsvariablen gesetzt sind:

• SSLTRUS_JARSIGNER_ACCESS_KEY
• SSLTRUS_JARSIGNER_ACCESS_SECRET
• SSLTRUS_JARSIGNER_CERT_CODE

Nachdem die Umgebungsvariablen gesetzt wurden, müssen Sie den Signierbefehl im selben Terminalfenster ausführen.

Hinweis Ungültige Option: -providerPath

Sie verwenden derzeit JDK 8. Bitte verwenden Sie den JDK 8 Signierbefehl aus diesem Dokument.

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

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 ein vollständiges JDK verweist.

Hinweis, dass Zertifikat oder 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 Anmeldedaten zur Nutzung dieses Zertifikats berechtigt sind.

Signieranfrage fehlgeschlagen

Bitte überprüfen Sie:

• Netzwerkverbindung, Proxy- und Firewall-Einstellungen.
• Ob Anmeldedaten und Zertifikatsnummer korrekt sind.
• Ob die dedizierte Serviceadresse gemäß den Angaben des Servicepersonals konfiguriert ist.

Wenn das Problem weiterhin besteht, bewahren Sie die vollständige Fehlermeldung auf und kontaktieren Sie den technischen Support. Entfernen oder schwärzen Sie vor dem Senden der Fehlermeldung Ihre Anmeldedaten.

Zeitstempel fehlgeschlagen

Bitte stellen Sie sicher, dass das aktuelle Netzwerk die im Befehl angegebene Zeitstempeladresse erreichen kann. Falls es die geschäftlichen Anforderungen erlauben, können Sie vorübergehend -tsa und die darauf folgende Adresse entfernen und die Signierung erneut ausführen, um das Problem einzugrenzen.

Sicherheitshinweise

• Speichern Sie echte Access Secrets nicht in Quellcode, Dokumentation, freigegebenen Skripten oder Images.
• Teilen Sie keine Befehlszeilen, Terminalverläufe oder Pipeline-Logs, die Anmeldedaten enthalten, mit anderen.
• In automatisierten Umgebungen sollten Anmeldedaten über geschützte Schlüsselvariablen injiziert werden.
• Laden Sie Tools nur aus vertrauenswürdigen Veröffentlichungsquellen herunter und überprüfen Sie die Dateiintegrität vor der Verwendung.
• Es wird empfohlen, die unsignierten Original-JAR-Dateien aufzubewahren.