DuoKey PKCS#11 ライブラリ

適用対象:

PKCS#11 (Cryptoki) 2.40Oracle TDEOracle Key VaultDuoKey Cockpit

はじめに

DuoKey PKCS#11 ライブラリは、PKCS#11（Cryptoki）2.40 標準を実装したネイティブの共有ライブラリです。Oracle Database TDE や Oracle Key Vault などのアプリケーションは、他の HSM プロバイダーと同様にこれをロードし、標準の C_* 関数を呼び出します。このライブラリはローカルでは一切暗号処理を行いません — すべての操作は HTTPS 経由で DuoKey Cockpit に送信され、Cockpit がテナントボールトまたは背後の HSM に対してその操作を実行します。鍵素材がアプリケーションホストに存在することはありません。

パッケージング

プロパティ	値
成果物	Linux `libdke_pkcs11.so` ・ Windows `dke_pkcs11.dll`
標準	PKCS#11 (Cryptoki) 2.40
エクスポートされるシンボル	`C_GetFunctionList` — PKCS#11 プロバイダーがエクスポートしなければならない唯一のシンボル。関数テーブル全体を返す
ローカルの暗号処理	なし — すべての操作は DuoKey Cockpit にプロキシされる
マニュファクチャラー ID	DuoKey

アーキテクチャ

アプリケーションが Cockpit と直接やり取りすることはありません。ライブラリをロードすると、各 Cryptoki 呼び出しが Cockpit のプロキシエンドポイントへの単一のリクエストに変換され、Cockpit が操作を実行して結果を返します。

設計上のポイント

ローカルでの暗号処理なし

ライブラリは鍵を保持せず、暗号処理も一切実行しません。ペイロードをエンコードして転送するだけであり、実際の処理はバックエンドが行います。

単一のエクスポートシンボル

C_GetFunctionList のみがエクスポートされ、他のすべての関数は返された関数テーブルを通じて呼び出されます。

シリアルセッション

ライブラリの状態はすべて単一のロックの背後で直列化され、シリアルセッションのみがサポートされます。並列セッションは CKR_SESSION_PARALLEL_NOT_SUPPORTED で拒否されます。

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

PKCS#11 の整数ハンドルはサーバー側のオブジェクト識別子にマッピングされます。記述子はキャッシュされ重複排除されるため、同じオブジェクトは常に同じハンドルを返します。

トークン認証、PIN なし

C_Login はPIN を送信しません — セッションをユーザー状態に移すだけです。認証は、構成から取得されるリクエストごとのベアラートークンによって行われます。

関数カバレッジ

このライブラリは、Cockpit を通じて鍵を管理・使用するために必要な Cryptoki のサブセット — 単一部分操作のみ — を実装しています。関数ごとの完全な一覧は**関数カバレッジ** ページにあります。概要は以下のとおりです。

カテゴリ	実装されている関数
汎用	`C_GetFunctionList`, `C_Initialize`, `C_Finalize`, `C_GetInfo`
スロット & トークン	`C_GetSlotList`, `C_GetSlotInfo`, `C_GetTokenInfo`, `C_GetMechanismList`, `C_GetMechanismInfo`
セッション	`C_OpenSession`, `C_CloseSession`, `C_CloseAllSessions`, `C_GetSessionInfo`, `C_Login`, `C_Logout`
オブジェクト	`C_FindObjectsInit` / `C_FindObjects` / `C_FindObjectsFinal`, `C_GetAttributeValue`, `C_DestroyObject`
暗号化 / 復号	`C_EncryptInit` / `C_Encrypt`, `C_DecryptInit` / `C_Decrypt`（単一部分）
署名 / 検証 / ダイジェスト	`C_Sign`, `C_Verify`, `C_Digest`（単一部分）
鍵管理	`C_GenerateKey`, `C_GenerateKeyPair`, `C_WrapKey`, `C_UnwrapKey`
乱数	`C_GenerateRandom`（`C_SeedRandom` は受理されるが無視される）

サポート対象外（設計上、単一部分のみ）

マルチパート / ストリーミング操作（*_Update / *_Final）、デュアルファンクション暗号、C_DeriveKey、オブジェクトの作成/コピー/属性設定（C_CreateObject、C_CopyObject、C_SetAttributeValue）、トークン/PIN 管理（C_InitToken、C_InitPIN、C_SetPIN）は CKR_FUNCTION_NOT_SUPPORTED を返します。C_GetFunctionStatus と C_CancelFunction は CKR_FUNCTION_NOT_PARALLEL を返します。マスター鍵の操作は構造上単一部分であるため、これらは意図的に省かれています。

