CI/CD и инструменты сборки

sslTrus сервис удалённого подписывания кода может быть интегрирован в процессы CI/CD, сборки приложений и создания установочных пакетов, автоматически подписывая артефакты выпуска после компиляции или упаковки.

В настоящее время поддерживаемые типовые сценарии интеграции включают:

• GitHub Actions
• Electron Builder
• Advanced Installer

В зависимости от возможностей инструмента сборки можно напрямую использовать sslTrus GitHub Action, вызывать SignTool CLI или выполнять интеграцию через настраиваемый интерфейс подписывания, предоставляемый инструментом сборки.

GitHub Actions

sslTrus предоставляет официальный GitHub Action:

ssltrus-official/code-sign-action

Вы можете выполнить удалённое подписание кода для артефактов сборки непосредственно в GitHub Actions Workflow.

Action вызовет сервис удалённого подписания кода sslTrus для завершения подписания и напрямую обновит указанные файлы; подходит для раннеров Linux, macOS и Windows.

Подготовка GitHub Secrets

Рекомендуется сохранить учётные данные удалённого подписания кода в GitHub Actions Secrets:

SSLTRUS_ACCESS_KEY
SSLTRUS_ACCESS_SECRET
SSLTRUS_CERT_CODE

Не указывайте Access Secret непосредственно в файле Workflow.

Базовая конфигурация

- 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/app.exe будет напрямую заменён подписанным файлом.

Подписание нескольких файлов

files поддерживает настройку нескольких файлов с помощью многострочной конфигурации:

- 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

Также можно указать пути к файлам через запятую.

Повторяющиеся пути к файлам обрабатываются только один раз.

Полная конфигурация

- 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	Да	-	Ключ доступа sslTrus
access-secret	Да	-	Секрет доступа sslTrus
cert-code	Да	-	Номер сертификата подписи кода
files	Да	-	Путь к файлу, который необходимо подписать
nicsrs	Нет	false	Использовать ли службу NICSRS
dry-run	Нет	false	Выполнить тестовую подпись с помощью локального тестового сертификата
timestamp-rfc3161	Нет	auto	Сервер меток времени RFC 3161
description	Нет	-	Записать описание программы в подпись Authenticode
description-url	Нет	-	Записать URL программы в подпись Authenticode

Полный пример Workflow

Ниже приведён пример компиляции, подписания и загрузки артефактов сборки в 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

Рекомендуется разместить шаг подписания в:

Компиляция → Упаковка → Подписание кода → Публикация

До шага публикации в процессе.

Runner для нескольких платформ

GitHub Action можно вызывать в разных Runner:

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

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

Таким образом, даже если задача сборки выполняется на Linux или macOS, можно использовать то же самое Action для удалённой подписи поддерживаемых файлов.

Dry Run

Если необходимо проверить Workflow и логику обработки файлов, можно включить:

dry-run: true

В этом режиме используется локальный тестовый сертификат, без обращения к удалённому сервису подписи кода.

Например:

- 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 по-прежнему изменяет целевой файл, поэтому не следует понимать это как режим предварительного просмотра, который вообще не изменяет файл.

Electron Builder

Electron Builder может вызывать CLI sslTrus SignTool через пользовательскую функцию подписи, чтобы автоматически подписывать исполняемые файлы Windows и установочные пакеты в процессе сборки приложения Electron.

Типичный процесс:

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"

Эти переменные считываются пользовательским скриптом подписи Electron, а затем передаются в SignTool CLI.

Настройка Electron Builder

В:

electron-builder.mjs

Или в фактически используемом файле конфигурации Electron Builder для проекта настройте пользовательскую функцию подписи для Windows:

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

Где win.sign — это официально предоставляемый Electron Builder вход для настраиваемой подписи; подробное описание см. в документации Electron Builder по подписанию кода Windows.

customSign

Отвечает за вызов sslTrus SignTool CLI.

Пользовательская функция подписи

Пример:

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

Поэтому не следует упрощённо понимать, что «одна сборка Electron даёт только одну подпись».

Фактическое количество подписей зависит от того, сколько файлов в процессе сборки выполняют удалённую подпись.

Advanced Installer

Advanced Installer — это инструмент для создания установочных пакетов на основе технологии Windows Installer.

