Błędy bezpieczeństwa i podpisywania

W skrócie

Ta strona dokumentuje wyjątki domeny bezpieczeństwa w drzewie przestrzeni nazw NextPDF\Security. Każdy wpis podaje klasę, mówi, kiedy jest zgłaszana, wymienia pola zwracane przez jej getContext() oraz podaje krok naprawczy.

Większość tych klas rozszerza SecurityException, który rozszerza NextPdfException i implementuje ContextAwareExceptionInterface. Oznacza to, że getContext(): array zwraca ustrukturyzowaną, wolną od sekretów diagnostykę, którą można kierować do logowania lub do potoków monitorowania wydajności aplikacji (APM). Przechwyć SecurityException, aby ująć każdą awarię domeny bezpieczeństwa w jednym bloku; przechwyć konkretną podklasę, gdy potrzebujesz jej typowanego ładunku.

Kilka klas w tym drzewie rozszerza RuntimeException bezpośrednio, a nie SecurityException. Są one oznaczone poniżej; nie udostępniają getContext(), a większość jest udokumentowana jako wewnętrzne sygnały sterowania przepływem, których nie należy spodziewać się przechwytywać w kodzie aplikacji.

Konwencja pól kontekstu

Aspekt	Zachowanie
Kontrakt bazowy	NextPdfException::getContext() zwraca []; podklasy go nadpisują.
Higiena sekretów	Komunikaty i kontekst pomijają surowy materiał klucza, tekst jawny, kody PIN oraz bajty wektora inicjującego (IV). Klucze są ujawniane wyłącznie jako prefiks odcisku palca.
SecurityException	Baza abstrakcyjna; nie niesie własnych pól. Podklasy definiują ładunek.

Typ bazowy

SecurityException

• Kiedy zgłaszany. Nigdy nie zgłaszany bezpośrednio; to baza abstrakcyjna dla domeny bezpieczeństwa. Istnieje po to, by jeden blok catch (SecurityException $e) mógł ująć awarie integralności szyfrowania uwierzytelnionego, obronę przed ponownym użyciem wartości jednorazowej (nonce), powiązanie PDF/A-z-szyfrowaniem, błędy zarządzania kluczami oraz awarie PKI.
• Pola kontekstu. Żadnych własnych. Dziedziczy pustą wartość domyślną z NextPdfException; podklasy wypełniają ładunek.
• Naprawa. Przechwyć konkretną podklasę do możliwej do obsłużenia obsługi albo SecurityException do zgrubnego kierowania incydentów bezpieczeństwa.

Błędy szyfrowania i szyfrowania uwierzytelnionego

Są zgłaszane przez szyfrator AES-GCM (Galois/Counter Mode) oraz strażnika PDF/A. Aby uzyskać wskazówki zaczynające się od objawu, zobacz Szyfrowanie i uprawnienia.

DecryptionFailedException

• Kiedy zgłaszany. Odszyfrowywanie z szyfrowaniem uwierzytelnionym z powiązanymi danymi (AEAD) nie powiedzie się z przyczyny niezwiązanej z manipulacją: obcięty szyfrogram, brakujący IV albo nieprawidłowy klucz przekazany na granicy API, gdzie nie było wystarczająco dużo materiału, aby kontrola integralności mogła faktycznie zostać wykonana. To błąd konfiguracji lub transportu, a nie incydent bezpieczeństwa.
• Pola kontekstu. algorithm (na przykład AES-256-GCM), reason (na przykład ciphertext shorter than IV+tag).
• Naprawa. Zweryfikuj, że szyfrogram, IV i klucz są kompletne i poprawnie ujęte w ramki; nie traktuj tego jako manipulacji. Porównaj z TamperedDataException.

TamperedDataException

