Rozwiązywanie problemów z szyfrowaniem i flagami uprawnień

Zakres i granice

Skorzystaj z tych wpisów, aby usuwać błędy odszyfrowywania zgłaszane przez silnik za pomocą NextPDF\Exception\EncryptionException oraz NextPDF\Security\Exception\DecryptionFailedException, a także aby zrozumieć ograniczenia flag uprawnień formatu Portable Document Format (PDF).

Zacznij od ograniczeń, ponieważ pomaga to uniknąć najczęstszego błędnego przekonania: flagi uprawnień PDF w słowniku szyfrowania zapisują intencję autora. Nie są mechanizmem kontroli dostępu egzekwowanym przez tę bibliotekę. Czytnik, który ignoruje te flagi, nadal może drukować, kopiować lub modyfikować zawartość. Traktuj je jako prośbę kierowaną do współpracującego czytnika, a nie jako wymuszenie.

Wpis: operacja szyfrowania kończy się niepowodzeniem

• Objaw. EncryptionException z komunikatem w postaci Encryption operation "<op>" failed using algorithm "<algorithm>".
• Prawdopodobna przyczyna. Operacji szyfru nie udało się wykonać, zwykle dlatego, że brakuje rozszerzenia OpenSSL albo jest ono błędnie skonfigurowane, materiał klucza jest nieprawidłowy lub na granicy szyfru przekazano nieprawidłowy rozmiar wektora inicjującego (IV).
• Dowody / diagnoza. getContext() zwraca algorithm oraz operation. Wartość operation to encrypt, decrypt albo key_derivation, co pozwala ustalić, który etap zawiódł.
• Rozwiązanie.
  1. Sprawdź, czy rozszerzenie PHP OpenSSL jest zainstalowane i załadowane.
  2. Użyj pola operation, aby zidentyfikować etap, który zawiódł.
  3. W przypadku key_derivation zweryfikuj dane wejściowe hasła lub klucza.
  4. Ponów wywołanie.
• Powiązane. Dokumentacja wyjątków.

Wpis: odszyfrowywanie kończy się niepowodzeniem z przyczyny strukturalnej

• Objaw. DecryptionFailedException z komunikatem w postaci Decryption failed for "<algorithm>": <reason>.
• Prawdopodobna przyczyna. Szyfrogramu nie udało się przetworzyć z przyczyny niezwiązanej z manipulacją, takiej jak obcięty szyfrogram, brakujący IV albo nieprawidłowy klucz przekazany na granicy interfejsu programowania aplikacji (API). Kontrola integralności nie została wykonana, ponieważ nie było wystarczająco dużo materiału do oceny.
• Dowody / diagnoza. getContext() zwraca algorithm oraz reason. Dokumentacja źródłowa odróżnia DecryptionFailedException od TamperedDataException: ten wyjątek oznacza błąd konfiguracji lub transportu, a nie manipulację. Sam w sobie nie powinien być traktowany jako incydent bezpieczeństwa.
• Rozwiązanie.
  1. Odczytaj reason, aby zidentyfikować defekt strukturalny, na przykład ciphertext shorter than IV+tag.
  2. Sprawdź, czy szyfrogram został przesłany bez obcięcia.
  3. Potwierdź, że klucz przekazany na granicy jest tym samym, którego użyto do zaszyfrowania dokumentu.
  4. Ponów wywołanie.
• Powiązane. Błędy podpisu i znacznika czasu.

Wpis: zgłaszany jest wyjątek „tampered data”

• Objaw. Otrzymujesz NextPDF\Security\Exception\TamperedDataException zamiast DecryptionFailedException.
• Prawdopodobna przyczyna. Kontrola integralności została wykonana i zakończyła się niepowodzeniem. Różni się to od strukturalnego błędu odszyfrowywania: dostępna była wystarczająca ilość materiału do oceny integralności, ale integralność nie została zachowana.
• Dowody / diagnoza. Źródło odróżnia te dwie klasy: DecryptionFailedException jest błędem strukturalnym, a nie incydentem bezpieczeństwa; TamperedDataException wskazuje, że uwierzytelniona zawartość nie przeszła weryfikacji.
• Rozwiązanie.
  1. Traktuj dane wejściowe jako niezaufane; nie korzystaj z odszyfrowanej zawartości.
  2. Pobierz dokument ponownie z zaufanego źródła.
  3. Jeśli niepowodzenie utrzymuje się dla źródła o znanej poprawności, przechwyć getContext() do raportu o incydencie.
