構成
DuoKey Cockpit に対して、PKCS#11 プロバイダーは pkcs11.toml ファイルと、オプションの DKE_PKCS11_* 環境変数による上書きで構成します。このファイルが保持するのは、Cockpit プロキシ URL と access_guid ベアラートークンという 2 つの必須項目だけです。Cockpit がアプリとテナントをサーバー側で解決するためです。
このページでは、構成モデルをアーキテクチャレベルで説明します。完全なスキーマ、デフォルト、および v1 → v2 の移行マッピングについては、PKCS#11 プロバイダー構成 (pkcs11.toml) を参照してください。
概要
構成ファイル
プロバイダーは、C_Initialize の時点で、DKE_PKCS11_CONF 環境変数に指定されたパスから構成を読み込みます。Oracle はこれを Oracle ユーザーのプロファイル（または OKV ラッパー）に設定します。一般的なインストールパスは次のとおりです。
/usr/local/okv/hsm/generic/pkcs11.toml
スキーマ
# pkcs11.toml — DuoKey PKCS#11 provider configuration
[http_config]
# Full Cockpit proxy URL for this Oracle TDE app (required).
# It already contains the app identity and access_guid, so no separate
# endpoint, tenant, or credential fields are needed.
server_url = "https://cockpit.example.com/api/apps/APP_ID/tde/pkcs11/ACCESS_GUID"
# Bearer token used to authenticate every request — the app's access_guid.
access_token = "ACCESS_GUID"
# 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
[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 への接続
| キー | 型 | デフォルト | 目的 |
|---|---|---|---|
server_url | 文字列 | （必須） | このアプリ向けの完全な Cockpit プロキシ URL。アプリの識別情報と access_guid を含むため、別途エンドポイントやテナントのフィールドは不要です。 |
access_token | 文字列 | "" | Authorization: Bearer … として送信されるベアラートークン。Oracle TDE の場合、これはアプリの access_guid です。 |
timeout_secs | 整数 | 30 | リクエストごとの HTTP タイムアウト。 |
verify_tls | ブール値 | true | TLS 証明書の検証。本番環境では true のままにしてください。 |
[pkcs11] — ローカルのプロバイダー動作
| キー | 型 | デフォルト | 目的 |
|---|---|---|---|
slot_id | 整数 | 0 | Oracle に公開される単一の仮想スロットの ID。 |
logging_level | 文字列 | "info" | プロバイダーのログの詳細度。 |
logging_folder | 文字列 | （なし） | プロバイダーのログ用ディレクトリ。未設定の場合、ログは stderr に出力されます。 |
認証モデル
- 単一の認証情報。 認証は、
server_urlに埋め込まれaccess_tokenとして繰り返される、単一のaccess_guidベアラートークンです。OAuth2 クライアントクレデンシャルフローはなく、client_id/client_secretもなく、ユーザー名／パスワードもなく、OpenID Connect ディスカバリもありません。 - テナントフィールドなし。 Cockpit は、URL 内のアプリ識別情報からテナントをサーバー側で解決します。クライアント側にテナント ID やテナントヘッダーはありません。
- ボールトフィールドなし。 背後のボールト／キーストアは Cockpit のアプリによって管理され、クライアント側では構成しません。
server_url / access_token に含まれる access_guid はベアラー認証情報です。ファイルを Oracle OS ユーザーに限定し（例: chmod 600、所有者 oracle）、万一露出した場合はアプリのアクセストークンを Cockpit からローテーションしてください。
環境変数による上書き
環境変数はファイルより優先されるため、ベースとなる 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_SLOT_ID | pkcs11.slot_id |
DKE_PKCS11_LOGGING_LEVEL | pkcs11.logging_level |
DKE_PKCS11_LOGGING_FOLDER | pkcs11.logging_folder |
ファイルパスが指定されない場合でも、少なくともサーバー URL とアクセストークンが設定されていれば、ライブラリは構成を完全に環境変数から組み立てることができます。
値の取得
これらの値を手作業で組み立てることはありません。Cockpit で Oracle TDE アプリを開き、そのデプロイバンドルを使用してください。Cockpit が、pkcs11.toml（正しい server_url と access_guid を含む）、環境変数のエクスポート、および Oracle SQL スクリプトを生成し、ダウンロードできるようにします。
検証
ライブラリは初期化時に構成を検証します。
- サーバー URL が存在し、正しい形式である。
- アクセストークンが存在する。
- 失敗した場合、初期化は
CKR_DEVICE_ERROR（接続／構成）またはCKR_PIN_INCORRECT（認証）を返します。
セキュリティのベストプラクティス
pkcs11.tomlやaccess_guidを決してバージョン管理にコミットしないでください。- ファイル権限を Oracle OS ユーザーに限定してください（
chmod 600）。 - アプリのアクセストークンを定期的なスケジュールで、また露出した場合はただちに Cockpit からローテーションしてください。
verify_tls = trueを維持し、すべての接続に TLS 1.2 以上を使用してください。
次のステップ
- 通信フロー → - 構成がどのように使用されるかを見る
- アーキテクチャ概要 → - 全体的なアーキテクチャを理解する
- PKCS#11 プロバイダー構成 (pkcs11.toml) → - 完全なスキーマと v1 → v2 マッピング