Erreurs de sécurité et de signature

En bref

Cette page documente les exceptions du domaine de la sécurité dans l’arbre d’espaces de noms NextPDF\Security. Chaque entrée nomme la classe, indique quand elle est levée, liste les champs que renvoie son getContext() et donne une étape de rétablissement.

La plupart de ces classes étendent SecurityException, qui étend NextPdfException et implémente ContextAwareExceptionInterface. Cela signifie que getContext(): array renvoie des diagnostics structurés et sans secret que tu peux router vers la journalisation ou les pipelines de surveillance des performances des applications (APM). Attrape SecurityException pour piéger toute défaillance du domaine de la sécurité en un seul bloc ; attrape une sous-classe spécifique lorsque tu as besoin de sa charge utile typée.

Quelques classes de cet arbre étendent directement RuntimeException plutôt que SecurityException. Elles sont marquées ci-dessous ; elles n’exposent pas getContext(), et la plupart sont documentées comme des signaux internes de flux de contrôle que tu ne devrais pas t’attendre à attraper dans du code applicatif.

Convention de champs de contexte

Aspect	Comportement
Contrat de base	NextPdfException::getContext() renvoie [] ; les sous-classes le redéfinissent.
Hygiène des secrets	Les messages et le contexte omettent le matériel de clé brut, le texte en clair, les codes PIN et les octets du vecteur d’initialisation (IV). Les clés ne sont exposées que sous la forme d’un préfixe d’empreinte.
SecurityException	Base abstraite ; ne porte aucun champ propre. Les sous-classes définissent la charge utile.

Type de base

SecurityException

• Quand elle est levée. Jamais levée directement ; c’est la base abstraite du domaine de la sécurité. Elle existe pour qu’un seul bloc catch (SecurityException $e) puisse piéger les échecs d’intégrité de chiffrement authentifié, les défenses contre la réutilisation de nonce, la liaison PDF/A-contre-chiffrement, les fautes de gestion de clés et les échecs de PKI.
• Champs de contexte. Aucun propre. Hérite de la valeur par défaut vide de NextPdfException ; les sous-classes peuplent la charge utile.
• Rétablissement. Attrape la sous-classe concrète pour un traitement actionnable, ou SecurityException pour un routage grossier des incidents de sécurité.

Erreurs de chiffrement et de chiffrement authentifié

Celles-ci sont levées par le chiffreur AES-GCM (Galois/Counter Mode) et la garde PDF/A. Pour des conseils axés sur le symptôme, voir Chiffrement et permissions.

DecryptionFailedException

• Quand elle est levée. Un déchiffrement de chiffrement authentifié avec données associées (AEAD) échoue pour une raison non liée à une altération : texte chiffré tronqué, IV manquant, ou clé erronée fournie à la frontière de l’API, là où il n’y avait pas assez de matériel pour que la vérification d’intégrité s’exécute réellement. C’est une erreur de configuration ou de transport, pas un incident de sécurité.
• Champs de contexte. algorithm (par exemple AES-256-GCM), reason (par exemple ciphertext shorter than IV+tag).
• Rétablissement. Vérifie que le texte chiffré, l’IV et la clé sont complets et correctement encadrés ; ne traite pas cela comme une altération. À mettre en contraste avec TamperedDataException.

TamperedDataException

• Quand elle est levée. Le tag d’authentification AEAD échoue à la vérification. Le tag couvre le texte chiffré plus les données authentifiées associées (AAD) ; si l’un ou l’autre a été modifié après le chiffrement, le openssl_decrypt() sous-jacent renvoie false. Ce sous-type distinct te permet de faire remonter une alerte de niveau incident de sécurité plutôt qu’une erreur d’encadrement.
• Champs de contexte. algorithm, ciphertext_length (longueur du texte chiffré rejeté, hors IV et tag).
• Rétablissement. Traite cela comme une altération ou une clé/IV erronée. Ne réessaie pas aveuglément ; enquête sur la source du texte chiffré. Selon ISO/TS 32003:2023 §5.2 et NIST SP 800-38D §6.5, un échec de la vérification du tag signifie que les données ne sont pas authentiques.

NonceReuseException