• Kiedy zgłaszany. Znacznik uwierzytelniający AEAD nie przechodzi weryfikacji. Znacznik obejmuje szyfrogram oraz powiązane uwierzytelnione dane (AAD); jeśli którekolwiek zostały zmodyfikowane po zaszyfrowaniu, bazowe openssl_decrypt() zwraca false. Ten odrębny podtyp pozwala ujawnić alarm o randze incydentu bezpieczeństwa, a nie błąd tworzenia ramki.
• Pola kontekstu. algorithm, ciphertext_length (długość odrzuconego szyfrogramu, z wyłączeniem IV i znacznika).
• Naprawa. Potraktuj jako manipulację lub nieprawidłowy klucz/IV. Nie ponawiaj na ślepo; zbadaj źródło szyfrogramu. Zgodnie z ISO/TS 32003:2023 §5.2 oraz NIST SP 800-38D §6.5 nieudana kontrola znacznika oznacza, że dane nie są autentyczne.

NonceReuseException

• Kiedy zgłaszany. AES-GCM zostaje poproszony o dwukrotne szyfrowanie tą samą parą klucza i IV. Szyfrator broni się licznikiem monotonicznym na instancję oraz, jako obrona w głąb, zbiorem haszującym (hash-set) w czasie wykonania każdej wyemitowanej pary (odcisk palca klucza, IV). Ponieważ licznik konstrukcyjnie wyklucza kolizje, to wystąpienie jest wskaźnikiem błędu o priorytecie krytycznym, który nigdy nie powinien wystąpić w produkcji. Ponowne użycie pary klucz/IV kompromituje cały strumień klucza (ISO/TS 32003:2023 §5.2 NOTE 2; NIST SP 800-38D §8.3).
• Pola kontekstu. key_fingerprint_prefix (pierwsze 8 znaków szesnastkowych SHA-256(klucz)), iv_length (zawsze 12 dla ISO/TS 32003), reason (hashset-collision lub counter-rollover, odróżniający błąd refaktoryzacji unieważniający licznik od progu zadziałania licznika 2^63) oraz iv_fixed_field_hex (pole stałe IV, obecne tylko gdy dostarczone, raportowane pod własnym kluczem i nigdy błędnie oznaczone jako odcisk palca klucza).
• Naprawa. Natychmiast przerwij i wymień klucz. Zgłoś raport o usterce; oznacza to błąd w szyfratorze, a nie nieprawidłowe dane wejściowe wywołującego.

GcmInvocationLimitExceededException

• Kiedy zgłaszany. Osiągnięto opcjonalną liczbę wywołań bezpieczeństwa użycia z NIST SP 800-38D §8.3 dla danego klucza AES-GCM. To hak telemetryczny obrony w głąb dla wywołujących, którzy chcą egzekwować zalecaną przez specyfikację granicę (około 2^32 wywołań na klucz) wcześniej niż architektoniczne limity wewnątrz szyfratora. Nie zadziała domyślnie; zgłasza to wyłącznie pomocnik assertWithinSafetyBound().
• Pola kontekstu. key_fingerprint_prefix, invocation_count (bieżąca liczba encrypt(), na poziomie limitu lub powyżej), invocation_limit (opcjonalna granica).
• Naprawa. Wymień klucz dokumentu (skonstruuj świeży szyfrator z nowym materiałem klucza), zanim łączne prawdopodobieństwo kolizji i sfałszowania przestanie być pomijalne, albo rozszerz politykę wywołującego, aby odmawiać dalszej obsługi.

IncompatiblePdfAModeException

• Kiedy zgłaszany. Podjęto próbę operacji szyfrowania na dokumencie oznaczonym jako PDF/A. Rodzina PDF/A (PDF/A-2, PDF/A-3, PDF/A-4) jednolicie zabrania szyfrowania: zgodnie z ISO 19005 §6.1.3 klucz Encrypt nie może być obecny w zwiastunie, a ISO 19005-4:2020 Aneksy A i B dziedziczą to bez modyfikacji. Nie istnieje dozwolona kombinacja PDF/A i szyfrowania.
• Pola kontekstu. pdfa_mode (na przykład pdfa4, pdfa3), encryption_operation (odrzucone wywołanie, na przykład useAesGcm).
• Naprawa. Aby utworzyć zaszyfrowany dokument, pomiń wywołanie enablePdfA(); aby utworzyć dokument archiwalny, pomiń wywołanie szyfrowania. Zobacz Walidacja PDF/A i PDF/UA.

Egzekwowanie polityki kryptograficznej

CryptoPolicyViolationException

