Rozwiązywanie problemów: błędy podpisu i znacznika czasu

Zakres

Te wpisy obejmują błędy podpisu zgłaszane przez NextPDF\Exception\SignatureException oraz NextPDF\Security\Signature\Exception\SignatureLevelUnreachableException. Każdy wpis wskazuje konkretną metodę fabryczną lub klasę, dzięki czemu przyczynę można potwierdzić na podstawie komunikatu i getContext(), zamiast ją zakładać.

Uwaga terminologiczna: silnik nie poświadcza, że podpis jest prawidłowy ani że dokument jest chroniony. Zgłasza błąd, który wykrył. Każde rozwiązanie traktuj jako krok prowadzący do usunięcia zgłoszonej przyczyny.

Wpis: nie można wygenerować poziomu PAdES „B-LT” ani „B-LTA”

• Objaw. SignatureException z końcówką komunikatu nextpdf/enterprise package is required for B-LT/B-LTA signatures.
• Prawdopodobna przyczyna. Brakuje dostawcy funkcji walidacji długoterminowej. B-LT i B-LTA osadzają materiał unieważnień oraz archiwalny znacznik czasu, a taki dostawca jest dostępny w nextpdf/enterprise.
• Dowody / diagnoza. Metoda fabryczna SignatureException::ltvCapabilityMissing() generuje dokładnie ten komunikat. getContext() zwraca signature_level ustawione na poziom, dla którego podjęto próbę.
• Rozwiązanie.
  1. Zainstaluj dostawcę, uruchamiając composer require nextpdf/enterprise.
  2. Ponownie wywołaj operację podpisywania.
  3. Jeśli nie możesz zainstalować dostawcy, zażądaj zamiast tego poziomu B-B lub B-T, który może wygenerować pakiet core.
• Powiązane. Dokumentacja wyjątków.

Wpis: poziom podpisu jest nieosiągalny i wywołanie zostaje odrzucone

• Objaw. SignatureLevelUnreachableException z komunikatem w postaci PAdES level "<x>" is unreachable (highest achievable: "<y>").
• Prawdopodobna przyczyna. Żądany poziom zgodności wymaga infrastruktury, która nie jest dostępna w momencie podpisywania, najczęściej urzędu znaczników czasu dla poziomu B-T i wyższych. Silnik działa w trybie fail-closed: nie obniża po cichu poziomu, aby potem deklarować wyższy.
• Dowody / diagnoza. getContext() zwraca requestedLevel, highestAchievableLevel oraz reason. Pole reason wskazuje brak w infrastrukturze. Jest to domyślne zachowanie fail-closed, wprowadzone po to, aby zapobiec powstaniu dokumentu deklarującego poziom, którego nie spełnia.
• Rozwiązanie.
  1. Odczytaj pole reason, aby zidentyfikować brakującą infrastrukturę.
  2. Dostarcz brakujący komponent. Na przykład skonfiguruj urząd znaczników czasu i ponownie wywołaj operację.
  3. Aby celowo zaakceptować niższy poziom, przekaż allowDegradation: true do PadesOrchestrator. Wywołanie generuje wówczas highestAchievableLevel i zgłasza poziom, który wygenerowało.
• Powiązane. Szyfrowanie i uprawnienia.

Wpis: klient urzędu znaczników czasu jest wymagany, ale go brakuje

• Objaw. SignatureException z końcówką TSA client is required for level <x> but none was provided.
• Prawdopodobna przyczyna. Żądanie poziomu B-T, B-LT lub B-LTA wymaga klienta urzędu znaczników czasu, a orkiestrator go nie otrzymał.
• Dowody / diagnoza. Metoda fabryczna SignatureException::tsaRequired() generuje ten komunikat; getContext() zawiera signature_level, którego dotyczyła próba.
• Rozwiązanie.
  1. Skonfiguruj klienta urzędu znaczników czasu i przekaż go do orkiestratora.
  2. Ponownie wywołaj operację.
  3. Aby wygenerować poziom, który nie wymaga znacznika czasu, zażądaj B-B.
• Powiązane. Dokumentacja wyjątków.

Wpis: adres URL punktu końcowego urzędu znaczników czasu jest pusty

