npm @certchip/signer

SSH 키 인증을 지원하는 크로스 플랫폼 코드 및 문서 서명 CLI 도구입니다.

주요 기능

크로스 플랫폼 - Windows, Linux, macOS (x64, arm64) 지원
SSH 키 인증 - Ed25519, ECDSA, RSA 지원
코드 서명 - PE 실행 파일 (EXE, DLL, SYS, OCX), MSI, MSP, CAB
문서 서명 - 시각적 서명이 포함된 PDF (워터마크, 박스, 바코드, QR 코드)
스크립트 서명 - Authenticode를 사용한 PowerShell, VBScript
텍스트/소스 서명 - JS, Python, Go, Rust 등
해시 기반 서명 - 기본 모드: 파일이 아닌 해시만 서버로 전송
Windows KSP - 네이티브 Windows 암호화 통합 (Windows 전용)
구조화된 출력 - 스크립팅 및 자동화를 위한 JSON, 테이블, CSV 출력
인증서 배포 - SSL/TLS, 디바이스, 서명 인증서를 위한 원격 인증서 다운로드, 갱신, 동기화 (-cert-dist)
Let's Encrypt 관리 - 서버에 저장된 Let's Encrypt SSL 인증서에 직접 접근 (-letsencrypt)
인증서 관리 API - 인증서/키 업로드, 다운로드, 삭제, CSR 생성 (-cert, -privkey, -pubkey, -csr)

설치

# 전역 설치 (권장)
npm install -g @certchip/signer

# 또는 로컬 설치
npm install @certchip/signer

빠른 시작

signercli (크로스 플랫폼: Windows, Linux, macOS)

# SSH 키 인증으로 로그인
signercli -login https://signer.example.com username

# 파일 서명 (두 가지 동등한 형식)
signercli myapp.exe              # 암시적 형식
signercli -sign myapp.exe        # 명시적 형식

# 서명 검증
signercli -verify myapp.exe

# 로그아웃
signercli -logout

signer (Windows 전용 - KSP 통합)

# 로그인 (인증서가 Windows 인증서 저장소에 설치됨)
signer -login https://signer.example.com username

# signer로 직접 서명 (두 가지 동등한 형식, signercli와 동일한 옵션)
signer myapp.exe                              # 암시적 형식 (기본: 해시 전용 모드)
signer -sign myapp.exe                        # 명시적 형식
signer myapp.exe -o myapp_signed.exe          # 출력 파일 지정
signer myapp.exe -file-upload -save-signed    # 파일 업로드, _signed 접미사로 저장

# 또는 Windows signtool.exe 사용 (로그인 후)
signtool sign /n "Your Certificate CN" /fd sha256 /tr http://timestamp.digicert.com /td sha256 myapp.exe

# 로그아웃 (저장소에서 인증서 제거)
signer -logout

로컬 설치 사용 시 (npx)

# signercli (크로스 플랫폼)
npx signercli -login https://signer.example.com username
npx signercli myapp.exe

# signer (Windows 전용)
npx signer -login https://signer.example.com username
npx signer myapp.exe

CLI 명령어

이 패키지는 서로 다른 기능을 가진 두 가지 CLI 도구를 제공합니다:

도구 비교 개요

	signercli	signer
목적	전체 기능의 서명 및 인증서 관리	Windows signtool.exe 통합 + 직접 서명
플랫폼	Windows, Linux, macOS	Windows 전용
작동 방식	서버 API를 통해 직접 파일 서명	signtool.exe 통합을 위해 Windows 저장소에 인증서 등록
적합한 용도	CI/CD, 자동화, 크로스 플랫폼, 인증서 관리	Windows 개발자, signtool.exe, Visual Studio 통합

기능 비교

기능	signercli	signer
플랫폼 지원
Windows	✅	✅
Linux	✅	❌
macOS	✅	❌
ARM64 지원	✅	❌
인증
SSH 키 (Ed25519, ECDSA, RSA)	✅	✅
비밀번호 인증	✅	✅
API 키 (로그인 불필요)	✅	❌
프로필 기반 설정	✅	✅
파일 서명
PE 실행 파일 (.exe, .dll, .sys, .ocx)	✅	✅
설치 프로그램 (.msi, .msp, .cab)	✅	✅
PDF 문서	✅	✅
스크립트 (.ps1, .vbs)	✅	✅
소스 코드 (JS, Python, Go, Rust 등)	✅	✅
JAR 파일	✅	✅
해시 전용 서명 (기본)	✅	✅
파일 업로드 서명	✅	✅
PDF 서명 옵션
워터마크 스타일	✅	✅
박스 스타일	✅	✅
바코드 스타일	✅	✅
QR 코드 스타일	✅	✅
위치/투명도 제어	✅	✅
인증서 관리
인증서 목록	✅	✅
인증서 ID 가져오기/설정	✅	✅
인증서 PEM 가져오기	✅	✅
개인 키 비밀번호 설정	✅	✅
인증서 업로드	✅	❌
인증서 다운로드 (PEM/DER/PFX)	✅	❌
인증서 삭제	✅	❌
인증서 메타데이터 업데이트	✅	❌
개인 키 관리
개인 키 목록	✅	❌
개인 키 업로드	✅	❌
개인 키 다운로드	✅	❌
개인 키 삭제	✅	❌
인증서에 연결/해제	✅	❌
CSR 및 공개 키
CSR 생성	✅	❌
공개 키 관리	✅	❌
인증서 배포
Let's Encrypt SSL 인증서	✅	❌
Let's Encrypt 직접 관리	✅	❌
디바이스 인증서	✅	❌
서명 인증서	✅	❌
자동 갱신 확인	✅	❌
다양한 다운로드 형식	✅	❌
Windows 통합
signtool.exe 통합	❌	✅
Windows 인증서 저장소	❌	✅
KSP 공급자 등록	❌	✅
키 컨테이너 관리	❌	✅
출력 및 자동화
클래식 출력	✅	✅
JSON 출력	✅	❌
테이블 출력	✅	❌
CSV 출력	✅	❌
로그 레벨 제어	✅	✅

어떤 도구를 사용해야 할까요?

시나리오	권장 도구
CI/CD 파이프라인 (모든 플랫폼)	signercli - 크로스 플랫폼, JSON 출력, API 키 인증
Linux/macOS 개발	signercli - Windows가 아닌 환경의 유일한 옵션
간단한 파일 서명	signercli 또는 signer - 둘 다 동일하게 작동
Windows signtool.exe 통합	signer - Windows 저장소에 인증서 등록
Visual Studio 빌드 후 서명	signer - signtool.exe 호환
Windows 인증서 저장소 통합	signer - KSP 공급자 지원
인증서 업로드/다운로드/삭제	signercli - API 키로 `-cert`
Let's Encrypt 인증서 배포	signercli - `-cert-dist` 명령
Let's Encrypt 직접 관리	signercli - `-letsencrypt` 명령
개인 키 관리	signercli - `-privkey` 명령
CSR 생성	signercli - `-csr` 명령
SSH 키 없이 자동화	signercli - API 키 인증
스크립트에서 출력 파싱	signercli - `-format json` 옵션

signercli (크로스 플랫폼)

코드 및 문서 서명을 위한 주요 CLI 도구입니다. 서명 서버와 통신하여 직접 파일에 서명합니다. 추가 설정 없이 모든 플랫폼에서 작동합니다.

인증

# 자동 감지 인증 (SSH 키가 있으면 SSH 키, 없으면 비밀번호 프롬프트)
signercli -login <url> [username]

# SSH 키 인증 (명시적)
signercli -login <url> -key ~/.ssh/id_ed25519
signercli -login <url> username -key ~/.ssh/id_rsa

# 비밀번호 인증
signercli -login <url> -user <userid>              # 비밀번호 대화형 입력
signercli -login <url> -user <userid> -pw <password>  # 명령줄에서 비밀번호 지정

# 로그인 옵션
-profile <name>       특정 설정 프로필 사용
-expires <time>       토큰 만료 시간 (예: 24h, 7d, 1w)
-cert-id <id>         인증서 ID 미리 지정
-cert-serial <sn>     인증서 일련번호 미리 지정
-include-chain        토큰에 인증서 체인 포함

# 로그아웃
signercli -logout [url]

파일 서명

# 기본 서명 (기본: 해시 전용 모드)
signercli <file>                          # 암시적 형식
signercli -sign <file>                    # 명시적 형식 (동일한 결과)

# 서명 옵션
signercli <file> -o <output>              # 출력 파일 지정
signercli -sign <file> -o <output>        # 명시적 형식
signercli <file> -save-signed             # _signed 접미사로 저장 (원본 보존)
signercli <file> -hash-only               # 해시 기반 서명 (기본)
signercli <file> -file-upload             # 전체 파일을 서버에 업로드
signercli <file> -hash-algorithm <alg>    # sha256, sha384, sha512
signercli <file> -timestamp-url <url>     # 타임스탬프 서버 URL
signercli <file> -profile <name>          # 설정 프로필 사용

