CSP Usage Instructions

Overview

These instructions are for configuring sslTrus Cryptographic Service Provider (CSP) on Windows and using the cloud HSM for code signing through Microsoft signtool.exe in the Windows SDK.

The signtool csp in this project is responsible for installing, configuring, and maintaining the Provider; the actual signing uses signtool.exe from the Windows SDK. These are two different programs.

sslTrus Cryptographic Service Provider is a traditional CryptoAPI CSP, suitable for Windows signing workflows that need to integrate through /csp and /kc. The signing private key always remains in the cloud HSM; the local machine only stores the CSP DLL, signing certificate, and access configuration protected by Windows DPAPI.

Prerequisites

• Windows x64 system.
• A terminal running as administrator for installing or uninstalling the Provider.
• This project's signtool CLI, which includes the csp subcommand.
• Windows SDK installed, and able to use Microsoft signtool.exe.
• Valid Access Key, Access Secret, and certificate number (CERT_CODE).
• Network access to the code signing service and the selected timestamp service.

Confirm 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 the PATH, be sure to confirm the actual invocation target via the full path or where.

Quick Start

In an administrator terminal, run the following commands in sequence:

signtool csp install
signtool csp add
signtool csp list

csp add will interactively prompt for input:

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

After configuration is successful, sign using the Microsoft signtool.exe from the 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.

Installing the Provider

Run:

signtool csp install

The command will:

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

Installation modifies system-level Provider registrations and must typically be run in an elevated 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 perform the Provider registration process.

Adding Certificate Configuration

Run:

signtool csp add

If you need to use the NICSRS service address:

signtool csp add --address nicsrs

--address is not a URL pass-through parameter. Currently, nicsrs will use the NICSRS service; an empty value, racent, or any other value will use the default service.

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

%ProgramData%\sslTrusKSP\CERT_CODE.crt

Meanwhile, the service address, credentials, certificate number, and certificate path are written into the encrypted configuration file. CERT_CODE serves both as the remote certificate identifier and as the value of /kc in the subsequent Microsoft signtool.exe.

If a certificate number that already exists is added, the CLI will ask whether to overwrite: enter y to replace the old configuration; pressing Enter directly or entering any other value keeps the original configuration unchanged.

Viewing and Deleting Configuration

View the current configuration:

signtool csp list

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

To delete a configuration:

signtool csp del

Enter the certificate number as prompted. This operation only deletes the corresponding entry in the encryption configuration and does not remove the .crt certificate file with the same name; please manually clean up this file when it is no longer needed.

Using Microsoft signtool.exe Signing

SHA-256 Signing

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 description:

Parameter	Description
/csp "sslTrus Cryptographic Service Provider"	Specifies the CSP Provider.
/kc CERT_CODE	Specifies the key container corresponding to the certificate 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 the SHA1, SHA256, SHA384, and SHA512 file digest algorithms; for new signatures, SHA-256 or higher is generally recommended. The timestamp server address should be determined by your certificate policy and target platform compatibility.

Appending a SHA-1 Signature

When there is a genuine requirement for compatibility with older systems, you can append a SHA-1 signature to the existing one:

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 the signature to avoid overwriting an existing one. Whether SHA-1 is needed should follow the target system and certificate policy; it should not be the default choice for new projects.

Verifying Signatures

After signing, Microsoft signtool.exe can be used for verification:

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

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

Uninstall the Provider

Run in an administrator terminal:

signtool csp uninstall

The command will deregister the CSP, as well as the CNG Provider alias with the same name as the CSP, and delete the copies of the CSP DLL from the ProgramData and system directories. It will not delete the entire %ProgramData%\sslTrusKSP directory, nor will it automatically remove the associated registration and DLL of sslTrus Key Storage Provider; if this KSP is used only by the CSP installation process, please clean it up cautiously based on the actual deployment status.

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

FAQ

Issue	Recommended Action
cryptographic service provider is only supported on windows	Run the CSP management command on Windows.
Permission error or system directory write failure during installation	Use an administrator terminal to run signtool csp install.
no csp configuration	First run signtool csp install, then run signtool csp add.
no such certificate code	First, use signtool csp list to verify the certificate number.
Microsoft signtool.exe cannot find the Provider	Confirm that the installation command succeeded, that both the current tool and the Provider are x64, and reopen the terminal before trying again.
Certificate file not found during signing	Confirm that the /f path matches the csp add-downloaded CERT_CODE.crt.
Signing call failed	Check the certificate number, service credentials, and network connectivity; then review %ProgramData%\sslTrusKSP\sslTrusCSP.log.
Using a custom service address but requests fail	The CSP fixes the /v1/codesign/sign path for the requested service; the configured service address should only provide http(s)://host[:port].

Security Notes

• Access Secret, config.dat, certificate files, and CSP logs should all be treated as sensitive data.
• config.dat is protected by DPAPI under the current Windows user profile that created the configuration and should not be directly copied 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 rejections, or an unavailable timestamp service may all cause signing failures.

For more CLI parameters and signing command references, see SignTool sign command reference.