signtool ksp et intégration avec le KSP Windows
signtool ksp gère le sslTrus Key Storage Provider Windows (KSP). Une fois le KSP installé et configuré, le signtool.exe de Microsoft peut appeler le service de signature à distance via le fournisseur CNG, sans avoir besoin de détenir la clé privée localement.
Toutes les sous-commandes de signtool ksp sont uniquement prises en charge sur la plateforme Windows. L’exécution de toute sous-commande ksp sur une plateforme non Windows renverra :
key storage provider is only supported on windows
Aperçu des sous-commandes
signtool ksp [command]
| Sous-commande | Usage |
|---|---|
install | Installer et enregistrer la DLL KSP |
uninstall | Désenregistrer KSP et supprimer la DLL |
list | Lister les configurations de clé KSP enregistrées |
add | Ajouter une configuration de clé KSP (interactif) |
del | Supprimer la configuration de clé KSP spécifiée (interactif) |
Le paramètre --address n'est valide que lorsque ksp add, il est utilisé pour obtenir le PEM du certificat et enregistrer l'adresse du service distant.
Installer KSP
signtool ksp install
Après exécution :
- Écrivez le
sslTrusKSP.dllintégré dansProgramData/sslTrusKSP/sslTrusKSP.dll. - Si la version de la DLL dans ProgramData diffère de celle dans System32, copiez la DLL vers System32.
- Enregistrez le fournisseur CNG :
sslTrus Key Storage Provider. - Enregistrez le fichier de configuration KSP
ProgramData/sslTrusKSP/config.dat(chiffré par DPAPI).
install modifie l’enregistrement du fournisseur CNG au niveau système ; il est recommandé de l’exécuter dans un terminal administrateur. Si la version de la DLL détectée est identique, ksp is already installed est consigné et le processus retourne directement.
Désinstaller KSP
signtool ksp uninstall
Après exécution :
- Désenregistrer le fournisseur CNG :
sslTrus Key Storage Provider. - Supprimer
ProgramData/sslTrusKSP/sslTrusKSP.dll. - Supprimer
sslTrusKSP.dlldans System32.
uninstall ne supprime pas le répertoire ProgramData/sslTrusKSP entier. Les config.dat, les fichiers de certificat et les journaux déjà enregistrés doivent être nettoyés manuellement.
Voir la configuration des clés
signtool ksp list
Description des champs de sortie :
| Champ | Signification |
|---|---|
No | Numéro d’ordre |
CertCode | Numéro du certificat |
ServerUrl | Affiché comme nicsrs ou default |
AccessKey | Access Key |
AccessSecret | Access Secret masqué |
- S’il n’existe pas de fichier de configuration, renvoie
no ksp configuration.
- Si la configuration existe mais que la liste des clés est vide, enregistrez
no ksp key. AccessSecrets'affiche de manière masquée, mais le fichier de configuration lui-même doit toujours être géré comme un fichier sensible. :::
Ajouter une configuration de clé
signtool ksp add
Spécifiez l'adresse NICSRS :
signtool ksp add --address nicsrs
La commande est interactive, saisissez dans l’ordre :
Please enter the access key: your-access-key
Please enter the access secret: your-access-secret
Please enter the certificate code: CERT_CODE
Après exécution :
- Appelez le
/v1/codesign/certdistant pour obtenir le PEM du certificat. - Enregistrez le certificat sous
ProgramData/sslTrusKSP/CERT_CODE.crt. - Écrivez la configuration de la clé dans
ProgramData/sslTrusKSP/config.dat(chiffrement DPAPI).
Si le numéro de certificat existe déjà, un message s'affiche :
The certificate code already exists, do you want to override it? [y/N]
Saisissez y pour écraser, toute autre valeur ou appui direct sur Entrée annule l’opération.
ksp add est une commande interactive, les paramètres non interactifs tels que --access-key, --cert-code ne sont pas pris en charge. L’ajout de la configuration accède à l’API distante et écrit le PEM du certificat dans le dossier ProgramData local.
Supprimer la configuration de clé
signtool ksp del
Saisie interactive du numéro de certificat :
Please enter the certificate code: CERT_CODE
Exécutez puis supprimez la configuration de clé correspondante de config.dat, puis enregistrez à nouveau le fichier de configuration chiffré.
L’implémentation actuelle supprime uniquement l’élément de configuration, et ne supprime pas le fichier de certificat ProgramData/sslTrusKSP/CERT_CODE.crt.
Utiliser Microsoft signtool.exe via KSP
Une fois la configuration KSP terminée, utilisez le signtool.exe de Microsoft du SDK Windows pour appeler le fournisseur.
Le signtool.exe dans les commandes ci-dessous est un outil fourni avec le SDK Windows de Microsoft, et non l’interface CLI de sslTrus. Si les deux outils sont présents simultanément dans le répertoire courant ou dans le PATH, utilisez le chemin complet du signtool.exe du SDK Windows pour éviter toute confusion.
Exemple de signature SHA256 :
signtool.exe sign /v ^
/csp "sslTrus Key Storage Provider" ^
/kc CERT_CODE ^
/f C:\ProgramData\sslTrusKSP\CERT_CODE.crt ^
/fd SHA256 ^
/tr http://timestamp.acs.microsoft.com ^
/td SHA256 ^
.\EXAMPLE.exe
Exemple d'ajout de signature SHA1 :
signtool.exe sign /v ^
/csp "sslTrus Key Storage Provider" ^
/kc CERT_CODE ^
/f C:\ProgramData\sslTrusKSP\CERT_CODE.crt ^
/fd SHA1 ^
/tr http://timestamp.acs.microsoft.com ^
/td SHA256 ^
/as ^
.\EXAMPLE.exe
Description des paramètres :
| Paramètre | Signification |
|---|---|
/csp "sslTrus Key Storage Provider" | Spécifie le KSP Provider installé par sslTrus |
/kc CERT_CODE | Spécifie le nom de la clé KSP, correspondant au numéro du certificat |
/f C:\ProgramData\sslTrusKSP\CERT_CODE.crt | Spécifie le fichier de certificat enregistré par ksp add |
/fd SHA256 ou /fd SHA1 | Algorithme de hachage du fichier |
/tr <url> | Service d’horodatage RFC3161 |
/td SHA256 | Algorithme de hachage de l’horodatage |
/as | Ajoute une signature sans écraser la signature existante |
Référence de dépannage
| Message d’erreur | Cause possible | Suggestion de traitement |
|---|---|---|
key storage provider is only supported on windows | La commande ksp a été exécutée sur une plateforme non Windows. | Exécutez les opérations KSP uniquement sur Windows. |
no ksp configuration | Le fichier de configuration KSP n’a pas encore été créé. | Exécutez d’abord signtool ksp install et signtool ksp add. |
no such certificate code | Le numéro du certificat à supprimer n’existe pas. | Utilisez signtool ksp list pour vérifier le numéro du certificat. |
Consignes de sécurité
signtool ksp installetsigntool ksp uninstallmodifient le répertoire système Windows et le registre du fournisseur CNG, nécessitant généralement des privilèges d'administrateur.signtool ksp addaccède à l'interface de certificat distante et écrit les fichiers de certificat ainsi que la configuration chiffrée dansProgramData/sslTrusKSP.- Access Secret, les fichiers de configuration KSP et les journaux locaux doivent être traités comme des informations sensibles et ne doivent pas être écrits dans les journaux ou les dépôts de versions.