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.

Hinzufügen von Variablen über die Windows-GUI

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 healthcheck

Im 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_50dxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxe4 (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

Permissions:
Account Manager:
  MANAGE_AM_PERMISSION
  MANAGE_AM_ROLE
  MANAGE_AM_ACCOUNT_USER
  VIEW_AM_ROLE
  VIEW_AM_ACCOUNT
  VIEW_AM_USER
  VIEW_AM_ORGANIZATION
  VIEW_AM_AUDIT_LOG

Keypairs:
  SIGN_SM_HASH
  VIEW_SM_KEYPAIR
  MANAGE_SM_KEYPAIR

Certificates:
  VIEW_SM_CERTIFICATE
  REVOKE_SM_CERTIFICATE

Other permissions:
  VIEW_SM_LICENSE
  MANAGE_SM_CC_API_KEY

--------- 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: No

Wenn 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 certsync Bei erfolgreicher Synchronisierung sehen Sie eine Bestätigung:

Syncing certificate for alias: key_1236506290, ID: ac793b6d-cac4-4be4-b145-003d4d1d63db and SHA1 Fingerprint: 54d0c7a2d93ae4d5fccb41d97c51a8ab3581c72c

Signaturprobleme

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.exe

Sie 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

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

```

War für Sie dieser Artikel nützlich?

Infozentrum

SSLmarket app