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 Runner に対応しています。

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 Key
access-secret	はい	-	sslTrus Access Secret
cert-code	はい	-	コード署名証明書番号
files	はい	-	署名対象のファイルパス
nicsrs	いいえ	false	NICSRS サービスを使用するかどうか
dry-run	いいえ	false	ローカルテスト証明書を使用してテスト署名を実行する
timestamp-rfc3161	いいえ	auto	RFC 3161 タイムスタンプサーバー
description	いいえ	-	Authenticode 署名のプログラム説明を書き込む
description-url	いいえ	-	Authenticode 署名のプログラム URL を書き込む

完全な Workflow 例

以下は、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

署名手順を以下に配置することを推奨します：

コンパイル → パッケージ化 → コード署名 → リリース

流程中的公开步骤之前。

多平台 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 は、カスタム署名関数を通じて sslTrus SignTool CLI を呼び出すことで、Electron アプリケーションのビルドプロセス中に Windows 実行可能ファイルとインストーラーの署名を自動的に完了できます。

典型的なフロー：

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

サブプロセスの呼び出しには、パスエスケープや特殊文字処理の問題を減らすため、完全なシェルコマンドを連結するのではなく、パラメータ配列を使用することを推奨します。

Electron Builder は signingHashAlgorithms 内の各ハッシュアルゴリズムごとに署名関数を1回呼び出します。上記の例では SHA-256 のみを有効にしているため、ファイルごとに1回呼び出されます。

ビルドの実行

設定が完了したら、通常どおり Electron Builder を実行します。

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

Electron Builder は、ファイルに署名を実行する必要がある場合、自動的に customSign を呼び出します。

1 回の Electron ビルドで複数のファイルに署名する場合があります。例：

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

したがって、「1回のElectronパッケージングで署名が1回だけ発生する」と単純に理解すべきではありません。

実際の署名回数は、ビルドプロセス中にリモート署名を実行したファイルの数によって異なります。

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 署名設定
• タイムスタンプサーバー
• ファイルパス

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 は、1 回のインストーラービルドプロセス中に複数のファイルに対して個別に署名を実行する場合があります。

例：

ファイル	署名
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つのファイルがすべて正常に署名された場合：

合计 = 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 は 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 統合方法を優先して使用してください。