Guide d'utilisation du CSP

Aperçu

Ce guide décrit la configuration du sslTrus Cryptographic Service Provider (CSP) sur Windows, ainsi que l'utilisation du signtool.exe de Microsoft du SDK Windows pour réaliser la signature de code à l'aide du HSM cloud.

Le signtool csp de ce projet est responsable de l'installation, de la configuration et de la maintenance du fournisseur ; lors de la signature effective, c'est le signtool.exe du SDK Windows qui est utilisé. Les deux ne constituent pas le même programme.

Le sslTrus Cryptographic Service Provider est un CSP CryptoAPI traditionnel, adapté aux flux de signature Windows nécessitant une intégration via /csp et /kc. La clé privée de signature reste en permanence dans le HSM cloud ; la machine locale ne conserve que la DLL du CSP, le certificat de signature et la configuration d'accès protégée par Windows DPAPI.

Prérequis

• Système Windows x64.
• Un terminal exécuté en tant qu'administrateur, pour installer ou désinstaller le fournisseur.
• La CLI signtool de ce projet, incluant la sous-commande csp.
• Le SDK Windows est installé et Microsoft signtool.exe peut être utilisé.
• Une clé d’accès (Access Key), un secret d’accès (Access Secret) et un numéro de certificat (CERT_CODE) valides.
• Le réseau permet d’accéder au service de signature de code et au service d’horodatage choisi.

Confirmez que les deux outils sont utilisables séparément :

REM 本项目 CLI
signtool csp --help

REM Windows SDK 工具；必要时请使用其完整路径
signtool.exe sign /?

Si le répertoire courant ou le PATH contient simultanément deux programmes portant le même nom, vérifiez impérativement la cible réellement appelée via le chemin complet ou where.

Démarrage rapide

Dans un terminal administrateur, exécutez successivement :

signtool csp install
signtool csp add
signtool csp list

csp add demandera de manière interactive la saisie de :

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 une configuration réussie, utilisez le SDK Windows pour signer avec Microsoft signtool.exe :

signtool.exe sign /v ^
  /csp "sslTrus Cryptographic Service Provider" ^
  /kc CERT_CODE ^
  /f "C:\ProgramData\sslTrusKSP\CERT_CODE.crt" ^
  /fd SHA256 ^
  /tr http://timestamp.acs.microsoft.com ^
  /td SHA256 ^
  ".\app.exe"

Remplacez CERT_CODE et app.exe dans l'exemple par le numéro de certificat réel et le fichier à signer.

Installer le Provider

Exécutez :

signtool csp install

Cette commande va :

• Écrire sslTrusCSP.dll dans %ProgramData%\sslTrusKSP et le copier dans le répertoire système.
• Enregistrer sslTrus Cryptographic Service Provider (le type de fournisseur est PROV_RSA_AES).
• Installer la DLL KSP associée et enregistrer l’alias de fournisseur CNG sslTrus Key Storage Provider portant le même nom que le CSP.
• Créer ou enregistrer %ProgramData%\sslTrusKSP\config.dat ; le fichier est chiffré avec Windows DPAPI local.

L’installation modifie l’enregistrement des fournisseurs au niveau système et doit généralement être exécutée dans un terminal administrateur. Si la version de la DLL CSP dans le répertoire système est identique à la version intégrée, l’interface CLI ignore la copie de la DLL CSP, mais exécute tout de même le processus d’enregistrement du fournisseur.

Ajouter une configuration de certificat

Exécutez :

signtool csp add

Si vous devez utiliser l’adresse de service NICSRS :

signtool csp add --address nicsrs

--address n’est pas un paramètre transmis par URL. Actuellement, nicsrs utilise le service NICSRS ; une valeur vide, racent ou toute autre valeur utilise le service par défaut.

Lors de l’ajout, la CLI récupère le certificat depuis le service distant et l’écrit dans :

%ProgramData%\sslTrusKSP\CERT_CODE.crt

Écrivez simultanément l’adresse du service, les informations d’identification, le numéro de certificat et le chemin du certificat dans le fichier de configuration chiffré. CERT_CODE sert à la fois d’identifiant de certificat distant et de valeur de /kc dans le signtool.exe de Microsoft.

Si vous ajoutez un numéro de certificat déjà existant, l’interface CLI vous demandera s’il faut l’écraser : saisissez y pour remplacer l’ancienne configuration ; appuyez directement sur Entrée ou saisissez une autre valeur pour conserver la configuration existante.

Afficher et supprimer la configuration

Afficher la configuration actuelle :

signtool csp list

Le résultat contient le numéro du certificat, le type de service, l’Access Key et l’Access Secret partiellement masqué. Veuillez ne pas téléverser la sortie de commande, les fichiers de configuration ou les journaux vers des emplacements publics.

Supprimer une configuration :

signtool csp del

Suivez l’invite pour saisir le numéro du certificat. Cette opération supprime uniquement l’entrée correspondante dans la configuration de chiffrement, elle ne supprime pas le fichier de certificat .crt du même nom ; veuillez nettoyer manuellement ce fichier lorsqu’il n’est plus utilisé.

Utilisation de la signature Microsoft signtool.exe

Signature SHA-256

