CI/CD et outils de build

Le service de signature de code à distance sslTrus peut être intégré aux flux CI/CD, à la construction d’applications et à la création de packages d’installation, afin de signer automatiquement le code des artefacts publiés une fois la compilation ou l’empaquetage terminé.

Les scénarios d’intégration typiques actuellement pris en charge sont les suivants :

• GitHub Actions
• Electron Builder
• Advanced Installer

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

GitHub Actions

sslTrus fournit une GitHub Action officielle :

ssltrus-official/code-sign-action

Vous pouvez directement effectuer la signature de code à distance des artefacts de build dans un workflow GitHub Actions.

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

Préparer les secrets GitHub

Il est recommandé d’enregistrer les identifiants de signature de code à distance dans les GitHub Actions Secrets :

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é.

Signer 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 virgules pour séparer les chemins de fichiers.

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	Utiliser ou non le service NICSRS
dry-run	Non	false	Utiliser un certificat de test local pour effectuer une signature de test
timestamp-rfc3161	Non	auto	Serveur d’horodatage RFC 3161
description	Non	-	Description du programme à écrire dans la signature Authenticode
description-url	Non	-	URL du programme à écrire dans la signature Authenticode

Exemple de Workflow complet

Voici un exemple de compilation, de signature et de téléversement des artefacts de build dans 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

Il est recommandé de placer l’étape de signature dans :

Compilation → Empaquetage → Signature du code → Publication

Avant l’étape de publication dans le flux.

Runner multiplateforme

L’action GitHub peut être appelée dans différents runners :

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

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

Par conséquent, même si la tâche de build s'exécute sous Linux ou macOS, la même Action peut être utilisée pour effectuer la signature à distance des fichiers pris en charge.

Dry Run

Si vous avez besoin de valider le Workflow et la logique de traitement des fichiers, vous pouvez activer :

dry-run: true

Ce mode utilise un certificat de test local 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 le considérer comme un mode d'aperçu ne modifiant aucun fichier.

Electron Builder

Electron Builder peut appeler sslTrus SignTool CLI via une fonction de signature personnalisée, afin de signer automatiquement les fichiers exécutables Windows et les packages d'installation lors du processus de build de l'application Electron.

Flux typique :

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

Prérequis

Avant de commencer, vous devez :

• Disposer d’un service de signature de code à distance sslTrus utilisable.
• Avoir obtenu l’Access Key et l’Access Secret.
• Avoir obtenu le numéro du certificat de signature de code.
• Le projet Electron doit être construit avec electron-builder.
• L’environnement de construction doit pouvoir exécuter l’interface CLI sslTrus SignTool, téléchargeable depuis la page de publication du client sslTrus.

Configurer les 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 SignTool.

Configurer Electron Builder

Dans :

electron-builder.mjs

Ou 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'],
  },
};

Parmi eux, win.sign est le point d’entrée de signature personnalisée officiellement fourni par Electron Builder. Pour plus de détails, consultez la documentation de signature de code Windows d’Electron Builder.

customSign

Responsable d’appeler la CLI 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’appeler le sous-processus avec un tableau de paramètres plutôt que de construire la ligne de commande Shell complète, afin de réduire les problèmes d’échappement des chemins et de gestion des caractères spéciaux.

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

Exécution de la compilation

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

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

Lorsqu'Electron Builder doit signer des fichiers, il appelle automatiquement customSign.

Une même build Electron peut signer plusieurs fichiers, par exemple :

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

Par conséquent, il ne faut pas simplement comprendre qu’« un seul empaquetage Electron ne produit qu’une seule signature ».

Le nombre réel de signatures dépend du nombre de fichiers ayant fait l’objet d’une signature à distance au cours du processus de construction.

Advanced Installer

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

Vous pouvez utiliser la fonction d’outil de signature personnalisé d’Advanced Installer pour appeler le sslTrus SignTool CLI, afin que les artefacts de construction comme MSI, EXE, CAB réalisent automatiquement la signature de code à distance pendant le processus d’empaquetage.

Prérequis

Vous devez préparer :

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

Configurer l’outil de signature personnalisé

Ouvrez le projet Advanced Installer :

Digital Signature

Page de configuration.

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

Custom

Définissez le chemin de l'outil de signature sur le fichier exécutable CLI de sslTrus SignTool.

Par exemple :

C:\Tools\sslTrus\signtool.exe

Paramètres personnalisés à appeler :

sign

Sous-commandes, et transmet 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 l’Access Key et l’Access Secret en priorité par des moyens sécurisés, afin d’éviter d’enregistrer en clair un Access Secret à validité prolongée 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 d’accès réel du fichier doit être transmis par son mécanisme d’outil de signature personnalisé, et non fixé sur l’exemple app.exe.

Configuration de la compilation

Si vous utilisez Advanced Installer pour signer automatiquement les fichiers internes du package d’installation, vous devez également vérifier les méthodes de compilation et de compression.

Selon la configuration réelle du projet, certaines méthodes d’archivage CAB peuvent affecter le flux de signature personnalisée. Il convient donc de confirmer que les fichiers devant être signés peuvent être appelés à l’étape correspondante.

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

Files configured for signing

afin de confirmer quels fichiers seront signés au cours du processus de génération.

Nombre de signatures

Advanced Installer peut signer plusieurs fichiers séparément au cours d’une même génération 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 :

一次构建 ≠ 一次签名

Il doit être calculé en fonction du nombre réel de fichiers ou d’actions de signature à distance effectués.

Nombre de signatures

Les outils CI/CD et de build traitent généralement automatiquement plusieurs artefacts, le nombre de signatures doit donc faire l’objet d’une attention particulière.

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 build 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.
• Le MSI.
• Le package d'installation EXE.
• D'autres fichiers exécutables auxiliaires.

Par conséquent, le nombre de signatures doit être confirmé en fonction des journaux de build et des artefacts réellement signés, et non estimé selon le nombre d'exécutions du Pipeline ou du Build.

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

Horodatage

Il est généralement recommandé d'ajouter un horodatage de confiance aux logiciels publiés officiellement.

Les intégrations GitHub Actions, Electron Builder et Advanced Installer peuvent toutes utiliser l'horodatage RFC 3161, par exemple :

http://timestamp.acs.microsoft.com

L’horodatage ne constitue pas une nouvelle opération de signature de code et n’augmente pas séparément le nombre de signatures de code.

Pour connaître la prise en charge des protocoles et les restrictions d’utilisation des différentes TSA, veuillez consulter les documents de référence.

Sécurité des justificatifs

Dans un environnement automatisé, il convient de protéger tout particulièrement :

Access Key
Access Secret
Cert Code

Parmi eux, l’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 construction.
• Être écrit dans une image Docker publique.
• Être transmis de manière non sécurisée à un système de construction tiers.

GitHub Actions recommande d’utiliser :

GitHub Actions Secrets

Les autres systèmes CI/CD doivent utiliser leurs mécanismes correspondants de gestion des secrets, des identifiants ou des variables.

Comment choisir

Scénario	Méthode recommandée
Workflow GitHub Actions	GitHub Actions
Build d’application Electron	Electron Builder
Création de packages d’installation MSI / EXE	Advanced Installer
Automatisation Shell / PowerShell ordinaire	SignTool CLI
Logiciels Windows prenant en charge nativement KSP	Windows Provider
Développement autonome d’un flux de signature	Intégration API

Si le système de build 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 via le Windows Provider correspondant.