Outils 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 ceux-ci, 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 du fichier exécutable après installation est signtool.

Il offre principalement les capacités suivantes :

Fonction	Commande	Description
Signature de fichier	signtool sign	Effectue une signature de code à distance sur les fichiers locaux
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 Windows Key Storage Provider
Windows CSP	signtool csp	Installe et gère le Windows Cryptographic Service Provider

KSP et CSP relèvent du mode d'intégration Windows Provider. Pour plus de détails, consultez Windows Provider.

Téléchargement du client

SignTool CLI peut être téléchargé à partir de la page de publication du client sslTrus :

Page de publication du client sslTrus

La page de publication fournit les derniers packages d’installation client pour chaque plateforme. Les scénarios automatisés peuvent également consulter les informations de version actuelles via l’index de versions latest.json.

Les utilisateurs macOS peuvent également installer directement via Homebrew, voir macOS Homebrew ci-dessous.

Afficher les informations du client

Après l’installation, vous pouvez exécuter :

signtool --help

Afficher l’aide de la commande.

Vérifier la version actuelle du client :

signtool --version

Les informations de version comprennent la version du client, la révision de build, la plateforme d'exécution et l'heure de build.

Informations d'accès

Avant d'utiliser le service de signature de code à distance, vous devez préparer :

• Access Key
• Access Secret
• Cert Code

L'Access Key et l'Access Secret servent à accéder au service de signature de code à distance, tandis que le Cert Code sert à spécifier le certificat de signature de code qui exécutera réellement la signature.

Le CLI SignTool peut fournir les informations d'identification via des paramètres de commande ou les lire à partir de variables d'environnement :

export ACCESS_KEY="your-access-key"
export ACCESS_SECRET="your-access-secret"

Il est recommandé de fournir l’Access Secret de préférence via des variables d’environnement, des secrets CI/CD ou d’autres méthodes sécurisées de gestion des informations d’identification.

Ne pas faire ce qui suit avec l’Access Secret :

• Le commettre dans un dépôt Git.
• L’écrire dans des scripts publics.
• L’afficher dans les journaux de construction.
• L’envoyer à des systèmes tiers non fiables.

Adresse du service distant

Par défaut, l’interface CLI SignTool utilise l’adresse du service de production sslTrus, sans configuration supplémentaire.

Si vous utilisez l’environnement NICSRS (www.nicsrs.com), vous devez ajouter --address nicsrs dans 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 fichier

L’utilisation de signtool sign permet d’exécuter directement une signature de code à distance sur un fichier local.

La commande de signature la plus élémentaire :

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe

Si cela a déjà été configuré :

ACCESS_KEY
ACCESS_SECRET

SignTool CLI lira automatiquement les identifiants d’accès correspondants.

La signature est effectuée par défaut avec SHA-2.

Spécifier le fichier de sortie

Par défaut, le client ne remplace pas directement le fichier d’origine.

Il est possible de spécifier le fichier de sortie signé via --out :

signtool sign \
  --cert-code CERT_CODE \
  --file app-unsigned.exe \
  --out app-signed.exe

Écraser le fichier d'origine

Pour modifier directement le fichier d'origine, vous pouvez utiliser :

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --override=true

Activez --override et le résultat de la signature sera directement réécrit dans le fichier d’entrée.

Lors de son utilisation dans un environnement de build automatisé, confirmez si les étapes suivantes nécessitent le fichier d’origine ou le fichier signé.

Spécification de la description du programme

Vous pouvez écrire la description du programme et son 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

Uniquement avec SHA-1 :

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --sha1=true \
  --sha2=false

Activer simultanément SHA-1 et SHA-2 :

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --sha1=true \
  --sha2=true

SHA-1 sert principalement à 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 conseillé d'ajouter également un horodatage fiable.

L'interface CLI de SignTool configure automatiquement un service d'horodatage pour la signature par défaut. Vous pouvez également spécifier un serveur d'horodatage via un paramètre :

