Crypto Providers  ❯   Windows CSP and KSP

Overview

Signing tools secifically designed for Windows typically use CNG KSP or CAPI CSP providers. Install and use the SignPath KSP and CSP providers to use this tools with SignPath.

Setup

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

Configuration

See SignPath Crypto Providers for general configuration options.

Signing code

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

Using other signing tools

In addition to the general Crypto Provider configuration, specify the following values using the parameters provided by your signing tool:

Use Project and Signing Policy slugs to speficy a key

Identify a specific Signing Policy by specifying Project and Signing Policy slugs. The SignPath KSP/CSP will select that policy’s certificate.

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().