メインコンテンツまでスキップ

DuoKey SDK レイヤー

DuoKey SDK レイヤー は、DuoKey Cockpit とのすべての通信を処理します。各 PKCS#11 操作を HTTPS 経由で Cockpit に運び、認証トークンを付加し、リトライと接続の再利用を処理します。

API リファレンス: 具体的なワイヤープロトコル（エンドポイントとリクエスト／レスポンス形式）は内部仕様であり、開発者ドキュメント で別途文書化されています。このページは、このレイヤーの責務を高レベルで示すものです。

概要​

責務​

認証​

DuoKey Cockpit への認証には、単一の access_guid ベアラートークン を使用します。このトークンは、Oracle TDE アプリ向けに構成された Cockpit プロキシ URL の一部であり、すべてのリクエストに Authorization: Bearer … ヘッダーとして送信されます。

OAuth2 クライアントクレデンシャルフローはなく、client_id / client_secret もなく、ユーザー名／パスワードもなく、クライアント側のテナントヘッダーもありません。Cockpit は、URL に埋め込まれたアプリ識別情報からテナントをサーバー側で解決します。

認証フロー:

構成: トークンは pkcs11.toml（または DKE_PKCS11_ACCESS_TOKEN による上書き）から提供されます。構成 を参照してください。

HTTPS クライアント​

DuoKey Cockpit プロキシエンドポイントにリクエストを送信します。各 PKCS#11 操作は単一のリクエストとなり、ベアラートークンとともに送信されます。レスポンスは PKCS#11 の結果に解析されて戻されます。概念レベルでは、操作は 2 つのグループに分かれます。

  • キー管理 — マスターキーのプロビジョニング、キー情報の参照。
  • ラップ／アンラップ — マスターキーによるテーブルおよび表領域キーのラップとアンラップ。

リクエスト／レスポンスの処理​

このレイヤーは、送信リクエストをシリアライズし、ヘッダーとベアラートークンを付加し、HTTPS 経由で送信し、レスポンスを解析します。

エラー処理: このレイヤーは、Cockpit およびトランスポートのエラーを適切な PKCS#11 リターンコードに変換します。これにより、Oracle TDE には標準的な Cryptoki の結果が見えます。たとえば、認証の失敗は認証エラーとして、オブジェクトの欠落は無効なハンドルエラーとして、バックエンドまたはネットワークの失敗はデバイスエラーとして現れます。

リトライロジック​

一時的な失敗は、指数バックオフでリトライされます。

リトライ可能: ネットワークタイムアウト、503 Service Unavailable、502 Bad Gateway、接続エラー。

リトライ不可: 401 Unauthorized（認証）、404 Not Found（オブジェクトの欠落）、400 Bad Request（無効なパラメーター）。

構成: リクエストごとのタイムアウトは、pkcs11.toml 内の timeout_secs（デフォルト 30 秒）で設定されます。構成 を参照してください。

接続の再利用​

  • キープアライブ: HTTPS 接続はリクエスト間で再利用され、TCP/TLS ハンドシェイクの繰り返しを回避します。
  • TLS: すべての接続で、厳格な証明書検証を伴う TLS 1.2 以上を使用します（verify_tls で制御されます）。

エラー処理​

Cockpit は失敗時に構造化されたエラーを返します。SDK レイヤーはそれを解析し、PKCS#11 リターンコードにマッピングします。

セキュリティに関する考慮事項​

TLS​

  • 最小バージョン: TLS 1.2 以上
  • 証明書の検証: 厳格。本番環境では verify_tls = true
  • 暗号スイート: 強力なスイートのみ

認証情報の処理​

  • 単一の認証情報: access_guid ベアラートークンが、クライアント側の唯一のシークレットです。
  • ロギングなし: トークンが決してログに記録されることはありません。
  • 実行時に提供: pkcs11.toml または DKE_PKCS11_ACCESS_TOKEN 環境変数による上書きを通じて提供されます。ファイルは制限的な権限で保護してください。

次のステップ​