• Quand elle est levée. AES-GCM est invité à chiffrer deux fois avec la même paire clé/IV. Le chiffreur se défend avec un compteur monotone par instance et, comme défense en profondeur, un ensemble de hachages à l’exécution de chaque paire (empreinte de clé, IV) émise. Parce que le compteur exclut les collisions par construction, ce déclenchement est un indicateur de bug de priorité critique qui ne doit jamais se produire en production. Réutiliser une paire clé/IV compromet l’ensemble du keystream (ISO/TS 32003:2023 §5.2 NOTE 2 ; NIST SP 800-38D §8.3).
• Champs de contexte. key_fingerprint_prefix (les 8 premiers caractères hexadécimaux de SHA-256(clé)), iv_length (toujours 12 pour ISO/TS 32003), reason (hashset-collision ou counter-rollover, distinguant un bug de refactoring qui déjoue le compteur du déclencheur du compteur à 2^63) et iv_fixed_field_hex (le champ fixe de l’IV, présent uniquement lorsqu’il est fourni, signalé sous sa propre clé et jamais étiqueté à tort comme l’empreinte de la clé).
• Rétablissement. Abandonne immédiatement et fais tourner la clé. Ouvre un rapport de défaut ; cela indique un bug dans le chiffreur, pas une mauvaise entrée de l’appelant.

GcmInvocationLimitExceededException

• Quand elle est levée. Un nombre d’invocations de sûreté d’usage NIST SP 800-38D §8.3, activable, est atteint pour une clé AES-GCM donnée. C’est un point d’ancrage de télémétrie de défense en profondeur pour les appelants qui veulent appliquer la borne recommandée par la spécification (autour de 2^32 invocations par clé) plus tôt que les limites architecturales internes au chiffreur. Il ne se déclenche pas par défaut ; seul l’assistant assertWithinSafetyBound() le lève.
• Champs de contexte. key_fingerprint_prefix, invocation_count (le nombre actuel d’encrypt(), à la limite ou au-delà), invocation_limit (la borne activée).
• Rétablissement. Fais tourner la clé du document (construis un nouveau chiffreur avec un nouveau matériel de clé) avant que la probabilité cumulée de collision et de falsification ne cesse d’être négligeable, ou élargis la politique de l’appelant pour refuser de continuer le service.

IncompatiblePdfAModeException

• Quand elle est levée. Une opération de chiffrement est tentée sur un document balisé PDF/A. La famille PDF/A (PDF/A-2, PDF/A-3, PDF/A-4) interdit uniformément le chiffrement : selon ISO 19005 §6.1.3, la clé Encrypt ne doit pas être présente dans le trailer, et ISO 19005-4:2020 Annexes A et B en héritent sans modification. Il n’existe aucune combinaison permise de PDF/A et de chiffrement.
• Champs de contexte. pdfa_mode (par exemple pdfa4, pdfa3), encryption_operation (l’appel rejeté, par exemple useAesGcm).
• Rétablissement. Pour produire un document chiffré, omets l’appel enablePdfA() ; pour produire un document d’archivage, omets l’appel de chiffrement. Voir Validation PDF/A et PDF/UA.

Application de la politique cryptographique

CryptoPolicyViolationException

• Quand elle est levée. Une politique cryptographique configurée rejette un algorithme, une force de clé ou un chiffre sélectionné par une opération du cœur de signature, de chiffrement ou de hachage. C’est la frontière en mode fermé pour l’application de la conformité (par exemple FIPS 140-2/3, eIDAS, ou une politique d’entreprise personnalisée) et elle est levée par CryptoPolicyEnforcer avant qu’une signature ou un texte chiffré ne soit produit, afin qu’une opération violant la politique ne puisse jamais émettre un artefact non approuvé. Distincte d’un échec d’opération OpenSSL étroit et d’un échec de primitive de signature : c’est un rejet de politique d’une requête par ailleurs valide. Alignée sur NIST SP 800-131A Rev. 2 et ISO/IEC 19790:2025 §7.
• Champs de contexte. policy (nom de la politique, par exemple FIPS 140-3 Strict), category (hash, signature, encryption ou key-strength), item (l’élément rejeté, par exemple un identifiant d’objet (OID), un nom de chiffre, ou rsa/1024), reason.
• Rétablissement. Sélectionne un algorithme, une longueur de clé ou un chiffre que la politique nommée approuve, ou ajuste la politique si tu en es propriétaire. Route le contexte structuré vers le runbook de conformité documenté.

