Errori di sicurezza e firma

In breve

Questa pagina documenta le eccezioni del dominio sicurezza nell’albero del namespace NextPDF\Security. Ogni voce indica la classe, dichiara quando viene sollevata, elenca i campi che la sua getContext() restituisce e fornisce un passaggio di recupero.

La maggior parte di queste classi estende SecurityException, che estende NextPdfException e implementa ContextAwareExceptionInterface. Ciò significa che getContext(): array restituisce diagnosi strutturate e prive di segreti che si possono indirizzare verso pipeline di logging o di application performance monitoring (APM). Intercettare SecurityException per catturare in un unico blocco ogni guasto del dominio sicurezza; intercettare una sottoclasse specifica quando serve il suo payload tipizzato.

Alcune classi di questo albero estendono direttamente RuntimeException anziché SecurityException. Quelle sono contrassegnate di seguito; non espongono getContext() e la maggior parte è documentata come segnale interno di controllo di flusso che non ci si dovrebbe aspettare di intercettare nel codice applicativo.

Convenzione sui campi di contesto

Aspetto	Comportamento
Contratto base	NextPdfException::getContext() restituisce []; le sottoclassi la sovrascrivono.
Igiene dei segreti	Messaggi e contesto omettono materiale di chiave grezzo, testo in chiaro, PIN e byte del vettore di inizializzazione (IV). Le chiavi sono esposte solo come prefisso di impronta digitale.
SecurityException	Base astratta; non trasporta campi propri. Le sottoclassi definiscono il payload.

Tipo base

SecurityException

• Quando viene sollevata. Mai sollevata direttamente; è la base astratta del dominio sicurezza. Esiste affinché un unico blocco catch (SecurityException $e) possa catturare i guasti di integrità della cifratura autenticata, le difese contro il riuso del nonce, il vincolo PDF/A rispetto a cifratura, i guasti di gestione delle chiavi e i guasti PKI.
• Campi di contesto. Nessuno proprio. Eredita il valore predefinito vuoto da NextPdfException; le sottoclassi popolano il payload.
• Recupero. Intercettare la sottoclasse concreta per una gestione azionabile, oppure SecurityException per un instradamento grossolano degli incidenti di sicurezza.

Errori di cifratura e cifratura autenticata

Questi sono sollevati dall’encryptor AES-GCM (Galois/Counter Mode) e dalla guardia PDF/A. Per indicazioni orientate al sintomo, vedere Cifratura e permessi.

DecryptionFailedException

• Quando viene sollevata. Una decifratura con cifratura autenticata con dati associati (AEAD) fallisce per un motivo non riconducibile a manomissione: testo cifrato troncato, un IV mancante o una chiave errata fornita al confine dell’API, dove non c’era materiale sufficiente perché il controllo di integrità potesse effettivamente essere eseguito. È un errore di configurazione o di trasporto, non un incidente di sicurezza.
• Campi di contesto. algorithm (ad esempio AES-256-GCM), reason (ad esempio ciphertext shorter than IV+tag).
• Recupero. Verificare che testo cifrato, IV e chiave siano completi e inquadrati correttamente; non considerarlo una manomissione. Contrapporre a TamperedDataException.

TamperedDataException

• Quando viene sollevata. Il tag di autenticazione AEAD non supera la verifica. Il tag copre il testo cifrato più i dati autenticati associati (AAD); se uno dei due è stato modificato dopo la cifratura, l’openssl_decrypt() sottostante restituisce false. Questo sottotipo distinto consente di far emergere un allarme di livello incidente di sicurezza anziché un errore di framing.
• Campi di contesto. algorithm, ciphertext_length (lunghezza del testo cifrato rifiutato, escludendo IV e tag).
• Recupero. Considerare come manomissione o come chiave/IV errati. Non riprovare alla cieca; indagare sull’origine del testo cifrato. Secondo ISO/TS 32003:2023 §5.2 e NIST SP 800-38D §6.5, un controllo del tag non superato significa che i dati non sono autentici.

NonceReuseException

