Fehlerbehebung: Signatur- und Zeitstempelfehler

Geltungsbereich

Diese Einträge decken Signaturfehler ab, die die Engine über NextPDF\Exception\SignatureException und NextPDF\Security\Signature\Exception\SignatureLevelUnreachableException auslöst. Jeder Eintrag nennt die genaue Factory-Methode oder Klasse, damit Sie die Ursache anhand der Meldung und von getContext() bestätigen können, statt sie erraten zu müssen.

Ein Hinweis zur Formulierung: Die Engine bestätigt nicht, dass eine Signatur gültig oder ein Dokument geschützt ist. Sie meldet den Fehler, den sie erkannt hat. Behandeln Sie jede Lösung als Schritt, um eine gemeldete Ursache zu beseitigen.

Eintrag: PAdES-Stufe „B-LT“ oder „B-LTA“ kann nicht erzeugt werden

• Symptom. SignatureException mit dem Meldungsende nextpdf/enterprise package is required for B-LT/B-LTA signatures.
• Wahrscheinliche Ursache. Der Capability-Provider für die Langzeitvalidierung fehlt. B-LT und B-LTA betten Widerrufsmaterial und einen Archiv-Zeitstempel ein; dieser Provider wird mit nextpdf/enterprise ausgeliefert.
• Nachweis / Diagnose. Die Factory SignatureException::ltvCapabilityMissing() erzeugt genau diese Meldung. getContext() liefert signature_level mit der von Ihnen angeforderten Stufe.
• Lösung.
  1. Installieren Sie den Provider: Führen Sie composer require nextpdf/enterprise aus.
  2. Führen Sie den Signieraufruf erneut aus.
  3. Wenn Sie den Provider nicht installieren können, fordern Sie stattdessen B-B oder B-T an; diese Stufen kann das Core-Paket erzeugen.
• Verwandt. Exception-Referenz.

Eintrag: Signaturstufe ist unerreichbar und der Aufruf wird abgelehnt

• Symptom. SignatureLevelUnreachableException mit einer Meldung der Form PAdES level "<x>" is unreachable (highest achievable: "<y>").
• Wahrscheinliche Ursache. Die angeforderte Konformitätsstufe benötigt Infrastruktur, die zum Signierzeitpunkt nicht verfügbar ist — meist eine Zeitstempelstelle für B-T und höher. Die Engine verhält sich fail-closed: Sie stuft nicht stillschweigend herab und weist anschließend die höhere Stufe aus.
• Nachweis / Diagnose. getContext() liefert requestedLevel, highestAchievableLevel und reason. Das Feld reason benennt die Infrastrukturlücke. Dies ist die Fail-closed-Voreinstellung, die verhindern soll, dass ein Dokument eine Stufe behauptet, die es nicht erfüllt.
• Lösung.
  1. Lesen Sie das Feld reason, um die fehlende Infrastruktur zu identifizieren.
  2. Stellen Sie die fehlende Komponente bereit — richten Sie zum Beispiel eine Zeitstempelstelle ein — und führen Sie den Aufruf erneut aus.
  3. Um absichtlich eine niedrigere Stufe zu akzeptieren, übergeben Sie allowDegradation: true an PadesOrchestrator. Der Aufruf erzeugt dann highestAchievableLevel und meldet die tatsächlich erzeugte Stufe.
• Verwandt. Verschlüsselung und Berechtigungen.

Eintrag: Zeitstempelstellen-Client wird benötigt, fehlt aber

• Symptom. SignatureException mit dem Ende TSA client is required for level <x> but none was provided.
• Wahrscheinliche Ursache. Eine Anforderung für B-T, B-LT oder B-LTA benötigt einen Zeitstempelstellen-Client; es wurde jedoch keiner in den Orchestrator eingebunden.
• Nachweis / Diagnose. Die Factory SignatureException::tsaRequired() erzeugt diese Meldung; getContext() trägt die angeforderte signature_level.
• Lösung.
  1. Richten Sie einen Zeitstempelstellen-Client ein und übergeben Sie ihn an den Orchestrator.
  2. Führen Sie den Aufruf erneut aus.
  3. Um eine Stufe zu erzeugen, die keinen Zeitstempel benötigt, fordern Sie B-B an.
• Verwandt. Exception-Referenz.

Eintrag: Endpunkt-URL der Zeitstempelstelle ist leer