メカニズム

C_GetMechanismList は以下のファミリーを公開します（C_GetMechanismInfo は CKF_HW も設定します）。正確な一覧と鍵サイズ範囲については関数カバレッジを参照してください。

ファミリー	メカニズム	操作
AES	`CKM_AES_KEY_GEN`, `CKM_AES_ECB/CBC/CBC_PAD`, `CKM_AES_GCM`, `CKM_AES_KEY_WRAP(_PAD)`	生成、暗号化/復号、ラップ/アンラップ
RSA	`CKM_RSA_PKCS_KEY_PAIR_GEN`, `CKM_RSA_PKCS`, `CKM_RSA_PKCS_OAEP`, `CKM_RSA_PKCS_PSS`, `CKM_SHAn_RSA_PKCS`	生成、暗号化/復号、署名/検証、ラップ/アンラップ
EC	`CKM_EC_KEY_PAIR_GEN`, `CKM_ECDSA`, `CKM_ECDSA_SHA256/384`	生成、署名/検証
ダイジェスト	`CKM_SHA_1`, `CKM_SHA256/384/512`	ダイジェスト（バックエンドでは SHA-256/384/512）
HMAC	`CKM_SHA256/384/512_HMAC`	署名/検証

使用されるメカニズムは利用者次第

これは汎用の Cryptoki プロバイダーであるため、AES、RSA、EC、SHA、HMAC を公開しています。各アプリケーションは必要なものだけを使用します。例えば、Oracle TDE は AES のみを使用します — マスター鍵は AES256 であり、RSA や EC を使用することはありません（Oracle TDE → Cockpit v2 を参照）。他のインテグレーションでは RSA や EC を使用する場合があります。

オブジェクトと属性

オブジェクトクラス: CKO_DATA、CKO_CERTIFICATE、CKO_PUBLIC_KEY、CKO_PRIVATE_KEY、CKO_SECRET_KEY、CKO_DOMAIN_PARAMETERS。
鍵タイプ: CKK_AES、CKK_RSA、CKK_EC、CKK_GENERIC_SECRET、CKK_DSA、CKK_DH、CKK_SHA256/384/512_HMAC。
鍵は CKA_LABEL と CKA_ID によってアドレス指定され、C_GetAttributeValue はキャッシュされた記述子から応答します。
CKA_VALUE は決して返されません — CKR_ATTRIBUTE_SENSITIVE を返します。これは、生の鍵素材がバックエンドにのみ存在するためです。返される鍵はエクスポート不可かつセンシティブとしてマークされます。

構成

このライブラリは、DKE_PKCS11_CONF で指定されたパスから TOML ファイルを読み込みます（Oracle / OKV はこれをウォレット環境で設定します）。環境変数はファイルの設定を上書きします。

pkcs11.tomlTOML

[http_config]
server_url = "https://<cockpit-host>/api/apps/<app_id>/tde/pkcs11/<access_guid>"
access_token = "<access_guid>" # sent as the bearer token
timeout_secs = 30
verify_tls = true

[pkcs11]
slot_id = 0
logging_level = "info"
logging_folder = "/var/log/dke-pkcs11"

環境変数	上書き対象
`DKE_PKCS11_CONF`	TOML ファイルのパス（未設定の場合、以下の変数から構成が組み立てられる）
`DKE_PKCS11_SERVER_URL`	`http_config.server_url`
`DKE_PKCS11_ACCESS_TOKEN`	`http_config.access_token`
`DKE_PKCS11_VERIFY_TLS`	`http_config.verify_tls`
`DKE_PKCS11_SLOT_ID`	`pkcs11.slot_id`
`DKE_PKCS11_LOGGING_LEVEL`	`pkcs11.logging_level`
`DKE_PKCS11_LOGGING_FOLDER`	`pkcs11.logging_folder`

検証を有効なままにしてください

verify_tls の既定値は true です。自己署名証明書に対するテストの場合のみ false に設定してください — これは TLS 証明書の検証を無効化します。

利用者

Oracle Database TDE

TDE マスター鍵を DuoKey に保存するため、/opt/oracle/extapi/64/pkcs11/ からライブラリをロードします。

Oracle Key Vault (OKV)

HSM モード — ライブラリは汎用 PKCS#11 プロバイダーとして okv_hsm.conf から参照されます。

このライブラリではありません

Microsoft SQL Server EKM は、DuoKey PKCS#11 ライブラリではなく、別のプロバイダー（CNG Key Storage Provider DLL）を使用します。SQL EKM ガイドを参照してください。

はじめに​

パッケージング​

アーキテクチャ​

設計上のポイント​