CI/CD und Build-Tools

sslTrus Remote-Code-Signaturdienst kann in CI/CD-, Anwendungserstellungs- und Installationspaket-Erstellungsprozesse integriert werden, um nach Abschluss der Kompilierung oder Paketierung automatisch eine Codesignatur an den Veröffentlichungsartefakten durchzuführen.

Zu den aktuell unterstützten typischen Integrationsszenarien gehören:

• GitHub Actions
• Electron Builder
• Advanced Installer

Je nach den Fähigkeiten des Build-Tools kann die Integration direkt über die sslTrus GitHub Action, den Aufruf der SignTool-CLI oder über die benutzerdefinierte Signaturschnittstelle des Build-Tools erfolgen.

GitHub Actions

sslTrus bietet eine offizielle GitHub Action an:

ssltrus-official/code-sign-action

源码与版本说明见 ssltrus-official/code-sign-action。当前稳定用法使用主版本标签 @v1。

可以直接在 GitHub Actions Workflow 中对构建产物执行远程代码签名。

Action 会调用 sslTrus 远程代码签名服务完成签名，并直接更新指定文件，适用于 Linux、macOS 和 Windows Runner。

GitHub Secrets vorbereiten

Es wird empfohlen, die Anmeldeinformationen für die Remote-Codesignatur in den GitHub Actions Secrets zu speichern:

SSLTRUS_ACCESS_KEY
SSLTRUS_ACCESS_SECRET
SSLTRUS_CERT_CODE

Verfassen Sie das Access Secret nicht direkt in die Workflow-Datei.

Grundkonfiguration

- 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

Nach erfolgreicher Signatur wird build/app.exe direkt durch die signierte Datei ersetzt.

Mehrere Dateien signieren

files unterstützt die Konfiguration mehrerer Dateien über mehrere Zeilen:

- 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

Sie können auch kommagetrennte Dateipfade verwenden.

Wiederholte Dateipfade werden nur einmal verarbeitet.

Vollständige Konfiguration

- 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

Hauptparameter:

Parameter	Erforderlich	Standardwert	Beschreibung
access-key	Ja	-	sslTrus Access Key
access-secret	Ja	-	sslTrus Access Secret
cert-code	Ja	-	Code-Signatur-Zertifikatsnummer
files	Ja	-	Pfad der zu signierenden Datei
nicsrs	Nein	false	Verwendung des NICSRS-Dienstes
dry-run	Nein	false	Testsignatur mit lokalem Testzertifikat ausführen
timestamp-rfc3161	Nein	auto	RFC-3161-Zeitstempelserver; bei leerer Eingabe wird die Zeitstempelung deaktiviert
description	Nein	-	Programmbezeichnung, die in die Authenticode-Signatur geschrieben wird
description-url	Nein	-	Programm-URL, die in die Authenticode-Signatur geschrieben wird

Vollständiges Workflow-Beispiel

Das folgende Beispiel zeigt, wie Build-Artefakte unter Windows Runner kompiliert, signiert und hochgeladen werden:

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

Empfehlung: Der Signaturschritt sollte hier platziert werden:

Kompilieren → Packen → Codesignierung → Veröffentlichen

Vor dem Veröffentlichungsschritt im Ablauf.

Multi-Plattform Runner

GitHub Action kann in verschiedenen Runnern aufgerufen werden:

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

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

Daher können auch dann, wenn die Build-Aufgabe unter Linux oder macOS läuft, dieselben Actions für die Remote-Signatur unterstützter Dateien verwendet werden.

Probelauf (Dry Run)

Wenn Sie den Workflow und die Dateiverarbeitungslogik überprüfen möchten, können Sie Folgendes aktivieren:

dry-run: true

Dieser Modus verwendet lokale Testzertifikate und ruft keine entfernten Codesignatur-Dienste auf.

Zum Beispiel:

- 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 ändert weiterhin die Zieldatei, daher sollte es nicht als Vorschaumodus verstanden werden, der die Datei überhaupt nicht verändert.

Electron Builder

Electron Builder kann über eine benutzerdefinierte Signaturfunktion die sslTrus SignTool CLI aufrufen, um während des Build-Prozesses von Electron-Anwendungen automatisch die Signierung von Windows-Ausführbaren Dateien und Installationspaketen abzuschließen.

Typischer Ablauf:

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

Voraussetzungen

Vor Beginn müssen folgende Punkte erfüllt sein:

