Skip to content

How-To: Sign with an Externally Generated Development Key

This how-to shows you how to:

  1. Create an RSA code-signing chain with OpenSSL outside the Keyserver.
  2. Import the root certificate and signing key into the Keyserver.
  3. Use the imported key to Authenticode-sign a Windows executable.

Take this route when the key material must originate outside the Keyserver: migrating from an existing signing setup, or a certificate with attributes the Keyserver does not issue, such as a Code Signing Extended Key Usage (EKU).

Prefer a chain the Keyserver generates

Build a Development Signing Chain for Windows takes fewer steps, and the private key never exists outside the HSM. Import only when the key must come from elsewhere.

Development and internal testing only

The chain built here is anchored by a root you created. Binaries signed with it are trusted only on machines where you have installed that root. For distribution to anyone else, the signing certificate must chain to a publicly trusted code-signing CA. See Background: what Windows requires.

How it works

sequenceDiagram
    participant W as Workstation
    participant K as Keyserver
    participant H as HSM

    W->>W: OpenSSL generates root + signing key
    W->>K: Download PGP public keyring
    W->>W: Encrypt both private keys to that keyring
    W->>K: Import root (certificate + encrypted key)
    W->>K: Import signing key (certificate + encrypted key)
    K->>H: Install key material
    W->>K: Sign order via PKCS#11
    K-->>W: Signature

Diagram: Workstation; Keyserver; HSM; OpenSSL generates root + signing key; Download PGP public keyring; Encrypt both private keys to that keyring; Import root (certificate + encrypted key); Import signing key (certificate + encrypted key); Install key material; Sign order via PKCS#11; Signature

The Keyserver generates no key material in this flow. Each import carries a PGP-encrypted private key and its certificate, and the Keyserver stores the certificate as supplied, including extensions it would not issue itself.

Prerequisites

Examples use Ubuntu 24.04.

  • An administrative session on the Keyserver, to import keys and edit roles
  • An OAuth2 client whose subject will sign with the imported key, and its access token
  • Two unused HSM Key IDs
  • The Keyserver PKCS#11 module libpkcs11ks.so. See Getting the library.
  • openssl, gpg (package gnupg), curl, jq and xxd (package xxd)
  • wget (or download the JAR in a browser)
  • JSign 7.4 from the JSign project page, with a Java runtime (package default-jre)
  • osslsigncode (package osslsigncode, or the osslsigncode project)
  • For checking on Windows: the tools listed in the development-chain prerequisites
sudo apt install openssl gnupg curl jq xxd default-jre osslsigncode
wget https://github.com/ebourg/jsign/releases/download/7.4/jsign-7.4.jar

Step 1: Generate the chain

The chain uses RSA-2048 with SHA256. See Background: what Windows requires. OpenSSL 3.x adds basicConstraints to the self-signed root and the Subject Key Identifier and Authority Key Identifier to the leaf automatically, so leaf.ext only writes keyUsage and the code signing EKU.

mkdir -p ~/devsign && cd ~/devsign

cat > leaf.ext <<'EOF'
keyUsage=critical,digitalSignature
extendedKeyUsage=codeSigning
EOF

openssl req -x509 -newkey rsa:2048 -sha256 -days 3650 -nodes \
  -keyout devroot.key -out devroot.pem -subj "/CN=Dev Signing Root"

openssl req -newkey rsa:2048 -sha256 -nodes \
  -keyout devleaf.key -out devleaf.csr -subj "/CN=Dev Code Signing"

openssl x509 -req -in devleaf.csr -CA devroot.pem -CAkey devroot.key \
  -CAcreateserial -days 3650 -sha256 -extfile leaf.ext -out devleaf.pem

Confirm the chain before importing it:

openssl verify -CAfile devroot.pem devleaf.pem

Expected output:

devleaf.pem: OK

Confirm each private key matches its certificate. The two hashes must be identical:

openssl rsa -in devleaf.key -pubout | openssl sha256
openssl x509 -in devleaf.pem -pubkey -noout | openssl sha256

Step 2: Download the PGP keyring

