Problemen oplossen: handtekening- en tijdstempelfouten

Toepassingsgebied

Deze vermeldingen behandelen handtekeningfouten die worden opgeworpen via NextPDF\Exception\SignatureException en NextPDF\Security\Signature\Exception\SignatureLevelUnreachableException. Elke vermelding noemt de exacte factorymethode of klasse, zodat u de oorzaak op basis van het bericht en getContext() kunt bevestigen in plaats van afleiden.

Opmerking over formulering: de engine certificeert niet dat een handtekening geldig is of dat een document beschermd is. Hij rapporteert de fout die hij heeft gedetecteerd. Behandel elke oplossing als een stap om de gerapporteerde oorzaak weg te nemen.

Vermelding: PAdES-niveau “B-LT” of “B-LTA” kan niet worden geproduceerd

• Symptoom. SignatureException met een bericht dat eindigt op nextpdf/enterprise package is required for B-LT/B-LTA signatures.
• Waarschijnlijke oorzaak. De provider voor langetermijnvalidatie ontbreekt. B-LT en B-LTA bevatten intrekkingsmateriaal en een archiveringstijdstempel, en die provider wordt geleverd in nextpdf/enterprise.
• Bewijs / diagnose. De factorymethode SignatureException::ltvCapabilityMissing() produceert precies dit bericht. getContext() retourneert signature_level met het niveau dat u hebt geprobeerd.
• Oplossing.
  1. Installeer de provider door composer require nextpdf/enterprise uit te voeren.
  2. Voer de ondertekenaanroep opnieuw uit.
  3. Als u de provider niet kunt installeren, vraag dan in plaats daarvan B-B of B-T aan; die kan het core-pakket wel produceren.
• Gerelateerd. Exceptiereferentie.

Vermelding: handtekeningniveau is onbereikbaar en de aanroep wordt afgewezen

• Symptoom. SignatureLevelUnreachableException met een bericht in de vorm PAdES level "<x>" is unreachable (highest achievable: "<y>").
• Waarschijnlijke oorzaak. Het gevraagde conformiteitsniveau vereist infrastructuur die op het moment van ondertekenen niet beschikbaar is, meestal een tijdstempelautoriteit voor B-T en hoger. De engine faalt veilig (fail closed): hij degradeert niet stilzwijgend en adverteert daarna geen hoger niveau.
• Bewijs / diagnose. getContext() retourneert requestedLevel, highestAchievableLevel en reason. Het veld reason benoemt de ontbrekende infrastructuur. Dit is de standaardinstelling voor fail-closed gedrag, geïntroduceerd om te voorkomen dat een document een niveau claimt waaraan het niet voldoet.
• Oplossing.
  1. Lees het veld reason om de ontbrekende infrastructuur te identificeren.
  2. Lever de ontbrekende component. Configureer bijvoorbeeld een tijdstempelautoriteit en voer de aanroep opnieuw uit.
  3. Om bewust een lager niveau te accepteren, geeft u allowDegradation: true door aan PadesOrchestrator. De aanroep produceert dan highestAchievableLevel en rapporteert welk niveau is geproduceerd.
• Gerelateerd. Versleuteling en machtigingen.

Vermelding: de client voor de tijdstempelautoriteit is vereist maar ontbreekt

• Symptoom. SignatureException met een bericht dat eindigt op TSA client is required for level <x> but none was provided.
• Waarschijnlijke oorzaak. Een aanvraag voor B-T, B-LT of B-LTA heeft een client voor een tijdstempelautoriteit nodig, maar de orchestrator heeft er geen.
• Bewijs / diagnose. De factorymethode SignatureException::tsaRequired() produceert dit bericht; getContext() bevat het geprobeerde signature_level.
• Oplossing.
  1. Configureer een client voor een tijdstempelautoriteit en geef deze door aan de orchestrator.
  2. Voer de aanroep opnieuw uit.
  3. Om een niveau te produceren dat geen tijdstempel nodig heeft, vraagt u B-B aan.
• Gerelateerd. Exceptiereferentie.

Vermelding: de endpoint-URL van de tijdstempelautoriteit is leeg

