Security- und Signaturfehler

Auf einen Blick

Diese Seite dokumentiert die Security-Domänen-Exceptions im Namespace-Baum NextPDF\Security. Jeder Eintrag nennt die Klasse, gibt an, wann sie ausgelöst wird, listet die Felder auf, die ihr getContext() zurückgibt, und gibt einen Behebungsschritt an.

Die meisten dieser Klassen erweitern SecurityException, das NextPdfException erweitert und ContextAwareExceptionInterface implementiert. Das bedeutet, dass getContext(): array strukturierte, secret-freie Diagnosen zurückgibt, die Sie an Logging- oder Application-Performance-Monitoring-(APM-)Pipelines routen können. Fangen Sie SecurityException ab, um jeden Security-Domänen-Fehler in einem Block abzufangen; fangen Sie eine bestimmte Unterklasse ab, wenn Sie ihre typisierte Payload benötigen.

Einige wenige Klassen in diesem Baum erweitern RuntimeException direkt statt SecurityException. Diese sind unten gekennzeichnet; sie legen kein getContext() offen, und die meisten sind als interne Kontrollfluss-Signale dokumentiert, die Sie in Anwendungscode nicht abfangen sollten.

Konvention für Kontextfelder

Aspekt	Verhalten
Basisvertrag	NextPdfException::getContext() gibt [] zurück; Unterklassen überschreiben es.
Secret-Hygiene	Meldungen und Kontext lassen rohes Schlüsselmaterial, Klartext, PINs und Initialisierungsvektor-(IV-)Bytes weg. Schlüssel werden nur als Fingerprint-Präfix offengelegt.
SecurityException	Abstrakte Basis; trägt keine eigenen Felder. Unterklassen definieren die Payload.

Basistyp

SecurityException

• Wann ausgelöst. Wird nie direkt ausgelöst; es ist die abstrakte Basis für die Security-Domäne. Es existiert, damit ein einziger catch (SecurityException $e)-Block Integritätsfehler authentifizierter Verschlüsselung, Abwehr von Nonce-Wiederverwendung, die PDF/A-gegen-Verschlüsselung-Bindung, Schlüsselverwaltungsfehler und PKI-Fehler abfangen kann.
• Kontextfelder. Keine eigenen. Erbt die leere Voreinstellung von NextPdfException; Unterklassen füllen die Payload.
• Behebung. Fangen Sie die konkrete Unterklasse für umsetzbare Behandlung ab, oder SecurityException für grobes Security-Incident-Routing.

Verschlüsselungs- und authentifizierte-Verschlüsselungs-Fehler

Diese werden vom AES-GCM-(Galois/Counter-Mode-)Encryptor und dem PDF/A- Guard ausgelöst. Für symptomorientierte Hinweise siehe Verschlüsselung und Berechtigungen.

DecryptionFailedException

• Wann ausgelöst. Eine authentifizierte Verschlüsselung mit zugehörigen Daten (AEAD) scheitert beim Entschlüsseln aus einem Nicht-Manipulationsgrund: abgeschnittener Chiffretext, ein fehlender IV oder ein an der API-Grenze übergebener falscher Schlüssel, bei dem nicht genügend Material vorhanden war, damit die Integritätsprüfung tatsächlich ausgeführt werden konnte. Dies ist ein Konfigurations- oder Transportfehler, kein Sicherheitsvorfall.
• Kontextfelder. algorithm (zum Beispiel AES-256-GCM), reason (zum Beispiel ciphertext shorter than IV+tag).
• Behebung. Prüfen Sie, ob Chiffretext, IV und Schlüssel vollständig und korrekt gerahmt sind; behandeln Sie dies nicht als Manipulation. Kontrastieren Sie mit TamperedDataException.

TamperedDataException

• Wann ausgelöst. Das AEAD-Authentifizierungs-Tag besteht die Verifizierung nicht. Das Tag deckt Chiffretext plus zugehörige authentifizierte Daten (AAD) ab; wenn eines von beiden nach der Verschlüsselung verändert wurde, gibt das zugrunde liegende openssl_decrypt() false zurück. Dieser eigene Subtyp lässt Sie einen Alarm in Sicherheitsvorfall-Qualität statt eines Rahmungsfehlers zutage fördern.
• Kontextfelder. algorithm, ciphertext_length (Länge des abgelehnten Chiffretexts, ohne IV und Tag).
• Behebung. Behandeln Sie es als Manipulation oder als falschen Schlüssel/IV. Wiederholen Sie nicht blind; untersuchen Sie die Quelle des Chiffretexts. Gemäß ISO/TS 32003:2023 §5.2 und NIST SP 800-38D §6.5 bedeutet eine fehlgeschlagene Tag-Prüfung, dass die Daten nicht authentisch sind.