• Objaw. SignatureException z końcówką TSA endpoint URL is empty.
• Prawdopodobna przyczyna. Klient urzędu znaczników czasu został utworzony z pustym adresem URL punktu końcowego.
• Dowody / diagnoza. Metoda fabryczna SignatureException::tsaUrlEmpty() generuje ten komunikat. Jest to wada konfiguracji, a nie awaria sieci.
• Rozwiązanie.
  1. Ustaw niepusty adres URL punktu końcowego w kliencie urzędu znaczników czasu, na przykład https://timestamp.example.com/tsa.
  2. Jeśli żądany poziom nie wymaga znacznika czasu, usuń zamiast tego podłączenie klienta urzędu znaczników czasu.
  3. Ponownie wywołaj operację.
• Powiązane. Dokumentacja wyjątków.

Wpis: w buforze brakuje symbolu zastępczego podpisu

• Objaw. SignatureException z końcówką no /Contents <…> field found in PDF buffer (signature placeholder missing).
• Prawdopodobna przyczyna. Etap podpisywania otrzymał bufor bez zarezerwowanego kontenera podpisu, więc nie ma miejsca, w którym można zapisać podpis.
• Dowody / diagnoza. Metoda fabryczna SignatureException::signatureContentsNotFound() generuje ten komunikat.
• Rozwiązanie.
  1. Upewnij się, że pole podpisu i jego symbol zastępczy są zapisane przed uruchomieniem etapu podpisywania.
  2. Ponownie uruchom potok, aby symbol zastępczy istniał w momencie rozpoczęcia podpisywania.
• Powiązane. Dokumentacja wyjątków.

Wpis: status unieważnienia jest nieznany (responder OCSP odmówił)

• Objaw. SignatureException z końcówką OCSP responder returned non-successful OCSPResponseStatus "<status>".
• Prawdopodobna przyczyna. Responder Online Certificate Status Protocol (OCSP) nie zwrócił statusu successful, więc nie wygenerował żadnego potwierdzenia unieważnienia. Silnik stosuje się do RFC 6960 §4.2.1, które cytuje w kodzie źródłowym: wypełniona treść odpowiedzi jest dozwolona wyłącznie dla statusu successful (0). Silnik odmawia traktowania odrzuconej odpowiedzi jako wyniku potwierdzającego zaufanie.
• Dowody / diagnoza. Metoda fabryczna SignatureException::nonSuccessfulOcspResponseStatus() generuje ten komunikat i podaje zgłoszony status, na przykład tryLater lub internalError. Zarezerwowany albo nieznany bajt statusu generuje natomiast SignatureException::reservedOcspResponseStatus().
• Rozwiązanie.
  1. Zidentyfikuj status w komunikacie. W przypadku statusu przejściowego, takiego jak tryLater, ponów pobranie unieważnienia później.
  2. W przypadku unauthorized lub malformedRequest zweryfikuj adres URL żądania OCSP oraz certyfikat, którego oczekuje responder.
  3. Nie wyciszaj błędu, aby uzyskać artefakt B-LT lub B-LTA; potwierdzenie unieważnienia jest częścią tego poziomu.
• Powiązane. Dokumentacja wyjątków.

Wpis: nie udaje się zdekodować wpisu łańcucha certyfikatów

• Objaw. SignatureException z końcówką failed to base64-decode PEM body — input is not valid PEM.
• Prawdopodobna przyczyna. Wpis łańcucha certyfikatów nie ma prawidłowego formatu Privacy-Enhanced Mail (PEM), zwykle z powodu obcięcia, błędnego znaku lub binarnego bloku Distinguished Encoding Rules (DER) dostarczonego tam, gdzie oczekiwano PEM.
• Dowody / diagnoza. Metoda fabryczna SignatureException::pemDecodingFailed() generuje ten komunikat podczas budowania łańcucha.
• Rozwiązanie.
  1. Sprawdź każdy certyfikat w łańcuchu pod kątem błędnych znaków lub obcięcia.
  2. Ponownie wyeksportuj w formacie PEM certyfikat, którego dotyczy problem.
  3. Ponownie wywołaj operację podpisywania.
• Powiązane. Szyfrowanie i uprawnienia.

Wpis: typ klucza prywatnego nie pasuje do algorytmu