In the Keyserver UI: Keys → Import key ... → Download PGP public keyring for encryption.

Download it immediately before encrypting, every time. The Keyserver's PGP key pair may be rotated, and a private key encrypted against a stale keyring cannot be decrypted. The import then fails with no useful detail.

Step 3: Encrypt both private keys

export GNUPGHOME=$(mktemp -d) && chmod 700 "$GNUPGHOME"
gpg --batch --import ~/Downloads/cryptera-pgppublickeyring.gpg

for k in devroot devleaf; do
  gpg --batch --yes --no-tty --pinentry-mode loopback \
      --encrypt --armor --trust-model always \
      --recipient "keyserver@cryptera.com" \
      --output $k.key.asc $k.key
done

head -1 devleaf.key.asc

Expected output:

-----BEGIN PGP MESSAGE-----

The import form accepts only PGP messages. --no-tty --pinentry-mode loopback stops gpg from opening a passphrase dialog that would block a script; encrypting to a public key needs no passphrase.

Step 4: Import the root, then the signing key

Key Type defaults to ROOT, and cannot be changed afterwards

The dropdown opens on ROOT. Key type is fixed once the key is created, and signing keys can only be revoked, never deleted. A signing key imported as ROOT is unrecoverable, and both its Key ID and its HSM Key ID are spent. Check the type on each import. A key of the wrong type imports and initializes normally; the first symptom is a sign order rejected with 409 and Only FW keys can be used to sign hashes.

Import each certificate only once

If an import goes wrong, generate a new certificate rather than re-importing the same one under a different Key ID. Re-importing a certificate that has been imported before does not reliably associate it with the private key supplied the second time.

Keys → Import key ... → Import PGP encrypted signingkey, once per key:

Field Root Signing key
Key ID devroot devfw
HSM Key ID an unused 4-hex value a different unused 4-hex value
Key Type ROOT FW
Key Location HSM HSM
Description 8 characters or more 8 characters or more
Import Private Key devroot.key.asc devleaf.key.asc
Import Certificate devroot.pem devleaf.pem

Both files are required; one without the other is rejected. Algorithm, parameter, hash and certificate validity come from the imported key and its certificate. For the remaining fields, such as the Distinguished Name of an imported ROOT key, see Step 5b: Import an Existing Key of the key management guide.

After each import, reload the Keys page and confirm the key is listed before continuing. An import that is rejected, for example because the HSM Key ID is already in use, may close the form without displaying an error.

Step 5: Set approvals and grant the signing client access

An imported key starts with 0 Required Approvers

The import form has no Required Approvers field, so devfw can sign without approval as soon as a role grants access to it. Set Required Approvers before you grant any access.

  1. Edit devfw and set Required Approvers. See Step 5: Edit an Existing Key of the key management guide.
  2. Roles → the role your signing subject holds → add createoperation, order, getkeys, getallkeys, getoperation and canceloperation on devfw.

Do not grant anything on devroot. It is a trust anchor and never signs. A key the caller has no rights on returns 403 and is absent from GET /api/keys entirely, which looks as though it was never created.

Step 6: Verify the import before relying on the key

Do this once per imported signing key. A sign order can return 201 with a well-formed signature that verifies against nothing; only this probe proves the Keyserver holds the private key you supplied. Run it as the signing client from Step 5.

First confirm the served certificate is the one you imported:

export KEYSERVER=https://keyserver.<UNIQUE-ID>.cryptera-security.io
export TOKEN=<the signing client's access token>

curl -sS -H "Authorization: Bearer $TOKEN" "$KEYSERVER/api/keys/devfw" \
  | jq -r .certificate > served.pem

openssl x509 -in served.pem -noout -pubkey > servedpub.pem
openssl x509 -in devleaf.pem -noout -pubkey > leafpub.pem
cmp servedpub.pem leafpub.pem && echo "certificate matches"

Expected output:

certificate matches

Then sign a known digest and verify it locally. If devfw requires approvers, approve the probe operation before the sign order. See Step 3: Approve the Operation (If Required) of the Authenticode guide.

