클라이언트 도구

sslTrus는 원격 코드 서명 서비스에 연결하고 파일 서명을 완료하기 위한 명령줄 클라이언트와 데스크톱 클라이언트를 제공합니다.

그중 SignTool CLI는 명령줄, 스크립트 및 자동화 시나리오에 적합하며, macOS 사용자는 Homebrew를 통해 SignTool CLI 또는 데스크톱 클라이언트를 설치하고 업데이트할 수도 있습니다.

SignTool CLI

SignTool CLI는 sslTrus가 제공하는 원격 코드 서명 명령줄 클라이언트로, 설치 후 실행 파일 이름은 signtool입니다.

주요 기능은 다음과 같습니다.

기능	명령	설명
파일 서명	signtool sign	로컬 파일에 대해 원격 코드 서명을 수행합니다
서명 할당량	signtool quota	인증서의 남은 서명 할당량과 총 서명 할당량을 조회합니다
클라이언트 업데이트	signtool update	현재 플랫폼의 최신 클라이언트를 조회하고 설치합니다
Windows KSP	signtool ksp	Windows Key Storage Provider를 설치하고 관리합니다
Windows CSP	signtool csp	Windows Cryptographic Service Provider를 설치하고 관리합니다

KSP와 CSP는 Windows Provider 통합 방식에 속합니다. 자세한 사용 방법은 Windows Provider를 참조하십시오.

클라이언트 다운로드

SignTool CLI는 sslTrus 클라이언트 릴리스 페이지에서 다운로드할 수 있습니다.

sslTrus 클라이언트 릴리스 페이지

릴리스 페이지에서 각 플랫폼의 최신 클라이언트 설치 패키지를 제공합니다. 자동화 시나리오에서도 버전 인덱스 latest.json을 통해 현재 최신 버전 정보를 조회할 수 있습니다.

macOS 사용자는 Homebrew를 통해 직접 설치할 수도 있습니다. 아래 macOS Homebrew를 참조하세요.

클라이언트 정보 확인

설치 완료 후 다음을 실행할 수 있습니다.

signtool --help

명령 도움말을 확인합니다.

현재 클라이언트 버전을 확인합니다:

signtool --version

버전 정보에는 클라이언트 버전, 빌드 revision, 실행 플랫폼 및 빌드 시간 등의 정보가 포함됩니다.

액세스 자격 증명

원격 코드 서명 서비스를 사용하기 전에 다음을 준비해야 합니다.

• Access Key
• Access Secret
• 인증서 번호(Cert Code)

여기서 Access Key와 Access Secret은 원격 코드 서명 서비스에 액세스하는 데 사용되며, 인증서 번호는 실제 서명을 수행할 코드 서명 인증서를 지정하는 데 사용됩니다.

SignTool CLI는 명령 매개변수를 통해 자격 증명을 제공하거나 환경 변수를 통해 읽을 수 있습니다.

export ACCESS_KEY="your-access-key"
export ACCESS_SECRET="your-access-secret"

Access Secret는 환경 변수, CI/CD Secret 또는 기타 안전한 자격 증명 관리 방식을 통해 제공하는 것을 우선적으로 권장합니다.

Access Secret을 다음과 같이 하지 마십시오.

• Git 리포지토리에 커밋하지 마십시오.
• 공개 스크립트에 작성하지 마십시오.
• 빌드 로그에 출력하지 마십시오.
• 신뢰할 수 없는 타사 시스템에 전송하지 마십시오.

원격 서비스 주소

기본적으로 SignTool CLI는 sslTrus 프로덕션 서비스 주소를 사용하므로 추가 구성이 필요하지 않습니다.

NICSRS(www.nicsrs.com) 환경을 사용하는 경우 명령에 --address nicsrs를 추가해야 합니다.

signtool sign \
  --address nicsrs \
  --cert-code CERT_CODE \
  --file app.exe

signtool quota 및 signtool update 역시 --address nicsrs를 지원합니다.

