CI/CD y herramientas de compilación

El servicio de firma de código remota de sslTrus puede integrarse en procesos de CI/CD, compilación de aplicaciones y creación de instaladores para firmar automáticamente los artefactos de publicación una vez finalizada la compilación o el empaquetado.

Entre los escenarios de integración habituales compatibles actualmente se incluyen:

• GitHub Actions
• Electron Builder
• Advanced Installer

Según las capacidades de la herramienta de compilación, puede utilizar directamente sslTrus GitHub Action, invocar SignTool CLI o completar la integración mediante la interfaz de firma personalizada que proporcione la herramienta.

GitHub Actions

sslTrus proporciona una GitHub Action oficial:

ssltrus-official/code-sign-action

El código fuente y las notas de versión se encuentran en ssltrus-official/code-sign-action. La configuración estable actual utiliza la etiqueta de versión principal @v1.

Puede realizar la firma remota de código de los artefactos de compilación directamente en un flujo de trabajo de GitHub Actions.

La acción invoca el servicio de firma remota de código de sslTrus y actualiza directamente los archivos especificados. Es compatible con ejecutores de Linux, macOS y Windows.

Preparar GitHub Secrets

Se recomienda guardar las credenciales de firma remota de código en 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

Parámetros principales:

Parámetro	Obligatorio	Valor predeterminado	Descripción
access-key	Sí	-	Clave de acceso sslTrus
access-secret	Sí	-	Secreto de acceso sslTrus
cert-code	Sí	-	Número de certificado de firma de código
files	Sí	-	Ruta del archivo que debe firmarse
nicsrs	No	false	Si se utiliza el servicio NICSRS
dry-run	No	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

antes del paso de publicación del flujo de trabajo.

Ejecutores multiplataforma

La GitHub Action se puede invocar en distintos ejecutores:

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

Requisitos previos

Antes de empezar, necesita:

• Disponer de un servicio de firma remota de código de sslTrus operativo.
• Haber obtenido Access Key y Access Secret.
• Haber obtenido el número del certificado de firma de código.
• Que el proyecto de Electron se compile con electron-builder.
• Que el entorno de compilación pueda ejecutar sslTrus SignTool CLI, disponible para descargar en la página de versiones del cliente de sslTrus.

Configurar las credenciales

Puede pasar las credenciales al script de compilación mediante variables de entorno:

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

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

Se recomienda invocar los subprocesos con una matriz de argumentos, en lugar de concatenar un comando completo de Shell, para reducir los problemas de escape de rutas y tratamiento de caracteres especiales.

Electron Builder invoca la función de firma una vez por cada algoritmo hash incluido en signingHashAlgorithms. El ejemplo anterior solo habilita SHA-256, por lo que la función se invoca una vez por archivo.

Ejecutar la compilación

Una vez finalizada la configuración, ejecute Electron Builder de la forma habitual:

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

Electron Builder invoca automáticamente customSign cuando necesita firmar un archivo.

Una compilación de Electron puede firmar varios archivos, por ejemplo:

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

como subcomando, pasando al cliente:

• Access Key
• Access Secret
• Cert Code
• Configuración de firma SHA-2
• Servidor de sellado de tiempo
• Ruta del archivo

Se recomienda proporcionar Access Key y Access Secret mediante mecanismos seguros, evitando guardar un Access Secret de larga duración en texto plano en archivos del proyecto accesibles públicamente.

Ejemplo 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

para confirmar qué archivos se firmarán durante el proceso de compilación.

Número de firmas

Advanced Installer puede firmar varios archivos por separado durante la compilación de un único paquete de instalación.

Por ejemplo:

Archivo	Firmas
app.exe	1 firma
helper.dll	1 firma
uninstall.exe	1 firma
installer.msi	1 firma
Total	4 firmas

Por lo tanto:

一次构建 ≠ 一次签名

El recuento debe basarse en el número de archivos o de operaciones de firma remota que se hayan completado realmente.

Número de firmas

Los sistemas CI/CD y las herramientas de compilación suelen procesar varios artefactos automáticamente, por lo que debe prestarse especial atención al número de firmas.

Principios básicos:

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

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

El sellado de tiempo no constituye una nueva operación de firma de código y no incrementa por separado el número de firmas de código.

Para conocer los protocolos compatibles y las restricciones de uso de las distintas TSA, consulte Material de referencia.

Seguridad de las credenciales

En los entornos automatizados deben protegerse especialmente:

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

En otros sistemas CI/CD, utilice sus respectivos mecanismos de gestión de Secret, Credential o Variable.

Cómo elegir

Escenario	Método recomendado
GitHub Actions Workflow	GitHub Actions
Compilación de aplicaciones Electron	Electron Builder
Creación de paquetes de instalación MSI / EXE	Advanced Installer
Automatización general con Shell / PowerShell	SignTool CLI
Software de Windows con compatibilidad nativa con KSP	Windows Provider
Desarrollo de un proceso de firma propio	Integración con la API

Si el sistema de compilación puede invocar directamente programas de línea de comandos, puede utilizar SignTool CLI. Si la herramienta ya proporciona una interfaz estándar de Windows KSP/CSP, dé prioridad a la integración con el Windows Provider correspondiente.