• Quando viene sollevata. Ad AES-GCM viene chiesto di cifrare due volte con la stessa coppia di chiave e IV. L’encryptor si difende con un contatore monotono per istanza e, come difesa in profondità, con un hash-set a runtime di ogni coppia (impronta della chiave, IV) emessa. Poiché il contatore esclude per costruzione le collisioni, questo scatto è un indicatore di bug a priorità critica che non deve mai verificarsi in produzione. Riutilizzare una coppia chiave/IV compromette l’intero keystream (ISO/TS 32003:2023 §5.2 NOTE 2; NIST SP 800-38D §8.3).
• Campi di contesto. key_fingerprint_prefix (primi 8 caratteri esadecimali di SHA-256(key)), iv_length (sempre 12 per ISO/TS 32003), reason (hashset-collision o counter-rollover, che distingue un bug di refactoring che vanifica il contatore dal trip-wire del contatore a 2^63) e iv_fixed_field_hex (il campo fisso dell’IV, presente solo quando fornito, riportato sotto la propria chiave e mai etichettato erroneamente come impronta della chiave).
• Recupero. Interrompere immediatamente e ruotare la chiave. Aprire una segnalazione di difetto; questo indica un bug nell’encryptor, non un input errato del chiamante.

GcmInvocationLimitExceededException

• Quando viene sollevata. Viene raggiunto un conteggio di invocazioni di sicurezza d’uso NIST SP 800-38D §8.3 attivabile su richiesta per una data chiave AES-GCM. È un hook di telemetria di difesa in profondità per i chiamanti che vogliono imporre il limite raccomandato dalla specifica (circa 2^32 invocazioni per chiave) prima dei limiti architetturali interni all’encryptor. Non scatta per impostazione predefinita; solo l’helper assertWithinSafetyBound() lo solleva.
• Campi di contesto. key_fingerprint_prefix, invocation_count (conteggio encrypt() corrente, pari o superiore al limite), invocation_limit (il limite attivabile su richiesta).
• Recupero. Ruotare la chiave del documento (costruire un nuovo encryptor con nuovo materiale di chiave) prima che la probabilità cumulativa di collisione e contraffazione cessi di essere trascurabile, oppure ampliare la policy del chiamante per rifiutare la continuazione del servizio.

IncompatiblePdfAModeException

• Quando viene sollevata. Si tenta un’operazione di cifratura su un documento con tag PDF/A. La famiglia PDF/A (PDF/A-2, PDF/A-3, PDF/A-4) vieta in modo uniforme la cifratura: secondo ISO 19005 §6.1.3 la chiave Encrypt non deve essere presente nel trailer, e ISO 19005-4:2020 Annexes A e B lo ereditano senza modifiche. Non esiste alcuna combinazione consentita di PDF/A e cifratura.
• Campi di contesto. pdfa_mode (ad esempio pdfa4, pdfa3), encryption_operation (la chiamata rifiutata, ad esempio useAesGcm).
• Recupero. Per produrre un documento cifrato, omettere la chiamata enablePdfA(); per produrre un documento di archiviazione, omettere la chiamata di cifratura. Vedere Convalida PDF/A e PDF/UA.

Applicazione della crypto-policy

CryptoPolicyViolationException

• Quando viene sollevata. Una crypto-policy configurata rifiuta un algoritmo, una robustezza di chiave o un cifrario selezionato da un’operazione core di firma, cifratura o hashing. È il confine fail-closed per l’applicazione della conformità (ad esempio FIPS 140-2/3, eIDAS o una policy enterprise personalizzata) e viene sollevata da CryptoPolicyEnforcer prima che venga prodotta qualsiasi firma o testo cifrato, così che un’operazione che viola la policy non possa mai emettere un artefatto non approvato. Distinta da un guasto ristretto di un’operazione OpenSSL e da un guasto di una primitiva di firma: qui si tratta di un rifiuto di policy di una richiesta per il resto valida. Allineata a NIST SP 800-131A Rev. 2 e ISO/IEC 19790:2025 §7.
• Campi di contesto. policy (nome della policy, ad esempio FIPS 140-3 Strict), category (hash, signature, encryption o key-strength), item (l’elemento rifiutato, ad esempio un object identifier (OID), un nome di cifrario o rsa/1024), reason.
• Recupero. Selezionare un algoritmo, una lunghezza di chiave o un cifrario che la policy indicata approva, oppure regolare la policy se ne si è proprietari. Indirizzare il contesto strutturato verso il runbook di conformità documentato.

