CI/CD et outils de build

Le service de signature de code à distance sslTrus peut être intégré aux flux CI/CD, à la génération d’applications et à la création de packages d’installation, afin d’exécuter automatiquement la signature du code sur les artefacts de publication après la compilation ou l’empaquetage.

Les scénarios d’intégration typiques actuellement pris en charge incluent :

GitHub Actions
Electron Builder
Advanced Installer

Selon les capacités de l’outil de construction, vous pouvez utiliser directement l’action GitHub sslTrus, appeler l’interface CLI de SignTool, ou passer par l’interface de signature personnalisée fournie par l’outil de construction pour réaliser l’intégration.

GitHub Actions

sslTrus fournit une action GitHub officielle :

ssltrus-official/code-sign-action

La source et les notes de version sont disponibles dans ssltrus-official/code-sign-action. L’utilisation stable actuelle repose sur le tag de version principale @v1.

Vous pouvez effectuer une signature de code à distance directement sur les artefacts de build dans un workflow GitHub Actions.

L’action appelle le service de signature de code à distance sslTrus pour réaliser la signature et met directement à jour les fichiers spécifiés, compatible avec les runners Linux, macOS et Windows.

Préparation des secrets GitHub

Il est recommandé de stocker les identifiants de signature de code à distance dans les secrets GitHub Actions :

SSLTRUS_ACCESS_KEY
SSLTRUS_ACCESS_SECRET
SSLTRUS_CERT_CODE

Ne pas écrire directement l’Access Secret dans le fichier Workflow.

Configuration de base

- 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

Après une signature réussie, build/app.exe sera directement remplacé par le fichier signé.

Signature de plusieurs fichiers

files prend en charge la configuration de plusieurs fichiers sur plusieurs lignes :

- 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
      build/library.dll
      build/installer.msi

Vous pouvez également utiliser des chemins de fichiers séparés par des virgules.

Les chemins de fichiers en double ne seront traités qu’une seule fois.

Configuration complète

- 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
      build/library.dll
      build/installer.msi
    dry-run: false
    timestamp-rfc3161: http://timestamp.acs.microsoft.com
    description: Example Application
    description-url: https://example.com

Paramètres principaux :

Paramètre	Requis	Valeur par défaut	Description
`access-key`	Oui	-	Clé d'accès sslTrus
`access-secret`	Oui	-	Secret d'accès sslTrus
`cert-code`	Oui	-	Numéro du certificat de signature de code
`files`	Oui	-	Chemin du fichier à signer
`nicsrs`	Non	`false`	Utilisation du service NICSRS
`dry-run`	Non	`false`	Utilisation d'un certificat de test local pour effectuer une signature de test
`timestamp-rfc3161`	Non	`auto`	Serveur d’horodatage RFC 3161 ; laissez vide pour désactiver l’horodatage
`description`	Non	-	Description du programme inscrite dans la signature Authenticode
`description-url`	Non	-	URL du programme inscrite dans la signature Authenticode

Exemple complet de Workflow

Voici un exemple de compilation, de signature et de téléversement des artefacts de build sur un Runner Windows :

name: Build and Sign

on:
  workflow_dispatch:

permissions:
  contents: read

jobs:
  build:
    runs-on: windows-latest

    steps:
      - name: Check out repository
        uses: actions/checkout@v7

      - name: Build
        run: |
          # 在这里执行实际构建命令

      - 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
            build/library.dll
          timestamp-rfc3161: http://timestamp.acs.microsoft.com

      - name: Upload signed files
        uses: actions/upload-artifact@v7
        with:
          name: signed-files
          path: |
            build/app.exe
            build/library.dll

Suggestion de placer l’étape de signature à :

Compilation → Empaquetage → Signature du code → Publication

Avant l’étape de publication dans le processus.

Runner multi-plateforme

GitHub Action peut être appelé depuis différents Runner :

strategy:
  matrix:
    os:
      - ubuntu-latest
      - macos-latest
      - windows-latest

runs-on: ${{ matrix.os }}

Ainsi, même si la tâche de construction s’exécute sur Linux ou macOS, il est possible d’utiliser la même Action pour effectuer la signature à distance des fichiers pris en charge.