• Kiedy zgłaszany. Skonfigurowana polityka kryptograficzna odrzuca algorytm, siłę klucza lub szyfr wybrany przez podstawową operację podpisywania, szyfrowania lub haszowania. To granica fail-closed dla egzekwowania zgodności (na przykład FIPS 140-2/3, eIDAS lub niestandardowa polityka korporacyjna), zgłaszana przez CryptoPolicyEnforcer przed wytworzeniem jakiegokolwiek podpisu lub szyfrogramu, więc operacja naruszająca politykę nigdy nie może wyemitować niezatwierdzonego artefaktu. Odrębna od wąskiej awarii operacji OpenSSL oraz od awarii prymitywu podpisującego: to odrzucenie przez politykę poza tym prawidłowego żądania. Zgodna z NIST SP 800-131A Rev. 2 oraz ISO/IEC 19790:2025 §7.
• Pola kontekstu. policy (nazwa polityki, na przykład FIPS 140-3 Strict), category (hash, signature, encryption lub key-strength), item (odrzucony element, na przykład identyfikator obiektu (OID), nazwa szyfru lub rsa/1024), reason.
• Naprawa. Wybierz algorytm, długość klucza lub szyfr, który nazwana polityka zatwierdza, albo dostosuj politykę, jeśli jesteś jej właścicielem. Skieruj ustrukturyzowany kontekst do udokumentowanego podręcznika operacyjnego zgodności.

Zarządzanie kluczami

Istnieją dwie klasy o tej samej nazwie. Współdzielą korzeń SecurityException, więc jeden blok catch (SecurityException $e) ujmuje obie, ale niosą odrębne ładunki. Importuj według w pełni kwalifikowanej nazwy, gdy potrzebujesz konkretnego kształtu.

KeyManagementException (cykl życia: NextPDF\Security\Exception)

• Kiedy zgłaszany. Operacja zarządzania kluczami nie powiedzie się, zanim klucz zostanie spożytkowany przez prymityw podpisu lub szyfrowania: awarie parsowania klucza Privacy-Enhanced Mail (PEM), PKCS#12 lub PKCS#11; awarie wyprowadzania klucza (HKDF, PBKDF2, scrypt); odrzucenie AES Key Wrap (RFC 3394) na nieprawidłowym kluczu szyfrującym klucz; sprzętowy moduł bezpieczeństwa (HSM) zwracający źle sformowane Distinguished Encoding Rules (DER); albo niezgodność długości ziarna Ed25519.
• Pola kontekstu. operation (na przykład load_pem, kek_derive, key_wrap), key_type (na przykład RSA, EC-P256, Ed25519, AES-256), reason. Surowy materiał klucza nigdy nie jest dołączany.
• Naprawa. Sprawdź nazwaną operację oraz typ klucza, popraw źródłowy materiał klucza lub dane wejściowe wyprowadzania i ponów.

KeyManagementException (ścieżka podpisywania: NextPDF\Security\Signature\Exception)

• Kiedy zgłaszany. Dostawca obiektu podpisującego napotyka błąd zarządzania kluczami: żądana wersja klucza jest nieznana, wyłączona, zaplanowana do zniszczenia, nie ma uprawnienia do podpisywania albo jest w inny sposób nieużywalna. To właśnie zgłaszają RsaPssSigner i LocalKeySignerProvider przy awariach klucza na żywo. Nazwane konstruktory: unknownKeyVersion() oraz keyVersionDisabled().
• Pola kontekstu. providerId, keyVersion, reason. Akcesory: providerId(), keyVersion(), reason().
• Naprawa. Wymień klucz lub nadaj mu ponownie uprawnienia, albo wybierz używalną wersję klucza, a następnie ponów. Odrębne od SignatureFailedException, które sygnalizuje, że sam prymityw podpisujący zawiódł.

Podpisywanie

Aby uzyskać wskazówki zaczynające się od objawu dotyczące nieosiągalnych poziomów i brakujących możliwości, zobacz Błędy podpisu i znacznika czasu.

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

