CSP User Guide

Overview

This guide is intended for configuring sslTrus Cryptographic Service Provider (CSP) on Windows and completing code signing with the cloud HSM through the Microsoft signtool.exe of the Windows SDK.

The signtool csp of this project is responsible for installing, configuring, and maintaining the Provider; the signtool.exe of the Windows SDK is used for actual signing operations. The two are not the same program.

sslTrus Cryptographic Service Provider is a traditional CryptoAPI CSP, suitable for Windows signing workflows that require access via /csp and /kc. The signing private key always remains in the cloud HSM, and only the CSP DLL, signing certificate, and access configuration protected by Windows DPAPI are stored locally.

Prerequisites

• A Windows x64 system.
• A terminal running as administrator, used for installing or uninstalling the Provider.
• The signtool CLI for this project, which includes the csp subcommand.
• Windows SDK is installed, and Microsoft signtool.exe is available for use.
• Valid Access Key, Access Secret, and certificate ID (CERT_CODE).
• Network access to the code signing service and the selected timestamping service.

Verify that both tools are available respectively:

REM 本项目 CLI
signtool csp --help

REM Windows SDK 工具；必要时请使用其完整路径
signtool.exe sign /?

If two programs with the same name exist in the current directory or in PATH at the same time, be sure to confirm the actual call target via the full path or where.

Quick Start

Execute the following in sequence in an administrator terminal:

signtool csp install
signtool csp add
signtool csp list

csp add will prompt for input interactively:

Please enter the access key: your-access-key
Please enter the access secret: your-access-secret
Please enter the certificate code: CERT_CODE

After the configuration is successful, use Microsoft signtool.exe signing for Windows SDK:

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"

Replace CERT_CODE and app.exe in the example with the actual certificate number and the file to be signed.

Install the Provider

Run:

signtool csp install

This command will:

• Write sslTrusCSP.dll to %ProgramData%\sslTrusKSP and copy it to the system directory.
• Register sslTrus Cryptographic Service Provider (with Provider type PROV_RSA_AES).
• Install the supporting KSP DLL and register a CNG Provider alias sslTrus Key Storage Provider that shares the same name as the CSP.
• Create or save %ProgramData%\sslTrusKSP\config.dat; the file is encrypted using the local Windows DPAPI.

The installation modifies system-level Provider registrations and generally must be executed in an administrator terminal. If the CSP DLL version in the system directory matches the embedded version, the CLI will skip copying the CSP DLL but will still run the Provider registration process.

Add certificate configuration

Execute:

signtool csp add

If you need to use the NICSRS service address:

signtool csp add --address nicsrs

--address is not a URL passthrough parameter. Currently, nicsrs will use the NICSRS service; empty values, racent, or other values will use the default service.

When added, the CLI will retrieve the certificate from the remote service and write it to:

%ProgramData%\sslTrusKSP\CERT_CODE.crt

The service address, credentials, certificate ID, and certificate path will also be written to the encrypted configuration file. CERT_CODE serves both as the remote certificate identifier and as the value for /kc in the subsequent Microsoft signtool.exe.

If you add an existing certificate ID, the CLI will ask whether to overwrite it: enter y to replace the old configuration; press Enter directly or enter any other value to keep the original configuration unchanged.

Viewing and Deleting Configurations

View the current configuration:

signtool csp list

The output contains the certificate number, service type, Access Key, and desensitized Access Secret. Do not upload command outputs, configuration files, or logs to public locations.

Delete a certain configuration:

signtool csp del

Follow the prompts and enter the certificate number. This operation only removes the corresponding entry from the encryption configuration and will not delete the .crt certificate file with the same name; please clean up this file manually when it is no longer needed.

Sign using Microsoft signtool.exe

SHA-256 signature

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"

Parameter descriptions:

Parameter	Description
/csp "sslTrus Cryptographic Service Provider"	Specifies the CSP Provider.
/kc CERT_CODE	Specifies the key container corresponding to the certificate serial number.
/f <证书路径>	Specifies the certificate file downloaded by csp add.
/fd SHA256	Specifies the file digest algorithm.
/tr <URL>	Specifies the RFC 3161 timestamp service.
/td SHA256	Specifies the timestamp digest algorithm.

The current CSP supports SHA1, SHA256, SHA384, and SHA512 file digest algorithms; SHA-256 or higher versions are generally recommended for new signatures. The timestamp address should be determined based on your certificate policy and the compatibility of the target platform.

Append SHA-1 signature

When compatibility with legacy systems is truly required, you can append a SHA-1 signature on top of the existing signature:

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 indicates appending a signature to avoid overwriting existing signatures. Whether SHA-1 is required should follow the target system and certificate policy; it should not be used as the default option for new projects.

Verify the signature

After signing, you can verify the signature using Microsoft signtool.exe:

signtool.exe verify /pa /v ".\app.exe"

To verify all signatures, select the corresponding verification option according to the version and parameter instructions of the Windows SDK signtool.exe.

Uninstall the Provider

Execute the following in an administrator terminal:

signtool csp uninstall

This command will unregister the CSP and its CNG Provider alias of the same name, and delete the copies of the CSP DLL in ProgramData and the system directory. It will not delete the entire %ProgramData%\sslTrusKSP directory, nor will it automatically remove the registration and DLL of the paired sslTrus Key Storage Provider; if this KSP is only used by the CSP installation process, please clean it up with caution based on the actual deployment status.

If you need to remove local sensitive data after uninstallation, please manually delete the configurations, certificates and logs in %ProgramData%\sslTrusKSP after confirming that they are no longer used by the KSP or other signing processes.

Frequently Asked Questions

Symptom	Handling Suggestion
cryptographic service provider is only supported on windows	Execute the CSP management command on Windows.
Permission errors or system directory write failures during installation	Execute signtool csp install in an administrator terminal.
no csp configuration	Execute signtool csp install first, then execute signtool csp add.
no such certificate code	First use signtool csp list to verify the certificate serial number.
Microsoft signtool.exe cannot find the Provider	Confirm that the installation command succeeded, both the current tool and the Provider are x64, then reopen the terminal and try again.
Certificate file not found during signing	Confirm that the /f path matches the CERT_CODE.crt downloaded from csp add.
Signing invocation failed	Check the certificate serial number, service credentials, and network connectivity; then check %ProgramData%\sslTrusKSP\sslTrusCSP.log.
Abnormal requests when using a custom service address	The CSP always sends requests to the /v1/codesign/sign path; the configured service address should only provide http(s)://host[:port].

Security Notes

• Access Secret, config.dat, certificate files and CSP logs must all be treated as sensitive materials.
• config.dat is protected by DPAPI under the current Windows user profile that created the configuration, and must not be copied directly for reuse by other users or machines.
• The CSP does not store private keys; do not attempt to import private keys into %ProgramData%\sslTrusKSP.
• CSP signing requires access to remote services; network timeouts, server-side rejections, or unavailable timestamp services can all cause signing failures.

For more CLI parameter and signing command reference, see SignTool sign Command Reference.