Gestion des clés

Il existe deux classes du même nom. Elles partagent la racine SecurityException afin qu’un seul bloc catch (SecurityException $e) les piège toutes deux, mais elles portent des charges utiles distinctes. Importe par le nom pleinement qualifié lorsque tu as besoin d’une forme spécifique.

KeyManagementException (cycle de vie : NextPDF\Security\Exception)

• Quand elle est levée. Une opération de gestion de clés échoue avant que la clé ne soit consommée par une primitive de signature ou de chiffrement : échecs d’analyse de clé Privacy-Enhanced Mail (PEM), PKCS#12 ou PKCS#11 ; échecs de dérivation de clé (HKDF, PBKDF2, scrypt) ; rejet d’AES Key Wrap (RFC 3394) sur une clé de chiffrement de clé erronée ; un module de sécurité matériel (HSM) renvoyant des Distinguished Encoding Rules (DER) malformées ; ou une incohérence de longueur de graine Ed25519.
• Champs de contexte. operation (par exemple load_pem, kek_derive, key_wrap), key_type (par exemple RSA, EC-P256, Ed25519, AES-256), reason. Le matériel de clé brut n’est jamais inclus.
• Rétablissement. Inspecte l’opération et le type de clé nommés, corrige le matériel de clé source ou l’entrée de dérivation, et réessaie.

KeyManagementException (chemin de signature : NextPDF\Security\Signature\Exception)

• Quand elle est levée. Un fournisseur de signataire rencontre une faute de gestion de clés : la version de clé demandée est inconnue, désactivée, programmée pour destruction, dépourvue de la permission de signature, ou autrement inutilisable. C’est ce que lèvent RsaPssSigner et LocalKeySignerProvider sur des échecs de clé en direct. Constructeurs nommés : unknownKeyVersion() et keyVersionDisabled().
• Champs de contexte. providerId, keyVersion, reason. Accesseurs : providerId(), keyVersion(), reason().
• Rétablissement. Fais tourner ou réautorise la clé, ou sélectionne une version de clé utilisable, puis réessaie. Distincte de SignatureFailedException, qui signale que la primitive de signature elle-même a échoué.

Signature

Pour des conseils axés sur le symptôme concernant les niveaux inatteignables et les capacités manquantes, voir Échecs de signature et d’horodatage.

SignatureFailedException (R4-13 : NextPDF\Security\Exception)

• Quand elle est levée. Une opération de signature cryptographique échoue : une primitive de signature RSA, ECDSA ou Ed25519 renvoie false ou une sortie de longueur erronée ; un HSM ou un jeton PKCS#11 répond avec un statut de non-succès ; l’assemblage SignedData de la Cryptographic Message Syntax (CMS) échoue sur un certificat ou une chaîne malformés ; ou une auto-vérification aller-retour Ed25519 échoue. Le nouveau code devrait préférer ce sous-type R4-13 à l’exception de signature héritée couplée à PAdES.
• Champs de contexte. operation (par exemple sign, verify, build_cms), algorithm (par exemple rsa-pkcs1v15-sha256, ed25519), reason. Accesseurs : getOperation(), getAlgorithm(), getReason().
• Rétablissement. Lis l’opération et l’algorithme, corrige l’entrée (clé, chaîne de certificats, ou disponibilité du backend), et réessaie. Aligné sur la posture de gestion de clés en mode fermé d’ETSI EN 319 142-1.

SignatureFailedException (SPI : NextPDF\Security\Signature\Exception)

• Quand elle est levée. Une implémentation de SignerProviderInterface ne peut pas mener à bien une opération de signature pour toute raison non catégorisée comme gestion de clés : erreur de pilote du backend, matériel de clé malformé, ou E/S HSM irrécupérable. C’est le fourre-tout du contrat de signature en mode fermé, où chaque primitive lève en cas d’échec plutôt que de renvoyer null, false ou une chaîne vide. Constructeur nommé : forProvider().
• Champs de contexte. providerId, reason. Accesseurs : providerId(), reason().
• Rétablissement. Inspecte l’identifiant du fournisseur et la raison, corrige le backend du fournisseur ou le matériel de clé, et réessaie. Branche sur KeyManagementException par opposition à ce type pour séparer « la clé est mauvaise » de « la primitive a échoué ».