• Kiedy zgłaszany. Kryptograficzna operacja podpisywania nie powiedzie się: prymityw podpisujący RSA, ECDSA lub Ed25519 zwraca false albo wyjście o błędnej długości; token HSM lub PKCS#11 odpowiada statusem braku sukcesu; składanie SignedData Cryptographic Message Syntax (CMS) nie powiedzie się na źle sformowanym certyfikacie lub łańcuchu; albo samoweryfikacja Ed25519 w obie strony nie powiedzie się. Nowy kod powinien preferować ten podtyp R4-13 zamiast starego wyjątku podpisu powiązanego z PAdES.
• Pola kontekstu. operation (na przykład sign, verify, build_cms), algorithm (na przykład rsa-pkcs1v15-sha256, ed25519), reason. Akcesory: getOperation(), getAlgorithm(), getReason().
• Naprawa. Odczytaj operację i algorytm, popraw dane wejściowe (klucz, łańcuch certyfikatów lub dostępność backendu) i ponów. Zgodne z postawą fail-closed obsługi klucza z ETSI EN 319 142-1.

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

• Kiedy zgłaszany. Implementacja SignerProviderInterface nie może ukończyć operacji podpisywania z dowolnego powodu niesklasyfikowanego jako zarządzanie kluczami: błąd sterownika backendu, źle sformowany materiał klucza lub nieusuwalne wejście/wyjście HSM. To wariant przechwytujący wszystko dla kontraktu podpisywania fail-closed, w którym każdy prymityw zgłasza wyjątek przy awarii, zamiast zwracać null, false lub pusty ciąg. Nazwany konstruktor: forProvider().
• Pola kontekstu. providerId, reason. Akcesory: providerId(), reason().
• Naprawa. Sprawdź identyfikator dostawcy oraz przyczynę, popraw backend dostawcy lub materiał klucza i ponów. Rozgałęziaj logikę na KeyManagementException względem tego typu, aby oddzielić „klucz jest zły” od „prymityw zawiódł”.

SignatureLevelUnreachableException

• Kiedy zgłaszany. Żądanego poziomu zgodności PAdES nie można uhonorować w bieżącej infrastrukturze środowiska wykonawczego (najczęściej brak urzędu znaczników czasu dla B-T i wyższych), a wywołujący nie udzielił zgody na degradację. Domyślnie działa w trybie fail-closed: silnik odmawia, zamiast po cichu wytworzyć niższy poziom, reklamując jednocześnie wyższy, co byłoby regresją o randze eIDAS. Zgodne z ETSI EN 319 142-1 §6. Zauważ, że ta klasa rozszerza NextPdfException bezpośrednio (a nie SecurityException).
• Pola kontekstu. requestedLevel, highestAchievableLevel, reason. Akcesory: requestedLevel(), highestAchievableLevel(), reason().
• Naprawa. Odczytaj reason, aby zidentyfikować brakującą infrastrukturę, i dostarcz ją (na przykład skonfiguruj urząd znaczników czasu) albo przekaż allowDegradation: true do PadesOrchestrator, aby celowo zaakceptować najwyższy osiągalny poziom.

SignerProviderNotFoundException

• Kiedy zgłaszany. SignerProviderRegistry::get() zostaje poproszony o identyfikator dostawcy, który nie jest zarejestrowany. Implementuje PSR-11 NotFoundExceptionInterface, więc rejestr jest zgodny z kontraktem kontenera PSR-11. Nazwany konstruktor: forId(). Ta klasa rozszerza RuntimeException i nie udostępnia getContext().
• Pola kontekstu. Brak. Niezarejestrowany identyfikator pojawia się w komunikacie.
• Naprawa. Zarejestruj dostawcę pod oczekiwanym identyfikatorem przed zażądaniem go albo popraw identyfikator przekazywany do rejestru.

Haszowanie (SHAKE256)

Rozszerzają RuntimeException i nie udostępniają getContext(). SHAKE256 to funkcja o rozszerzanej długości wyjścia SHA-3 wymagana przez niektóre ścieżki ISO/TS 32001.

Shake256NotAvailableException