signtool.exe sign /v ^
  /csp "sslTrus Cryptographic Service Provider" ^
  /kc CERT_CODE ^
  /f "C:\ProgramData\sslTrusKSP\CERT_CODE.crt" ^
  /fd SHA256 ^
  /tr http://timestamp.acs.microsoft.com ^
  /td SHA256 ^
  ".\app.exe"

Explication des paramètres :

Paramètre	Description
/csp "sslTrus Cryptographic Service Provider"	Spécifie le fournisseur CSP.
/kc CERT_CODE	Spécifie le conteneur de clé correspondant au numéro du certificat.
/f <证书路径>	Spécifie le fichier de certificat téléchargé via csp add.
/fd SHA256	Spécifie l'algorithme de résumé du fichier.
/tr <URL>	Spécifie le service d'horodatage RFC 3161.
/td SHA256	Spécifie l'algorithme de résumé de l'horodatage.

Actuellement, CSP prend en charge les algorithmes de résumé de fichier SHA1, SHA256, SHA384 et SHA512 ; pour les nouvelles signatures, il est généralement recommandé d’utiliser SHA-256 ou une version supérieure. L’adresse d’horodatage doit être déterminée par votre politique de certificat et la compatibilité de la plateforme cible.

Ajouter une signature SHA-1

Lorsqu’une compatibilité avec d’anciens systèmes est réellement requise, vous pouvez ajouter SHA-1 à la signature existante :

signtool.exe sign /v ^
  /csp "sslTrus Cryptographic Service Provider" ^
  /kc CERT_CODE ^
  /f "C:\ProgramData\sslTrusKSP\CERT_CODE.crt" ^
  /fd SHA1 ^
  /tr http://timestamp.acs.microsoft.com ^
  /td SHA256 ^
  /as ^
  ".\app.exe"

/as désigne l'ajout d'une signature pour éviter d'écraser une signature existante. La nécessité d'utiliser SHA-1 doit se conformer au système cible et à la politique de certificat ; il ne doit pas être le choix par défaut pour les nouveaux projets.

Vérifier la signature

Après la signature, vous pouvez utiliser Microsoft signtool.exe pour vérifier :

signtool.exe verify /pa /v ".\app.exe"

Si vous devez vérifier toutes les signatures, sélectionnez les options de vérification correspondantes selon la version et les paramètres du SDK Windows signtool.exe.

Désinstaller le fournisseur

Exécutez la commande suivante dans un terminal administrateur :

signtool csp uninstall

Cette commande désinscrit le CSP, ainsi que l'alias du fournisseur CNG portant le même nom que le CSP, et supprime la copie de la DLL du CSP dans ProgramData ainsi que dans le répertoire système. Elle ne supprime pas l'intégralité du répertoire %ProgramData%\sslTrusKSP et ne retire pas automatiquement l'enregistrement et la DLL du sslTrus Key Storage Provider associé ; si ce KSP est utilisé uniquement par le processus d'installation du CSP, procédez à un nettoyage prudent en fonction de l'état réel du déploiement.

Après la désinstallation, si vous devez supprimer des données sensibles locales, veuillez d'abord confirmer qu'elles ne sont plus utilisées par le KSP ou d'autres flux de signature, puis supprimez manuellement la configuration, les certificats et les journaux dans %ProgramData%\sslTrusKSP.

Questions fréquentes

Symptôme	Suggestion de traitement
cryptographic service provider is only supported on windows	Exécutez la commande de gestion du CSP sous Windows.
Échec d'installation signalant une permission ou une écriture dans le répertoire système	Utilisez un terminal administrateur pour exécuter signtool csp install.
no csp configuration	Exécutez d'abord signtool csp install, puis signtool csp add.
no such certificate code	Utilisez d'abord signtool csp list pour vérifier le numéro du certificat.
Microsoft signtool.exe introuvable Provider	Confirmez que la commande d'installation a réussi, que l'outil actuel et le Provider sont tous deux en x64, puis rouvrez le terminal avant de réessayer.
Fichier de certificat introuvable lors de la signature	Vérifiez que le chemin /f correspond au fichier CERT_CODE.crt téléchargé depuis csp add.
Échec de l'appel de signature	Vérifiez le numéro du certificat, les informations d'identification du service et la connectivité réseau, puis consultez %ProgramData%\sslTrusKSP\sslTrusCSP.log.
L’utilisation d’une adresse de service personnalisée entraîne une requête anormale	Le CSP fixe le chemin /v1/codesign/sign du service de requête ; l’adresse de service configurée ne doit fournir que http(s)://host[:port].

Consignes de sécurité

• L’Access Secret, le config.dat, les fichiers de certificat et les journaux CSP doivent tous être traités comme des informations sensibles.
• Le config.dat est protégé par DPAPI du profil de l’utilisateur Windows courant qui a créé la configuration ; il ne doit pas être directement copié vers un autre utilisateur ou une autre machine pour être réutilisé.
• Le CSP n’enregistre pas la clé privée ; n’essayez pas d’importer la clé privée dans %ProgramData%\sslTrusKSP.
• La signature par le CSP nécessite l’accès au service distant ; un délai réseau, un refus côté serveur ou l’indisponibilité du service d’horodatage peuvent tous entraîner l’échec de la signature.

Pour plus de paramètres CLI et la référence des commandes de signature, consultez la référence de la commande SignTool sign.