CI/CD y herramientas de compilación

sslTrus 远程代码签名服务可集成到 CI/CD、应用构建和安装包制作流程中，在编译或打包完成后自动对发布产物执行代码签名。

当前支持的典型集成场景包括：

• GitHub Actions
• Electron Builder
• Advanced Installer

根据构建工具的能力，可以直接使用 sslTrus GitHub Action、调用 SignTool CLI，或通过构建工具提供的自定义签名接口完成集成。

GitHub Actions

sslTrus 提供官方 GitHub Action：

ssltrus-official/code-sign-action

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

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

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

准备 GitHub Secrets

建议将远程代码签名凭证保存到 GitHub Actions Secrets：

SSLTRUS_ACCESS_KEY
SSLTRUS_ACCESS_SECRET
SSLTRUS_CERT_CODE

No escribas el Access Secret directamente en el archivo de Workflow.

Configuración básica

- 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

Tras la firma exitosa, build/app.exe será reemplazado directamente por el archivo firmado.

Firmar múltiples archivos

files admite la configuración de múltiples archivos mediante varias líneas:

- 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

También se pueden usar rutas de archivo separadas por comas.

Las rutas de archivo duplicadas solo se procesarán una vez.

Configuración completa

- 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

主要参数：

参数	必填	默认值	说明
access-key	是	-	Clave de acceso sslTrus
access-secret	是	-	Secreto de acceso sslTrus
cert-code	是	-	Número de certificado de firma de código
files	是	-	Ruta del archivo que debe firmarse
nicsrs	否	false	Si se utiliza el servicio NICSRS
dry-run	否	false	Utilizar un certificado de prueba local para realizar una firma de prueba
timestamp-rfc3161	No	auto	Servidor de sellado de tiempo RFC 3161; pasar un valor vacío desactiva el sellado de tiempo
description	No	-	Descripción del programa escrita en la firma Authenticode
description-url	No	-	URL del programa escrita en la firma Authenticode

Ejemplo completo de Workflow

A continuación se muestra un ejemplo de compilación, firma y carga de los artefactos de compilación en Windows Runner:

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

Sugerimos colocar el paso de firma en:

Compilar → Empaquetar → Firma de código → Publicar

流程中的发布步骤之前。

多平台 Runner

GitHub Action 可以在不同 Runner 中调用：

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

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

Por lo tanto, incluso si las tareas de compilación se ejecutan en Linux o macOS, se puede utilizar la misma Action para completar la firma remota de los archivos compatibles.

Dry Run

Si necesita verificar la lógica del Workflow y el procesamiento de archivos, puede habilitar:

dry-run: true

Este modo utiliza certificados de prueba locales y no invoca el servicio de firma de código remoto.

Por ejemplo:

- 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 seguirá modificando el archivo de destino, por lo que no debe interpretarse como un modo de vista previa que no modifica los archivos en absoluto.

Electron Builder

Electron Builder puede invocar la CLI de sslTrus SignTool mediante una función de firma personalizada, completando así automáticamente la firma de archivos ejecutables e instaladores de Windows durante el proceso de compilación de aplicaciones Electron.

Flujo típico:

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

前提条件

开始前需要：

• 已有可用的 sslTrus 远程代码签名服务。
• 已获得 Access Key 和 Access Secret。
• 已获得代码签名证书编号。
• Electron 项目使用 electron-builder 构建。
• 构建环境能够执行 sslTrus SignTool CLI，可从 sslTrus 客户端发布页 下载。

配置凭证

可以通过环境变量将凭证传递给构建脚本：

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

Estas variables son leídas por el script de firma personalizado de Electron y luego se pasan a la CLI de SignTool.

Configuración de Electron Builder

En:

electron-builder.mjs

O en el archivo de configuración de Electron Builder que el proyecto realmente utiliza, establece una función de firma personalizada para Windows:

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

其中 win.sign es la entrada de firma personalizada proporcionada oficialmente por Electron Builder. Para más detalles, consulte la documentación de firma de código de Electron Builder para Windows.

customSign

Responsable de invocar la CLI de sslTrus SignTool.

Función de firma personalizada

Ejemplo:

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

建议使用参数数组调用子进程，而不是拼接完整 Shell 命令，以减少路径转义和特殊字符处理问题。

Electron Builder 会按照 signingHashAlgorithms 中的每个哈希算法分别调用一次签名函数。上面的示例只启用 SHA-256，因此每个文件调用一次。

执行构建

配置完成后，正常执行 Electron Builder：

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

Electron Builder 在需要对文件执行签名时，会自动调用 customSign。

一次 Electron 构建可能签名多个文件，例如：

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

Por lo tanto, no debe interpretarse simplemente como "un solo empaquetado de Electron produce una sola firma".