참고: signercli <file> (암시적)과 signercli -sign <file> (명시적) 형식은 동일합니다. 명시적 형식은 스크립트와 자동화에서 의도를 더 명확하게 합니다.

참고: 해시 전용 서명이 기본 모드입니다. 전체 파일이 아닌 파일 해시만 서버로 전송됩니다.

서명 검증

signercli -verify <file>
signercli -verify <file> -signature-id <id>    # 특정 서명 검증
signercli -verify <file> -profile <name>

인증서 관리

# 사용 가능한 인증서 목록
signercli -codesign-list

# 인증서 ID 가져오기/설정
signercli -codesign-id                    # 현재 인증서 ID 표시
signercli -codesign-id <id>               # 인증서 ID 설정

# 인증서 PEM 가져오기
signercli -codesign-cert                  # 현재 인증서 가져오기
signercli -codesign-cert -id <id>         # 특정 인증서 가져오기
signercli -codesign-cert -o cert.pem      # 파일로 저장

# 개인 키 비밀번호 설정 (서버의 비밀번호로 보호된 키용)
signercli -codesign-set <password>

대안: -cert 명령어 (signer.exe와 호환)

# 인증서 목록 (용도별 필터)
signercli -cert list                      # 개인 키가 있는 모든 인증서 목록 (기본)
signercli -cert list any                  # 모든 인증서 (개인 키 없는 것 포함)
signercli -cert list codesign             # 코드 서명 인증서 목록
signercli -cert list docsign              # 문서 서명 인증서 목록
signercli -cert list serverauth           # 서버 인증 (SSL/TLS) 인증서 목록
signercli -cert list clientauth           # 클라이언트 인증 인증서 목록
signercli -cert list ca                   # CA 인증서 목록
signercli -cert list timestamp            # 타임스탬핑 인증서 목록
signercli -cert list ocsp                 # OCSP 서명 인증서 목록
signercli -cert list encrypt              # 암호화 인증서 목록
signercli -cert list verify               # 검증 인증서 목록

# 인증서 ID 가져오기/설정
signercli -cert -id                       # 현재 설정 표시
signercli -cert -id <cert_id>             # 인증서 ID 설정
signercli -cert -id <cert_id> <label>     # 레이블과 함께 설정

# 인증서 PEM 가져오기
signercli -cert -pem

# 개인 키 비밀번호 설정
signercli -cert -password <password>

참고: -cert 명령어는 signer.exe와 동일한 API 엔드포인트를 사용하여 두 도구 간의 완전한 호환성을 보장합니다.

설정

설정 파일을 사용하면 연결 설정, 인증 자격 증명 및 서명 옵션을 재사용 가능한 프로필에 저장할 수 있습니다. 이를 통해 명령줄에서 동일한 옵션을 반복적으로 지정할 필요가 없습니다.

설정 프로필을 사용하는 이유:

편의성: 서버 URL, API 키 및 기타 설정을 한 번만 저장
다중 환경: 프로덕션, 스테이징, 개발 서버 간 전환
CI/CD 통합: 자동화된 서명 워크플로우를 위한 설정 사전 구성
보안: 자격 증명을 명령 기록 및 스크립트에서 제외

기본 프로필 이해:

[default] 프로필은 특별합니다 - 모든 작업의 기본 설정 역할을 합니다:

자동 로딩: -profile 옵션을 지정하지 않으면 SignerCLI가 자동으로 [default]를 사용
상속: 명명된 프로필 ([production] 또는 [staging])은 [default]의 모든 설정을 상속
재정의 동작: 명명된 프로필은 [default]와 다른 설정만 지정하면 됨

이 상속 모델은 다음을 의미합니다:

공통 설정 (서버 URL, API 키)을 [default]에 저장
환경별 설정 (인증서 ID, 타임스탬프 URL)을 명명된 프로필에 저장

┌─────────────────────────────────────────────────────┐
│ [default]                                           │
│   host = https://signer.example.com:7443            │
│   api_key = cdk_xxx...                              │
│   hash_algorithm = sha256                           │
├─────────────────────────────────────────────────────┤
│ [production]              │ [staging]               │
│   cert_id = prod-001      │   host = https://stg:7443│
│   (host, api_key,         │   cert_id = stg-001     │
│    hash_alg 상속)          │   (api_key, hash_alg    │
│                           │    상속)                 │
└───────────────────────────┴─────────────────────────┘

설정 파일 위치:

OS	경로
Linux/macOS	`~/.signer/config`
Windows	`%USERPROFILE%\.signer\config`

기본 명령어:

# 설정 보기
signercli -config                         # 전체 설정 파일 표시
signercli -config list                    # 모든 프로필 목록
signercli -config show <name>             # 특정 프로필 세부 정보 표시

# 프로필 생성/업데이트 (프로필 이름 생략 시 'default')
signercli -config set [name] [options]

# 프로필에서 특정 설정 제거
signercli -config unset [name] <options>

# 전체 프로필 삭제
signercli -config delete <name>

설정 제거 (-config unset):

# default 프로필에서 api_key 제거
signercli -config unset -api-key

# 여러 설정 제거
signercli -config unset -api-key -host

# 명명된 프로필에서 제거
signercli -config unset production -cert-id

API 키 인증 (로그인 불필요):

프로필에 API 키를 저장하여 로그인 없이 -cert, -privkey, -pubkey, -csr, -cert-dist 명령을 사용합니다.

# default 프로필에 API 키 설정 (프로필 이름 생략 = 'default')
signercli -config set \
    -host https://signer.example.com:7443 \
    -api-key cdk_e2f369e7c85bfa7835d375f6b088f15dac2c2d8ebeb0815c392a6d6b34ee916f

# 위와 동일 (명시적 'default')
signercli -config set default \
    -host https://signer.example.com:7443 \
    -api-key cdk_e2f369e7c85bfa7835d375f6b088f15dac2c2d8ebeb0815c392a6d6b34ee916f

# 로그인 없이 명령 사용 (API 키 자동 적용)
signercli -cert list
signercli -cert get <id>
signercli -cert upload cert.pem -name "My Cert"
signercli -cert-dist list

프로필 상속 예시:

# default 프로필에 공통 설정 저장 (프로필 이름 선택 사항)
signercli -config set \
    -host https://signer.example.com:7443 \
    -api-key cdk_common_api_key \
    -hash-algorithm sha256

# production 프로필 생성 (host, api_key, hash-algorithm 상속)
signercli -config set production -cert-id prod-cert-001

# staging 프로필 생성 (host 재정의, 나머지 상속)
signercli -config set staging \
    -host https://staging.example.com:7443 \
    -cert-id staging-cert-001

# 사용법
signercli -cert list                      # default 프로필 사용
signercli -cert list -profile production  # production 프로필 사용
signercli -cert list -profile staging     # staging 프로필 사용

상속 표시:

$ signercli -config show production
Profile: [production]
----------------------------------------
  host              = https://signer.example.com:7443 (default)
  api_key           = cdk_common_api_key (default)
  cert_id           = prod-cert-001
  hash_algorithm    = sha256 (default)

(default) 표시는 [default] 프로필에서 상속된 값임을 나타냅니다.

인증 우선순위:

명령줄 인수 (-api-key, -host) - 최고 우선순위
지정된 프로필 (-profile <name>)
기본 프로필
로그인 토큰 (사용 가능한 경우)

# 명령줄 인수가 프로필 설정을 재정의
signercli -cert list -profile production -host https://other:7443
# → other:7443 사용 (production의 host 무시)

프로필 옵션:

옵션	설명
`-host <url>`	서버 URL
`-ssh-key-path <path>`	SSH 개인 키 경로
`-username <name>`	SSH 사용자 이름
`-user <id>`	비밀번호 인증용 사용자 ID
`-api-key <key>`	API 키 (로그인 우회)
`-cert-id <id>`	기본 인증서 ID
`-cert-serial <sn>`	인증서 일련번호
`-expires <time>`	토큰 만료 (24h, 7d, 1w)
`-include-chain`	인증서 체인 포함
`-timestamp-url <url>`	타임스탬프 서버 URL
`-hash-algorithm <alg>`	해시 알고리즘 (sha256, sha384, sha512)
`-output-format <type>`	출력 형식 (classic, json, table, csv)

문서 서명 옵션:

옵션	설명
`-doc-style <style>`	watermark, box, barcode, qrcode
`-doc-position <pos>`	bottom-right, bottom-left, top-right, top-left, center
`-doc-sig-position <pos>`	left, center, right (barcode/qrcode용)
`-doc-font-size <size>`	서명 글꼴 크기
`-doc-opacity <value>`	투명도 (0.0-1.0 또는 0-100)

설정 파일 예시 (~/.signer/config):

