Java-Integration

sslTrus bietet einen sslTrusJarsigner Java-Provider, der mit dem im JDK enthaltenen jarsigner-Tool zusammen verwendet werden kann, um Java-JAR-Dateien über einen Remote-Codesignaturdienst zu signieren.

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

Neben der JAR-Signatur bietet sslTrusJarsigner auch XMLDSig-Signaturfähigkeiten und kann für XML-Digitalsignaturszenarien verwendet werden.

Vorbereitung

Bereiten Sie vor der Verwendung 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 den Beispielen dieses Artikels 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 sslTrusJarsigner-<version>.jar anhand der SHA-256-Prüfsumme zu überprüfen.

Laufzeitumgebung prüfen

Stellen Sie zunächst sicher, dass Java und das im JDK enthaltene jarsigner ordnungsgemäß verwendet werden können:

java -version
jarsigner -help

Prüfen der sslTrusJarsigner-Version:

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

Hilfe anzeigen:

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

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

Zugangsdaten konfigurieren

sslTrusJarsigner liest die Zugangsdaten für den Remote-Codesignaturdienst und die Zertifikatsnummer ü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"

Wenn das Servicepersonal eine dedizierte Serviceadresse bereitgestellt hat, muss zusätzlich 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 Dienst-Adresse angegeben ist, muss diese Variable nicht gesetzt werden.

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

JAR-Signatur

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

Das folgende Beispiel führt Folgendes aus:

app-unsigned.jar

Signiert wird Folgendes ausgegeben:

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

JDK 8 lädt den Provider anders als JDK 9 und höhere Versionen.

Zuerst 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"

Hinweise zur Verwendung:

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

Zeitstempel

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

Im Beispiel wird 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 muss, ersetzen Sie die Adresse nach -tsa durch eine TSA-Adresse, die der tatsächlichen Signaturrichtlinie entspricht.

Informationen zu verschiedenen Zeitstempeldiensten und zur Auswahl in Produktionsumgebungen finden Sie unter Referenzmaterial.

XML-Signatur

sslTrusJarsigner bietet außerdem die Funktion zur digitalen XML-Signatur.

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

Während des Signaturvorgangs werden die für XMLDSig erforderlichen Digest- und Signaturstrukturen lokal generiert; die eigentliche RSA-Private-Key-Signatur erfolgt über 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 standardmäßige Ausgabe von KeyInfo enthält nur das Blattzertifikat. Wenn der Empfänger verlangt, dass die XML die vollständige Zertifikatskette enthält, können Sie am Ende des Befehls den Parameter --full-chain hinzufügen.

Nach Abschluss der Ausführung:

input.xml

Für die ursprüngliche XML-Datei:

signed.xml

Für Ausgabedateien, die eine XML-Digital-signatur enthalten.

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

Verifizierungsdatei 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"

Generieren:

verify.jks

Diese Datei wird nur zur Signaturprüfung verwendet und kann nicht für das Codesigning eingesetzt werden.

Der private Schlüssel für das Codesigning 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 vorhandenen Signaturinformationen in der JAR-Datei anzeigen möchten, können Sie Folgendes ausführen:

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

Die Signaturprüfung überprüft nur vorhandene Signaturen und ruft nicht erneut den Remote-Private-Key zur Signierung auf.

Anzahl der Signaturen

Die Anzahl der Signaturen von Jarsigner wird anhand der tatsächlich erfolgreich durchgeführten Remote-Signaturaktionen berechnet.

In der Regel gilt:

Vorgang	Anzahl der Signaturen
Einen JAR einmal erfolgreich signieren	1 Mal
3 JARs getrennt signieren	3 Mal
Denselben JAR erneut signieren	weitere 1 Mal
jarsigner -verify Signatur prüfen	0 Mal
Erzeugen verify.jks	0 Mal

Daher hängt die Anzahl der Signaturen hauptsächlich davon ab, wie viele erfolgreiche Signaturvorgä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 im aktuellen Terminal Folgendes gesetzt 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

Normalerweise bedeutet dies, dass aktuell 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 JDK-8-Befehle.

SSLTrusProvider kann nicht geladen werden

Wenn gemeldet wird, dass das Laden nicht möglich ist:

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.

Remotesignaturanfrage fehlgeschlagen

Bitte überprüfen Sie:

• Ob das aktuelle Netzwerk auf den Remotecodesignaturdienst zugreifen kann.
• Ob Proxy, Firewall und DNS-Konfiguration normal funktionieren.
• 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 die vollständigen Fehlerinformationen aufbewahrt werden. Bevor Sie jedoch Protokolle oder Fehler-Screenshots einreichen, sollten Sie das Access Secret und andere sensible Zugangsdaten entfernen oder unkenntlich machen.

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

Bei der Java-Integration sind folgende Punkte zu beachten:

• Access Secret sollte als vertrauliche Anmeldeinformation gespeichert werden.
• Übergeben Sie Zugangsdaten nicht an ein Git-Repository.
• Geben Sie das vollständige Access Secret nicht in Protokollen aus.
• verify.jks dient nur zur Validierung und enthält keinen privaten Schlüssel für die Remote-Signatur.
• Der lokale sslTrusJarsigner Provider speichert keinen privaten Schlüssel für die Codesignatur.
• Die Signatur mit dem privaten Schlüssel wird stets vom Remote-Codesignaturdienst durchgeführt.
• In automatisierten Umgebungen wird empfohlen, Zugangsdaten über CI/CD Secret oder ein dediziertes 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
Signieren von EXE-, DLL-, MSI- und anderen Dateien direkt über die Befehlszeile	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
Eigene Entwicklung eines Remote-Signatur-Clients	API-Integration