Gestione delle chiavi

Esistono due classi con lo stesso nome. Condividono la radice SecurityException, così che un unico blocco catch (SecurityException $e) le catturi entrambe, ma trasportano payload distinti. Importare per nome completo quando serve una forma specifica.

KeyManagementException (ciclo di vita: NextPDF\Security\Exception)

• Quando viene sollevata. Un’operazione di gestione delle chiavi fallisce prima che la chiave sia consumata da una primitiva di firma o cifratura: guasti di parsing di chiavi Privacy-Enhanced Mail (PEM), PKCS#12 o PKCS#11; guasti di derivazione della chiave (HKDF, PBKDF2, scrypt); rifiuto di AES Key Wrap (RFC 3394) su una chiave di cifratura della chiave errata; un hardware security module (HSM) che restituisce Distinguished Encoding Rules (DER) malformate; oppure una discrepanza nella lunghezza del seed Ed25519.
• Campi di contesto. operation (ad esempio load_pem, kek_derive, key_wrap), key_type (ad esempio RSA, EC-P256, Ed25519, AES-256), reason. Il materiale di chiave grezzo non è mai incluso.
• Recupero. Ispezionare l’operazione e il tipo di chiave indicati, correggere il materiale di chiave di origine o l’input di derivazione, quindi riprovare.

KeyManagementException (percorso di firma: NextPDF\Security\Signature\Exception)

• Quando viene sollevata. Un provider di signer incontra un guasto di gestione delle chiavi: la versione di chiave richiesta è sconosciuta, disabilitata, programmata per la distruzione, priva del permesso di firma o comunque inutilizzabile. È ciò che RsaPssSigner e LocalKeySignerProvider sollevano in caso di guasti di chiave live. Costruttori denominati: unknownKeyVersion() e keyVersionDisabled().
• Campi di contesto. providerId, keyVersion, reason. Accessor: providerId(), keyVersion(), reason().
• Recupero. Ruotare o riautorizzare la chiave, oppure selezionare una versione di chiave utilizzabile, quindi riprovare. Distinta da SignatureFailedException, che segnala il fallimento della primitiva di firma stessa.

Firma

Per indicazioni orientate al sintomo su livelli irraggiungibili e capacità mancanti, vedere Errori di firma e marca temporale.

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

• Quando viene sollevata. Un’operazione crittografica di firma fallisce: una primitiva di firma RSA, ECDSA o Ed25519 restituisce false o un output di lunghezza errata; un HSM o un token PKCS#11 risponde con uno stato di non-successo; l’assemblaggio SignedData di Cryptographic Message Syntax (CMS) fallisce su un certificato o una catena malformati; oppure un’autoverifica round-trip Ed25519 fallisce. Il nuovo codice dovrebbe preferire questo sottotipo R4-13 alla legacy eccezione di firma accoppiata a PAdES.
• Campi di contesto. operation (ad esempio sign, verify, build_cms), algorithm (ad esempio rsa-pkcs1v15-sha256, ed25519), reason. Accessor: getOperation(), getAlgorithm(), getReason().
• Recupero. Leggere l’operazione e l’algoritmo, correggere l’input (chiave, catena di certificati o disponibilità del backend), quindi riprovare. Allineata alla postura fail-closed di gestione delle chiavi di ETSI EN 319 142-1.

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

• Quando viene sollevata. Un’implementazione di SignerProviderInterface non può completare un’operazione di firma per qualsiasi motivo non categorizzato come gestione delle chiavi: errore del driver del backend, materiale di chiave malformato o I/O HSM non recuperabile. È il catch-all per il contratto di firma fail-closed, in cui ogni primitiva solleva un’eccezione in caso di guasto anziché restituire null, false o una stringa vuota. Costruttore denominato: forProvider().
• Campi di contesto. providerId, reason. Accessor: providerId(), reason().
• Recupero. Ispezionare l’id del provider e il motivo, correggere il backend del provider o il materiale di chiave, quindi riprovare. Diramare su KeyManagementException rispetto a questo tipo per separare “la chiave è errata” da “la primitiva è fallita”.

