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のインストールまたはアンインストールに使用する、管理者権限で実行されたターミナル。
- 本プロジェクトの
signtoolCLIが存在し、その中にcspサブコマンドが含まれていること。 - Windows SDKがインストールされており、Microsoftの
signtool.exeを使用できること。 - 有効なAccess Key、Access Secret、および証明書番号（
CERT_CODE）を保有していること。 - ネットワークからコード署名サービスおよび選択したタイムスタンプサービスにアクセスできること。
2つのツールがそれぞれ利用可能であることを確認します：
REM 本项目 CLI
signtool csp --help
REM Windows SDK 工具；必要时请使用其完整路径
signtool.exe sign /?
現在のディレクトリまたはPATHに同名のプログラムが2つ存在する場合は、必ず完全パスまたは 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エイリアスとして
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エイリアスを削除するとともに、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 コマンドリファレンスを参照してください。