Skip to content

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.bin

Diagram: 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 (package opensc), and the PKCS#11 engine libengine-pkcs11-openssl, or pkcs11-provider for 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:

sudo apt install curl jq openssl opensc libengine-pkcs11-openssl

Or, for the provider interface:

sudo apt install curl jq openssl opensc pkcs11-provider

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:

  1. Go to https://keyclient.<UNIQUE-ID>.cryptera-security.io/approvaladmin
  2. Log in as an approver
  3. 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:

export OPENSSL_CONF=<PATH_TO_ABOVE_FILE>

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:

export OPENSSL_CONF=<PATH_TO_ABOVE_FILE>

openssl list -providers

Expected output: the pkcs11 provider, reporting status: active:

  pkcs11
    name: PKCS#11 Provider
    version: <version>
    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:

pkcs11-tool --module /path/to/libpkcs11ks.so --list-objects

You will see output like:

Private Key Object; label: fw-quickstart; id: <...>

The label is the Keyserver key ID. Use it in the PKCS#11 URI:

pkcs11:object=fw-quickstart;type=private

On the provider interface, OpenSSL resolves that URI itself, so you can confirm discovery without pkcs11-tool:

openssl storeutl -text -noout "pkcs11:object=fw-quickstart;type=private"

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:

echo "hello world" > data.bin

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

openssl dgst -sha256 -verify <KEYLABEL>_pubkey.pem -signature signature.bin data.bin

If successful:

Verified OK

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/-sha512 option 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.