SignatureLevelUnreachableException

• Quando viene sollevata. Il livello di conformità PAdES richiesto non può essere onorato con l’infrastruttura di runtime corrente (il più delle volte un’autorità di marca temporale mancante per B-T e superiori) e il chiamante non ha concesso il permesso di degradare. L’impostazione predefinita è fail-closed: il motore rifiuta anziché produrre silenziosamente un livello inferiore mentre pubblicizza quello superiore, il che sarebbe una regressione di livello eIDAS. Allineata a ETSI EN 319 142-1 §6. Si noti che questa classe estende direttamente NextPdfException (non SecurityException).
• Campi di contesto. requestedLevel, highestAchievableLevel, reason. Accessor: requestedLevel(), highestAchievableLevel(), reason().
• Recupero. Leggere reason per individuare l’infrastruttura mancante e fornirla (ad esempio configurare un’autorità di marca temporale), oppure passare allowDegradation: true a PadesOrchestrator per accettare intenzionalmente il livello più alto ottenibile.

SignerProviderNotFoundException

• Quando viene sollevata. A SignerProviderRegistry::get() viene chiesto un id di provider non registrato. Implementa PSR-11 NotFoundExceptionInterface, perciò il registro è conforme al contratto del container PSR-11. Costruttore denominato: forId(). Questa classe estende RuntimeException e non espone getContext().
• Campi di contesto. Nessuno. L’id non registrato compare nel messaggio.
• Recupero. Registrare il provider sotto l’id atteso prima di richiederlo, oppure correggere l’id passato al registro.

Hashing (SHAKE256)

Questi estendono RuntimeException e non espongono getContext(). SHAKE256 è la extendable-output function di SHA-3 richiesta da alcuni percorsi di ISO/TS 32001.

Shake256NotAvailableException

• Quando viene sollevata. Al momento del digest, quando il provider selezionato non può soddisfare la richiesta. Costruttori denominati: noBackend() (nessun backend SHAKE256 funzionante su questo host, in tutti i tier tentati) e ffiCallFailed() (una chiamata OpenSSL EVP via FFI ha restituito uno stato di non-successo, ad esempio da una build di libcrypto ridotta).
• Campi di contesto. Nessuno. Il messaggio indica i tier tentati o il simbolo fallito.
• Recupero. Installare ext-ffi con OpenSSL 3.x presente, oppure aggiornare a una build PHP che espone shake256 in hash_algos(). Un fallback Keccak in userland non viene fornito intenzionalmente.

Shake256ProviderNotAvailableException

• Quando viene sollevata. Da un costruttore di provider SHAKE256 quando la probe di capacità fallisce, così che il provider non possa essere istanziato. È un segnale di controllo di flusso: il registro dei provider la intercetta, registra l’etichetta del tier e prova il tier successivo. Non dovrebbe mai sfuggire nel codice applicativo. Costruttore denominato: forTier().
• Campi di contesto. Nessuno. Il messaggio indica il tier e il motivo.
• Recupero. Non direttamente azionabile dal chiamante; se l’intera catena di tier è esaurita, il registro fa emergere invece Shake256NotAvailableException::noBackend(), che trasporta la correzione rivolta all’operatore.

Integrità MAC del documento (ISO/TS 32004)

Questi coprono il message authentication code (MAC) a livello di documento di ISO/TS 32004, memorizzato sotto /AuthCode. Entrambi estendono NextPdfException e sovrascrivono getContext().

DocumentMacTokenException

• Quando viene sollevata. Fail-closed, dal reader del token MAC, quando un token MAC AuthenticatedData CMS è strutturalmente malformato o dichiara un algoritmo fuori dall’insieme ISO/TS 32004 concordato. Costruttori denominati: malformed() e algorithmMismatch(). Contrassegnata @internal.
• Campi di contesto. status (il valore di DocumentMacVerificationStatus, MalformedToken o AlgorithmMismatch). Proprietà pubblica readonly: $status.
• Recupero. Considerare il documento come non verificato. Un token malformato o un algoritmo fuori dall’insieme concordato significano che il MAC non può stabilire fiducia; non procedere come se il contenuto fosse protetto.

DocumentMacVerificationException

