Fehlerbehebungsleitfaden für KeyLocker
KeyLocker ist ein leistungsstarkes Werkzeug für Codesignierung, das die Speicherung Ihres Codesignierungszertifikats in der Cloud und die sichere Fernsignierung dessen Hashes ermöglicht. Die anfängliche Einrichtung hat jedoch bestimmte Tücken, bei denen dieser Artikel hilft.
Überprüfung der Variablen
Ein entscheidender Schritt für die Funktion von KeyLocker auf Ihrem System ist die korrekte Einrichtung der Variablen. Diese bestimmen nicht nur den Pfad zu den Signierungswerkzeugen, sondern tragen auch die Authentifizierungsinformationen. Sie können diese für eine Sitzung oder dauerhaft einrichten.
Sie können die Variablen auf verschiedene Arten in Ihr System einrichten. Neben einer separaten Datei und den Variablen können Sie sie auch im Windows Credential Manager speichern. Wenn Sie über ein GUI signieren möchten, können Sie sie im Click-to-sign Tool einrichten, das Sie in Ihrem KeyLocker-Konto finden (die Variablen funktionieren jedoch nicht auf Systemebene).
Die Einrichtung einer Variablen erfolgt in Windows einfach über die Eingabeaufforderung. Starten Sie cmd und geben Sie setx VARIABLE=Wert. Beachten Sie - setx arbeitet mit Benutzer-, nicht mit Systemvariablen.
Für das korrekte Funktionieren von KeyLocker müssen die Variablen für die Client-Authentifizierung und die Position der DigiCert-Signierungswerkzeuge und Bibliotheken eingerichtet werden.
Einrichtung der Authentifizierung
- SM_CLIENT_CERT_FILE - Pfad zum Authentifizierungszertifikat mit der Endung p12, das Sie aus dem Leitfaden in DigiCert ONE heruntergeladen haben
- SM_HOST - Hostadresse von DigiCert ONE, diese ist https://clientauth.one.digicert.com
Diese beiden Variablen sind nicht geheim, da das Zertifikat durch ein Passwort geschützt ist. Sie können diese problemlos im System einrichten. Die folgenden zwei Variablen sind jedoch geheim, und ich empfehle, sie nicht im System einzurichten, wenn mehrere Benutzer darauf zugreifen können. Es ist besser, sie im Windows-Passwortmanager zu speichern. Weitere Informationen zur Einrichtung von Variablen für Windows finden Sie im Artikel Credential setup for Windows.
- SM_API_KEY - API-Schlüssel, den Sie in der DigiCert ONE-Oberfläche generiert haben
- SM_CLIENT_CERT_PASSWORD - Passwort für das Authentifizierungszertifikat in P12, das Ihnen einmalig im Leitfaden DC1 angezeigt wurde
Einrichtung des Pfads zu den Signierungswerkzeugen
Das Hinzufügen eines Werts zur PATH-Variable erfolgt durch den Befehl setx PATH "Pfad;%PATH%". Dieser Befehl fügt einen neuen Wert zu den bestehenden Benutzerwerten der PATH-Variable hinzu und speichert ihn dauerhaft. Für die korrekte Funktion von KeyLocker müssen mindestens zwei Pfade eingerichtet werden:
- Pfad zu Windows SDK und signtool
- Pfad zu DigiCert Keylocker Tools
Ermitteln Sie den gültigen Pfad zum Windows SDK (der Pfad verwendet die Versionsnummer, die Sie installiert haben). Außerdem benötigen Sie die DigiCert Keylocker Tools, die Sie von DigiCert ONE heruntergeladen und installiert haben; sie befinden sich in C:\Program Files\DigiCert\DigiCert Keylocker Tools.
Wir fügen beide Variablen auf einmal über CMD hinzu, sonst wird eine von der anderen überschrieben:
setx PATH "C:\Program Files\DigiCert\DigiCert Keylocker Tools\;C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x86\;%PATH%"Sie können Systemsvariablen auch über das Windows-GUI einrichten; über CMD ist es schneller, aber die Werte werden bei mehrfacher Eingabe überschrieben. Auch PowerShell kann verwendet werden.
Wie man die PATH-Variable manuell in Windows bearbeitet
Wenn Sie sicherstellen möchten, dass die Werte erhalten bleiben, können Sie PATH manuell bearbeiten:
- Öffnen Sie die Systemsteuerung → System → Erweiterte Systemeinstellungen.
- Klicken Sie auf Umgebungsvariablen.
- Suchen Sie PATH (in Systemvariablen oder Benutzervariablen).
- Klicken Sie auf Bearbeiten, fügen Sie einzelne Pfade hinzu und speichern Sie.
Wie man die PATH-Variable mit PowerShell hinzufügt
Wenn Sie einen Pfad dauerhaft zu der PATH-Variable mit PowerShell hinzufügen möchten, folgen Sie diesen Schritten:
- Öffnen Sie PowerShell als Administrator (klicken Sie mit der rechten Maustaste auf Start → Windows PowerShell (Admin)).
- Bestimmen Sie zuerst den aktuellen Wert der "PATH"-Variablen:
[System.Environment]::GetEnvironmentVariable("Path", "User") - Fügen Sie dann den neuen Pfad zu den bestehenden Werten hinzu:
$path = [System.Environment]::GetEnvironmentVariable("Path", "User") $newPath = $path + ";C:\Program Files\DigiCert\DigiCert Keylocker Tools\" [System.Environment]::SetEnvironmentVariable("Path", $newPath, "User") - Wenn Sie einen weiteren Pfad hinzufügen müssen, wiederholen Sie den Vorgang:
$newPath = $newPath + ";C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x86\" [System.Environment]::SetEnvironmentVariable("Path", $newPath, "User") - Starten Sie nach der Ausführung der Befehle die Eingabeaufforderung oder den Computer neu, damit die Änderungen wirksam werden.
Hinweis: Wenn Sie die Systemvariable "PATH" (für alle Benutzer gültig) ändern möchten, ersetzen Sie "User" durch "Machine" im Befehl.
Achtung: Starten Sie die Eingabeaufforderung nach der Einrichtung der Variablen über CMD neu, sonst werden die Änderungen nicht wirksam!
Überprüfung des Variablenwerts in cmd: echo %VARIABLE% Zum Beispiel "echo %PATH%". Dann zeigt Ihnen cmd deren Wert an.
Überprüfung der korrekten Einrichtung
Die KeyLocker Tools enthalten das Dienstprogramm smctl, mit dem Sie signieren können, es dient jedoch auch zur grundlegenden Diagnose. Der folgende Befehl überprüft, ob alles auf der Station richtig eingerichtet ist und ob sich smctl mit der DigiCert-Cloud verbinden kann:
smctl healthcheckIm Protokoll sehen Sie eine Bestätigung, ob Sie mit dem KeyLocker verbunden sind (Authentifizierung funktioniert) und ob smctl das Vorhandensein von Signierungswerkzeugen wie signtool erkennt. Beispiel:
smctl healthcheck
--------- Account Settings ---------
Teams: Disabled
Threat detection: Enabled
Static Binary Analysis: Enabled
Software Composition Analysis: Disabled
--------- User credentials ---------
Status: Connected
Username: XXXX-keylocker
Accounts: XXXX-1699076
Authentication: 2FA
Environment: Prod
Credentials:
Host: https://clientauth.one.digicert.com
API key: 010897bf735bbc57d48270cd3d_50dxxxxx...e4 (Pulled from environment variable)
Client certificate file path: C:\Users\xy\Documents\keylocker\Certificate_pkcs12.p12
Client certificate password: ytf_xxxxxx0F (Pulled from environment variable)
API keys:
Name: xy (expires on Mon, 31 Dec 2029 23:59:59 UTC)
Client certificates:
Name: xy (expires on Mon, 31 Dec 2029 23:59:59 UTC)
Privileges:
Can sign: Yes
Can approve offline release: No
Can revoke certificate: Yes
Can scan: No
--------- Signing tools ---------
Signtool 32 bit:
Mapped: No
Signtool:
Mapped: Yes
Path: C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x86\signtool.exe
Mage:
Mapped: No
Nuget:
Mapped: No
Jarsigner:
Mapped: No
Apksigner:
Mapped: NoWenn es ein Problem mit der Authentifizierung gibt, überprüfen Sie, ob Sie die richtigen Werte eingerichtet haben, die Sie im KeyLocker-Leitfaden in der DigiCert ONE-Oberfläche erhalten haben. Wenn Sie Zweifel haben, können Sie den Leitfaden zurücksetzen und neue credentials erstellen.
Es kann auch vorkommen, dass smctl signtool oder andere Signierungswerkzeuge nicht erkennt. Dies bedeutet, dass deren Position in der Benutzer- oder System-PATH-Variable hinzugefügt werden muss. Siehe oben im Abschnitt zu den Variablen.
MMC und Zertifikatsprüfung
Wenn Sie auf Windows arbeiten, schauen Sie sich den Zertifikatsmanager an, den Sie durch den Befehl certmgr.msc starten. Wenn die Synchronisation mit dem KeyLocker erfolgreich verläuft, sehen Sie das Zertifikat mit dem privaten Schlüsselkürzel im Zertifikatsspeicher. Das bedeutet jedoch nicht, dass es tatsächlich mit privatem Schlüssel vorhanden ist - das Zertifikat mit privatem Schlüssel wird immer noch in der Cloud gespeichert.
Wenn dort kein Zertifikat ist, starten Sie die Synchronisation.
smctl windows certsyncBei erfolgreicher Synchronisation sehen Sie eine Bestätigung:
Syncing certificate for alias: key_1236506290, ID: ac793b6d-cac4-4be4-b145-003d4d1d63db and SHA1 Fingerprint: 54d0c7a2d93ae4d5fccb41d97c51a8ab3581c72cProbleme bei der Signatur
Bei Signierungsproblemen, beginnen Sie mit dem Allgemeinsten und gehen Sie zu den Komplexeren über. Am einfachsten ist es, mit dem DigiCert-Dienstprogramm smctl zu signieren, das als Overlay für Signierungswerkzeuge wie signtool oder jarsigner dienen kann. Dies ist der am wenigsten konfliktträchtige Weg und erfordert keine Parameter. Verwenden Sie zur Problemlösung keinen Timestamp oder andere Optionen.
Die Signatur mit smctl führen Sie einfach aus:
smctl sign --keypair-alias=key_1234567890 --input C:\Users\John.Doe\Desktop\file_to_sign.exeSie können auf das Zertifikat mit dem Parameter "keypair-alias" oder "fingerprint" verweisen, diese Informationen zum Zertifikat finden Sie z.B. mit dem Befehl smctl windows certsync.
Nach der Signatur können Sie die Signatur überprüfen:
smctl sign verify --input <path to signed file or folder>Eine Anleitung zur Signierung finden Sie im Artikel Sign binaries with SMCTL.
Nach einer erfolgreichen Signatur mit smctl können Sie mit einem anderen Tool signieren, z.B. signtool. Dieses sollte ebenfalls funktionieren. Lassen Sie die Zertifikatsauswahl automatisch und fügen Sie nach und nach weitere Parameter hinzu.
Wenn es erfolgreich gemäß Ihren Vorstellungen funktioniert, können Sie Signierung z.B. mit Visual Studio oder in einer anderen Entwicklungsumgebung ausprobieren.
Wo man die Logdateien findet
Wenn alles oben Genannte fehlschlägt und die Signatur nicht funktioniert, empfehle ich, sich die smctl-Logdateien und andere DigiCert-Tools anzusehen. Wenn Sie die Logdateien bei der Problemlösung mit unserem Support verwenden, wird dies sicherlich die Lösung des Problems beschleunigen.
Das Log des smctl-Utilities befindet sich in der Datei smctl.log, die im Ordner /.signingmanager/logs im jeweiligen Benutzerprofil abgelegt wird. Versuchen Sie, in cmd echo %USERPROFILE%/.signingmanager/logs einzugeben, und Sie sehen den vollständigen Pfad des Ordners.
Weitere Ressourcen und Informationen
- Häufigste Fehler - Troubleshoot Guide in der KeyLocker-Dokumentation.
- KeyLocker-Dokumentation auf der DigiCert-Website
Haben Sie Fragen?
Zögern Sie nicht, unseren Kundensupport zu kontaktieren, der Ihnen berät und hilft.
War für Sie dieser Artikel nützlich?
Wir danken Ihnen für Ihr Feedback zu diesem Artikel.
Es tut uns leid, dass Sie hier für Ihren Bedarf nichts Passendes gefunden haben.
Helfen Sie uns, diesen Artikel zu verbessern. Schreiben Sie uns bitte, was Sie hier erwartet und nicht erfahren haben.