Устранение неполадок: шифрование и флаги разрешений

Область применения и границы

Эти разделы помогут устранить сбои расшифровки, о которых движок сообщает через NextPDF\Exception\EncryptionException и NextPDF\Security\Exception\DecryptionFailedException, а также понять границы флагов разрешений в Portable Document Format (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.
• Вероятная причина. Проверка целостности была выполнена и не прошла. В отличие от структурного сбоя расшифровки, материала хватило для оценки целостности, и целостность не подтвердилась.
• Признаки и диагностика. Исходный код различает два класса: DecryptionFailedException является структурным сбоем и не относится к инцидентам безопасности; TamperedDataException указывает, что аутентифицированное содержимое не прошло проверку.
• Решение.
  1. Рассматривайте входные данные как недоверенные; не используйте расшифрованное содержимое.
  2. Повторно получите документ из доверенного источника.
  3. Если сбой сохраняется при заведомо исправном источнике, сохраните getContext() для отчёта об инциденте.
• См. также. Сбои подписи и метки времени.

Раздел: флаги разрешений не блокируют последующие действия

• Симптом. Документ создан с установленными флагами разрешений — например, с запретом копирования или печати, — но программа просмотра всё равно копирует или печатает содержимое.
• Вероятная причина. Это ожидаемая граница, а не дефект. Целое число разрешений, передаваемое в построитель словаря шифрования ядра, библиотека не применяет как принудительное ограничение. Флаги являются рекомендательными метаданными; программа просмотра, которая их не учитывает, не блокируется NextPDF.
• Признаки и диагностика. src/Security/Encryption/EncryptionDictionaryBuilder.php объявляет buildDict(int $permissions, string $fileId) и описывает этот параметр как ignored; retained for forward compatibility. Метод начинается с unset($permissions, $fileId). Флаги разрешений, отображаемые через src/Inspect/PdfPermissions.php, являются данными проверки только для чтения, а не уровнем принудительного применения.
• Решение.
  1. Не полагайтесь на флаги разрешений, чтобы остановить печать, копирование или изменение. Библиотека, которая создаёт PDF, не может применить их принудительно.
  2. Там, где необходимо ограничить доступ, контролируйте распространение самого файла или применяйте систему контроля доступа за пределами PDF.
  3. Используйте PdfPermissions только для вывода флагов, которые объявляет существующий документ, а не для утверждения, что эти действия предотвращаются.
• См. также. Сбои подписи и метки времени.

Раздел: шифрование отклоняется в режиме PDF/A

• Симптом. NextPDF\Security\Exception\IncompatiblePdfAModeException, когда сборка включает PDF/A и запрашивает шифрование.
• Вероятная причина. Профиль PDF/A запрещает ключ Encrypt в трейлере. Движок отклоняет эту комбинацию при любом порядке вызовов.
• Признаки и диагностика. Цитируемый пункт, поля getContext() и тест пути сбоя описаны в разделе о PDF/A и PDF/UA.
• Решение.
  1. Решите, что нужно документу: соответствие требованиям архивирования или шифрование.
  2. Удалите вызов для свойства, которое вам не нужно.
  3. Запустите конвейер заново.
• См. также. Проверка PDF/A и PDF/UA.

Граничные случаи и подводные камни

• DecryptionFailedException и TamperedDataException означают разные вещи: структурный сбой и непройденную проверку целостности. Выбирайте ветку логики по классу, а не по сообщению.
• Построитель словаря шифрования ядра игнорирует целое число разрешений; любая сборка, которая зависит от принудительного применения разрешений пакетом ядра, исходит из неверного предположения.
• PdfPermissions заполняется только для зашифрованных документов при полной глубине проверки и отражает объявленные флаги. Если поле заполнено, это не означает, что действие предотвращено.

См. также

• Справочник по исключениям
• Сбои подписи и метки времени
• Проверка PDF/A и PDF/UA
• Указатель базы знаний

Глоссарий: флаги разрешений · аутентифицированная расшифровка