CSP-Verwendungshinweise

Übersicht

Diese Anleitung beschreibt die Konfiguration von sslTrus Cryptographic Service Provider (CSP) unter Windows und die Verwendung des cloudbasierten HSM für Codesignierung über die Microsoft signtool.exe des Windows SDK.

Der signtool csp dieses Projekts ist für Installation, Konfiguration und Wartung des Providers zuständig; für die tatsächliche Signierung wird die signtool.exe des Windows SDK verwendet. Beide sind nicht dasselbe Programm.

sslTrus Cryptographic Service Provider ist ein herkömmlicher CryptoAPI-CSP, der sich für Windows-Signierungsprozesse eignet, die über /csp und /kc angebunden werden. Der private Signaturschlüssel verbleibt stets im cloudbasierten HSM; lokal werden nur die CSP-DLL, das Signaturzertifikat und die durch Windows DPAPI geschützte Zugriffskonfiguration gespeichert.

Vorbereitung

• Windows-x64-System.
• Ein Terminal, das als Administrator ausgeführt wird, zum Installieren oder Deinstallieren des Providers.
• Das signtool CLI dieses Projekts, das den Unterbefehl 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).
• Das Netzwerk hat Zugriff auf den Codesignierungsdienst und den ausgewählten Zeitstempeldienst.

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

REM 本项目 CLI
signtool csp --help

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

Wenn im aktuellen Verzeichnis oder im PATH zwei Programme mit demselben Namen vorhanden sind, stellen Sie sicher, dass Sie über den vollständigen Pfad oder where das tatsächliche Ziel 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 dem 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

Führen Sie aus:

signtool csp install

Dieser Befehl führt folgende Aktionen aus:

• Schreibt sslTrusCSP.dll nach %ProgramData%\sslTrusKSP und kopiert sie in das Systemverzeichnis.
• Registriert sslTrus Cryptographic Service Provider mit dem Provider-Typ PROV_RSA_AES.
• Installiert die zugehörige KSP-DLL und registriert sslTrus Key Storage Provider sowie einen CNG-Provider-Alias mit demselben Namen wie der CSP.
• Erstellt oder speichert %ProgramData%\sslTrusKSP\config.dat; die Datei wird mit Windows DPAPI auf diesem Computer verschlüsselt.

Die Installation ändert die systemweite Provider-Registrierung und muss normalerweise in einem Administrator-Terminal ausgeführt werden. Stimmt die CSP-DLL-Version im Systemverzeichnis mit der eingebetteten Version überein, überspringt die CLI das Kopieren der CSP-DLL, führt die Provider-Registrierung aber trotzdem aus.

Zertifikatskonfiguration hinzufügen

Ausführen:

signtool csp add

Wenn Sie die NICSRS-Dienstadresse verwenden möchten:

signtool csp add --address nicsrs

--address ist kein URL-Durchreichparameter. Der aktuelle nicsrs verwendet den NICSRS-Dienst; Leerwerte, racent oder andere Werte verwenden den Standarddienst.

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

%ProgramData%\sslTrusKSP\CERT_CODE.crt

Gleichzeitig werden die Dienstadresse, Anmeldedaten, Zertifikatsnummer und der Zertifikatspfad in die verschlüsselte Konfigurationsdatei geschrieben. CERT_CODE ist sowohl die Kennung des Remote-Zertifikats als auch der Wert von /kc im späteren Microsoft signtool.exe.

Falls eine bereits vorhandene Zertifikatsnummer hinzugefügt wird, fragt die CLI, ob überschrieben werden soll: Eingabe von y ersetzt die alte Konfiguration; direktes Drücken der Eingabetaste oder Eingabe anderer Werte behält die ursprüngliche Konfiguration bei.

Konfiguration anzeigen und löschen

Aktuelle Konfiguration anzeigen:

signtool csp list

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

Löschen einer bestimmten Konfiguration:

signtool csp del

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

Verwenden der Microsoft signtool.exe-Signatur

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 an, der der Zertifikatsnummer entspricht.
/f <证书路径>	Gibt die heruntergeladene Zertifikatsdatei von csp add an.
/fd SHA256	Gibt den Datei-Hash-Algorithmus an.
/tr <URL>	Gibt den RFC 3161-Zeitstempeldienst an.
/td SHA256	Gibt den Zeitstempel-Hash-Algorithmus an.