SignatureLevelUnreachableException

• Quand elle est levée. Le niveau de conformité PAdES demandé ne peut pas être honoré sous l’infrastructure d’exécution actuelle (le plus souvent une autorité d’horodatage manquante pour B-T et au-delà) et l’appelant n’a pas accordé la permission de se dégrader. La valeur par défaut est en mode fermé : le moteur refuse plutôt que de produire silencieusement un niveau inférieur tout en annonçant le niveau supérieur, ce qui serait une régression de niveau eIDAS. Aligné sur ETSI EN 319 142-1 §6. Note que cette classe étend directement NextPdfException (pas SecurityException).
• Champs de contexte. requestedLevel, highestAchievableLevel, reason. Accesseurs : requestedLevel(), highestAchievableLevel(), reason().
• Rétablissement. Lis reason pour identifier l’infrastructure manquante et fournis-la (par exemple configure une autorité d’horodatage), ou passe allowDegradation: true à PadesOrchestrator pour accepter intentionnellement le niveau atteignable le plus élevé.

SignerProviderNotFoundException

• Quand elle est levée. SignerProviderRegistry::get() est interrogé pour un identifiant de fournisseur qui n’est pas enregistré. Implémente PSR-11 NotFoundExceptionInterface, donc le registre est conforme au contrat de conteneur PSR-11. Constructeur nommé : forId(). Cette classe étend RuntimeException et n’expose pas getContext().
• Champs de contexte. Aucun. L’identifiant non enregistré apparaît dans le message.
• Rétablissement. Enregistre le fournisseur sous l’identifiant attendu avant de le demander, ou corrige l’identifiant que tu passes au registre.

Hachage (SHAKE256)

Celles-ci étendent RuntimeException et n’exposent pas getContext(). SHAKE256 est la fonction à sortie extensible SHA-3 requise par certains chemins ISO/TS 32001.

Shake256NotAvailableException

• Quand elle est levée. Au moment du condensat, lorsque le fournisseur sélectionné ne peut pas satisfaire la requête. Constructeurs nommés : noBackend() (aucun backend SHAKE256 fonctionnel sur cet hôte, à travers tous les paliers tentés) et ffiCallFailed() (un appel OpenSSL EVP lié par FFI a renvoyé un statut de non-succès, par exemple depuis une build libcrypto allégée).
• Champs de contexte. Aucun. Le message nomme les paliers tentés ou le symbole en échec.
• Rétablissement. Installe ext-ffi avec OpenSSL 3.x présent, ou mets à niveau vers une build PHP qui expose shake256 dans hash_algos(). Un repli Keccak en espace utilisateur n’est intentionnellement pas livré.

Shake256ProviderNotAvailableException

• Quand elle est levée. Depuis un constructeur de fournisseur SHAKE256 lorsque la sonde de capacité échoue, de sorte que le fournisseur ne peut pas être instancié. C’est un signal de flux de contrôle : le registre des fournisseurs l’attrape, enregistre l’étiquette du palier, et tente le palier suivant. Il ne devrait jamais s’échapper dans le code applicatif. Constructeur nommé : forTier().
• Champs de contexte. Aucun. Le message nomme le palier et la raison.
• Rétablissement. Non actionnable directement par l’appelant ; si toute la chaîne de paliers est épuisée, le registre fait remonter Shake256NotAvailableException::noBackend() à la place, qui porte le correctif destiné à l’opérateur.

Intégrité du MAC de document (ISO/TS 32004)

Celles-ci couvrent le code d’authentification de message (MAC) au niveau du document ISO/TS 32004, stocké sous /AuthCode. Les deux étendent NextPdfException et redéfinissent getContext().

DocumentMacTokenException

• Quand elle est levée. En mode fermé, par le lecteur de jeton MAC, lorsqu’un jeton MAC CMS AuthenticatedData est structurellement malformé ou déclare un algorithme hors de l’ensemble ISO/TS 32004 convenu. Constructeurs nommés : malformed() et algorithmMismatch(). Marquée @internal.
• Champs de contexte. status (la valeur DocumentMacVerificationStatus, soit MalformedToken, soit AlgorithmMismatch). Propriété publique en lecture seule : $status.
• Rétablissement. Traite le document comme non vérifié. Un jeton malformé ou un algorithme hors de l’ensemble convenu signifie que le MAC ne peut pas établir la confiance ; ne procède pas comme si le contenu était protégé.

