Overview
Signing tools secifically designed for Windows typicall use CNG KSP or CAPI CSP providers. Install and use the SignPath KSP and CSP providers to use this tools with SignPath.
Installation
To install the Windows CNG KSP and CAPI CSP providers,
- Run the MSI installer file from the
Windows
subdirectory of the Crypto Providers ZIP archive. (See below for unattended options.) - Continue with the general Crypto Provider configuration.
Verification
To verify the successful registration of the CSP and KSP, you can use the following command:
certutil -csplist
It should contain two entries:
Provider Name: SignPathCSP
Provider Name: SignPathKSP
CSPs are deprecated by Microsoft, so most up-to-date tools only require a KSP. You can deselect the “Windows CAPI CSP” in the “custom setup” installer step.
Unattended installation
To install the MSI in an automated fashion, run the following command (in an elevated command prompt).
msiexec /i SignPathCryptoProviders-$Version.msi /qn /L* install.log
Installing as a prerequisite for build steps
If you want msiexec
to terminate only after the installation has completed, run the following command in a PowerShell session:
msiexec /i SignPathCryptoProviders-$Version.msi /qn /L* install.log | Out-Host; if ($LASTEXITCODE -ne 0) { throw "msiexec exited with $LASTEXITCODE" }
Selecting components
To install only parts, use the ADDLOCAL
msiexec parameter with the following options (delimited by commas):
KSP
for the Windows CNG KSP installation and registrationCSP
for the Windows CAPI CNG installation and registrationCryptoki
for the Cryptoki library installationSignPathConfigAndEnv
for the defaultCryptoProvidersConfig.json
configuration file in%ProgramFiles%\SignPath\CryptoProviders
and the system-wideSIGNPATH_CONFIG_FILE
environment variable
Example: install KSP and configuration file variable
msiexec /i SignPathCryptoProviders-$Version.msi /qn /L* install.log ADDLOCAL=KSP,SignPathConfigAndEnv | Out-Host; if ($LASTEXITCODE -ne 0) { throw "msiexec exited with $LASTEXITCODE" }
Update to a new version
Installing a new version will overwrite the existing installation.
Uninstallation
Uninstall via Windows’ “Apps & features” / “Installed apps” dialog.
Unattended uninstallation
To uninstall in an automated fashion, run the following command (in an elevated PowerShell session).
msiexec /x SignPathCryptoProviders-$Version.msi /qn /L* uninstall.log | Out-Host
Using KSP/CSP parameters of signing tools
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 different error situations when calling the SignPath REST API.
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.”) |
The CSP error code has to be retrieved via GetLastError()
.
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
/v
to 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