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

通信フロー

通信フローを理解することは、問題のトラブルシューティングやパフォーマンスの最適化に役立ちます。このページでは、Oracle Database から DuoKey Cockpit までの操作が、システム内をどのように流れて往復するかを高レベルで説明します。

API リファレンス: 詳細な API エンドポイントおよびリクエスト／レスポンス形式は、Developer Docs で別途文書化されています。

概要​

典型的な操作フロー​

初期化フロー​

手順:

  1. Oracle が C_Initialize() を呼び出す: ライブラリの初期化が始まります
  2. 構成の読み取り: ライブラリが pkcs11.toml から server_url と access_guid を読み取ります
  3. 認証: ライブラリが最初のリクエストで access_guid ベアラートークンを Cockpit に提示します
  4. サーバー側の検証: Cockpit がトークンを検証し、アプリのアイデンティティからテナントを解決します。個別のトークン交換は行われません
  5. ボールトの検証: 指定されたボールトへのアクセスを検証します
  6. 成功の返却: ライブラリが操作の準備完了となります

セッション作成フロー​

手順:

  1. Oracle が C_OpenSession() を呼び出す: 新しいセッションを要求します
  2. スロットの検証: スロット ID が有効であることを確認します
  3. セッションの作成: 内部セッションオブジェクトを作成します
  4. テーブルの初期化: セッション用のハンドルマッピングテーブルを作成します
  5. ハンドルの返却: セッションハンドルを Oracle に返します

注: セッションの作成に API 呼び出しは不要です。セッションはローカルで管理されます。

ログインフロー​

手順:

  1. Oracle が C_Login() を呼び出す: セッションのログインを要求します
  2. トークンの確認: access_guid ベアラートークンが pkcs11.toml に構成されていることを検証します
  3. セッションのマーク: セッションを認証済みとしてマークします
  4. 成功の返却: CKR_OK を返します

注: DuoKey PKCS#11 では、認証は C_Initialize() の際に行われ、そこでライブラリが access_guid ベアラートークンを Cockpit に提示します。C_Login() 関数はトークンが利用可能であることを確認しますが、追加の API 呼び出しは行いません。

キー生成フロー​

手順:

  1. Oracle が C_GenerateKey() を呼び出す: キーの生成を要求します
  2. テンプレートの解析: キー属性（タイプ、サイズ、ラベル）を抽出します
  3. API リクエストの構築: キー生成リクエストを作成します
  4. API 呼び出し: キー生成リクエストを Cockpit に送信します
  5. HSM での生成: バックエンド HSM がキーを生成します
  6. UUID の受信: Cockpit がキーの UUID を返します
  7. ハンドルの作成: UUID を PKCS#11 ハンドルにマッピングします
  8. ハンドルの返却: ハンドルを Oracle に返します

暗号化フロー​

手順:

  1. Oracle が C_Encrypt() / C_WrapKey() を呼び出す: マスターキーのパスでのラップを要求します（例: 表領域キーの保護）
  2. ハンドルのルックアップ: 指定されたマスターキーハンドルに対応する UUID を見つけます
  3. メカニズムの解析: アルゴリズム (AES-CBC / AES-CBC-PAD) と IV を抽出します
  4. リクエストの構築: ラップリクエストを作成します
  5. API 呼び出し: ラップリクエストを Cockpit に送信します
  6. HSM でのラップ: バックエンド HSM が、長さを保持する AES-CBC(-PAD) ラップを実行します
  7. ラップされたキーの受信: ラップされたデータを取得します
  8. 結果の返却: Oracle に返します

注: ラップには、長さを保持する AES-CBC / AES-CBC-PAD メカニズムを使用します。このパスで、長さが拡張される AES-GCM エンベロープを使用しては なりません。使用すると、Oracle の SET KEY が ORA-00600 [kcbtse_populate_tbskey_1] で失敗します。バルクなテーブルおよび表領域の暗号化は、Oracle が AES-NI を用いてローカルで実行し、データベースから外に出ることはありません。

復号フロー​

手順:

  1. Oracle が C_Decrypt() / C_UnwrapKey() を呼び出す: マスターキーのパスでのアンラップを要求します（例: キーストアのオープン時や SET KEY 時の表領域キーの復元）
  2. ハンドルのルックアップ: 指定されたマスターキーハンドルに対応する UUID を見つけます
  3. メカニズムの解析: アルゴリズム (AES-CBC / AES-CBC-PAD) と IV を抽出します
  4. リクエストの構築: アンラップリクエストを作成します
  5. API 呼び出し: アンラップリクエストを Cockpit に送信します
  6. HSM でのアンラップ: バックエンド HSM が、長さを保持する AES-CBC(-PAD) アンラップを実行します
  7. 表領域キーの受信: アンラップされたキーを取得します
  8. 結果の返却: Oracle に返します

