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에 쓰고 시스템 디렉터리로 복사합니다.
sslTrus Cryptographic Service Provider을(를) 등록합니다(Provider 유형: PROV_RSA_AES).
호환 KSP DLL을 설치하고 CSP와 동일한 이름의 CNG Provider alias로 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 을(를) 입력하면 기존 설정을 교체하고, 바로 Enter를 누르거나 다른 값을 입력하면 기존 설정을 그대로 유지합니다.

설정 확인 및 삭제

현재 설정 확인:

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 제거​

자주 묻는 질문​

보안 설명​

개요