• Objaw. SignatureException z końcówką expected private key of type "<x>" for the configured algorithm but got "<y>".
• Prawdopodobna przyczyna. Wczytany klucz prywatny nie pasuje do skonfigurowanego algorytmu podpisu, na przykład klucz Rivest-Shamir-Adleman (RSA) przy wybranym Elliptic Curve Digital Signature Algorithm (ECDSA).
• Dowody / diagnoza. Metoda fabryczna SignatureException::unexpectedKeyType() generuje ten komunikat i podaje zarówno oczekiwaną, jak i rzeczywistą klasę klucza.
• Rozwiązanie.
  1. Sprawdź, czy certyfikat i para kluczy pasują do wybranego algorytmu.
  2. Zmień algorytm tak, aby pasował do klucza, albo wczytaj klucz, który pasuje do algorytmu.
  3. Ponownie wywołaj operację podpisywania.
• Powiązane. Dokumentacja wyjątków.

Wpis: klucz lub materiał podpisu Ed25519 jest zniekształcony

• Objaw. SignatureException z końcówką wskazującą niezgodność długości Ed25519 — na przykład Ed25519 signature length <n> ≠ expected 64 bytes lub Ed25519 round-trip self-verify failed.
• Prawdopodobna przyczyna. Kompilacja biblioteki kryptograficznej w środowisku zwróciła klucz lub materiał podpisu o nieprawidłowej długości albo świeżo wygenerowany podpis nie przeszedł weryfikacji przy użyciu własnego klucza publicznego. Silnik cytuje w kodzie źródłowym RFC 8032 §3.4, które ustala długość odłączonego podpisu Ed25519 na 64 bajty. Silnik przerywa działanie zamiast zwracać materiał, którego nie może samodzielnie zweryfikować.
• Dowody / diagnoza. Odpowiednie metody fabryczne to SignatureException::ed25519SignatureMalformed(), ::ed25519RoundTripVerifyFailed(), ::ed25519KeyParseFailed(), ::ed25519SeedInvalid(), ::ed25519SecretKeyMalformed() oraz ::ed25519PublicKeyInvalid(). Każda z nich podaje zaobserwowaną długość.
• Rozwiązanie.
  1. Zainstaluj ponownie rozszerzenie PHP libsodium; okrojona lub uszkodzona kompilacja jest udokumentowaną przyczyną materiału o nieprawidłowej długości.
  2. Potwierdź, że klucz jest kluczem Ed25519, a OpenSSL ma wersję 1.1.1 lub nowszą.
  3. Ponownie wywołaj operację podpisywania.
• Powiązane. Dokumentacja wyjątków.

Wpis: słownik archiwalnego znacznika czasu nie został wyemitowany

• Objaw. SignatureException z końcówką no /Type /DocTimeStamp dictionary was emitted into the PDF buffer.
• Prawdopodobna przyczyna. Pętla archiwizacji B-LTA wykonała się, ale słownik znacznika czasu dokumentu nigdy nie trafił do bufora. Artefakt byłby niedokończonym B-LTA, więc silnik odmawia jego zwrócenia.
• Dowody / diagnoza. Metoda fabryczna SignatureException::documentTimestampNotEmitted() generuje ten komunikat. Ten błąd warunku końcowego jest zgłaszany na etapie finalizacji.
• Rozwiązanie.
  1. Potraktuj wynik jako odrzucony; nie wysyłaj częściowego artefaktu.
  2. Ponownie uruchom potok B-LTA z osiągalnym urzędem znaczników czasu.
  3. Jeśli błąd się powtarza, dołącz getContext() oraz powiązany poprzedni wyjątek do zgłoszenia usterki.
• Powiązane. Dokumentacja wyjątków.

Przypadki brzegowe i pułapki

• Te metody fabryczne ustawiają cert_info na podmiot lub odcisk palca tylko wtedy, gdy taka informacja jest dostępna; puste cert_info jest oczekiwane w przypadku błędów funkcji i konfiguracji.
• Żądanie poziomu B-LT lub B-LTA bez skonfigurowanego klienta Hypertext Transfer Protocol (HTTP) zgłasza SignatureException::httpClientMissing(); pobranie unieważnienia wymaga przekazania orkiestratorowi klienta PHP Standards Recommendation (PSR)-18.
• Certyfikat oparty na sprzętowym module bezpieczeństwa (HSM) bez zaimplementowanego obiektu podpisującego zgłasza SignatureException::hsmSignerMissing(); podłącz obiekt podpisujący do certyfikatu przed podpisaniem.

Zobacz też

• Dokumentacja wyjątków
• Szyfrowanie i uprawnienia
• Indeks bazy wiedzy

Słownik: poziom PAdES · potwierdzenie unieważnienia