printf 'probe' > probe.bin
DIGEST=$(openssl dgst -sha256 probe.bin | cut -d ' ' -f 2)

OPERATION_ID=$(curl -sS -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" "$KEYSERVER/api/operations" \
  -d "{\"validms\":600000,\"description\":\"Imported key verification probe\",
       \"new-keyusagerestrictions\":[{\"keyid\":\"devfw\",\"maxusagecount\":1}]}" | jq -r .id)

curl -sS -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  "$KEYSERVER/api/signorders" \
  -d "{\"operationid\":\"$OPERATION_ID\",\"keyid\":\"devfw\",\"inputdata\":\"$DIGEST\",
       \"inputformat\":\"hex\",\"signatureformat\":\"asn1\",
       \"description\":\"Imported key verification probe\"}" \
  | jq -r .result | xxd -r -p > probe.sig

openssl dgst -sha256 -verify servedpub.pem -signature probe.sig probe.bin

Expected output:

Verified OK
Check Must be If it is not
Key is listed on the Keys page Present after reload The import was rejected. Check the HSM Key ID is unused and re-import under a fresh one
Served certificate certificate matches The import did not take; do not proceed
openssl dgst -verify Verified OK The stored private key is not the one you supplied. Do not use this key: generate a new certificate and key pair and import those

Step 7: Sign

Export the variables the PKCS#11 module reads:

export KSC_API_SERVER=$KEYSERVER
export KSC_ID_TOKEN=$TOKEN

Create an operation on devfw as in Step 2: Create an Operation of the Authenticode guide (replace fw-rsa with devfw; it exports KSC_OPERATION_ID), and have it approved as in Step 3: Approve the Operation (If Required) of the same guide. Then sign:

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

java -jar jsign-7.4.jar \
  -keystore pkcs11.cfg -storetype PKCS11 \
  -tsa http://timestamp.digicert.com \
  -replace --alias devfw app.exe

Expected output includes:

Adding Authenticode signature to app.exe

Always pass -tsa. See Background: what Windows requires. If JSign prompts for a keystore password, enter any value; the module authenticates with KSC_ID_TOKEN.

JSign verifies its own output before writing the file, so a key that does not match its certificate fails here with the private key doesn't match the certificate rather than producing a bad file.

Step 8: Verify

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

Expected output, abbreviated:

Signer #0:
    Subject: CN=Dev Code Signing
    Issuer : CN=Dev Signing Root
Timestamp Server Signature verification: ok
Signature verification: ok

The chain shown must terminate in your development root.

Step 9: Trust the root on Windows

On each Windows machine that checks the signature, install devroot.pem, restrict it to code signing, and confirm with signtool verify, as described in Trust the development root on Windows. That page also covers fleet distribution and SmartScreen.

Operational notes

  • Delete the plaintext private keys once both imports are verified. The encrypted .asc files are of no further use either; the Keyserver holds the key material now.
  • An imported key is recorded as self-signed regardless of its certificate, so the Keys page does not link devfw to devroot. Signing and verification use the certificate chain and are unaffected. See Step 5b: Import an Existing Key of the key management guide.
  • Key IDs and HSM Key IDs cannot be reused. Signing keys are revoke-only, so a key you abandon keeps both. Use fresh values for each new attempt.

If something fails

Symptom Cause
Import form closes, key not on the Keys page Import rejected, commonly an HSM Key ID already in use. Re-import with a fresh one
409 Only FW keys can be used to sign hashes The key was imported with the wrong Key Type; it cannot be changed. Import again under a new Key ID
403 on GET /api/keys/devfw The calling subject has no getkeys on that key (Step 5)
409 "Need more approvers" on the probe sign order The operation is not approved yet. Approve it, or check the Required Approvers you set in Step 5
openssl dgst -verify reports failure in Step 6 The stored private key is not the one supplied. Generate a new certificate and key pair
JSign: the private key doesn't match the certificate Same cause as above, caught by JSign's own verification
osslsigncode cannot build the chain Wrong -CAfile, or the root was never imported
signtool reports 0x800B0109 The development root is not installed on that machine (Step 9)

See the Error Codes Reference for the full list.