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

ソースコードとバージョンの説明は 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

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を使用してサポート対象ファイルのリモート署名を完了できます。

ドライラン

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

因此、単純に「Electron のパッケージング1回につき署名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統合方式を優先してください。