トラブルシューティング

このセクションでは、Cockpit v2 に対して DuoKey PKCS#11 プロバイダーを使用する Oracle TDE のトラブルシューティング手順とデバッグ手法を説明します。

Cockpit v2 のモデル

プロバイダーは pkcs11.toml ファイル（DKE_PKCS11_CONF 環境変数で場所を指定します）で構成し、access_token ベアラー認証情報 で認証します。server_url に含まれる access_guid は、認証情報ではなく、秘密情報ではない別個のルーティング識別子です。OAuth2 のクライアントクレデンシャルフロー、ユーザー名／パスワード、テナントやボールトの個別フィールドはいずれも存在しません。HSM パートナーは Securosys です。

診断チェックリスト

TDE の問題をトラブルシューティングする際は、次の体系的なアプローチに従ってください。

ステップ 1: PKCS#11 ライブラリが正しくインストールされていることを確認する

ライブラリは 変更せずに インストールします。出荷時の名前を維持し、libpkcs11.so にリネームしないでください。

# Linux: the library lives here for Oracle Database
ls -la /opt/oracle/extapi/64/hsm/DuoKey/1.0/libdke_pkcs11.so

# Oracle Key Vault (OKV) installs it under the generic HSM directory instead
ls -la /usr/local/okv/hsm/generic/libdke_pkcs11.so

# Verify it is a valid shared object
file /opt/oracle/extapi/64/hsm/DuoKey/1.0/libdke_pkcs11.so

# Check the Cryptoki entry point is exported
nm -D /opt/oracle/extapi/64/hsm/DuoKey/1.0/libdke_pkcs11.so | grep C_GetFunctionList

Windows では、プロバイダーは dke_pkcs11.dll です。

glibc と OS の一致

ライブラリは、ご使用の OS 向けのビルドである必要があります。Oracle のリリースから glibc のバージョンを推測しないでください。 ビルドを依頼する前に、ldd --version | head -1 で実際のホストを確認してください。例えば、Oracle 自身が提供する公式の 19.3.0.0 Enterprise Edition コンテナイメージは、OL8 ではなく Oracle Linux 7.9 / glibc 2.17 で動作しています。ホストが提供する glibc より新しい glibc に対してビルドされたライブラリは dlopen に失敗し、初期化にすら至らないため、プロバイダーのログは まったく 出力されません。これは、キーストアのオープンが失敗する最も多い原因です。後述の ORA-28353 を参照してください。

確認済み: この不一致（GLIBC_2.18' not found、skgdllDiscover did not find any library files、ORA-28376: cannot find PKCS11 library）は、OL7 ベースで glibc が 2.17 までしか含まれない公式の 19.3.0.0 Enterprise Edition イメージに対して、実際に再現しました。OL7 のベースライン (glibc 2.17 以下) でライブラリを再ビルドすることで解決しています。glibc には後方互換性があるため、同じ OL7 でビルドしたライブラリは OL8／OL9 のホスト (21c、23ai 以降) でも使用できます。Oracle のバージョンごとに個別のビルドを用意する必要はありません。サポートする 最も古い ホストに合わせて 1 回ビルドしてください。

ステップ 2: 構成ファイルと環境を確認する

# As the oracle user, confirm the config path is exported
sudo su - oracle
echo "$DKE_PKCS11_CONF"          # e.g. /etc/dke/pkcs11.toml

# Confirm the file exists and is readable by oracle
ls -la "$DKE_PKCS11_CONF"

# Review the effective settings (server_url, access_token, verify_tls, logging)
cat "$DKE_PKCS11_CONF"

どのフィールドも DKE_PKCS11_* 環境変数で上書きできます（構成リファレンスを参照）。両方が設定されている場合は、環境変数が優先されます。

ステップ 3: ライブラリを単体でテストする

export DKE_PKCS11_CONF=/etc/dke/pkcs11.toml

# List the single virtual slot the library presents
pkcs11-tool --module /opt/oracle/extapi/64/hsm/DuoKey/1.0/libdke_pkcs11.so --list-slots

# List objects (the PIN here is advisory — the real credential is the access_guid)
pkcs11-tool --module /opt/oracle/extapi/64/hsm/DuoKey/1.0/libdke_pkcs11.so -l --pin 1234 --list-objects

ステップ 4: Oracle の構成を確認する