• Kiedy zgłaszany. W czasie obliczania skrótu, gdy wybrany dostawca nie może spełnić żądania. Nazwane konstruktory: noBackend() (brak działającego backendu SHAKE256 na tym hoście, we wszystkich próbowanych poziomach) oraz ffiCallFailed() (wywołanie OpenSSL EVP powiązane przez FFI zwróciło status braku sukcesu, na przykład z okrojonej kompilacji libcrypto).
• Pola kontekstu. Brak. Komunikat podaje próbowane poziomy lub nieudany symbol.
• Naprawa. Zainstaluj ext-ffi z obecnym OpenSSL 3.x albo zaktualizuj do kompilacji PHP, która udostępnia shake256 w hash_algos(). Wariant zapasowy Keccak w przestrzeni użytkownika celowo nie jest dostarczany.

Shake256ProviderNotAvailableException

• Kiedy zgłaszany. Z konstruktora dostawcy SHAKE256, gdy sonda możliwości zawiedzie, więc dostawcy nie można zinstancjonować. To sygnał sterowania przepływem: rejestr dostawców go przechwytuje, zapisuje etykietę poziomu i próbuje następnego poziomu. Nigdy nie powinien wydostać się do kodu aplikacji. Nazwany konstruktor: forTier().
• Pola kontekstu. Brak. Komunikat podaje poziom oraz przyczynę.
• Naprawa. Nie jest bezpośrednio możliwy do obsłużenia przez wywołującego; jeśli cały łańcuch poziomów zostanie wyczerpany, rejestr ujawnia zamiast tego Shake256NotAvailableException::noBackend(), które niesie naprawę zorientowaną na operatora.

Integralność MAC dokumentu (ISO/TS 32004)

Obejmują kod uwierzytelniania wiadomości (MAC) na poziomie dokumentu z ISO/TS 32004, przechowywany pod /AuthCode. Obie rozszerzają NextPdfException i nadpisują getContext().

DocumentMacTokenException

• Kiedy zgłaszany. W trybie fail-closed, przez czytnik tokenu MAC, gdy token MAC CMS AuthenticatedData jest strukturalnie źle sformowany lub deklaruje algorytm spoza uzgodnionego zestawu ISO/TS 32004. Nazwane konstruktory: malformed() oraz algorithmMismatch(). Oznaczony jako @internal.
• Pola kontekstu. status (wartość DocumentMacVerificationStatus, czyli MalformedToken lub AlgorithmMismatch). Publiczna właściwość readonly: $status.
• Naprawa. Potraktuj dokument jako niezweryfikowany. Źle sformowany token lub algorytm spoza uzgodnionego zestawu oznacza, że MAC nie może ustanowić zaufania; nie postępuj tak, jakby treść była chroniona.

DocumentMacVerificationException

• Kiedy zgłaszany. W trybie fail-closed, gdy weryfikacja MAC na poziomie dokumentu nie może osiągnąć zaufanego stanu: brakujący lub źle sformowany /AuthCode, algorytm spoza uzgodnionego zestawu, awaria rozpakowania albo niezgodność MAC (manipulacja). Metoda verify() weryfikatora zwraca jawny wynik do rozgałęziania; to jest odpowiednik w przepływie wyjątków zgłaszany przez assertVerified(), aby kod „zaufaj treści” nigdy nie mógł przejść poza niezweryfikowany dokument. Nazwany konstruktor: fromResult().
• Pola kontekstu. status (wartość DocumentMacVerificationStatus). Publiczna właściwość readonly: $status.
• Naprawa. Nie ufaj treści dokumentu. Sprawdź status, aby odróżnić manipulację (niezgodność MAC) od problemu konfiguracji (brakujący lub źle sformowany /AuthCode, niezgodność algorytmu).

Walidacja ścieżki PKI (RFC 5280)

Obejmują walidację ścieżki certyfikacji z RFC 5280. Typ bazowy oraz jego podklasy działają w trybie fail-closed.

PkiPathValidationException

• Kiedy zgłaszany. Awaria trybu ścisłego z walidatora ścieżki RFC 5280. To niefinalna baza dla węższych podklas (ChainLengthExceededException, UnsupportedExtensionException), więc programy obsługi przechwytujące ten typ przechwytują również tamte przez podstawialność Liskov. Rozszerza SecurityException.
• Pola kontekstu. Nie nadpisuje getContext() (dziedziczy pustą wartość domyślną). Niesie ustrukturyzowane przyczyny w zamrożonej publicznej właściwości readonly $reasons (niepustej liście napisów nazwa-reguły plus opis).
• Naprawa. Odczytaj $reasons, aby zidentyfikować zawodzącą regułę, popraw łańcuch certyfikatów i zwaliduj ponownie. Przechwyć ten typ, aby jednolicie obsłużyć każdą awarię walidacji ścieżki.