Die aktuelle CSP unterstützt die Dateidigest-Algorithmen SHA1, SHA256, SHA384 und SHA512; für neue Signaturen wird in der Regel SHA-256 oder höher empfohlen. Die Zeitstempeladresse sollte von deiner Zertifikatsrichtlinie und der Kompatibilität der Zielplattform abhängen.

SHA-1-Signatur anhängen

Wenn tatsächlich Kompatibilitätsanforderungen für Altsysteme bestehen, kann eine SHA-1-Signatur 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 fügt eine Signatur hinzu, ohne vorhandene Signaturen zu überschreiben. Ob SHA-1 benötigt wird, sollte den Vorgaben des Zielsystems und der Zertifikatsrichtlinie entsprechen; es sollte nicht als Standardoption für neue Projekte verwendet werden.

Signatur überprüfen

Nach dem Signieren kann die Signatur mit Microsoft signtool.exe überprüft werden:

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

Um alle Signaturen zu prüfen, wählen Sie die entsprechenden Prüfoptionen anhand der Version und Parameterdokumentation von Windows SDK signtool.exe.

Provider deinstallieren

In einem Administrator-Terminal ausführen:

signtool csp uninstall

Dieser Befehl hebt die Registrierung des CSP und des gleichnamigen CNG-Provider-Alias auf und löscht die Kopien der CSP-DLL aus ProgramData und dem Systemverzeichnis. Er löscht weder das gesamte Verzeichnis %ProgramData%\sslTrusKSP noch automatisch die Registrierung und DLL des zugehörigen sslTrus Key Storage Provider. Falls dieser KSP ausschließlich vom CSP-Installationsprozess verwendet wurde, bereinigen Sie ihn unter Berücksichtigung der tatsächlichen Bereitstellung mit entsprechender Vorsicht.

Wenn Sie nach der Deinstallation vertrauliche lokale Daten entfernen möchten, löschen Sie die Konfigurationen, Zertifikate und Protokolle in %ProgramData%\sslTrusKSP erst dann manuell, wenn sie nicht mehr vom KSP oder anderen Signaturabläufen verwendet werden.

Häufige Fragen

Symptom	Empfehlung
cryptographic service provider is only supported on windows	Führen Sie den CSP-Verwaltungsbefehl unter Windows aus.
Fehler bei Berechtigung oder Schreiben in Systemverzeichnis während Installation	Verwenden Sie ein Administrator-Terminal, um signtool csp install auszuführen.
no csp configuration	Führen Sie zuerst signtool csp install aus, dann signtool csp add.
no such certificate code	Verwenden Sie zunächst signtool csp list, um die Zertifikatsnummer zu überprüfen.
Microsoft signtool.exe findet den Provider nicht	Stellen Sie sicher, dass der Installationsbefehl erfolgreich war, dass sowohl das aktuelle Tool als auch der Provider x64-Architektur verwenden, und öffnen Sie das Terminal erneut, bevor Sie es erneut versuchen.
Zertifikatsdatei beim Signieren nicht gefunden	Stellen Sie sicher, dass der Pfad von /f mit dem von csp add heruntergeladenen CERT_CODE.crt übereinstimmt.
Signaturaufruf fehlgeschlagen	Überprüfen Sie die Zertifikatsnummer, die Dienstanmeldedaten und die Netzwerkverbindung; sehen Sie sich anschließend %ProgramData%\sslTrusKSP\sslTrusCSP.log an.
Benutzerdefinierte Dienstadresse, aber fehlerhafte Anfrage	CSP ruft immer den Pfad /v1/codesign/sign des Dienstes auf. Die konfigurierte Dienstadresse darf daher nur http(s)://host[:port] enthalten.

Sicherheitshinweise

• Access Secret、config.dat、Zertifikatsdateien und CSP-Protokolle sind als sensible Daten zu behandeln.
• config.dat ist durch DPAPI des Windows-Benutzerprofils geschützt, unter dem die Konfiguration erstellt wurde, und sollte nicht direkt auf andere Benutzer oder Maschinen kopiert und wiederverwendet werden.
• Das CSP speichert keine privaten Schlüssel; versuchen Sie nicht, private Schlüssel in %ProgramData%\sslTrusKSP zu importieren.
• Die CSP-Signatur erfordert Zugriff auf den Remotedienst; Netzwerkzeitüberschreitungen, Ablehnungen durch den Server oder nicht verfügbare Zeitstempeldienste können zum Fehlschlagen der Signatur führen.

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