Risoluzione dei problemi: cifratura e flag dei permessi

Ambito e confine

Queste voci riguardano gli errori di decifratura sollevati dal motore tramite NextPDF\Exception\EncryptionException e NextPDF\Security\Exception\DecryptionFailedException, e i limiti dei flag dei permessi PDF.

Prima di tutto, una nota sui limiti: previene l’equivoco più comune. I flag dei permessi PDF nel dizionario di cifratura registrano l’intento dell’autore. Non costituiscono un meccanismo di controllo degli accessi imposto da questa libreria. Un lettore che ignora i flag può comunque stampare, copiare o modificare il contenuto. Considerare i flag come una richiesta rivolta a un lettore cooperante, non come un vincolo applicato.

Voce: l’operazione di cifratura non riesce

• Sintomo. EncryptionException con un messaggio nella forma Encryption operation "<op>" failed using algorithm "<algorithm>".
• Causa probabile. L’operazione di cifratura non è stata eseguita correttamente: in genere per un’estensione OpenSSL mancante o mal configurata, materiale di chiave non valido o una dimensione IV non valida al confine del cifrario.
• Evidenza / diagnosi. getContext() restituisce algorithm e operation. Il valore di operation è uno tra encrypt, decrypt o key_derivation, che indica quale fase non è riuscita.
• Risoluzione.
  1. Verificare che l’estensione PHP OpenSSL sia installata e caricata.
  2. Leggere il campo operation per individuare la fase non riuscita.
  3. Per key_derivation, verificare gli input della password o della chiave.
  4. Eseguire di nuovo la chiamata.
• Correlato. Riferimento delle eccezioni.

Voce: la decifratura non riesce per un motivo strutturale

• Sintomo. DecryptionFailedException con un messaggio nella forma Decryption failed for "<algorithm>": <reason>.
• Causa probabile. Il testo cifrato non ha potuto essere elaborato per un motivo non riconducibile a manomissione: per esempio un testo cifrato troncato, un IV mancante o la chiave errata fornita al confine dell’API. Il controllo di integrità non è stato eseguito perché non era disponibile materiale sufficiente da valutare.
• Evidenza / diagnosi. getContext() restituisce algorithm e reason. DecryptionFailedException è documentata nel codice sorgente come distinta da TamperedDataException: questa eccezione indica un errore di configurazione o di trasporto, non una manomissione. Non considerarla di per sé un incidente di sicurezza.
• Risoluzione.
  1. Leggere reason per identificare il difetto strutturale, ad esempio ciphertext shorter than IV+tag.
  2. Verificare che il testo cifrato sia stato trasmesso senza troncamento.
  3. Verificare che la chiave fornita al confine sia la chiave con cui il documento è stato cifrato.
  4. Eseguire di nuovo la chiamata.
• Correlato. Errori di firma e marca temporale.

Voce: viene sollevata un’eccezione di «dati manomessi»

• Sintomo. NextPDF\Security\Exception\TamperedDataException invece di DecryptionFailedException.
• Causa probabile. Il controllo di integrità è stato eseguito ma non superato. È un caso distinto da un errore di decifratura strutturale: era disponibile materiale sufficiente per valutare l’integrità, che però non è risultata valida.
• Evidenza / diagnosi. Il codice sorgente distingue le due classi: DecryptionFailedException è strutturale e non un incidente di sicurezza; TamperedDataException indica che il contenuto autenticato non ha superato la verifica.
• Risoluzione.
  1. Considerare l’input come non attendibile; non utilizzare il contenuto decifrato.
  2. Recuperare di nuovo il documento da una fonte attendibile.
  3. Se l’errore persiste con una fonte di sicura affidabilità, acquisire getContext() per un report dell’incidente.
• Correlato. Errori di firma e marca temporale.

Voce: i flag dei permessi non impediscono un’azione a valle

• Sintomo. Un documento è stato prodotto con i flag dei permessi impostati — ad esempio, copia o stampa non consentite — eppure un lettore copia o stampa comunque il contenuto.
• Causa probabile. Questo è il limite previsto, non un difetto. Il valore intero dei permessi passato al generatore del dizionario di cifratura di Core non viene applicato come vincolo da questa libreria. I flag sono metadati indicativi; un lettore che non li rispetta non viene bloccato da NextPDF.
• Evidenza / diagnosi. src/Security/Encryption/EncryptionDictionaryBuilder.php dichiara buildDict(int $permissions, string $fileId) con il parametro documentato come ignored; retained for forward compatibility. Il metodo inizia con unset($permissions, $fileId). I flag dei permessi esposti da src/Inspect/PdfPermissions.php sono campi di ispezione di sola lettura, non un meccanismo di applicazione.
• Risoluzione.
  1. Non fare affidamento sui flag dei permessi per impedire la stampa, la copia o la modifica. Non possono essere applicati da una libreria che produce il PDF.
  2. Quando l’accesso deve essere limitato, controllare la distribuzione del file stesso oppure usare un sistema di controllo degli accessi esterno al PDF.
  3. Usare PdfPermissions solo per riportare i flag dichiarati da un documento esistente, non per sostenere che tali azioni siano impedite.
• Correlato. Errori di firma e marca temporale.

Voce: la cifratura viene rifiutata in modalità PDF/A

• Sintomo. NextPDF\Security\Exception\IncompatiblePdfAModeException quando una build abilita PDF/A e, allo stesso tempo, richiede la cifratura.
• Causa probabile. Il profilo PDF/A vieta la chiave Encrypt nel trailer. Il motore rifiuta la combinazione in qualunque ordine di chiamata.
• Evidenza / diagnosi. Vedere la voce PDF/A e PDF/UA per la clausola citata, i campi di getContext() e il test del percorso di errore.
• Risoluzione.
  1. Decidere se il documento necessita di conformità per l’archiviazione oppure di cifratura.
  2. Rimuovere la chiamata relativa alla proprietà non necessaria.
  3. Eseguire di nuovo la pipeline.
• Correlato. Validazione PDF/A e PDF/UA.

Casi limite e insidie

• DecryptionFailedException e TamperedDataException indicano condizioni diverse: errore strutturale rispetto a verifica di integrità non superata. Gestire il flusso in base alla classe, non al messaggio.
• Il generatore del dizionario di cifratura di Core ignora il valore intero dei permessi; una build che dipende dall’applicazione dei permessi da parte del pacchetto Core si basa su un equivoco.
• PdfPermissions viene popolato solo per i documenti cifrati alla profondità di ispezione completa e riflette i flag dichiarati. La presenza di un campo valorizzato non significa che l’azione sia impedita.

Vedere anche

• Riferimento delle eccezioni
• Errori di firma e marca temporale
• Validazione PDF/A e PDF/UA
• Indice della knowledge base

Glossario: flag dei permessi · decifratura autenticata