Skip to content

PKCS#11 Library Reference (libpkcs11ks)

libpkcs11ks.so is the Cryptera Keyserver PKCS#11 module. This page covers how it works, how to get and configure it, and the practices for running it in CI. The how-to guides for OpenSSL, GitLab CI, Azure DevOps and Authenticode show it end to end.


How the module works

The module presents Keyserver signing keys to any PKCS#11-capable tool (OpenSSL, JSign, osslsigncode, pkcs11-tool) as if they were in a local token. It reads its KSC_* environment variables and turns each PKCS#11 signing call into a Keyserver sign order (POST /api/signorders) under the operation named in KSC_OPERATION_ID. As a result:

  • PKCS#11 signing needs the same access token and approved operation as REST signing.
  • Each signature consumes one use of the key's maxusagecount in that operation, and is recorded in the audit log under that operation.
  • The private key stays in the Keyserver; only the hash and the signature cross the network. This holds for KEYSTORE keys too: such a key leaves the Keyserver only through an explicit export.

The tool reaches the module through its own PKCS#11 frontend: the OpenSSL engine or provider, or the SunPKCS11 configuration used by JSign and jarsigner.


Getting the library

Download the prebuilt binary (recommended): each release of github.com/cryptera-device-security/libpkcs11ks ships libpkcs11ks.so as a release asset:

curl -sSL --fail -o libpkcs11ks.so \
  https://github.com/cryptera-device-security/libpkcs11ks/releases/download/v1.0.4/libpkcs11ks.so

Pin the version; verify what you deploy

Do not substitute releases/latest in a signing pipeline. --fail stops curl writing an HTML error page into libpkcs11ks.so.

Cryptera does not publish checksums or signatures for this artifact. Record its SHA-256 (sha256sum libpkcs11ks.so) on first download, keep it with your build configuration, and check it on every later deployment.

Or build from source via Docker for a consistent environment:

git clone --depth 1 --branch v1.0.4 https://github.com/cryptera-device-security/libpkcs11ks.git
cd libpkcs11ks
docker build -t libpkcs11ks .
docker run --rm -v "$(pwd)/output:/output" libpkcs11ks

The binary is written to ./output/libpkcs11ks.so.


Environment variables