NonceReuseException

• Wann ausgelöst. AES-GCM wird gebeten, zweimal mit demselben Schlüssel- und IV- Paar zu verschlüsseln. Der Encryptor verteidigt sich mit einem instanzbezogenen monotonen Zähler und, als Defense-in-Depth, einem Laufzeit-Hash-Set jedes ausgegebenen (Schlüssel-Fingerprint, IV)- Paares. Da der Zähler Kollisionen konstruktionsbedingt ausschließt, ist dieses Auslösen ein Bug-Indikator kritischer Priorität, der in der Produktion niemals auftreten darf. Die Wiederverwendung eines Schlüssel/IV-Paares kompromittiert den gesamten Keystream (ISO/TS 32003:2023 §5.2 NOTE 2; NIST SP 800-38D §8.3).
• Kontextfelder. key_fingerprint_prefix (erste 8 Hex-Zeichen von SHA-256(key)), iv_length (immer 12 für ISO/TS 32003), reason (hashset-collision oder counter-rollover, zur Unterscheidung eines zählerbesiegenden Refactor-Bugs vom 2^63-Zähler-Stolperdraht) und iv_fixed_field_hex (das IV-Festfeld, nur vorhanden, wenn übergeben, unter seinem eigenen Schlüssel gemeldet und nie fälschlich als Schlüssel-Fingerprint bezeichnet).
• Behebung. Brechen Sie sofort ab und rotieren Sie den Schlüssel. Reichen Sie einen Defektbericht ein; dies zeigt einen Bug im Encryptor an, keine fehlerhafte Aufrufer-Eingabe.

GcmInvocationLimitExceededException

• Wann ausgelöst. Ein opt-in-NIST-SP-800-38D-§8.3-Safety-of-use-Aufrufzähler wird für einen gegebenen AES-GCM-Schlüssel erreicht. Dies ist ein Defense-in-Depth-Telemetrie-Hook für Aufrufer, die die spezifikationsempfohlene Grenze (etwa 2^32 Aufrufe pro Schlüssel) früher erzwingen wollen als die architektonischen Grenzen innerhalb des Encryptors. Er löst nicht standardmäßig aus; nur der assertWithinSafetyBound()- Helper löst ihn aus.
• Kontextfelder. key_fingerprint_prefix, invocation_count (aktueller encrypt()-Zähler, am oder über dem Limit), invocation_limit (die opt-in- Grenze).
• Behebung. Rotieren Sie den Dokumentschlüssel (konstruieren Sie einen frischen Encryptor mit neuem Schlüssel- Material), bevor die kumulative Kollisions- und Fälschungswahrscheinlichkeit aufhört, vernachlässigbar zu sein, oder erweitern Sie die Aufrufer-Policy, um weiteren Service zu verweigern.

IncompatiblePdfAModeException

• Wann ausgelöst. Eine Verschlüsselungsoperation wird auf einem PDF/A-getaggten Dokument versucht. Die PDF/A-Familie (PDF/A-2, PDF/A-3, PDF/A-4) verbietet Verschlüsselung einheitlich: Gemäß ISO 19005 §6.1.3 darf der Encrypt-Schlüssel nicht im Trailer vorhanden sein, und ISO 19005-4:2020 Annexes A und B übernehmen dies ohne Änderung. Es gibt keine erlaubte Kombination von PDF/A und Verschlüsselung.
• Kontextfelder. pdfa_mode (zum Beispiel pdfa4, pdfa3), encryption_operation (der abgelehnte Aufruf, zum Beispiel useAesGcm).
• Behebung. Um ein verschlüsseltes Dokument zu erzeugen, lassen Sie den enablePdfA()-Aufruf weg; um ein Archivdokument zu erzeugen, lassen Sie den Verschlüsselungsaufruf weg. Siehe PDF/A- und PDF/UA-Validierung.

Durchsetzung der Crypto-Policy

CryptoPolicyViolationException