• Ein verfügbarer sslTrus Remote-Code-Signierungsservice.
• Access Key und Access Secret wurden bereits erhalten.
• Die Code-Signatur-Zertifikatsnummer wurde bereits erhalten.
• Das Electron-Projekt wird mit electron-builder erstellt.
• Die Build-Umgebung kann die sslTrus SignTool CLI ausführen, die von der sslTrus-Client-Veröffentlichungsseite heruntergeladen werden kann.

Anmeldedaten konfigurieren

Die Anmeldedaten können dem Build-Skript über Umgebungsvariablen übergeben werden:

Linux und 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"

Diese Variablen werden vom benutzerdefinierten Signatur-Skript von Electron gelesen und anschließend an die SignTool CLI übergeben.

Konfiguration von Electron Builder

In:

electron-builder.mjs

Oder in der tatsächlich verwendeten Electron-Builder-Konfigurationsdatei des Projekts eine benutzerdefinierte Signaturfunktion für Windows festlegen:

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

win.sign ist der von Electron Builder offiziell bereitgestellte Einstiegspunkt für benutzerdefinierte Signaturen. Detaillierte Informationen finden Sie in der Electron Builder Windows-Codesignierungsdokumentation.

customSign

Verantwortlich für den Aufruf der sslTrus SignTool CLI.

Benutzerdefinierte Signaturfunktion

Beispiel:

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

Es wird empfohlen, den Unterprozess über ein Parameter-Array aufzurufen, anstatt einen vollständigen Shell-Befehl zusammenzusetzen, um Probleme mit Pfad-Escaping und der Verarbeitung von Sonderzeichen zu reduzieren.

Electron Builder ruft die Signaturfunktion für jeden Hash-Algorithmus in signingHashAlgorithms separat auf. Das obige Beispiel aktiviert nur SHA-256, daher wird die Funktion pro Datei einmal aufgerufen.

Ausführen des Builds

Nach der Konfiguration führen Sie Electron Builder wie gewohnt aus:

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

Electron Builder ruft automatisch customSign auf, wenn eine Signatur für die Datei erforderlich ist.

Ein einziger Electron-Build kann mehrere Dateien signieren, zum Beispiel:

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

Daher sollte es nicht vereinfacht als „ein einziger Electron-Packaging-Vorgang erzeugt nur eine einzige Signatur“ verstanden werden.

Die tatsächliche Anzahl der Signaturen hängt davon ab, wie viele Dateien während des Build-Prozesses eine Remote-Signatur ausführen.

Advanced Installer

Advanced Installer ist ein Tool zur Erstellung von Installationspaketen, das auf der Windows-Installer-Technologie basiert.

Über die Funktion „Benutzerdefiniertes Signaturtool“ von Advanced Installer kann die sslTrus SignTool-CLI aufgerufen werden, sodass Build-Artefakte wie MSI, EXE, CAB usw. während des Paketierungsprozesses automatisch eine Remote-Codesignatur erhalten.

Voraussetzungen

Folgendes muss vorbereitet werden:

• sslTrus SignTool-CLI, herunterladbar über die sslTrus-Client-Veröffentlichungsseite.
• Access Key.
• Access Secret.
• Zertifikatsnummer.
• Ein bereits konfiguriertes Advanced-Installer-Projekt.

Konfiguration des benutzerdefinierten Signaturtools

Öffnen Sie im Advanced-Installer-Projekt:

Digital Signature

Konfigurationsseite.

Nach der Aktivierung der Codesignatur wählen Sie das Signaturtool wie folgt aus:

Custom

Signaturwerkzeug-Pfad wird auf die ausführbare Datei sslTrus SignTool CLI gesetzt.

Zum Beispiel:

C:\Tools\sslTrus\signtool.exe

Benutzerdefinierte Parameter müssen wie folgt aufgerufen werden:

sign

Unterbefehle und übergibt dem Client:

• Access Key
• Access Secret
• Cert Code
• SHA-2-Signatureinstellung
• Zeitstempelserver
• Dateipfad

Es wird empfohlen, Access Key und Access Secret vorrangig auf sicherem Wege bereitzustellen, um zu vermeiden, dass ein langfristig gültiges Access Secret im Klartext in öffentlich zugänglichen Projektdateien gespeichert wird.

Beispiel für SignTool-Parameter

Die entsprechende Signaturlogik ähnelt:

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"