Exécution à blanc

Si vous souhaitez vérifier le Workflow et la logique de traitement des fichiers, vous pouvez activer :

dry-run: true

Ce mode utilise des certificats de test locaux et n'appelle pas le service de signature de code à distance.

Par exemple :

- name: Test signing
  uses: ssltrus-official/code-sign-action@v1
  with:
    access-key: dummy
    access-secret: dummy
    cert-code: dummy
    files: build/app.exe
    dry-run: true

dry-run modifiera toujours le fichier cible, il ne faut donc pas l'interpréter comme un mode aperçu qui ne modifie aucunement le fichier.

Electron Builder

Electron Builder peut appeler l'interface en ligne de commande sslTrus SignTool via une fonction de signature personnalisée, afin de signer automatiquement les exécutables Windows et les paquets d'installation pendant le processus de construction de l'application Electron.

Flux typique :

Electron Builder
      ↓
customSign
      ↓
SignTool CLI
      ↓
sslTrus 远程代码签名服务
      ↓
云端 HSM

Conditions préalables

Avant de commencer, assurez-vous de disposer de :

Un service de signature de code à distance sslTrus déjà disponible.
D'une Access Key et d'un Access Secret.
D'un numéro de certificat de signature de code.
Le projet Electron est construit avec electron-builder.
L'environnement de construction est capable d'exécuter sslTrus SignTool CLI, téléchargeable depuis la page de publication du client sslTrus.

Configuration des identifiants

Vous pouvez transmettre les identifiants au script de construction via des variables d'environnement :

Linux et macOS :

export SIGNTOOL_ACCESS_KEY="YOUR_ACCESS_KEY"
export SIGNTOOL_ACCESS_SECRET="YOUR_ACCESS_SECRET"
export SIGNTOOL_CERT_CODE="YOUR_CERT_CODE"

Windows PowerShell :

$env:SIGNTOOL_ACCESS_KEY = "YOUR_ACCESS_KEY"
$env:SIGNTOOL_ACCESS_SECRET = "YOUR_ACCESS_SECRET"
$env:SIGNTOOL_CERT_CODE = "YOUR_CERT_CODE"

Ces variables sont lues par le script de signature personnalisé d'Electron, puis transmises à l'interface en ligne de commande (CLI) de SignTool.

Configuration d'Electron Builder

Dans :

electron-builder.mjs

Ou bien, dans le fichier de configuration Electron Builder réellement utilisé par le projet, définissez une fonction de signature personnalisée pour Windows :

export default {
  win: {
    target: [
      {
        target: 'nsis',
        arch: ['x64'],
      },
    ],
    sign: customSign,
    signingHashAlgorithms: ['sha256'],
  },
};

win.sign est le point d'entrée de signature personnalisé officiellement fourni par Electron Builder. Pour plus de détails, veuillez consulter la documentation de signature de code Windows d'Electron Builder.

customSign

Responsable de l'appel de l'interface CLI de sslTrus SignTool.

Fonction de signature personnalisée

Exemple :

import { execFileSync } from 'node:child_process';

async function customSign(configuration) {
  const {
    SIGNTOOL_ACCESS_KEY,
    SIGNTOOL_ACCESS_SECRET,
    SIGNTOOL_CERT_CODE,
  } = process.env;

  if (
    !SIGNTOOL_ACCESS_KEY ||
    !SIGNTOOL_ACCESS_SECRET ||
    !SIGNTOOL_CERT_CODE
  ) {
    throw new Error('Missing sslTrus signing credentials');
  }

  execFileSync(
    './signtool',
    [
      'sign',
      '--access-key',
      SIGNTOOL_ACCESS_KEY,
      '--access-secret',
      SIGNTOOL_ACCESS_SECRET,
      '--cert-code',
      SIGNTOOL_CERT_CODE,
      '--file',
      configuration.path,
      '--override=true',
      '--sha1=false',
      '--sha2=true',
      '--timestamp-rfc3161=http://timestamp.acs.microsoft.com',
    ],
    {
      stdio: 'inherit',
    },
  );
}