• Wann ausgelöst. Eine konfigurierte Crypto-Policy lehnt einen Algorithmus, eine Schlüsselstärke oder eine Cipher ab, die von einer Core-Signier-, -Verschlüsselungs- oder -Hashing-Operation gewählt wurde. Sie ist die Fail-closed-Grenze für die Compliance-Durchsetzung (zum Beispiel FIPS 140-2/3, eIDAS oder eine benutzerdefinierte Enterprise-Policy) und wird von CryptoPolicyEnforcer ausgelöst, bevor eine Signatur oder ein Chiffretext erzeugt wird, sodass eine policy-verletzende Operation niemals ein nicht zugelassenes Artefakt ausgeben kann. Verschieden von einem schmalen OpenSSL-Operations- fehler und von einem Signier-Primitive-Fehler: Dies ist eine Policy-Ablehnung einer ansonsten gültigen Anforderung. Ausgerichtet an NIST SP 800-131A Rev. 2 und ISO/IEC 19790:2025 §7.
• Kontextfelder. policy (Policy-Name, zum Beispiel FIPS 140-3 Strict), category (hash, signature, encryption oder key-strength), item (das abgelehnte Element, zum Beispiel ein Object Identifier (OID), Cipher-Name oder rsa/1024), reason.
• Behebung. Wählen Sie einen Algorithmus, eine Schlüssellänge oder eine Cipher, die die benannte Policy zulässt, oder passen Sie die Policy an, wenn sie Ihnen gehört. Routen Sie den strukturierten Kontext an das dokumentierte Compliance-Runbook.

Schlüsselverwaltung

Es existieren zwei gleichnamige Klassen. Sie teilen die SecurityException-Wurzel, sodass ein catch (SecurityException $e)-Block beide abfängt, aber sie tragen unterschiedliche Payloads. Importieren Sie über den vollständig qualifizierten Namen, wenn Sie eine bestimmte Form benötigen.

KeyManagementException (Lebenszyklus: NextPDF\Security\Exception)

• Wann ausgelöst. Eine Schlüsselverwaltungsoperation schlägt fehl, bevor der Schlüssel von einem Sign- oder Encrypt-Primitive konsumiert wird: Privacy-Enhanced Mail (PEM), PKCS#12 oder PKCS#11 Schlüssel-Parse-Fehler; Schlüsselableitungs-(HKDF, PBKDF2, scrypt-)Fehler; AES Key Wrap (RFC 3394)-Ablehnung bei einem falschen Schlüsselverschlüsselungsschlüssel; ein Hardware Security Module (HSM), das fehlerhafte Distinguished Encoding Rules (DER) zurückgibt; oder eine Ed25519-Seed- Längenabweichung.
• Kontextfelder. operation (zum Beispiel load_pem, kek_derive, key_wrap), key_type (zum Beispiel RSA, EC-P256, Ed25519, AES-256), reason. Rohes Schlüsselmaterial ist niemals enthalten.
• Behebung. Inspizieren Sie die benannte Operation und den Schlüsseltyp, korrigieren Sie das Quell-Schlüssel- material oder die Ableitungseingabe und versuchen Sie es erneut.

KeyManagementException (Signierpfad: NextPDF\Security\Signature\Exception)

• Wann ausgelöst. Ein Signer-Provider stößt auf einen Schlüsselverwaltungsfehler: Die angeforderte Schlüsselversion ist unbekannt, deaktiviert, zur Zerstörung vorgesehen, hat keine Signier- berechtigung oder ist anderweitig unbrauchbar. Das ist es, was RsaPssSigner und LocalKeySignerProvider bei Live-Schlüsselfehlern auslösen. Benannte Konstruktoren: unknownKeyVersion() und keyVersionDisabled().
• Kontextfelder. providerId, keyVersion, reason. Accessoren: providerId(), keyVersion(), reason().
• Behebung. Rotieren oder berechtigen Sie den Schlüssel neu, oder wählen Sie eine nutzbare Schlüsselversion, und versuchen Sie es erneut. Verschieden von SignatureFailedException, das signalisiert, dass das Signier-Primitive selbst fehlgeschlagen ist.

Signieren

Für symptomorientierte Hinweise zu unerreichbaren Stufen und fehlenden Capabilities siehe Signatur- und Zeitstempelfehler.

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

