Outil client
sslTrus fournit un client en ligne de commande et un client de bureau pour se connecter au service de signature de code à distance et effectuer la signature de fichiers.
Parmi eux, SignTool CLI convient aux scénarios de ligne de commande, de script et d'automatisation ; les utilisateurs de macOS peuvent également installer et mettre à jour SignTool CLI ou le client de bureau via Homebrew.
SignTool CLI
SignTool CLI est le client en ligne de commande de signature de code à distance fourni par sslTrus. Le nom de l'exécutable après installation est signtool.
Il offre principalement les fonctionnalités suivantes :
| Fonction | Commande | Description |
|---|---|---|
| Signature de fichier | signtool sign | Effectue une signature de code à distance sur un fichier local |
| Quota de signature | signtool quota | Interroge le quota de signature restant et total du certificat |
| Mise à jour du client | signtool update | Recherche et installe la dernière version du client pour la plateforme actuelle |
| Windows KSP | signtool ksp | Installe et gère le fournisseur de stockage de clés Windows |
| Windows CSP | signtool csp | Installe et gère le fournisseur de services cryptographiques Windows |
KSP et CSP sont des méthodes d'intégration du fournisseur Windows. Pour les instructions d'utilisation spécifiques, veuillez consulter Windows Provider.
Télécharger le client
SignTool CLI peut être téléchargé depuis la page de publication du client sslTrus :
Page de publication du client sslTrus
La page de publication fournit les paquets d’installation client les plus récents pour chaque plateforme. Dans les scénarios d’automatisation, vous pouvez également consulter les informations sur la dernière version actuelle via l’index de versions latest.json.
Les utilisateurs de macOS peuvent aussi installer directement via Homebrew, voir macOS Homebrew ci-dessous.
Consulter les informations sur le client
Une fois l’installation terminée, vous pouvez exécuter :
signtool --help
Afficher l’aide de la commande.
Afficher la version actuelle du client :
signtool --version
Informations de version comprenant la version du client, la révision de build, la plateforme d’exécution et l’heure de build.
Informations d’identification d’accès
Avant d’utiliser le service de signature de code à distance, vous devez préparer :
- Access Key
- Access Secret
- Numéro de certificat (Cert Code)
L’Access Key et l’Access Secret servent à accéder au service de signature de code à distance, et le numéro de certificat sert à désigner le certificat de signature de code utilisé pour la signature proprement dite.
SignTool CLI peut fournir les informations d’identification via des paramètres de commande ou les lire via des variables d’environnement :
export ACCESS_KEY="your-access-key"
export ACCESS_SECRET="your-access-secret"
Il est recommandé de fournir l'Access Secret en priorité via des variables d'environnement, des secrets CI/CD ou d'autres méthodes sécurisées de gestion des identifiants.
Ne pas exposer l'Access Secret :
- Ne le committez pas dans un dépôt Git.
- Ne l'écrivez pas dans des scripts publics.
- Ne l'affichez pas dans les journaux de build.
- Ne l'envoyez pas à des systèmes tiers non fiables.
Adresse du service distant
Par défaut, SignTool CLI utilise l'adresse du service de production sslTrus, aucune configuration supplémentaire n'est requise.
Si vous utilisez l'environnement NICSRS (www.nicsrs.com), vous devez ajouter --address nicsrs à la commande :
signtool sign \
--address nicsrs \
--cert-code CERT_CODE \
--file app.exe
signtool quota et signtool update prennent également en charge --address nicsrs.
Signature de fichiers
L'utilisation de signtool sign permet d'exécuter directement une signature de code à distance sur des fichiers locaux.
Commande de signature la plus élémentaire :
signtool sign \
--cert-code CERT_CODE \
--file app.exe
Si déjà défini :
ACCESS_KEY
ACCESS_SECRET
Le CLI SignTool lit automatiquement les identifiants d’accès correspondants.
Par défaut, la signature est effectuée avec SHA-2.
Spécifier le fichier de sortie
Par défaut, le client ne remplace pas directement le fichier d’origine.
Vous pouvez spécifier le fichier de sortie après la signature via --out :
signtool sign \
--cert-code CERT_CODE \
--file app-unsigned.exe \
--out app-signed.exe
Écraser le fichier d’origine
Si vous devez modifier directement le fichier d’origine, vous pouvez utiliser :
signtool sign \
--cert-code CERT_CODE \
--file app.exe \
--override=true
Une fois --override activé, le résultat de la signature est réécrit directement dans le fichier d’entrée.
Lors d’une utilisation dans un environnement de build automatisé, vérifiez si les étapes suivantes ont besoin du fichier d’origine ou du fichier signé.
Spécifier la description du programme
Vous pouvez inclure la description du programme et l’URL dans la signature Authenticode :
signtool sign \
--cert-code CERT_CODE \
--file app.exe \
--desc "Example Application" \
--url "https://example.com"
SHA-1 et SHA-2
SHA-2 est activé par défaut :
signtool sign \
--cert-code CERT_CODE \
--file app.exe
Utiliser uniquement SHA-1 :
signtool sign \
--cert-code CERT_CODE \
--file app.exe \
--sha1=true \
--sha2=false
Activez simultanément SHA-1 et SHA-2 :
signtool sign \
--cert-code CERT_CODE \
--file app.exe \
--sha1=true \
--sha2=true
SHA-1 est principalement utilisé pour la compatibilité avec les anciens systèmes. Pour les nouveaux projets, il est généralement recommandé de privilégier SHA-2.
Horodatage
Pour la signature de code, il est généralement recommandé d’ajouter un horodatage de confiance.
SignTool CLI configure automatiquement le service d’horodatage par défaut pour la signature, mais il est également possible de spécifier le serveur d’horodatage via des paramètres :
--timestamp-rfc3161: serveur d’horodatage RFC 3161 utilisé pour les signatures SHA-2.--timestamp: serveur d’horodatage Authenticode utilisé pour les signatures SHA-1.
Spécifier un serveur d’horodatage RFC 3161 :
signtool sign \
--cert-code CERT_CODE \
--file app.exe \
--timestamp-rfc3161=http://timestamp.acs.microsoft.com
Spécifiez le serveur d’horodatage Authenticode :
signtool sign \
--cert-code CERT_CODE \
--file app.exe \
--timestamp=http://timestamp.sectigo.com
Si vous devez désactiver l’horodatage correspondant, vous pouvez définir la valeur du paramètre sur vide :
signtool sign \
--cert-code CERT_CODE \
--file app.exe \
--timestamp-rfc3161= \
--timestamp=
Concernant le protocole d’horodatage, l’adresse du serveur et les recommandations de choix, veuillez consulter les documents de référence.
Consulter le quota de signature
Utilisation :
signtool quota
Vous pouvez consulter le quota des certificats de signature de code visibles avec les informations d’identification actuelles.
Le contenu de sortie comprend :
- Numéro du certificat.
- Informations sur le certificat.
- Nombre de signatures restantes.
- Nombre total de signatures.
Si vous avez besoin d’une sortie au format JSON :
signtool quota --json
Vous pouvez également utiliser l’abréviation :
signtool quota -j
Le mode de calcul exact du nombre de signatures peut varier selon la méthode d’appel : CLI, KSP, Jarsigner ou outil de build. Pour les règles détaillées, consultez Explication du calcul du nombre de signatures.
Mise à jour du client
Le CLI SignTool permet de rechercher et d’installer la dernière version pour la plateforme actuelle :
signtool update
Lors de la mise à jour, la taille du fichier téléchargé et le SHA-256 sont vérifiés afin de confirmer l’intégrité du fichier client.
Si SignTool CLI a été installé via Homebrew, il est recommandé de continuer à gérer les versions via Homebrew, plutôt que de mélanger deux méthodes de mise à jour.
macOS Homebrew
Les utilisateurs macOS peuvent installer SignTool CLI ou le client de bureau via le Homebrew Tap officiel de sslTrus.
Installer le Homebrew Tap
Exécutez :
brew tap ssltrus-official/tap
brew trust ssltrus-official/tap
Une fois cette étape terminée, vous pouvez installer le client correspondant.
Installer SignTool CLI
Exécutez :
brew install ssltrus-official/tap/code-sign-cli
Après l'installation, vous pouvez exécuter :
signtool --version
Vérifiez que le client est correctement installé.
Le nom du paquet dans Homebrew est :
code-sign-cli
Le nom réel du programme en ligne de commande installé est :
signtool
Installation du client de bureau
Installez le client de bureau de signature de code sslTrus :
brew install --cask ssltrus-official/tap/code-sign-gui
Le nom du Cask Homebrew correspondant est :
code-sign-gui
Mise à jour du client
Si le client a été installé via Homebrew, il est recommandé d'utiliser Homebrew pour effectuer la mise à niveau.
Commencez par mettre à jour les informations des paquets Homebrew :
brew update
Mettez à niveau l'interface CLI de SignTool :
brew upgrade ssltrus-official/tap/code-sign-cli
Mettre à niveau le client de bureau :
brew upgrade --cask ssltrus-official/tap/code-sign-gui
Cela permet de maintenir la cohérence entre la version installée localement et les métadonnées du paquet Homebrew.
Fournisseur Windows
Si votre scénario ne consiste pas à appeler directement SignTool CLI, mais que vous souhaitez que Microsoft SignTool, Visual Studio, MSBuild, Advanced Installer ou d'autres logiciels Windows utilisent directement la clé privée de signature de code à distance, vous devez utiliser le fournisseur Windows.
sslTrus fournit :
- KSP (Key Storage Provider) : destiné à Windows CNG.
- CSP (Cryptographic Service Provider) : destiné à l'API CryptoAPI Windows traditionnelle.
Veuillez consulter Fournisseur Windows.
Signature automatique CI/CD
S'il est nécessaire d'effectuer la signature au cours du processus d'intégration continue ou de build automatisé, il n'est pas indispensable d'installer et d'appeler manuellement SignTool CLI.
Par exemple, GitHub Actions peut directement utiliser sslTrus Code Sign Action :
- name: Sign files
uses: ssltrus-official/code-sign-action@v1
with:
access-key: ${{ secrets.SSLTRUS_ACCESS_KEY }}
access-secret: ${{ secrets.SSLTRUS_ACCESS_SECRET }}
cert-code: ${{ secrets.SSLTRUS_CERT_CODE }}
files: build/app.exe
GitHub Action prend en charge les runners Linux, macOS et Windows, et peut effectuer directement la signature de code à distance sur des fichiers spécifiés dans le processus de build.
Pour la configuration complète, veuillez consulter CI/CD et outils de build.
Comment choisir
Vous pouvez choisir le client ou la méthode d’intégration approprié selon votre mode d’utilisation réel :
| Scénario | Méthode recommandée |
|---|---|
| Signer manuellement des fichiers dans le terminal | SignTool CLI |
| Appeler la signature par lots à l’aide de scripts | SignTool CLI |
| Consulter le quota de signature de code | SignTool CLI |
| Installer et mettre à jour la CLI sur macOS | Homebrew |
| Utiliser le client de bureau sur macOS | Homebrew |
| Logiciels Windows tels que Microsoft SignTool appelant directement une clé privée distante | KSP |
| Logiciels CryptoAPI traditionnels | CSP |
| Signature automatique avec GitHub Actions | GitHub Actions |
| Développer soi-même un client de signature | API de signature de code à distance |
Si votre application prend déjà en charge KSP Windows, CSP ou d’autres fournisseurs standard, il est généralement préférable d’utiliser d’abord la méthode d’intégration standard correspondante ; si vous devez contrôler directement le processus de signature, vous pouvez utiliser SignTool CLI ou l’API de signature de code à distance.