Skip to main content

DuoKey SDK Layer

The DuoKey SDK Layer handles all communication with DuoKey Cockpit. It carries each PKCS#11 operation to Cockpit over HTTPS, attaches the authentication token, and handles retries and connection reuse.

API reference: The concrete wire protocol — endpoints and request/response formats — is internal and documented separately in the Developer Docs. This page is a high-level view of the layer's responsibilities.

Overview​

DuoKey SDK layer
PKCS#11 Interface Layer
PKCS#11 functions
DuoKey SDK Layer
Authenticationaccess_token bearer credential
HTTPS clientRequest buildingResponse parsing
SerializationEncode / decodeError parsing
Retry logicBackoff for transient errors
HTTPS
DuoKey Cockpit
Cockpit proxy endpoint

The SDK layer carries each PKCS#11 operation to the Cockpit proxy endpoint over HTTPS.

Responsibilities​

Authentication​

Authentication to DuoKey Cockpit uses an access_token bearer credential, configured in pkcs11.toml and sent as an Authorization: Bearer … header on every request. The access_guid embedded in the Cockpit proxy server_url for the Oracle TDE app is a separate, non-secret routing id — it is not the credential.

There is no OAuth2 client-credentials flow, no client_id / client_secret, no username / password, and no tenant header on the client side. Cockpit resolves the tenant server-side from the app identity embedded in the URL.

Authentication flow:

Authentication flow
SDK Layeraccess_token loaded from pkcs11.toml
Authorization: Bearer access_token
DuoKey CockpitValidate token, resolve tenant
response
SDK LayerResponse received

access_token is loaded from pkcs11.toml and sent as a bearer credential on every request.

Configuration: the token is supplied by pkcs11.toml (or the DKE_PKCS11_ACCESS_TOKEN override). See Configuration.

HTTPS client​

Sends requests to the DuoKey Cockpit proxy endpoint. Each PKCS#11 operation becomes a single request, sent with the bearer token; the response is parsed back into a PKCS#11 result. At a conceptual level the operations fall into two groups:

  • Key management — provision a master key, look up key information.
  • Wrap / unwrap — wrap and unwrap the table and tablespace keys under the master key.

Request / response handling​

The layer serializes the outgoing request, attaches headers and the bearer token, sends it over HTTPS, and parses the response.

Error handling: the layer translates Cockpit and transport errors into the appropriate PKCS#11 return codes, so Oracle TDE sees standard Cryptoki results — for example, an authentication failure surfaces as an authentication error, a missing object as an invalid-handle error, and backend or network failures as a device error.

Retry logic​

Transient failures are retried with exponential backoff.

Retry logic
Make request
Attempt 1
Attempt 1 result
Success
Transient errorBackoff
retry — Attempt 2
Attempt 2 result
Success
FailureMax retries

Transient failures are retried with exponential backoff, up to the max-retry limit.

Retryable: network timeouts, 503 Service Unavailable, 502 Bad Gateway, connection errors.

Non-retryable: 401 Unauthorized (authentication), 404 Not Found (object missing), 400 Bad Request (invalid parameters).

Configuration: the per-request timeout is set by timeout_secs in pkcs11.toml (default 30 seconds). See Configuration.

Connection reuse​

  • Keep-alive: HTTPS connections are reused across requests to avoid repeated TCP/TLS handshakes.
  • TLS: all connections use TLS 1.2+ with strict certificate validation (controlled by verify_tls).

Error Handling​

Cockpit returns a structured error on failure; the SDK layer parses it and maps it to a PKCS#11 return code.

Error mapping
Error response
Parse errorClassify error type
Authentication
CKR_PIN_INCORRECT
Not found
CKR_OBJECT_HANDLE_INVALID
Server / network
CKR_DEVICE_ERROR
Invalid parameter
CKR_ARGUMENTS_BAD
Return to PKCS#11 layer

Cockpit errors are parsed and mapped to a PKCS#11 return code, then returned to the PKCS#11 layer.

Security Considerations​

TLS​

  • Minimum version: TLS 1.2+
  • Certificate validation: strict; verify_tls = true in production
  • Cipher suites: strong suites only

Credential handling​

  • Single credential: the access_token bearer credential is the only client-side secret (the access_guid in server_url is a non-secret routing id).
  • No logging: the token is never logged.
  • Supplied at runtime: provided via pkcs11.toml or the DKE_PKCS11_ACCESS_TOKEN environment override; protect the file with restrictive permissions.

Next Steps​