Il est recommandé d’utiliser un tableau de paramètres pour appeler le sous-processus, plutôt que de concaténer une commande Shell complète, afin de réduire les problèmes d’échappement de chemins et de traitement des caractères spéciaux.

Electron Builder appelle la fonction de signature une fois pour chaque algorithme de hachage dans signingHashAlgorithms. L’exemple ci-dessus n’active que SHA-256, donc un appel est effectué pour chaque fichier.

Exécution du build

Une fois la configuration terminée, exécutez normalement Electron Builder :

npx electron-builder build \
  --config electron-builder.mjs \
  --win \
  --x64

Electron Builder appelle automatiquement customSign lorsqu'il doit signer un fichier.

Une seule compilation Electron peut signer plusieurs fichiers, par exemple :

MyApp.exe
helper.dll
update.exe
uninstall.exe
MyApp Setup.exe

Il ne faut donc pas supposer qu'un seul empaquetage Electron ne génère qu'une seule opération de signature.

Le nombre réel de signatures dépend du nombre de fichiers signés à distance pendant la compilation.

Advanced Installer

Advanced Installer est un outil de création de packages d'installation fondé sur la technologie Windows Installer.

La fonction d'outil de signature personnalisé d'Advanced Installer peut appeler sslTrus SignTool CLI afin de signer automatiquement à distance les artefacts MSI, EXE, CAB et autres pendant l'empaquetage.

Prérequis

Préparez les éléments suivants :

sslTrus SignTool CLI, téléchargeable depuis la page de publication du client sslTrus.
Access Key。
Access Secret。
Le numéro du certificat.
Un projet Advanced Installer déjà configuré.

Configurer un outil de signature personnalisé

Dans le projet Advanced Installer, ouvrez la page de configuration :

Digital Signature

Après avoir activé la signature de code, sélectionnez comme outil de signature :

Custom

Le chemin de l’outil de signature est défini sur le fichier exécutable sslTrus SignTool CLI.

Par exemple :

C:\Tools\sslTrus\signtool.exe

Les paramètres personnalisés nécessitent un appel :

sign

Sous-commandes, et transmettez au client :

Access Key
Access Secret
Cert Code
Paramètres de signature SHA-2
Serveur d’horodatage
Chemin du fichier

Il est recommandé de fournir de préférence l’Access Key et l’Access Secret de manière sécurisée, afin d’éviter de conserver l’Access Secret à long terme en clair dans des fichiers de projet accessibles publiquement.

Exemple de paramètres SignTool

La logique de signature correspondante est similaire à :

signtool.exe sign ^
  --access-key="YOUR_ACCESS_KEY" ^
  --access-secret="YOUR_ACCESS_SECRET" ^
  --cert-code="YOUR_CERT_CODE" ^
  --nest=true ^
  --sha1=false ^
  --sha2=true ^
  --timestamp-rfc3161=http://timestamp.acs.microsoft.com ^
  --desc="Example Application" ^
  --override=true ^
  --file "app.exe"

Dans Advanced Installer, le chemin de fichier réel doit être transmis par son mécanisme d’outil de signature personnalisé, ne le fixez pas à l’exemple app.exe.

Configuration de la build

Si vous utilisez Advanced Installer pour signer automatiquement les fichiers internes du package d’installation, vous devez vérifier à la fois la méthode de build et la méthode de compression.

Selon la configuration réelle du projet, certains modes d’archivage CAB peuvent affecter le processus de signature personnalisé ; confirmez que le fichier final à signer peut être appelé à l’étape correspondante.

Une fois la configuration terminée, vous pouvez vérifier sur la page de signature numérique d’Advanced Installer :

Files configured for signing

Cela permet ainsi de confirmer quels fichiers seront signés au cours du processus de construction.

Nombre de signatures

Advanced Installer peut signer plusieurs fichiers séparément au cours d'une même construction de package d'installation.

Par exemple :

Fichier	Signature
`app.exe`	1 fois
`helper.dll`	1 fois
`uninstall.exe`	1 fois
`installer.msi`	1 fois
Total	4 fois

Par conséquent :

一次构建 ≠ 一次签名

