How-To: Sign with signtool and the Cryptera CNG KSP¶
Sign Windows binaries with Microsoft signtool on a Windows build agent, through the Cryptera Keyserver KSP. CNG (Cryptography API: Next Generation) is the Windows cryptography API, and a KSP (Key Storage Provider) is a CNG plug-in that gives CNG-aware tools such as signtool access to keys they do not hold. The private key stays in the Keyserver.
Signing on Linux, macOS or in containers?
Use JSign or osslsigncode through the Keyserver PKCS#11 module instead. See Sign Windows Executables (Authenticode), which also compares the three tools.
Internal Authserver for Testing Only
On the trial environment the internal Authserver may be used for testing. Production signing must authenticate through an external OAuth2/OIDC provider, such as Azure Entra ID or GitLab OIDC. See the Authentication Model.
How it works¶
sequenceDiagram
participant T as signtool
participant P as Cryptera Keyserver KSP
participant K as Keyserver
T->>P: CNG sign request (digest)
P->>K: Sign order (KSC_* credentials,<br/>given or auto-created operation)
K-->>P: Signature
P-->>T: SignatureDiagram: signtool; Cryptera Keyserver KSP; Keyserver; CNG sign request (digest); Sign order (KSC_* credentials, given or auto-created operation); Signature
The KSP reads the KSC_* environment variables of the process that runs signtool. It authenticates to the Keyserver and turns each CNG signing call into a sign order under an operation, which you either create in advance or let the KSP create. Keyserver key IDs appear as CNG key container names. The KSP supports signing only: RSA PKCS#1 v1.5 and ECDSA P-256/P-384/P-521. It does not support key creation, key import or export, decryption, or RSA-PSS padding.
The private key never reaches this machine: signtool sends only the hash, and the Keyserver returns the signature. This holds for KEYSTORE keys too: such a key leaves the Keyserver only through an explicit export.
What Windows requires of the certificate chain, and why to timestamp, is in Background: what Windows requires.
Prerequisites¶
- Windows 10/11 or Windows Server, x64 only, with HTTPS access to the Keyserver and the authorization server
- Administrator rights on the build agent, to install the KSP machine-wide
signtool.exe, which is not part of Windows. It ships with the Windows SDK (feature "Signing Tools for Desktop Apps") and with Visual Studio installs that include the SDK, underC:\Program Files (x86)\Windows Kits\10\bin\<sdk-version>\x64\.certutil.exe, built into Windows (%SystemRoot%\System32), and PowerShell, also built in. See the certutil reference.- A signing key that meets Background, and an OAuth2 client whose subject has a role built from the fwsigner nature scoped to that key. See Manage Roles in the Keyserver.
- The KSP release zip, downloaded in Step 1
Step 1: Install the Cryptera CNG KSP¶
- Download the latest release from the libcngks releases page:
cryptera-cngks-<version>.zip, containingcryptera-cngks.dll,install.ps1,uninstall.ps1andksp_tool.exe. Verify the accompanying SHA-256 checksum asset. You can also build it from source with Visual Studio 2022 and CMake. -
Extract the zip, open an elevated PowerShell prompt, and run:
This copies the DLL into
System32and registers the provider machine-wide as Cryptera Keyserver KSP. -
Verify that the provider is registered:
Expected output: a line naming
Cryptera Keyserver KSP.
To remove the provider later, run uninstall.ps1 the same way.
Step 2: Configure the Environment Variables¶
Set the variables in the environment that runs signtool:
Authenticate with either a pre-obtained token or client credentials that the KSP exchanges itself:
# Option A: a pre-obtained bearer token
$env:KSC_ID_TOKEN = "<TOKEN>"
# Option B: client credentials; the KSP requests its own token
$env:KSC_AUTH_SERVER = "https://authserver.<UNIQUE-ID>.cryptera-security.io"
$env:KSC_CLIENT_ID = "<CLIENT_ID>"
$env:KSC_CLIENT_SECRET = "<CLIENT_SECRET>"
For Option A, obtain the access token as in Step 1: Authenticate and Obtain an OAuth Token of the Authenticode guide or from your CI identity provider.
Then choose how the KSP obtains its operation. For production, create an operation in advance and have it approved, as in Step 2: Create an Operation and Step 3: Approve the Operation (If Required) of the Authenticode guide, and reference it by ID. This gives explicit control over what is signed and how many times. Create it with the same client the KSP authenticates as: by default (creatorowns) only the creator can use an operation. See also Operations and Approval.
For development or CI convenience, let the KSP create short-lived operations instead:
Optional variables:
KSC_OPERATION_DESCRIPTION: recorded in the audit log for each auto-created operation (defaultCryptera CNG signing)KSC_OPERATION_VALID_MS: validity window in milliseconds for auto-created operations (default1800000)KSC_OPERATION_USAGE_COUNT: usage count for auto-created operations (default1)KSC_TRACE_FILE: diagnostics log path; leave it unset in production
Step 3: Inspect and Bind the Key with ksp_tool¶
From the folder containing ksp_tool.exe, list the keys:
Expected output: the key IDs visible to the configured credentials, including your signing key.
Bind the key's certificate so Windows can build the signature's chain:
Expected output: the certificate's SHA-1 thumbprint. To install an externally supplied certificate or full chain instead, for example after importing a CA-issued key pair, use:
Before signing, verify:
| Check | Must be | If it is not |
|---|---|---|
.\ksp_tool.exe list | Shows your key ID | KSC_* variables missing or wrong in this environment, or the subject's role cannot see the key |
install-cert output | A thumbprint | The certificate was not bound; signtool cannot build the chain |
Step 4: Sign Using signtool¶
& "C:\Program Files (x86)\Windows Kits\10\bin\<sdk-version>\x64\signtool.exe" sign /v /fd SHA256 /tr http://timestamp.digicert.com /td SHA256 /csp "Cryptera Keyserver KSP" /kc "<key-id>" "C:\path\to\your.package"
The Keyserver produces the signature, and the sign order appears in the audit log under the active operation.
Step 5: Verify the Signature¶
or, from PowerShell:
The certificate chain shown must reach a root that the verifying machine trusts. For a development root, see Step 5: Trust the development root on Windows of the Windows development signing chain guide.
Running it in CI¶
Practices that apply to every CI signing job, such as token handling and operation budgets, are in CI practices. Specific to signtool:
- Always timestamp. Keep
/trand/tdin the pipeline. - Verify before publishing. Run Step 5 in the pipeline and fail the build on a verification error.
If something fails¶
| Symptom | Cause and fix |
|---|---|
0x80090016 (NTE_BAD_KEYSET) | KSC_* configuration missing in the environment running signtool (Step 2) |
0x80090020 (NTE_FAIL) | Authentication rejected, the Keyserver or authorization server is unreachable, or the operation is not approved |
0x80090029 (NTE_NOT_SUPPORTED) | Unsupported algorithm or padding requested, such as RSA-PSS |
0x800B0109 from signtool verify | The chain ends in a root the machine does not trust. For a development root, see Trust the development root on Windows |
Status codes behind an authentication or operation failure: Error Codes.
Related pages¶
- Build a Development Signing Chain for Windows: test signing before you have a CA-issued certificate