• Quando viene sollevata. Fail-closed, quando una verifica del MAC a livello di documento non può raggiungere uno stato attendibile: un /AuthCode mancante o malformato, un algoritmo fuori dall’insieme concordato, un guasto di unwrap o una discrepanza del MAC (manomissione). Il metodo verify() del verificatore restituisce un risultato esplicito per la diramazione; questa è la controparte a flusso di eccezione sollevata da assertVerified(), così che il codice che “considera attendibile il contenuto” non possa mai procedere oltre un documento non verificato. Costruttore denominato: fromResult().
• Campi di contesto. status (il valore di DocumentMacVerificationStatus). Proprietà pubblica readonly: $status.
• Recupero. Non considerare attendibile il contenuto del documento. Ispezionare status per distinguere una manomissione (discrepanza del MAC) da un problema di configurazione (/AuthCode mancante o malformato, discrepanza dell’algoritmo).

Convalida del percorso PKI (RFC 5280)

Questi coprono la convalida del percorso di certificazione di RFC 5280. Il tipo base e le sue sottoclassi sono fail-closed.

PkiPathValidationException

• Quando viene sollevata. Un guasto in modalità strict del validatore del percorso RFC 5280. È la base non-finale per sottoclassi più ristrette (ChainLengthExceededException, UnsupportedExtensionException), così che i gestori che intercettano questo tipo catturino anche quelle per sostituzione di Liskov. Estende SecurityException.
• Campi di contesto. Non sovrascrive getContext() (eredita il valore predefinito vuoto). Trasporta i motivi strutturati nella proprietà pubblica readonly congelata $reasons (un elenco non vuoto di stringhe nome-regola più descrizione).
• Recupero. Leggere $reasons per individuare la regola fallita, correggere la catena di certificati e rivalidare. Intercettare questo tipo per gestire in modo uniforme qualsiasi guasto di convalida del percorso.

ChainLengthExceededException

• Quando viene sollevata. Al validatore del percorso viene chiesto di percorrere una catena la cui lunghezza supera il tetto configurato. Il limite viene imposto prima dell’inizio di qualsiasi parsing, così che un fornitore malevolo non possa spingere il validatore in un lavoro quadratico o esaurire le risorse con una catena arbitrariamente profonda. Il tetto predefinito di 10 segue il profilo PKIX-CMP (RFC 4210 §5.3.18); le catene reali stanno in 5 o 6 voci. Sottoclasse di PkiPathValidationException.
• Campi di contesto. Eredita la getContext() vuota; la stringa di motivo chain_length_exceeded: supplied=<n> cap=<n> viene inoltrata nei $reasons del genitore. Proprietà pubbliche readonly: $supplied, $cap.
• Recupero. Fornire una catena entro il tetto, oppure innalzare il limite configurato se è attesa una catena legittimamente più lunga.

UnsupportedExtensionException

• Quando viene sollevata. Il validatore del percorso incontra un’estensione X.509 critica la cui applicazione non è ancora implementata. Secondo RFC 5280 §4.2, un’estensione critica non riconosciuta deve adottare il fail-closed; sia la modalità strict sia quella lenient adottano qui il fail-closed, poiché saltare silenziosamente un’estensione critica sarebbe una regressione di sicurezza. Il validatore copre costruzione della catena, corrispondenza AKI/SKI, key usage, extended key usage, basic constraints, scadenza e verifica della firma; qualsiasi altra estensione critica emerge qui. Sottoclasse di PkiPathValidationException.
• Campi di contesto. Eredita la getContext() vuota; i motivi strutturati vengono inoltrati nei $reasons del genitore. Proprietà pubbliche readonly: $extensionOid (OID con punti, ad esempio 2.5.29.30 per i vincoli sui nomi), $extensionName, $clauseRef (puntatore alla clausola RFC 5280 e alla voce di log degli elementi differiti).
• Recupero. In modalità lenient, intercettare questa sottoclasse specifica per ripiegare su una policy più grossolana senza inghiottire i veri guasti di convalida del percorso. Verificare $extensionOid e $clauseRef rispetto alle proprie fixture PKI per capire quale estensione blocca la convalida.

RevocationCheckFailedException