• Symptom. SignatureException mit dem Ende TSA endpoint URL is empty.
• Wahrscheinliche Ursache. Ein Zeitstempelstellen-Client wurde mit einer leeren Endpunkt-URL konstruiert.
• Nachweis / Diagnose. Die Factory SignatureException::tsaUrlEmpty() erzeugt diese Meldung. Dies ist ein Konfigurationsfehler, kein Netzwerkfehler.
• Lösung.
  1. Setzen Sie am Zeitstempelstellen-Client eine nicht leere Endpunkt-URL, zum Beispiel https://timestamp.example.com/tsa.
  2. Wenn für die angeforderte Stufe kein Zeitstempel erforderlich ist, entfernen Sie stattdessen die Einbindung des Zeitstempelstellen-Clients.
  3. Führen Sie den Aufruf erneut aus.
• Verwandt. Exception-Referenz.

Eintrag: Signatur-Platzhalter fehlt im Puffer

• Symptom. SignatureException mit dem Ende no /Contents <…> field found in PDF buffer (signature placeholder missing).
• Wahrscheinliche Ursache. Die Signierstufe wurde auf einem Puffer ausgeführt, der keinen reservierten Signaturcontainer hat, sodass es keine Stelle gibt, an die die Signatur geschrieben werden kann.
• Nachweis / Diagnose. Die Factory SignatureException::signatureContentsNotFound() erzeugt diese Meldung.
• Lösung.
  1. Stellen Sie sicher, dass das Signaturfeld und sein Platzhalter geschrieben werden, bevor die Signierstufe läuft.
  2. Führen Sie die Pipeline erneut aus, damit der Platzhalter existiert, wenn das Signieren beginnt.
• Verwandt. Exception-Referenz.

Eintrag: Widerrufsstatus ist unbekannt (OCSP-Responder hat abgelehnt)

• Symptom. SignatureException mit dem Ende OCSP responder returned non-successful OCSPResponseStatus "<status>".
• Wahrscheinliche Ursache. Der OCSP-Responder hat keinen Status successful zurückgegeben und daher keine Widerrufsaussage erzeugt. Die Engine folgt RFC 6960 §4.2.1, der im Quellcode zitiert wird: Ein gefüllter Antwortkörper ist nur für den Status successful (0) erlaubt. Die Engine weigert sich, eine abgelehnte Antwort als positives Ergebnis für die Vertrauensentscheidung zu behandeln.
• Nachweis / Diagnose. Die Factory SignatureException::nonSuccessfulOcspResponseStatus() erzeugt diese Meldung und benennt den gemeldeten Status, zum Beispiel tryLater oder internalError. Ein reserviertes oder unbekanntes Statusbyte erzeugt stattdessen SignatureException::reservedOcspResponseStatus().
• Lösung.
  1. Identifizieren Sie den Status in der Meldung. Bei einem vorübergehenden Status wie tryLater wiederholen Sie den Widerrufsabruf später.
  2. Bei unauthorized oder malformedRequest prüfen Sie die OCSP-Anfrage-URL und das Zertifikat, das der Responder erwartet.
  3. Unterdrücken Sie das Fehlschlagen nicht, um ein B-LT- oder B-LTA-Artefakt zu erhalten; die Widerrufsaussage ist Teil dieser Stufe.
• Verwandt. Exception-Referenz.

Eintrag: Eintrag der Zertifikatskette kann nicht dekodiert werden

• Symptom. SignatureException mit dem Ende failed to base64-decode PEM body — input is not valid PEM.
• Wahrscheinliche Ursache. Ein Eintrag der Zertifikatskette ist kein gültiges PEM — typischerweise wegen einer Kürzung, eines fremden Zeichens oder eines binären DER-Blobs, der dort übergeben wurde, wo PEM erwartet wurde.
• Nachweis / Diagnose. Die Factory SignatureException::pemDecodingFailed() erzeugt diese Meldung während des Kettenaufbaus.
• Lösung.
  1. Prüfen Sie jedes Kettenzertifikat auf fremde Zeichen oder Kürzungen.
  2. Exportieren Sie das betroffene Zertifikat erneut in PEM-Form.
  3. Führen Sie den Signieraufruf erneut aus.
• Verwandt. Verschlüsselung und Berechtigungen.

Eintrag: Typ des privaten Schlüssels passt nicht zum Algorithmus

