CSP 사용 설명서

개요

본 설명서는 Windows에서 sslTrus Cryptographic Service Provider(CSP)를 구성하고, Windows SDK의 Microsoft signtool.exe을 통해 클라우드 HSM으로 코드 서명을 완료하는 방법을 안내합니다.

본 프로젝트의 signtool csp는 Provider의 설치, 구성 및 유지보수를 담당하며, 실제 서명 시에는 Windows SDK의 signtool.exe를 사용합니다. 양자는 동일한 프로그램이 아닙니다.

sslTrus Cryptographic Service Provider는 기존 CryptoAPI CSP로, /csp 및 /kc를 통해 연동해야 하는 Windows 서명 프로세스에 적합합니다. 서명 개인키는 항상 클라우드 HSM에 보관되며, 로컬 컴퓨터에는 CSP DLL, 서명 인증서 및 Windows DPAPI로 보호된 접근 구성만 저장됩니다.

사용 전 준비사항

Windows x64 시스템.
Provider 설치 또는 제거 시 관리자 권한으로 실행한 터미널이 필요합니다.
본 프로젝트의 signtool CLI가 설치되어 있고, csp 하위 명령이 포함되어 있어야 합니다.
Windows SDK가 설치되어 있고 Microsoft signtool.exe을(를) 사용할 수 있어야 합니다.
유효한 Access Key, Access Secret 및 인증서 번호(CERT_CODE)가 있어야 합니다.
네트워크에서 코드 서명 서비스와 선택한 타임스탬프 서비스에 접근할 수 있어야 합니다.

두 도구가 각각 사용 가능한지 확인하세요:

REM 本项目 CLI
signtool csp --help

REM Windows SDK 工具；必要时请使用其完整路径
signtool.exe sign /?

현재 디렉터리나 PATH에 동일한 이름의 프로그램이 두 개 존재하는 경우, 반드시 전체 경로 또는 where를 통해 실제로 호출할 대상을 확인하십시오.

빠른 시작

관리자 터미널에서 순서대로 실행하십시오:

signtool csp install
signtool csp add
signtool csp list

csp add은(는) 대화형으로 다음 입력을 요청합니다:

Please enter the access key: your-access-key
Please enter the access secret: your-access-secret
Please enter the certificate code: CERT_CODE

구성이 완료되면 Windows SDK의 Microsoft signtool.exe 서명을 사용합니다:

signtool.exe sign /v ^
  /csp "sslTrus Cryptographic Service Provider" ^
  /kc CERT_CODE ^
  /f "C:\ProgramData\sslTrusKSP\CERT_CODE.crt" ^
  /fd SHA256 ^
  /tr http://timestamp.acs.microsoft.com ^
  /td SHA256 ^
  ".\app.exe"

예시의 CERT_CODE 및 app.exe를 실제 인증서 번호와 서명 대상 파일로 교체하십시오.

Provider 설치

다음을 실행하십시오:

signtool csp install

이 명령은 다음 작업을 수행합니다:

sslTrusCSP.dll를 %ProgramData%\sslTrusKSP에 기록하고 시스템 디렉터리로 복사합니다.
(Provider 유형이 PROV_RSA_AES인) sslTrus Cryptographic Service Provider를 등록합니다.
함께 제공되는 KSP DLL을 설치하고, CSP와 동일한 이름의 CNG Provider 별칭인 sslTrus Key Storage Provider를 등록합니다.
%ProgramData%\sslTrusKSP\config.dat를 생성하거나 저장합니다. 파일은 로컬 Windows DPAPI로 암호화됩니다.

설치 시 시스템 수준의 Provider 등록 정보가 수정되므로 일반적으로 관리자 터미널에서 실행해야 합니다. 시스템 디렉터리 내 CSP DLL 버전이 내장된 버전과 일치하는 경우, CLI는 CSP DLL 복사를 건너뛰지만 Provider 등록 프로세스는 계속 실행합니다.

인증서 구성 추가

