Fehlerbehebung: Verschlüsselung und Berechtigungs-Flags

Geltungsbereich und Grenzen

Diese Einträge behandeln Entschlüsselungsfehler, die die Engine über NextPDF\Exception\EncryptionException und NextPDF\Security\Exception\DecryptionFailedException auslöst, sowie die Grenzen von PDF-Berechtigungs-Flags.

Zunächst eine Abgrenzung, weil sie das häufigste Missverständnis ausräumt: PDF-Berechtigungs-Flags im Verschlüsselungs-Dictionary halten die Absicht des Autors fest. Sie sind kein Zugriffskontrollmechanismus, den diese Bibliothek durchsetzt. Ein Reader, der die Flags ignoriert, kann den Inhalt trotzdem drucken, kopieren oder verändern. Verstehen Sie die Flags als Bitte an einen kooperierenden Reader, nicht als Durchsetzung.

Eintrag: Verschlüsselungsvorgang schlägt fehl

• Symptom. EncryptionException mit einer Meldung der Form Encryption operation "<op>" failed using algorithm "<algorithm>".
• Wahrscheinliche Ursache. Der Verschlüsselungsvorgang konnte nicht ausgeführt werden — typischerweise wegen einer fehlenden oder falsch konfigurierten OpenSSL-Erweiterung, ungültigen Schlüsselmaterials oder einer ungültigen IV-Größe an der Verschlüsselungsgrenze.
• Belege / Diagnose. getContext() liefert algorithm und operation. Der Wert von operation ist einer von encrypt, decrypt oder key_derivation und gibt an, welche Stufe fehlgeschlagen ist.
• Lösung.
  1. Stellen Sie sicher, dass die OpenSSL-PHP-Erweiterung installiert und geladen ist.
  2. Lesen Sie das Feld operation, um die fehlschlagende Stufe zu ermitteln.
  3. Prüfen Sie bei key_derivation die Passwort- oder Schlüsseleingaben.
  4. Führen Sie den Aufruf erneut aus.
• Verwandt. Exception-Referenz.

Eintrag: Entschlüsselung schlägt aus einem strukturellen Grund fehl

• Symptom. DecryptionFailedException mit einer Meldung der Form Decryption failed for "<algorithm>": <reason>.
• Wahrscheinliche Ursache. Der Chiffretext konnte aus einem Grund verarbeitet werden, der nicht auf Manipulation zurückgeht — zum Beispiel wegen eines abgeschnittenen Chiffretexts, eines fehlenden IV oder eines falschen Schlüssels, der an der API-Grenze übergeben wurde. Die Integritätsprüfung wurde nicht ausgeführt, weil nicht genügend Material für die Auswertung vorhanden war.
• Belege / Diagnose. getContext() liefert algorithm und reason. DecryptionFailedException wird in der Quelle als von TamperedDataException unterschieden dokumentiert: Diese Exception ist ein Konfigurations- oder Transportfehler, kein Hinweis auf Manipulation. Behandeln Sie sie für sich genommen nicht als Sicherheitsvorfall.
• Lösung.
  1. Lesen Sie reason, um den strukturellen Defekt zu erkennen, zum Beispiel ciphertext shorter than IV+tag.
  2. Prüfen Sie, dass der Chiffretext nicht abgeschnitten übertragen wurde.
  3. Stellen Sie sicher, dass der an der Grenze übergebene Schlüssel dem Schlüssel entspricht, mit dem das Dokument verschlüsselt wurde.
  4. Führen Sie den Aufruf erneut aus.
• Verwandt. Signatur- und Zeitstempel-Fehler.

Eintrag: Eine Exception wegen „manipulierter Daten“ wird ausgelöst

• Symptom. NextPDF\Security\Exception\TamperedDataException statt DecryptionFailedException.
• Wahrscheinliche Ursache. Die Integritätsprüfung wurde ausgeführt und ist fehlgeschlagen. Das unterscheidet sich von einem strukturellen Entschlüsselungsfehler: Es war genügend Material vorhanden, um die Integrität auszuwerten, und die Prüfung bestand nicht.
• Belege / Diagnose. Die Quelle stellt die beiden Klassen einander gegenüber: DecryptionFailedException ist strukturell und kein Sicherheitsvorfall; TamperedDataException zeigt an, dass der authentifizierte Inhalt nicht verifiziert wurde.
• Lösung.
  1. Behandeln Sie die Eingabe als nicht vertrauenswürdig; verwenden Sie den entschlüsselten Inhalt nicht.
  2. Beziehen Sie das Dokument erneut aus einer vertrauenswürdigen Quelle.
  3. Falls der Fehler bei einer als zuverlässig bekannten Quelle bestehen bleibt, erfassen Sie getContext() für einen Incident-Report.