• Symptoom. SignatureException met een bericht dat eindigt op TSA endpoint URL is empty.
• Waarschijnlijke oorzaak. Een client voor een tijdstempelautoriteit is gemaakt met een lege endpoint-URL.
• Bewijs / diagnose. De factorymethode SignatureException::tsaUrlEmpty() produceert dit bericht. Dit is een configuratiefout, geen netwerkstoring.
• Oplossing.
  1. Stel een niet-lege endpoint-URL in op de client voor de tijdstempelautoriteit, zoals https://timestamp.example.com/tsa.
  2. Als het gevraagde niveau geen tijdstempeling vereist, verwijder dan in plaats daarvan de koppeling met de client voor de tijdstempelautoriteit.
  3. Voer de aanroep opnieuw uit.
• Gerelateerd. Exceptiereferentie.

Vermelding: de handtekening-placeholder ontbreekt in de buffer

• Symptoom. SignatureException met een bericht dat eindigt op no /Contents <…> field found in PDF buffer (signature placeholder missing).
• Waarschijnlijke oorzaak. De ondertekenfase ontving een buffer zonder gereserveerde handtekeningcontainer, waardoor er geen plek is om de handtekening te schrijven.
• Bewijs / diagnose. De factorymethode SignatureException::signatureContentsNotFound() produceert dit bericht.
• Oplossing.
  1. Zorg ervoor dat het handtekeningveld en de bijbehorende placeholder worden geschreven voordat de ondertekenfase wordt uitgevoerd.
  2. Voer de pijplijn opnieuw uit zodat de placeholder bestaat wanneer het ondertekenen begint.
• Gerelateerd. Exceptiereferentie.

Vermelding: intrekkingsstatus is onbekend (OCSP-responder weigerde)

• Symptoom. SignatureException met een bericht dat eindigt op OCSP responder returned non-successful OCSPResponseStatus "<status>".
• Waarschijnlijke oorzaak. De Online Certificate Status Protocol (OCSP)-responder retourneerde geen successful-status en produceerde dus geen intrekkingsbewering. De engine volgt RFC 6960 §4.2.1, die hij in de broncode citeert: een gevulde response-body is alleen toegestaan voor de status successful (0). De engine weigert een geweigerde response als positief vertrouwensresultaat te behandelen.
• Bewijs / diagnose. De factorymethode SignatureException::nonSuccessfulOcspResponseStatus() produceert dit bericht en noemt de gerapporteerde status, zoals tryLater of internalError. Een gereserveerde of onbekende statusbyte produceert in plaats daarvan SignatureException::reservedOcspResponseStatus().
• Oplossing.
  1. Identificeer de status in het bericht. Bij een tijdelijke status zoals tryLater kunt u het ophalen van de intrekking later opnieuw proberen.
  2. Verifieer voor unauthorized of malformedRequest de OCSP-aanvraag-URL en het certificaat dat de responder verwacht.
  3. Onderdruk de fout niet om een B-LT- of B-LTA-artefact te verkrijgen; de intrekkingsbewering maakt deel uit van dat niveau.
• Gerelateerd. Exceptiereferentie.

Vermelding: een vermelding in de certificaatketen kan niet worden gedecodeerd

• Symptoom. SignatureException met een bericht dat eindigt op failed to base64-decode PEM body — input is not valid PEM.
• Waarschijnlijke oorzaak. Een vermelding in de certificaatketen is geen geldige Privacy-Enhanced Mail (PEM), meestal door afkapping, een verdwaald teken of een binaire Distinguished Encoding Rules (DER)-blob die is aangeleverd waar PEM werd verwacht.
• Bewijs / diagnose. De factorymethode SignatureException::pemDecodingFailed() produceert dit bericht tijdens het samenstellen van de keten.
• Oplossing.
  1. Inspecteer elk certificaat in de keten op verdwaalde tekens of afkapping.
  2. Exporteer het betreffende certificaat opnieuw in PEM-indeling.
  3. Voer de ondertekenaanroep opnieuw uit.
• Gerelateerd. Versleuteling en machtigingen.

Vermelding: het type privésleutel komt niet overeen met het algoritme

