Signer avec KeyLocker cloud HSM
Ce guide décrit comment signer avec un certificat Code Signing stocké dans Keylocker cloud HSM. Keylocker prend en charge toutes les plateformes et les outils de signature, comme signtool, jarsigner etc. Ce guide peut vous aider également avec Software Trust Manager de DigiCert ONE, le principe est similaire.
Compatibilité du KeyLocker
Fonctionnera ce modèle dans le workflow de mon organisation ? Keylocker (et Software Trust Managet via DC1) et ses bibliothèques prennent en charge les outils de signature tiers. Pour vérifier les formats du fichier et les outils compatibles, consultez l'article de DigiCert Signing tool integration.
Un exemple pour Signtool en version 32b et 64b :
- SignTool (32-bit): .doc, .docm, .dot, .dotm, .msi, .cab, .exe, .dll, .mpp, .mpt, .pot, .potm, .ppa, .ppam, .pps, .ppsm, .ppt, .pptm, .pub, .vdw*, .vdx*, .vsd*, .vsdm, .vss*, .vssm, .vst*, .vstm, .vsx*, .vtx*, .wiz*, .xla, .xlam, .xls, .xlsb, .xlsm, .xlt, .xltm
- SignTool (64-bit): .appx, .appxbundle, .arx, .cab, .cat, .cbx, .cpl, .crx, .dbx, .deploy, .dll, .drx, .efi, .exe, .js, .msi, .msix, .msixbundle, .msm, .msp, .ocx, .psi, .psm1, .stl, .sys, .vbs, .vsix, .wsf, .xsn
Configuration du KeyLocker
L'assistant de configuration vous aidera à créer votre authentification.
Enregistrez soigneusement les données d'authentification, vous en aurez besoin pour les signatures. Stockez le certificat d'authentification sur l'ordinateur sur lequel vous allez signer. Le mot de passe de ce certificat (PFX) va être enregistré dans les variables du système et vous pouvez le saisir dans l'assistant.
Configuration de l'environnement de signature
Définissez les variables et l'authentification dans votre système. Soit manuellement dans les paramètres système, soit avec le guide de DigiCert (fait partie de l'application Click-to-sign - voir le dernier paragraphe). Le fichier d'installation Click-to-sign se trouve dans le même dossier comme smctl (Signing Manager Controller), typiquement dans C:/Program Files/DigiCert/DigiCert Keylocker Tools/
Définissez les données suivantes dans les variables système (manuellement ou à l'aide de l'assistant) :
- Host - URL de votre connexion (https://clientauth.one.digicert.com)
- API key - votre API token de KeyLocker
- Client authentication certificate - votre certificat d'authentification et son mot de passe
- Client authentication certificate password - mot de passe du certificat ci-dessus
- Pkcs11 configuration file - facultatif pour signtool ; fichier de configuration pour la bibliothèque PKCS11 utilisé par smctl, jarsigner et autres. Comment le créer, voir ici.
Pour savoir comment définir les variables dans Windows, consultez cette vidéo.
La configuration peut être vérifiée dans l'assistant : "Credentials saved" ou avec Signing Manager Controller (SMCTL), commande : smctl healthcheck
Cette commande vérifie l'authentification, la connexion à Keylocker, mais vérifie également si au moins un outil de signature est accessible. Si tel est le cas, l'outil affichera : Mapped : Yes et le chemin d'accès.
Si vous ne voyez pas signtool dans le résultat du test (Signtool: Mapped: No), Signtool n'est pas installé ou son chemin d'accès n'est pas défini dans les variables du système (voir la configuration : Set PATH environment variable). En cas de besoin, consultez l'article d'aide Healthcheck commands dans la documentation Digicert.
Nous recommandons de configurer les variables dans le système de manière permanente. Sur un système Windows, utilisez Windows Credential Manager sécurisé (les variables sont accessibles à toute personne ayant accès à l'ordinateur). Si vous utiliserez la ligne de commande, vous allez devoir répéter cette opération à chaque session. Pour en savoir plus, consultez la documentation : Session-based environment variables.
Synchronisation du certificat
Une fois la configuration de la connexion à Keylock réussie, vous devez synchroniser les certificats avec votre système.
C:/Program Files/DigiCert/DigiCert Keylocker Tools>smctl windows certsync --keypair-alias=key_558469087
Syncing certificate for alias: key_558469087, ID: 2a47112c-4b5d-4ce0-8e70-d67437e58135 and SHA1 Fingerprint: ecb0f10ab1XXXXXXXXXX1681fb70a31e32288263
Vous pouvez également utiliser l'utilitaire smksp_cert_sync :
C:/>smksp_cert_sync
Syncing certificate for alias: key_558469087, ID: 2a47112c-4b5d-4ce0-8e70-d67437e58135
Maintenant, la partie publique du certificat est stockée localement dans le magasin de certificats Windows, et la clé privée reste dans le stockage cloud.
Signer des fichiers
Digicert Cloud prend en charge plusieurs outils de signature pour signer avec les certificats Code Signing.
À l'exception de DigiCert® Click-to-sign (voir la dernière paragraphe), les logiciels utilisent la ligne de commande (CLI).
Signer des fichiers avec SMCTL (recommandé)
Développé par Digicert, Signing Manager Controller (SMCTL) permet de signer numériquement des fichiers à l'aide d'outils tiers (vous avez toujours besoin de Signtool). SMCTL prend en charge des outils : Signtool, Apsigner, Jarsigner, Mage, Nuget. L'outil se trouve dans le dossier C:/Program Files/DigiCert/DigiCert Keylocker Tools/smctl.exe
Pour sélectionner le certificat, vous pouvez utiliser soit key alias (recommandé - il se trouve dans Keylocker) ou un hash (SHA-1) du certificat.
smctl sign --keypair-alias=key_558469087 -d=SHA256 --verbose --config-file "C:/Program Files/DigiCert/DigiCert Keylocker Tools/pkcs11properties.cfg" --input "C:/Users/User/HelloSign.exe"
smctl sign --fingerprint <certificate fingerprint> --input <path to unsigned file or folder>
Pour vérifier la validité de la signature, utilisez la commande suivante :
smctl sign verify --input <path to signed file or folder>
Retrouvez l'ensemble de la documentation de SMCTL sur le site web de Digicert.
Signer des fichier avec Signtool
Signtool est un outil du Windows SDK et l'outil de signature le plus utilisé sur la plateforme Windows.
Dans la commande Signtool, il est nécessaire de spécifier le fichier que vous souhaitez signer, avec quel certificat et éventuellement les paramètres associés. Pour se référer au certificat de signature, vous pouvez laisser Signtool choisir un certificat automatiquement (depuis un stockage) ou vous pouvez sélectionner le fichier contenant le certificat (bien sur, uniquement la partie publique sans clé privée) ou utiliser le hash du certificat souhaité.
Voici un exemple de signature avec un hash du certificat :
C:/>signtool.exe sign /sha1 ecb0f10ab1XXXXXXXXXX1681fb70a31e32288263 /tr http://timestamp.digicert.com /td SHA256 /fd SHA256 C:/Users/User/Documents/HelloSign.exe
Voici un exemple de signature avec KeyLocker et un fichier du certificat :
C:/Users/User>signtool.exe sign /csp "DigiCert Signing Manager KSP" /kc key_558469087 /f C:/Users/User/Documents/cert_558469087.crt /tr http://timestamp.digicert.com /td SHA256 /fd SHA256 C:/Users/User/Documents/HelloSign.exe
Done Adding Additional Store
Successfully signed: C:/Users/User/Documents/HelloSign.exe
Pour vérifier la validité de la signature, utilisez la commande : signtool verify /v file.exe Vous pouvez également utiliser Explorateur Windows et avec bouton droit de la souris, sélectionnez Propriétés de la signature.
Signer des fichiers avec Jarsigner
Jarsigner est un outil qui vous permet de signer et de vérifier les fichiers .jar. Jarsigner utilise un fichier de configuration pour s'intégrer à la bibliothèque DigiCert® KeyLocker PKCS11. Vous pouvez signer tout simplement à l'aide de SMCTL ou avec Jarsigner et la bibliothèque PKCS11.
Exemple de signature avec Jarsigner :
jarsigner -keystore NONE -storepass NONE -storetype PKCS11 -sigalg SHA256withRSA -providerClass sun.security.pkcs11.SunPKCS11 -providerArg pkcs11properties2.cfg -signedjar C:/Users/Name/Desktop/signed/signedjar.jar C:/Users/Name/Desktop/ToSign/jartosign.jar key3 -tsa "http://timestamp.digicert.com"
Pour vérifier la validité de la signature, utilisez la commande :
jarsigner -verify <path to signed jar file> -certs -verbose
Retrouvez l'ensemble de la documentation de Jarsigner sur le site web de Digicert.
Signer des fichiers avec DigiCert® Click-to-sign
DigiCert® Click-to-sign est un interface utilisateur qui ne nécessite pas l'utilisation de la ligne de commande. Cet outil permet aux clients de signer des fichiers de manière simple. Ce principe donne le même résultat comme les outils utilisant la ligne de commande, seulement ils offrent les paramètres plus détaillés. DigiCert® Click-to-sign est une solution simplifiée et suffisante pour la plupart des utilisateurs.
L'un des gros avantages de DigiCert® Click-to-sign est la configuration simple. Vous passez par l'assistant de Configuration pour configurer les paramètres des droits d'accès au KeyLocker. L'assistant va tester votre connexion au cloud, mais surtout paramétrer les variables au système ! Vous ne devez rien à configurer manuellement.
Signer avec cet outil, c'est vraiment très simple. Faites un clic droit sur le fichier à signer et sélectionnez Click to Sign. Ensuite, vous pouvez signer directement ou avec une confirmation des paramètres de signature.
Retrouvez l'ensemble de la documentation de Click-to-sign sur le site web de Digicert.
Remarque : Si Click-to-sign ne fonctionne pas : définissez l'emplacement du Click-to-sign et de l'application de signature (signtool) dans les variables PATH. Séparez-les par les points-virgules. Par exemple :
Path: C:/Program Files/DigiCert/DigiCert Keylocker Tools;C:/Program Files (x86)/Windows Kits/10/bin/10.0.22621.0x64;
Integrations CI/CD
Le principal avantage du Keylocker est de pouvoir automatiser les signatures et d'intégrer le processus dans le workflow CI/CD. DigiCert a préparé certains scripts et plugins pour les outils et plateformes de développement les plus utilisés. Les plugins sont disponibles pour Azure DevOps, GitHub et Jenkins. Il propose encore plus de scripts d'intégration pour la bibliothèque PKCS11.
Retrouvez l'ensemble de la documentation dans l'article CI/CD integrations.