The module is configured entirely through environment variables. It reads them, and fetches the key list, once, when the tool initializes the module (PKCS#11 C_Initialize). A long-running process must finalize and re-initialize the module to pick up a new token, operation ID or key.

Variable Required Description
KSC_API_SERVER Yes Base URL of the Keyserver, e.g. https://keyserver.<UNIQUE-ID>.cryptera-security.io
KSC_ID_TOKEN Yes The OAuth2 access token, despite the variable name. See the warning below
KSC_OPERATION_ID Yes, for signing ID of an approved operation that includes the key being used
KSC_OPERATION_DESCRIPTION Recommended Description recorded in the audit log for each sign order. Padded with - to 8 characters; unset, it is sent as --------
KSC_HTTP_CLIENT_TIMEOUT No (default 10s) HTTP timeout for calls against the Keyserver, e.g. 15s

KSC_ID_TOKEN holds an access token, not an ID token

The variable name is historical. It carries the access token the Keyserver validates. Passing an OIDC ID token here fails with 401, because the Keyserver checks the audience and issuer of an access token.

GitLab CI's id_tokens: block produces a token GitLab calls an ID token; the Keyserver accepts it as the access credential.

Notes:

  • Signing requires an approved operation. Create it via POST /api/operations and, if the key requires approvers, wait for approval before invoking the PKCS#11 tool.
  • Listing keys (pkcs11-tool --list-objects) requires only KSC_API_SERVER and a valid KSC_ID_TOKEN.
  • The token must belong to a subject whose role permits order on the key being used.

Key discovery and PKCS#11 URIs

Keyserver key IDs appear as PKCS#11 object labels:

pkcs11-tool --module /path/to/libpkcs11ks.so --list-objects
Private Key Object; label: fw-quickstart; id: <...>

Reference a key in a PKCS#11 URI by its label:

pkcs11:object=fw-quickstart;type=private

With the OpenSSL provider configured (below), OpenSSL resolves that URI itself, so key discovery needs no separate tool:

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

OpenSSL configuration

OpenSSL reaches libpkcs11ks.so through one of two interfaces, the engine or a provider. Both are supported; configure one, not both.

Interface Package (Debian/Ubuntu) Module named in Validated with
Engine libengine-pkcs11-openssl MODULE_PATH libp11 0.4.12 and 0.4.20
Provider pkcs11-provider pkcs11-module-path pkcs11-provider 0.3

The guides, including every CI recipe, use the engine. It is deprecated upstream and removed in OpenSSL 4.x. Use the provider if your pipeline must outlive OpenSSL 3.x or your distribution no longer packages the engine. Both produce equivalent signatures from the same key and operation. The versions in the table are the ones Cryptera has validated against a Keyserver.

Engine interface

Create a configuration file (openssl-ks.cnf):

The [provider_sect] block here is not the PKCS#11 provider

In the engine configuration below, [provider_sect] only re-activates OpenSSL's own default and base providers, which a custom configuration file would otherwise disable. The PKCS#11 provider interface is configured separately; see the next section.

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 = /path/to/libpkcs11ks.so
init = 0
  • dynamic_path: the generic OpenSSL pkcs11 engine (package libengine-pkcs11-openssl on Ubuntu)
  • MODULE_PATH: your libpkcs11ks.so

Activate it and sign:

export OPENSSL_CONF=/path/to/openssl-ks.cnf

openssl dgst -engine pkcs11 -keyform engine \
  -sign "pkcs11:object=fw-quickstart" -sha256 \
  -out signature.bin data.bin

Provider interface

Install the provider:

sudo apt install pkcs11-provider

Use pkcs11-provider, not libp11's pkcs11prov

Two unrelated PKCS#11 providers exist for OpenSSL 3.x, both installed into ossl-modules/, and only one is safe to sign with. Name the file explicitly in your configuration:

Provider Installs as Verdict
pkcs11-provider, from the latchset project ossl-modules/pkcs11.so Use this. Validated with the Keyserver at 0.3
pkcs11prov, from libp11 ossl-modules/pkcs11prov.so, plus an ossl-modules/libpkcs11.so symlink to it Do not sign with this

libp11's provider reports a refused sign order (for example 409 "The key has already been used the allowed number of times in this operation") as success: openssl dgst -sign exits 0 and writes an 8192-byte file containing the input data padded with NUL bytes. A pipeline that checks only the exit status publishes its own plaintext as the signature. Observed with libp11 0.4.20 on EC and RSA keys; pkeyutl through the same provider reports the refusal correctly. The defect is in libp11's provider, not in libpkcs11ks.so or the Keyserver.

It may already be installed. Recent libp11 releases build this provider and distributions ship it inside the engine package, so installing the engine as the previous section instructs can also place libp11's provider in OpenSSL's modules directory. Check for ossl-modules/pkcs11prov.so before assuming a provider configuration picked up the one you intended.

Watch the file name. The engine is engines-3/libpkcs11.so; libp11's provider is symlinked as ossl-modules/libpkcs11.so. Do not reuse the name libpkcs11.so in a provider configuration; the file you want is pkcs11.so.

The two providers also take the Keyserver module through differently named configuration keys: pkcs11-module-path for pkcs11-provider, pkcs11_module for pkcs11prov. A configuration written for one loads the other without passing it libpkcs11ks.so at all, and the symptom is silent: no keys are found.

With either interface, verify every signature before you publish it. See Verify before publishing.

Create a configuration file (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 = /path/to/libpkcs11ks.so
activate = 1
  • module: the pkcs11-provider shared object. Name the file explicitly so you load pkcs11.so, not libp11's provider
  • pkcs11-module-path: your libpkcs11ks.so
  • [default_sect] activate = 1: required. Without it the PKCS#11 provider is the only one loaded and ordinary operations such as hashing and file-based verification lose their implementations

Activate it and confirm OpenSSL loaded the provider:

export OPENSSL_CONF=/path/to/openssl-ks-provider.cnf

openssl list -providers
  pkcs11
    name: PKCS#11 Provider
    version: <version>
    status: active

status: active does not mean the Keyserver module was loaded

The provider reports itself active even when pkcs11-module-path points at a file that does not exist. Run key discovery (openssl storeutl on the key's PKCS#11 URI, as shown above) to confirm the provider reached libpkcs11ks.so.

Then sign. The provider needs no -engine/-keyform options; name the key by its PKCS#11 URI:

openssl dgst -sha256 \
  -sign "pkcs11:object=fw-quickstart;type=private" \
  -out signature.bin data.bin

openssl pkeyutl -sign -inkey "pkcs11:object=fw-quickstart;type=private" -rawin -digest sha256 -in data.bin -out signature.bin is equivalent and also validated.

With either interface, the hash algorithm passed to OpenSSL must match the key's configured hash algorithm.


JSign configuration (Authenticode)

JSign uses a Java keystore config file instead of the OpenSSL engine:

name = CrypteraKS
library = /path/to/libpkcs11ks.so
slotListIndex = 0
java -jar jsign.jar --keystore pkcs11.cfg --storetype PKCS11 \
  --alias fw-rsa --certfile cert.pem app.exe

The --alias is the Keyserver key ID. See Sign Windows Executables (Authenticode) for the complete flow. jarsigner uses the same SunPKCS11 provider configuration. See Sign JAR Files Using jarsigner and PKCS#11.


CI practices

These practices apply to every pipeline that signs through the Keyserver, whether through this module or the REST API. The CI and signing how-tos link here and add only their page-specific practices.

Secrets and tokens

  • Request a fresh access token at the start of each job, from credentials held in a protected CI variable or secret store. Tokens are short-lived: never bake them into images or cache them across runs.
  • Never print a token or a client secret in a job log. Check that it is set instead ([ -n "$KSC_ID_TOKEN" ]).

Operation budgets

  • Set validms to the shortest window the job needs. It must cover the approval wait, any queue time before the signing job starts, and the signing itself.
  • Set maxusagecount to the number of signatures the job produces.
  • An approver authorizes the operation, not a specific artifact. For a key that requires approval, a compromised job can therefore spend at most that one approved budget, and every use is audited. See What an approver authorizes.

Least privilege

  • Give each pipeline or machine its own subject, so that one leaked credential compromises one identity and the audit log attributes each sign order correctly.
  • That subject holds only a signing-Nature role (fwsigner, or devcertsigner for certificates) for the keys it needs, never approver or administrative roles. The Keyserver does not stop one subject from approving its own operations. See Why approvals exist.

Verify before publishing

  • Verify every signature in the pipeline and fail the build on a verification error. A zero exit status is not proof of a signature. See the libp11 warning in Provider interface. For OpenSSL, verify as in Step 9: Verify the Signature of the OpenSSL guide.

Troubleshooting

Symptom Likely cause
--list-objects shows no keys Token invalid/expired, or subject has no key-scoped permissions
openssl list -providers omits pkcs11, or shows it without status: active pkcs11-provider not installed, or module/pkcs11-module-path wrong in the configuration
Provider loads, but storeutl finds no key The configuration names the wrong module-path key for the provider you installed (pkcs11-module-path vs pkcs11_module)
Signing exits 0 but the output is 8192 bytes and begins with your input data You are signing through libp11's pkcs11prov provider. Switch to pkcs11-provider, and treat the artifact as unsigned
Signing fails with authorization error KSC_OPERATION_ID not set, operation not approved, or key not included in the operation
Signing fails after N successes Operation's maxusagecount for the key is exhausted. Create a new operation
Signing fails after working earlier Operation's validms window expired. Create a new operation
Timeout errors on slow networks Increase KSC_HTTP_CLIENT_TIMEOUT (e.g. 15s)

For HTTP status code semantics, see the Error Codes Reference.