• Verwandt. Signatur- und Zeitstempel-Fehler.

Eintrag: Berechtigungs-Flags stoppen eine nachgelagerte Aktion nicht

• Symptom. Ein Dokument wurde mit gesetzten Berechtigungs-Flags erzeugt — zum Beispiel mit untersagtem Kopieren oder Drucken — und dennoch kopiert oder druckt ein Reader den Inhalt weiterhin.
• Wahrscheinliche Ursache. Das ist die erwartete Grenze, kein Defekt. Die an den Core-Builder des Verschlüsselungs-Dictionarys übergebene Berechtigungs-Ganzzahl wird von dieser Bibliothek nicht zur Durchsetzung verwendet. Die Flags sind beratende Metadaten; ein Reader, der sie nicht beachtet, wird von NextPDF nicht blockiert.
• Belege / Diagnose. src/Security/Encryption/EncryptionDictionaryBuilder.php deklariert buildDict(int $permissions, string $fileId), wobei der Parameter als ignored; retained for forward compatibility dokumentiert ist. Die Methode beginnt mit unset($permissions, $fileId). Die von src/Inspect/PdfPermissions.php bereitgestellten Berechtigungs-Flags sind schreibgeschützte Inspektionsfelder, keine Durchsetzungsschicht.
• Lösung.
  1. Verlassen Sie sich nicht darauf, dass Berechtigungs-Flags Drucken, Kopieren oder Verändern verhindern. Sie können von einer Erzeuger-Bibliothek nicht durchgesetzt werden.
  2. Wenn Zugriff beschränkt werden muss, steuern Sie die Verteilung der Datei selbst oder setzen Sie ein Zugriffskontrollsystem außerhalb des PDF ein.
  3. Verwenden Sie PdfPermissions nur, um die Flags zu melden, die ein vorhandenes Dokument deklariert, nicht um zu behaupten, dass diese Aktionen verhindert werden.
• Verwandt. Signatur- und Zeitstempel-Fehler.

Eintrag: Verschlüsselung wird unter PDF/A abgelehnt

• Symptom. NextPDF\Security\Exception\IncompatiblePdfAModeException, wenn ein Build sowohl PDF/A aktiviert als auch Verschlüsselung anfordert.
• Wahrscheinliche Ursache. Das PDF/A-Profil verbietet den Schlüssel Encrypt im Trailer. Die Engine lehnt die Kombination in jeder Aufrufreihenfolge ab.
• Belege / Diagnose. Siehe den Eintrag zu PDF/A und PDF/UA für die zitierte Klausel, die Felder von getContext() und den Failure-Path-Test.
• Lösung.
  1. Entscheiden Sie, ob das Dokument Archivkonformität oder Verschlüsselung benötigt.
  2. Entfernen Sie den Aufruf für die Eigenschaft, die Sie nicht benötigen.
  3. Führen Sie die Pipeline erneut aus.
• Verwandt. PDF/A- und PDF/UA-Validierung.

Sonderfälle & Fallstricke

• DecryptionFailedException und TamperedDataException bedeuten Unterschiedliches: struktureller Fehler gegenüber fehlgeschlagener Integrität. Verzweigen Sie anhand der Klasse, nicht anhand der Meldung.
• Der Core-Builder des Verschlüsselungs-Dictionarys ignoriert die Berechtigungs-Ganzzahl; ein Build, der auf Berechtigungsdurchsetzung durch das Core-Paket setzt, beruht auf einem Missverständnis.
• PdfPermissions wird nur für verschlüsselte Dokumente bei voller Inspektionstiefe befüllt und spiegelt die deklarierten Flags wider. Ein befülltes Feld bedeutet nicht, dass die Aktion verhindert wird.

Siehe auch

• Exception-Referenz
• Signatur- und Zeitstempel-Fehler
• PDF/A- und PDF/UA-Validierung
• Wissensdatenbank-Index

Glossar: Berechtigungs-Flags · authentifizierte Entschlüsselung