파일 서명

signtool sign를 사용하면 로컬 파일에 대해 원격 코드 서명을 직접 수행할 수 있습니다.

가장 기본적인 서명 명령:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe

이미 설정되어 있는 경우:

ACCESS_KEY
ACCESS_SECRET

SignTool CLI는 해당 액세스 자격 증명을 자동으로 읽습니다.

기본적으로 SHA-2를 사용하여 서명합니다.

출력 파일 지정

기본적으로 클라이언트는 원본 파일을 직접 덮어쓰지 않습니다.

--out를 통해 서명 후 출력 파일을 지정할 수 있습니다.

signtool sign \
  --cert-code CERT_CODE \
  --file app-unsigned.exe \
  --out app-signed.exe

원본 파일 덮어쓰기

원본 파일을 직접 수정해야 하는 경우 다음을 사용할 수 있습니다:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --override=true

--override을 활성화하면 서명 결과가 입력 파일에 직접 다시 기록됩니다.

자동화된 빌드 환경에서 사용할 때는 후속 단계에 원본 파일이 필요한지 서명된 파일이 필요한지 확인해야 합니다.

프로그램 설명 지정

프로그램 설명과 URL을 Authenticode 서명에 기록할 수 있습니다:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --desc "Example Application" \
  --url "https://example.com"

SHA-1 및 SHA-2

기본적으로 SHA-2가 활성화됩니다:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe

SHA-1만 사용:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --sha1=true \
  --sha2=false

SHA-1 및 SHA-2를 동시에 활성화:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --sha1=true \
  --sha2=true

SHA-1은 주로 레거시 시스템과의 호환성을 위해 사용되며, 새 프로젝트에서는 일반적으로 SHA-2를 우선 사용해야 합니다.

타임스탬프

코드 서명 시 일반적으로 신뢰할 수 있는 타임스탬프를 함께 추가하는 것이 좋습니다.

SignTool CLI는 기본적으로 서명에 타임스탬프 서비스를 자동으로 구성하며, 매개변수를 통해 타임스탬프 서버를 지정할 수도 있습니다.

• --timestamp-rfc3161: SHA-2 서명에 사용되는 RFC 3161 타임스탬프 서버.
• --timestamp: SHA-1 서명에 사용되는 Authenticode 타임스탬프 서버.

RFC 3161 타임스탬프 서버 지정:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --timestamp-rfc3161=http://timestamp.acs.microsoft.com

Authenticode 타임스탬프 서버 지정:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --timestamp=http://timestamp.sectigo.com

해당 타임스탬프를 비활성화해야 하는 경우, 매개변수 값을 비워 두면 됩니다:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --timestamp-rfc3161= \
  --timestamp=

타임스탬프 프로토콜, 서버 주소 및 선택 권장 사항은 참고 자료를 참조하십시오.

서명 할당량 조회

사용:

signtool quota

현재 접근 자격 증명으로 볼 수 있는 코드 서명 인증서의 할당량을 조회할 수 있습니다.

출력 내용은 다음과 같습니다.

• 인증서 번호.
• 인증서 정보.
• 남은 서명 횟수.
• 총 서명 횟수.

JSON 형식 출력이 필요한 경우:

signtool quota --json

약어를 사용할 수도 있습니다:

signtool quota -j

서명 횟수의 구체적인 계산 방식은 CLI, KSP, Jarsigner 또는 빌드 도구의 호출 방식에 따라 달라질 수 있으며, 자세한 규칙은 서명 횟수 계산 설명을 참조하십시오.

클라이언트 업데이트

SignTool CLI는 현재 플랫폼의 최신 버전 조회 및 설치를 지원합니다:

signtool update

업데이트 과정에서 다운로드 파일의 크기와 SHA-256을 검증하여 클라이언트 파일 무결성을 확인합니다.

SignTool CLI를 Homebrew로 설치한 경우, 두 가지 업데이트 방식을 혼용하지 말고 Homebrew를 통해 버전을 계속 관리하는 것이 좋습니다.