• Quando viene sollevata. Sia gli endpoint OCSP sia quelli di certificate revocation list (CRL) sono esauriti senza un verdetto definitivo: guasto di trasporto OCSP o risposta malformata, e guasto di trasporto CRL o CRL malformata, con entrambi i circuit breaker aperti o entrambe le cache mancanti. La modalità strict la tratta come fail-closed; la modalità lenient la intercetta ed emette un avviso PSR-3 con revocation = null. Estende SecurityException.
• Campi di contesto. Non sovrascrive getContext() (eredita il valore predefinito vuoto). Trasporta lo stato nelle proprietà pubbliche readonly $ocspState e $crlState (ciascuna con valore predefinito unknown).
• Recupero. Ripristinare la raggiungibilità di una fonte di revoca, attendere che i circuit breaker si chiudano oppure preriscaldare la cache, quindi riprovare. Non sopprimere questo errore per ottenere un artefatto di convalida a lungo termine; l’asserzione di revoca fa parte di quel livello.

Verifica della firma OCSP (RFC 6960)

OcspSignatureInvalidException

• Quando viene sollevata. Una firma di BasicOCSPResponse di RFC 6960 §4.2.2.2 non supera la verifica crittografica rispetto al certificato del responder. Il parser decodifica signatureAlgorithm (RSA-PSS, ECDSA o RSA-PKCS1v15) e verifica signature su tbsResponseData; qualsiasi fallimento solleva questa eccezione tipizzata, così che i chiamanti possano distinguere una risposta strutturalmente valida ma crittograficamente manomessa da una risposta con DER malformato. Non-finale, così che i pacchetti a valle possano pubblicare sottoclassi più specifiche. Estende SecurityException.
• Campi di contesto. Non sovrascrive getContext() (eredita il valore predefinito vuoto). Trasporta il tag di guasto nella proprietà pubblica readonly $reason (ad esempio signature_mismatch, responder_cert_not_in_bundle, unsupported_signature_algorithm); il detail a testo libero è inglobato nel messaggio.
• Recupero. Ispezionare $reason. Per responder_cert_not_in_bundle, fornire il bundle di trust anchor corretto e il certificato del responder. Per signature_mismatch, considerare la risposta non attendibile. Vedere Errori di firma e marca temporale.

Marcatura temporale (RFC 3161)

TsaException

• Quando viene sollevata. Un guasto nella comunicazione con la time-stamp authority (TSA) di RFC 3161 o nel parsing della risposta: la TSA restituisce uno stato di errore, la richiesta HTTP fallisce, oppure la risposta ASN.1 non può essere analizzata. È la base della gerarchia dei guasti TSA ed è non-finale così che i guasti di verifica possano estenderla. Estende NextPdfException.
• Campi di contesto. Non sovrascrive getContext() (eredita il valore predefinito vuoto).
• Recupero. Intercettare TsaException per qualsiasi percorso di guasto TSA. Verificare la raggiungibilità della TSA e che l’endpoint restituisca una risposta RFC 3161 ben formata.

TsaTokenVerificationException

• Quando viene sollevata. La verifica CMS di un TimeStampToken di RFC 3161 fallisce in uno qualsiasi dei passaggi di verifica obbligatori: binding ESSCertIDv2 di RFC 5816 §3, integrità degli attributi firmati di RFC 5652 §11, freschezza di producedAt di RFC 3161 §2.4.2, oppure firma SignerInfo di RFC 5652 §5.4. Fail-closed, con un discriminatore di passaggio tipizzato così che le pipeline di audit possano distinguere replay da clock skew da cert-mismatch senza grep dei messaggi. Sottoclasse di TsaException, perciò i gestori legacy catch (TsaException) continuano a scattare.
• Campi di contesto. step (il valore Step del passaggio fallito) e message. Accessor: getStep().
• Recupero. Azionabile da uno sviluppatore (certificato TSA mal configurato o tolleranza di skew) o dalla sicurezza (sospetto MITM o replay). Leggere step per localizzare la fase fallita e correggere il corrispondente input o la configurazione di trust.

MalformedDerException

