Java-Integration

sslTrus stellt einen sslTrusJarsigner Java-Provider bereit, der mit dem in JDK integrierten jarsigner-Tool verwendet werden kann, um Java-JAR-Dateien über den Remote-Codesignaturdienst zu signieren.

Während des Signaturvorgangs bleibt der private Codesignaturschlüssel stets in der Cloud-HSM gespeichert. Lokal werden die zu signierenden Daten und die Signaturstruktur erzeugt; die Signatur mit dem privaten Schlüssel erfolgt über den sslTrusJarsigner-Provider, der den Remotedienst aufruft.

Neben der JAR-Signatur bietet sslTrusJarsigner auch XMLDSig-Signaturfunktionen, die für XML-Signaturszenarien verwendet werden können.

Vorbereitung

Bitte bereiten Sie Folgendes vor:

• JDK 8 oder höher.
• sslTrusJarsigner-<version>.jar.
• Access Key.
• Access Secret.
• Zertifikatsnummer (Cert Code).
• Die zu signierende JAR-Datei oder XML-Datei.

Die in diesem Artikel verwendeten <version>, Zugangsdaten, Zertifikatsnummern und Dateipfade müssen durch tatsächliche Werte ersetzt werden.

sslTrusJarsigner herunterladen

Laden Sie das neueste Release-Paket von der sslTrusJarsigner-Veröffentlichungsseite herunter und entpacken Sie es.

Das Release-Paket enthält:

sslTrusJarsigner-<version>.jar
SHA-256 校验文件

Es wird empfohlen, vor der Verwendung die Integrität der Datei anhand des SHA-256-Hashwerts zu überprüfen, um sslTrusJarsigner-<version>.jar zu verifizieren.

Laufzeitumgebung überprüfen

Stellen Sie zunächst sicher, dass das in Java und JDK enthaltene jarsigner ordnungsgemäß funktioniert:

java -version
jarsigner -help

Überprüfen Sie die sslTrusJarsigner-Version:

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

Hilfe anzeigen:

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

Falls der Befehl jarsigner nicht vorhanden ist, stellen Sie sicher, dass das vollständige JDK installiert ist und nicht nur eine Laufzeitumgebung, die ausschließlich die Java Runtime enthält.

Zugangsdaten konfigurieren

sslTrusJarsigner liest die Zugangsdaten und die Zertifikatsnummer des Remote-Codesignaturdienstes über Umgebungsvariablen.

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 Serviceadresse bereitgestellt hat, muss außerdem SSLTRUS_JARSIGNER_URL festgelegt werden.

Linux und macOS:

export SSLTRUS_JARSIGNER_URL="YOUR_SERVICE_URL"

Windows PowerShell:

$env:SSLTRUS_JARSIGNER_URL = "YOUR_SERVICE_URL"

Wenn keine dedizierte Service-Adresse bereitgestellt wird, muss diese Variable nicht gesetzt werden.

Der Access Secret ist eine sensible Zugangsberechtigung und sollte nicht in den Quellcode, öffentliche Konfigurationsdateien oder Build-Protokolle geschrieben werden. In automatisierten Umgebungen wird empfohlen, ihn über CI/CD-Secrets oder andere Verwaltungsmechanismen für Zugangsdaten zu injizieren.

JAR-Signatur

sslTrusJarsigner wird über den Java Security Provider-Mechanismus in das Standard-Tool jarsigner integriert.

Das folgende Beispiel:

app-unsigned.jar

Signierte Ausgabe:

app-signed.jar

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

Die Art und Weise, wie JDK 8 den Provider lädt, unterscheidet sich von JDK 9 und höheren Versionen.

Zunächst bestätigen:

JAVA_HOME

Zeigt auf das vollständige JDK-8-Installationsverzeichnis.

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"

Bei der Verwendung ist Folgendes zu beachten:

• Die Zertifikatsnummer am Ende des Befehls muss mit SSLTRUS_JARSIGNER_CERT_CODE übereinstimmen.
• Es wird empfohlen, -signedjar zur Ausgabe in eine neue Datei zu verwenden, um ein Überschreiben der ursprünglichen JAR-Datei zu vermeiden.
• Das Beispiel verwendet SHA256withRSA, um die Codesignatur abzuschließen.
• Wenn kein Zeitstempel benötigt wird, können Sie -tsa und die nachfolgende Zeitstempeladresse löschen.

