CI/CD und Build-Tools

sslTrus Remote-Code-Signing-Dienste lassen sich in CI/CD-, Anwendungsbuild- und Installationspaketerstellungsprozesse integrieren und führen nach Abschluss von Kompilierung oder Paketierung automatisch die Codesignatur der Veröffentlichungsartefakte durch.

Derzeit unterstützte typische Integrationsszenarien sind:

• GitHub Actions
• Electron Builder
• Advanced Installer

Je nach Fähigkeiten des Build-Tools können Sie direkt die sslTrus GitHub Action verwenden, die SignTool CLI aufrufen oder die Integration über die vom Build-Tool bereitgestellte benutzerdefinierte Signaturschnittstelle abschließen.

GitHub Actions

sslTrus bietet eine offizielle GitHub Action:

ssltrus-official/code-sign-action

Sie können Build-Artefakte direkt in einem GitHub Actions Workflow remote codesignieren.

Die Action ruft den Remote-Codesignaturdienst von sslTrus auf, um die Signatur abzuschließen und die angegebenen Dateien direkt zu aktualisieren. Sie ist für Linux-, macOS- und Windows-Runner geeignet.

GitHub Secrets vorbereiten

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

SSLTRUS_ACCESS_KEY
SSLTRUS_ACCESS_SECRET
SSLTRUS_CERT_CODE

Schreiben Sie den 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 mit mehreren 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 durch Kommas getrennte Dateipfade verwenden.

Doppelte 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	Pflicht	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	Ob der NICSRS-Dienst verwendet werden soll
dry-run	Nein	false	Lokales Testzertifikat für Testsignatur verwenden
timestamp-rfc3161	Nein	auto	RFC 3161 Zeitstempelserver
description	Nein	-	Programmbeschreibung in Authenticode-Signatur schreiben
description-url	Nein	-	Programm-URL in Authenticode-Signatur schreiben

Vollständiges Workflow-Beispiel

Das folgende Beispiel kompiliert, signiert und lädt Build-Artefakte in einem Windows Runner hoch:

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

Es wird empfohlen, den Signaturschritt zu platzieren unter:

Kompilieren → Packen → Codesignatur → Veröffentlichen

vor dem Veröffentlichungsschritt im Workflow.

Multi-Plattform-Runner

GitHub Action kann in verschiedenen Runnern aufgerufen werden:

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

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

Da selbst Build-Jobs unter Linux oder macOS laufen, kann dieselbe Action auch für die Remote-Signatur unterstützter Dateien verwendet werden.

Dry Run

Falls der Workflow und die Dateiverarbeitungslogik überprüft werden sollen, kann Folgendes aktiviert werden:

dry-run: true

Dieser Modus verwendet ein lokales Testzertifikat und ruft keinen Remote-Codesignaturdienst 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 die Zieldatei dennoch, daher darf dies nicht als Vorschaumodus verstanden werden, der die Datei überhaupt nicht verändert.

Electron Builder

Electron Builder kann die sslTrus SignTool CLI über eine benutzerdefinierte Signaturfunktion aufrufen und so während des Build-Prozesses der Electron-Anwendung automatisch die Signatur von Windows-Ausführungsdateien und Installationspaketen abschließen.

Typischer Ablauf:

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

Voraussetzungen

Bevor Sie beginnen, benötigen Sie:

• Einen verfügbaren sslTrus Remote-Codesignaturdienst.
• Access Key und Access Secret.
• Die Nummer des Code-Signaturzertifikats.
• Das Electron-Projekt wird mit electron-builder gebaut.
• Die Build-Umgebung kann die sslTrus SignTool CLI ausführen. Sie können sie von der sslTrus-Client-Veröffentlichungsseite herunterladen.

Anmeldedaten konfigurieren

Die Anmeldedaten können über Umgebungsvariablen an das Build-Skript ü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 Electron-Signaturskript gelesen und dann an die SignTool-CLI übergeben.

Electron Builder konfigurieren

Unter:

electron-builder.mjs

Oder in der tatsächlich vom Projekt verwendeten Electron-Builder-Konfigurationsdatei eine benutzerdefinierte Signierfunktion für Windows festlegen:

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

Dabei ist win.sign der offiziell von Electron Builder bereitgestellte Einstiegspunkt für benutzerdefinierte Signaturen. Ausführliche Informationen finden Sie in der Electron Builder-Dokumentation zur Codesignatur unter Windows.

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 mit einem Parameter-Array aufzurufen, anstatt einen vollständigen Shell-Befehl zusammenzusetzen, um Probleme mit Pfad-Escaping und Sonderzeichen zu reduzieren.

Electron Builder ruft die Signierfunktion für jeden Hash-Algorithmus in signingHashAlgorithms jeweils einmal auf. Im obigen Beispiel ist nur SHA-256 aktiviert, daher wird pro Datei einmal aufgerufen.

Build ausführen

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

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

Electron Builder ruft customSign automatisch auf, wenn Dateien signiert werden müssen.

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

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

Daher sollte dies nicht einfach als „ein Electron-Build erzeugt nur eine Signatur“ verstanden werden.

