Solução de problemas: criptografia e flags de permissão

Escopo e limite

Use estas entradas para solucionar as falhas de descriptografia que o mecanismo sinaliza por meio de NextPDF\Exception\EncryptionException e NextPDF\Security\Exception\DecryptionFailedException, e para entender o limite das flags de permissão do Portable Document Format (PDF).

Comece por esse limite, pois ele evita o equívoco mais comum: as flags de permissão do PDF no dicionário de criptografia registram a intenção do autor. Elas não são um mecanismo de controle de acesso imposto por esta biblioteca. Um leitor que ignora as flags ainda pode imprimir, copiar ou modificar o conteúdo. Trate as flags como uma solicitação a um leitor cooperativo, não como uma imposição.

Entrada: a operação de criptografia falha

• Sintoma. EncryptionException com uma mensagem no formato Encryption operation "<op>" failed using algorithm "<algorithm>".
• Causa provável. A operação de cifra não pôde ser executada, normalmente porque a extensão OpenSSL está ausente ou mal configurada, o material da chave é inválido ou o tamanho do vetor de inicialização (IV) é inválido para a cifra.
• Evidência / diagnóstico. getContext() retorna algorithm e operation. O valor de operation é um de encrypt, decrypt ou key_derivation, para que você possa identificar qual estágio falhou.
• Resolução.
  1. Confirme se a extensão PHP OpenSSL está instalada e carregada.
  2. Use o campo operation para localizar o estágio que está falhando.
  3. Para key_derivation, verifique as entradas de senha ou de chave.
  4. Repita a chamada.
• Relacionado. Referência de exceções.

Entrada: a descriptografia falha por um motivo estrutural

• Sintoma. DecryptionFailedException com uma mensagem no formato Decryption failed for "<algorithm>": <reason>.
• Causa provável. O texto cifrado não pôde ser processado por um motivo não relacionado à adulteração, como texto cifrado truncado, IV ausente ou a chave errada fornecida no limite da API. A verificação de integridade não foi executada porque não havia material suficiente para avaliação.
• Evidência / diagnóstico. getContext() retorna algorithm e reason. A documentação original distingue DecryptionFailedException de TamperedDataException: esta exceção significa erro de configuração ou de transporte, não adulteração. Não a trate como um incidente de segurança por si só.
• Resolução.
  1. Leia reason para identificar o defeito estrutural, por exemplo ciphertext shorter than IV+tag.
  2. Verifique se o texto cifrado foi transportado sem truncamento.
  3. Confirme que a chave fornecida no limite é a mesma usada para criptografar o documento.
  4. Repita a chamada.
• Relacionado. Falhas de assinatura e carimbo de tempo.

Entrada: uma exceção de “dados adulterados” é lançada

• Sintoma. Você recebe NextPDF\Security\Exception\TamperedDataException em vez de DecryptionFailedException.
• Causa provável. A verificação de integridade foi executada e falhou. Isso é diferente de uma falha estrutural de descriptografia: havia material suficiente para avaliar a integridade, mas ela não se manteve.
• Evidência / diagnóstico. A origem distingue as duas classes: DecryptionFailedException é estrutural e não um incidente de segurança; TamperedDataException indica que o conteúdo autenticado não passou na verificação.
• Resolução.
  1. Trate a entrada como não confiável; não consuma o conteúdo descriptografado.
  2. Obtenha o documento novamente de uma fonte confiável.
  3. Se a falha persistir com uma fonte sabidamente íntegra, capture getContext() para um relatório de incidente.
• Relacionado. Falhas de assinatura e carimbo de tempo.

Entrada: as flags de permissão não estão impedindo uma ação posterior

• Sintoma. Um documento foi produzido com flags de permissão definidas — por exemplo, cópia ou impressão não permitidas — mas um leitor ainda consegue copiar ou imprimir o conteúdo.
• Causa provável. Esse é o limite esperado, não um defeito. O inteiro de permissão passado ao construtor de dicionário de criptografia do core não é imposto por esta biblioteca. As flags são metadados consultivos; um leitor que não as respeita não é bloqueado pelo NextPDF.
• Evidência / diagnóstico. src/Security/Encryption/EncryptionDictionaryBuilder.php declara buildDict(int $permissions, string $fileId) e documenta o parâmetro como ignored; retained for forward compatibility. O método começa com unset($permissions, $fileId). As flags de permissão expostas por src/Inspect/PdfPermissions.php são campos de inspeção somente leitura, não uma camada de imposição.
• Resolução.
  1. Não dependa das flags de permissão para impedir impressão, cópia ou modificação. Elas não podem ser impostas por uma biblioteca produtora.
  2. Quando for necessário restringir o acesso, controle a distribuição do próprio arquivo ou aplique um sistema de controle de acesso fora do PDF.
  3. Use PdfPermissions apenas para relatar as flags que um documento existente declara, não para afirmar que essas ações foram impedidas.
• Relacionado. Falhas de assinatura e carimbo de tempo.

Entrada: a criptografia é recusada sob PDF/A

• Sintoma. NextPDF\Security\Exception\IncompatiblePdfAModeException quando um build habilita PDF/A e solicita criptografia.
• Causa provável. O perfil PDF/A proíbe a chave Encrypt no trailer. O mecanismo recusa a combinação em qualquer ordem das chamadas.
• Evidência / diagnóstico. Consulte a entrada de PDF/A e PDF/UA para a cláusula citada, os campos de getContext() e o teste de caminho de falha.
• Resolução.
  1. Decida se o documento precisa de conformidade de arquivamento ou de criptografia.
  2. Remova a chamada da propriedade de que você não precisa.
  3. Execute o pipeline novamente.
• Relacionado. Validação de PDF/A e PDF/UA.

Casos extremos e armadilhas

• DecryptionFailedException e TamperedDataException significam coisas diferentes: falha estrutural versus falha de integridade. Faça a ramificação pela classe, não pela mensagem.
• O construtor de dicionário de criptografia do core ignora o inteiro de permissão; qualquer build que dependa da imposição de permissões pelo pacote core está baseado em um equívoco.
• PdfPermissions é preenchido somente para documentos criptografados na profundidade total de inspeção e reflete as flags declaradas. Um campo preenchido não significa que a ação foi impedida.

Veja também

• Referência de exceções
• Falhas de assinatura e carimbo de tempo
• Validação de PDF/A e PDF/UA
• Índice da base de conhecimento

Glossário: flags de permissão · descriptografia autenticada