실행:

signtool csp add

NICSRS 서비스 주소를 사용해야 하는 경우:

signtool csp add --address nicsrs

--address은(는) URL 패스스루 매개변수가 아닙니다. 현재 nicsrs은(는) NICSRS 서비스를 사용하며; 빈 값, racent 또는 기타 값은 기본 서비스를 사용합니다.

추가 시 CLI가 원격 서비스에서 인증서를 가져와 다음 위치에 기록합니다:

%ProgramData%\sslTrusKSP\CERT_CODE.crt

동시에 서비스 주소, 자격 증명, 인증서 번호와 인증서 경로를 암호화된 구성 파일에 기록합니다. CERT_CODE는 원격 인증서 식별자일 뿐만 아니라 이후 Microsoft signtool.exe에서 /kc의 값이기도 합니다.

이미 존재하는 인증서 번호를 추가할 경우 CLI에서 덮어쓸지 여부를 묻습니다: y를 입력하면 기존 구성을 대체하고, 바로 엔터를 누르거나 다른 값을 입력하면 기존 구성이 그대로 유지됩니다.

구성 보기 및 삭제

현재 구성 보기:

signtool csp list

출력 내용에는 인증서 번호, 서비스 유형, Access Key 및 마스킹 처리된 Access Secret가 포함됩니다. 명령 출력, 구성 파일 또는 로그를 공개된 위치에 업로드하지 마십시오.

특정 구성 삭제:

signtool csp del

안내에 따라 인증서 번호를 입력하시면 됩니다. 이 작업은 암호화 구성의 해당 항목만 삭제하며, 동일한 이름의 .crt 인증서 파일은 삭제하지 않습니다. 더 이상 사용하지 않을 경우 해당 파일을 수동으로 정리해 주세요.

Microsoft `signtool.exe` 서명 사용

SHA-256 서명

signtool.exe sign /v ^
  /csp "sslTrus Cryptographic Service Provider" ^
  /kc CERT_CODE ^
  /f "C:\ProgramData\sslTrusKSP\CERT_CODE.crt" ^
  /fd SHA256 ^
  /tr http://timestamp.acs.microsoft.com ^
  /td SHA256 ^
  ".\app.exe"

매개변수 설명:

매개변수	설명
`/csp "sslTrus Cryptographic Service Provider"`	CSP Provider를 지정합니다.
`/kc CERT_CODE`	인증서 번호에 해당하는 키 컨테이너를 지정합니다.
`/f <证书路径>`	`csp add`에서 다운로드한 인증서 파일을 지정합니다.
`/fd SHA256`	파일 다이제스트 알고리즘을 지정합니다.
`/tr <URL>`	RFC 3161 타임스탬프 서비스를 지정합니다.
`/td SHA256`	타임스탬프 다이제스트 알고리즘을 지정합니다.

현재 CSP는 SHA1, SHA256, SHA384 및 SHA512 파일 요약 알고리즘을 지원합니다. 새 서명에는 일반적으로 SHA-256 이상 버전을 사용할 것을 권장합니다. 타임스탬프 주소는 인증서 정책과 대상 플랫폼 호환성에 따라 결정해야 합니다.

SHA-1 서명 추가

구형 시스템 호환성 요구가 확실한 경우 기존 서명에 SHA-1을 추가할 수 있습니다:

signtool.exe sign /v ^
  /csp "sslTrus Cryptographic Service Provider" ^
  /kc CERT_CODE ^
  /f "C:\ProgramData\sslTrusKSP\CERT_CODE.crt" ^
  /fd SHA1 ^
  /tr http://timestamp.acs.microsoft.com ^
  /td SHA256 ^
  /as ^
  ".\app.exe"

/as는 기존 서명을 덮어쓰지 않도록 서명을 추가하는 방식을 의미합니다. SHA-1 사용 여부는 대상 시스템과 인증서 정책을 따라야 하며, 신규 프로젝트의 기본 선택지로 사용해서는 안 됩니다.

