動作の仕組み
DuoKey PKCS#11 ライブラリの動作の仕組み — プロキシモデル、セッション、ログイン、センシティブな属性、構成の優先順位、既知のクセ。
この注記は、概要 および 関数カバレッジ を補足するものです。エラー、セッション、構成について統合担当者が正しく理解できるよう、プロバイダーの動作を説明します。
プロキシモデル
ライブラリはローカルでは一切暗号処理を行わず、鍵も保持しません。各 Cryptoki 呼び出しは DuoKey Cockpit への単一の HTTPS リクエストに変換され、Cockpit がテナントボールトまたは背後の HSM に対してその操作を実行し、結果を返します。ライブラリはペイロードのエンコードと転送のみを行い、鍵素材が PKCS#11 の境界を越えてアプリケーションホストに渡ることはありません。
- シリアルセッションのみ。 ライブラリの状態はすべて単一のグローバルロックの背後で直列化され、シリアルセッションのみがサポートされます —
C_OpenSessionはCKF_SERIAL_SESSIONを欠くリクエストをCKR_SESSION_PARALLEL_NOT_SUPPORTEDで拒否します。低速なネットワークのラウンドトリップはロックを保持せずに実行されるため、低速なバックエンドが無関係な呼び出しをブロックすることはありません。 - オブジェクトハンドル。 PKCS#11 の整数ハンドルは、サーバー側のオブジェクト識別子にマッピングされます。インターン化によりサーバー ID で重複排除されるため、同じオブジェクトを再発見すると同じハンドルが返されます。
C_DestroyObjectは Cockpit 側のオブジェクトを削除し、その後ローカルのハンドルを破棄します。
ログインと認証
C_Login はPIN を送信しません — pPin / ulPinLen 引数は無視されます。バックエンド認証は、構成から取得されるベアラーアクセストークンによってリクエストごとに運ばれます。C_Login は CKU_USER と CKU_CONTEXT_SPECIFIC のみを受け付け（SO ロールは CKR_USER_TYPE_INVALID を返します）、単にセッションをユーザー状態に移してアプリケーションが処理を続行できるようにします。C_GenerateKey と C_GenerateKeyPair にはログイン状態が必要です。
属性とセンシティブな素材
C_GetAttributeValue はキャッシュされた記述子から応答し、標準的な2段階の Cryptoki バッファプロトコルに従います（null の値ポインタは必要な長さを返し、小さすぎるバッファは CKR_BUFFER_TOO_SMALL を返します）。
CKA_VALUEは常にCKR_ATTRIBUTE_SENSITIVEを返します — 生の鍵素材はバックエンドにのみ存在します。- 鍵は妥当な既定値を報告します:
CKA_TOKEN = true、CKA_SENSITIVE = true、CKA_EXTRACTABLE = false、CKA_NEVER_EXTRACTABLE = true、CKA_MODIFIABLE = false。 - 認識されない属性タイプは
CKR_ATTRIBUTE_TYPE_INVALIDを返します。検索フィルタや鍵生成テンプレート内の認識されない属性は、暗黙的に無視されます。
AES-GCM の処理
AES-GCM では、認証タグは暗号文に連結され（ciphertext || tag）、復号時に分割されるため、呼び出し元には単一の不透明なブロブとして見えます。
ワイヤープロトコル
すべての Cryptoki 操作は、設定された唯一の server_url への単一の HTTPS リクエストであり、ベアラーアクセストークンによって認証されます。暗号処理の失敗は、汎用的なトランスポートエラーではなく、正確な Cryptoki 戻り値にマッピングできる形式で返されます。
構成の優先順位
ライブラリは DKE_PKCS11_CONF から TOML ファイルを読み込み、環境変数がファイルの設定を上書きします。優先順位は環境変数（値が空でない場合）> TOML ファイル > 組み込みの既定値です。ファイルが設定されていない場合、構成はすべて環境変数から組み立てられます（少なくとも DKE_PKCS11_SERVER_URL が必要です）。
verify_tls = falseは TLS 証明書の検証を無効化します — テスト専用です。- ロギングは
C_Initialize時にlogging_level/logging_folderから初期化されます。
完全な pkcs11.toml スキーマと変数一覧については、概要 → 構成 を参照してください。
既知のクセと注意点
CKM_SHA_1はC_GetMechanismListによって公開されますが、SHA-1 ダイジェストはバックエンドによって拒否されます（CKR_MECHANISM_INVALID）— SHA-256/384/512 のみが計算されます。- 暗号化と復号は同じボールトプリミティブを使用するため、Cryptoki のメカニズムは参考情報にすぎません — 利用者が保存する不透明なブロブについて、ラウンドトリップの整合性は保証されます。
C_CreateObject、C_CopyObject、C_SetAttributeValue はサポートされていません（CKR_FUNCTION_NOT_SUPPORTED）。オブジェクトは鍵生成操作（C_GenerateKey / C_GenerateKeyPair）を通じて作成されるか、C_FindObjects で発見されるものであり、クライアント側で属性を1つずつ組み立てて作成されることはありません。
これは汎用の Cryptoki プロバイダーであるため、公開されるメカニズム（AES / RSA / EC / SHA / HMAC）は利用者ごとに使い分けられます。Oracle TDE は AES のみを使用します — マスター鍵は AES256 です。詳細は Oracle TDE → Cockpit v2 を参照してください。