Die tatsächliche Anzahl der Signaturen hängt davon ab, wie viele Dateien während des Build-Prozesses remote signiert werden.

Advanced Installer

Advanced Installer ist ein Tool zur Erstellung von Installationspaketen auf Basis der Windows Installer-Technologie.

Über die Funktion für benutzerdefinierte Signaturtools von Advanced Installer kann die sslTrus SignTool CLI aufgerufen werden, sodass Build-Artefakte wie MSI, EXE, CAB usw. während des Paketierungsprozesses automatisch remote codesigniert werden.

Voraussetzungen

Erforderlich sind:

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

Benutzerdefiniertes Signaturtool konfigurieren

Öffnen Sie im Advanced Installer-Projekt:

Digital Signature

Konfigurationsseite.

Nachdem die Codesignatur aktiviert wurde, wählen Sie als Signaturwerkzeug:

Custom

Legen Sie den Pfad des Signaturwerkzeugs als ausführbare Datei der sslTrus SignTool CLI fest.

Beispiel:

C:\Tools\sslTrus\signtool.exe

Benutzerdefinierte Parameter erfordern einen Aufruf:

sign

Unterbefehle und übergibt an den Client:

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

Es wird empfohlen, Access Key und Access Secret vorrangig auf sicherem Weg bereitzustellen und zu vermeiden, das langfristig gültige Access Secret im Klartext in öffentlich zugänglichen Projektdateien zu speichern.

SignTool-Parameterbeispiel

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 als app.exe wie im Beispiel.

Build-Konfiguration

Wenn Advanced Installer verwendet wird, um Dateien innerhalb des Installationspakets automatisch zu signieren, müssen sowohl die Build- als auch die Komprimierungsmethode überprüft werden.

Je nach tatsächlicher Projektkonfiguration können bestimmte CAB-Archivierungsmethoden den benutzerdefinierten Signaturprozess beeinflussen. Es sollte bestätigt werden, dass die letztendlich zu signierenden Dateien in der entsprechenden Phase aufgerufen werden können.

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 kann bestätigt werden, welche Dateien während des Build-Prozesses signiert werden.

Anzahl der Signaturvorgänge

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

Beispiel:

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

Daher:

一次构建 ≠ 一次签名

Die Anzahl sollte auf der Grundlage der tatsächlich per Fernsignatur abgeschlossenen Dateien oder Signaturaktionen berechnet werden.

Anzahl der Signaturen

CI/CD- und Build-Tools verarbeiten in der Regel automatisch mehrere Artefakte, weshalb die Anzahl der Signaturen besondere Aufmerksamkeit erfordert.

Grundprinzipien:

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

Zum Beispiel:

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

Wenn alle drei Dateien erfolgreich signiert wurden:

合计 = 3 次

Build-Tools wie Electron Builder und Advanced Installer können außerdem automatisch Folgendes generieren und signieren:

• Das Hauptprogramm.
• DLLs.
• Das Update-Programm.
• Das Deinstallationsprogramm.
• MSI.
• Das EXE-Installationspaket.
• Weitere ausführbare Hilfsdateien.

Daher sollte die Anzahl der Signaturen anhand der Build-Protokolle und der tatsächlich signierten Artefakte bestätigt werden, statt sie anhand der Ausführungsanzahl von Pipeline oder Build zu schätzen.

Weitere Regeln finden Sie unter Referenzmaterial.

Zeitstempel

Bei offiziell veröffentlichten Programmen wird üblicherweise empfohlen, einen vertrauenswürdigen Zeitstempel hinzuzufügen.

Die Integrationen von GitHub Actions, Electron Builder und Advanced Installer können alle RFC-3161-Zeitstempel verwenden, zum Beispiel:

http://timestamp.acs.microsoft.com

Zeitstempel gehören nicht zu einem neuen Codesignatur-Vorgang und erhöhen die Anzahl der Codesignaturen nicht separat.

Die Protokollunterstützung und Nutzungsbeschränkungen verschiedener TSA finden Sie in den Referenzmaterialien.

Sicherheit von Anmeldedaten

In automatisierten Umgebungen sollte besonders geschützt werden:

Access Key
Access Secret
Cert Code

Dabei sollte das Access Secret als Secret verwaltet werden und nicht:

• In ein Git-Repository eingecheckt werden.
• Im Klartext in öffentliche Workflows geschrieben werden.
• In Build-Logs ausgegeben werden.
• In öffentliche Docker-Images geschrieben werden.
• Auf unsichere Weise an Build-Systeme von Drittanbietern übergeben werden.

Für GitHub Actions wird empfohlen:

GitHub Actions Secrets

Andere CI/CD-Systeme sollten ihre entsprechenden Secret-, Credential- oder Variablen-Verwaltungsmechanismen verwenden.

Auswahl

Szenario	Empfohlene Methode
GitHub Actions Workflow	GitHub Actions
Electron-Anwendungs-Build	Electron Builder
MSI-/EXE-Installationspaketerstellung	Advanced Installer
Allgemeine Shell-/PowerShell-Automatisierung	SignTool CLI
Native KSP-Unterstützung von Windows-Software	Windows Provider
Eigene Signaturablaufentwicklung	API-Integration

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