Skip to content

How-To: Sign Windows Executables (Authenticode)

Sign Windows binaries (EXE, DLL, MSI and other PE files) with Authenticode through the Keyserver PKCS#11 module, using JSign or osslsigncode. The private key stays in the Keyserver.

Signing on a Windows build agent with signtool?

signtool signs through the Cryptera Key Storage Provider (KSP) for CNG (Cryptography API: Next Generation) instead of the PKCS#11 module. See Sign with signtool and the Cryptera CNG KSP.

Internal Authserver for Testing Only

On the trial environment the internal Authserver may be used for testing. Production Authenticode signing must authenticate through an external OAuth2/OIDC provider, such as Azure Entra ID or GitLab OIDC. See the Authentication Model.

Choosing a tool

JSign osslsigncode signtool
Runtime Java runtime Native binary, no runtime; smaller CI images Native Windows SDK tool
Platform Linux, macOS, Windows Linux, macOS, Windows Windows only
File types PE (EXE/DLL), MSI, CAB, scripts (PS1/VBS), APPX PE, MSI, CAB PE (EXE/DLL), MSI, CAB, APPX
Keyserver module PKCS#11 (libpkcs11ks.so), Java SunPKCS11 config file PKCS#11 (libpkcs11ks.so), OpenSSL pkcs11 engine CNG Key Storage Provider (libcngks)
Fit Broadest format support; a JVM is already present in many CI images Minimal containers; teams already using the OpenSSL engine setup from the other guides Windows-native build agents with no JVM or OpenSSL engine; binds the certificate into the Windows certificate store for thumbprint-based workflows
Guide This page, Step 6 This page, Step 7 Sign with signtool and the Cryptera CNG KSP

JSign and osslsigncode use the same module and the same operation workflow. This page shows JSign as the primary path and osslsigncode as the alternative.

How it works

sequenceDiagram
    participant S as JSign / osslsigncode
    participant M as libpkcs11ks.so
    participant K as Keyserver

    S->>M: PKCS11 sign request (PE digest)
    M->>K: Sign order (Bearer KSC_ID_TOKEN,<br/>operation KSC_OPERATION_ID)
    K-->>M: Signature
    M-->>S: Signature

Diagram: JSign / osslsigncode; libpkcs11ks.so; Keyserver; PKCS11 sign request (PE digest); Sign order (Bearer KSC_ID_TOKEN, operation KSC_OPERATION_ID); Signature

JSign loads the module through Java's SunPKCS11 provider, osslsigncode through the OpenSSL PKCS#11 engine. The module turns each signing call into a Keyserver sign order, as described in the PKCS#11 Library Reference. Authenticode signing therefore needs the same access token and approved operation as REST signing. The private key never reaches this machine: the signing tool 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.

Background: what Windows requires

Trust chain. Windows validates an Authenticode signature against the certificate chain, which must end in a root that the verifying machine trusts.

  • Public distribution (customers, arbitrary Windows machines): the signing certificate must chain to a publicly trusted code-signing CA (DigiCert, Sectigo and others). Have your CA issue a code-signing certificate and import that key pair into the Keyserver. See Step 5b: Import an Existing Key of the key management guide. A Keyserver-generated self-signed or internal-ROOT certificate is not trusted. Keep using the same certificate, because SmartScreen reputation accrues to it. See SmartScreen.
  • Internal distribution (your own fleet): a certificate chaining to an enterprise root that you distribute by Group Policy is enough; no public CA is needed.
  • Kernel-mode drivers need Microsoft attestation or WHQL signing through the Hardware Dev Center, which is out of scope for this guide.

Timestamping. Always pass a timestamp authority (--tsa for JSign, -t for osslsigncode). The RFC 3161 countersignature proves when the binary was signed, so signatures made while the certificate was valid stay valid after it expires. Without it, every signature becomes invalid the day the signing certificate expires, and each certificate rotation means re-signing your release history.

Algorithm. RSA with SHA256 is the most widely accepted choice, and the examples use it. JSign and osslsigncode also sign with ECDSA keys. Before you choose ECDSA, confirm that the Windows versions you target accept an ECDSA code-signing chain.

Building a development-only chain in the Keyserver

Before you have a CA-issued certificate, you can run this guide against a chain the Keyserver generates itself: a ROOT key with an RSA FW key beneath it. Windows accepts the resulting signatures only on machines where you install that root. The steps, the Windows trust-store setup and the limits of this approach are in Build a Development Signing Chain for Windows. For a chain generated outside the Keyserver, see Sign with an Externally Generated Development Key.