Zeitstempel

Es wird empfohlen, für offiziell veröffentlichte JAR-Signaturen einen vertrauenswürdigen Zeitstempel hinzuzufügen.

Im Beispiel wird Folgendes verwendet:

http://timestamp.sectigo.com

Entsprechende Parameter:

-tsa http://timestamp.sectigo.com

Der Zeitstempel dient als Nachweis für den Zeitpunkt der Signatur; die ursprüngliche JAR-Datei wird dabei nicht auf den Zeitstempelserver hochgeladen.

Falls ein anderer Zeitstempeldienst verwendet werden soll, ersetzen Sie die Adresse nach -tsa durch die TSA-Adresse, die der tatsächlichen Signaturrichtlinie entspricht.

Zu verschiedenen Zeitstempeldiensten und der Auswahl für Produktionsumgebungen siehe Referenzmaterial.

XML-Signatur

sslTrusJarsigner bietet außerdem die Möglichkeit digitaler XML-Signaturen.

XML-Dateien können mit dem Befehl sign-xml eine XMLDSig Enveloped Signature erzeugen.

Während des Signiervorgangs werden die für XMLDSig erforderlichen Digest- und Signaturstrukturen lokal erzeugt; die eigentliche Signatur mit dem privaten RSA-Schlüssel erfolgt durch den Remote-Codesignaturdienst.

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"

Die Standardausgabe von KeyInfo enthält nur das Blattzertifikat. Wenn der Empfänger verlangt, dass die XML die vollständige Zertifikatskette enthält, kann am Ende des Befehls der Parameter --full-chain hinzugefügt werden.

Nach Abschluss der Ausführung:

input.xml

für die ursprüngliche XML-Datei,

signed.xml

Für Ausgabedateien mit XML-Digital Signatur.

Der private Schlüssel für die Codesignatur wird nicht in die XML-Datei geschrieben und auch nicht auf dem lokalen Computer gespeichert.

Prüfdatei generieren

Nach Abschluss der Signatur kann eine JKS-Datei zur Überprüfung der Signatur generiert 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"

Erzeugen:

verify.jks

Diese Datei wird nur zur Signaturprüfung verwendet und kann nicht für die Code-Signierung eingesetzt werden.

Der private Schlüssel für die Code-Signierung verbleibt weiterhin im entfernten HSM und wird nicht in verify.jks geschrieben.

JAR-Signatur überprüfen

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

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

Wenn Sie nur die bereits im JAR enthaltenen Signaturinformationen anzeigen möchten, können Sie Folgendes ausführen:

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

Die Überprüfung der Signatur prüft nur vorhandene Signaturen und ruft nicht erneut den entfernten privaten Schlüssel zur Signierung auf.

Anzahl der Signaturen

Die Anzahl der Signaturen bei Jarsigner wird anhand der tatsächlich erfolgreich abgeschlossenen entfernten Signierungsvorgänge berechnet.

In der Regel gilt:

Vorgang	Anzahl der Signaturen
Ein JAR einmal erfolgreich signieren	1 Mal
3 JARs getrennt signieren	3 Mal
Dasselbe JAR erneut signieren	zusätzlich 1 Mal
jarsigner -verify Signatur überprüfen	0 Mal
verify.jks generieren	0 Mal

Daher hängt die Anzahl der Signaturen hauptsächlich davon ab, wie viele erfolgreiche Signierungsvorgänge tatsächlich durchgeführt wurden, und nicht von der Anzahl der Quellcodedateien des Java-Projekts.

Detaillierte Regeln finden Sie in den Referenzmaterialien.

Häufig gestellte Fragen

Fehlender Access Key, Access Secret oder Zertifikatsnummer

Stellen Sie sicher, dass das aktuelle Terminal bereits eingerichtet ist:

SSLTRUS_JARSIGNER_ACCESS_KEY
SSLTRUS_JARSIGNER_ACCESS_SECRET
SSLTRUS_JARSIGNER_CERT_CODE

Nachdem die Umgebungsvariablen gesetzt wurden, müssen Sie den Signaturbefehl in derselben Terminalsitzung ausführen.

Invalid option: -providerPath

Wenn Folgendes angezeigt wird:

Invalid option: -providerPath

In der Regel bedeutet dies, dass JDK 8 verwendet wird.

JDK 8 verwendet nicht den Parameter -providerPath aus den Beispielen für JDK 9 und höher. Verwenden Sie stattdessen die in diesem Dokument bereitgestellten Befehle für JDK 8.

SSLTrusProvider kann nicht geladen werden

Wenn die Meldung „kann nicht geladen werden“ angezeigt wird:

com.racent.codesign.SSLTrusProvider

Bitte überprüfen Sie:

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

Zertifikat oder Alias nicht gefunden

Bitte überprüfen Sie:

• Ob die Zertifikatsnummer korrekt ist.
• Ob die am Ende des Befehls angegebene Zertifikatsnummer mit SSLTRUS_JARSIGNER_CERT_CODE übereinstimmt.
• Ob der aktuelle Access Key und das Access Secret über die Nutzungsberechtigung für dieses Zertifikat verfügen.

Remote-Signaturanforderung fehlgeschlagen

Bitte überprüfen Sie:

• Ob das aktuelle Netzwerk auf den Remote-Codesignaturdienst zugreifen kann.
• Ob Proxy, Firewall und DNS-Konfiguration ordnungsgemäß sind.
• Ob Access Key und Access Secret korrekt sind.
• Ob die Zertifikatsnummer korrekt ist.
• Wenn eine dedizierte Dienstadresse verwendet wird, ob SSLTRUS_JARSIGNER_URL gemäß den tatsächlich gelieferten Informationen konfiguriert ist.

Bei der Fehlerbehebung können vollständige Fehlermeldungen aufbewahrt werden. Bevor jedoch Protokolle oder Fehler-Screenshots übermittelt werden, sollten vertrauliche Zugangsdaten wie das Access Secret gelöscht oder maskiert werden.

Zeitstempelfehler

Stellen Sie sicher, dass das aktuelle Netzwerk auf den unter -tsa angegebenen Zeitstempelserver zugreifen kann.

Wenn es das Geschäft erlaubt, können Sie Folgendes vorübergehend entfernen:

-tsa <URL>

Führen Sie die Signatur erneut aus, um festzustellen, ob das Problem bei der Remote-Codesignatur oder beim Zeitstempel-Anforderungsschritt auftritt.

Sicherheitshinweise

Beim Java-Integrationsprozess ist Folgendes zu beachten:

• Access Secret sollte als sensible Anmeldeinformation gespeichert werden.
• Geben Sie Zugriffsanmeldeinformationen nicht in Git-Repositorys ein.
• Geben Sie das vollständige Access Secret nicht in Protokollen aus.
• verify.jks dient nur zur Verifizierung und enthält keinen privaten Schlüssel, der für die Remote-Signatur verwendet werden kann.
• Der lokale sslTrusJarsigner-Provider speichert keine privaten Schlüssel für die Codesignatur.
• Die Signierung mit dem privaten Schlüssel erfolgt stets durch den Remote-Codesignaturdienst.
• In automatisierten Umgebungen wird empfohlen, Zugriffsanmeldeinformationen über CI/CD Secret oder ein spezielles Credential-Management-System zu injizieren.

Verwandte Integrationsmethoden

Wenn keine Java-JAR- oder XML-Dateien signiert werden müssen, können je nach tatsächlichem Szenario andere Integrationsmethoden gewählt werden:

Szenario	Integrationsmethode
EXE-, DLL-, MSI- und andere Dateien direkt über die Befehlszeile signieren	Client-Tool
Microsoft SignTool, Visual Studio und andere Windows-Tools	Windows Provider
Automatisierte Builds mit GitHub Actions, Electron Builder usw.	CI/CD- und Build-Tools
Eigenentwicklung eines Remote-Signatur-Clients	API-Integration