• Wann ausgelöst. Eine kryptografische Signieroperation schlägt fehl: Ein RSA-, ECDSA- oder Ed25519-Sign-Primitive gibt false oder eine Ausgabe falscher Länge zurück; ein HSM oder PKCS#11- Token antwortet mit einem Nicht-Erfolgs-Status; die Cryptographic-Message-Syntax-(CMS-) SignedData-Assemblierung scheitert an einem fehlerhaften Zertifikat oder einer fehlerhaften Kette; oder ein Ed25519- Round-Trip-Selbstverify schlägt fehl. Neuer Code sollte diesen R4-13-Subtyp gegenüber der Legacy-PAdES-gekoppelten Signatur-Exception bevorzugen.
• Kontextfelder. operation (zum Beispiel sign, verify, build_cms), algorithm (zum Beispiel rsa-pkcs1v15-sha256, ed25519), reason. Accessoren: getOperation(), getAlgorithm(), getReason().
• Behebung. Lesen Sie die Operation und den Algorithmus, korrigieren Sie die Eingabe (Schlüssel, Zertifikatskette oder Backend-Verfügbarkeit) und versuchen Sie es erneut. Ausgerichtet an der Fail-closed-Schlüsselhandhabungshaltung von ETSI EN 319 142-1.

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

• Wann ausgelöst. Eine SignerProviderInterface-Implementierung kann eine Signieroperation aus irgendeinem Grund nicht abschließen, der nicht als Schlüsselverwaltung kategorisiert ist: Backend-Treiberfehler, fehlerhaftes Schlüsselmaterial oder nicht behebbares HSM-I/O. Dies ist der Catch-all für den Fail-closed-Signiervertrag, bei dem jedes Primitive bei Fehlschlag auslöst, statt null, false oder einen leeren String zurückzugeben. Benannter Konstruktor: forProvider().
• Kontextfelder. providerId, reason. Accessoren: providerId(), reason().
• Behebung. Inspizieren Sie die Provider-ID und den Grund, korrigieren Sie das Provider-Backend oder das Schlüsselmaterial und versuchen Sie es erneut. Verzweigen Sie auf KeyManagementException gegenüber diesem Typ, um „der Schlüssel ist fehlerhaft“ von „das Primitive ist fehlgeschlagen“ zu trennen.

SignatureLevelUnreachableException

• Wann ausgelöst. Die angeforderte PAdES-Konformitätsstufe kann unter der aktuellen Laufzeitinfrastruktur nicht eingehalten werden (meist eine fehlende Zeitstempelstelle für B-T und höher), und der Aufrufer hat keine Erlaubnis zum Herabstufen erteilt. Die Voreinstellung ist fail-closed: Die Engine verweigert, statt stillschweigend eine niedrigere Stufe zu erzeugen und dabei die höhere auszuweisen, was eine Regression in eIDAS-Qualität wäre. Ausgerichtet an ETSI EN 319 142-1 §6. Beachten Sie, dass diese Klasse NextPdfException direkt erweitert (nicht SecurityException).
• Kontextfelder. requestedLevel, highestAchievableLevel, reason. Accessoren: requestedLevel(), highestAchievableLevel(), reason().
• Behebung. Lesen Sie reason, um die fehlende Infrastruktur zu identifizieren, und stellen Sie sie bereit (richten Sie zum Beispiel eine Zeitstempelstelle ein), oder übergeben Sie allowDegradation: true an PadesOrchestrator, um die höchste erreichbare Stufe absichtlich zu akzeptieren.

SignerProviderNotFoundException

• Wann ausgelöst. SignerProviderRegistry::get() wird nach einer Provider-ID gefragt, die nicht registriert ist. Implementiert PSR-11 NotFoundExceptionInterface, sodass die Registry dem PSR-11-Container-Vertrag entspricht. Benannter Konstruktor: forId(). Diese Klasse erweitert RuntimeException und legt kein getContext() offen.
• Kontextfelder. Keine. Die nicht registrierte ID erscheint in der Meldung.
• Behebung. Registrieren Sie den Provider unter der erwarteten ID, bevor Sie ihn anfordern, oder korrigieren Sie die ID, die Sie an die Registry übergeben.

Hashing (SHAKE256)

Diese erweitern RuntimeException und legen kein getContext() offen. SHAKE256 ist die SHA-3-Extendable-Output-Function, die von einigen ISO/TS-32001-Pfaden benötigt wird.

Shake256NotAvailableException