[default]
host=https://signer.example.com:7443
api_key=cdk_e2f369e7c85bfa7835d375f6b088f15dac2c2d8ebeb0815c392a6d6b34ee916f
hash_algorithm=sha256
output_format=classic

[production]
cert_id=prod-codesign-001
timestamp_url=http://timestamp.digicert.com
include_chain=true

[ci-automation]
api_key=cdk_ci_specific_api_key
output_format=json
cert_id=automation-cert-001

보안 참고사항:

API 키는 설정 파일에 일반 텍스트로 저장됩니다
적절한 파일 권한 설정: chmod 600 ~/.signer/config (Linux/macOS)

Windows DLL 설치

# System32에 DLL 설치 (UAC 권한 자동 요청)
signercli -install

# System32에서 DLL 제거
signercli -uninstall

도움말 및 디버깅

signercli -help
signercli -version

# 로그 레벨 (디버깅을 위해 모든 명령에 추가)
signercli <file> LOG_DBG                  # 디버그 출력
signercli <file> LOG_INF                  # 정보 출력
# 사용 가능: LOG_NON, LOG_ERR, LOG_WRN, LOG_DBG, LOG_INF

버전 출력:

-version 명령은 종합적인 버전 정보를 표시합니다:

# signercli -version
Certchip Signer CLI v0.1.18
Cross-platform code and document signing tool
Copyright (c) 2026 Certchip. All rights reserved.

DLL Versions (Local):
  otpkey.dll:   0.1.18.0
  Certchip.dll: 0.1.18.0

DLL Versions (System32):
  otpkey.dll:   0.1.18.0
  Certchip.dll: 0.1.18.0

정보	설명
CLI 버전	signercli/signer 실행 파일 버전
로컬 DLL	실행 파일과 같은 디렉토리의 DLL 버전
System32 DLL	Windows System32 폴더에 설치된 DLL 버전

참고: DLL 버전 정보는 Windows 전용입니다. Linux/macOS에서는 CLI 버전만 표시됩니다.

출력 형식

signercli와 signer 모두 스크립팅 및 자동화를 위한 구조화된 출력 형식을 지원합니다.

# JSON 형식 (스크립팅 기본)
signercli -verify myapp.exe -format json
signercli -config list -format json
signercli -logout -format json

# 테이블 형식 (정렬된 열)
signercli -verify myapp.exe -format table

# CSV 형식 (스프레드시트 친화적)
signercli -config list -format csv

# 클래식 형식 (기본 - 사람이 읽기 쉬움)
signercli -verify myapp.exe

형식 옵션:

형식	설명	적합한 용도
`classic`	사람이 읽기 쉬운 출력 (기본)	대화형 사용
`json`	JSON 구조화 출력	CI/CD, 스크립팅, 자동화
`table`	정렬된 테이블 형식	터미널 표시
`csv`	쉼표로 구분된 값	스프레드시트, 데이터 처리

예시: verify 명령의 JSON 출력

$ signercli -verify myapp.exe -format json

{
    "command": "verify",
    "status": "valid",
    "file": "myapp.exe",
    "method": "AUTHENTICODE",
    "signer": "Example Company",
    "serialNumber": "0123456789abcdef",
    "timestamp": "2025-01-15 10:30:00",
    "success": true
}

예시: config list의 JSON 출력

$ signercli -config list -format json

{
    "command": "config-list",
    "count": 3,
    "profiles": ["default", "production", "staging"],
    "success": true
}

예시: login의 JSON 출력

$ signercli -login https://signer.example.com admin -pw secret -format json

{
    "command": "login",
    "status": "success",
    "username": "admin",
    "expiresIn": 86400,
    "certificate": {
        "cn": "Example Company Code Signing"
    },
    "success": true
}

참고: 구조화된 출력 형식에서는 대화형 인증(비밀번호 프롬프트, SSH 키 선택)을 사용할 수 없습니다. 비대화형 로그인에는 -user 및 -pw 옵션 또는 -key 옵션을 사용하세요.

signer (Windows 전용)

KSP(Key Storage Provider)를 통해 Windows 암호화 시스템과 통합되는 Windows 전용 도구입니다. signercli처럼 직접 파일에 서명하거나 signtool.exe에서 사용할 수 있도록 Windows 인증서 저장소에 인증서를 등록할 수 있습니다.

두 가지 서명 방법:

직접 서명 - signer <file> 또는 signer -sign <file>로 파일에 직접 서명 (signercli와 동일)
signtool 통합 - 로그인하여 인증서 등록 후 Windows signtool.exe 사용

# 인증 (인증서를 Windows 저장소로 가져옴)
signer -login <url> [username]            # 로그인 및 인증서 등록
signer -logout                            # 로그아웃 및 인증서 제거

# 파일 서명 (직접 - signercli와 동일한 옵션)
signer <file> [options]                   # 파일 서명 (암시적 형식)
signer -sign <file> [options]             # 파일 서명 (명시적 형식)
    -o <path>                             # 출력 파일 경로
    -hash-only                            # 해시 기반 서명 (기본)
    -file-upload                          # 전체 파일을 서버에 업로드
    -save-signed                          # _signed 접미사로 저장
    -profile <name>                       # 특정 서명 프로필 사용

# 인증서 관리
signer -cert -list                        # 사용 가능한 인증서 목록
signer -cert -list codesign               # 용도별 필터
signer -cert -id                          # 현재 인증서 설정 표시
signer -cert -id <cert_id>                # 인증서 ID 설정
signer -cert -pem                         # 인증서 PEM 가져오기
signer -cert -password <password>         # 개인 키 비밀번호 설정

# KSP 공급자 관리
signer -register                          # Certchip KSP 공급자 등록
signer -unregister                        # KSP 공급자 등록 해제
signer -enum                              # 모든 암호화 공급자 목록
signer -container                         # 키 컨테이너 목록

# DLL 설치 (UAC 권한 자동 요청)
signer -install                           # System32에 DLL 설치
signer -uninstall                         # System32에서 DLL 제거

# 버전 및 도움말
signer -version                           # 버전 및 DLL 정보 표시
signer -help                              # 사용법 도움말 표시

# 로그인 후 표준 Windows 서명 도구 사용 (signtool 통합)
signtool sign /n "Certificate Name" /fd sha256 myapp.exe
signtool sign /sha1 <thumbprint> /fd sha256 /tr http://timestamp.digicert.com myapp.exe

예시:

# 출력 경로와 함께 직접 서명 (두 가지 동등한 형식)
signer myapp.exe -o myapp_signed.exe
signer -sign myapp.exe -o myapp_signed.exe

# 서명을 위해 전체 파일 업로드
signer myapp.exe -file-upload -o myapp_signed.exe

# _signed 접미사와 함께 해시 전용 서명
signer myapp.exe -save-signed
signer -sign myapp.exe -save-signed

버전 출력:

# signer -version
Certchip Signer v0.1.18
Windows Key Storage Provider and Code Signing Tool
Copyright (c) 2026 Certchip. All rights reserved.

DLL Versions (Local):
  otpkey.dll:   0.1.18.0
  Certchip.dll: 0.1.18.0

DLL Versions (System32):
  otpkey.dll:   0.1.18.0
  Certchip.dll: 0.1.18.0

버전 출력은 로컬과 시스템 전체 설치 간의 DLL 버전 불일치를 진단하는 데 도움이 됩니다.

cert-dist (인증서 배포)

원격 서버에서 인증서를 다운로드하고 관리합니다. SSL/TLS, 디바이스, 서명 인증서를 포함한 다양한 인증서 유형을 지원합니다.

지원되는 인증서 유형:

SSL/TLS 서버 인증서 (Let's Encrypt 포함)
디바이스 인증서
코드 서명 인증서
문서 서명 인증서

# 인증서 상태 확인
signercli -cert-dist status <domain> -api-key <key> -host <url>

# 갱신 필요 여부 확인
signercli -cert-dist check <domain> -api-key <key> -host <url>

# 인증서 다운로드
signercli -cert-dist download <domain> -api-key <key> -host <url> [-format <type>] [-o <dir>]

# 인증서 갱신 트리거
signercli -cert-dist renew <domain> -api-key <key> -host <url> [-force] [-wait|-no-wait]

# 사용 가능한 도메인 목록
signercli -cert-dist list -api-key <key> -host <url>

# 전체 동기화 (확인 + 갱신 + 다운로드)
signercli -cert-dist sync <domain> -api-key <key> -host <url> [-reload-cmd <cmd>]

# 도움말
signercli -cert-dist help

API 키 권한 모드

API 키는 두 가지 권한 모드를 지원합니다:

모드	설명
`explicit`	API 키에 명시적으로 할당된 권한만 사용
`inherited`	연결된 사용자 계정의 역할 및 그룹에서 권한 상속

Explicit 모드:

API 키 생성 시 권한 설정
최소 권한 원칙 적용에 이상적
사용자 권한이 변경되어도 권한 변경 없음

Inherited 모드:

연결된 사용자 계정에서 권한 가져옴
사용자 권한 변경 시 API 키 권한도 자동 업데이트
여러 API 키를 가진 사용자의 관리 간소화

확장 권한

권한	설명	cert-dist	cert-api	letsencrypt
`read`	인증서 정보 보기	✅	✅	✅
`renew`	인증서 갱신	✅	-	-
`download`	인증서 다운로드	✅	✅	✅
`upload`	인증서/키 업로드	-	✅	-
`delete`	인증서/키 삭제	-	✅	-
`edit`	메타데이터 편집	-	✅	-
`csr`	CSR 생성	-	✅	-
`hsm`	HSM 작업 (protect/unprotect)	-	✅	-
`letsencrypt`	Let's Encrypt SSL 인증서 관리	-	-	✅
`all`	모든 권한	✅	✅	✅

사용자 계정 연결

API 키에 사용자 계정을 연결하면:

감사 추적: API 호출 로그에 연결된 사용자 정보 포함
권한 상속: inherited 모드로 사용자 권한 자동 적용
리소스 접근: 연결된 사용자가 소유한 인증서/키에 접근

명령별 형식 옵션:

명령	`-format json`	파일 형식
`status`	✅ JSON 출력	-
`check`	✅ JSON 출력	-
`list`	✅ JSON 출력	-
`renew`	✅ JSON 출력	-
`download`	✅ JSON 출력	nginx, pem, letsencrypt, json (파일)
`sync`	✅ JSON 출력	nginx, pem, letsencrypt

다운로드 파일 형식:

형식	설명	생성되는 파일
`nginx`	Nginx 형식 (기본)	`<domain>.crt`, `<domain>.key`
`pem`	표준 PEM 형식	`<domain>.fullchain.pem`, `<domain>.privkey.pem`
`letsencrypt`	Let's Encrypt 스타일	`<domain>/cert.pem`, `<domain>/chain.pem`, `<domain>/fullchain.pem`, `<domain>/privkey.pem`
`json`	JSON 형식	`<domain>.json`

예시:

# Nginx 형식으로 다운로드 (기본)
signercli -cert-dist download example.com -api-key cdk_xxx -host https://signer.example.com:7443

# Let's Encrypt 스타일로 다운로드
signercli -cert-dist download example.com -api-key cdk_xxx -host https://signer.example.com:7443 \
    -format letsencrypt -o /etc/letsencrypt/live

# 자동화: 필요시 갱신, 다운로드, Nginx 재시작
signercli -cert-dist sync example.com -api-key cdk_xxx -host https://signer.example.com:7443 \
    -o /etc/nginx/ssl -reload-cmd "systemctl reload nginx"

# 스크립팅용 JSON 형식으로 상태 가져오기
signercli -cert-dist status example.com -api-key cdk_xxx -host https://signer.example.com:7443 -format json

종료 코드:

0: 성공 (check 명령: 갱신 불필요)
1: 오류
2: 갱신 필요 (check 명령만)

cert-api (인증서 관리 API)

일반 인증서 및 키 관리 명령입니다. cert-dist와 동일한 API 키를 사용합니다.

세 가지 명령 시스템:

명령	목적	API 엔드포인트
`-cert-dist`	Let's Encrypt 인증서 배포/갱신	`/api/cert-distribution`
`-cert`, `-privkey`, `-pubkey`, `-csr`	일반 인증서/키 관리	`/api/cert-api`
`-letsencrypt`	Let's Encrypt SSL 인증서 직접 관리	`/api/cert-api/letsencrypt`

API 키 인증 (-api-key)

API 키는 SSH 키 기반 로그인 없이 직접 API 접근을 허용합니다.

API 키란?

서버에서 발급한 고유 인증 토큰 (형식: cdk_ 접두사 + 64자 16진수)
SSH 키 기반 챌린지-응답 로그인의 대안
CI/CD 파이프라인, 자동화 스크립트, 프로그래밍 방식 접근에 이상적

API 키 형식:

cdk_e2f369e7c85bfa7835d375f6b088f15dac2c2d8ebeb0815c392a6d6b34ee916f

사용 방법:

# 방법 1: 명령줄에 직접 지정
signercli -cert list -api-key cdk_xxx -host https://server:7443

# 방법 2: 프로필에 저장 (권장)
signercli -config set default -host https://server:7443 -api-key cdk_xxx
signercli -cert list  # api-key와 host 자동 적용

# 방법 3: 명명된 프로필 사용
signercli -config set production -host https://prod:7443 -api-key cdk_prod_key
signercli -cert list -profile production

지원되는 명령:

명령	설명
`-cert`	인증서 관리 (목록, 업로드, 다운로드, 삭제)
`-cert-dist`	Let's Encrypt 인증서 배포/갱신
`-letsencrypt`	Let's Encrypt SSL 인증서 직접 관리
`-privkey`	개인 키 관리
`-pubkey`	공개 키 관리
`-csr`	인증서 서명 요청 생성

로그인 인증 vs API 키 인증:

측면	로그인 인증	API 키 인증
방법	SSH 키 챌린지-응답	직접 API 키 전송
토큰 만료	예 (기본 24시간)	서버 설정에 따라 다름
명령	`-login` 후 모든 명령	`-cert`, `-cert-dist` 등만
적합한 용도	대화형 사용, 코드 서명	자동화, CI/CD, 스크립트

보안 참고사항:

API 키를 비밀번호처럼 보호
설정 파일 권한 설정: chmod 600 ~/.signer/config
스크립트에 API 키 하드코딩 금지
CI/CD 환경에서 시크릿 매니저 사용

인증서 명령 (-cert)

# 인증서 목록
signercli -cert list -api-key <key> [-host <url>]

# 인증서 세부 정보 가져오기
signercli -cert get <id> -api-key <key>

# 인증서 업로드 (기본: DB 저장)
signercli -cert upload <file> -name "Certificate Name" -api-key <key>

# Software HSM에 인증서 업로드 (PIN 불필요)
signercli -cert upload <file> -name "My Cert" -storage SW_HSM -api-key <key>

# Hardware HSM에 인증서 업로드 (슬롯 및 PIN 필요)
signercli -cert upload <file> -name "My Cert" -storage HW_HSM -hsm-slot 0 -hsm-pin <pin> -api-key <key>

# 인증서 다운로드 (PEM/DER)
signercli -cert download <id> -format pem -o <dir> -api-key <key>

# 인증서 다운로드 (PFX)
signercli -cert download-pfx <id> -password <pwd> -o <dir> -api-key <key>

# 인증서 메타데이터 업데이트
signercli -cert update <id> -name "New Name" -desc "Description" -api-key <key>

# 인증서 삭제
signercli -cert delete <id> -api-key <key>

# 관련 개인 키와 함께 인증서 삭제
signercli -cert delete <id> -delete-related -api-key <key>

# HSM 인증서 삭제 (PIN 필요)
signercli -cert delete <id> -hsm-pin <pin> -api-key <key>

저장소 유형:

유형	설명	요구사항
`DB`	데이터베이스 저장소 (기본)	없음
`SW_HSM`	Software HSM (암호화 저장소)	없음
`HW_HSM`	Hardware HSM (PKCS#11 장치)	`-hsm-slot`, `-hsm-pin`

API 키와 함께 프로필 사용:

모든 명령에서 API 키를 지정하지 않으려면 프로필에 API 키를 저장할 수 있습니다:

# API 키로 프로필 구성 (일회성 설정)
signercli -config set default -host https://server:7443 -api-key cdk_xxx

# 이제 -api-key와 -host 없이 -cert 명령 사용
signercli -cert list
signercli -cert get <id>
signercli -cert upload cert.pem -name "My Cert"

# 또는 명명된 프로필 사용
signercli -config set myserver -host https://server:7443 -api-key cdk_xxx
signercli -cert list -profile myserver

테스트 인증서 생성 (OpenSSL)

-cert upload 및 기타 인증서 명령을 테스트하기 위해 OpenSSL로 테스트 인증서를 생성할 수 있습니다.

Linux / macOS

1. 자체 서명 인증서 (간단)

# RSA 키 + 인증서를 한 번에 생성
openssl req -x509 -newkey rsa:2048 -keyout test_key.pem -out test_cert.pem -days 365 -nodes \
  -subj "/C=KR/ST=Seoul/L=Gangnam/O=TestOrg/OU=Dev/CN=Test Certificate"

# 인증서 확인
openssl x509 -in test_cert.pem -text -noout

2. 코드 서명 인증서

# 개인 키 생성
openssl genrsa -out codesign_key.pem 2048

# 코드 서명 확장이 포함된 인증서 생성
openssl req -new -x509 -key codesign_key.pem -out codesign_cert.pem -days 365 \
  -subj "/C=KR/O=MyCompany/CN=Code Signing Certificate" \
  -addext "keyUsage=digitalSignature" \
  -addext "extendedKeyUsage=codeSigning"

3. PFX/P12 번들 (키 + 인증서)

# PEM 파일에서 PFX 생성
openssl pkcs12 -export -out test_bundle.pfx \
  -inkey test_key.pem -in test_cert.pem \
  -password pass:test1234

4. DER 형식 인증서

# PEM을 DER로 변환
openssl x509 -in test_cert.pem -outform DER -out test_cert.der

5. 전체 테스트 스크립트 (Linux/macOS)

#!/bin/bash
# create_test_certs.sh
mkdir -p test_certs && cd test_certs

# 기본 테스트 인증서
openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes \
  -subj "/CN=Test Certificate"

# 코드 서명 인증서
openssl req -x509 -newkey rsa:4096 -keyout codesign_key.pem -out codesign_cert.pem -days 365 -nodes \
  -subj "/C=KR/O=TestOrg/CN=Code Signing Test" \
  -addext "keyUsage=digitalSignature" \
  -addext "extendedKeyUsage=codeSigning"

# PFX 번들
openssl pkcs12 -export -out bundle.pfx -inkey key.pem -in cert.pem -password pass:test1234

# DER 형식
openssl x509 -in cert.pem -outform DER -out cert.der

echo "Created files:"
ls -la

Windows (PowerShell / CMD)

참고: Windows에서는 OpenSSL이 설치되어 있어야 합니다. 다음을 통해 설치할 수 있습니다:

Git for Windows (Git Bash에 OpenSSL 포함)

MSYS2 (pacman -S openssl)

OpenSSL for Windows

1. 자체 서명 인증서 (PowerShell)

# Git Bash OpenSSL 사용 (필요에 따라 경로 조정)
& "C:\Program Files\Git\usr\bin\openssl.exe" req -x509 -newkey rsa:2048 `
  -keyout test_key.pem -out test_cert.pem -days 365 -nodes `
  -subj "/C=KR/ST=Seoul/L=Gangnam/O=TestOrg/OU=Dev/CN=Test Certificate"

# 인증서 확인
& "C:\Program Files\Git\usr\bin\openssl.exe" x509 -in test_cert.pem -text -noout

2. Windows 기본 방식 사용 (certreq + PowerShell)

# PowerShell을 사용하여 자체 서명 인증서 생성
$cert = New-SelfSignedCertificate -DnsName "Test Certificate" `
  -CertStoreLocation "Cert:\CurrentUser\My" `
  -KeyUsage DigitalSignature `
  -Type CodeSigningCert `
  -NotAfter (Get-Date).AddYears(1)

# PFX로 내보내기
$password = ConvertTo-SecureString -String "test1234" -Force -AsPlainText
Export-PfxCertificate -Cert $cert -FilePath "test_bundle.pfx" -Password $password

# 인증서만 내보내기 (CER/DER 형식)
Export-Certificate -Cert $cert -FilePath "test_cert.cer" -Type CERT

# 인증서 정보 표시
$cert | Format-List Subject, Thumbprint, NotAfter

3. 전체 테스트 스크립트 (Windows CMD with Git Bash OpenSSL)

@echo off
REM create_test_certs.bat
REM OpenSSL 필요 (Git Bash 또는 독립 설치)

set OPENSSL="C:\Program Files\Git\usr\bin\openssl.exe"
mkdir test_certs 2>nul
cd test_certs

REM 기본 테스트 인증서
%OPENSSL% req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes -subj "/CN=Test Certificate"

REM 코드 서명 인증서
%OPENSSL% req -x509 -newkey rsa:4096 -keyout codesign_key.pem -out codesign_cert.pem -days 365 -nodes -subj "/C=KR/O=TestOrg/CN=Code Signing Test" -addext "keyUsage=digitalSignature" -addext "extendedKeyUsage=codeSigning"

REM PFX 번들
%OPENSSL% pkcs12 -export -out bundle.pfx -inkey key.pem -in cert.pem -password pass:test1234

REM DER 형식
%OPENSSL% x509 -in cert.pem -outform DER -out cert.der

echo Created files:
dir /b

4. 전체 테스트 스크립트 (Windows PowerShell Native)

# create_test_certs.ps1
# Windows 기본 인증서 API 사용 (OpenSSL 불필요)

$testDir = "test_certs"
New-Item -ItemType Directory -Force -Path $testDir | Out-Null
Set-Location $testDir

$password = ConvertTo-SecureString -String "test1234" -Force -AsPlainText

# 기본 테스트 인증서
$basicCert = New-SelfSignedCertificate -DnsName "Test Certificate" `
  -CertStoreLocation "Cert:\CurrentUser\My" `
  -NotAfter (Get-Date).AddYears(1)

Export-PfxCertificate -Cert $basicCert -FilePath "bundle.pfx" -Password $password
Export-Certificate -Cert $basicCert -FilePath "cert.cer" -Type CERT
Export-Certificate -Cert $basicCert -FilePath "cert.der" -Type CERT

# 코드 서명 인증서
$codeCert = New-SelfSignedCertificate -Subject "CN=Code Signing Test, O=TestOrg, C=KR" `
  -CertStoreLocation "Cert:\CurrentUser\My" `
  -KeyUsage DigitalSignature `
  -Type CodeSigningCert `
  -NotAfter (Get-Date).AddYears(1)

Export-PfxCertificate -Cert $codeCert -FilePath "codesign_bundle.pfx" -Password $password

# 인증서 저장소에서 정리 (선택 사항)
# Remove-Item -Path $basicCert.PSPath
# Remove-Item -Path $codeCert.PSPath

Write-Host "Created files:"
Get-ChildItem

테스트 업로드 명령 (모든 플랫폼)

# PEM 인증서 업로드
signercli -cert upload test_certs/cert.pem -name "Test Cert" -api-key <key> -host https://server:7443

# PFX 번들 업로드
signercli -cert upload test_certs/bundle.pfx -name "PFX Bundle" -api-key <key> -host https://server:7443

# DER 인증서 업로드
signercli -cert upload test_certs/cert.der -name "DER Cert" -api-key <key> -host https://server:7443

파일 형식 요약

형식	확장자	설명	생성 도구
PEM	`.pem`, `.crt`	Base64 인코딩, 텍스트 형식	OpenSSL
DER	`.der`, `.cer`	바이너리 형식	OpenSSL, Windows
PFX/P12	`.pfx`, `.p12`	키 + 인증서 번들	OpenSSL, Windows

개인 키 명령 (-privkey)

# 개인 키 목록
signercli -privkey list -api-key <key>

# 개인 키 세부 정보 가져오기
signercli -privkey get <id> -api-key <key>

# 개인 키 업로드 (기본: DB 저장)
signercli -privkey upload <file> -api-key <key>

# 암호화된 개인 키 업로드
signercli -privkey upload <file> -password <pwd> -api-key <key>

# Software HSM에 개인 키 업로드
signercli -privkey upload <file> -storage SW_HSM -api-key <key>

# Hardware HSM에 개인 키 업로드
signercli -privkey upload <file> -storage HW_HSM -hsm-slot 0 -hsm-pin <pin> -api-key <key>

# 개인 키 삭제
signercli -privkey delete <id> -api-key <key>

# HSM 개인 키 삭제 (PIN 필요)
signercli -privkey delete <id> -hsm-pin <pin> -api-key <key>

# 인증서에 개인 키 연결
signercli -privkey link <key-id> <cert-id> -api-key <key>

# 인증서에서 개인 키 연결 해제
signercli -privkey unlink <key-id> -api-key <key>

공개 키 명령 (-pubkey)

# 공개 키 목록
signercli -pubkey list -api-key <key>

# 인증서에서 공개 키 추출
signercli -pubkey extract <cert-id> -api-key <key>

# 사용자 정의 이름으로 추출
signercli -pubkey extract <cert-id> -name "Public Key Name" -api-key <key>

CSR 명령 (-csr)

# CSR 생성
signercli -csr generate -cn <common-name> -api-key <key>

# 전체 주체로 CSR 생성
signercli -csr generate \
  -cn example.com \
  -c KR \
  -st Seoul \
  -l Gangnam \
  -org "Example Corp" \
  -ou "IT Department" \
  -email admin@example.com \
  -keysize 4096 \
  -api-key <key>

# CSR을 파일로 저장
signercli -csr generate -cn example.com -o <dir> -api-key <key>

Let's Encrypt 명령 (-letsencrypt)

서버에 저장된 Let's Encrypt SSL 인증서의 직접 관리. SYSTEM_ADMIN 역할 또는 명시적 letsencrypt 권한이 필요합니다.

참고: 이 명령은 서버에 저장된 Let's Encrypt 인증서에 직접 접근하며, -cert-dist는 외부 서버/장치에 인증서를 배포하기 위한 것입니다.

인증:

두 가지 방법 중 하나로 인증할 수 있습니다:

먼저 로그인 - 로그인 세션의 JWT 토큰 사용 (API 키 불필요)
API 키 - API 키를 직접 제공

# 방법 1: 먼저 로그인 후 API 키 없이 명령 사용
signercli -login https://signer.example.com:7443 admin
signercli -letsencrypt list

# 방법 2: API 키를 직접 사용
signercli -letsencrypt list -api-key <key>

접근 제어:

인증	조건	접근
JWT	role = `SYSTEM_ADMIN`	✅ 허용
JWT	role = `OPERATION_MANAGER` 또는 `USER`	❌ 거부
API 키 (inherited)	linkedUserRole = `SYSTEM_ADMIN`	✅ 허용
API 키 (inherited)	linkedUserRole ≠ `SYSTEM_ADMIN`	❌ 거부
API 키 (explicit)	permissions에 `letsencrypt` 또는 `all` 포함	✅ 허용
API 키 (explicit)	permissions에 `letsencrypt` 미포함	❌ 거부

명령:

명령	설명
`list`	Let's Encrypt 인증서 목록
`get <id>`	인증서 세부 정보 가져오기
`download <id>`	인증서 파일 다운로드
`request`	새 인증서 요청 (HTTP-01 또는 DNS-01)
`dns-request`	DNS-01 챌린지 시작 (챌린지 ID 출력)
`dns-request -interactive`	DNS-01 챌린지 (대화형 모드)
`dns-complete`	DNS-01 챌린지 완료
`dns-providers`	사용 가능한 DNS 공급자 목록
`renew <id>`	인증서 갱신 (자동)
`renew-dns <id>`	수동 DNS-01 갱신 시작 (챌린지 ID 출력)
`renew-dns <id> -interactive`	수동 DNS-01 갱신 (대화형 모드)
`delete <id>`	인증서 삭제
`auto-renewal <id>`	자동 갱신 활성화/비활성화
`activate <id>`	Signer 서버의 SSL 인증서로 설정

목록/가져오기/다운로드 옵션:

옵션	설명	기본값
`-api-key <key>`	API 키 (로그인한 경우 선택 사항)	-
`-host <url>`	서버 URL	`https://localhost:7443`
`-format <type>`	출력 형식: text, json	text
`-env <environment>`	환경별 필터: staging, production	-
`-domain <pattern>`	도메인별 필터 (`` 와일드카드 지원, 예: `.example.com`)	-
`-type <type>`	다운로드 유형: cert, chain, fullchain, key, all	fullchain
`-o <dir>`	다운로드 출력 디렉토리	현재 디렉토리
`-naming <style>`	파일명 스타일: `letsencrypt` 또는 `domain`	letsencrypt

요청 옵션:

옵션	설명	기본값
`-domain <domain>`	인증서용 도메인 이름 (필수)	-
`-email <email>`	Let's Encrypt 계정용 연락처 이메일 (필수)	-
`-agree-tos`	Let's Encrypt 이용약관 동의 (필수)	-
`-env <environment>`	환경: staging, production	staging
`-key-type <type>`	키 유형: RSA, ECDSA	RSA
`-keysize <bits>`	키 크기: 2048, 4096 등	2048
`-san <domains>`	Subject Alternative Names (쉼표로 구분)	-
`-challenge <type>`	챌린지 유형: http-01, dns-01	http-01
`-dns-provider <mode>`	DNS 공급자 모드: auto, selected (dns-01용)	auto
`-provider-id <id>`	DNS 공급자 ID (-dns-provider를 'selected'로 자동 설정)	-

DNS-01 챌린지 옵션 (dns-request/dns-complete용):

옵션	설명	기본값
`-interactive, -i`	대화형 모드: Enter 대기 후 완료 (dns-request)	-
`-challenge-id <id>`	dns-request의 챌린지 ID (dns-complete용)	-

자동 갱신 옵션:

옵션	설명
`-enable`	자동 갱신 활성화
`-disable`	자동 갱신 비활성화

# Let's Encrypt 인증서 목록
signercli -letsencrypt list                          # 로그인 토큰 사용
signercli -letsencrypt list -api-key <key>           # API 키 사용

# 환경별 필터
signercli -letsencrypt list -env production
signercli -letsencrypt list -env staging

# 도메인별 필터 (부분 일치 또는 와일드카드)
signercli -letsencrypt list -domain example.com
signercli -letsencrypt list -domain api              # api.example.com 등과 일치
signercli -letsencrypt list -domain "*.example.com"  # 와일드카드 인증서와 일치

# 필터 조합
signercli -letsencrypt list -env production -domain example.com

# 인증서 세부 정보 가져오기
signercli -letsencrypt get <id>

# 인증서 다운로드 (기본: fullchain)
signercli -letsencrypt download <id>

# 특정 유형 다운로드
signercli -letsencrypt download <id> -type cert      # 인증서만
signercli -letsencrypt download <id> -type chain     # 체인만
signercli -letsencrypt download <id> -type fullchain # 전체 체인 (기본)
signercli -letsencrypt download <id> -type key       # 개인 키
signercli -letsencrypt download <id> -type all       # 모든 파일

# 특정 디렉토리로 다운로드 (기본: cert.pem, privkey.pem 등)
signercli -letsencrypt download <id> -type all -o /etc/ssl

# 도메인 기반 이름으로 다운로드 (<domain>.crt, <domain>.key 등)
signercli -letsencrypt download <id> -type all -o /etc/ssl -naming domain

다운로드 유형:

유형	설명	Let's Encrypt (기본)	도메인 스타일
`cert`	인증서만	`cert.pem`	`<domain>.crt`
`chain`	중간 체인	`chain.pem`	`<domain>.chain.crt`
`fullchain`	인증서 + 체인 (기본)	`fullchain.pem`	`<domain>.fullchain.crt`
`key`	개인 키	`privkey.pem`	`<domain>.key`
`all`	모든 파일	위의 모든 파일	위의 모든 파일

출력 옵션:

# JSON 형식 출력
signercli -letsencrypt list -format json

# 테이블 형식 출력
signercli -letsencrypt list -format table

예시:

# 먼저 로그인 (대화형 사용 시 권장)
signercli -login https://signer.example.com:7443 admin

# 모든 프로덕션 인증서 목록
signercli -letsencrypt list -env production

# 특정 도메인의 인증서 목록
signercli -letsencrypt list -domain example.com

# 특정 인증서 세부 정보 가져오기
signercli -letsencrypt get 6789abcd

# /etc/nginx/ssl에 fullchain 다운로드
signercli -letsencrypt download 6789abcd -type fullchain -o /etc/nginx/ssl

# Nginx 구성용 모든 파일 다운로드
signercli -letsencrypt download 6789abcd -type all -o /etc/nginx/ssl

# API 키 사용 (자동화/스크립트용)
signercli -letsencrypt list -env production -api-key cdk_xxx -host https://signer.example.com:7443

# --- HTTP-01 챌린지 (기본) ---
# 새 인증서 요청 (스테이징 환경 - 테스트용)
signercli -letsencrypt request -domain example.com -email admin@example.com -agree-tos

# 프로덕션 인증서 요청
signercli -letsencrypt request -domain example.com -email admin@example.com -agree-tos -env production

# Subject Alternative Names와 함께 인증서 요청
signercli -letsencrypt request -domain example.com -san "www.example.com,api.example.com" -email admin@example.com -agree-tos

# --- DNS 공급자를 사용한 DNS-01 챌린지 ---
# 도메인에 대한 DNS 공급자 자동 감지 (dns-01 사용 시 기본)
signercli -letsencrypt request -domain example.com -email admin@example.com -agree-tos \
    -challenge dns-01

# 특정 DNS 공급자 사용 (provider-id가 모드를 'selected'로 자동 설정)
signercli -letsencrypt request -domain example.com -email admin@example.com -agree-tos \
    -challenge dns-01 -provider-id 6789abc

# DNS 공급자를 사용한 와일드카드 인증서 (자동 모드)
signercli -letsencrypt request -domain "*.example.com" -email admin@example.com -agree-tos \
    -challenge dns-01 -env production

# --- DNS-01 챌린지 (수동 - 2단계 프로세스) ---
# 1단계: DNS 챌린지 시작 (추가할 TXT 레코드 가져오기)
signercli -letsencrypt dns-request -domain example.com -email admin@example.com -agree-tos
# 2단계: DNS에 TXT 레코드 추가 후 챌린지 완료
signercli -letsencrypt dns-complete -challenge-id <challenge-id>

# --- DNS-01 챌린지 (수동 - 대화형 모드) ---
# Enter 대기 후 자동으로 완료하는 단일 명령
signercli -letsencrypt dns-request -domain example.com -email admin@example.com -agree-tos -interactive

# --- DNS 공급자 관리 ---
# 사용 가능한 DNS 공급자 목록
signercli -letsencrypt dns-providers

# --- 인증서 갱신 ---
# 인증서 갱신 (자동 - HTTP-01 또는 자동 DNS-01용)
signercli -letsencrypt renew 6789abcd

# --- 수동 DNS-01 갱신 (2단계 프로세스) ---
# 1단계: 갱신 시작 (DNS 레코드 및 챌린지 ID 가져오기)
signercli -letsencrypt renew-dns 6789abcd
# 2단계: DNS에 TXT 레코드 추가 후 갱신 완료
signercli -letsencrypt dns-complete -challenge-id <challenge-id>

# --- 수동 DNS-01 갱신 (대화형 모드) ---
# Enter 대기 후 자동으로 완료하는 단일 명령
signercli -letsencrypt renew-dns 6789abcd -interactive

# 인증서 삭제
signercli -letsencrypt delete 6789abcd

# 자동 갱신 활성화
signercli -letsencrypt auto-renewal 6789abcd -enable

# 자동 갱신 비활성화
signercli -letsencrypt auto-renewal 6789abcd -disable

# --- 서버 SSL 인증서 활성화 ---
# HTTPS 서버용 인증서 활성화
signercli -letsencrypt activate 6789abcd

중요: 'activate' 명령에 대해

activate 명령은 지정된 Let's Encrypt 인증서를 Signer 서버 자체의 SSL 인증서로 설정합니다. 이는 활성화 후:

Signer 서버가 HTTPS 연결에 이 인증서를 사용함

Signer 서버에 연결하는 클라이언트가 이 인증서를 보게 됨

다음을 의미하지 않습니다:

❌ 인증서 자체를 활성화 또는 비활성화

❌ 인증서를 "활성" vs "비활성"으로 만들기

❌ 인증서를 게시 또는 게시 취소

발급된 모든 인증서는 활성화 상태와 관계없이 유효하고 사용 가능합니다. activate 명령은 Signer 서버가 자체 HTTPS 엔드포인트에 사용하는 인증서를 구성하기 위한 것입니다.

인증서 발급/갱신 참고사항:

시나리오	명령	설명
새 인증서
DNS-01 수동 (스크립트)	`dns-request` + `dns-complete`	자동화를 위한 2단계 프로세스
DNS-01 수동 (대화형)	`dns-request -interactive`	Enter 프롬프트가 있는 단일 명령
인증서 갱신
HTTP-01 챌린지	`renew`	HTTP 검증을 통한 자동 갱신
공급자를 사용한 DNS-01	`renew`	DNS API를 통한 자동 갱신
DNS-01 수동 (스크립트)	`renew-dns` + `dns-complete`	자동화를 위한 2단계 프로세스
DNS-01 수동 (대화형)	`renew-dns -interactive`	Enter 프롬프트가 있는 단일 명령
갱신 실패	`renew-dns`	`renew`에서 "Manual DNS renewal required" 표시 시 사용

챌린지 유형:

챌린지	설명	사용 사례
HTTP-01	포트 80에서 HTTP로 검증	표준 도메인, 인터넷 접근 가능한 서버
DNS-01	DNS TXT 레코드로 검증	와일드카드 인증서, 내부 서버, 포트 80 차단

DNS 공급자 모드:

모드	설명
`auto`	도메인 기반으로 DNS 공급자 자동 감지 (dns-01 기본)
`selected`	특정 공급자 사용 (`-provider-id` 제공 시 자동 설정)
수동	`dns-request`/`dns-complete` 명령 사용

참고: -challenge dns-01 사용 시:

-dns-provider를 지정하지 않으면 기본값은 auto

-provider-id를 지정하면 -dns-provider가 자동으로 selected로 설정

지원되는 DNS 공급자:

Cloudflare
AWS Route 53
GoDaddy
Custom Script

참고사항:

HTTP-01 챌린지 (기본)는 인터넷에서 포트 80에 접근 가능해야 합니다.
DNS-01 챌린지는 와일드카드 인증서 (예: *.example.com)에 필요합니다.
DNS 공급자를 사용한 DNS-01은 자동 갱신을 포함한 전체 자동화를 가능하게 합니다.
프로덕션 환경에는 속도 제한이 있습니다. 먼저 스테이징으로 테스트하세요.
모든 Let's Encrypt 작업에는 SYSTEM_ADMIN 역할이 필요합니다.

cert-api 공통 옵션

옵션	설명	기본값
`-api-key <key>`	API 키 (로그인한 경우 `-letsencrypt`에서 선택 사항)	-
`-host <url>`	Signer 서버 URL	`https://localhost:7443`
`-profile <name>`	설정 프로필의 설정 사용	default
`-format <type>`	출력 형식 (json, pem, der)	text
`-o <dir>`	출력 디렉토리	현재 디렉토리
`-name <name>`	업로드/생성용 이름	파일명
`-desc <text>`	설명	-
`-password <pwd>`	PFX/암호화된 키 비밀번호	-
`-storage <type>`	저장소 유형: DB, SW_HSM, HW_HSM	DB
`-hsm-slot <id>`	HSM 슬롯 ID (HW_HSM에 필수)	-
`-hsm-pin <pin>`	HSM PIN (HSM 객체용)	-
`-include-chain`	인증서 체인 포함	-
`-delete-related`	관련 개인 키 삭제	-

DLL 시스템 설치 (Windows)

시스템 전체 DLL 접근 (signtool 통합에 필요)을 위해 DLL을 System32에 설치합니다:

# 두 도구 모두 필요시 UAC 권한 자동 요청
signercli -install
signer -install

# System32에서 DLL 제거
signercli -uninstall
signer -uninstall

설치되는 항목:

otpkey.dll → C:\Windows\System32\otpkey.dll
Certchip.dll → C:\Windows\System32\Certchip.dll

사용 시기:

Certchip KSP 공급자와 함께 signtool.exe 사용 시
다른 애플리케이션이 DLL에 접근해야 할 때
시스템 전체 인증서 저장소 통합용

Node.js API

const signer = require('@certchip/signer');

// 로그인
await signer.login('https://signer.example.com', 'username', {
    keyPath: '~/.ssh/id_ed25519',
    expires: '24h',
    certId: 'abc123',
    includeChain: true
});

// 파일 서명
await signer.sign('myapp.exe', {
    output: 'myapp_signed.exe',
    hashAlgorithm: 'sha256',
    timestampUrl: 'http://timestamp.digicert.com'
});

// 서명 검증
const result = await signer.verify('myapp_signed.exe');
console.log(result.valid ? 'Valid' : 'Invalid');

// 설정
await signer.config('set', 'production', {
    host: 'https://signer.example.com',
    username: 'john',
    expires: '12h'
});

// 인증서 목록
const certs = await signer.listCertificates();

// 로그아웃
await signer.logout();

설정 프로필

재사용 가능한 서명 프로필 생성:

# 코드 서명 프로필 생성
signercli -config set production \
    -host https://signer.example.com \
    -username john \
    -ssh-key-path ~/.ssh/id_ed25519 \
    -expires 24h \
    -cert-id abc123 \
    -include-chain \
    -timestamp-url http://timestamp.digicert.com \
    -hash-algorithm sha256

# 시각적 서명이 있는 문서 서명 프로필 생성
signercli -config set pdf-signing \
    -host https://signer.example.com \
    -username john \
    -doc-style qrcode \
    -doc-position bottom-right \
    -doc-sig-position center \
    -doc-font-size 12 \
    -doc-opacity 0.8

# JSON 출력이 있는 자동화 프로필 생성
signercli -config set automation \
    -host https://signer.example.com \
    -output-format json

# API 키가 있는 프로필 생성 (로그인 불필요)
signercli -config set cert-api \
    -host https://signer.example.com:7443 \
    -api-key cdk_e2f369e7c85bfa7835d375f6b088f15dac2c2d8ebeb0815c392a6d6b34ee916f

# 프로필 사용
signercli -login -profile production
signercli myapp.exe -profile production          # 암시적 형식
signercli -sign myapp.exe -profile production    # 명시적 형식 (동일 결과)
signercli document.pdf -profile pdf-signing
signercli -verify myapp.exe -profile automation  # 자동으로 JSON 출력

# API 키 프로필 사용 (로그인 불필요)
signercli -cert list -profile cert-api
signercli -cert get <id> -profile cert-api
signercli -cert upload cert.pem -profile cert-api

지원되는 파일 유형

유형	확장자	방법
코드	.exe, .dll, .sys, .ocx, .msi, .msp, .cab	Authenticode
문서	.pdf	시각적 서명이 있는 서버 기반
스크립트	.ps1, .vbs	Authenticode
Java	.jar	JAR 서명
텍스트/소스	.js, .ts, .py, .java, .c, .cpp, .go, .rs, .sh, .yml, .json, .xml, .html, .sql, .md, .txt	임베디드 서명

패키지 내용

@certchip/signer/
├── lib/
│   ├── index.js          # Node.js API
│   └── index.d.ts        # TypeScript 정의
└── bin/
    ├── signercli.js      # 크로스 플랫폼 래퍼
    ├── signer.js         # Windows KSP 래퍼
    └── win32-x64/
        ├── signercli.exe # 9.3 MB (정적 빌드)
        ├── signer.exe    # 420 KB (정적 빌드)
        ├── otpkey.dll    # 6.2 MB (정적 링크)
        └── Certchip.dll  # 700 KB (KSP 공급자)

바이너리 비교

	signercli	signer
플랫폼	Windows, Linux, macOS	Windows 전용
의존성	없음 (정적 빌드)	otpkey.dll, Certchip.dll
크기	9.3 MB	420 KB + 6.9 MB DLL
서명 방법	직접 (서버 API 통해)	직접 또는 Windows 암호화 (signtool) 통해
Windows KSP	아니오	예
signtool 호환	아니오	예
UAC 자동 권한 상승	예	예
사용 사례	CI/CD, 크로스 플랫폼	Windows 개발자, signtool

예시

CI/CD 파이프라인

#!/bin/bash
set -e

# JSON 출력으로 로그인하여 파싱
result=$(signercli -login "$SIGNER_URL" -user "$SIGNER_USER" -pw "$SIGNER_PW" -format json)
if ! echo "$result" | jq -e '.success' > /dev/null; then
    echo "Login failed: $(echo "$result" | jq -r '.error')"
    exit 1
fi

# 모든 실행 파일 서명
for exe in dist/*.exe; do
    signercli "$exe"
done

# JSON 출력으로 로그아웃
signercli -logout -format json

검증이 포함된 CI/CD 파이프라인

#!/bin/bash
set -e

# JSON 출력으로 서명 및 검증
signercli -login "$SIGNER_URL" -user "$SIGNER_USER" -pw "$SIGNER_PW" -format json

for exe in dist/*.exe; do
    signercli "$exe"

    # JSON 결과 검증 및 파싱
    verify_result=$(signercli -verify "$exe" -format json)
    status=$(echo "$verify_result" | jq -r '.status')

    if [ "$status" != "valid" ]; then
        echo "Verification failed for $exe"
        exit 1
    fi
done

signercli -logout -format json

TypeScript 사용

import * as signer from '@certchip/signer';

async function signRelease() {
    await signer.login('https://signer.example.com', 'username');

    const result = await signer.sign('app.exe', {
        output: 'app_signed.exe',
        hashAlgorithm: 'sha256'
    });

    if (result.success) {
        console.log('Signed:', result.outputPath);
    }

    await signer.logout();
}

시각적 서명이 있는 문서 서명

# 로그인
signercli -login https://signer.example.com username

# QR 코드 서명으로 PDF 서명
signercli document.pdf \
    -doc-style qrcode \
    -doc-position bottom-right \
    -o document_signed.pdf

# 워터마크로 PDF 서명
signercli contract.pdf \
    -doc-style watermark \
    -doc-position center \
    -doc-opacity 0.3

signtool과 Windows KSP

REM 최초 설정 (관리자 권한으로 실행):
REM 1. System32에 DLL 설치
signercli -install

REM 2. KSP 공급자 등록
signer -register

REM 일상적인 사용:
REM 인증서 가져오기 위해 로그인
signer -login https://signer.example.com username

REM signtool로 서명
signtool sign /n "Your Certificate" /fd sha256 /tr http://timestamp.digicert.com myapp.exe

REM 검증
signtool verify /pa myapp.exe

REM 로그아웃
signer -logout

REM 제거하려면:
signer -unregister
signercli -uninstall

인증

SSH 키 (권장)

# Ed25519 키 생성 (필요한 경우)
ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519

# 기본 키로 로그인
signercli -login https://server.com username

# 특정 키로 로그인
signercli -login https://server.com username -key ~/.ssh/id_rsa

비밀번호

signercli -login https://server.com -user admin -pw password

환경 변수

변수	설명
`SIGNER_URL`	기본 서버 URL
`SIGNER_USER`	기본 사용자 이름
`SIGNER_KEY_PATH`	기본 SSH 키 경로
`SIGNER_CERT_ID`	기본 인증서 ID

문제 해결

"signer command is only available on Windows"

signer 명령은 Windows KSP 통합이 필요합니다. 크로스 플랫폼 서명에는 signercli를 사용하세요.

"DLL not found"

signer.exe는 otpkey.dll과 Certchip.dll이 필요합니다. npm을 통해 설치하면 자동으로 포함됩니다. 추가적인 MSYS2 또는 시스템 DLL은 필요하지 않습니다.

signtool 통합 또는 시스템 전체 접근을 위해 DLL을 System32에 설치하세요:

signercli -install

"Access denied" during installation

-install 명령은 관리자 권한이 필요합니다. signercli와 signer 모두 UAC 권한 상승을 자동으로 요청합니다. UAC 프롬프트가 취소되면 명령 프롬프트를 관리자 권한으로 실행하세요.

"Token expired"

다시 로그인하세요:

signercli -login https://server.com username

"Permission denied"

Linux/macOS에서 바이너리가 실행 가능한지 확인하세요:

chmod +x node_modules/@certchip/signer/bin/*/signercli

요구사항

Node.js >= 14.0.0
플랫폼: Windows x64 (Linux x64/arm64, macOS x64/arm64 곧 출시 예정)
서버: Certchip Signer API 호환 서버

참고: 현재 npm 패키지에는 Windows x64 바이너리만 포함되어 있습니다. Linux 및 macOS 바이너리는 향후 릴리스에서 추가될 예정입니다.

주요 기능​

설치​

빠른 시작​

signercli (크로스 플랫폼: Windows, Linux, macOS)​

signer (Windows 전용 - KSP 통합)​

로컬 설치 사용 시 (npx)​

CLI 명령어​

도구 비교 개요​

기능 비교​

어떤 도구를 사용해야 할까요?​

signercli (크로스 플랫폼)​

인증​

파일 서명​

서명 검증​

인증서 관리​

설정​

Windows DLL 설치​

도움말 및 디버깅​

출력 형식​

signer (Windows 전용)​

cert-dist (인증서 배포)​

API 키 권한 모드​

확장 권한​

사용자 계정 연결​

cert-api (인증서 관리 API)​

API 키 인증 (-api-key)​

인증서 명령 (-cert)​

테스트 인증서 생성 (OpenSSL)​

Linux / macOS​

Windows (PowerShell / CMD)​

테스트 업로드 명령 (모든 플랫폼)​

파일 형식 요약​

개인 키 명령 (-privkey)​

공개 키 명령 (-pubkey)​

CSR 명령 (-csr)​

Let's Encrypt 명령 (-letsencrypt)​

cert-api 공통 옵션​

DLL 시스템 설치 (Windows)​

Node.js API​

설정 프로필​

지원되는 파일 유형​

패키지 내용​

바이너리 비교​

예시​

CI/CD 파이프라인​

검증이 포함된 CI/CD 파이프라인​

TypeScript 사용​

시각적 서명이 있는 문서 서명​

signtool과 Windows KSP​

인증​

SSH 키 (권장)​

비밀번호​

환경 변수​

문제 해결​

"signer command is only available on Windows"​

"DLL not found"​

"Access denied" during installation​

"Token expired"​

"Permission denied"​

요구사항​

라이선스​

링크​

주요 기능

설치

빠른 시작

signercli (크로스 플랫폼: Windows, Linux, macOS)

signer (Windows 전용 - KSP 통합)

로컬 설치 사용 시 (npx)

CLI 명령어

도구 비교 개요

기능 비교

어떤 도구를 사용해야 할까요?

signercli (크로스 플랫폼)

인증

파일 서명

서명 검증

인증서 관리

설정

Windows DLL 설치

도움말 및 디버깅

출력 형식

signer (Windows 전용)

cert-dist (인증서 배포)

API 키 권한 모드

확장 권한

사용자 계정 연결

cert-api (인증서 관리 API)

API 키 인증 (-api-key)

인증서 명령 (-cert)

테스트 인증서 생성 (OpenSSL)

Linux / macOS

Windows (PowerShell / CMD)

테스트 업로드 명령 (모든 플랫폼)

파일 형식 요약

개인 키 명령 (-privkey)

공개 키 명령 (-pubkey)

CSR 명령 (-csr)

Let's Encrypt 명령 (-letsencrypt)

cert-api 공통 옵션

DLL 시스템 설치 (Windows)

Node.js API

설정 프로필

지원되는 파일 유형

패키지 내용

바이너리 비교

예시

CI/CD 파이프라인

검증이 포함된 CI/CD 파이프라인

TypeScript 사용

시각적 서명이 있는 문서 서명

signtool과 Windows KSP

인증

SSH 키 (권장)

비밀번호

환경 변수

문제 해결

"signer command is only available on Windows"

"DLL not found"

"Access denied" during installation

"Token expired"

"Permission denied"

요구사항

라이선스

링크