-- Connect as SYSDBA
sqlplus / as sysdba

-- Check wallet root and TDE configuration
SHOW PARAMETER wallet_root;
SHOW PARAMETER tde_configuration;   -- should reference KEYSTORE_CONFIGURATION=HSM

-- Check keystore status
SELECT CON_ID, WRL_TYPE, STATUS FROM V$ENCRYPTION_WALLET;

キーストアタイプは HSM です。ADMINISTER KEY MANAGEMENT ステートメントにおける PIN 文字列（例えば "user:1234"）は 補助的なもの であり、Cockpit への呼び出しを実際に認可する認証情報は pkcs11.toml 内の access_guid です。

ステップ 5: ログを確認する

# DuoKey PKCS#11 provider log (path from logging_folder / DKE_PKCS11_LOGGING_FOLDER)
tail -100 /var/log/dke-pkcs11/*.log

# Oracle alert log
tail -100 $ORACLE_BASE/diag/rdbms/$ORACLE_SID/$ORACLE_SID/trace/alert_$ORACLE_SID.log

# Oracle trace files (if errors occurred)
ls -lt $ORACLE_BASE/diag/rdbms/$ORACLE_SID/$ORACLE_SID/trace/*.trc | head -5

プロバイダーのログがまったく出力されない場合

操作が失敗した後に /var/log/dke-pkcs11/ が空であれば、ほぼ確実にライブラリが一度もロードされていません（パスの誤り、ベンダー／バージョンディレクトリの誤り、または glibc の不一致したビルド）。ステップ 1 から確認を始めてください。

よくあるエラーのシナリオ

ORA-28353: ウォレットのオープンに失敗する

症状:

ORA-28353: failed to open wallet

最も多い根本原因 — glibc と OS の不一致。 libdke_pkcs11.so のビルドがデータベースホストの OS と一致していないため、C_Initialize が実行される前の段階で、Oracle によるライブラリの dlopen が失敗します。決定的な手がかりは、/var/log/dke-pkcs11/ にエントリが まったく 存在しないことです。プロバイダーはログを記録する段階まで到達していません。

その他の原因:

.so が誤ったベンダー／バージョンディレクトリにある、または存在しない。
ライブラリがリネームされている（libpkcs11.so ではなく libdke_pkcs11.so のままでなければなりません）。
oracle ユーザーがライブラリまたは構成ファイルを読み取れない。

デバッグ手順:

# 1. Confirm the deployed library is in the exact expected directory
ls -la /opt/oracle/extapi/64/hsm/DuoKey/1.0/libdke_pkcs11.so

# 2. Confirm it loads and resolves all dependencies on THIS host
ldd /opt/oracle/extapi/64/hsm/DuoKey/1.0/libdke_pkcs11.so   # look for "not found"

# 3. Confirm the glibc on this host
ldd --version | head -1

# 4. Check the Oracle alert log for the dlopen failure
tail -100 $ORACLE_BASE/diag/rdbms/$ORACLE_SID/$ORACLE_SID/trace/alert_$ORACLE_SID.log | grep -i -E "pkcs11|dlopen|hsm"

解決策: /opt/oracle/extapi/64/hsm/DuoKey/1.0/（OKV の場合は /usr/local/okv/hsm/generic/）に変更なしで配置されている libdke_pkcs11.so のビルドが、このホストの glibc と一致していることを確認してください。確認には ldd --version | head -1 を使用し、Oracle のバージョンから推測しないでください。このホストが提供するものより新しい glibc 向けのビルドをデプロイしている場合は、ご使用の OS に合ったビルドに置き換えてください。

403 / 無効なアクセストークン

症状:

プロバイダーのログに認証の拒否が記録され、キーストアのオープンまたはキー操作が失敗します。

[ERROR] Cockpit request rejected: 403 Forbidden (invalid access token)

考えられる原因:

pkcs11.toml 内の access_guid（access_token、または DKE_PKCS11_ACCESS_TOKEN による上書き）が、server_url に埋め込まれた access_guid と一致していない、または Cockpit 上のアプリと一致していない。
Cockpit 上で Oracle TDE アプリが 無効化されている（またはトークンがローテーションされた）。

デバッグ手順:

# Confirm access_token matches the access_guid in the server_url
grep -E "server_url|access_token" "$DKE_PKCS11_CONF"

# Confirm the Cockpit API host is reachable (not the frontend hostname —
# a wrong host still returns HTTP 200, just with an HTML page instead of JSON)
curl -I https://<cockpit-api-host>/

解決策: Cockpit v2 からアプリの デプロイバンドル を再ダウンロードし（一致する pkcs11.toml が再生成されます）、Cockpit 上でアプリが有効になっていることを確認してください。トークンを手作業で編集しないでください。

ORA-00600 [kcbtse_populate_tbskey_1]

症状:

ORA-00600: internal error code, arguments: [kcbtse_populate_tbskey_1], ...

原因: TDE のキーパスで 長さが保存されない ラップが使用されました。例えば AES-GCM のエンベロープは IV と認証タグを付加するため、暗号文の長さが変わります。Oracle TDE では、キーのラップが 長さを保存する 方式、すなわち AES-CBC（PKCS パディング付き、AES-CBC-PAD）である必要があります。長さが変わるラップは表領域キーの生成を破損させ、この ORA-00600 として現れます。

解決策: TDE のパスで TDE マスターキーを AES-CBC(-PAD) でラップするプロバイダーのビルド／構成を使用してください。誤ったラッピングメカニズムでアプリが作成されていた場合は、デプロイバンドルを再ダウンロードし、修正後に再キー設定を行ってください。

ORA-46664: すべてのコンテナでマスターキーが作成されていない

症状:

ORA-46664: master key not created for all PDBs

通常、CONTAINER=ALL によるキー設定／再キー設定の際に発生します。

考えられる原因:

再キー設定の時点で、1 つ以上の PDB が OPEN READ WRITE になっていなかった。
すべてのコンテナに対してマスターキーが作成されなかった。

デバッグ手順:

-- Confirm every PDB is OPEN READ WRITE
SELECT con_id, name, open_mode FROM v$pdbs ORDER BY con_id;

-- See which containers already have a key
SELECT con_id, key_id, activation_time FROM v$encryption_keys ORDER BY con_id;

解決策: すべての PDB を READ WRITE で開くか、コンテナごとに個別のセッションでキーを設定してください。まずルート (CDB$ROOT) でキーを設定し、続いて各 PDB で個別に設定します。

-- In the root
ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY "user:1234" WITH BACKUP CONTAINER=CURRENT;

-- Then, connected into each PDB
ALTER SESSION SET CONTAINER = <pdb_name>;
ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY "user:1234" WITH BACKUP CONTAINER=CURRENT;

ORA-46693 / ORA-28365: ライブラリまたはキーストアが開いていない

症状:

ORA-46693: An error occurred while loading library for Transparent Data Encryption
ORA-28365: wallet is not open

考えられる原因:

PKCS#11 ライブラリをロードできなかった（glibc／パスの確認については ORA-28353 を参照）。
現在のコンテナで HSM キーストアが開いていない。
ライブラリは Cockpit に到達したが、操作が失敗した（接続性、TLS、またはトークンの拒否）。
ある sqlplus セッションでキーストアを開き、それに依存する操作 (SET KEY、ALTER TABLESPACE … ENCRYPT) を、しばらく後に別のセッションで実行した。SET KEYSTORE OPEN がその直前に成功を報告していても、Oracle のデフォルトの HSM 接続ハートビートによって、その間にキーストアが閉じられることがあります。

デバッグ手順:

-- Is the keystore open in this container?
SELECT CON_ID, WRL_TYPE, STATUS FROM V$ENCRYPTION_WALLET;

# Provider log detail for the failed operation
tail -200 /var/log/dke-pkcs11/*.log

解決策: ライブラリがロードされることを確認し（ステップ 1）、HSM キーストアを開き、Cockpit への接続性を確認してください（後述）。直前にキーストアが OPEN と報告されていた場合は、同じスクリプト／セッション内で、依存するステートメントの直前に SET KEYSTORE OPEN を再実行するか、_heartbeat_period_multiplier を大きくしてください（ベストプラクティスを参照）。

バックグラウンドプロセスでの ORA-28407 の後に発生するインスタンスのクラッシュ (ORA-03113)

症状:

アラートログに kzthsmcc encountered: ORA-28407 ... HSM heartbeat check failed to cache object handle、HSM connection lost, closing wallet が記録され、最終的にバックグラウンドプロセス（多くは DBW0）がインスタンスを終了させ、接続中のクライアントには ORA-03113: end-of-file on communication channel として現れます。

原因: DKE_PKCS11_CONF が、インスタンス自身 が起動された環境から見えていませんでした。例えば、Oracle OS ユーザーのシェルプロファイルを一度も読み込まないコンテキスト（素の docker exec、非ログインの ssh コマンド、.bash_profile を継承しないサービスマネージャーなど）からデータベースが起動された場合です。クライアントセッションが個別にこの変数をエクスポートすれば手動でキーストアを開くことはできてしまうため、問題が見えにくくなります。しかし、Oracle のバックグラウンドの HSM ハートビートチェックは インスタンス自身の 環境に対して実行されるため、何も表面化しないまま失敗し続け、最終的にバックグラウンドプロセスを停止させます。

解決策: はじめにで説明しているとおり、DKE_PKCS11_CONF を /home/oracle/.bash_profile（または .profile）に永続化し、常にそれを読み込むログインシェルからデータベースを起動／再起動してください。クラッシュ後は、ホスト／インスタンスを再起動し、新しい sudo su - oracle セッションで変数が設定されていることを確認してから、そのセッションで STARTUP を再実行してください。

ORA-28374: 指定された型のマスターキーがウォレットに見つからない

症状:

ORA-28374: typed master key not found in wallet

考えられる原因:

キーストアが閉じている。
このコンテナではまだマスターキーが作成されていない。

解決策:

-- If the keystore is closed, reopen it (PIN is advisory; the access_guid authorizes)
ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN
  IDENTIFIED BY "user:1234"
  CONTAINER=ALL;

-- If no key exists, create the master key
ADMINISTER KEY MANAGEMENT SET KEY
  IDENTIFIED BY "user:1234"
  WITH BACKUP
  CONTAINER=ALL;

接続性と TLS のトラブルシューティング

すべての Cryptoki 操作は、pkcs11.toml 内の server_url に対する HTTPS 呼び出しです。Cockpit ホストに到達できない場合、または verify_tls = true の状態でサーバー証明書を検証できない場合、キーストアおよびキーの操作は失敗します。

Cockpit への到達性をテストする:

# Basic HTTPS reachability
curl -I https://<cockpit-host>/

# TCP reachability on 443
nc -zv <cockpit-host> 443

TLS 証明書を確認する:

# Inspect the certificate the Cockpit presents
openssl s_client -connect <cockpit-host>:443 -showcerts </dev/null

Cockpit がホスト側で信頼されていない証明書を使用している場合は、検証を無効化するのではなく、その CA をホストのトラストストアに追加してください。
verify_tls = false（または DKE_PKCS11_VERIFY_TLS=false）は 自己署名証明書に対するテスト専用 です。本番環境では true のままにしてください。

次にプロバイダーのログを確認します。 /var/log/dke-pkcs11/ で具体的な接続エラーやハンドシェイクエラーを確認し、セットアップ中は logging_level を debug に上げてください。

grep -i -E "connect|handshake|timeout|tls|certificate" /var/log/dke-pkcs11/*.log

プロバイダーログの分析

DuoKey PKCS#11 プロバイダーは、logging_folder で指定したディレクトリ（本ドキュメントでは既定として /var/log/dke-pkcs11/ を参照しています）に書き込みます。トラブルシューティング中は logging_level を debug に上げ、終わったら元に戻してください。

確認すべき主なポイント:

初期化 — プロバイダーが pkcs11.toml を読み取り、server_url を解決し、Cockpit に対するレディネスプローブを完了したか。
認証 — access_token ベアラー認証情報が受け入れられたか（ここで 403 が出る場合は、前述の 403 / 無効なアクセストークン のシナリオを参照してください）。
キー操作 — 生成／暗号化／復号の呼び出しと、その結果コード。
接続エラー — DNS、TCP、タイムアウト、または TLS ハンドシェイクの失敗は、接続性と TLS のセクションに該当します。

失敗後にログディレクトリが空である場合、ライブラリは一度もロードされていません。ORA-28353 ／ステップ 1 の確認に戻ってください。

Oracle アラートログの分析

Oracle のアラートログには、プロバイダーの問題を診断するのに役立つ TDE 関連のメッセージが記録されます。

ロードとオープンの成功時:

TDE: Loading PKCS#11 library: /opt/oracle/extapi/64/hsm/DuoKey/1.0/libdke_pkcs11.so
TDE: PKCS#11 library loaded successfully
TDE: HSM keystore opened successfully

ライブラリのロード失敗（glibc ／パス）:

TDE: Failed to load PKCS#11 library: /opt/oracle/extapi/64/hsm/DuoKey/1.0/libdke_pkcs11.so
TDE: Error: dlopen() failed: cannot open shared object file

解決策: ライブラリのパスを確認し、デプロイしたビルドの glibc がこのホストのものと一致していることを確認してください。確認には ldd --version | head -1 を使用し、Oracle のバージョンから推測しないでください（ORA-28353 を参照）。

TDE: PKCS#11 function C_Initialize failed: CKR_DEVICE_ERROR

解決策: プロバイダーのログを確認し、Cockpit への接続性を検証し、access_guid を確認してください。

構成リファレンス

pkcs11.toml の完全なスキーマ、すべてのフィールド、およびすべての DKE_PKCS11_* 環境変数による上書きは、PKCS#11 プロバイダー構成 (pkcs11.toml) に正式なリファレンスとして一箇所にまとめられています。デバッグ時にここで内容を重複させず、トラブルシューティング対象のファイルと並べてそのページを開いてください。

デバッグに役立つ SQL クエリ

キーストアの状態を確認する:

SELECT CON_ID, WRL_TYPE, STATUS, WALLET_TYPE
FROM V$ENCRYPTION_WALLET
ORDER BY CON_ID;

すべての暗号化キーを一覧表示する:

SELECT
  CON_ID,
  KEY_ID,
  TAG,
  ACTIVATION_TIME,
  CREATOR
FROM V$ENCRYPTION_KEYS
ORDER BY CON_ID, ACTIVATION_TIME DESC;

暗号化された列を一覧表示する:

SELECT
  OWNER,
  TABLE_NAME,
  COLUMN_NAME,
  ENCRYPTION_ALG,
  SALT,
  INTEGRITY_ALG
FROM DBA_ENCRYPTED_COLUMNS
ORDER BY OWNER, TABLE_NAME, COLUMN_NAME;

暗号化された表領域を一覧表示する:

SELECT
  tablespace_name,
  encrypted,
  encryptionalg
FROM dba_tablespaces
WHERE encrypted = 'YES'
ORDER BY tablespace_name;

TDE のパラメーターを確認する:

SHOW PARAMETER wallet_root;
SHOW PARAMETER tde_configuration;
SHOW PARAMETER encrypt;

ウォレットの場所を表示する:

SELECT * FROM V$WALLET;

どの PDB が暗号化キーを持っているかを確認する:

SELECT
  p.con_id,
  p.name AS pdb_name,
  ek.key_id,
  ek.activation_time
FROM v$pdbs p
LEFT JOIN v$encryption_keys ek ON p.con_id = ek.con_id
ORDER BY p.con_id;

Linux でのデプロイに関する注意事項

Linux はエンドツーエンドで検証済み であり、XE エディションだけでなく、Oracle 自身が提供する公式の Enterprise Edition コンテナイメージに対しても確認しています。Oracle 19.3.0.0 Enterprise Edition（Oracle Linux 7.9）に対して、SET KEYSTORE OPEN (CONTAINER=ALL)、CDB ルートと PDB の両方での SET KEY、および実際の CREATE TABLESPACE ... ENCRYPTION の一往復（挿入、選択）がいずれも成功しました。この検証で明らかになった唯一の実際の不具合は、前述の glibc と OS の不一致です。再現可能なビルドが以前は Oracle Linux 8 (glibc 2.28) を対象としており、公式の 19.3.0.0 イメージの実際の OL7 ベース (glibc 2.17) ではロードできませんでした。サポート対象の最も古いホスト (OL7) に対してビルドすることで解決し、現在はこれが既定です。同じビルドは新しいホストもカバーするため、Oracle のバージョンごとに個別のビルドを用意する必要はありません。

ご自身でスクリプト化する場合に知っておく価値のある運用上の詳細が 2 つあります。1 つは、WALLET_ROOT は SPFILE スコープであり、有効にするにはインスタンスの完全な再起動が必要であることです（これを回避する方法はありません。DuoKey ではなく Oracle 側の要件です）。もう 1 つは、キーストアのオープンから SET KEY までの一連の流れを 1 つの セッションで最後まで実行すべきであることです。PKCS#11 のログイン状態はプロセスごとに保持されるため、この流れを複数の接続に分割すると、（Oracle から見て）キーストアがすでに開いた後に新たに確立した接続は、その新しいセッションのプロセス内で HSM に自動的に再認証されません。

Oracle 12.2 のベースリリース (12.2.0.1.0): WALLET_ROOT ではなく sqlnet.ora を使用する

WALLET_ROOT と TDE_CONFIGURATION インスタンスパラメーターは、ベースリリースの 12.2.0.1.0 には 存在しません（どちらに対する ALTER SYSTEM SET も ORA-02065: illegal option for ALTER SYSTEM を発生させ、v$parameter にも存在しないことを確認済みです）。これらは GA リリースではなく、後の 12.2 Release Update ／ 18c 以降で追加されました。本物の Oracle Database 12.2.0.1.0 Enterprise Edition（コミュニティイメージではなく、実際のインストーラーメディアから構築したもの）に対して、WALLET_ROOT 以前の仕組みを使用してエンドツーエンドで検証済みです。sqlnet.ora（network/admin ディレクトリ、または TNS_ADMIN が指す場所）に次を追加してください。

ENCRYPTION_WALLET_LOCATION =
  (SOURCE =
    (METHOD = HSM)
  )

これにより、最新の (12c 以降の) ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN ／ SET KEY の構文が、このページの他の箇所で説明しているとおりに動作します。WALLET_ROOT とは異なり、この手順ではインスタンスの再起動は不要です。対象のリリースでどちらの仕組みが必要か分からない場合は、まず v$parameter に wallet_root があるかを確認し、存在しなければ sqlnet.ora を使用してください。

Oracle 11g R2 における未適用パッチ由来の ORA-28376 の制約は、Windows 固有の癖ではなく、プラットフォーム横断で確認されています。 Linux 上の gvenzl/oracle-xe:11-slim（Oracle Database 11g Express Edition Release 11.2.0.2.0）に対して、ライブラリを正しく配置し読み取り可能にした状態（パス／権限／glibc という通常の原因を排除した状態）で再テストしたところ、ALTER SYSTEM SET ENCRYPTION WALLET OPEN と ALTER SYSTEM SET ENCRYPTION KEY はいずれも ORA-28376: cannot find PKCS11 library で失敗しました。さらに、Windows での確認結果と同じシグネチャとして、セッションのトレースファイルのどこにも kzthsminit ／ HSM TRACING のエントリが存在せず、パッチ適用前の Oracle は PKCS#11 の検出ステップを試みてすらいないことが分かります。これは OS とは無関係な、Oracle カーネルの基本的な動作です。なお、Oracle XE エディションは個別にパッチを適用できない（opatch に対応していない）ため、XE ではこの制約を解除できません。11g R2 で実際に HSM のパスをテストするには、パッチ適用済みの 11.2.0.4 Enterprise ／ Standard Edition のインストールが必要です。

Windows でのデプロイに関する注意事項

Windows はエンドツーエンドで検証済みです。 Windows 向け Oracle 21.3.0.0.0 Enterprise Edition に対し、Cockpit v2 への実際のネットワーク接続を通じて、SET KEYSTORE OPEN、SET KEY、および実際の CREATE TABLESPACE ... ENCRYPTION の一往復（挿入、選択、キーストアを閉じた状態ではアクセス不可 — ORA-28365 — であることの確認）がいずれも成功しました。詳しい手順についてははじめに (Windows) を参照してください。以下のリファレンス表は、起こりうるすべての問題と、それらの見分け方を網羅しています。その多くは、見た目が同じ汎用的な ORA-28353／ORA-28407 として現れるため、エラーコードそのものよりも、診断上のシグナル（どのログに詳細があるか、curl が何を返すか）のほうが重要です。

症状	原因	対処
`ORA-28353`／`ORA-28407`、プロバイダーのログが空、セッション自身のトレースファイルに `PKCS#11 error code 5`	`pkcs11.toml` を Oracle サービスアカウントが読み取れない	`NT SERVICE\OracleService<SID>` に明示的にアクセス権を付与します: `icacls <path> /grant "NT SERVICE\OracleService<SID>:(F)"`。正確なアカウントは `Get-WmiObject Win32_Service -Filter "Name='OracleService<SID>'" \| Select StartName` で確認してください。別の Oracle Home 由来の既存の ACL エントリが正しいものだと決めつけないでください。
`server_url` に対する `curl`／`Invoke-WebRequest` が、JSON ではなく HTML ページとともに `HTTP 200` を返す	`server_url` が API ではなくフロントエンドのホスト名を指している	ブラウザー UI 用ではなく、API を提供するホスト名（例: `cockpit-api-<env>.duokey.cloud`）を使用してください。
`ORA-28353`、ライブラリが一向に見つからない、`skgdllDiscover did not find any library files`	ライブラリが `%ORACLE_HOME%\extapi\` または `%ORACLE_BASE%\extapi\` 配下にデプロイされている	代わりに固定パス `C:\oracle\extapi\64\hsm\DuoKey\1.0\dke_pkcs11.dll` にデプロイしてください。データベースソフトウェアや `ORACLE_BASE` の実際の場所とは無関係であることを確認済みです。
DLL のロードに失敗する、Win32 エラー 126	動的リンクされた CRT (`VCRUNTIME140.dll`、`api-ms-win-crt-*`) がホストに存在しない	`RUSTFLAGS="-C target-feature=+crt-static" cargo build --release -p dke-pkcs11` でビルドし、`dumpbin /DEPENDENTS dke_pkcs11.dll` で確認してください。
`ORA-07445 [kzthsminit_discover_load_pkcs_lib]` または `[kzthsminit_load_pkcs_lib]`、インスタンスのクラッシュ	実在する、まれで非決定的な Oracle 側の不具合 — 後述を参照	再実行してください。構成の問題を示すものではありません。
`ALTER SYSTEM SET TDE_CONFIGURATION=HSM` の直後の `ORA-28353`／クラッシュ、ベンダー／バージョンディレクトリ配下に複数のファイルがある	Oracle のディレクトリ検出の走査が複数の候補を正しく処理できない	`<vendor>\<version>` ディレクトリごとに、ファイルをちょうど 1 つに保ってください。
Oracle 11g R2 での `ORA-28376: cannot find PKCS11 library`	パッチ未適用の 11.2.0.x — Oracle はライブラリのロードをまったく試みません。Windows 固有ではなく、プラットフォーム横断（Windows と Linux）で確認済みです。Linux でのデプロイに関する注意事項を参照してください。	パッチ 18948524（またはそれ以降）を適用してください。18c 以降では不要です。Oracle XE では不可能です（個別のパッチ適用ができないため）。11g R2 で HSM のパスを使用するには、パッチ適用済みの Enterprise ／ Standard Edition のインストールが必要です。

確認済みの Oracle 側の不具合: kzthsminit_discover_load_pkcs_lib ／ kzthsminit_load_pkcs_lib における ORA-07445。テストしたすべての Windows リリース (19.0.0.0、19.3.0.0.0、21.3.0.0.0、いずれもパッチ未適用の GA メディア) で再現しました。インシデントトレースの全文からは、Oracle 自身のコードが、破損したレジスタ（Rsi／Rbx に明らかに無効で非正規のポインターが入っている）を介した間接呼び出しでクラッシュしていることが分かります。一方で、C_GetFunctionList の 正しい アドレスは同じスタック上の別の場所に見えており、Oracle は正しいシンボルを解決したうえで、誤ったレジスタを介してジャンプしたことを意味します。これは完全に Oracle の呼び出し側コード内部の問題であり、ロードされたライブラリの実装内容とは無関係です。本プロバイダーのライブラリ、サードパーティの OpenSC モジュール、および本物の Securosys Primus バイナリのいずれに対しても同一に再現しており、CRT のリンク方法、実装言語、ベンダーの違いが原因である可能性は排除されています。

この現象は非決定的であり、動作するデプロイを妨げるものではありません。 繰り返しクラッシュしたのとまったく同じ構成が、双方のコードを一切変更しないまま、後には正常に完了しました。これは、特定のライブラリやビルドに結び付く決定的な不具合ではなく、初期化されていないレジスタを読み取るバグのシグネチャです。同じパッチ未適用の 21.3.0.0.0 GA メディア上で、Release Update も My Oracle Support へのアクセスも一切必要とせずに、TDE のエンドツーエンドのデプロイが完全に成功しています。この ORA-07445 のシグネチャに遭遇した場合は再実行してください。利用者側の構成の問題である可能性は非常に低いです。

あわせて確認済み: Azure AD に参加した Windows ホストでは、これとは無関係の Oracle インストーラー の不具合（TDE の問題ではありません）が発生します。従来の OUI と XE の MSI／InstallShield ラッパーは、ローカルグループのメンバーシップを列挙するためにレガシーな Win32 API を呼び出しますが、これはクラウド専用アカウントに対しては、昇格の方法（runas、Start-Process -Credential、schtasks）にかかわらず失敗します。唯一の回避策は、実際に対話型ログオンが可能な、正規のローカル Windows 管理者アカウントを使用することです。これとは別に、DBCA のインスタンス作成／起動ステップは、負荷の高いホストやウイルス対策のスキャン対象となっているホストでは、実際には停止していなくても数分間ハングしているように見えることがあります。強制終了する前に、<ORACLE_BASE>/cfgtoollogs/dbca/<SID>/<SID>.log の DBCA_PROGRESS を確認してください。

過去の問題: Windows における Cryptoki 構造体のパッキング（修正済み）。 Cryptoki のリファレンスヘッダーは、Windows では #pragma pack(1) を、Unix では自然アライメントを要求します。dke-pkcs11 は当初 Unix のレイアウトしか実装しておらず、これは最初のマルチバイトアライメントのフィールド以降のすべての構造体フィールドをずらしてしまう、実在する目に見えない ABI のバグでした。そのため、Windows の呼び出し元が CK_FUNCTION_LIST を読み取ると、関数ポインターが不正な値として見えていました。これはプロバイダー側で修正済みです（現在はすべての構造体がプラットフォームごとに条件付きでパックされます）。影響を受けるのは、この修正より前のビルドのみです。

サポートを受けるには

このトラブルシューティングガイドに従っても問題が解決しない場合は、次のようにしてください。

DuoKey サポートポータルを確認する: https://support.duokey.cloud
プロバイダーのログを提供する: /var/log/dke-pkcs11/ からの関連する抜粋
Oracle のアラートログを提供する: 関連する TDE のエラーメッセージ
構成を記録する: access_guid を 含めずに pkcs11.toml を共有してください（server_url と access_token は伏せ字にしてください）
ライブラリのビルドを確認する: ホストの実際の OS／glibc (ldd --version) と、デプロイした libdke_pkcs11.so を記録してください

次のステップ

運用 → - 運用手順を学ぶ
アーキテクチャドキュメント - システムアーキテクチャを理解する

診断チェックリスト​

よくあるエラーのシナリオ​

ORA-28353: ウォレットのオープンに失敗する​

403 / 無効なアクセストークン​

ORA-00600 [kcbtse_populate_tbskey_1]​

ORA-46664: すべてのコンテナでマスターキーが作成されていない​

ORA-46693 / ORA-28365: ライブラリまたはキーストアが開いていない​

バックグラウンドプロセスでの ORA-28407 の後に発生するインスタンスのクラッシュ (ORA-03113)​

ORA-28374: 指定された型のマスターキーがウォレットに見つからない​

接続性と TLS のトラブルシューティング​

プロバイダーログの分析​

Oracle アラートログの分析​

構成リファレンス​

デバッグに役立つ SQL クエリ​

Linux でのデプロイに関する注意事項​

Windows でのデプロイに関する注意事項​

サポートを受けるには​

次のステップ​

診断チェックリスト

よくあるエラーのシナリオ

ORA-28353: ウォレットのオープンに失敗する

403 / 無効なアクセストークン

ORA-00600 [kcbtse_populate_tbskey_1]

ORA-46664: すべてのコンテナでマスターキーが作成されていない

ORA-46693 / ORA-28365: ライブラリまたはキーストアが開いていない

バックグラウンドプロセスでの ORA-28407 の後に発生するインスタンスのクラッシュ (ORA-03113)

ORA-28374: 指定された型のマスターキーがウォレットに見つからない

接続性と TLS のトラブルシューティング

プロバイダーログの分析

Oracle アラートログの分析

構成リファレンス

デバッグに役立つ SQL クエリ

Linux でのデプロイに関する注意事項

Windows でのデプロイに関する注意事項

サポートを受けるには

次のステップ