In Advanced Installer sollte der tatsächliche Dateipfad über den Mechanismus des benutzerdefinierten Signaturtools übergeben werden und nicht fest auf app.exe aus dem Beispiel gesetzt werden.

Build-Konfiguration

Wenn Sie mit Advanced Installer die in der Installation enthaltenen Dateien automatisch signieren, müssen Sie sowohl die Build- als auch die Komprimierungsmethode überprüfen.

Abhängig von der tatsächlichen Projektkonfiguration können bestimmte CAB-Archivierungsmethoden den benutzerdefinierten Signaturprozess beeinflussen. Sie sollten daher bestätigen, dass die letztendlich zu signierende Datei in der entsprechenden Phase aufgerufen werden kann.

Nach Abschluss der Konfiguration können Sie dies auf der Seite für digitale Signaturen in Advanced Installer überprüfen:

Files configured for signing

Dadurch wird bestätigt, welche Dateien während des Build-Prozesses signiert werden.

Anzahl der Signierungen

Advanced Installer kann während eines einzelnen Installationspaket-Builds mehrere Dateien separat signieren.

Beispiel:

Datei	Signierung
app.exe	1 Mal
helper.dll	1 Mal
uninstall.exe	1 Mal
installer.msi	1 Mal
Gesamt	4 Mal

Daher:

一次构建 ≠ 一次签名

Die Berechnung erfolgt basierend auf der tatsächlichen Anzahl der Dateien, für die eine Remote-Signierung abgeschlossen wurde, oder der Anzahl der Signierungsvorgänge.

Anzahl der Signierungen

CI/CD- und Build-Tools verarbeiten in der Regel automatisch mehrere Artefakte, daher muss der Anzahl der Signierungen besondere Aufmerksamkeit geschenkt werden.

Grundprinzipien:

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

例如：

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

Wenn alle drei Dateien erfolgreich signiert wurden:

合计 = 3 次

Elektron Builder und Advanced Installer sowie ähnliche Build-Tools können außerdem automatisch Folgendes generieren und signieren:

• Das Hauptprogramm.
• DLLs.
• Das Update-Programm.
• Das Deinstallationsprogramm.
• MSI.
• EXE-Installationspakete.
• Andere unterstützende ausführbare Dateien.

Daher sollte die Anzahl der Signaturen anhand des Build-Protokolls und der tatsächlich signierten Artefakte ermittelt werden, nicht anhand der Anzahl der Pipeline- oder Build-Ausführungen.

Weitere Regeln finden Sie in den Referenzmaterialien.

Zeitstempel

Für offiziell veröffentlichte Software wird empfohlen, einen vertrauenswürdigen Zeitstempel hinzuzufügen.

GitHub Actions, Elektron Builder und Advanced Installer-Integrationen unterstützen alle RFC-3161-Zeitstempel, zum Beispiel:

http://timestamp.acs.microsoft.com

时间戳不属于新的代码签名操作，不单独增加代码签名次数。

不同 TSA 的协议支持和使用限制请参阅 参考资料。

凭证安全

自动化环境中应特别保护：

Access Key
Access Secret
Cert Code

Access Secret sollte als Secret verwaltet werden und nicht:

• in ein Git-Repository committet werden.
• im Klartext in einen öffentlichen Workflow geschrieben werden.
• in Build-Protokolle ausgegeben werden.
• in ein öffentliches Docker-Image geschrieben werden.
• auf unsichere Weise an ein Drittanbieter-Build-System übergeben werden.

Für GitHub Actions wird empfohlen:

GitHub Actions Secrets

Andere CI/CD-Systeme sollten die entsprechenden Secret-, Credential- oder Variable-Verwaltungsmechanismen verwenden.

Auswahlhilfe

Szenario	Empfohlene Methode
GitHub Actions Workflow	GitHub Actions
Elektron-Anwendungsbuild	Electron Builder
MSI-/EXE-Installationspaketerstellung	Advanced Installer
Allgemeine Shell-/PowerShell-Automatisierung	SignTool-CLI
Windows-Software mit nativer KSP-Unterstützung	Windows Provider
Eigene Signaturprozessentwicklung	API-Integration

Wenn das Build-System direkt Befehlszeilenprogramme aufrufen kann, kann die SignTool-CLI verwendet werden; wenn das Tool bereits eine standardmäßige Windows-KSP-/CSP-Schnittstelle bereitstellt, sollte bevorzugt die entsprechende Windows-Provider-Integrationsmethode verwendet werden.