Résoudre les problèmes de KeyLocker

KeyLocker est un outil avancé de signature de code conçu pour stocker les certificats de signature dans le cloud et signer des fichiers à distance. Bien que sa configuration initiale puisse présenter quelques défis pour certains utilisateurs, cet article vise à vous guider pas à pas dans son installation et à dissiper toute incertitude éventuelle.

Les variables et leurs vérification

Pour garantir le bon fonctionnement de KeyLocker sur votre système, configurez correctement les variables. Ces variables spécifient le chemin vers les outils de signature, mais elles transportent également les données d'authentification. Vous pouvez définir ces variables pour une session unique ou de manière permanente.

Plusieurs méthodes sont disponibles pour définir ces variables dans le système. Vous pouvez soit utiliser un fichier pour stocker les variables, soit enregistrer les variables dans le Gestionnaire d'identifiants de Windows. Si vous préférez utiliser l'interface graphique pour la signature, vous avez la possibilité de configurer ces variables via l'outil Click-to-sign, accessible depuis votre compte KeyLocker. Cependant, veuillez noter que les variables configurées de cette manière ne fonctionneront pas au niveau du système.

Pour définir une variable dans la console Windows, suivez ces étapes : allez dans le menu Démarrer, cliquez sur Exécuter, tapez "cmd" et, dans la fenêtre qui s'ouvre, entrez la commande suivante setx VARIABLE=valeur Attention - Notez qu'il est important de savoir que la commande `setx` agit sur des variables utilisateur et non sur des variables système.

Enfin, pour assurer le bon fonctionnement de KeyLocker, il est crucial de définir les variables relatives à l'authentification client, ainsi que l'emplacement des outils de signature et des bibliothèques DigiCert.

Paramétrer l'authentification

Pour configurer le chemin d'accès que votre système ou application doit utiliser pour accéder aux outils de signature, suivez les étapes suivantes.

Définissez le chemin du certificat d'authentification : SM_CLIENT_CERT_FILE - chemin d'accès à l'emplacement du certificat d'authentification avec l'extension p12 que vous avez téléchargé à partir de l'assistant dans DigiCert ONE
Configurez l'adresse de l'hôte : SM_HOST - adresse de l'hôte (host adresse) de DigiCert ONE : https://clientauth.one.digicert.com

Ces deux variables ne sont pas considérées comme confidentielles, car le certificat est sécurisé par un mot de passe. Vous pouvez les configurer aisément dans votre système. Cependant, pour les deux variables suivantes, qui sont de nature confidentielle, nous vous recommandons de ne pas les définir dans un environnement partagé. Il est préférable de les stocker de manière sécurisée dans le gestionnaire de mots de passe de Windows. Pour plus de détails sur la configuration des variables sous Windows, veuillez vous référer à l'article Credential setup for Windows.

SM_API_KEY - clé API que vous avez générée dans DigiCert ONE
SM_CLIENT_CERT_PASSWORD - mot de passe pour le certificat d'authentification qui vous a été affiché une seule fois dans l'assistant DC1

Définir le chemin vers les outils de signature

Pour configurer correctement les outils de signature, il est nécessaire de définir les chemins dans la variable d'environnement PATH. Cela garantit le bon fonctionnement de KeyLocker. Voici comment procéder : Utilisez la commande suivante pour ajouter une nouvelle valeur à la variable PATH et l'enregistrer de manière permanente : setx PATH "chemin;%PATH%" Pour assurer le bon fonctionnement de KeyLocker, il est essentiel de définir au moins deux paramètres :

Chemin vers Windows SDK et signtool
Chemin vers DigiCert Keylocker Tools

Identifiez le chemin valide vers le SDK Windows en fonction de la version que vous avez installée. Assurez-vous d'avoir téléchargé et installé les outils DigiCert KeyLocker à partir de DigiCert ONE. Vous pouvez les trouver à l'emplacement suivant C:\Program Files\DigiCert\DigiCert Keylocker Tools.

Pour éviter que les variables ne se remplacent l'une l'autre, ajoutez-les simultanément via l'invite de commandes (CMD) : setx PATH "C:\Program Files\DigiCert\DigiCert Keylocker Tools\;C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x86\;%PATH%"

Vous avez également la possibilité de définir des variables système via l’interface graphique de Windows. Bien que l'utilisation de CMD soit plus rapide, les valeurs peuvent être écrasées si elles sont saisies plusieurs fois. Alternativement, vous pouvez utiliser PowerShell.

Comment modifier manuellement la variable PATH sous Windows

Si vous voulez être sûr que les valeurs sont conservées, vous pouvez modifier PATH manuellement en suivant ces étapes :

Ouvrez Panneau de configuration → Système → Paramètres système avancés.
Sélectionnez Variables d’environnement.
Trouvez PATH (dans Variables système ou Variables utilisateur).
Cliquez sur Modifier, ajoutez les chemins souhaités et enregistrez vos modifications.

Comment ajouter la variable PATH avec PowerShell

Pour ajouter un chemin à la variable PATH de façon permanente à l'aide de PowerShell, suivez ces étapes :

Ouvrez PowerShell en tant qu'Administrateur (Faites un clic droit sur le bouton Démarrer → Windows PowerShell (Admin)).
Vérifiez la Valeur Actuelle de la Variable "PATH" :