El número real de firmas depende de cuántos archivos se sometan a firma remota durante el proceso de compilación.

Advanced Installer

Advanced Installer es una herramienta de creación de paquetes de instalación basada en la tecnología Windows Installer.

A través de la función de herramienta de firma personalizada de Advanced Installer, se puede invocar la CLI de sslTrus SignTool para que los artefactos de compilación como MSI, EXE, CAB, etc., completen automáticamente la firma de código remota durante el proceso de empaquetado.

Requisitos previos

Es necesario preparar:

• sslTrus SignTool CLI, que se puede descargar desde la página de versiones del cliente sslTrus.
• Access Key.
• Access Secret.
• Número de certificado.
• Un proyecto de Advanced Installer ya configurado.

Configurar la herramienta de firma personalizada

Abra el proyecto de Advanced Installer en:

Digital Signature

Página de configuración.

Después de habilitar la firma de código, seleccione la herramienta de firma como:

Custom

Ruta de la herramienta de firma configurada como el archivo ejecutable de sslTrus SignTool CLI.

Por ejemplo:

C:\Tools\sslTrus\signtool.exe

Los parámetros personalizados requieren la siguiente llamada:

sign

子命令，并向客户端传入：

• Access Key
• Access Secret
• Cert Code
• 配置 SHA-2 签名
• 时间戳服务器
• 文件路径

建议优先通过安全方式提供 Access Key 和 Access Secret，避免将长期有效的 Access Secret 明文保存到可公开获取的项目文件中。

示例 de parámetros de SignTool

La lógica de firma correspondiente es similar a:

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"

En Advanced Installer, la ruta real del archivo debe ser pasada por su mecanismo de herramientas de firma personalizadas, no fijarse en el app.exe del ejemplo.

Configuración de compilación

Si se utiliza Advanced Installer para firmar automáticamente los archivos internos del paquete de instalación, es necesario verificar tanto el método de compilación como el de compresión.

Según la configuración real del proyecto, algunos métodos de archivado CAB pueden afectar el flujo de firma personalizada; se debe confirmar que los archivos que finalmente necesitan ser firmados puedan ser invocados en la etapa correspondiente.

Una vez completada la configuración, se puede verificar en la página de firma digital de Advanced Installer:

Files configured for signing

从而确认哪些文件将在构建过程中执行签名。

签名次数

Advanced Installer 可能在一次安装包构建过程中对多个文件分别执行签名。

例如：

文件	签名
app.exe	1 次
helper.dll	1 次
uninstall.exe	1 次
installer.msi	1 次
合计	4 次

因此：

一次构建 ≠ 一次签名

应根据实际完成远程签名的文件或签名动作数量计算。

签名次数

CI/CD 与构建工具通常会自动处理多个产物，因此签名次数需要特别关注。

基本原则：

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

Por ejemplo:

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

Si los tres archivos se firman correctamente:

合计 = 3 次

Electron Builder y Advanced Installer, entre otras herramientas de compilación, también pueden generar y firmar automáticamente:

• El programa principal.
• DLL.
• El programa de actualización.
• El programa de desinstalación.
• MSI.
• Paquete de instalación EXE.
• Otros ejecutables auxiliares.

Por lo tanto, el número de firmas debe confirmarse según el registro de compilación y los artefactos firmados reales, en lugar de estimarse según el número de ejecuciones de Pipeline o Build.

Para más reglas, consulte Material de referencia.

Marca de tiempo

Para el software publicado oficialmente, se recomienda agregar una marca de tiempo confiable.

Las integraciones de GitHub Actions, Electron Builder y Advanced Installer pueden usar marcas de tiempo RFC 3161, por ejemplo:

http://timestamp.acs.microsoft.com

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

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

凭证安全

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

Access Key
Access Secret
Cert Code

El Access Secret debe gestionarse como un secreto, y no debe:

• Enviarse al repositorio de Git.
• Escribirse en texto plano en flujos de trabajo públicos.
• Mostrarse en los registros de compilación.
• Escribirse en imágenes públicas de Docker.
• Transmitirse a sistemas de compilación de terceros de manera insegura.

GitHub Actions recomienda usar:

GitHub Actions Secrets

其他 CI/CD 系统则应使用其对应的 Secret、Credential 或 Variable 管理机制。

如何选择

场景	推荐方式
GitHub Actions Workflow	GitHub Actions
Electron 应用构建	Electron Builder
MSI / EXE 安装包制作	Advanced Installer
普通 Shell / PowerShell 自动化	SignTool CLI
Windows 软件原生支持 KSP	Windows Provider
自行开发签名流程	API 集成

如果构建系统能够直接调用命令行程序，可以使用 SignTool CLI；如果工具已经提供标准的 Windows KSP/CSP 接口，则优先使用对应的 Windows Provider 集成方式。