Leitfaden zur Fehlerbehebung für KeyLocker
KeyLocker ist ein leistungsstarkes Werkzeug zum Code-Signieren, das es Ihnen ermöglicht, Ihr Code-Signing-Zertifikat in der Cloud zu speichern und seinen Hash sicher aus der Ferne zu signieren. Die Ersteinrichtung hat jedoch einige Hürden, bei denen dieser Artikel hilft.
Variablenkontrolle
Ein wesentlicher Schritt für das Funktionieren des KeyLockers auf Ihrem System ist die korrekte Einstellung der Variablen. Diese bestimmen nicht nur den Pfad zu den Signaturwerkzeugen, sondern enthalten hauptsächlich Authentifizierungsdaten. Sie können sie für eine Sitzung oder dauerhaft festlegen.
Variablen können auf verschiedene Weise im System festgelegt werden. Neben einzelnen Dateien und Variablen können sie auch in den Windows Credential Manager gespeichert werden. Wenn Sie über eine GUI signieren möchten, können Sie sie im Click-to-Sign-Dienstprogramm einstellen, das Sie in Ihrem KeyLocker-Konto finden (Variablen funktionieren jedoch nicht auf Systemebene).
Sie stellen die Variable in Windows einfach über die Eingabeaufforderung ein. Öffnen Sie cmd und tippen Sie setx VARIABLE=Wert. Beachten Sie - setx arbeitet mit Benutzerumgebungsvariablen, nicht mit Systemvariablen.
Um den KeyLocker ordnungsgemäß nutzen zu können, müssen die Variablen für die Client-Authentifizierung und die Position von Signaturwerkzeugen und Bibliotheken von DigiCert eingestellt sein.
Authentifizierungseinstellung
- SM_CLIENT_CERT_FILE - Pfad zum Authentifizierungszertifikat mit der Endung p12, das Sie vom Assistenten in DigiCert ONE heruntergeladen haben
- SM_HOST - Host-Adresse 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 sie bedenkenlos im System festlegen. Die folgenden zwei Variablen sind jedoch geheime Daten und sollten nicht im System festgelegt werden, wenn mehrere Benutzer darauf zugreifen können. Es ist besser, sie im Windows-Passwort-Manager zu speichern. Weitere Informationen zum Festlegen 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 DC1-Assistenten angezeigt wurde
Einstellung des Pfades zu den Signaturwerkzeugen
Die Hinzufügung eines Wertes zur PATH-Variablen erfolgt mit dem 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 das ordnungsgemäße Funktionieren des KeyLockers müssen mindestens zwei Pfade eingestellt 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 von Ihnen installierte Versionsnummer). Sie benötigen außerdem die DigiCert Keylocker Tools, die Sie von DigiCert ONE heruntergeladen und installiert haben; sie befinden sich unter C:\Program Files\DigiCert\DigiCert Keylocker Tools.
Beide Variablen werden nacheinander über die CMD hinzugefügt, sonst überschreibt eine die andere:
setx PATH "C:\Program Files\DigiCert\DigiCert Keylocker Tools\;C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x86\;%PATH%"Systemvariablen können Sie auch über die Windows-GUI einstellen; über die CMD geht es schneller, aber die Werte werden bei mehrfachem Eingeben überschrieben. Es ist auch möglich, PowerShell zu verwenden.
Wie man die PATH-Variable manuell in Windows bearbeitet
Wenn Sie sicherstellen möchten, dass die Werte beibehalten werden, können Sie die PATH manuell bearbeiten:
- Öffnen Sie Systemsteuerung → System → Erweiterte Systemeinstellungen.
- Klicken Sie auf Umgebungsvariablen.
- Suchen Sie PATH (in Systemvariablen oder Benutzervariablen).
- Klicken Sie auf Bearbeiten, fügen Sie die einzelnen Pfade hinzu und speichern Sie.
Wie man die PATH-Variable mit PowerShell hinzufügt
Wenn Sie dauerhaft einen Pfad zur PATH-Variable mit PowerShell hinzufügen möchten, gehen Sie wie folgt vor:
- Öffnen Sie PowerShell als Administrator (klicken Sie mit der rechten Maustaste auf Start → Windows PowerShell (Admin)).
- Ermitteln Sie zunächst den aktuellen Wert der "PATH"-Variable:
[System.Environment]::GetEnvironmentVariable("Path", "User") - Fügen Sie dann einen 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") - Falls 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, um die Änderungen zu übernehmen.
Hinweis: Wenn Sie die systemweite "PATH"-Variable (gültig für alle Benutzer) ändern möchten, ersetzen Sie "User" durch "Machine" im Befehl.
Achtung: Nach dem Setzen der Variablen über die CMD starten Sie die Eingabeaufforderung neu, sonst treten die Änderungen nicht in Kraft!
Überprüfung des Variablenwerts in cmd: echo %VARIABLE% Beispielsweise "echo %PATH%". Dann zeigt cmd dessen Wert an.
Überprüfung korrekter Einstellungen
Die KeyLocker-Tools enthalten das Dienstprogramm smctl, mit dem Sie signieren können, das aber auch für grundlegende Diagnosen verwendet werden kann. Der folgende Befehl überprüft, ob alles richtig eingerichtet ist und ob sich smctl mit der DigiCert-Cloud verbinden kann:
smctl healthcheckIm Bericht sehen Sie eine Bestätigung, ob Sie sich mit dem KeyLocker verbunden haben (Authentifizierung funktioniert) und ob smctl die Anwesenheit der Signaturwerkzeuge, wie z.B. 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 Probleme mit der Authentifizierung gibt, überprüfen Sie, ob Sie die richtigen Werte festgelegt haben, die Sie im KeyLocker-Assistenten in der DigiCert ONE-Oberfläche erhalten haben. Wenn Sie Zweifel haben, können Sie den Assistenten zurücksetzen und neue Zugangsdaten erstellen.
Es kann auch vorkommen, dass smctl signtool oder andere Signaturwerkzeuge nicht erkennt. Das bedeutet, dass deren Position in der Benutzer- oder System-PATH-Variable hinzugefügt werden muss. Siehe oben im Abschnitt über Variablen.
MMC und Zertifikatprüfung
Wenn Sie mit Windows arbeiten, schauen Sie im Zertifikatsmanager nach, den Sie mit dem Befehl certmgr.msc starten. Wenn die Synchronisierung mit dem KeyLocker erfolgreich ist, sehen Sie ein Zertifikat mit dem Attribut privater Schlüssel im Zertifikatsspeicher. Dies bedeutet jedoch nicht, dass der private Schlüssel tatsächlich vorhanden ist - das Zertifikat mit dem privaten Schlüssel ist nach wie vor in der Cloud gespeichert.
Falls das Zertifikat fehlt, führen Sie die Synchronisierung aus.
smctl windows certsyncBei erfolgreicher Synchronisierung sehen Sie eine Bestätigung:
Syncing certificate for alias: key_1236506290, ID: ac793b6d-cac4-4be4-b145-003d4d1d63db and SHA1 Fingerprint: 54d0c7a2d93ae4d5fccb41d97c51a8ab3581c72cSignaturprobleme
Wenn Sie Probleme mit dem Signieren haben, versuchen Sie, von den allgemeinsten zu komplexeren Ansätzen zu gehen. Am einfachsten ist es, mit dem Dienstprogramm smctl von DigiCert zu signieren, das als Erweiterung zu Signaturwerkzeugen wie signtool oder jarsigner dienen kann. Dies ist der am wenigsten konfliktträchtige Weg und benötigt keine Parameter. Für die Fehlersuche verwenden Sie bitte keinen Zeitstempel oder andere Optionen.
Das Signieren mit smctl erfolgt einfach:
smctl sign --keypair-alias=key_1234567890 --input C:\Users\John.Doe\Desktop\file_to_sign.exeSie können auf das Zertifikat über den Parameter "keypair-alias" oder "fingerprint" verweisen, diese Informationen über das Zertifikat finden Sie beispielsweise mit dem Befehl smctl windows certsync.
Nach dem Signieren können Sie die Signatur überprüfen:
smctl sign verify --input <path to signed file or folder>Hilfe zum Signieren finden Sie im Artikel Sign binaries with SMCTL.
Nach dem erfolgreichen Signieren mit smctl können Sie auch ein anderes Tool verwenden, wie 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 nach Ihren Wünschen funktioniert, können Sie auch versuchen, beispielsweise mit Visual Studio oder in einer anderen Entwicklungsumgebung zu signieren.
Wo man Logs findet
Wenn alles oben Genannte fehlschlägt und das Signieren nicht funktioniert, empfehle ich, sich die Protokolle von smctl und anderen Tools von DigiCert anzusehen. Wenn Sie die Protokolle bei der Lösung eines Problems mit unserem Support verwenden, wird die Lösung des Problems sicherlich beschleunigt.
Das Log der smctl-Utility befindet sich in der Datei smctl.log, die im Ordner /.signingmanager/logs im jeweiligen Benutzerprofil abgelegt ist. Versuchen Sie, in cmd echo %USERPROFILE%/.signingmanager/logs zu schreiben, und Sie sehen den vollständigen Speicherort des Ordners.
Weitere Quellen und Informationen
- Häufige 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.