Client-Tools

sslTrus bietet einen Befehlszeilen-Client und einen Desktop-Client an, um eine Verbindung zum Remote-Code-Signaturdienst herzustellen und Dateisignaturen durchzuführen.

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

SignTool CLI

SignTool CLI ist der von sslTrus bereitgestellte Remote-Code-Signatur-Befehlszeilenclient. Der ausführbare Dateiname nach der Installation lautet signtool.

Es bietet hauptsächlich die folgenden Funktionen:

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

KSP und CSP gehören zur Windows-Provider-Integration; für die genaue Verwendung siehe Windows Provider.

Client herunterladen

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

sslTrus-Client-Veröffentlichungsseite

Die Veröffentlichungsseite bietet die neuesten Client-Installationspakete für alle Plattformen. Automatisierte Szenarien können die aktuellste Versionsinformationen auch über den Versionsindex latest.json abfragen.

macOS-Benutzer können den Client auch direkt über Homebrew installieren, siehe unten macOS Homebrew.

Client-Informationen anzeigen

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

signtool --help

---

Befehlshilfe anzeigen.

Aktuelle Client-Version anzeigen:

---

Übersetzung ins Deutsche:

Hilfe zum Befehl anzeigen.

Die aktuelle Client-Version anzeigen:

signtool --version

Die Versionsinformationen umfassen die Client-Version, die Build-Revision, die Laufzeitplattform und den Build-Zeitpunkt.

Zugangsdaten

Vor der Nutzung des Remote-Code-Signierungsdienstes müssen folgende Daten vorbereitet werden:

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

Der Access Key und das Access Secret dienen dem Zugriff auf den Remote-Code-Signierungsdienst, während der Zertifikatscode das tatsächlich für die Signierung verwendete Code-Signaturzertifikat spezifiziert.

SignTool CLI kann die Zugangsdaten über Befehlszeilenparameter bereitstellen oder über Umgebungsvariablen auslesen:

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

Es wird empfohlen, Access Secret vorzugsweise über Umgebungsvariablen, CI/CD-Secrets oder andere sichere Methoden der Anmeldeinformationsverwaltung bereitzustellen.

Access Secret darf nicht:

• in ein Git-Repository eingecheckt werden.
• in öffentliche Skripte geschrieben werden.
• in Build-Logs ausgegeben werden.
• an nicht vertrauenswürdige Drittsysteme gesendet werden.

Adresse des Remote-Dienstes

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

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

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

signtool quota und signtool update unterstützen ebenfalls --address nicsrs.

Dateisignatur

Mit signtool sign können Sie direkt eine Remote-Codesignatur für lokale Dateien durchführen.

Der grundlegendste Signaturbefehl:

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

Wenn bereits festgelegt ist:

ACCESS_KEY
ACCESS_SECRET

SignTool CLI liest automatisch die entsprechenden Zugangsdaten ein.

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

Ausgabedatei festlegen

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 Sie die Originaldatei direkt ändern möchten, 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 einer automatisierten Build-Umgebung sollte bestätigt werden, ob nachfolgende Schritte die Originaldatei oder die signierte Datei benötigen.

Programmbescheinigung angeben

Die Programmbescheinigung 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

Gleichzeitige Aktivierung von SHA-1 und SHA-2:

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

SHA-1 wird hauptsächlich für die Kompatibilität mit Altsystemen verwendet; für neue Projekte sollte in der Regel SHA-2 bevorzugt werden.

Zeitstempel

Bei der Codesignatur wird empfohlen, zusätzlich einen vertrauenswürdigen Zeitstempel hinzuzufügen.

Das SignTool-CLI konfiguriert standardmäßig automatisch einen Zeitstempeldienst für die Signatur; der Zeitstempelserver kann auch über Parameter angegeben werden:

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

Angabe des RFC-3161-Zeitstempelservers:

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=

