General instructions
This section provides information to use SignPath with any tool that supports KSP or CSP providers.
Installation
To install both CSP and KSP,
- Copy the contents of the
Windowsdirectory of the Crypto Providers ZIP archive to the target system. -
Run the following command with Administrator privileges in the destination directory:
powershell -ExecutionPolicy RemoteSigned .\InstallCspKsp.ps1 - Continue with the general Crypto Provider configuration.
Alternatively, you can also run .\InstallCspKsp.ps1 within a PowerShell or PowerShell Core session.
Verification
To verify the successful registration of the CSP and KSP, you can use the following command:
certutil -csplistIt should contain two entries:
Provider Name: SignPathCSPProvider Name: SignPathKSP
CSPs are deprecated by Microsoft and therefore most tools only require a KSP. In case you only want to install the KSP, use the following command:
powershell -ExecutionPolicy RemoteSigned .\InstallCspKsp.ps1 -InstallParts KSP
Update to a new version
Installing a new version will overwrite the existing installation.
Uninstallation
Run the following command with Administrator privileges in the installation directory:
powershell -ExecutionPolicy RemoteSigned .\InstallCspKsp.ps1 Uninstall
This removes both the CSP and KSP version (in case they are installed).
Parameters
Additionally to the general Crypto Provider configuration, specify the following values using the parameters provided by your signing tool:
| Parameter | Value | Description |
|---|---|---|
| Crypto Provider | SignPathKSP or SignPathCSP |
SignPath KSP (preferred) or CSP |
| Key container name | $ProjectSlug/$SigningPolicySlug |
Project and Signing Policy slugs, separated by a forward slash |
| Certificate file | Path to the x.509 certificate file | Download the respective certificate file from SignPath |
Keys are not specified directly
The KSP and CSP interfaces expect you to identify a key, but SignPath requires you to specify Project and Signing Policy. SignPath will select the correct key or certificate based on the Project and Signing Policy you specify.
Error handling
The following table shows the KSP HRESULT result codes for the different error situations when calling the SignPath REST API.
Note that the CSP error code has to be retrieved via GetLastError().
| Situation | error code (KSP result code or CSP GetLastError() code) |
|---|---|
| Transient errors like HTTP timeouts or 503 (Service Unavailable) which still occur after the last retry | NTE_DEVICE_NOT_READY (“The device that is required by this cryptographic provider is not ready for use.”) for errors without an HTTP status code. Otherwise, HTTP status code as an HRESULT in the FACILITY_ITF, e.g. 0x800401F7 for HTTP 503 |
| Non-transient service errors (e.g. 500 Internal Server Error) | HTTP status code as an HRESULT in the FACILITY_ITF, e.g. 0x800401F4 for HTTP 500 |
| User errors detected by service (4xx returned) | HTTP status code as an HRESULT in the FACILITY_ITF, e.g. 0x80040190 for HTTP 400 |
| Other unspecified errors (fall back) | NTE_FAIL (“An internal error occurred.”) |
SignTool.exe
SignTool.exe is a command line tool by Microsoft. SignTool.exe can use both the SignPath CSP and the SignPath KSP. We recommend using the SignPath KSP whenever possible.
Important
Only the 64-bit version of SignTool.exe is supported.
SignTool.exe requires the following parameters:
| Parameter | Value | Description |
|---|---|---|
/csp |
SignPathKSP or SignPathCSP |
SignPath KSP (preferred) or CSP |
/kc |
$ProjectSlug/$SigningPolicySlug |
Key container name: Project and Signing Policy slug, separated by a forward slash |
/fd |
SHA256, SHA384 or SHA512 |
Digest (hashing) algorithm |
/f |
Path to the certificate file | Download the respective certificate file from SignPath |
Sample: sign MyApp.exe
signtool.exe sign /csp SignPathKSP /kc "$ProjectSlug/$SigningPolicySlug" /fd SHA256 /f "certificate.cer" "MyApp.exe"
Tip: Diagnostics
Specify
/vto enable verbose output.
Warning: Produce correct timestamps
When using SignTool.exe (or any other signing tool) directly, you are responsible for correct time stamping. See Timestamps