Prerequisites

Examples use Ubuntu 24.04.

  • A Cryptera Keyserver deployment
  • An FW signing key, certified as described in Background. The worked example is fw-rsa, an RSA-2048 key with hash SHA256. The trial environment ships only an EC key (fw-quickstart); to follow the example, create an RSA-2048 FW key first. See Create and Manage Keys in the Keyserver or Admin Configuration.
  • An OAuth2 client whose subject has a role built from the fwsigner nature scoped to the signing key. See Manage Roles in the Keyserver.
  • The Keyserver PKCS#11 module libpkcs11ks.so. See Getting the library.
  • JSign 7.4, a single JAR file from the JSign project page. It needs a Java runtime: the Ubuntu package default-jre, or any installed JDK.
  • osslsigncode, for the alternative path: the Ubuntu package osslsigncode, or a build from the osslsigncode project. It loads the module through the OpenSSL PKCS#11 engine, package libengine-pkcs11-openssl.
  • curl, jq, openssl, and pkcs11-tool (package opensc) to list key labels
  • wget (or download the JAR in a browser)
sudo apt install curl jq openssl opensc libengine-pkcs11-openssl default-jre osslsigncode
wget https://github.com/ebourg/jsign/releases/download/7.4/jsign-7.4.jar

Set the base URLs:

export KSC_API_SERVER="https://keyserver.<UNIQUE-ID>.cryptera-security.io"
export AUTHSERVER="https://authserver.<UNIQUE-ID>.cryptera-security.io/oauth2/token"

Step 1: Authenticate and Obtain an OAuth Token

Request a token. KSC_ID_TOKEN holds the OAuth2 access token:

export AUTH_CREDS=$(printf '%s' "<CLIENT_ID>:<CLIENT_SECRET>" | base64 | tr -d '\n')

export KSC_ID_TOKEN=$(
  curl -sS --tlsv1.3 \
    -X POST \
    -H "Authorization: Basic $AUTH_CREDS" \
    -d "grant_type=client_credentials" \
    "$AUTHSERVER" | jq -r .access_token
)

[ -n "$KSC_ID_TOKEN" ] && [ "$KSC_ID_TOKEN" != null ] && echo "token OK (${#KSC_ID_TOKEN} chars)"

Expected output: token OK ( followed by the token length. If it prints nothing, the credentials or the AUTHSERVER URL are wrong. The check never prints the token itself.

Step 2: Create an Operation

Create an operation that allows one signature. Replace fw-rsa with your key:

export KSC_OPERATION_ID=$(
  curl -sS --tlsv1.3 \
    -X POST "$KSC_API_SERVER/api/operations" \
    -H "Authorization: Bearer $KSC_ID_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
          "validms": 600000,
          "description": "Authenticode signing of app.exe",
          "new-keyusagerestrictions": [
            { "keyid": "fw-rsa", "maxusagecount": 1 }
          ]
        }' | jq -r .id
)

echo "$KSC_OPERATION_ID"

Expected output: an operation UUID. If it prints null, the request failed: a 404 means the keyid is unknown or the key has been revoked. The 10-minute window (validms: 600000) allows for a manual approval; CI pipelines usually use much shorter windows.

Step 3: Approve the Operation (If Required)

If the key requires approvers:

  1. Open https://keyclient.<UNIQUE-ID>.cryptera-security.io/approvaladmin
  2. Log in as an approver and approve the operation

Confirm before continuing:

curl -sS --tlsv1.3 -H "Authorization: Bearer $KSC_ID_TOKEN" \
  "$KSC_API_SERVER/api/operations/$KSC_OPERATION_ID" | jq .approved

Expected output: true. Keys with 0 required approvers are approved immediately.

Step 4: Export the Certificate

Both tools need the certificate of the signing key:

curl -sS --tlsv1.3 -H "Authorization: Bearer $KSC_ID_TOKEN" \
  "$KSC_API_SERVER/api/keys/fw-rsa" | jq -r .certificate > cert.pem

head -1 cert.pem

Expected output:

-----BEGIN CERTIFICATE-----

Step 5: Configure the PKCS#11 Environment

KSC_API_SERVER, KSC_ID_TOKEN and KSC_OPERATION_ID are already set. Add the description recorded in the audit log:

export KSC_OPERATION_DESCRIPTION="Authenticode signing of app.exe"