Informationen zu Timestamp-Protokollen, Serveradressen und Auswahlempfehlungen finden Sie in den Referenzmaterialien.

Signaturkontingent abfragen

Verwendung:

signtool quota

Sie können das Kontingent für Codesignatur-Zertifikate abfragen, die mit dem aktuellen Zugriffsnachweis sichtbar sind.

Die Ausgabe umfasst:

• Zertifikatsnummer.
• Zertifikatsinformationen.
• Verbleibende Signaturanforderungen.
• Gesamtzahl der Signaturanforderungen.

Für die Ausgabe im JSON-Format:

signtool quota --json

Sie können auch die Kurzform verwenden:

signtool quota -j

Die genaue Berechnungsweise der Signaturanforderungen kann je nach Aufrufmethode von CLI, KSP, Jarsigner oder Build-Tools variieren. Detaillierte Regeln finden Sie in der Erläuterung zur Berechnung der Signaturanforderungen.

Client aktualisieren

Mit dem SignTool-CLI können Sie die neueste Version für die aktuelle Plattform abfragen und installieren:

signtool update

Während des Updates werden die Größe und SHA-256 der heruntergeladenen Datei überprüft, um die Integrität der Client-Datei sicherzustellen.

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

macOS Homebrew

macOS-Benutzer können das SignTool CLI oder den Desktop-Client über das offizielle Homebrew Tap von sslTrus installieren.

Öffentliches Repository: ssltrus-official/homebrew-tap

Homebrew Tap installieren

Führen Sie Folgendes aus:

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

Nach Abschluss kann der entsprechende Client installiert werden.

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

Bestätigen Sie, ob der Client ordnungsgemäß installiert ist.

Der Paketname in Homebrew lautet:

code-sign-cli

Der tatsächlich installierte Name des Befehlszeilenprogramms lautet:

signtool

Installation des Desktop-Clients

Installieren Sie den sslTrus Code-Signing-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, empfiehlt es sich, das Upgrade mit Homebrew durchzuführen.

Aktualisieren Sie zuerst die Homebrew-Paketinformationen:

brew update

Upgrade des SignTool-CLI:

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

Upgrade des Desktop-Clients:

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

So bleibt die lokale Installation mit den Homebrew-Paketmetadaten konsistent.

Windows Provider

Wenn Ihr Szenario nicht direkt den SignTool-CLI aufruft, sondern Microsoft SignTool, Visual Studio, MSBuild, Advanced Installer oder andere Windows-Software den privaten Schlüssel für die Remote-Code-Signierung direkt verwenden soll, verwenden Sie den Windows Provider.

sslTrus bietet:

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

Weitere Informationen finden Sie unter Windows Provider.

CI/CD-Autosignierung

Wenn Sie die Signierung im Rahmen von Continuous Integration oder automatischen Build-Prozessen durchführen müssen, ist eine manuelle Installation und Aufruf des SignTool-CLI nicht zwingend erforderlich.

GitHub Actions kann beispielsweise 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 in Build-Prozessen direkt die Remote-Codesignierung für angegebene Dateien durchführen.

Öffentliches Repository: ssltrus-official/code-sign-action

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

So wählen Sie aus

Sie können je nach tatsächlichem Nutzungsszenario einen geeigneten Client oder eine Integrationsmethode wählen:

Szenario	Empfohlene Methode
Dateien manuell im Terminal signieren	SignTool CLI
Stapelweises Signieren über Skripte	SignTool CLI
Codesignierungs-Kontingent abfragen	SignTool CLI
macOS-Installation und -Update der CLI	Homebrew
macOS mit Desktop-Client	Homebrew
Microsoft SignTool und andere Windows-Software rufen direkt Remote-Private-Key auf	KSP
Traditionelle CryptoAPI-Software	CSP
GitHub Actions automatische Signierung	GitHub Actions
Eigenentwicklung eines Signierungsclients	Remote-Codesignierungs-API

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