DocumentMacVerificationException

• Quand elle est levée. En mode fermé, lorsqu’une vérification de MAC au niveau du document ne peut pas atteindre un état de confiance : un /AuthCode manquant ou malformé, un algorithme hors de l’ensemble convenu, un échec de désencapsulage, ou un désaccord de MAC (altération). Le verify() du vérificateur renvoie un résultat explicite pour le branchement ; ceci est l’homologue par flux d’exception levé par assertVerified() afin que le code « fais confiance au contenu » ne puisse jamais dépasser un document non vérifié. Constructeur nommé : fromResult().
• Champs de contexte. status (la valeur DocumentMacVerificationStatus). Propriété publique en lecture seule : $status.
• Rétablissement. Ne fais pas confiance au contenu du document. Inspecte status pour distinguer une altération (désaccord de MAC) d’un problème de configuration (/AuthCode manquant ou malformé, désaccord d’algorithme).

Validation de chemin PKI (RFC 5280)

Celles-ci couvrent la validation de chemin de certification RFC 5280. Le type de base et ses sous-classes sont en mode fermé.

PkiPathValidationException

• Quand elle est levée. Un échec en mode strict du validateur de chemin RFC 5280. C’est la base non finale de sous-classes plus étroites (ChainLengthExceededException, UnsupportedExtensionException), de sorte que les gestionnaires qui attrapent ce type attrapent aussi celles-ci via la substitution de Liskov. Étend SecurityException.
• Champs de contexte. Ne redéfinit pas getContext() (hérite de la valeur par défaut vide). Porte les raisons structurées dans la propriété figée de tableau public en lecture seule $reasons (une liste non vide de chaînes nom-de-règle plus description).
• Rétablissement. Lis $reasons pour identifier la règle en échec, corrige la chaîne de certificats, et revalide. Attrape ce type pour traiter uniformément tout échec de validation de chemin.

ChainLengthExceededException

• Quand elle est levée. Le validateur de chemin est invité à parcourir une chaîne dont la longueur dépasse le plafond configuré. Le plafond est appliqué avant que toute analyse ne commence, de sorte qu’un fournisseur malveillant ne peut pas pousser le validateur vers un travail quadratique ni épuiser les ressources avec une chaîne arbitrairement profonde. Le plafond par défaut de 10 suit le profil PKIX-CMP (RFC 4210 §5.3.18) ; les chaînes du monde réel tiennent en 5 à 6 entrées. Sous-classe de PkiPathValidationException.
• Champs de contexte. Hérite du getContext() vide ; la chaîne de raison chain_length_exceeded: supplied=<n> cap=<n> est transmise dans les $reasons du parent. Propriétés publiques en lecture seule : $supplied, $cap.
• Rétablissement. Fournis une chaîne dans le plafond, ou relève le plafond configuré si une chaîne légitimement plus longue est attendue.

UnsupportedExtensionException

• Quand elle est levée. Le validateur de chemin rencontre une extension X.509 critique dont l’application n’est pas encore implémentée. Selon RFC 5280 §4.2, une extension critique non reconnue doit échouer en mode fermé ; les modes strict et indulgent échouent tous deux en mode fermé ici, puisque sauter silencieusement une extension critique serait une régression de sécurité. Le validateur couvre la construction de chaîne, la correspondance AKI/SKI, l’usage de clé, l’usage de clé étendu, les contraintes de base, l’expiration et la vérification de signature ; tout autre élément critique remonte ici. Sous-classe de PkiPathValidationException.
• Champs de contexte. Hérite du getContext() vide ; les raisons structurées sont transmises dans les $reasons du parent. Propriétés publiques en lecture seule : $extensionOid (OID pointé, par exemple 2.5.29.30 pour les contraintes de nom), $extensionName, $clauseRef (pointeur vers la clause RFC 5280 et l’entrée du journal des éléments différés).
• Rétablissement. En mode indulgent, attrape cette sous-classe spécifique pour retomber sur une politique plus grossière sans avaler de vrais échecs de validation de chemin. Audite $extensionOid et $clauseRef par rapport à tes fixtures PKI pour voir quelle extension bloque la validation.

