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.

Overview

Architecture

DuoKey SDK layer

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:

Sequence

Authentication flow

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.

Flowchart

Retry logic

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.

Flowchart

Error mapping

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

• Object Handle Mapping → - Understand how handles map to key identifiers
• Communication Flow → - See end-to-end communication patterns
• Configuration → - Learn about pkcs11.toml configuration