서명 검증

서명 완료 후 Microsoft signtool.exe로 검증할 수 있습니다:

signtool.exe verify /pa /v ".\app.exe"

모든 서명을 검증해야 하는 경우 Windows SDK signtool.exe의 버전과 매개변수 설명에 따라 해당 검증 옵션을 선택하세요.

Provider 제거

관리자 터미널에서 다음을 실행하세요:

signtool csp uninstall

이 명령은 CSP와 CSP와 동일한 이름의 CNG Provider alias를 등록 해제하고, CSP DLL의 ProgramData 및 시스템 디렉터리 복사본을 삭제합니다. %ProgramData%\sslTrusKSP 전체 디렉터리는 삭제하지 않으며, 함께 제공되는 sslTrus Key Storage Provider의 등록 정보와 DLL도 자동으로 제거하지 않습니다. 해당 KSP가 CSP 설치 프로세스에서만 사용되는 경우, 실제 배포 상태를 고려하여 신중하게 정리하시기 바랍니다.

제거 후 로컬의 민감한 자료를 삭제해야 하는 경우, KSP나 기타 서명 프로세스에서 더 이상 사용하지 않는 것을 확인한 후 %ProgramData%\sslTrusKSP 내의 구성, 인증서 및 로그를 수동으로 삭제하시기 바랍니다.

자주 묻는 질문

현상	처리 권장 사항
`cryptographic service provider is only supported on windows`	Windows에서 CSP 관리 명령을 실행하십시오.
설치 시 권한 오류 또는 시스템 디렉터리 쓰기 실패가 발생하는 경우	관리자 터미널에서 `signtool csp install`를 실행하십시오.
`no csp configuration`	먼저 `signtool csp install`를 실행한 후 `signtool csp add`를 실행하십시오.
`no such certificate code`	먼저 `signtool csp list`로 인증서 번호를 확인하세요.
Microsoft `signtool.exe`에서 Provider를 찾을 수 없음	설치 명령이 성공했는지, 현재 도구와 Provider가 모두 x64인지 확인한 뒤 터미널을 다시 열고 시도하세요.
서명 시 인증서 파일을 찾을 수 없음	`/f` 경로가 `csp add`에서 다운로드한 `CERT_CODE.crt`과 일치하는지 확인하세요.
서명 호출 실패	인증서 번호, 서비스 자격 증명 및 네트워크 연결을 확인한 뒤 `%ProgramData%\sslTrusKSP\sslTrusCSP.log`를 확인하세요.
사용자 정의 서비스 주소를 사용하지만 요청이 비정상인 경우	CSP는 서비스 요청 시 `/v1/codesign/sign` 경로를 고정으로 사용합니다. 구성된 서비스 주소는 `http(s)://host[:port]`만 제공해야 합니다.

보안 안내

Access Secret, config.dat, 인증서 파일 및 CSP 로그는 모두 민감 자료로 취급해야 합니다.
config.dat는 구성을 생성한 현재 Windows 사용자 프로필의 DPAPI로 보호되므로, 다른 사용자나 시스템에 직접 복사하여 재사용해서는 안 됩니다.
CSP는 개인 키를 저장하지 않습니다. 개인 키를 %ProgramData%\sslTrusKSP에 가져오려고 시도하지 마십시오.
CSP 서명은 원격 서비스 접근이 필요하며, 네트워크 타임아웃, 서버 측 거부 또는 타임스탬프 서비스를 사용할 수 없는 경우 서명이 실패할 수 있습니다.

더 많은 CLI 매개변수와 서명 명령 참조는 SignTool sign 명령 참조를 확인하십시오.

개요​

사용 전 준비사항​

빠른 시작​

Provider 설치​

인증서 구성 추가​

구성 보기 및 삭제​

Microsoft signtool.exe 서명 사용​

SHA-256 서명​

SHA-1 서명 추가​

서명 검증​

Provider 제거​

자주 묻는 질문​

보안 안내​

개요