PKCS#11 Provider Configuration — pkcs11.toml
The TOML configuration file for the DuoKey PKCS#11 provider — its schema and environment-variable overrides.
The DuoKey PKCS#11 provider is configured with a TOML file (typically named pkcs11.toml): a .../tde/pkcs11/... proxy URL and an access_token bearer credential.
A short demo video of configuring and testing pkcs11.toml will be added here.
The values below come straight from the Oracle TDE app's detail page in Cockpit v2 — the PKCS#11 Endpoint card shows the exact server_url, the non-secret access_guid, and the access_token bearer credential (masked by default, with a reveal/copy control) side by side:
File location
The provider reads the TOML file at C_Initialize from the path in the DKE_PKCS11_CONF environment variable. Oracle sets this in the Oracle user's profile (or in okvclient.ora / the OKV wrapper). A common OKV install location is:
/usr/local/okv/hsm/generic/pkcs11.toml
If no file path is provided, the library can build its configuration entirely from environment variables (see Environment-variable overrides), provided at least the server URL is set.
Configuration schema
# pkcs11.toml — DuoKey PKCS#11 provider configuration for Cockpit v2
[http_config]
# Full Cockpit v2 proxy URL for this Oracle TDE app (required).
# Format: https://<cockpit-api-host>/api/apps/<app_id>/tde/pkcs11/<access_guid>
# Use the API-serving hostname, not the browser/frontend one — Cockpit v2
# typically separates the two (e.g. cockpit-api-<env>.duokey.cloud for the
# API vs cockpit-<env>.duokey.cloud for the UI). The wrong host still
# returns HTTP 200, just with the frontend's HTML instead of JSON.
server_url = "https://cockpit-api-test.duokey.cloud/api/apps/APP_ID/tde/pkcs11/ACCESS_GUID"
# Bearer token used to authenticate every request (default: "").
# This is a distinct, rotatable secret — NOT the access_guid in server_url above.
access_token = "ACCESS_TOKEN"
# HTTP request timeout in seconds (default: 30).
timeout_secs = 30
# Verify the server's TLS certificate (default: true).
# Set to false ONLY for testing against self-signed certificates.
verify_tls = true
# Optional: path to a PEM file holding a client certificate chain and its
# private key, presented to Cockpit v2 for mutual TLS in addition to the
# bearer token. Leave unset for server-auth TLS only (default).
# client_identity_path = "/etc/dke/client-identity.pem"
[pkcs11]
# Id of the single virtual slot the library presents (default: 0).
slot_id = 0
# Logging level: "error" | "warn" | "info" | "debug" | "trace" (default: "info").
logging_level = "info"
# Optional folder for provider log files (default: none — logs to stderr).
logging_folder = "/var/log/dke-pkcs11"
[http_config] — connection to Cockpit v2
| Key | Type | Default | Purpose |
|---|---|---|---|
server_url | string | (required) | The full Cockpit v2 proxy URL for this app. It already contains the app_id and access_guid, so no separate endpoint/tenant fields are needed. |
access_token | string | "" | Bearer token sent as Authorization: Bearer … — a distinct, rotatable secret. Do not confuse it with the access_guid in server_url, which is only a routing identifier. |
timeout_secs | integer | 30 | Per-request HTTP timeout. |
verify_tls | boolean | true | TLS certificate verification. Keep true in production. |
client_identity_path | string | (none) | Optional path to a PEM file (client certificate chain + private key) for mutual TLS. When set, the provider presents this client identity in addition to the bearer token. |
[pkcs11] — local provider behaviour
| Key | Type | Default | Purpose |
|---|---|---|---|
slot_id | integer | 0 | Id of the single virtual slot exposed to Oracle. |
logging_level | string | "info" | Provider log verbosity. |
logging_folder | string | (none) | Directory for provider logs; if unset, logs go to stderr. |
Endpoint & authentication model
Endpoint
Every Cryptoki operation is a single POST to server_url. A GET on the same URL is used as a readiness / handshake probe.
Authentication
A bearer token, access_token — a distinct, rotatable secret, not the access_guid in the URL. There is no OAuth2 client-credentials flow, no username/password, and no OpenID Connect discovery.
Tenant resolution
There is no tenant field in pkcs11.toml. Cockpit v2 resolves the tenant server-side from the (app_id, access_guid) pair in the URL.
TLS
verify_tls = true by default. Client-certificate (mutual TLS) authentication is available as an opt-in: set client_identity_path to a PEM file holding a client certificate chain and its private key, and the provider presents it alongside the bearer token. Leave it unset for server-auth TLS only (the default).
The access_token is a bearer credential — keep it secret. Restrict the file to the Oracle OS user (for example chmod 600, owned by oracle), and rotate the app's access token from the Cockpit if it is ever exposed. The access_guid in server_url is not secret by itself, but since it identifies the app and rides in a URL path (which can end up in reverse-proxy or ingress access logs outside DuoKey's control), keep the whole file protected regardless.
Environment-variable overrides
Environment variables take precedence over the file, so you can keep a base pkcs11.toml and override per host:
| Environment variable | Overrides |
|---|---|
DKE_PKCS11_CONF | Path to the pkcs11.toml file |
DKE_PKCS11_SERVER_URL | http_config.server_url |
DKE_PKCS11_ACCESS_TOKEN | http_config.access_token |
DKE_PKCS11_VERIFY_TLS | http_config.verify_tls (0 / false / no = disabled) |
DKE_PKCS11_CLIENT_IDENTITY | http_config.client_identity_path |
DKE_PKCS11_SLOT_ID | pkcs11.slot_id |
DKE_PKCS11_LOGGING_LEVEL | pkcs11.logging_level |
DKE_PKCS11_LOGGING_FOLDER | pkcs11.logging_folder |
You do not assemble these values by hand. In Cockpit v2, open the Oracle TDE app and use its deployment bundle — the Cockpit generates the pkcs11.toml (with the correct server_url and access_guid), the environment exports, and the Oracle SQL scripts for you to download.