Le calcul doit être fondé sur le nombre de fichiers réellement signés à distance ou d'opérations de signature effectuées.

Signature Times

Les outils de CI/CD et de compilation traitent généralement plusieurs artefacts automatiquement ; il convient donc de prêter une attention particulière au nombre de signatures.

Principes de base :

签名次数 = 实际成功完成的签名动作数量

Par exemple :

app.exe        → 1 次
library.dll    → 1 次
installer.msi  → 1 次

Si les trois fichiers sont tous signés avec succès :

合计 = 3 次

Les outils de génération tels qu’Electron Builder et Advanced Installer peuvent également générer et signer automatiquement :

Le programme principal.
Les DLL.
Le programme de mise à jour.
Le programme de désinstallation.
Les fichiers MSI.
Les packages d’installation EXE.
D’autres fichiers exécutables auxiliaires.

Par conséquent, le nombre de signatures doit être confirmé en fonction du journal de génération et des artefacts signés réels, et non estimé selon le nombre d’exécutions du Pipeline ou du Build.

Pour plus de règles, veuillez consulter Documentation de référence.

Horodatage

Pour les logiciels publiés officiellement, il est généralement recommandé d’ajouter un horodatage de confiance.

GitHub Actions, Electron Builder et Advanced Installer prennent tous en charge l’horodatage RFC 3161, par exemple :

http://timestamp.acs.microsoft.com

Le timestamp n’est pas considéré comme une nouvelle opération de signature de code et n’augmente pas séparément le nombre de signatures de code.

Pour les supports de protocole et les limites d’utilisation des différentes TSA, veuillez consulter Références.

Sécurité des identifiants

Dans un environnement automatisé, une attention particulière doit être portée à la protection des éléments suivants :

Access Key
Access Secret
Cert Code

Où Access Secret doit être géré comme un Secret, et ne doit pas :

être commité dans un dépôt Git.
être écrit en clair dans un Workflow public.
être affiché dans les journaux de build.
être écrit dans une image Docker publique.
être transmis à un système de build tiers par un moyen non sécurisé.

GitHub Actions recommande d’utiliser :

GitHub Actions Secrets

Les autres systèmes CI/CD doivent utiliser leurs mécanismes correspondants de Secret, Credential ou Variable pour la gestion.

Comment choisir

Scénario	Méthode recommandée
Workflow GitHub Actions	GitHub Actions
Compilation d’applications Electron	Electron Builder
Création de packages d’installation MSI / EXE	Advanced Installer
Automatisation Shell / PowerShell ordinaire	SignTool CLI
Prise en charge native de KSP par les logiciels Windows	Windows Provider
Développement de votre propre processus de signature	Intégration API

Si le système de compilation peut appeler directement des programmes en ligne de commande, vous pouvez utiliser SignTool CLI ; si l’outil fournit déjà une interface standard Windows KSP/CSP, privilégiez l’intégration avec le fournisseur Windows correspondant.

GitHub Actions​

Préparation des secrets GitHub​

Configuration de base​

Signature de plusieurs fichiers​

Configuration complète​

Exemple complet de Workflow​

Runner multi-plateforme​

Exécution à blanc​

Electron Builder​

Conditions préalables​

Configuration des identifiants​

Configuration d'Electron Builder​

Fonction de signature personnalisée​

Exécution du build​

Advanced Installer​

Prérequis​

Configurer un outil de signature personnalisé​

Exemple de paramètres SignTool​

Configuration de la build​

Nombre de signatures​

Signature Times​

Horodatage​

Sécurité des identifiants​

Comment choisir​

GitHub Actions

Préparation des secrets GitHub

Configuration de base

Signature de plusieurs fichiers

Configuration complète

Exemple complet de Workflow

Runner multi-plateforme

Exécution à blanc

Electron Builder

Conditions préalables

Configuration des identifiants

Configuration d'Electron Builder

Fonction de signature personnalisée

Exécution du build

Advanced Installer

Prérequis

Configurer un outil de signature personnalisé

Exemple de paramètres SignTool

Configuration de la build

Nombre de signatures

Signature Times

Horodatage

Sécurité des identifiants

Comment choisir