PKCS#11 プロバイダー構成 — pkcs11.toml
DuoKey PKCS#11 プロバイダーの TOML 構成ファイル — そのスキーマと、環境変数による上書き。
DuoKey PKCS#11 プロバイダーは TOML ファイル（通常は pkcs11.toml という名前）で構成します。内容は .../tde/pkcs11/... というプロキシ URL と、access_token ベアラー認証情報です。
pkcs11.toml の構成とテストを示す簡単なデモ動画をここに追加予定です。
以下の値は、Cockpit v2 の Oracle TDE アプリ詳細ページからそのまま取得できます。PKCS#11 Endpoint カードには、正確な server_url、秘密情報ではない access_guid、そして access_token ベアラー認証情報（デフォルトではマスクされ、表示／コピー用のコントロールが付いています）が並べて表示されます。
ファイルの場所
プロバイダーは C_Initialize の時点で、DKE_PKCS11_CONF 環境変数に指定されたパスから TOML ファイルを読み取ります。Oracle はこの変数を Oracle ユーザーのプロファイル（または okvclient.ora / OKV ラッパー）で設定します。OKV での一般的なインストール場所は次のとおりです。
/usr/local/okv/hsm/generic/pkcs11.toml
ファイルパスが指定されていない場合でも、少なくともサーバー URL が設定されていれば、ライブラリは構成を すべて環境変数から 組み立てることができます（環境変数による上書き を参照してください）。
構成スキーマ
# pkcs11.toml — DuoKey PKCS#11 provider configuration for Cockpit v2
[http_config]
# Full Cockpit v2 proxy URL for this Oracle TDE app (required).
# Format: https://<cockpit-api-host>/api/apps/<app_id>/tde/pkcs11/<access_guid>
# Use the API-serving hostname, not the browser/frontend one — Cockpit v2
# typically separates the two (e.g. cockpit-api-<env>.duokey.cloud for the
# API vs cockpit-<env>.duokey.cloud for the UI). The wrong host still
# returns HTTP 200, just with the frontend's HTML instead of JSON.
server_url = "https://cockpit-api-test.duokey.cloud/api/apps/APP_ID/tde/pkcs11/ACCESS_GUID"
# Bearer token used to authenticate every request (default: "").
# This is a distinct, rotatable secret — NOT the access_guid in server_url above.
access_token = "ACCESS_TOKEN"
# HTTP request timeout in seconds (default: 30).
timeout_secs = 30
# Verify the server's TLS certificate (default: true).
# Set to false ONLY for testing against self-signed certificates.
verify_tls = true
# Optional: path to a PEM file holding a client certificate chain and its
# private key, presented to Cockpit v2 for mutual TLS in addition to the
# bearer token. Leave unset for server-auth TLS only (default).
# client_identity_path = "/etc/dke/client-identity.pem"
[pkcs11]
# Id of the single virtual slot the library presents (default: 0).
slot_id = 0
# Logging level: "error" | "warn" | "info" | "debug" | "trace" (default: "info").
logging_level = "info"
# Optional folder for provider log files (default: none — logs to stderr).
logging_folder = "/var/log/dke-pkcs11"
[http_config] — Cockpit v2 への接続
| キー | 型 | デフォルト | 用途 |
|---|---|---|---|
server_url | 文字列 | (必須) | このアプリの完全な Cockpit v2 プロキシ URL。app_id と access_guid をすでに含んでいるため、エンドポイントやテナントを指定する別のフィールドは必要ありません。 |
access_token | 文字列 | "" | Authorization: Bearer … として送信されるベアラートークン。ローテーション可能な独立した秘密情報です。server_url 内の access_guid（ルーティング用の識別子にすぎません）と混同しないでください。 |
timeout_secs | 整数 | 30 | リクエストごとの HTTP タイムアウト。 |
verify_tls | 真偽値 | true | TLS 証明書の検証。本番環境では true のままにしてください。 |
client_identity_path | 文字列 | (なし) | 相互 TLS 用の PEM ファイル（クライアント証明書チェーンと秘密鍵）への任意のパス。設定すると、プロバイダーはベアラートークンに加えてこのクライアント ID を提示します。 |
[pkcs11] — プロバイダーのローカル動作
| キー | 型 | デフォルト | 用途 |
|---|---|---|---|
slot_id | 整数 | 0 | Oracle に公開される単一の仮想スロットの ID。 |
logging_level | 文字列 | "info" | プロバイダーログの詳細度。 |
logging_folder | 文字列 | (なし) | プロバイダーログのディレクトリ。未設定の場合、ログは stderr に出力されます。 |
エンドポイントと認証モデル
エンドポイント
すべての Cryptoki 操作は、server_url への単一の POST です。同じ URL への GET は、レディネス／ハンドシェイクのプローブとして使用されます。
認証
ベアラートークン access_token を使用します。これは、URL 内の access_guid とは異なる、ローテーション可能な独立した秘密情報です。OAuth2 のクライアントクレデンシャルフローも、ユーザー名／パスワードも、OpenID Connect のディスカバリーも 使用しません。
テナントの解決
pkcs11.toml に テナントのフィールドはありません。Cockpit v2 は、URL 内の (app_id, access_guid) のペアからサーバー側でテナントを解決します。
TLS
デフォルトは verify_tls = true です。クライアント証明書による認証（相互 TLS）は オプトイン で利用できます。client_identity_path に、クライアント証明書チェーンと秘密鍵を含む PEM ファイルを指定すると、プロバイダーはベアラートークンとあわせてそれを提示します。サーバー認証のみの TLS（デフォルト）とする場合は、未設定のままにしてください。
access_token はベアラー認証情報です。秘密として扱ってください。ファイルへのアクセスは Oracle の OS ユーザーに限定し（例えば所有者を oracle として chmod 600）、万一漏洩した場合は Cockpit からアプリのアクセストークンをローテーションしてください。server_url 内の access_guid はそれ自体が秘密情報というわけではありませんが、アプリを識別するものであり、URL パスに含まれる（DuoKey の管理外にあるリバースプロキシやイングレスのアクセスログに残る可能性がある）ため、いずれにせよファイル全体を保護してください。
環境変数による上書き
環境変数はファイルよりも優先されるため、基本となる pkcs11.toml を用意しておき、ホストごとに上書きすることができます。
| 環境変数 | 上書き対象 |
|---|---|
DKE_PKCS11_CONF | pkcs11.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（0 / false / no = 無効） |
DKE_PKCS11_CLIENT_IDENTITY | http_config.client_identity_path |
DKE_PKCS11_SLOT_ID | pkcs11.slot_id |
DKE_PKCS11_LOGGING_LEVEL | pkcs11.logging_level |
DKE_PKCS11_LOGGING_FOLDER | pkcs11.logging_folder |
これらの値を手作業で組み立てる必要はありません。Cockpit v2 で Oracle TDE アプリを開き、その デプロイバンドル を使用してください。Cockpit が pkcs11.toml（正しい server_url と access_guid を含みます）、環境変数のエクスポート、および Oracle SQL スクリプトを生成し、ダウンロードできるようにします。