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.

Hinzufügen von Variablen über das Windows-GUI

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 healthcheck

Im 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_50dxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxe4 (aus Umgebungsvariable gezogen)
        Client certificate file path: C:\Users\xy\Documents\keylocker\Certificate_pkcs12.p12
        Client certificate password: ytf_xxxxxx0F (aus Umgebungsvariable gezogen)
API keys:
        Name: xy (läuft ab am Mo, 31 Dez 2029 23:59:59 UTC)
       
Client certificates:
        Name: xy (läuft ab am Mo, 31 Dez 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 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 certsync Bei erfolgreicher Synchronisation sehen Sie eine Bestätigung:

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

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

Sie 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

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

War für Sie dieser Artikel nützlich?

Infozentrum

SSLmarket app