macOS Homebrew

macOS 사용자는 sslTrus 공식 Homebrew Tap을 통해 SignTool CLI 또는 데스크톱 클라이언트를 설치할 수 있습니다.

Homebrew Tap 설치

실행:

brew tap ssltrus-official/tap
brew trust ssltrus-official/tap

완료 후 해당 클라이언트를 설치할 수 있습니다.

SignTool CLI 설치

실행:

brew install ssltrus-official/tap/code-sign-cli

설치가 완료된 후 다음을 실행할 수 있습니다.

signtool --version

클라이언트가 정상적으로 설치되었는지 확인합니다.

Homebrew의 패키지 이름은 다음과 같습니다:

code-sign-cli

실제 설치되는 명령줄 프로그램 이름은 다음과 같습니다:

signtool

데스크톱 클라이언트 설치

sslTrus 코드 서명 데스크톱 클라이언트 설치:

brew install --cask ssltrus-official/tap/code-sign-gui

해당 Homebrew Cask 이름은 다음과 같습니다:

code-sign-gui

클라이언트 업데이트

클라이언트를 Homebrew로 설치한 경우에는 Homebrew를 사용하여 업그레이드하는 것이 좋습니다.

먼저 Homebrew 패키지 정보를 업데이트합니다:

brew update

SignTool CLI 업그레이드:

brew upgrade ssltrus-official/tap/code-sign-cli

데스크톱 클라이언트 업그레이드:

brew upgrade --cask ssltrus-official/tap/code-sign-gui

이렇게 하면 로컬 설치 버전이 Homebrew 패키지 메타데이터와 일치하게 유지됩니다.

Windows Provider

Microsoft SignTool, Visual Studio, MSBuild, Advanced Installer 또는 기타 Windows 소프트웨어에서 원격 코드 서명 개인 키를 직접 사용해야 하고 SignTool CLI를 직접 호출하는 시나리오가 아니라면 Windows Provider를 사용해야 합니다.

sslTrus 제공:

• KSP(Key Storage Provider): Windows CNG용.
• CSP(Cryptographic Service Provider): 기존 Windows CryptoAPI용.

Windows Provider를 참조하세요.

CI/CD 자동 서명

지속적 통합 또는 자동 빌드 과정에서 서명을 수행해야 하는 경우, 반드시 SignTool CLI를 수동으로 설치하고 호출할 필요는 없습니다.

예를 들어 GitHub Actions는 sslTrus Code Sign Action을 직접 사용할 수 있습니다:

- 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

GitHub Action은 Linux, macOS 및 Windows Runner를 지원하며, 빌드 프로세스에서 지정된 파일에 대해 원격 코드 서명을 직접 완료할 수 있습니다.

전체 구성은 CI/CD 및 빌드 도구를 참조하십시오.

선택 방법

실제 사용 방식에 따라 적절한 클라이언트 또는 통합 방식을 선택할 수 있습니다:

시나리오	권장 방식
터미널에서 파일 수동 서명	SignTool CLI
스크립트를 사용한 일괄 서명 호출	SignTool CLI
코드 서명 할당량 조회	SignTool CLI
macOS CLI 설치 및 업데이트	Homebrew
macOS 데스크톱 클라이언트 사용	Homebrew
Microsoft SignTool 등 Windows 소프트웨어에서 원격 개인 키 직접 호출	KSP
기존 CryptoAPI 소프트웨어	CSP
GitHub Actions 자동 서명	GitHub Actions
자체 서명 클라이언트 개발	원격 코드 서명 API

애플리케이션이 이미 Windows KSP, CSP 또는 기타 표준 Provider를 지원한다면 일반적으로 해당 표준 통합 방식을 우선 사용해야 하며, 서명 프로세스를 직접 제어해야 하는 경우 SignTool CLI 또는 원격 코드 서명 API를 사용할 수 있습니다.