RevocationCheckFailedException

• Quand elle est levée. Les points de terminaison OCSP et de liste de révocation de certificats (CRL) sont tous deux épuisés sans verdict définitif : échec de transport OCSP ou réponse malformée, et échec de transport CRL ou CRL malformée, avec les deux disjoncteurs ouverts ou les deux caches manquants. Le mode strict traite cela en mode fermé ; le mode indulgent l’attrape et émet un avertissement PSR-3 avec revocation = null. Étend SecurityException.
• Champs de contexte. Ne redéfinit pas getContext() (hérite de la valeur par défaut vide). Porte l’état dans les propriétés publiques en lecture seule $ocspState et $crlState (chacune par défaut à unknown).
• Rétablissement. Restaure l’accessibilité à une source de révocation, attends que les disjoncteurs se ferment, ou réchauffe le cache, puis réessaie. Ne supprime pas cela pour obtenir un artefact de validation à long terme ; l’assertion de révocation fait partie de ce niveau.

Vérification de signature OCSP (RFC 6960)

OcspSignatureInvalidException

• Quand elle est levée. La signature d’une BasicOCSPResponse RFC 6960 §4.2.2.2 échoue à la vérification cryptographique par rapport au certificat du répondeur. L’analyseur décode signatureAlgorithm (RSA-PSS, ECDSA, ou RSA-PKCS1v15) et vérifie signature sur tbsResponseData ; tout échec lève cette exception typée afin que les appelants puissent distinguer une réponse structurellement valide mais cryptographiquement altérée d’une réponse à DER malformé. Non finale, afin que les paquets en aval puissent publier des sous-classes plus spécifiques. Étend SecurityException.
• Champs de contexte. Ne redéfinit pas getContext() (hérite de la valeur par défaut vide). Porte l’étiquette d’échec dans la propriété publique en lecture seule $reason (par exemple signature_mismatch, responder_cert_not_in_bundle, unsupported_signature_algorithm) ; le detail en texte libre est replié dans le message.
• Rétablissement. Inspecte $reason. Pour responder_cert_not_in_bundle, fournis le bon paquet d’ancres de confiance et le certificat du répondeur. Pour signature_mismatch, traite la réponse comme non fiable. Voir Échecs de signature et d’horodatage.

Horodatage (RFC 3161)

TsaException

• Quand elle est levée. Un échec de la communication avec une autorité d’horodatage (TSA) RFC 3161 ou de l’analyse de la réponse : la TSA renvoie un statut d’erreur, la requête HTTP échoue, ou la réponse ASN.1 ne peut pas être analysée. C’est la base de la hiérarchie de fautes TSA et elle est non finale afin que les échecs de vérification puissent l’étendre. Étend NextPdfException.
• Champs de contexte. Ne redéfinit pas getContext() (hérite de la valeur par défaut vide).
• Rétablissement. Attrape TsaException pour tout chemin de faute TSA. Vérifie l’accessibilité de la TSA et que le point de terminaison renvoie une réponse RFC 3161 bien formée.

TsaTokenVerificationException

• Quand elle est levée. La vérification CMS d’un TimeStampToken RFC 3161 échoue à l’une des étapes de vérification obligatoires : liaison ESSCertIDv2 RFC 5816 §3, intégrité des attributs signés RFC 5652 §11, fraîcheur de producedAt RFC 3161 §2.4.2, ou signature SignerInfo RFC 5652 §5.4. En mode fermé, avec un discriminateur d’étape typé afin que les pipelines d’audit puissent distinguer un rejeu d’un décalage d’horloge d’un désaccord de certificat sans grepper les messages. Sous-classe de TsaException, de sorte que les gestionnaires hérités catch (TsaException) continuent de se déclencher.
• Champs de contexte. step (la valeur de Step du pipeline en échec) et message. Accesseur : getStep().
• Rétablissement. Actionnable par un développeur (certificat TSA mal configuré ou tolérance de décalage) ou par la sécurité (MITM ou rejeu suspecté). Lis step pour localiser l’étape en échec et corrige l’entrée correspondante ou la configuration de confiance.

MalformedDerException

