클라이언트 도구

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"

가급적 환경 변수, CI/CD Secret 또는 기타 안전한 자격 증명 관리 방식을 통해 Access 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을 검증하여 클라이언트 파일 무결성을 확인합니다.

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

macOS Homebrew

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

공개 저장소: ssltrus-official/homebrew-tap

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 공급자

직접 SignTool CLI를 호출하는 시나리오가 아니라 Microsoft SignTool, Visual Studio, MSBuild, Advanced Installer 또는 기타 Windows 소프트웨어에서 원격 코드 서명 개인 키를 직접 사용하려면 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를 지원하며, 빌드 프로세스에서 지정된 파일에 대한 원격 코드 서명을 직접 완료할 수 있습니다.

공개 저장소: ssltrus-official/code-sign-action

전체 구성은 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를 사용할 수 있습니다.