ChainLengthExceededException

• Kiedy zgłaszany. Walidator ścieżki zostaje poproszony o przejście łańcucha, którego długość przekracza skonfigurowany pułap. Górna granica jest egzekwowana przed rozpoczęciem jakiegokolwiek parsowania, więc złośliwy dostawca nie może wpędzić walidatora w kwadratową pracę ani wyczerpać zasobów dowolnie głębokim łańcuchem. Domyślny pułap 10 jest zgodny z profilem PKIX-CMP (RFC 4210 §5.3.18); łańcuchy z realnego świata mieszczą się w 5 do 6 wpisach. Podklasa PkiPathValidationException.
• Pola kontekstu. Dziedziczy puste getContext(); napis przyczyny chain_length_exceeded: supplied=<n> cap=<n> jest przekazywany do $reasons rodzica. Publiczne właściwości readonly: $supplied, $cap.
• Naprawa. Dostarcz łańcuch mieszczący się w pułapie albo podnieś skonfigurowaną górną granicę, jeśli spodziewany jest zasadnie dłuższy łańcuch.

UnsupportedExtensionException

• Kiedy zgłaszany. Walidator ścieżki napotyka krytyczne rozszerzenie X.509, którego egzekwowanie nie jest jeszcze zaimplementowane. Zgodnie z RFC 5280 §4.2 nierozpoznane krytyczne rozszerzenie musi zadziałać w trybie fail-closed; zarówno tryb ścisły, jak i łagodny działają tu w trybie fail-closed, ponieważ ciche pominięcie krytycznego rozszerzenia byłoby regresją bezpieczeństwa. Walidator obejmuje budowanie łańcucha, dopasowanie AKI/SKI, użycie klucza, rozszerzone użycie klucza, ograniczenia podstawowe, wygaśnięcie oraz weryfikację podpisu; wszystko inne krytyczne ujawnia się tutaj. Podklasa PkiPathValidationException.
• Pola kontekstu. Dziedziczy puste getContext(); ustrukturyzowane przyczyny są przekazywane do $reasons rodzica. Publiczne właściwości readonly: $extensionOid (kropkowany OID, na przykład 2.5.29.30 dla ograniczeń nazw), $extensionName, $clauseRef (wskaźnik na klauzulę RFC 5280 oraz wpis dziennika elementów odroczonych).
• Naprawa. W trybie łagodnym przechwyć tę konkretną podklasę, aby cofnąć się do zgrubniejszej polityki bez połykania prawdziwych awarii walidacji ścieżki. Skontroluj $extensionOid i $clauseRef względem swoich fikstur PKI, aby zobaczyć, które rozszerzenie blokuje walidację.

RevocationCheckFailedException

• Kiedy zgłaszany. Zarówno punkty końcowe OCSP, jak i listy unieważnionych certyfikatów (CRL) zostają wyczerpane bez ostatecznego werdyktu: awaria transportu OCSP lub źle sformowana odpowiedź oraz awaria transportu CRL lub źle sformowana CRL, przy obu otwartych wyłącznikach obwodu lub obu brakujących pamięciach podręcznych. Tryb ścisły traktuje to jako fail-closed; tryb łagodny to przechwytuje i emituje ostrzeżenie PSR-3 z revocation = null. Rozszerza SecurityException.
• Pola kontekstu. Nie nadpisuje getContext() (dziedziczy pustą wartość domyślną). Niesie stan w publicznych właściwościach readonly $ocspState i $crlState (każda domyślnie unknown).
• Naprawa. Przywróć osiągalność źródła unieważnień, poczekaj na zamknięcie wyłączników obwodu albo rozgrzej pamięć podręczną, a następnie ponów. Nie tłum tego, aby uzyskać artefakt walidacji długoterminowej; potwierdzenie unieważnienia jest częścią tego poziomu.

Weryfikacja podpisu OCSP (RFC 6960)

OcspSignatureInvalidException

