Instructions d’utilisation du CSP

Aperçu

Ces instructions expliquent comment configurer sslTrus Cryptographic Service Provider (CSP) sur Windows et utiliser le cloud HSM pour la signature de code via le signtool.exe Microsoft du SDK Windows.

Le signtool csp de ce projet est responsable de l’installation, de la configuration et de la maintenance du fournisseur ; la signature effective est réalisée avec le signtool.exe du SDK Windows. Les deux ne sont pas le même programme.

sslTrus Cryptographic Service Provider est un CSP CryptoAPI traditionnel, adapté aux flux de signature Windows qui doivent passer par /csp et /kc. La clé privée de signature reste toujours conservée dans le cloud HSM ; la machine locale ne stocke que la DLL du CSP, le certificat de signature et la configuration d’accès protégée par DPAPI Windows.

Préparation avant utilisation

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

Confirmez que les deux outils sont chacun utilisables :

REM 本项目 CLI
signtool csp --help

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

Si le répertoire courant ou le PATH contient deux programmes du même nom, assurez-vous d’identifier la cible réelle de l’appel 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 interactivement 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

Une fois la configuration terminée, utilisez le signtool.exe de Microsoft dans le SDK Windows pour signer :

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, dans les exemples, CERT_CODE et app.exe par le numéro réel du certificat et le fichier à signer.

Installation du Provider

Exécutez :

signtool csp install

Cette commande :

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

L'installation modifie l'enregistrement du fournisseur au niveau système, elle doit donc généralement être exécutée dans un terminal administrateur. Si la version de la DLL CSP présente dans le répertoire système correspond à la version intégrée, le CLI ignore la copie de la DLL CSP, mais exécute toujours le processus d'enregistrement du fournisseur.

Ajouter une configuration de certificat

Exécutez :

signtool csp add

Pour utiliser l’adresse du service NICSRS :

signtool csp add --address nicsrs

--address n’est pas un paramètre de transmission d’URL. Actuellement, nicsrs utilisera le service NICSRS ; une valeur vide, racent ou toute autre valeur utilisera 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

Simultanément, écrivez l'adresse du service, les identifiants, le numéro de certificat et le chemin du certificat dans le fichier de configuration chiffré. CERT_CODE est à la fois l'identifiant du certificat distant et la valeur de /kc dans le Microsoft signtool.exe suivant.

Si vous ajoutez un numéro de certificat déjà existant, la CLI demande si vous souhaitez le remplacer : saisissez y pour remplacer l'ancienne configuration ; appuyez directement sur Entrée ou saisissez une autre valeur pour conserver la configuration actuelle.

Affichage et suppression de la configuration

Afficher la configuration actuelle :

signtool csp list

La sortie comprend le numéro du certificat, le type de service, la clé d’accès (Access Key) et le secret d’accès (Access Secret) masqué. Veuillez ne pas téléverser la sortie de commande, les fichiers de configuration ou les journaux vers un emplacement public.

Supprimer une certaine configuration :

signtool csp del

Saisissez simplement le numéro du certificat comme demandé. Cette opération supprime uniquement l’entrée correspondante dans la configuration chiffrée, mais ne supprime pas le fichier de certificat .crt portant le même nom ; veuillez nettoyer manuellement ce fichier lorsque vous n’en avez plus besoin.

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"

Paramètres :

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

Le CSP actuel prend en charge les algorithmes de résumé de fichiers 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 de l’horodatage doit être déterminée par votre politique de certificat et la compatibilité de la plateforme cible.

Ajout d’une signature SHA-1

Lorsqu’il existe effectivement une exigence de compatibilité avec d’anciens systèmes, il est possible d’ajouter une signature SHA-1 sur 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 indique l’ajout d’une signature pour éviter d’écraser une signature existante. Le recours à SHA-1 doit respecter le système cible et la politique de certificats ; il ne doit pas être le choix par défaut pour un nouveau projet.

Vérification de la signature

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

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

Pour vérifier toutes les signatures, vous pouvez sélectionner l’option de validation correspondante en fonction de la version et des paramètres du SDK Windows signtool.exe.

Désinstallation du fournisseur

Exécutez dans un terminal en mode administrateur :

signtool csp uninstall

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

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

Questions fréquentes

Phénomène	Suggestion de traitement
cryptographic service provider is only supported on windows	Exécutez les commandes de gestion CSP sur Windows.
Erreur de permission ou échec d'écriture dans le répertoire système lors de l'installation	Exécutez signtool csp install dans un terminal administrateur.
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.
Provider Microsoft signtool.exe introuvable	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 et réessayez.
Fichier de certificat introuvable lors de la signature	Confirmez que le chemin de /f correspond au csp add téléchargé via CERT_CODE.crt.
Échec de l'appel de signature	Vérifiez le numéro du certificat, les informations d'identification du service et la connectivité réseau ; consultez ensuite %ProgramData%\sslTrusKSP\sslTrusCSP.log.
Utilisation d’une adresse de service personnalisée mais requête anormale	Le CSP fixe le chemin /v1/codesign/sign du service de requête ; l’adresse de service configurée doit uniquement fournir http(s)://host[:port].

Consignes de sécurité

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

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