How-To: Use OpenSSL 3.x with PKCS#11 for Signing¶
Sign files with OpenSSL 3.x through the Keyserver PKCS#11 module, libpkcs11ks.so. The private key stays in the Keyserver, and OpenSSL uses it as if it were on a local token.
Other PKCS#11 tools use the same module:
| Tool | Used for | Guide |
|---|---|---|
| OpenSSL | Signing and verifying files | This page |
| JSign, osslsigncode | Signing Windows executables (Authenticode) | Sign Windows Executables |
| signtool (through the Cryptera CNG KSP, not this module) | Signing Windows executables on Windows | Sign with signtool and the Cryptera CNG KSP |
| jarsigner | Signing JAR files | Sign JAR Files |
| pkcs11-tool | Listing keys and exporting certificates | PKCS#11 Library Reference |
Internal Authserver for Testing Only
On the trial environment the internal Authserver may be used for testing. Production signing must authenticate through an external OAuth2/OIDC provider, such as Azure Entra ID or GitLab OIDC. See the Authentication Model.
How it works¶
sequenceDiagram
participant O as openssl dgst
participant E as pkcs11 engine<br/>or provider
participant M as libpkcs11ks.so
participant K as Keyserver
O->>E: sign (pkcs11:object=fw-quickstart)
E->>M: PKCS11 sign request
M->>K: Sign order (Bearer KSC_ID_TOKEN,<br/>operation KSC_OPERATION_ID)
K-->>M: Signature
M-->>O: signature.binDiagram: openssl dgst; pkcs11 engine or provider; libpkcs11ks.so; Keyserver; sign (pkcs11:object=fw-quickstart); PKCS11 sign request; Sign order (Bearer KSC_ID_TOKEN, operation KSC_OPERATION_ID); Signature; signature.bin
OpenSSL loads a generic PKCS#11 frontend, either the pkcs11 engine (from libengine-pkcs11-openssl) or the pkcs11 provider (from pkcs11-provider), which in turn loads the Keyserver module. The module turns each signing call into a Keyserver sign order, as described in the PKCS#11 Library Reference. PKCS#11 signing therefore needs the same access token and approved operation as REST signing. The private key never reaches this machine: OpenSSL 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.
This guide uses the engine, which works on OpenSSL 3.x but is deprecated upstream and removed in OpenSSL 4.x. Step 5, Step 6 and Step 7 each give the provider equivalent. If you use the provider, read the provider warning first: one of the two available PKCS#11 providers must not be used for signing.
Prerequisites¶
Examples use Ubuntu 24.04; most Linux distributions work.
curl,jq,openssl,pkcs11-tool(packageopensc), and the PKCS#11 enginelibengine-pkcs11-openssl, orpkcs11-providerfor the provider interface- The Keyserver PKCS#11 module
libpkcs11ks.so. See Getting the library. - 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 signing key's ID. This guide uses the EC/SHA-256 key
fw-quickstart.
Install the tools for the engine interface:
Or, for the provider interface:
Step 1: Authenticate and Obtain an OAuth2 Token¶
Encode the client credentials and 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" \
https://authserver.<UNIQUE-ID>.cryptera-security.io/oauth2/token \
| 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 for the signing key:
export KSC_OPERATION_ID=$(
curl -sS --tlsv1.3 \
-X POST "https://keyserver.<UNIQUE-ID>.cryptera-security.io/api/operations" \
-H "Authorization: Bearer $KSC_ID_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"validms": 60000,
"description": "OpenSSL engine signing",
"new-keyusagerestrictions": [
{ "keyid": "fw-quickstart", "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.
Step 3: Approve the Operation (If Required)¶
If the key requires approvals:
- Go to
https://keyclient.<UNIQUE-ID>.cryptera-security.io/approvaladmin - Log in as an approver
- Approve the operation
Confirm before continuing:
curl -sS --tlsv1.3 -H "Authorization: Bearer $KSC_ID_TOKEN" \
"https://keyserver.<UNIQUE-ID>.cryptera-security.io/api/operations/$KSC_OPERATION_ID" \
| jq .approved
Expected output: true. Keys with 0 required approvers are approved immediately.
Step 4: Configure the PKCS#11 Library Environment¶
KSC_ID_TOKEN and KSC_OPERATION_ID are set from Step 1 and Step 2. Set the Keyserver URL and the description recorded in the audit log for each sign order:
export KSC_API_SERVER="https://keyserver.<UNIQUE-ID>.cryptera-security.io"
export KSC_OPERATION_DESCRIPTION="Building of firmware for XYZ development board"
These variables must be set in the shell that runs openssl. The module reads them once, when it loads, so each openssl command picks up the values set at its start. Full variable reference: PKCS#11 Library Reference.
Step 5: Create an OpenSSL 3.x Configuration¶
To make OpenSSL load the PKCS#11 engine, create an OpenSSL configuration file (openssl-ks.cnf).
Engine configuration¶
openssl_conf = openssl_init
[openssl_init]
engines = engine_section
providers = provider_sect
[provider_sect]
default = default_sect
base = base_sect
[default_sect]
activate = 1
[base_sect]
activate = 1
[engine_section]
pkcs11 = pkcs11_section
[pkcs11_section]
engine_id = pkcs11
dynamic_path = /usr/lib/x86_64-linux-gnu/engines-3/libpkcs11.so
MODULE_PATH = /opt/app/scripts/libpkcs11ks.so
init = 0
Set MODULE_PATH to the path of your libpkcs11ks.so, then activate the configuration:
Provider configuration (alternative)¶
To use the provider interface, install pkcs11-provider as shown in Prerequisites. On Ubuntu 24.04 that package is the version validated with the Keyserver, and it installs as /usr/lib/x86_64-linux-gnu/ossl-modules/pkcs11.so.
Sign through pkcs11.so, never libp11's pkcs11prov
Two unrelated PKCS#11 providers exist for OpenSSL 3.x. Sign only through pkcs11.so from the pkcs11-provider package, which the configuration below names.
libp11's pkcs11prov.so reports a refused sign order as a success. When the Keyserver declines a sign order, for example with the 409 you get once an operation's maxusagecount is exhausted, openssl still exits 0 and writes an 8192-byte file containing your input data padded with NUL bytes. A pipeline checking only the exit status would publish that file as signed.
Ubuntu 24.04's engine package predates pkcs11prov, so it is absent unless you build libp11 from source; do not. Newer distributions ship it in the engine package as ossl-modules/libpkcs11.so, which is easy to confuse with the engine's engines-3/libpkcs11.so. See Provider interface in the PKCS#11 Library Reference.
Create openssl-ks-provider.cnf:
openssl_conf = openssl_init
[openssl_init]
providers = provider_sect
[provider_sect]
default = default_sect
pkcs11 = pkcs11_sect
[default_sect]
activate = 1
[pkcs11_sect]
module = /usr/lib/x86_64-linux-gnu/ossl-modules/pkcs11.so
pkcs11-module-path = /opt/app/scripts/libpkcs11ks.so
activate = 1
Set pkcs11-module-path to the path of your libpkcs11ks.so. The provider uses this key name, not MODULE_PATH. Keep [default_sect] activate = 1, or hashing and verification lose their implementations. Activate the configuration and confirm OpenSSL loaded the provider:
Expected output: the pkcs11 provider, reporting status: active:
status: active appears even when pkcs11-module-path names a missing file. Step 6 confirms the provider reached libpkcs11ks.so.
Step 6: Find the Key via PKCS#11 URI¶
With a valid KSC_ID_TOKEN in the environment, list the keys visible to your client:
You will see output like:
The label is the Keyserver key ID. Use it in the PKCS#11 URI:
On the provider interface, OpenSSL resolves that URI itself, so you can confirm discovery without pkcs11-tool:
Expected output: a Private Key object for your key label. If it finds nothing while openssl list -providers reports status: active, the configuration names the wrong module-path key for the provider you installed.
Before signing, verify:
| Check | Must be | If it is not |
|---|---|---|
env \| grep KSC_ | KSC_API_SERVER, KSC_ID_TOKEN, KSC_OPERATION_ID all set in the shell that runs openssl | The key 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" |
pkcs11-tool --list-objects | Shows your key's label as a Private Key Object | Wrong --module path, wrong KSC_API_SERVER/KSC_ID_TOKEN, or the subject's role cannot see the key |
echo $OPENSSL_CONF | Absolute path of the configuration from Step 5, whose MODULE_PATH (engine) or pkcs11-module-path (provider) points at libpkcs11ks.so | OpenSSL cannot load the pkcs11 engine or provider, or finds no keys |
Step 7: Sign Data¶
Create data to sign:
Sign it. The key label in the URI is the key ID from Step 6 and must be a key in your operation from Step 2:
openssl dgst \
-engine pkcs11 \
-keyform engine \
-sign "pkcs11:object=fw-quickstart" \
-sha256 \
-out signature.bin \
data.bin
On the provider interface, the command drops -engine/-keyform and names the key by its full PKCS#11 URI:
openssl dgst \
-sha256 \
-sign "pkcs11:object=fw-quickstart;type=private" \
-out signature.bin \
data.bin
Expected result: signature.bin is created, and the signature consumes one use of the key's maxusagecount in the operation. An exit status of 0 does not prove that the Keyserver issued a signature; always verify it before use.
Step 8: Extract the Certificate for Verification¶
Export the certificate via PKCS#11:
pkcs11-tool \
--module /path/to/libpkcs11ks.so \
--read-object --type cert --label <KEYLABEL> \
--output-file <KEYLABEL>.der
Convert it to PEM and extract the public key:
openssl x509 -inform DER -in <KEYLABEL>.der -out <KEYLABEL>.pem -outform PEM
openssl x509 -in <KEYLABEL>.pem -pubkey -noout > <KEYLABEL>_pubkey.pem
Step 9: Verify the Signature¶
If successful:
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 OpenSSL:
- Match the digest to the key. The
-sha256/-sha384/-sha512option must match the key's configured hash algorithm. The Keyserver does not check the digest length: with an RSA key a different digest gives a signature that does not verify, and with an ECDSA key the signature verifies only against the digest you used. - Verify before publishing. Run Step 9 in the pipeline and fail the build unless it prints
Verified OK. This catches wrong-key mistakes, a digest mismatch on an RSA key, and a sign order that was refused.
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 |
invalid engine "pkcs11" or dynamic engine load failure | libengine-pkcs11-openssl not installed, or dynamic_path in the configuration is wrong for your distribution |
openssl list -providers omits pkcs11, or shows it without status: active | pkcs11-provider not installed, or module/pkcs11-module-path wrong in the provider configuration |
Provider is active but storeutl finds no key | The configuration names the wrong module-path key, or points module at libp11's provider instead of pkcs11.so (see Step 5) |
Signing exits 0 but signature.bin is 8192 bytes and starts with your input data | Signing through libp11's pkcs11prov. Switch to pkcs11-provider and treat the artifact as unsigned |
| OpenSSL cannot load the key / no objects listed | KSC_API_SERVER/KSC_ID_TOKEN not exported in the shell, MODULE_PATH/pkcs11-module-path wrong, 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 its creator cancelled it. 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 |
Verification failure in Step 9 | Wrong public key extracted (different key label), the data changed after signing, or (RSA key) the digest option does not match the key's configured hash algorithm |
Full status-code reference: Error Codes. PKCS#11-specific issues: PKCS#11 Library Reference.
Related pages¶
- Tutorial Part 2: Sign Code Using the Trial Environment: the REST flow behind this guide
- Verify a Signature: certificate-chain and signature checks before publishing