• Powiązane. Błędy podpisu i znacznika czasu.

Wpis: flagi uprawnień nie zatrzymują działania po stronie odbiorcy

• Objaw. Dokument utworzono z ustawionymi flagami uprawnień — na przykład z zablokowanym kopiowaniem lub drukowaniem — ale czytnik nadal kopiuje lub drukuje zawartość.
• Prawdopodobna przyczyna. To oczekiwane ograniczenie, a nie defekt. Liczba całkowita uprawnień przekazana do narzędzia budującego słownik szyfrowania w pakiecie Core nie jest używana przez tę bibliotekę jako mechanizm wymuszania. Flagi są metadanymi o charakterze doradczym; czytnik, który ich nie respektuje, nie jest blokowany przez NextPDF.
• Dowody / diagnoza. src/Security/Encryption/EncryptionDictionaryBuilder.php deklaruje buildDict(int $permissions, string $fileId) i dokumentuje ten parametr jako ignored; retained for forward compatibility. Metoda zaczyna się od unset($permissions, $fileId). Flagi uprawnień udostępniane przez src/Inspect/PdfPermissions.php są polami inspekcyjnymi tylko do odczytu, a nie warstwą wymuszającą.
• Rozwiązanie.
  1. Nie polegaj na flagach uprawnień, aby powstrzymać drukowanie, kopiowanie lub modyfikację. Biblioteka generująca dokumenty nie może ich wymusić.
  2. Tam, gdzie konieczne jest ograniczenie dostępu, kontroluj dystrybucję samego pliku lub zastosuj system kontroli dostępu poza dokumentem PDF.
  3. Używaj PdfPermissions wyłącznie do raportowania flag deklarowanych przez istniejący dokument, a nie do stwierdzania, że te działania są blokowane.
• Powiązane. Błędy podpisu i znacznika czasu.

Wpis: szyfrowanie jest odrzucane w trybie PDF/A

• Objaw. NextPDF\Security\Exception\IncompatiblePdfAModeException, gdy kompilacja włącza tryb PDF/A i wymaga szyfrowania.
• Prawdopodobna przyczyna. Profil PDF/A zabrania użycia klucza Encrypt w zwiastunie. Silnik odrzuca takie połączenie niezależnie od kolejności wywołań.
• Dowody / diagnoza. Zobacz wpis dotyczący PDF/A i PDF/UA, aby poznać przywołaną klauzulę, pola getContext() oraz test ścieżki błędu.
• Rozwiązanie.
  1. Zdecyduj, czy dokument wymaga zgodności archiwizacyjnej, czy szyfrowania.
  2. Usuń wywołanie dla właściwości, której nie potrzebujesz.
  3. Ponów wykonanie potoku.
• Powiązane. Walidacja PDF/A i PDF/UA.

Przypadki brzegowe i pułapki

• DecryptionFailedException oraz TamperedDataException oznaczają różne rzeczy: błąd strukturalny w przeciwieństwie do nieudanej kontroli integralności. Rozgałęziaj logikę według klasy, a nie według komunikatu.
• Narzędzie budujące słownik szyfrowania w pakiecie Core ignoruje liczbę całkowitą uprawnień; każda kompilacja, która polega na wymuszaniu uprawnień przez pakiet Core, opiera się na błędnym przekonaniu.
• PdfPermissions jest wypełniane wyłącznie dla zaszyfrowanych dokumentów przy pełnej głębokości inspekcji i odzwierciedla zadeklarowane flagi. Wypełnione pole nie oznacza, że dana operacja jest blokowana.

Zobacz też

• Dokumentacja wyjątków
• Błędy podpisu i znacznika czasu
• Walidacja PDF/A i PDF/UA
• Indeks bazy wiedzy

Słownik pojęć: flagi uprawnień · uwierzytelnione odszyfrowywanie