• Kiedy zgłaszany. Podpis BasicOCSPResponse z RFC 6960 §4.2.2.2 nie przechodzi weryfikacji kryptograficznej względem certyfikatu respondera. Parser dekoduje signatureAlgorithm (RSA-PSS, ECDSA lub RSA-PKCS1v15) i weryfikuje signature nad tbsResponseData; każda awaria zgłasza ten typowany wyjątek, aby wywołujący mogli odróżnić strukturalnie prawidłową, ale kryptograficznie zmanipulowaną odpowiedź od odpowiedzi ze źle sformowanym DER. Niefinalna, więc pakiety downstream mogą publikować bardziej szczegółowe podklasy. Rozszerza SecurityException.
• Pola kontekstu. Nie nadpisuje getContext() (dziedziczy pustą wartość domyślną). Niesie znacznik awarii w publicznej właściwości readonly $reason (na przykład signature_mismatch, responder_cert_not_in_bundle, unsupported_signature_algorithm); wolnotekstowy detail jest złożony w komunikacie.
• Naprawa. Sprawdź $reason. Dla responder_cert_not_in_bundle dostarcz poprawny pakiet kotwic zaufania oraz certyfikat respondera. Dla signature_mismatch potraktuj odpowiedź jako niegodną zaufania. Zobacz Błędy podpisu i znacznika czasu.

Znakowanie czasem (RFC 3161)

TsaException

• Kiedy zgłaszany. Awaria w komunikacji z urzędem znaczników czasu (TSA) z RFC 3161 lub w parsowaniu odpowiedzi: TSA zwraca status błędu, żądanie HTTP się nie powiedzie albo odpowiedzi ASN.1 nie można sparsować. To baza hierarchii błędów TSA i jest niefinalna, aby awarie weryfikacji mogły ją rozszerzać. Rozszerza NextPdfException.
• Pola kontekstu. Nie nadpisuje getContext() (dziedziczy pustą wartość domyślną).
• Naprawa. Przechwyć TsaException dla każdej ścieżki błędu TSA. Zweryfikuj osiągalność TSA oraz to, że punkt końcowy zwraca poprawnie sformowaną odpowiedź RFC 3161.

TsaTokenVerificationException

• Kiedy zgłaszany. Weryfikacja CMS TimeStampToken z RFC 3161 nie powiedzie się na którymkolwiek z nakazanych kroków weryfikacji: powiązanie ESSCertIDv2 z RFC 5816 §3, integralność podpisanych atrybutów z RFC 5652 §11, świeżość producedAt z RFC 3161 §2.4.2 albo podpis SignerInfo z RFC 5652 §5.4. W trybie fail-closed, z typowanym dyskryminatorem kroku, aby potoki audytowe odróżniały ponowne odtworzenie (replay) od dryfu zegara od niezgodności certyfikatu bez przeszukiwania komunikatów. Podklasa TsaException, więc stare programy obsługi catch (TsaException) nadal się uruchamiają.
• Pola kontekstu. step (zawodząca wartość Step potoku) oraz message. Akcesor: getStep().
• Naprawa. Możliwe do obsłużenia przez programistę (błędnie skonfigurowany certyfikat TSA lub tolerancja dryfu) albo bezpieczeństwo (podejrzewany MITM lub replay). Odczytaj step, aby zlokalizować zawodzący etap i popraw odpowiednie dane wejściowe lub konfigurację zaufania.

MalformedDerException

• Kiedy zgłaszany. Wewnętrzny sygnał, że przejście DER trafiło na źle sformowaną lub obciętą granicę, zgłaszany przez niskopoziomowe walkery wewnątrz weryfikatora tokenu TSA. Jest zawsze przechwytywany na publicznej granicy weryfikacji i ponownie opakowywany w TsaTokenVerificationException niosący właściwy dyskryminator kroku; nigdy nie wycieka do kodu wywołującego. Rozszerza RuntimeException; oznaczony jako @internal.
• Pola kontekstu. Brak.
• Naprawa. Nie skierowany do wywołującego. Obsłuż zamiast tego opakowany TsaTokenVerificationException.

Dekodowanie rozszerzeń certyfikatu

