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

서명 단계를 다음에 배치하는 것이 좋습니다:

컴파일 → 패키징 → 코드 서명 → 배포

프로세스의 게시 단계 이전.

멀티 플랫폼 러너

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

매개변수 배열을 사용하여 하위 프로세스를 호출하는 것을 권장합니다. 전체 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 패키징 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
• 인증서 코드
• 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 통합 방식을 우선 사용하십시오.