• Wann ausgelöst. Zur Digest-Zeit, wenn der gewählte Provider die Anforderung nicht erfüllen kann. Benannte Konstruktoren: noBackend() (kein funktionierendes SHAKE256-Backend auf diesem Host über alle versuchten Tiers hinweg) und ffiCallFailed() (ein FFI-gebundener OpenSSL- EVP-Aufruf gab einen Nicht-Erfolgs-Status zurück, zum Beispiel von einem gestrippten libcrypto- Build).
• Kontextfelder. Keine. Die Meldung nennt die versuchten Tiers oder das fehlgeschlagene Symbol.
• Behebung. Installieren Sie ext-ffi mit vorhandenem OpenSSL 3.x, oder aktualisieren Sie auf einen PHP- Build, der shake256 in hash_algos() offenlegt. Ein Userland-Keccak-Fallback wird absichtlich nicht ausgeliefert.

Shake256ProviderNotAvailableException

• Wann ausgelöst. Aus einem SHAKE256-Provider-Konstruktor, wenn die Capability-Probe fehlschlägt, sodass der Provider nicht instanziiert werden kann. Es ist ein Kontrollfluss-Signal: Die Provider-Registry fängt es ab, vermerkt das Tier-Label und versucht das nächste Tier. Es sollte niemals in Anwendungscode entweichen. Benannter Konstruktor: forTier().
• Kontextfelder. Keine. Die Meldung nennt das Tier und den Grund.
• Behebung. Nicht direkt vom Aufrufer umsetzbar; wenn die gesamte Tier-Kette erschöpft ist, fördert die Registry stattdessen Shake256NotAvailableException::noBackend() zutage, das die betriebsseitige Behebung trägt.

Document-MAC-Integrität (ISO/TS 32004)

Diese decken den dokumentweiten Message Authentication Code (MAC) gemäß ISO/TS 32004 ab, gespeichert unter /AuthCode. Beide erweitern NextPdfException und überschreiben getContext().

DocumentMacTokenException

• Wann ausgelöst. Fail-closed, vom MAC-Token-Reader, wenn ein CMS- AuthenticatedData-MAC-Token strukturell fehlerhaft ist oder einen Algorithmus außerhalb des vereinbarten ISO/TS-32004-Satzes deklariert. Benannte Konstruktoren: malformed() und algorithmMismatch(). Als @internal markiert.
• Kontextfelder. status (der DocumentMacVerificationStatus-Wert, entweder MalformedToken oder AlgorithmMismatch). Öffentliche readonly-Eigenschaft: $status.
• Behebung. Behandeln Sie das Dokument als nicht verifiziert. Ein fehlerhaftes Token oder ein Algorithmus außerhalb des vereinbarten Satzes bedeutet, dass der MAC kein Vertrauen herstellen kann; fahren Sie nicht fort, als ob der Inhalt geschützt wäre.

DocumentMacVerificationException

• Wann ausgelöst. Fail-closed, wenn eine dokumentweite MAC-Verifizierung keinen vertrauenswürdigen Zustand erreichen kann: ein fehlendes oder fehlerhaftes /AuthCode, ein Algorithmus außerhalb des vereinbarten Satzes, ein Unwrap-Fehler oder ein MAC-Mismatch (Manipulation). Die verify()-Methode des Verifiers gibt ein explizites Ergebnis zur Verzweigung zurück; dies ist das Exception-Flow-Gegenstück, ausgelöst von assertVerified(), sodass „dem Inhalt vertrauen“- Code niemals über ein unverifiziertes Dokument hinaus fortfahren kann. Benannter Konstruktor: fromResult().
• Kontextfelder. status (der DocumentMacVerificationStatus-Wert). Öffentliche readonly-Eigenschaft: $status.
• Behebung. Vertrauen Sie dem Dokumentinhalt nicht. Inspizieren Sie status, um eine Manipulation (MAC-Mismatch) von einem Konfigurationsproblem (fehlendes oder fehlerhaftes /AuthCode, Algorithmus-Mismatch) zu unterscheiden.

PKI-Pfadvalidierung (RFC 5280)

Diese decken die RFC-5280-Zertifizierungspfadvalidierung ab. Der Basistyp und seine Unterklassen sind fail-closed.

PkiPathValidationException

