トラブルシューティング：暗号化と権限フラグ

スコープと境界

このページの各エントリでは、エンジンが NextPDF\Exception\EncryptionException および NextPDF\Security\Exception\DecryptionFailedException として発生させる復号失敗と、PDF 権限フラグの境界を扱います。

最も一般的な誤解を避けるため、まず境界を示します。暗号化ディクショナリ内の PDF 権限フラグは、作成者の意図を記録するものです。これらは、このライブラリによって強制されるアクセス制御メカニズムではありません。フラグを無視するリーダーは、引き続きコンテンツの印刷、コピー、変更を行えます。フラグは強制ではなく、協調的なリーダーへの要求として扱ってください。

エントリ: 暗号化操作が失敗する

症状。 EncryptionException が、Encryption operation "<op>" failed using algorithm "<algorithm>" という形式のメッセージで発生します。
考えられる原因。 暗号操作を実行できなかった状態です。通常は、OpenSSL 拡張が存在しないか正しく設定されていない、無効な鍵マテリアル、または暗号境界での無効な IV サイズが原因です。
証拠 / 診断。 getContext() は algorithm と operation を返します。operation の値は encrypt、decrypt、key_derivation のいずれかであり、どの段階が失敗したかを示します。
解決方法。
1. PHP の OpenSSL 拡張がインストールされ、ロードされていることを確認します。
2. 対象の operation フィールドを確認し、失敗している段階を特定します。
3. 値が key_derivation の場合は、パスワードまたは鍵の入力を確認します。
4. 呼び出しを再実行します。
関連項目。 例外リファレンス。

エントリ: 構造的な理由で復号が失敗する

症状。 DecryptionFailedException が、Decryption failed for "<algorithm>": <reason> という形式のメッセージで発生します。
考えられる原因。 暗号文が、改ざん以外の理由で処理できなかった状態です。たとえば、暗号文の切り詰め、IV の欠落、または API 境界で渡された誤った鍵などが原因です。評価に十分なマテリアルがなかったため、整合性チェックは実行されませんでした。
証拠 / 診断。 getContext() は algorithm と reason を返します。DecryptionFailedException は、ソース上で TamperedDataException とは別の例外として文書化されています。この例外は設定エラーまたは転送エラーを示すものであり、改ざんの兆候ではありません。これだけでセキュリティインシデントとして扱わないでください。
解決方法。
1. まず reason を確認し、構造上の欠陥を特定します。たとえば ciphertext shorter than IV+tag などです。
2. 暗号文が切り詰められずに転送されたことを確認します。
3. 境界で渡された鍵が、ドキュメントの暗号化に使用された鍵であることを確認します。
4. 呼び出しを再実行します。
関連項目。 署名とタイムスタンプの失敗。

エントリ: 「改ざんデータ」例外が発生する

症状。 NextPDF\Security\Exception\TamperedDataException が発生します（DecryptionFailedException ではありません）。
考えられる原因。 整合性チェックは実行されましたが、通りませんでした。これは構造的な復号失敗とは区別されます。整合性を評価するのに十分なマテリアルが存在しており、その検証が成立しなかったということです。
証拠 / 診断。 ソースでは 2 つのクラスが対比されています。DecryptionFailedException は構造的なものであり、セキュリティインシデントではありません。TamperedDataException は、認証されたコンテンツの検証が成立しなかったことを示します。
解決方法。
1. 入力を信頼できないものとして扱い、復号されたコンテンツを使用しないでください。
2. 信頼できるソースからドキュメントを再取得します。
3. 既知の正常なソースでも失敗が続く場合は、インシデントレポートのために getContext() を取得します。
関連項目。 署名とタイムスタンプの失敗。

エントリ: 権限フラグが下流のアクションを止めていない

症状。 権限フラグを設定して（たとえば、コピーや印刷を不許可にして）ドキュメントを生成したにもかかわらず、リーダーが引き続きコンテンツをコピーまたは印刷できます。
考えられる原因。 これは想定された境界であり、欠陥ではありません。Core の暗号化ディクショナリビルダーに渡される権限整数は、このライブラリによって強制力のある制御として適用されることはありません。フラグは助言的なメタデータです。これを尊重しないリーダーが NextPDF によってブロックされることはありません。
証拠 / 診断。 src/Security/Encryption/EncryptionDictionaryBuilder.php は buildDict(int $permissions, string $fileId) を宣言しており、そのパラメータは ignored; retained for forward compatibility として文書化されています。このメソッドは unset($permissions, $fileId) で始まります。src/Inspect/PdfPermissions.php によって公開される権限フラグは、読み取り専用の検査フィールドであり、強制レイヤーではありません。
解決方法。
1. 印刷、コピー、変更を止めるために権限フラグに依存しないでください。これらは生成側ライブラリによって強制することはできません。
2. アクセスを制限する必要がある場合は、ファイル自体の配布を制御するか、PDF の外部でアクセス制御システムを適用してください。
3. ツールとして PdfPermissions を使用する場合は、既存のドキュメントが宣言しているフラグを報告する目的にのみ使用し、それらのアクションが防止されると主張するためには使用しないでください。
関連項目。 署名とタイムスタンプの失敗。

エントリ: PDF/A では暗号化が拒否される

症状。 ビルドで PDF/A を有効にし、同時に暗号化を要求すると NextPDF\Security\Exception\IncompatiblePdfAModeException が発生します。
考えられる原因。 PDF/A プロファイルは、トレーラー内の Encrypt キーを禁止しています。エンジンは、呼び出し順序にかかわらずこの組み合わせを拒否します。
証拠 / 診断。 PDF/A と PDF/UA のエントリを参照し、引用された条項、getContext() フィールド、失敗パスのテストを確認してください。
解決方法。
1. ドキュメントにアーカイブ適合性が必要なのか、暗号化が必要なのかを決定します。
2. 不要なプロパティへの呼び出しを削除します。
3. パイプラインを再実行します。
関連項目。 PDF/A と PDF/UA の検証。

エッジケースと注意点

DecryptionFailedException と TamperedDataException は異なる意味を持ちます。構造的な失敗なのか、整合性の失敗なのかが異なります。メッセージではなく、クラスで分岐してください。
Core の暗号化ディクショナリビルダーは権限整数を無視します。core パッケージによる権限の強制に依存するビルドは、誤解に基づいています。
PdfPermissions は、完全な検査深度において暗号化されたドキュメントに対してのみ設定され、宣言されたフラグを反映します。フィールドが設定されていても、そのアクションが防止されることを意味するわけではありません。