メインコンテンツまでスキップ

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）。
  • ネットワークからコードサイニングサービスと選択したタイムスタンプサービスにアクセスできること。

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をインストールし、sslTrus Key Storage Provider とCSPと同じ名前のCNG 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 windowsWindows上で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 コマンドリファレンス を参照してください。

に最終更新