How-To: Sign with an Externally Generated Development Key¶
This how-to shows you how to:
- Create an RSA code-signing chain with OpenSSL outside the Keyserver.
- Import the root certificate and signing key into the Keyserver.
- 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: SignatureDiagram: 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(packagegnupg),curl,jqandxxd(packagexxd)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:
Expected output:
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:
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.
- Edit
devfwand set Required Approvers. See Step 5: Edit an Existing Key of the key management guide. - Roles → the role your signing subject holds → add
createoperation,order,getkeys,getallkeys,getoperationandcanceloperationondevfw.
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:
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:
| 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:
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:
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¶
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
.ascfiles 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
devfwtodevroot. 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.
Related pages¶
- Manage Signing Keys: import form details, key lifecycle, CSR export
- Manage Roles: building the role the signing client needs