CSP – Gebrauchsanweisung

Überblick

Diese Anleitung dient dazu, sslTrus Cryptographic Service Provider (CSP) unter Windows zu konfigurieren und mithilfe des Microsoft-Tools signtool.exe aus dem Windows SDK die Codesignatur über ein Cloud-HSM durchzuführen.

Das signtool csp dieses Projekts ist für Installation, Konfiguration und Wartung des Providers zuständig; bei der eigentlichen Signatur wird das Windows-SDK-Tool signtool.exe verwendet. Es handelt sich nicht um dasselbe Programm.

sslTrus Cryptographic Service Provider ist ein klassischer CryptoAPI-CSP und eignet sich für Windows-Signaturabläufe, die über /csp und /kc eingebunden werden müssen. Der private Signaturschlüssel verbleibt stets im Cloud-HSM; lokal werden nur die CSP-DLL, das Signaturzertifikat und die durch Windows DPAPI geschützte Zugriffskonfiguration gespeichert.

Vorbereitung

• Windows x64-System.
• Ein als Administrator ausgeführtes Terminal für die Installation oder Deinstallation des Providers.
• Das signtool-CLI dieses Projekts, das das Unterkommando csp enthält.
• Das Windows SDK ist installiert, und Microsoft signtool.exe kann verwendet werden.
• Gültiger Access Key, Access Secret und Zertifikatsnummer (CERT_CODE).
• Netzwerkzugriff auf den Codesignaturdienst und den gewählten Zeitstempeldienst.

Bestätigen Sie, dass die beiden Tools jeweils verfügbar sind:

REM 本项目 CLI
signtool csp --help

REM Windows SDK 工具；必要时请使用其完整路径
signtool.exe sign /?

Wenn sich im aktuellen Verzeichnis oder im PATH zwei gleichnamige Programme befinden, stellen Sie sicher, dass Sie das tatsächliche Aufrufziel über den vollständigen Pfad oder where bestätigen.

Schnellstart

Führen Sie im Administrator-Terminal nacheinander Folgendes aus:

signtool csp install
signtool csp add
signtool csp list

csp add fordert interaktiv zur Eingabe auf:

Please enter the access key: your-access-key
Please enter the access secret: your-access-secret
Please enter the certificate code: CERT_CODE

Nach erfolgreicher Konfiguration signieren Sie mit Microsoft signtool.exe aus dem Windows SDK:

signtool.exe sign /v ^
  /csp "sslTrus Cryptographic Service Provider" ^
  /kc CERT_CODE ^
  /f "C:\ProgramData\sslTrusKSP\CERT_CODE.crt" ^
  /fd SHA256 ^
  /tr http://timestamp.acs.microsoft.com ^
  /td SHA256 ^
  ".\app.exe"

Ersetzen Sie im Beispiel CERT_CODE und app.exe durch die tatsächliche Zertifikatsnummer und die zu signierende Datei.

Provider installieren

Ausführen:

signtool csp install

Der Befehl führt Folgendes aus:

• Schreibt sslTrusCSP.dll in %ProgramData%\sslTrusKSP und kopiert es in das Systemverzeichnis.
• Registriert sslTrus Cryptographic Service Provider (Providertyp PROV_RSA_AES).
• Installiert die zugehörige KSP-DLL und registriert sslTrus Key Storage Provider als CNG-Provider-Alias mit demselben Namen wie der CSP.
• Erstellt oder speichert %ProgramData%\sslTrusKSP\config.dat; die Datei wird mit der lokalen Windows-DPAPI verschlüsselt.

Die Installation ändert die systemweite Provider-Registrierung und muss in der Regel in einem Administratorterminal ausgeführt werden. Wenn die CSP-DLL-Version im Systemverzeichnis mit der eingebetteten Version übereinstimmt, überspringt die CLI das Kopieren der CSP-DLL, führt den Provider-Registrierungsvorgang jedoch weiterhin aus.

Zertifikatskonfiguration hinzufügen

Ausführen:

signtool csp add

Bei Bedarf NICSRS-Dienstadresse verwenden:

signtool csp add --address nicsrs

--address ist kein URL-Durchreichungsparameter. Der aktuelle nicsrs verwendet den NICSRS-Dienst; ein leerer Wert, racent oder andere Werte verwenden den Standarddienst.

Beim Hinzufügen ruft die CLI das Zertifikat vom Remote-Dienst ab und schreibt:

%ProgramData%\sslTrusKSP\CERT_CODE.crt

Schreiben Sie gleichzeitig die Dienstadresse, die Zugangsdaten, die Zertifikatsnummer und den Zertifikatspfad in die verschlüsselte Konfigurationsdatei. CERT_CODE ist sowohl die Remote-Zertifikatskennung als auch der Wert von /kc im späteren Microsoft signtool.exe.

Wenn eine bereits vorhandene Zertifikatsnummer hinzugefügt wird, fragt die CLI, ob sie überschrieben werden soll: Geben Sie y ein, um die alte Konfiguration zu ersetzen; durch direktes Drücken der Eingabetaste oder die Eingabe eines anderen Werts bleibt die ursprüngliche Konfiguration unverändert.

Konfiguration anzeigen und löschen

Aktuelle Konfiguration anzeigen:

signtool csp list

Die Ausgabe enthält die Zertifikatsnummer, den Diensttyp, den Access Key und das maskierte Access Secret. Bitte laden Sie Befehlsausgaben, Konfigurationsdateien oder Protokolle nicht an öffentliche Orte hoch.

Löschen einer bestimmten Konfiguration:

signtool csp del

Geben Sie die Zertifikatsnummer wie aufgefordert ein. Dieser Vorgang löscht nur den entsprechenden Eintrag in der Verschlüsselungskonfiguration, nicht die gleichnamige Zertifikatsdatei .crt; bereinigen Sie diese Datei bitte manuell, wenn sie nicht mehr benötigt wird.

Verwenden von Microsoft signtool.exe-Signaturen

SHA-256-Signatur

signtool.exe sign /v ^
  /csp "sslTrus Cryptographic Service Provider" ^
  /kc CERT_CODE ^
  /f "C:\ProgramData\sslTrusKSP\CERT_CODE.crt" ^
  /fd SHA256 ^
  /tr http://timestamp.acs.microsoft.com ^
  /td SHA256 ^
  ".\app.exe"

Parameterbeschreibung:

Parameter	Beschreibung
/csp "sslTrus Cryptographic Service Provider"	Gibt den CSP-Provider an.
/kc CERT_CODE	Gibt den Schlüsselcontainer für die entsprechende Zertifikatsnummer an.
/f <证书路径>	Gibt die mit csp add heruntergeladene Zertifikatsdatei an.
/fd SHA256	Gibt den Algorithmus für die Dateizusammenfassung an.
/tr <URL>	Gibt den RFC 3161-Zeitstempeldienst an.
/td SHA256	Gibt den Algorithmus für die Zeitstempelzusammenfassung an.

Derzeit unterstützt CSP die Datei-Digest-Algorithmen SHA1, SHA256, SHA384 und SHA512; bei neuen Signaturen wird in der Regel SHA-256 oder eine höhere Version empfohlen. Die Adresse des Zeitstempels sollte anhand Ihrer Zertifikatsrichtlinie und der Kompatibilität der Zielplattform festgelegt werden.

SHA-1-Signatur anhängen

Wenn tatsächlich Anforderungen an die Kompatibilität mit Altsystemen bestehen, kann SHA-1 an die vorhandene Signatur angehängt werden:

signtool.exe sign /v ^
  /csp "sslTrus Cryptographic Service Provider" ^
  /kc CERT_CODE ^
  /f "C:\ProgramData\sslTrusKSP\CERT_CODE.crt" ^
  /fd SHA1 ^
  /tr http://timestamp.acs.microsoft.com ^
  /td SHA256 ^
  /as ^
  ".\app.exe"

/as bedeutet, die Signatur anzuhängen und eine bestehende Signatur nicht zu überschreiben. Ob SHA-1 erforderlich ist, sollte sich nach dem Zielsystem und der Zertifikatsrichtlinie richten. Es sollte nicht als Standard für neue Projekte gewählt werden.

