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

オブジェクトハンドルマッピング

DuoKey PKCS#11 ライブラリの重要な側面の 1 つは オブジェクトハンドルマッピング システムであり、PKCS#11 の整数オブジェクトハンドルと DuoKey Cockpit の永続的なキー識別子を橋渡しします。

概要​

課題​

PKCS#11 は整数ハンドル（32 ビット符号なし整数）でオブジェクトを参照するのに対し、DuoKey Cockpit は永続的な識別子（UUID 形式の文字列）でキーを参照します。マッピングシステムは、この 2 つの間を変換します。

PKCS#11 ハンドル​

  • タイプ: CK_OBJECT_HANDLE（整数）
  • スコープ: セッションごと（ハンドルはセッション固有）
  • ライフタイム: セッションが開いている間のみ有効

DuoKey キー識別子​

  • タイプ: 文字列（UUID 形式、例: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx）
  • スコープ: プラットフォーム全体で永続的かつ一意
  • ライフタイム: 永続的（識別子は変更されません）

仕組み​

マッピングプロセス​

ハンドル生成​

ハンドルはセッションごとに生成されます。

アルゴリズム:

  1. 最初のオブジェクトに最初のハンドルを割り当てます。
  2. 新しいオブジェクトごとにインクリメントします。
  3. セッションのハンドルテーブルにマッピングを格納します。

マッピングテーブル​

各セッションは、2 つのビューを持つ独自のマッピングテーブルを維持します。

  • 順引き: ハンドル → キー識別子
  • 逆引き: キー識別子 → ハンドル（高速な逆引き用）

操作: 新しいマッピングの挿入、ハンドルに対する識別子のルックアップ、識別子に対するハンドルの逆引き、およびオブジェクトが破棄されたときのマッピングの削除。

オブジェクトタイプ​

秘密鍵​

ラップ／アンラップ操作に使用される AES キー。

Handle: 0x12345
Type:   CKO_SECRET_KEY
Algorithm: AES-256

データオブジェクト​

Oracle がキーストア情報を追跡するために使用するメタデータオブジェクト。

Handle: 0x12346
Type:   CKO_DATA
Label:  ORACLE.TDE.CDB$ROOT.MK.IDENT

ハンドルのライフサイクル​

作成​

ハンドルは、オブジェクトが見つかったとき（C_FindObjects）、キーが生成されたとき（C_GenerateKey）、またはデータオブジェクトが作成されたとき（C_CreateObject）に作成されます。

使用​

ハンドルを取る操作: C_Encrypt / C_Decrypt（ラップ／アンラップ）、C_GetAttributeValue、および C_DestroyObject。

クリーンアップ​

ハンドルは、セッションのクローズ時に無効化されます。個々のマッピングは、そのオブジェクトが破棄されたときに削除されます。

例示シナリオ​

シナリオ 1: 既存のマスターキーを見つける​

  1. Oracle が { CKA_LABEL: "TDE-MASTER-20251219" } などのテンプレートで C_FindObjects を呼び出します。
  2. ライブラリが、そのラベルによってキーを特定するよう Cockpit に要求します。
  3. Cockpit がキー識別子を返します。
  4. ライブラリがマッピングテーブルを確認します。識別子が新しいため、ハンドル（例: 0x12345）を割り当て、マッピングを格納します。
  5. ハンドル 0x12345 を Oracle に返します。

シナリオ 2: 表領域キーをラップする​

  1. Oracle が C_Encrypt(session, 0x12345, tablespaceKey) を呼び出します。
  2. ライブラリがハンドル 0x12345 のキー識別子をルックアップします。
  3. ライブラリが、そのマスターキーによって表領域キーをラップするよう Cockpit に要求します（長さを保持する AES-CBC-PAD）。
  4. Cockpit がラップされたキーを返します。
  5. ライブラリがラップされたキーを Oracle に返します。

シナリオ 3: 新しいマスターキーを生成する​

  1. Oracle が AES-256 キーのために C_GenerateKey(session, mechanism, template) を呼び出します。
  2. ライブラリがキーのプロビジョニングを Cockpit に要求します。
  3. Cockpit が新しいキー識別子を返します。
  4. ライブラリがハンドル（例: 0x12346）を割り当て、マッピングを格納します。
  5. ハンドル 0x12346 を Oracle に返します。

パフォーマンスに関する考慮事項​

  • ルックアップ: 平均ケースで O(1)（ハッシュマップ検索）。
  • ハンドルの再利用: 同じ識別子が再度要求された場合、重複するマッピングを避けるために既存のハンドルが返されます。
  • 逆引き: 識別子 → ハンドルのマップが高速な逆引きをサポートします。
  • メモリ: マッピングはセッションのクローズ時にクリアされます。

エラー処理​

シナリオレスポンス
Oracle がマッピングテーブルに存在しないハンドルを提供するCKR_OBJECT_HANDLE_INVALID
以前に返されたキー識別子がもはや存在しない（操作の間にオブジェクトが削除された）CKR_DEVICE_ERROR

ベストプラクティス​

  • セッションをまたいでハンドルをキャッシュしない — ハンドルはセッション固有です。
  • 使用前にハンドルを検証します。
  • セッションのクローズ時にマッピングをクリーンアップします。
  • C_DestroyObject で適切に削除し、マッピングが削除されるようにします。

次のステップ​