• Wann ausgelöst. Ein Strict-Modus-Fehler vom RFC-5280-Pfadvalidator. Es ist die nicht-finale Basis für schmalere Unterklassen (ChainLengthExceededException, UnsupportedExtensionException), sodass Handler, die diesen Typ abfangen, auch jene über Liskov-Substitution abfangen. Erweitert SecurityException.
• Kontextfelder. Überschreibt getContext() nicht (erbt die leere Voreinstellung). Trägt die strukturierten Gründe in der eingefrorenen öffentlichen readonly-Array- Eigenschaft $reasons (eine nicht leere Liste aus Regelname-plus-Beschreibung-Strings).
• Behebung. Lesen Sie $reasons, um die fehlschlagende Regel zu identifizieren, korrigieren Sie die Zertifikats- kette und validieren Sie erneut. Fangen Sie diesen Typ ab, um jeden Pfadvalidierungsfehler einheitlich zu behandeln.

ChainLengthExceededException

• Wann ausgelöst. Der Pfadvalidator wird gebeten, eine Kette zu durchlaufen, deren Länge die konfigurierte Obergrenze überschreitet. Die Kappung wird vor jedem Parsen erzwungen, sodass ein böswilliger Lieferant den Validator nicht in quadratische Arbeit treiben oder Ressourcen mit einer beliebig tiefen Kette erschöpfen kann. Die Standardobergrenze von 10 folgt dem PKIX-CMP-Profil (RFC 4210 §5.3.18); reale Ketten passen in 5 bis 6 Einträge. Unterklasse von PkiPathValidationException.
• Kontextfelder. Erbt das leere getContext(); der Grund-String chain_length_exceeded: supplied=<n> cap=<n> wird in die $reasons der übergeordneten Klasse weitergereicht. Öffentliche readonly-Eigenschaften: $supplied, $cap.
• Behebung. Liefern Sie eine Kette innerhalb der Obergrenze, oder erhöhen Sie die konfigurierte Kappung, wenn eine legitim längere Kette erwartet wird.

UnsupportedExtensionException

• Wann ausgelöst. Der Pfadvalidator stößt auf eine kritische X.509-Extension, deren Durchsetzung noch nicht implementiert ist. Gemäß RFC 5280 §4.2 muss eine unbekannte kritische Extension fail-closed scheitern; sowohl der Strict- als auch der Lenient-Modus scheitern hier fail-closed, da das stillschweigende Überspringen einer kritischen Extension eine Sicherheitsregression wäre. Der Validator deckt Kettenaufbau, AKI/SKI-Matching, Key Usage, Extended Key Usage, Basic Constraints, Ablauf und Signaturverifizierung ab; alles andere Kritische taucht hier auf. Unterklasse von PkiPathValidationException.
• Kontextfelder. Erbt das leere getContext(); strukturierte Gründe werden in die $reasons der übergeordneten Klasse weitergereicht. Öffentliche readonly-Eigenschaften: $extensionOid (gepunktete OID, zum Beispiel 2.5.29.30 für Name Constraints), $extensionName, $clauseRef (Verweis auf die RFC-5280-Klausel und den Deferred-Items-Log-Eintrag).
• Behebung. Im Lenient-Modus fangen Sie diese spezifische Unterklasse ab, um auf eine gröbere Policy zurückzufallen, ohne echte Pfadvalidierungsfehler zu verschlucken. Auditieren Sie $extensionOid und $clauseRef gegen Ihre PKI-Fixtures, um zu sehen, welche Extension die Validierung blockiert.

RevocationCheckFailedException

• Wann ausgelöst. Sowohl OCSP- als auch Certificate-Revocation-List-(CRL-)Endpunkte sind erschöpft, ohne ein eindeutiges Urteil: OCSP-Transportfehler oder fehlerhafte Antwort und CRL-Transportfehler oder fehlerhafte CRL, mit beiden offenen Circuit Breakern oder beiden fehlenden Caches. Der Strict-Modus behandelt dies als fail-closed; der Lenient-Modus fängt es ab und gibt eine PSR-3-Warnung mit revocation = null aus. Erweitert SecurityException.
• Kontextfelder. Überschreibt getContext() nicht (erbt die leere Voreinstellung). Trägt den Zustand in den öffentlichen readonly-Eigenschaften $ocspState und $crlState (jede standardmäßig unknown).
• Behebung. Stellen Sie die Erreichbarkeit einer Widerrufsquelle wieder her, warten Sie auf das Schließen der Circuit Breaker, oder wärmen Sie den Cache, und versuchen Sie es dann erneut. Unterdrücken Sie dies nicht, um ein Long-Term-Validation-Artefakt zu erhalten; die Widerrufsaussage ist Teil dieser Stufe.