オブジェクト検索フロー​

手順:

  1. C_FindObjectsInit(): テンプレートを用いて検索を初期化します
  2. テンプレートの解析: 検索条件（ラベル、クラスなど）を抽出します
  3. C_FindObjects(): 検索を実行します
  4. API 呼び出し: オブジェクト検索リクエストを Cockpit に送信します
  5. UUID の受信: 一致するオブジェクトの UUID を取得します
  6. ハンドルの作成: UUID をハンドルにマッピングします
  7. ハンドルの返却: ハンドルの配列を Oracle に返します
  8. C_FindObjectsFinal(): 検索状態をクリーンアップします

エラー処理フロー​

ネットワークエラー処理​

認証エラー処理​

注: access_guid は単一の静的なベアラートークンです。トークンエンドポイントもリフレッシュサイクルも存在しないため、拒否されたトークンはライブラリがリトライするものではなく、終端エラー（pkcs11.toml 内の access_guid を確認してください）となります。

HSM エラー処理​

パフォーマンス最適化​

接続の再利用​

メリット:

  • TCP ハンドシェイクのオーバーヘッドを排除します
  • 接続確立の時間を短縮します
  • 全体的なスループットを向上させます

ベアラートークン​

ライブラリは、アプリプロキシの server_url に埋め込まれた単一の access_guid ベアラートークンで、すべてのリクエストを認証します。トークンエンドポイントもリフレッシュサイクルも存在しません。各リクエストで同じトークンが提示され、Cockpit によってサーバー側で検証され、Cockpit はアプリのアイデンティティからテナントを解決します。

メリット:

  • トークン交換のラウンドトリップが不要です
  • ローテーションすべき実行時シークレットがありません（client_id / client_secret がありません）
  • 接続のキープアライブにより、操作ごとの TLS ハンドシェイクが削減されます

ハンドルキャッシング​

メリット:

  • 重複した API 呼び出しを回避します
  • ハンドルの解決が高速になります
  • ネットワークトラフィックが削減されます

モニタリングとデバッグ​

リクエストのトレース​

デバッグログを有効にして、リクエストをトレースします。

export DKE_PKCS11_LOGGING_LEVEL=debug
export DKE_PKCS11_LOGGING_FOLDER=/var/log/dke-pkcs11

ログ出力:

[2025-12-19 10:30:45] [DEBUG] C_Initialize() called
[2025-12-19 10:30:45] [DEBUG] Reading pkcs11.toml (server_url, access_guid)
[2025-12-19 10:30:45] [INFO] Connecting to DuoKey Cockpit: https://cockpit-api-dev.duokey.cloud
[2025-12-19 10:30:46] [INFO] access_guid bearer token validated by Cockpit
[2025-12-19 10:30:46] [DEBUG] C_Initialize() completed: CKR_OK

パフォーマンスメトリクス​

主要なメトリクスをモニタリングします。

  • リクエストレイテンシ: Oracle の呼び出しから応答までの時間
  • API レイテンシ: DuoKey Cockpit API 呼び出しの時間
  • エラー率: 失敗したリクエストの割合
  • 認証失敗: 拒否された access_guid ベアラートークンの数

ネットワークモニタリング​

ネットワークトラフィックをモニタリングします。

  • HTTPS 接続数: アクティブな接続の数
  • リクエスト／レスポンスサイズ: ペイロードのサイズ
  • リトライ回数: リクエストあたりのリトライ数
  • タイムアウトイベント: タイムアウトの発生頻度

ベストプラクティス​

エラー処理​

  1. 一時的なエラーはリトライする: ネットワークエラー、タイムアウト
  2. 認証エラーはリトライしない: 無効な認証情報
  3. すべてのエラーをログに記録する: トラブルシューティングのため
  4. 適切なコードを返す: PKCS#11 コードに変換する

パフォーマンス​

  1. 接続を再利用する: 接続プールを使用する
  2. 接続をキープアライブにする: 操作間で TLS ハンドシェイクを償却する
  3. 操作をバッチ化する: 可能な場合（将来対応）
  4. レイテンシをモニタリングする: パフォーマンスメトリクスを追跡する

セキュリティ​

  1. TLS を使用する: すべての接続を暗号化する
  2. 証明書を検証する: 厳格な証明書検証
  3. 認証情報を保護する: access_guid を決してログに記録しない
  4. pkcs11.toml を保護する: access_guid ベアラートークンをシークレットとして扱い、ファイルのアクセス権限を制限する

次のステップ​