• Quando viene sollevata. Segnale interno che un walk DER ha incontrato un confine malformato o troncato, sollevato dai walker di basso livello interni al verificatore del token TSA. Viene sempre intercettato al confine di verify pubblico e riavvolto in una TsaTokenVerificationException che trasporta il discriminatore di passaggio corretto; non sfugge mai al codice del chiamante. Estende RuntimeException; contrassegnata @internal.
• Campi di contesto. Nessuno.
• Recupero. Non rivolta al chiamante. Gestire invece la TsaTokenVerificationException che la racchiude.

Decodifica delle estensioni dei certificati

Questi estendono RuntimeException e non espongono getContext(). Entrambi sono decodificatori fail-closed.

NameConstraintsDecodeException

• Quando viene sollevata. Il decodificatore dei vincoli sui nomi incontra un elemento GeneralSubtree applicabile che non può decodificare fedelmente. RFC 5280 §4.2.1.10 richiede che una relying party elabori un vincolo sui nomi applicabile o rifiuti il certificato; convertire il precedente drop silenzioso in questo guasto tipizzato impedisce un fail-open che avrebbe silenziosamente ampliato l’insieme di nomi accettati. L’ambito è limitato alle forme di nome applicabili (directoryName, dNSName, iPAddress, rfc822Name, uniformResourceIdentifier); le forme non applicabili restano ignorabili e non la sollevano mai. Costruttore denominato: undecodableEnforceableBase(). Contrassegnata @internal.
• Campi di contesto. Nessuno. Una stringa di dettaglio log-safe è trasportata nel messaggio.
• Recupero. L’enforcer fa emergere un motivo fail-closed name_constraints: e la catena viene rifiutata. Indagare sulla codifica dei vincoli sui nomi del certificato; non allentare l’applicazione.

QcStatementsDecodeException

• Quando viene sollevata. L’estensione qcStatements è strutturalmente malformata: DER troncato, un tag errato o un overflow di lunghezza. Il decodificatore è fail-closed e solleva un’eccezione anziché restituire un risultato parziale o euristico quando non può determinare con certezza cosa dice l’estensione. Contrassegnata @api.
• Campi di contesto. Nessuno.
• Recupero. Intercettarla esplicitamente solo se si intende tollerare una codifica malformata; altrimenti considerare gli statement di certificato qualificato del certificato come indeterminabili e rifiutare o riemettere il certificato.

Sessioni PKCS#11

Pkcs11SessionException

• Quando viene sollevata. Un difetto di gestione delle sessioni PKCS#11 v3.1. Ogni costruttore denominato mappa a una specifica classe di difetto e a un valore di ritorno PKCS#11 CKR_*, esposto tramite il discriminatore tipizzato $kind, così che i chiamanti diramino su una stringa-enum stabile anziché su una fragile corrispondenza di messaggi. I costruttori includono: cryptokiNotInitialized(), userNotLoggedIn(), userAlreadyLoggedIn(), operationNotInitialized(), operationActive(), mechanismNotAllowed(), tokenDisconnected(), concurrentSessionLimitExceeded(), sessionAlreadyClosed(), stateTransitionInvalid(), osLockingRequired(), loginTtlExpired() e signOperationTtlExpired(). Estende SecurityException.
• Campi di contesto. Non sovrascrive getContext() (eredita il valore predefinito vuoto). Trasporta il kind tipizzato nella proprietà pubblica readonly $kind, una delle costanti KIND_* (ad esempio KIND_USER_NOT_LOGGED_IN, KIND_TOKEN_DISCONNECTED, KIND_LOGIN_TTL_EXPIRED). Gli identificatori di slot e sessione, il meccanismo e i valori di TTL compaiono nel messaggio. I PIN e i byte dei certificati non sono mai inclusi.
• Recupero. Diramare su $kind. Per user_not_logged_in, effettuare il login con il PIN utente prima di inizializzare un’operazione di firma. Per token_disconnected, considerare orfane tutte le sessioni sullo slot. Per i kind di TTL, riautenticarsi o reinizializzare l’operazione. Per mechanism_not_allowed, estendere la allow-list dei meccanismi configurata o scegliere un meccanismo consentito.

Vedere anche

• Indice del riferimento degli errori
• Errori di firma e marca temporale
• Cifratura e permessi
• Convalida PDF/A e PDF/UA