These variables must be set in the environment that runs JSign or osslsigncode. Full variable reference: Environment variables.

Before signing, verify:

Check Must be If it is not
env \| cut -d= -f1 \| grep '^KSC_' KSC_API_SERVER, KSC_ID_TOKEN, KSC_OPERATION_ID all set in the shell that runs JSign or osslsigncode The key alias is not found, or signing fails with an authorization error
jq .approved on the operation (Step 3) true Signing fails with 409 "Need more approvers"
head -1 cert.pem -----BEGIN CERTIFICATE----- The certificate export failed. Check the token and the key ID
The signing key's hash algorithm The same as -h (osslsigncode) or --alg (JSign, default SHA-256) The Keyserver does not check the digest length. With an RSA key a different digest gives a signature that does not verify; with an ECDSA key the signature verifies only against the digest you used

Create the Java SunPKCS11 configuration. Set library to the path of your libpkcs11ks.so:

cat > pkcs11.cfg <<'EOF'
name = CrypteraKS
library = /path/to/libpkcs11ks.so
slotListIndex = 0
EOF

Sign app.exe in place. --alias is the Keyserver key ID:

java -jar jsign-7.4.jar \
  --keystore pkcs11.cfg \
  --storetype PKCS11 \
  --tsa http://timestamp.digicert.com \
  --alias fw-rsa \
  --certfile cert.pem \
  app.exe

Expected output includes:

Adding Authenticode signature to app.exe

If JSign prompts for a keystore password, enter any value. The module ignores it and authenticates with KSC_ID_TOKEN. The sign order is recorded in the audit log under the operation from Step 2 and uses one of its maxusagecount uses.

Step 7: Sign Using osslsigncode (Alternative)

osslsigncode writes the signed binary to a new file. The object in the key URI is the Keyserver key ID; to list the labels the module can see, see Key discovery and PKCS#11 URIs.

osslsigncode sign \
  -pkcs11module /path/to/libpkcs11ks.so \
  -key "pkcs11:token=KEYSERVER;object=fw-rsa;type=private" \
  -certs cert.pem \
  -in app.exe \
  -out app-signed.exe \
  -t http://timestamp.digicert.com \
  -h sha256

Set -h to the key's hash algorithm.

Step 8: Verify the Signature

Verify the signed file: app.exe after JSign, app-signed.exe after osslsigncode. For a key under a development root, add -CAfile with that root's certificate. See Build a Development Signing Chain for Windows.

osslsigncode verify -in app.exe

Expected output includes Signature verification: ok and ends with:

Number of verified signatures: 1
Succeeded

The certificate chain shown must be your signing certificate's chain. For public distribution, also verify on a Windows machine (file properties, Digital Signatures tab), which checks trust against that machine's certificate store.

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

  • Always timestamp. Keep --tsa or -t in the pipeline. See Background: what Windows requires.
  • Verify before publishing. Run Step 8 in the pipeline and fail the build on a verification error. It catches wrong-key, wrong-certificate and missing-timestamp mistakes at build time instead of on customer machines.

If something fails

Symptom Cause and fix
Token check in Step 1 prints nothing Wrong credentials or AUTHSERVER URL
401 "The user/client is not valid" The client ID does not match a registered subject
403 "Access forbidden" The subject's role lacks the fwsigner permissions for the key
JSign cannot load the keystore Wrong library path in pkcs11.cfg, or the config file path passed to --keystore is wrong
Key alias not found KSC_API_SERVER/KSC_ID_TOKEN not exported in the signing shell, wrong --alias, or the subject cannot see the key
Signing fails with 409 "Need more approvers" Operation not approved (Step 3)
Signing fails with 410 "Operation has expired" validms elapsed. Create a new operation
Signing fails with 410 "Operation is cancelled" An approver revoked the operation, or it was cancelled. Create a new operation
Creating the operation fails with 404 The keyid is unknown, or the key has been revoked (the response does not say which)
Signing fails with 410 "Signing key has been revoked" A key named in the operation has been revoked, so the operation can no longer be used. Create a new operation with another key
Signing fails, or the signed file does not verify With an RSA key, the digest was not made with the key's configured hash algorithm. The Keyserver does not reject it; the signature does not verify. Match -h or --alg to the key
Windows shows "Unknown publisher" despite a valid signature The certificate does not chain to a root the verifying machine trusts. See Background; for a development root, Trust the development root on Windows

Full status-code reference: Error Codes. PKCS#11-specific issues: PKCS#11 Library Reference.