Skip to main content

Configuration

Against DuoKey Cockpit, the PKCS#11 provider is configured with a pkcs11.toml file plus optional DKE_PKCS11_* environment-variable overrides. The file carries just two essentials — the Cockpit proxy URL (containing the non-secret access_guid routing id) and the access_token bearer credential — because Cockpit resolves the app and tenant server-side.

Canonical reference

This page describes the configuration model at an architectural level. For the full schema, defaults, and the v1 → v2 migration mapping, see PKCS#11 Provider Configuration (pkcs11.toml).

Overview​

Configuration loading
Configuration sources
pkcs11.tomlserver_url + access_token
DKE_PKCS11_* env varsoptional overrides
read
Library initialization
Read file / env
Validate configuration
Initialize components

The provider reads pkcs11.toml and optional environment overrides, validates them, then initializes its components.

Configuration file​

The provider reads its configuration at C_Initialize from the path in the DKE_PKCS11_CONF environment variable. Oracle sets this in the Oracle user's profile (or in the OKV wrapper). A common install path is:

/usr/local/okv/hsm/generic/pkcs11.toml

Schema​

# pkcs11.toml — DuoKey PKCS#11 provider configuration

[http_config]
# Full Cockpit proxy URL for this Oracle TDE app (required). Use the
# API-serving hostname, not the frontend/browser one (Cockpit v2 typically
# separates the two, e.g. cockpit-api-<env>.duokey.cloud vs
# cockpit-<env>.duokey.cloud) — the wrong host still returns HTTP 200, just
# with the frontend's HTML instead of JSON.
# It already contains the app identity and access_guid (a non-secret routing
# id), so no separate endpoint or tenant fields are needed.
server_url = "https://cockpit-api-test.duokey.cloud/api/apps/APP_ID/tde/pkcs11/ACCESS_GUID"

# Bearer token used to authenticate every request — a distinct, rotatable
# secret, NOT the access_guid 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

[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​

KeyTypeDefaultPurpose
server_urlstring(required)Full Cockpit proxy URL for this app. Contains the app identity and access_guid (a non-secret routing id), so no separate endpoint or tenant fields are required.
access_tokenstring""Bearer token sent as Authorization: Bearer … — a distinct, rotatable secret, not the access_guid.
timeout_secsinteger30Per-request HTTP timeout.
verify_tlsbooleantrueTLS certificate verification. Keep true in production.

[pkcs11] — local provider behaviour​

KeyTypeDefaultPurpose
slot_idinteger0Id of the single virtual slot exposed to Oracle.
logging_levelstring"info"Provider log verbosity.
logging_folderstring(none)Directory for provider logs; if unset, logs go to stderr.

Authentication model​

  • One credential. Authentication is the access_token bearer token in pkcs11.toml. The access_guid embedded in server_url is a separate, non-secret routing id used to resolve the app/tenant server-side — not a credential. There is no OAuth2 client-credentials flow, no client_id / client_secret, no username / password, and no OpenID Connect discovery.
  • No tenant field. Cockpit resolves the tenant server-side from the app identity in the URL — there is no tenant id or tenant header on the client side.
  • No vault field. The backing vault / keystore is managed by the app in the Cockpit, not configured client-side.
Protect pkcs11.toml

The access_token is a bearer credential — keep it secret. The access_guid in server_url is not secret by itself, but since it identifies the app and can appear in reverse-proxy/ingress access logs via the URL path, restrict the whole 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.

Environment-variable overrides​

Environment variables take precedence over the file, so you can keep a base pkcs11.toml and override per host:

Environment variableOverrides
DKE_PKCS11_CONFPath to the pkcs11.toml file
DKE_PKCS11_SERVER_URLhttp_config.server_url
DKE_PKCS11_ACCESS_TOKENhttp_config.access_token
DKE_PKCS11_VERIFY_TLShttp_config.verify_tls (0 / false / no = disabled)
DKE_PKCS11_SLOT_IDpkcs11.slot_id
DKE_PKCS11_LOGGING_LEVELpkcs11.logging_level
DKE_PKCS11_LOGGING_FOLDERpkcs11.logging_folder

If no file path is provided, the library can build its configuration entirely from environment variables, provided at least the server URL and access token are set.

Getting the values​

You do not assemble these values by hand. In the Cockpit, open the Oracle TDE app and use its deployment bundle — the Cockpit generates the pkcs11.toml (with the correct server_url, access_guid, and access_token), the environment exports, and the Oracle SQL scripts for you to download.

Validation​

The library validates configuration during initialization:

  • The server URL is present and well-formed.
  • The access token is present.
  • On failure, initialization returns CKR_DEVICE_ERROR (connection / configuration) or CKR_PIN_INCORRECT (authentication).

Security Best Practices​

  • Never commit pkcs11.toml or the access_token to version control.
  • Restrict file permissions to the Oracle OS user (chmod 600).
  • Rotate the app's access token from the Cockpit on a regular schedule and immediately if exposed.
  • Keep verify_tls = true and use TLS 1.2+ for all connections.

Next Steps​