Client-Tools

sslTrus bietet einen Kommandozeilen-Client und einen Desktop-Client, um eine Verbindung zum Remote-Codesignaturdienst herzustellen und Dateien zu signieren.

Dabei eignet sich das SignTool CLI für Kommandozeilen-, Skript- und Automatisierungsszenarien; macOS-Benutzer können das SignTool CLI oder den Desktop-Client auch über Homebrew installieren und aktualisieren.

SignTool CLI

Das SignTool CLI ist der von sslTrus bereitgestellte Remote-Codesignatur-Kommandozeilenclient. Der Name der ausführbaren Datei nach der Installation lautet signtool.

Es bietet hauptsächlich die folgenden Funktionen:

Funktion	Befehl	Beschreibung
Dateisignatur	signtool sign	Führt eine Remote-Codesignatur für lokale Dateien aus
Signaturkontingent	signtool quota	Fragt das verbleibende und gesamte Signaturkontingent des Zertifikats ab
Client-Aktualisierung	signtool update	Fragt den neuesten Client für die aktuelle Plattform ab und installiert ihn
Windows KSP	signtool ksp	Installiert und verwaltet den Windows Key Storage Provider
Windows CSP	signtool csp	Installiert und verwaltet den Windows Cryptographic Service Provider

KSP und CSP gehören zur Integrationsmethode des Windows Provider. Die konkrete Verwendung finden Sie unter Windows Provider.

Client herunterladen

Das SignTool CLI kann von der sslTrus-Client-Veröffentlichungsseite heruntergeladen werden:

sslTrus-Client-Veröffentlichungsseite

Die Veröffentlichungsseite stellt die neuesten Client-Installationspakete für alle Plattformen bereit. In Automatisierungsszenarien können die aktuellen Versionsinformationen auch über den Versionsindex latest.json abgefragt werden.

macOS-Benutzer können die Installation auch direkt über Homebrew durchführen, siehe unten macOS Homebrew.

Client-Informationen anzeigen

Nach Abschluss der Installation können Sie Folgendes ausführen:

signtool --help

Zeigen Sie die Befehlshilfe an.

Zeigen Sie die aktuelle Client-Version an:

signtool --version

Versionsinformationen umfasst Client-Version, Build-Revision, Laufzeitplattform und Build-Zeit.

Zugangsdaten

Vor der Nutzung des Remote-Codesignaturdienstes benötigen Sie:

• Access Key
• Access Secret
• Zertifikatsnummer (Cert Code)

Dabei dienen Access Key und Access Secret dem Zugriff auf den Remote-Codesignaturdienst, die Zertifikatsnummer gibt das tatsächlich signierende Codesignaturzertifikat an.

Die SignTool CLI kann Zugangsdaten über Befehlsparameter oder über Umgebungsvariablen erhalten:

export ACCESS_KEY="your-access-key"
export ACCESS_SECRET="your-access-secret"

Es wird empfohlen, den Access Secret vorzugsweise über Umgebungsvariablen, CI/CD-Secrets oder andere sichere Verfahren zur Verwaltung von Zugangsdaten bereitzustellen.

Geben Sie den Access Secret nicht:

• in Git-Repositories ein.
• in öffentliche Skripte ein.
• in Build-Protokolle aus.
• an nicht vertrauenswürdige Drittsysteme weiter.

Adresse des Remote-Dienstes

Standardmäßig verwendet die SignTool CLI die Produktionsdienst-Adresse von sslTrus, ohne dass eine zusätzliche Konfiguration erforderlich ist.

Wenn Sie die NICSRS-Umgebung (www.nicsrs.com) verwenden, müssen Sie dem Befehl --address nicsrs hinzufügen:

signtool sign \
  --address nicsrs \
  --cert-code CERT_CODE \
  --file app.exe

signtool quota 和 signtool update 同样支持 --address nicsrs。

Dateisignatur

Mit signtool sign können Sie lokale Dateien direkt per Remote-Codesignatur signieren.

Der grundlegendste Signaturbefehl:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe

Falls bereits eingerichtet:

ACCESS_KEY
ACCESS_SECRET

SignTool CLI liest automatisch die entsprechenden Zugriffsdaten.

Standardmäßig wird die Signatur mit SHA-2 ausgeführt.

Ausgabedatei angeben

Standardmäßig überschreibt der Client die Originaldatei nicht direkt.

Über --out kann die Ausgabedatei nach der Signatur angegeben werden:

signtool sign \
  --cert-code CERT_CODE \
  --file app-unsigned.exe \
  --out app-signed.exe

Originaldatei überschreiben

Wenn die Originaldatei direkt geändert werden muss, können Sie Folgendes verwenden:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --override=true

Nach der Aktivierung von --override wird das Signaturergebnis direkt in die Eingabedatei zurückgeschrieben.

Bei der Verwendung in automatisierten Build-Umgebungen sollte bestätigt werden, ob die nachfolgenden Schritte die Originaldatei oder die signierte Datei benötigen.

Programmdescription angeben

Die Programmbeschreibung und URL können in die Authenticode-Signatur geschrieben werden:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --desc "Example Application" \
  --url "https://example.com"

SHA-1 und SHA-2

Standardmäßig ist SHA-2 aktiviert:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe

Nur SHA-1 verwenden:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --sha1=true \
  --sha2=false

Gleichzeitig SHA-1 und SHA-2 aktivieren:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --sha1=true \
  --sha2=true

SHA-1 wird hauptsächlich zur Kompatibilität mit Altsystemen verwendet; bei neuen Projekten sollte in der Regel SHA-2 bevorzugt werden.

Zeitstempel

Beim Codesignieren wird generell empfohlen, einen vertrauenswürdigen Zeitstempel hinzuzufügen.

Die SignTool-CLI konfiguriert standardmäßig automatisch einen Zeitstempeldienst für die Signatur. Der Zeitstempelserver kann auch per Parameter angegeben werden:

• --timestamp-rfc3161: RFC-3161-Zeitstempelserver für SHA-2-Signaturen.
• --timestamp: Authenticode-Zeitstempelserver für SHA-1-Signaturen.

RFC-3161-Zeitstempelserver angeben:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --timestamp-rfc3161=http://timestamp.acs.microsoft.com

Geben Sie den Authenticode-Zeitstempelserver an:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --timestamp=http://timestamp.sectigo.com

Wenn Sie den entsprechenden Zeitstempel deaktivieren möchten, können Sie den Parameterwert leer lassen:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --timestamp-rfc3161= \
  --timestamp=

有关时间戳协议、服务器地址及选择建议，请参阅 参考资料。

Signaturkontingent abfragen

Verwendung:

signtool quota

Es kann das Kontingent der Codesignatur-Zertifikate abgefragt werden, die für den aktuellen Zugriffsnachweis sichtbar sind.

Die Ausgabe umfasst:

• Zertifikatsnummer.
• Zertifikatsinformationen.
• Verbleibende Signaturanzahl.
• Gesamtsignaturanzahl.

Falls eine Ausgabe im JSON-Format benötigt wird:

signtool quota --json

Es kann auch eine Kurzschreibweise verwendet werden:

signtool quota -j

Die konkrete Berechnung der Signaturanzahl kann je nach Aufrufweise von CLI, KSP, Jarsigner oder Build-Tools unterschiedlich sein. Detaillierte Regeln finden Sie unter Erläuterung zur Berechnung der Signaturanzahl.

Client aktualisieren

Die SignTool-CLI unterstützt das Abfragen und Installieren der neuesten Version für die aktuelle Plattform:

signtool update

Während des Updates werden Dateigröße und SHA-256 der heruntergeladenen Datei überprüft, um die Integrität der Client-Dateien zu bestätigen.

Wenn die SignTool-CLI über Homebrew installiert wurde, wird empfohlen, die Version weiterhin über Homebrew zu verwalten, anstatt beide Update-Methoden gleichzeitig zu verwenden.

macOS Homebrew

macOS-Benutzer können die SignTool-CLI oder den Desktop-Client über den offiziellen sslTrus Homebrew Tap installieren.