• Quand elle est levée. Signal interne indiquant qu’un parcours DER a heurté une frontière malformée ou tronquée, levé par les parcoureurs de bas niveau internes au vérificateur de jeton TSA. Il est toujours attrapé à la frontière de vérification publique et réenveloppé dans une TsaTokenVerificationException portant le bon discriminateur d’étape ; il ne fuit jamais vers le code de l’appelant. Étend RuntimeException ; marquée @internal.
• Champs de contexte. Aucun.
• Rétablissement. Non destinée à l’appelant. Traite plutôt la TsaTokenVerificationException enveloppante.

Décodage d’extensions de certificat

Celles-ci étendent RuntimeException et n’exposent pas getContext(). Les deux sont des décodeurs en mode fermé.

NameConstraintsDecodeException

• Quand elle est levée. Le décodeur de contraintes de nom rencontre un élément GeneralSubtree applicable qu’il ne peut pas décoder fidèlement. RFC 5280 §4.2.1.10 exige qu’une partie utilisatrice traite une contrainte de nom applicable ou rejette le certificat ; convertir l’ancien abandon silencieux en cet échec typé empêche un fail-open qui aurait élargi silencieusement l’ensemble de noms accepté. La portée est limitée aux formes de nom applicables (directoryName, dNSName, iPAddress, rfc822Name, uniformResourceIdentifier) ; les formes non applicables restent ignorables et ne la lèvent jamais. Constructeur nommé : undecodableEnforceableBase(). Marquée @internal.
• Champs de contexte. Aucun. Une chaîne de détail sûre pour les journaux est portée dans le message.
• Rétablissement. L’application fait remonter une raison name_constraints: en mode fermé et la chaîne est rejetée. Enquête sur l’encodage des contraintes de nom du certificat ; ne relâche pas l’application.

QcStatementsDecodeException

• Quand elle est levée. L’extension qcStatements est structurellement malformée : DER tronqué, tag erroné, ou dépassement de longueur. Le décodeur est en mode fermé et lève plutôt que de renvoyer un résultat partiel ou heuristique lorsqu’il ne peut pas déterminer avec certitude ce que dit l’extension. Marquée @api.
• Champs de contexte. Aucun.
• Rétablissement. Attrape-la explicitement uniquement si tu as l’intention de tolérer un encodage malformé ; sinon traite les déclarations de certificat qualifié du certificat comme indéterminables et rejette ou réémets le certificat.

Sessions PKCS#11

Pkcs11SessionException

• Quand elle est levée. Un défaut de gestion de session PKCS#11 v3.1. Chaque constructeur nommé correspond à une classe de défaut spécifique et à une valeur de retour CKR_* de PKCS#11, exposée via le discriminateur typé $kind afin que les appelants branchent sur une chaîne d’énumération stable plutôt que sur une correspondance de message fragile. Les constructeurs incluent : cryptokiNotInitialized(), userNotLoggedIn(), userAlreadyLoggedIn(), operationNotInitialized(), operationActive(), mechanismNotAllowed(), tokenDisconnected(), concurrentSessionLimitExceeded(), sessionAlreadyClosed(), stateTransitionInvalid(), osLockingRequired(), loginTtlExpired() et signOperationTtlExpired(). Étend SecurityException.
• Champs de contexte. Ne redéfinit pas getContext() (hérite de la valeur par défaut vide). Porte le type typé dans la propriété publique en lecture seule $kind, l’une des constantes KIND_* (par exemple KIND_USER_NOT_LOGGED_IN, KIND_TOKEN_DISCONNECTED, KIND_LOGIN_TTL_EXPIRED). Les identifiants de slot et de session, le mécanisme et les valeurs de TTL apparaissent dans le message. Les codes PIN et les octets de certificat ne sont jamais inclus.
• Rétablissement. Aiguille sur $kind. Pour user_not_logged_in, connecte-toi avec le code PIN utilisateur avant d’initialiser une opération de signature. Pour token_disconnected, traite toutes les sessions du slot comme orphelines. Pour les types TTL, réauthentifie-toi ou réinitialise l’opération. Pour mechanism_not_allowed, étends la liste d’autorisation de mécanismes configurée ou choisis un mécanisme autorisé.

Voir aussi

• Index de la référence des erreurs
• Échecs de signature et d’horodatage
• Chiffrement et permissions
• Validation PDF/A et PDF/UA