Rozszerzają RuntimeException i nie udostępniają getContext(). Oba to dekodery działające w trybie fail-closed.

NameConstraintsDecodeException

• Kiedy zgłaszany. Dekoder ograniczeń nazw napotyka egzekwowalny element GeneralSubtree, którego nie potrafi wiernie zdekodować. RFC 5280 §4.2.1.10 wymaga, aby strona ufająca przetworzyła egzekwowalne ograniczenie nazwy lub odrzuciła certyfikat; przekształcenie wcześniejszego cichego pominięcia w tę typowaną awarię zapobiega fail-open, który po cichu poszerzyłby akceptowany zbiór nazw. Zakres jest ograniczony do egzekwowalnych form nazw (directoryName, dNSName, iPAddress, rfc822Name, uniformResourceIdentifier); formy nieegzekwowalne pozostają ignorowalne i nigdy go nie zgłaszają. Nazwany konstruktor: undecodableEnforceableBase(). Oznaczony jako @internal.
• Pola kontekstu. Brak. Bezpieczny dla logu napis ze szczegółami jest niesiony w komunikacie.
• Naprawa. Egzekutor ujawnia przyczynę name_constraints: w trybie fail-closed, a łańcuch zostaje odrzucony. Zbadaj kodowanie ograniczeń nazw certyfikatu; nie łagodź egzekwowania.

QcStatementsDecodeException

• Kiedy zgłaszany. Rozszerzenie qcStatements jest strukturalnie źle sformowane: obcięty DER, błędny znacznik lub przepełnienie długości. Dekoder działa w trybie fail-closed i zgłasza wyjątek, zamiast zwracać częściowy lub heurystyczny wynik, gdy nie może z pewnością ustalić, co mówi rozszerzenie. Oznaczony jako @api.
• Pola kontekstu. Brak.
• Naprawa. Przechwyć go jawnie tylko wtedy, gdy zamierzasz tolerować źle sformowane kodowanie; w przeciwnym razie potraktuj oświadczenia certyfikatu kwalifikowanego jako nieustalalne i odrzuć lub ponownie wystaw certyfikat.

Sesje PKCS#11

Pkcs11SessionException

• Kiedy zgłaszany. Defekt zarządzania sesją PKCS#11 v3.1. Każdy nazwany konstruktor odwzorowuje się na konkretną klasę defektu oraz na wartość zwracaną CKR_* PKCS#11, ujawnianą przez typowany dyskryminator $kind, aby wywołujący rozgałęziali logikę na stabilnym napisie wyliczeniowym zamiast na kruchym dopasowywaniu komunikatów. Konstruktory obejmują: cryptokiNotInitialized(), userNotLoggedIn(), userAlreadyLoggedIn(), operationNotInitialized(), operationActive(), mechanismNotAllowed(), tokenDisconnected(), concurrentSessionLimitExceeded(), sessionAlreadyClosed(), stateTransitionInvalid(), osLockingRequired(), loginTtlExpired() oraz signOperationTtlExpired(). Rozszerza SecurityException.
• Pola kontekstu. Nie nadpisuje getContext() (dziedziczy pustą wartość domyślną). Niesie typowany rodzaj w publicznej właściwości readonly $kind, jednej z stałych KIND_* (na przykład KIND_USER_NOT_LOGGED_IN, KIND_TOKEN_DISCONNECTED, KIND_LOGIN_TTL_EXPIRED). Identyfikatory slotu i sesji, mechanizm oraz wartości TTL pojawiają się w komunikacie. Kody PIN i bajty certyfikatu nigdy nie są dołączane.
• Naprawa. Przełączaj według $kind. Dla user_not_logged_in zaloguj się kodem PIN użytkownika przed zainicjowaniem operacji podpisu. Dla token_disconnected potraktuj wszystkie sesje na slocie jako osierocone. Dla rodzajów TTL uwierzytelnij się ponownie lub ponownie zainicjuj operację. Dla mechanism_not_allowed rozszerz skonfigurowaną listę dozwolonych mechanizmów albo wybierz dozwolony mechanizm.

Zobacz także

• Indeks dokumentacji błędów
• Błędy podpisu i znacznika czasu
• Szyfrowanie i uprawnienia
• Walidacja PDF/A i PDF/UA