Homebrew Tap installieren

Ausführen:

brew tap ssltrus-official/tap
brew trust ssltrus-official/tap

Nach Abschluss können Sie den entsprechenden Client installieren.

Installation der SignTool-CLI

Ausführen:

brew install ssltrus-official/tap/code-sign-cli

Nach Abschluss der Installation können Sie Folgendes ausführen:

signtool --version

Prüfen Sie, ob der Client ordnungsgemäß installiert ist.

Der Paketname in Homebrew lautet:

code-sign-cli

Der tatsächlich installierte Befehlszeilenprogrammname lautet:

signtool

Desktop-Client installieren

Installieren Sie den sslTrus-Codesigning-Desktop-Client:

brew install --cask ssltrus-official/tap/code-sign-gui

Der entsprechende Homebrew-Cask-Name lautet:

code-sign-gui

Client aktualisieren

Wenn der Client über Homebrew installiert wurde, wird empfohlen, das Upgrade über Homebrew durchzuführen.

Aktualisieren Sie zunächst die Homebrew-Paketinformationen:

brew update

Aktualisieren Sie die SignTool-CLI:

brew upgrade ssltrus-official/tap/code-sign-cli

Upgrade der Desktop-Anwendung:

brew upgrade --cask ssltrus-official/tap/code-sign-gui

Dadurch wird die lokale Installation mit den Homebrew-Paketmetadaten konsistent gehalten.

Windows Provider

Wenn Ihr Szenario nicht darin besteht, die SignTool-CLI direkt aufzurufen, sondern Microsoft SignTool, Visual Studio, MSBuild, Advanced Installer oder andere Windows-Software den privaten Schlüssel für das Remote-Codesigning direkt verwenden soll, sollten Sie den Windows Provider verwenden.

sslTrus bietet:

• KSP (Key Storage Provider): für Windows CNG.
• CSP (Cryptographic Service Provider): für die klassische Windows CryptoAPI.

Siehe Windows Provider.

Automatisches Signieren in CI/CD

Wenn das Signieren im Rahmen der kontinuierlichen Integration oder des automatisierten Build-Prozesses erfolgen soll, ist es nicht zwingend erforderlich, die SignTool-CLI manuell zu installieren und aufzurufen.

Beispielsweise kann GitHub Actions direkt die sslTrus Code Sign Action verwenden:

- name: Sign files
  uses: ssltrus-official/code-sign-action@v1
  with:
    access-key: ${{ secrets.SSLTRUS_ACCESS_KEY }}
    access-secret: ${{ secrets.SSLTRUS_ACCESS_SECRET }}
    cert-code: ${{ secrets.SSLTRUS_CERT_CODE }}
    files: build/app.exe

GitHub Action unterstützt Linux-, macOS- und Windows-Runner und kann im Build-Prozess direkt ein Remote-Codesigning für angegebene Dateien durchführen.

Die vollständige Konfiguration finden Sie unter CI/CD und Build-Tools.

So wählen Sie aus

Sie können den passenden Client oder die passende Integrationsmethode basierend auf der tatsächlichen Nutzung auswählen:

Szenario	Empfohlene Methode
Dateien manuell im Terminal signieren	SignTool CLI
Signierung per Skript stapelweise aufrufen	SignTool CLI
Codesigning-Kontingent abfragen	SignTool CLI
CLI unter macOS installieren und aktualisieren	Homebrew
Desktop-Client unter macOS verwenden	Homebrew
Windows-Software wie Microsoft SignTool ruft Remote-Privatschlüssel direkt auf	KSP
Herkömmliche CryptoAPI-Software	CSP
Automatische Signierung in GitHub Actions	GitHub Actions
Signierclient selbst entwickeln	Remote-Codesigning-API

Wenn Ihre Anwendung bereits Windows KSP, CSP oder andere Standard-Provider unterstützt, sollten Sie in der Regel die entsprechende Standard-Integrationsmethode bevorzugen. Wenn Sie den Signierprozess direkt steuern müssen, können Sie die SignTool CLI oder die Remote-Codesigning-API verwenden.