Signatur überprüfen

Nach dem Signieren kann die Überprüfung mit Microsoft signtool.exe erfolgen:

signtool.exe verify /pa /v ".\app.exe"

Falls alle Signaturen überprüft werden sollen, können Sie die entsprechenden Überprüfungsoptionen gemäß der Version und den Parameterhinweisen des Windows SDK signtool.exe auswählen.

Provider deinstallieren

Führen Sie im Administrator-Terminal Folgendes aus:

signtool csp uninstall

Dieser Befehl meldet den CSP sowie den gleichnamigen CNG-Provider-Alias des CSP ab und löscht die ProgramData- und Systemverzeichnis-Kopien der CSP-DLL. Er löscht nicht das gesamte Verzeichnis %ProgramData%\sslTrusKSP und entfernt auch nicht automatisch die Registrierung und DLL des zugehörigen sslTrus Key Storage Provider. Falls dieser KSP nur vom CSP-Installationsprozess verwendet wird, bereinigen Sie ihn bitte unter Berücksichtigung des tatsächlichen Bereitstellungsstatus sorgfältig.

Wenn nach der Deinstallation lokale vertrauliche Daten entfernt werden sollen, löschen Sie bitte manuell die Konfiguration, Zertifikate und Protokolle in %ProgramData%\sslTrusKSP, nachdem Sie bestätigt haben, dass sie nicht mehr vom KSP oder anderen Signaturprozessen verwendet werden.

Häufig gestellte Fragen

Symptom	Empfehlung
cryptographic service provider is only supported on windows	Führen Sie den CSP-Verwaltungsbefehl unter Windows aus.
Bei der Installation werden Berechtigungs- oder Schreibfehler im Systemverzeichnis gemeldet	Verwenden Sie ein Administrator-Terminal und führen Sie signtool csp install aus.
no csp configuration	Führen Sie zuerst signtool csp install und anschließend signtool csp add aus.
no such certificate code	Überprüfen Sie zunächst anhand von signtool csp list die Zertifikatsnummer.
Microsoft signtool.exe Provider nicht gefunden	Vergewissern Sie sich, dass der Installationsbefehl erfolgreich ausgeführt wurde, das aktuelle Tool und der Provider beide x64 sind, und öffnen Sie anschließend das Terminal erneut, bevor Sie es erneut versuchen.
Zertifikatsdatei beim Signieren nicht gefunden	Stellen Sie sicher, dass der Pfad unter /f mit dem unter csp add heruntergeladenen CERT_CODE.crt übereinstimmt.
Signaturaufruf fehlgeschlagen	Überprüfen Sie die Zertifikatsnummer, die Dienstanmeldedaten und die Netzwerkverbindung; sehen Sie anschließend in %ProgramData%\sslTrusKSP\sslTrusCSP.log nach.
Bei Verwendung einer benutzerdefinierten Dienstadresse, aber abnormalen Anfragen	CSP fixiert den /v1/codesign/sign Pfad des Anfragedienstes; die konfigurierte Dienstadresse sollte nur http(s)://host[:port] bereitstellen.

Sicherheitshinweise

• Access Secret, config.dat, Zertifikatsdateien und CSP-Protokolle sind als sensible Daten zu behandeln.
• config.dat ist durch DPAPI des aktuellen Windows-Benutzerprofils geschützt, das die Konfiguration erstellt hat, und sollte nicht direkt auf andere Benutzer oder Maschinen kopiert und wiederverwendet werden.
• CSP speichert keine privaten Schlüssel; versuchen Sie nicht, private Schlüssel in %ProgramData%\sslTrusKSP zu importieren.
• Die CSP-Signatur erfordert Zugriff auf den Remote-Dienst. Netzwerk-Timeouts, Ablehnung durch den Server oder Nichtverfügbarkeit des Zeitstempeldienstes können zu Signaturfehlern führen.

Weitere CLI-Parameter und Signaturbefehle finden Sie in der SignTool sign-Befehlsreferenz.