[System.Environment]::GetEnvironmentVariable("Path", "User")

Ajoutez le nouveau chemin à la variable :


$path = [System.Environment]::GetEnvironmentVariable("Path", "User")
$newPath = $path + ";C:\Program Files\DigiCert\DigiCert Keylocker Tools\"
[System.Environment]::SetEnvironmentVariable("Path", $newPath, "User")

Ajoutez un autre chemin (si besoin) : si vous devez ajouter un autre chemin, répétez le processus


$newPath = $newPath + ";C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x86\"
[System.Environment]::SetEnvironmentVariable("Path", $newPath, "User")

Redémarrez la ligne de commande ou votre ordinateur pour que les modifications soient prises en compte.

Remarque : Si vous souhaitez modifier la variable système "PATH" (qui va s'appliquer à tous les utilisateurs), remplacez "User" par "Machine" dans la commande.

Remarque : Après avoir défini les variables via CMD, veillez à redémarrer votre session de commande pour que les modifications prennent effet.

Vérification de la valeur d'une variable dans cmd : echo %VARIABLE% Par exemple "echo %PATH%". Cmd affichera la valeur actuelle de la variable PATH.

Vérification de la configuration

SMCTL (Signing Manager Controller), qui fait partie des outils "KeyLocker", vous permet non seulement de signer des documents, mais aussi de réaliser des diagnostics de base. La commande suivante s'assurera que tout est correctement configuré sur votre station de travail et que smctl est en mesure de se connecter au cloud de DigiCert :

smctl healthcheck

Cette commande vous fournira une confirmation si vous êtes connecté à KeyLocker (vérifie que l'authentification est opérationnelle) et si smctl détecte la présence d'outils de signature, tels que signtool. Voici un exemple de sortie :

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:Vérification des variables
        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

Si vous rencontrez un problème d'authentification, assurez-vous d'avoir correctement défini les valeurs récupérées dans l'assistant KeyLocker de l'interface DigiCert ONE. En cas de doute, il est possible de réinitialiser l'assistant et créer de nouvelles informations d'identification "credentials".

Un autre problème potentiel peut survenir si smctl ne détecte pas signtool ou d'autres outils de signature. Dans ce cas, il est nécessaire d'ajouter leur emplacement à la variable PATH, soit au niveau de l'utilisateur, soit au niveau du système. Pour plus d'informations, veuillez vous référer à la section précédente dédiée aux variables.

MMC et contrôle de la présence du certificat

Si vous travaillez sous Windows, ouvrez le gestionnaire des certificat en exécutant la commande certmgr.msc). Après une synchronisation réussie avec KeyLocker, le certificat apparaîtra dans le magasin de certificats, accompagné de l'indicateur de clé privée. Toutefois, cela ne signifie pas que la clé privée est réellement là : le certificat avec la clé privée reste toujours stocké dans le cloud.

Si le certificat n'est pas présent, lancez la synchronisation. smctl windows certsync Si la synchronisation est réussie, un message de confirmation s'affichera :

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

Problèmes de signature

Si vous rencontrez des difficultés pour signer, il est conseillé de progresser du plus simple au plus complexe. La manière la plus aisée de signer est d'utiliser l'utilitaire smctl de DigiCert, qui peut agir comme une extension pour des outils de signature tels que signtool ou jarsigner. Cette méthode minimise les conflits et ne requiert aucun paramétrage spécifique. Afin de résoudre les problèmes, évitez d'utiliser des options d'horodatage/timestamp ou d'autres options pareilles.

Signer avec cmctl est simple : smctl sign --keypair-alias=key_1234567890 --input C:\Users\John.Doe\Desktop\file_to_sign.exe

Vous pouvez référencer le certificat soit par le paramètre "keypair-alias" soit par "fingerprint", Ces informations sur le certificat sont accessibles par exemple en utilisant la commande smctl windows certsync.

Vous pouvez vérifier la signature avec la commande suivante : smctl sign verify --input

Pour obtenir de l'aide sur la signature, référez-vous à l'article Sign binaries with SMCTL.

Une fois que vous avez signé avec SMCTL, vous pouvez également essayer de signer avec un autre outil, comme SignTool. Cela devrait également fonctionner. Optez pour la sélection automatique du certificat et ajoutez d'autres paramètres à votre configuration.

Une fois que vous êtes satisfait du fonctionnement, vous pouvez tenter de signer avec Visual Studio ou un autre environnement de développement.

Où se trouvent des logs ?

Si les étapes précédentes n'ont pas permis de résoudre le problème et que la signature ne fonctionne toujours pas, nous vous recommandons de consulter les logs de smctl ainsi que d'autres outils de DigiCert.

Le log de l'utilitaire smctl est enregistré dans le fichier smctl.log, que vous trouverez dans le dossier `/signingmanager/logs` de votre profil utilisateur. Pour accéder à l'emplacement exact, vous pouvez utiliser la commande suivante echo %USERPROFILE%/.signingmanager/logsCela affichera le chemin complet vers le dossier des journaux.

Sources d'information

Erreurs courants - Troubleshoot Guide dans la documentation du KeyLocker.
Documentation du KeyLocker sur le site web de DigiCert

Aide

Application SSLmarket