How-To: Build a Development Signing Chain for Windows¶
Build a code-signing chain inside the Keyserver (a ROOT key with an RSA FW key beneath it), trust its root on your own Windows machines, and test Authenticode signing before you have a CA-issued certificate. The trust-store and SmartScreen sections also apply to a development root generated outside the Keyserver. See Sign with an Externally Generated Development Key.
Development and internal testing only
A Keyserver-generated chain is not publicly trusted. Do not distribute binaries signed this way: on any machine without your root installed, Windows reports "Unknown publisher", and SmartScreen reputation accrues to the certificate you eventually distribute under, not to this one. For distribution, follow Background: what Windows requires.
Prerequisites¶
- An administrative session on the Keyserver, to create keys. See Create and Manage Keys in the Keyserver.
- An access token in
KSC_ID_TOKEN, obtained as in Step 1: Authenticate and Obtain an OAuth Token of the Authenticode guide. The token's subject needs a role grantinggetkeyson both keys. The ROOT key needs no signing rights. curl,jqandopensslon the machine that exports the certificates- One of the signing paths, set up: JSign or osslsigncode, or signtool and the Cryptera CNG KSP
- On each Windows machine that verifies signatures:
certutil.exe, built into Windows (%SystemRoot%\System32; see the certutil reference).Import-Certificate(PowerShell PKI module) andcertmgr.mscare built in too.- An elevated prompt, to install into the machine store
signtool.exe, to confirm the result. It 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.
The chain this page builds:
- ROOT key: Generator Algorithm RSA, Hash Algorithm SHA256
- FW key: created under that ROOT key, so its algorithm is RSA too; Hash Algorithm SHA256; Parameter
2048or larger
Step 1: Create the ROOT key¶
- Follow Admin Configuration Step 2.
- Choose RSA as the Generator Algorithm (the tutorial uses EC) and SHA256 as the Hash Algorithm. The FW key inherits its algorithm from the ROOT. For why this chain uses RSA, see Background: what Windows requires.
Step 2: Create the RSA FW key beneath it¶
- Follow Admin Configuration Step 3.
- In the Root Key field, select the ROOT key from Step 1 instead of "Self Signed". The FW key's Generator Algorithm is then locked to the ROOT's.
- Set the Hash Algorithm explicitly; it is not inherited.
- Selecting a Root Key resets Parameter to
2048. Set the key size you want after choosing the Root Key, then save.
Wait until both keys show INITIALIZED before continuing.
Step 3: Export both certificates¶
The signing tools need the FW key's certificate. The ROOT certificate is what you install into the Windows trust store:
export KSC_API_SERVER=https://keyserver.<UNIQUE-ID>.cryptera-security.io
curl -sS --tlsv1.3 -H "Authorization: Bearer $KSC_ID_TOKEN" \
"$KSC_API_SERVER/api/keys/<your FW key id>" | jq -r .certificate > cert.pem
curl -sS --tlsv1.3 -H "Authorization: Bearer $KSC_ID_TOKEN" \
"$KSC_API_SERVER/api/keys/<your ROOT key id>" | jq -r .certificate > devroot.pem
head -1 cert.pem devroot.pem
Expected output: both files begin with a PEM header.
Step 4: Sign a test binary¶
Sign with the FW key's Key ID, following Sign Windows Executables (Authenticode) or Sign with signtool and the Cryptera CNG KSP. To check the result on Linux against your own root (app-signed.exe if you signed with osslsigncode):
Expected output includes Signature verification: ok and ends with:
Step 5: Trust the development root on Windows¶
With the root in Trusted Root Certification Authorities, Windows validates the chain as it would a commercially issued one: the publisher name appears in the UAC prompt and the Digital Signatures tab, and signtool verify /pa succeeds. This holds only on machines that have the root. See What this does and does not replace.
Windows reads certificates as PEM (Base64 text) or DER (Distinguished Encoding Rules, the binary encoding). The commands below use a DER file; convert the PEM export first:
Single machine¶
From an elevated prompt, install into the machine store. It applies to every user and to services, which is what build agents need:
PowerShell equivalent:
Cert:\CurrentUser\Root needs no elevation but applies only to that user; services and scheduled builds do not see it.
A domain or a fleet¶
Use Group Policy:
Computer Configuration → Policies → Windows Settings → Security Settings → Public Key Policies → Trusted Root Certification Authorities → Import
Under Intune, deploy the same certificate as a Trusted certificate profile. Either way the root reaches every managed machine, and signed binaries validate across the estate.
Restrict the root to code signing¶
A root in the trust store is trusted for every purpose by default, including TLS server authentication, and this root's private key sits in a development Keyserver. In certmgr.msc, open the imported root under Trusted Root Certification Authorities → Properties → Enable only the following purposes, and tick Code Signing alone. The setting belongs to the store entry, not to the certificate, so apply it wherever the root is installed.
Confirm it worked¶
The output names your development root as the chain's terminating certificate. Before the root is installed, the same command fails with 0x800B0109: "A certificate chain processed, but terminated in a root certificate which is not trusted by the trust provider".
Remove the root when you are finished:
What this does and does not replace¶
| Development root, installed by you | Publicly trusted code-signing certificate | |
|---|---|---|
| Chain validates | Only where the root is installed | Every Windows machine |
| Publisher name shown | Yes, on those machines | Yes |
| SmartScreen reputation | None. Reputation accrues to the certificate with Microsoft and cannot be granted locally | Accrues with use; EV starts with it |
| Kernel-mode drivers | No | No; requires attestation or WHQL signing |
| Revocation | No CRL or OCSP endpoint; revoking means removing the root from every machine | Published CRL/OCSP |
| Appropriate for | Internal fleets and development | Distribution to anyone else |
SmartScreen¶
Installing the root removes "Unknown publisher" on machines that hold it. SmartScreen is a separate, reputation-based check, and it only checks files carrying Mark-of-the-Web (browser downloads, mail attachments, files from untrusted zones). Binaries copied over an internal share, deployed by management tooling, or built and run on the machine never get that mark, so an internal fleet sees no SmartScreen warning.
Outside the fleet, a file signed with a development root fails both checks: the machine lacks your root and the certificate has no reputation. A new commercial OV certificate also starts with no SmartScreen reputation and warns until it builds some; only EV certificates start with it. Reputation accrues to the certificate, so keep using the same one for public releases.
What to expect from a Keyserver-generated certificate¶
Certificates the Keyserver issues for FW keys carry no X.509 extensions, so no Extended Key Usage (EKU). Under RFC 5280 §4.2.1.12 an absent EKU places no restriction on the certificate, and Windows treats it as valid for all purposes, so the chain verifies for Authenticode. There is no EKU field to set when creating a key, and this path needs none. For a certificate with a Code Signing EKU, generate the chain outside the Keyserver. See Sign with an Externally Generated Development Key.
If something fails¶
| Symptom | Cause and fix |
|---|---|
| Generator Algorithm is locked to EC on the FW key | The selected ROOT key is EC. Create an RSA ROOT key (Step 1) |
| FW key has the wrong key size | Parameter was reset to 2048 when the Root Key was selected (Step 2) |
403 exporting the ROOT certificate | The subject's role has no getkeys on the ROOT key |
409 "Signing key is not initialized!" on export | The key is not INITIALIZED yet. Wait, then export again |
osslsigncode verify fails in Step 4 | Wrong -CAfile, or the FW key was not created under this ROOT |
signtool verify reports 0x800B0109 | The development root is not installed on that machine (Step 5) |
| Services or scheduled builds do not trust the root | It was installed in Cert:\CurrentUser\Root. Install it in the machine store |
Full status-code reference: Error Codes.
Related pages¶
- Manage Signing Keys: the key form, Root Key selection and the key status lifecycle