OCSP-Signaturverifizierung (RFC 6960)

OcspSignatureInvalidException

• Wann ausgelöst. Eine RFC-6960-§4.2.2.2-BasicOCSPResponse-Signatur besteht die kryptografische Verifizierung gegen das Zertifikat des Responders nicht. Der Parser dekodiert signatureAlgorithm (RSA-PSS, ECDSA oder RSA-PKCS1v15) und verifiziert signature über tbsResponseData; jeder Fehlschlag löst diese typisierte Exception aus, sodass Aufrufer eine strukturell gültige, aber kryptografisch manipulierte Antwort von einer fehlerhaften-DER-Antwort unterscheiden können. Nicht-final, sodass nachgelagerte Pakete spezifischere Unterklassen veröffentlichen können. Erweitert SecurityException.
• Kontextfelder. Überschreibt getContext() nicht (erbt die leere Voreinstellung). Trägt das Fehler-Tag in der öffentlichen readonly-Eigenschaft $reason (zum Beispiel signature_mismatch, responder_cert_not_in_bundle, unsupported_signature_algorithm); Freitext-detail wird in die Meldung eingefaltet.
• Behebung. Inspizieren Sie $reason. Bei responder_cert_not_in_bundle liefern Sie das korrekte Trust-Anchor-Bundle und das Responder-Zertifikat. Bei signature_mismatch behandeln Sie die Antwort als nicht vertrauenswürdig. Siehe Signatur- und Zeitstempelfehler.

Zeitstempelung (RFC 3161)

TsaException

• Wann ausgelöst. Ein Fehler in der RFC-3161-Time-Stamp-Authority-(TSA-)Kommunikation oder der Antwortauswertung: Die TSA gibt einen Fehlerstatus zurück, die HTTP-Anfrage schlägt fehl, oder die ASN.1-Antwort kann nicht geparst werden. Es ist die Basis der TSA-Fehlerhierarchie und ist nicht-final, sodass Verifizierungsfehler es erweitern können. Erweitert NextPdfException.
• Kontextfelder. Überschreibt getContext() nicht (erbt die leere Voreinstellung).
• Behebung. Fangen Sie TsaException für jeden TSA-Fehlerpfad ab. Prüfen Sie die TSA- Erreichbarkeit und ob der Endpunkt eine wohlgeformte RFC-3161-Antwort zurückgibt.

TsaTokenVerificationException

• Wann ausgelöst. Die CMS-Verifizierung eines RFC-3161-TimeStampToken scheitert an einem der vorgeschriebenen Verifizierungsschritte: RFC 5816 §3 ESSCertIDv2-Bindung, RFC 5652 §11 Integrität der signierten Attribute, RFC 3161 §2.4.2 producedAt-Frische oder RFC 5652 §5.4 SignerInfo-Signatur. Fail-closed, mit einem typisierten Schritt- Diskriminator, sodass Audit-Pipelines Replay von Clock-Skew von Cert-Mismatch unterscheiden können, ohne Meldungen zu durchsuchen. Unterklasse von TsaException, sodass Legacy- catch (TsaException)-Handler weiterhin auslösen.
• Kontextfelder. step (der fehlschlagende Pipeline-Step-Wert) und message. Accessor: getStep().
• Behebung. Umsetzbar durch einen Entwickler (falsch konfiguriertes TSA-Zertifikat oder Skew- Toleranz) oder Security (vermuteter MITM oder Replay). Lesen Sie step, um die fehlschlagende Stufe zu lokalisieren, und korrigieren Sie die entsprechende Eingabe oder Trust-Konfiguration.

MalformedDerException

• Wann ausgelöst. Internes Signal, dass ein DER-Walk auf eine fehlerhafte oder abgeschnittene Grenze gestoßen ist, ausgelöst von den Low-Level-Walkern innerhalb des TSA-Token-Verifiers. Es wird immer an der öffentlichen Verify-Grenze abgefangen und in eine TsaTokenVerificationException mit dem passenden Schritt-Diskriminator umgewickelt; es entweicht niemals in Aufrufercode. Erweitert RuntimeException; als @internal markiert.
• Kontextfelder. Keine.
• Behebung. Nicht aufruferseitig. Behandeln Sie stattdessen die umgewickelte TsaTokenVerificationException.

Zertifikatserweiterungs-Dekodierung

