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

프로세스 호출 시 전체 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 서명 설정
• 타임스탬프 서버
• 파일 경로

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은 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 통합 방식을 우선적으로 사용하는 것이 좋습니다.