Через функцию пользовательского инструмента подписи Advanced Installer можно вызывать sslTrus SignTool CLI, чтобы такие артефакты сборки, как MSI, EXE, CAB, автоматически проходили удалённую подпись кода в процессе упаковки.

Предварительные условия

Необходимо подготовить:

• sslTrus SignTool CLI, его можно скачать со страницы выпусков клиента sslTrus.
• Access Key.
• Access Secret.
• Номер сертификата.
• Уже настроенный проект Advanced Installer.

Настройка пользовательского инструмента подписи

Откройте в проекте Advanced Installer:

Digital Signature

Страница настройки.

После включения подписи кода выберите инструмент подписи:

Custom

Путь к инструменту подписи задается как исполняемый файл sslTrus SignTool CLI.

Например:

C:\Tools\sslTrus\signtool.exe

Пользовательские параметры требуют вызова:

sign

Подкоманда и передача клиенту:

• Access Key
• Access Secret
• Cert Code
• Настройка подписи SHA-2
• Сервер timestamp
• Путь к файлу

Рекомендуется в первую очередь передавать Access Key и Access Secret безопасным способом, избегая сохранения долгосрочного Access Secret в открытом виде в общедоступных файлах проекта.

Пример параметров SignTool

Соответствующая логика подписи аналогична:

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"

В Advanced Installer фактический путь к файлу должен передаваться через его собственный механизм пользовательского инструмента подписи, не фиксируйте его как app.exe из примера.

Конфигурация сборки

Если используется Advanced Installer для автоматической подписи файлов внутри установочного пакета, необходимо одновременно проверить способ сборки и сжатия.

В зависимости от фактической конфигурации проекта некоторые методы CAB-архивации могут повлиять на процесс пользовательской подписи, следует убедиться, что файлы, которые в итоге должны быть подписаны, могут быть вызваны на соответствующем этапе.

После завершения настройки можно проверить на странице цифровой подписи в Advanced Installer:

Files configured for signing

Таким образом, вы можете подтвердить, какие файлы будут подписаны в процессе сборки.

Количество подписей

Advanced Installer может подписывать несколько файлов по отдельности в ходе одной сборки установочного пакета.

Например:

Файл	Подпись
app.exe	1 раз
helper.dll	1 раз
uninstall.exe	1 раз
installer.msi	1 раз
Итого	4 раза

Таким образом:

一次构建 ≠ 一次签名

Она должна рассчитываться на основе фактического количества файлов или операций подписания, для которых выполнено удаленное подписание.

Количество подписаний

CI/CD и инструменты сборки обычно автоматически обрабатывают несколько артефактов, поэтому количеству подписаний необходимо уделять особое внимание.

Основные принципы:

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

Например:

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

Если все три файла успешно подписаны:

合计 = 3 次

Инструменты сборки, такие как Electron Builder и Advanced Installer, также могут автоматически создавать и подписывать:

• Основную программу.
• DLL.
• Программу обновления.
• Программу удаления.
• MSI.
• Установочный пакет EXE.
• Другие вспомогательные исполняемые файлы.

Поэтому количество подписей следует подтверждать на основе журнала сборки и фактических подписанных артефактов, а не оценивать по количеству выполнений Pipeline или Build.

Дополнительные правила см. в справочных материалах.

Отметка времени

Для официально выпускаемого ПО обычно рекомендуется добавлять доверенную отметку времени.

Интеграции GitHub Actions, Electron Builder и Advanced Installer могут использовать отметку времени RFC 3161, например:

http://timestamp.acs.microsoft.com

Временная метка не относится к новой операции подписывания кода и отдельно не увеличивает количество операций подписывания кода.

Сведения о поддержке протоколов и ограничениях использования различных TSA см. в справочных материалах.

Безопасность учетных данных

В автоматизированной среде следует особенно защищать:

Access Key
Access Secret
Cert Code

Из них Access Secret должен управляться как секрет и не должен:

• попадать в Git-репозиторий;
• записываться в открытом виде в публичные Workflow;
• выводиться в журналы сборки;
• записываться в публичные Docker-образы;
• передаваться сторонним системам сборки небезопасным способом.

В GitHub Actions рекомендуется использовать:

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.