• Symptoom. SignatureException met een bericht dat eindigt op expected private key of type "<x>" for the configured algorithm but got "<y>".
• Waarschijnlijke oorzaak. De geladen privésleutel komt niet overeen met het geconfigureerde handtekeningalgoritme, bijvoorbeeld wanneer een Rivest-Shamir-Adleman (RSA)-sleutel wordt gebruikt terwijl Elliptic Curve Digital Signature Algorithm (ECDSA) is geselecteerd.
• Bewijs / diagnose. De factorymethode SignatureException::unexpectedKeyType() produceert dit bericht en noemt zowel de verwachte als de werkelijke sleutelklasse.
• Oplossing.
  1. Verifieer dat het certificaat en het sleutelpaar overeenkomen met het algoritme dat u hebt geselecteerd.
  2. Wijzig de algoritmekeuze zodat deze overeenkomt met de sleutel, of laad de sleutel die overeenkomt met het algoritme.
  3. Voer de ondertekenaanroep opnieuw uit.
• Gerelateerd. Exceptiereferentie.

Vermelding: Ed25519-sleutel- of handtekeningmateriaal is misvormd

• Symptoom. SignatureException met een staart die een Ed25519-lengtemismatch noemt — bijvoorbeeld Ed25519 signature length <n> ≠ expected 64 bytes, of Ed25519 round-trip self-verify failed.
• Waarschijnlijke oorzaak. De cryptografie-build van de runtime retourneerde sleutel- of handtekeningmateriaal met de verkeerde lengte, of een zojuist geproduceerde handtekening werd niet geverifieerd tegen zijn eigen openbare sleutel. De engine citeert RFC 8032 §3.4 in de broncode, die een losgekoppelde Ed25519-handtekening vastlegt op 64 bytes. De engine breekt af in plaats van materiaal uit te zenden dat hij niet zelf kan verifiëren.
• Bewijs / diagnose. De relevante factorymethodes zijn SignatureException::ed25519SignatureMalformed(), ::ed25519RoundTripVerifyFailed(), ::ed25519KeyParseFailed(), ::ed25519SeedInvalid(), ::ed25519SecretKeyMalformed() en ::ed25519PublicKeyInvalid(). Elk noemt de waargenomen lengte.
• Oplossing.
  1. Installeer de libsodium PHP-extensie opnieuw; een uitgestripte of beschadigde build is de gedocumenteerde oorzaak van materiaal met de verkeerde lengte.
  2. Bevestig dat de sleutel een Ed25519-sleutel is en dat OpenSSL versie 1.1.1 of nieuwer is.
  3. Voer de ondertekenaanroep opnieuw uit.
• Gerelateerd. Exceptiereferentie.

Vermelding: de archiveringstijdstempel-dictionary is niet uitgeschreven

• Symptoom. SignatureException met een bericht dat eindigt op no /Type /DocTimeStamp dictionary was emitted into the PDF buffer.
• Waarschijnlijke oorzaak. De B-LTA-archiveringslus liep, maar de documenttijdstempel-dictionary bereikte de buffer nooit. Het artefact zou een deels geschreven B-LTA zijn, dus de engine weigert het te retourneren.
• Bewijs / diagnose. De factorymethode SignatureException::documentTimestampNotEmitted() produceert dit bericht. Deze postconditiefout wordt opgeworpen tijdens het finaliseren.
• Oplossing.
  1. Behandel de uitvoer als verworpen; lever het gedeeltelijke artefact niet uit.
  2. Voer de B-LTA-pijplijn opnieuw uit met een bereikbare tijdstempelautoriteit.
  3. Als de fout zich blijft voordoen, leg dan getContext() en de gekoppelde vorige exceptie vast voor een defectrapport.
• Gerelateerd. Exceptiereferentie.

Randgevallen en valkuilen

• Deze factorymethodes stellen cert_info alleen in op een onderwerp of vingerafdruk wanneer die beschikbaar is; een leeg cert_info is te verwachten bij mogelijkheid- en configuratiefouten.
• Een aanvraag voor B-LT of B-LTA zonder een geconfigureerde Hypertext Transfer Protocol (HTTP)-client werpt SignatureException::httpClientMissing() op; voor het ophalen van de intrekking is een PHP Standards Recommendation (PSR)-18-client nodig die aan de orchestrator wordt doorgegeven.
• Een certificaat dat wordt ondersteund door een hardware security module (HSM) zonder ondertekenaarimplementatie werpt SignatureException::hsmSignerMissing() op; koppel de ondertekenaar aan het certificaat vóór het ondertekenen.

Zie ook

• Exceptiereferentie
• Versleuteling en machtigingen
• Kennisbankindex

Woordenlijst: PAdES-niveau · intrekkingsbewering