• --timestamp-rfc3161 : serveur d'horodatage RFC 3161 utilisé pour la signature SHA-2.
• --timestamp : serveur d'horodatage Authenticode utilisé pour la signature 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 souhaitez 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=

Pour les informations concernant le protocole de timestamp, l'adresse du serveur et les recommandations de sélection, veuillez consulter les Références.

Vérifier le quota de signature

Utilisation :

signtool quota

Vous pouvez consulter le quota des certificats de signature de code visibles par les informations d’identification d’accès actuelles.

La sortie comprend :

• Le numéro du certificat.
• Les informations sur le certificat.
• Le nombre de signatures restantes.
• Le nombre total de signatures.

Si une sortie au format JSON est nécessaire :

signtool quota --json

Vous pouvez également utiliser l'abréviation :

signtool quota -j

Le mode de calcul précis du nombre de signatures peut varier selon la méthode d’appel du CLI, de KSP, de Jarsigner ou de l’outil de construction. Pour les règles détaillées, veuillez consulter la Description du calcul du nombre de signatures.

Mise à jour du client

SignTool CLI prend en charge la consultation et l’installation de la dernière version de la plateforme actuelle :

signtool update

Pendant la mise à jour, la taille du fichier téléchargé et le SHA-256 sont vérifiés pour 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 de macOS peuvent installer SignTool CLI ou le client de bureau via le Tap Homebrew officiel sslTrus.

Dépôt public : ssltrus-official/homebrew-tap

Installation du Tap Homebrew

Exécutez :

brew tap ssltrus-official/tap
brew trust ssltrus-official/tap

Une fois terminé, vous pouvez installer le client correspondant.

Installation de 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 Homebrew Cask correspondant est le suivant :

code-sign-gui

Mise à jour du client

Si le client est installé via Homebrew, il est recommandé de procéder à la mise à jour avec Homebrew.

Commencez par mettre à jour les informations des paquets Homebrew :

brew update

Mise à niveau de SignTool CLI :

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 d’installation locale et les métadonnées des paquets Homebrew.

Windows Provider

Si votre scénario ne consiste pas à appeler directement l’interface CLI SignTool, 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 Windows Provider.

sslTrus propose :

• KSP (Key Storage Provider) : destiné à Windows CNG.
• CSP (Cryptographic Service Provider) : destiné à l’ancienne Windows CryptoAPI.

Consultez Windows Provider.

Signature automatique CI/CD

Si vous devez effectuer une signature lors d’une intégration continue ou d’un processus de build automatisé, il n’est pas nécessaire d’installer manuellement et d’appeler l’interface CLI SignTool.

Par exemple, GitHub Actions peut utiliser directement l’action 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

L'action GitHub prend en charge les runners Linux, macOS et Windows, et peut effectuer directement la signature de code à distance sur des fichiers spécifiés pendant le processus de construction.

Dépôt public : ssltrus-official/code-sign-action

Pour la configuration complète, veuillez consulter CI/CD et outils de construction.

Comment choisir

Vous pouvez choisir le client ou la méthode d’intégration adapté en fonction de votre mode d’utilisation réel :

Scénario	Méthode recommandée
Signature manuelle de fichiers dans le terminal	SignTool CLI
Appels de signature par lots via des scripts	SignTool CLI
Consultation du quota de signature de code	SignTool CLI
Installation et mise à jour du CLI sur macOS	Homebrew
Utilisation du client de bureau sur macOS	Homebrew
Appel direct de la clé privée à distance par des logiciels Windows tels que Microsoft SignTool	KSP
Logiciels traditionnels CryptoAPI	CSP
Signature automatique via GitHub Actions	GitHub Actions
Développement de votre propre client de signature	API de signature de code à distance

Si votre application prend déjà en charge Windows KSP, CSP ou d’autres fournisseurs standard, vous devriez généralement privilégier la méthode d’intégration standard correspondante ; si vous avez besoin de contrôler directement le processus de signature, vous pouvez utiliser SignTool CLI ou l’API de signature de code à distance.