Crypto Providers  ❯  Windows CSP and KSP

• Overview
• Installation
  • Unattended installation
  • Update to a new version
  • Uninstallation
  • Unattended uninstallation
• Using KSP/CSP parameters of signing tools
• Error handling
• SignTool.exe

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,

1. Run the MSI installer file from the Windows subdirectory of the Crypto Providers ZIP archive. (See below for unattended options.)
2. 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

See msiexec documentation.

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 registration
• CSP for the Windows CAPI CNG installation and registration
• Cryptoki for the Cryptoki library installation
• SignPathConfigAndEnv for the default CryptoProvidersConfig.json configuration file in %ProgramFiles%\SignPath\CryptoProviders and the system-wide SIGNPATH_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:

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.

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:

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