Dépannage : chiffrement et indicateurs de permissions

Périmètre et limite

Ces entrées couvrent les échecs de déchiffrement signalés par le moteur via NextPDF\Exception\EncryptionException et NextPDF\Security\Exception\DecryptionFailedException, ainsi que la limite propre aux indicateurs de permissions PDF.

D’abord, un rappel de limite s’impose, car il évite le malentendu le plus courant : les indicateurs de permissions de la table de chiffrement expriment l’intention d’un auteur. Ce n’est pas un mécanisme de contrôle d’accès appliqué par cette bibliothèque. Un lecteur qui ignore ces indicateurs peut tout de même imprimer, copier ou modifier le contenu. Considère ces indicateurs comme une demande adressée à un lecteur coopératif, pas comme un dispositif contraignant.

Entrée : une opération de chiffrement échoue

• Symptôme. EncryptionException avec un message de la forme Encryption operation "<op>" failed using algorithm "<algorithm>".
• Cause probable. L’opération de chiffrement n’a pas pu s’exécuter : typiquement, une extension OpenSSL absente ou mal configurée, un matériel de clé invalide, ou une taille d’IV invalide à la frontière du chiffrement.
• Preuves / diagnostic. getContext() renvoie algorithm et operation. La valeur operation vaut encrypt, decrypt ou key_derivation, ce qui t’indique l’étape qui a échoué.
• Résolution.
  1. Vérifie que l’extension PHP OpenSSL est installée et chargée.
  2. Lis le champ operation pour localiser l’étape qui échoue.
  3. Pour key_derivation, vérifie le mot de passe ou les entrées de clé.
  4. Relance l’appel.
• Connexe. Référence des exceptions.

Entrée : le déchiffrement échoue pour une raison structurelle

• Symptôme. DecryptionFailedException avec un message de la forme Decryption failed for "<algorithm>": <reason>.
• Cause probable. Le texte chiffré n’a pas pu être traité pour une raison qui ne relève pas d’une altération : par exemple, un texte chiffré tronqué, un IV manquant, ou la mauvaise clé fournie à la frontière de l’API. Le contrôle d’intégrité ne s’est pas exécuté faute de données suffisantes à évaluer.
• Preuves / diagnostic. getContext() renvoie algorithm et reason. DecryptionFailedException est documentée dans le code source comme distincte de TamperedDataException : cette exception signale une erreur de configuration ou de transport, pas une altération. Ne la traite pas, à elle seule, comme un incident de sécurité.
• Résolution.
  1. Lis reason pour identifier le défaut structurel, par exemple ciphertext shorter than IV+tag.
  2. Vérifie que le texte chiffré a été transporté sans troncature.
  3. Confirme que la clé fournie à la frontière est bien celle avec laquelle le document a été chiffré.
  4. Relance l’appel.
• Connexe. Échecs de signature et d’horodatage.

Entrée : une exception « données altérées » est levée

• Symptôme. NextPDF\Security\Exception\TamperedDataException plutôt que DecryptionFailedException.
• Cause probable. Le contrôle d’intégrité s’est exécuté et a échoué. C’est distinct d’un échec de déchiffrement structurel : il y avait suffisamment de données pour évaluer l’intégrité, et la vérification a échoué.
• Preuves / diagnostic. Le code source distingue les deux classes : DecryptionFailedException est structurelle et n’est pas un incident de sécurité ; TamperedDataException indique que le contenu authentifié n’a pas été validé.
• Résolution.
  1. Traite l’entrée comme non fiable ; ne consomme pas le contenu déchiffré.
  2. Récupère à nouveau le document depuis une source de confiance.
  3. Si l’échec persiste avec une source connue comme saine, capture getContext() pour un rapport d’incident.
• Connexe. Échecs de signature et d’horodatage.

Entrée : les indicateurs de permissions ne bloquent pas une action en aval

• Symptôme. Un document a été produit avec des indicateurs de permissions définis, par exemple copie ou impression interdite, mais un lecteur copie ou imprime quand même le contenu.
• Cause probable. C’est la limite attendue, pas un défaut. L’entier de permissions passé au constructeur de la table de chiffrement du core n’est pas utilisé par cette bibliothèque comme mécanisme d’application. Ces indicateurs sont des métadonnées indicatives ; un lecteur qui ne les respecte pas n’est pas bloqué par NextPDF.
• Preuves / diagnostic. src/Security/Encryption/EncryptionDictionaryBuilder.php déclare buildDict(int $permissions, string $fileId) avec le paramètre documenté comme ignored; retained for forward compatibility. La méthode commence par unset($permissions, $fileId). Les indicateurs de permissions exposés par src/Inspect/PdfPermissions.php sont des champs d’inspection en lecture seule, pas une couche d’application des permissions.
• Résolution.
  1. Ne te repose pas sur les indicateurs de permissions pour empêcher l’impression, la copie ou la modification. Ils ne peuvent pas être appliqués par une bibliothèque de production.
  2. Lorsque l’accès doit être restreint, contrôle la distribution du fichier lui-même ou applique un système de contrôle d’accès en dehors du PDF.
  3. Utilise PdfPermissions uniquement pour signaler les indicateurs déclarés par un document existant, pas pour affirmer que ces actions sont empêchées.
• Connexe. Échecs de signature et d’horodatage.

Entrée : le chiffrement est refusé sous PDF/A

• Symptôme. NextPDF\Security\Exception\IncompatiblePdfAModeException lorsqu’une build active à la fois PDF/A et demande le chiffrement.
• Cause probable. Le profil PDF/A interdit la clé Encrypt dans le trailer. Le moteur refuse cette combinaison quel que soit l’ordre des appels.
• Preuves / diagnostic. Consulte l’entrée PDF/A et PDF/UA pour la clause citée, les champs de getContext() et le test du chemin d’échec.
• Résolution.
  1. Décide si le document a besoin de la conformité d’archivage ou du chiffrement.
  2. Supprime l’appel correspondant à la propriété dont tu n’as pas besoin.
  3. Relance le pipeline.
• Connexe. Validation PDF/A et PDF/UA.

Cas limites et pièges

• DecryptionFailedException et TamperedDataException ne signifient pas la même chose : échec structurel d’un côté, échec d’intégrité de l’autre. Branche sur la classe, pas sur le message.
• Le constructeur de la table de chiffrement du core ignore l’entier de permissions ; une build qui dépend de l’application des permissions par le package core repose sur une hypothèse erronée.
• PdfPermissions n’est renseigné que pour les documents chiffrés à la profondeur d’inspection complète et reflète les indicateurs déclarés. Un champ renseigné ne signifie pas que l’action est empêchée.

Voir aussi

• Référence des exceptions
• Échecs de signature et d’horodatage
• Validation PDF/A et PDF/UA
• Index de la base de connaissances

Glossaire : indicateurs de permissions · déchiffrement authentifié