• Symptom. SignatureException mit dem Ende expected private key of type "<x>" for the configured algorithm but got "<y>".
• Wahrscheinliche Ursache. Der geladene private Schlüssel passt nicht zum konfigurierten Signaturalgorithmus — zum Beispiel ein RSA-Schlüssel bei einer ECDSA-Auswahl.
• Nachweis / Diagnose. Die Factory SignatureException::unexpectedKeyType() erzeugt diese Meldung und benennt sowohl die erwartete als auch die tatsächliche Schlüsselklasse.
• Lösung.
  1. Prüfen Sie, ob Zertifikat und Schlüsselpaar zu dem von Ihnen gewählten Algorithmus passen.
  2. Ändern Sie entweder die Algorithmuswahl, damit sie zum Schlüssel passt, oder laden Sie den Schlüssel, der zum Algorithmus passt.
  3. Führen Sie den Signieraufruf erneut aus.
• Verwandt. Exception-Referenz.

Eintrag: Ed25519-Schlüssel oder -Signaturmaterial ist fehlerhaft

• Symptom. SignatureException mit einem Ende, das eine Ed25519-Längenabweichung nennt — zum Beispiel Ed25519 signature length <n> ≠ expected 64 bytes, oder Ed25519 round-trip self-verify failed.
• Wahrscheinliche Ursache. Der Kryptografie-Build der Laufzeitumgebung hat Schlüssel- oder Signaturmaterial mit falscher Länge zurückgegeben, oder eine frisch erzeugte Signatur ließ sich nicht gegen ihren eigenen öffentlichen Schlüssel verifizieren. Die Engine zitiert RFC 8032 §3.4 im Quellcode, der für eine separate Ed25519-Signatur 64 Byte festlegt. Die Engine bricht ab, anstatt Material auszugeben, das sie nicht selbst verifizieren kann.
• Nachweis / Diagnose. Die relevanten Factorys sind SignatureException::ed25519SignatureMalformed(), ::ed25519RoundTripVerifyFailed(), ::ed25519KeyParseFailed(), ::ed25519SeedInvalid(), ::ed25519SecretKeyMalformed() und ::ed25519PublicKeyInvalid(). Jede davon nennt die beobachtete Länge.
• Lösung.
  1. Installieren Sie die libsodium-PHP-Erweiterung neu; ein gestrippter oder beschädigter Build ist die dokumentierte Ursache für Material mit falscher Länge.
  2. Bestätigen Sie, dass der Schlüssel ein Ed25519-Schlüssel ist und OpenSSL 1.1.1 oder neuer ist.
  3. Führen Sie den Signieraufruf erneut aus.
• Verwandt. Exception-Referenz.

Eintrag: Archiv-Zeitstempel-Dictionary wurde nicht ausgegeben

• Symptom. SignatureException mit dem Ende no /Type /DocTimeStamp dictionary was emitted into the PDF buffer.
• Wahrscheinliche Ursache. Die B-LTA-Archivschleife wurde ausgeführt, aber das Dokumentzeitstempel-Dictionary wurde nie in den Puffer geschrieben, sodass das Artefakt ein nur teilweise geschriebenes B-LTA wäre. Die Engine weigert sich, es zurückzugeben.
• Nachweis / Diagnose. Die Factory SignatureException::documentTimestampNotEmitted() erzeugt diese Meldung. Es ist ein Nachbedingungsfehler, der bei der Finalisierung ausgelöst wird.
• Lösung.
  1. Behandeln Sie die Ausgabe als verworfen; liefern Sie das partielle Artefakt nicht aus.
  2. Führen Sie die B-LTA-Pipeline mit einer erreichbaren Zeitstempelstelle erneut aus.
  3. Wenn der Fehler erneut auftritt, erfassen Sie getContext() und die verkettete vorherige Exception für einen Fehlerbericht.
• Verwandt. Exception-Referenz.

Randfälle & Fallstricke

• Diese Factorys setzen cert_info nur dann auf ein Subject oder einen Thumbprint, wenn diese Information verfügbar ist; ein leeres cert_info ist bei Capability- und Konfigurationsfehlern zu erwarten.
• Eine B-LT- oder B-LTA-Anforderung ohne konfigurierten HTTP-Client löst SignatureException::httpClientMissing() aus — der Widerrufsabruf benötigt einen PSR-18-Client, der an den Orchestrator übergeben wird.
• Ein HSM-gestütztes Zertifikat ohne Signer-Implementierung löst SignatureException::hsmSignerMissing() aus; binden Sie den Signer an das Zertifikat, bevor Sie signieren.

Siehe auch

• Exception-Referenz
• Verschlüsselung und Berechtigungen
• Index der Wissensdatenbank

Glossar: PAdES-Stufe · Widerrufsaussage