Diese erweitern RuntimeException und legen kein getContext() offen. Beide sind fail-closed-Dekoder.

NameConstraintsDecodeException

• Wann ausgelöst. Der Name-Constraints-Dekoder stößt auf ein durchsetzbares GeneralSubtree-Element, das er nicht originalgetreu dekodieren kann. RFC 5280 §4.2.1.10 verlangt von einer Relying Party, eine durchsetzbare Namensbeschränkung zu verarbeiten oder das Zertifikat abzulehnen; die Umwandlung des vorherigen stillen Drops in diesen typisierten Fehler verhindert ein Fail-open, das die akzeptierte Namensmenge stillschweigend erweitert hätte. Der Geltungsbereich ist auf die durchsetzbaren Namensformen (directoryName, dNSName, iPAddress, rfc822Name, uniformResourceIdentifier) beschränkt; nicht durchsetzbare Formen bleiben ignorierbar und lösen es nie aus. Benannter Konstruktor: undecodableEnforceableBase(). Als @internal markiert.
• Kontextfelder. Keine. Ein log-sicherer Detail-String wird in der Meldung getragen.
• Behebung. Der Enforcer fördert einen fail-closed-name_constraints:-Grund zutage, und die Kette wird abgelehnt. Untersuchen Sie die Name-Constraints-Kodierung des Zertifikats; lockern Sie die Durchsetzung nicht.

QcStatementsDecodeException

• Wann ausgelöst. Die qcStatements-Extension ist strukturell fehlerhaft: abgeschnittenes DER, ein falsches Tag oder ein Length-Overflow. Der Dekoder ist fail-closed und löst aus, statt ein partielles oder heuristisches Ergebnis zurückzugeben, wenn er nicht mit Gewissheit bestimmen kann, was die Extension aussagt. Als @api markiert.
• Kontextfelder. Keine.
• Behebung. Fangen Sie es nur dann explizit ab, wenn Sie fehlerhafte Kodierung tolerieren wollen; behandeln Sie andernfalls die Qualified-Certificate-Statements des Zertifikats als unbestimmbar und lehnen Sie das Zertifikat ab oder stellen Sie es neu aus.

PKCS#11-Sitzungen

Pkcs11SessionException

• Wann ausgelöst. Ein PKCS#11-v3.1-Sitzungsverwaltungsdefekt. Jeder benannte Konstruktor wird einer bestimmten Defektklasse und einem PKCS#11-CKR_*-Rückgabe- wert zugeordnet, offengelegt über den typisierten $kind-Diskriminator, sodass Aufrufer auf einen stabilen Enum-String verzweigen statt auf brüchiges Message-Matching. Zu den Konstruktoren gehören: cryptokiNotInitialized(), userNotLoggedIn(), userAlreadyLoggedIn(), operationNotInitialized(), operationActive(), mechanismNotAllowed(), tokenDisconnected(), concurrentSessionLimitExceeded(), sessionAlreadyClosed(), stateTransitionInvalid(), osLockingRequired(), loginTtlExpired() und signOperationTtlExpired(). Erweitert SecurityException.
• Kontextfelder. Überschreibt getContext() nicht (erbt die leere Voreinstellung). Trägt den typisierten Kind in der öffentlichen readonly-Eigenschaft $kind, einer der KIND_*-Konstanten (zum Beispiel KIND_USER_NOT_LOGGED_IN, KIND_TOKEN_DISCONNECTED, KIND_LOGIN_TTL_EXPIRED). Slot- und Sitzungs- bezeichner, Mechanismus und TTL-Werte erscheinen in der Meldung. PINs und Zertifikatsbytes sind niemals enthalten.
• Behebung. Verzweigen Sie auf $kind. Bei user_not_logged_in melden Sie sich mit der Benutzer- PIN an, bevor Sie eine Signieroperation initialisieren. Bei token_disconnected behandeln Sie alle Sitzungen am Slot als verwaist. Bei den TTL-Kinds authentifizieren Sie sich erneut oder initialisieren Sie die Operation neu. Bei mechanism_not_allowed erweitern Sie die konfigurierte Mechanismus-Allow-List oder wählen Sie einen erlaubten Mechanismus.

Siehe auch

• Index der Fehlerreferenz
• Signatur- und Zeitstempelfehler
• Verschlüsselung und Berechtigungen
• PDF/A- und PDF/UA-Validierung