Skip to content

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 granting getkeys on both keys. The ROOT key needs no signing rights.
  • curl, jq and openssl on 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) and certmgr.msc are 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 2048 or larger

Step 1: Create the ROOT key

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.

==> cert.pem <==
-----BEGIN CERTIFICATE-----

==> devroot.pem <==
-----BEGIN CERTIFICATE-----

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

osslsigncode verify -in app.exe -CAfile devroot.pem

Expected output includes Signature verification: ok and ends with:

Number of verified signatures: 1
Succeeded

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:

openssl x509 -in devroot.pem -outform DER -out devroot.cer

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:

certutil -addstore -f Root devroot.cer

PowerShell equivalent:

Import-Certificate -FilePath devroot.cer -CertStoreLocation Cert:\LocalMachine\Root

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

signtool verify /pa /v app.exe

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:

certutil -delstore Root <thumbprint>

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.