Kesalahan keamanan dan penandatanganan

Sekilas

Halaman ini mendokumentasikan eksepsi domain-keamanan dalam pohon namespace NextPDF\Security. Setiap entri menyebutkan kelasnya, menyatakan kapan eksepsi dilemparkan, mencantumkan bidang yang dikembalikan getContext()-nya, dan memberikan langkah pemulihan.

Sebagian besar kelas ini memperluas SecurityException, yang memperluas NextPdfException dan mengimplementasikan ContextAwareExceptionInterface. Artinya getContext(): array mengembalikan diagnostik terstruktur dan bebas-rahasia yang dapat Anda rutekan ke pipeline logging atau application performance monitoring (APM). Tangkap SecurityException untuk menjerat setiap kegagalan domain-keamanan dalam satu blok; tangkap subkelas spesifik ketika Anda membutuhkan payload bertipenya.

Beberapa kelas dalam pohon ini memperluas RuntimeException secara langsung alih-alih SecurityException. Kelas-kelas tersebut ditandai di bawah; mereka tidak memaparkan getContext(), dan sebagian besar didokumentasikan sebagai sinyal kontrol-alur internal yang seharusnya tidak Anda harapkan untuk ditangkap dalam kode aplikasi.

Konvensi bidang-konteks

Aspek	Perilaku
Kontrak basis	NextPdfException::getContext() mengembalikan []; subkelas menimpanya.
Higiene rahasia	Pesan dan konteks menghilangkan materi kunci mentah, plaintext, PIN, dan byte initialization vector (IV). Kunci hanya dimunculkan sebagai prefiks fingerprint.
SecurityException	Basis abstrak; tidak membawa bidang miliknya sendiri. Subkelas mendefinisikan payload.

Tipe basis

SecurityException

• Kapan dilemparkan. Tidak pernah dilemparkan secara langsung; ini adalah basis abstrak untuk domain keamanan. Eksepsi ini ada agar satu blok catch (SecurityException $e) dapat menjerat kegagalan integritas authenticated-encryption, pertahanan nonce-reuse, pengikatan PDF/A-versus-enkripsi, cacat manajemen-kunci, dan kegagalan PKI.
• Bidang konteks. Tidak ada miliknya sendiri. Mewarisi bawaan kosong dari NextPdfException; subkelas mengisi payload.
• Pemulihan. Tangkap subkelas konkret untuk penanganan yang dapat ditindaklanjuti, atau SecurityException untuk perutean insiden-keamanan yang kasar.

Kesalahan enkripsi dan authenticated-encryption

Ini dimunculkan oleh enkriptor AES-GCM (Galois/Counter Mode) dan penjaga PDF/A. Untuk panduan gejala-dahulu, lihat Enkripsi dan izin.

DecryptionFailedException

• Kapan dilemparkan. Sebuah dekripsi authenticated-encryption with associated data (AEAD) gagal karena alasan non-pengrusakan: ciphertext terpotong, IV yang hilang, atau kunci salah yang disuplai pada batas API, di mana tidak ada cukup materi agar pemeriksaan integritas benar-benar berjalan. Ini adalah kesalahan konfigurasi atau transport, bukan insiden keamanan.
• Bidang konteks. algorithm (misalnya AES-256-GCM), reason (misalnya ciphertext shorter than IV+tag).
• Pemulihan. Verifikasi ciphertext, IV, dan kunci lengkap dan terbingkai dengan benar; jangan memperlakukan ini sebagai pengrusakan. Bandingkan dengan TamperedDataException.

TamperedDataException

• Kapan dilemparkan. Tag autentikasi AEAD gagal verifikasi. Tag tersebut mencakup ciphertext ditambah associated authenticated data (AAD); jika salah satunya dimodifikasi setelah enkripsi, openssl_decrypt() yang mendasarinya mengembalikan false. Subtipe berbeda ini memungkinkan Anda memunculkan peringatan berkelas-insiden-keamanan alih-alih kesalahan pembingkaian.
• Bidang konteks. algorithm, ciphertext_length (panjang ciphertext yang ditolak, tidak termasuk IV dan tag).
• Pemulihan. Perlakukan sebagai pengrusakan atau kunci/IV salah. Jangan mencoba ulang membabi buta; selidiki sumber ciphertext tersebut. Sesuai ISO/TS 32003:2023 §5.2 dan NIST SP 800-38D §6.5, pemeriksaan tag yang gagal berarti data tidak autentik.

NonceReuseException

• Kapan dilemparkan. AES-GCM diminta mengenkripsi dua kali dengan pasangan kunci dan IV yang sama. Enkriptor bertahan dengan penghitung monotonik per-instance dan, sebagai pertahanan berlapis, hash-set runtime dari setiap pasangan (key-fingerprint, IV) yang dipancarkan. Karena penghitung tersebut menyingkirkan kolisi secara konstruksi, pemicuan ini adalah indikator bug berprioritas-kritis yang tidak boleh terjadi di produksi. Penggunaan ulang pasangan key/IV mengompromikan seluruh keystream (ISO/TS 32003:2023 §5.2 NOTE 2; NIST SP 800-38D §8.3).
• Bidang konteks. key_fingerprint_prefix (8 karakter hex pertama dari SHA-256(key)), iv_length (selalu 12 untuk ISO/TS 32003), reason (hashset-collision atau counter-rollover, membedakan bug refaktor yang mengalahkan penghitung dari pemicu penghitung 2^63), dan iv_fixed_field_hex (bidang tetap IV, hadir hanya ketika disuplai, dilaporkan di bawah kuncinya sendiri dan tidak pernah salah-label sebagai fingerprint kunci).
• Pemulihan. Batalkan segera dan rotasi kunci. Ajukan laporan cacat; ini menunjukkan bug dalam enkriptor, bukan masukan pemanggil yang buruk.

GcmInvocationLimitExceededException

• Kapan dilemparkan. Jumlah pemanggilan keamanan-penggunaan NIST SP 800-38D §8.3 yang bersifat opt-in tercapai untuk kunci AES-GCM tertentu. Ini adalah kait telemetri pertahanan-berlapis untuk pemanggil yang ingin menegakkan batas yang direkomendasikan-spesifikasi (sekitar 2^32 pemanggilan per kunci) lebih awal dari batas arsitektural di dalam enkriptor. Eksepsi ini tidak menyala secara bawaan; hanya helper assertWithinSafetyBound() yang memunculkannya.
• Bidang konteks. key_fingerprint_prefix, invocation_count (jumlah encrypt() saat ini, pada atau di atas batas), invocation_limit (batas opt-in).
• Pemulihan. Rotasi kunci dokumen (konstruksi enkriptor baru dengan materi kunci baru) sebelum probabilitas kumulatif kolisi dan pemalsuan tidak lagi dapat diabaikan, atau perluas kebijakan pemanggil untuk menolak layanan lanjutan.

IncompatiblePdfAModeException

• Kapan dilemparkan. Operasi enkripsi diupayakan pada dokumen ber-tag PDF/A. Keluarga PDF/A (PDF/A-2, PDF/A-3, PDF/A-4) secara seragam melarang enkripsi: sesuai ISO 19005 §6.1.3 kunci Encrypt tidak boleh hadir di trailer, dan ISO 19005-4:2020 Annex A dan B mewarisi ini tanpa modifikasi. Tidak ada kombinasi PDF/A dan enkripsi yang diizinkan.
• Bidang konteks. pdfa_mode (misalnya pdfa4, pdfa3), encryption_operation (panggilan yang ditolak, misalnya useAesGcm).
• Pemulihan. Untuk menghasilkan dokumen terenkripsi, hilangkan panggilan enablePdfA(); untuk menghasilkan dokumen arsip, hilangkan panggilan enkripsi. Lihat Validasi PDF/A dan PDF/UA.

Penegakan crypto-policy

CryptoPolicyViolationException

• Kapan dilemparkan. Sebuah crypto policy yang dikonfigurasi menolak algoritme, kekuatan kunci, atau cipher yang dipilih oleh operasi penandatanganan, enkripsi, atau hashing inti. Ini adalah batas gagal-tertutup untuk penegakan kepatuhan (misalnya FIPS 140-2/3, eIDAS, atau kebijakan enterprise kustom) dan dimunculkan oleh CryptoPolicyEnforcer sebelum tanda tangan atau ciphertext apa pun dihasilkan, sehingga operasi yang melanggar-kebijakan tidak pernah dapat memancarkan artefak yang tidak disetujui. Berbeda dari kegagalan operasi OpenSSL yang sempit dan dari kegagalan primitif-penandatanganan: ini adalah penolakan kebijakan terhadap permintaan yang sebenarnya valid. Selaras dengan NIST SP 800-131A Rev. 2 dan ISO/IEC 19790:2025 §7.
• Bidang konteks. policy (nama kebijakan, misalnya FIPS 140-3 Strict), category (hash, signature, encryption, atau key-strength), item (item yang ditolak, misalnya object identifier (OID), nama cipher, atau rsa/1024), reason.
• Pemulihan. Pilih algoritme, panjang kunci, atau cipher yang disetujui oleh kebijakan yang disebut, atau sesuaikan kebijakan jika Anda yang memilikinya. Rutekan konteks terstruktur ke runbook kepatuhan yang terdokumentasi.

Manajemen kunci

Dua kelas bernama-sama ada. Keduanya berbagi akar SecurityException sehingga satu blok catch (SecurityException $e) menjerat keduanya, tetapi keduanya membawa payload yang berbeda. Impor berdasarkan nama yang sepenuhnya berkualifikasi ketika Anda membutuhkan bentuk yang spesifik.

KeyManagementException (siklus hidup: NextPDF\Security\Exception)

• Kapan dilemparkan. Operasi manajemen-kunci gagal sebelum kunci dikonsumsi oleh primitif sign atau encrypt: kegagalan penguraian kunci Privacy-Enhanced Mail (PEM), PKCS#12, atau PKCS#11; kegagalan key-derivation (HKDF, PBKDF2, scrypt); penolakan AES Key Wrap (RFC 3394) pada key-encryption key yang salah; sebuah hardware security module (HSM) mengembalikan Distinguished Encoding Rules (DER) yang cacat; atau ketidakcocokan panjang seed Ed25519.
• Bidang konteks. operation (misalnya load_pem, kek_derive, key_wrap), key_type (misalnya RSA, EC-P256, Ed25519, AES-256), reason. Materi kunci mentah tidak pernah disertakan.
• Pemulihan. Periksa operasi dan tipe kunci yang disebut, perbaiki materi kunci sumber atau masukan derivasi, lalu coba lagi.

KeyManagementException (jalur penandatanganan: NextPDF\Security\Signature\Exception)

• Kapan dilemparkan. Sebuah penyedia signer mengalami cacat manajemen-kunci: versi kunci yang diminta tidak dikenal, dinonaktifkan, dijadwalkan untuk pemusnahan, tidak memiliki izin penandatanganan, atau tidak dapat digunakan dengan cara lain. Inilah yang dilemparkan RsaPssSigner dan LocalKeySignerProvider pada kegagalan kunci langsung. Konstruktor yang dinamai: unknownKeyVersion() dan keyVersionDisabled().
• Bidang konteks. providerId, keyVersion, reason. Aksesor: providerId(), keyVersion(), reason().
• Pemulihan. Rotasi atau beri-ulang izin kunci, atau pilih versi kunci yang dapat digunakan, lalu coba lagi. Berbeda dari SignatureFailedException, yang menandakan bahwa primitif penandatanganan itu sendiri yang gagal.

Penandatanganan

Untuk panduan gejala-dahulu tentang tingkat yang tak terjangkau dan kapabilitas yang hilang, lihat Kegagalan tanda tangan dan stempel waktu.

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

• Kapan dilemparkan. Sebuah operasi penandatanganan kriptografi gagal: sebuah primitif sign RSA, ECDSA, atau Ed25519 mengembalikan false atau keluaran dengan panjang salah; sebuah token HSM atau PKCS#11 merespons dengan status non-sukses; perakitan SignedData Cryptographic Message Syntax (CMS) gagal pada sertifikat atau rantai yang cacat; atau self-verify round-trip Ed25519 gagal. Kode baru sebaiknya mengutamakan subtipe R4-13 ini dibanding eksepsi tanda tangan lawas yang terkopel-PAdES.
• Bidang konteks. operation (misalnya sign, verify, build_cms), algorithm (misalnya rsa-pkcs1v15-sha256, ed25519), reason. Aksesor: getOperation(), getAlgorithm(), getReason().
• Pemulihan. Baca operasi dan algoritme, perbaiki masukan (kunci, rantai sertifikat, atau ketersediaan backend), lalu coba lagi. Selaras dengan postur penanganan-kunci gagal-tertutup ETSI EN 319 142-1.

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

• Kapan dilemparkan. Sebuah implementasi SignerProviderInterface tidak dapat menyelesaikan operasi penandatanganan untuk alasan apa pun yang tidak dikategorikan sebagai manajemen-kunci: kesalahan driver backend, materi kunci cacat, atau I/O HSM yang tak dapat dipulihkan. Ini adalah penangkap-segala untuk kontrak penandatanganan gagal-tertutup, di mana setiap primitif melemparkan saat kegagalan alih-alih mengembalikan null, false, atau string kosong. Konstruktor yang dinamai: forProvider().
• Bidang konteks. providerId, reason. Aksesor: providerId(), reason().
• Pemulihan. Periksa id penyedia dan alasannya, perbaiki backend penyedia atau materi kunci, lalu coba lagi. Bercabanglah pada KeyManagementException versus tipe ini untuk memisahkan “kuncinya buruk” dari “primitifnya gagal”.

SignatureLevelUnreachableException

• Kapan dilemparkan. Tingkat konformansi PAdES yang diminta tidak dapat dipenuhi di bawah infrastruktur runtime saat ini (paling sering otoritas stempel waktu yang hilang untuk B-T dan ke atas) dan pemanggil belum memberi izin untuk menurunkannya. Bawaannya adalah gagal-tertutup: mesin menolak alih-alih secara senyap menghasilkan tingkat yang lebih rendah sambil mengiklankan tingkat yang lebih tinggi, yang akan menjadi regresi berkelas-eIDAS. Selaras dengan ETSI EN 319 142-1 §6. Perhatikan kelas ini memperluas NextPdfException secara langsung (bukan SecurityException).
• Bidang konteks. requestedLevel, highestAchievableLevel, reason. Aksesor: requestedLevel(), highestAchievableLevel(), reason().
• Pemulihan. Baca reason untuk mengidentifikasi infrastruktur yang hilang dan suplaikan (misalnya konfigurasikan otoritas stempel waktu), atau teruskan allowDegradation: true ke PadesOrchestrator untuk secara sengaja menerima tingkat tertinggi yang dapat dicapai.

SignerProviderNotFoundException

• Kapan dilemparkan. SignerProviderRegistry::get() diminta untuk id penyedia yang tidak terdaftar. Mengimplementasikan PSR-11 NotFoundExceptionInterface, sehingga registri tersebut konforman dengan kontrak kontainer PSR-11. Konstruktor yang dinamai: forId(). Kelas ini memperluas RuntimeException dan tidak memaparkan getContext().
• Bidang konteks. Tidak ada. Id yang tidak terdaftar muncul dalam pesan.
• Pemulihan. Daftarkan penyedia di bawah id yang diharapkan sebelum memintanya, atau perbaiki id yang Anda teruskan ke registri.

Hashing (SHAKE256)

Ini memperluas RuntimeException dan tidak memaparkan getContext(). SHAKE256 adalah extendable-output function SHA-3 yang dibutuhkan oleh beberapa jalur ISO/TS 32001.

Shake256NotAvailableException

• Kapan dilemparkan. Pada saat digest, ketika penyedia yang dipilih tidak dapat memenuhi permintaan. Konstruktor yang dinamai: noBackend() (tidak ada backend SHAKE256 yang berfungsi pada host ini, di semua tier yang dicoba) dan ffiCallFailed() (sebuah panggilan OpenSSL EVP yang terikat-FFI mengembalikan status non-sukses, misalnya dari build libcrypto yang dipangkas).
• Bidang konteks. Tidak ada. Pesan tersebut menyebutkan tier yang dicoba atau simbol yang gagal.
• Pemulihan. Pasang ext-ffi dengan OpenSSL 3.x hadir, atau mutakhirkan ke build PHP yang memaparkan shake256 di hash_algos(). Fallback Keccak userland sengaja tidak disertakan.

Shake256ProviderNotAvailableException

• Kapan dilemparkan. Dari konstruktor penyedia SHAKE256 ketika probe kapabilitas gagal, sehingga penyedia tidak dapat diinstansiasi. Ini adalah sinyal kontrol-alur: registri penyedia menangkapnya, mencatat label tier, dan mencoba tier berikutnya. Sinyal ini tidak boleh lolos ke kode aplikasi. Konstruktor yang dinamai: forTier().
• Bidang konteks. Tidak ada. Pesan tersebut menyebutkan tier dan alasannya.
• Pemulihan. Tidak dapat ditindaklanjuti pemanggil secara langsung; jika seluruh rantai tier habis, registri justru memunculkan Shake256NotAvailableException::noBackend(), yang membawa perbaikan yang menghadap-operator.

Integritas MAC dokumen (ISO/TS 32004)

Ini mencakup message authentication code (MAC) tingkat-dokumen ISO/TS 32004, disimpan di bawah /AuthCode. Keduanya memperluas NextPdfException dan menimpa getContext().

DocumentMacTokenException

• Kapan dilemparkan. Gagal-tertutup, oleh pembaca token MAC, ketika sebuah token MAC CMS AuthenticatedData cacat secara struktural atau mendeklarasikan algoritme di luar himpunan ISO/TS 32004 yang disepakati. Konstruktor yang dinamai: malformed() dan algorithmMismatch(). Ditandai @internal.
• Bidang konteks. status (nilai DocumentMacVerificationStatus, baik MalformedToken maupun AlgorithmMismatch). Properti readonly publik: $status.
• Pemulihan. Perlakukan dokumen sebagai tidak terverifikasi. Token yang cacat atau algoritme di luar himpunan yang disepakati berarti MAC tidak dapat membangun kepercayaan; jangan melanjutkan seolah-olah konten terlindungi.

DocumentMacVerificationException

• Kapan dilemparkan. Gagal-tertutup, ketika verifikasi MAC tingkat-dokumen tidak dapat mencapai status tepercaya: /AuthCode yang hilang atau cacat, algoritme di luar himpunan yang disepakati, kegagalan unwrap, atau ketidakcocokan MAC (pengrusakan). Metode verify() verifier mengembalikan hasil eksplisit untuk percabangan; ini adalah pendamping alur-eksepsi yang dilemparkan oleh assertVerified() agar kode “percayai konten” tidak pernah dapat melanjutkan melampaui dokumen yang tidak terverifikasi. Konstruktor yang dinamai: fromResult().
• Bidang konteks. status (nilai DocumentMacVerificationStatus). Properti readonly publik: $status.
• Pemulihan. Jangan percayai konten dokumen. Periksa status untuk membedakan pengrusakan (ketidakcocokan MAC) dari masalah konfigurasi (/AuthCode yang hilang atau cacat, ketidakcocokan algoritme).

Validasi jalur PKI (RFC 5280)

Ini mencakup validasi jalur-sertifikasi RFC 5280. Tipe basis dan subkelasnya bersifat gagal-tertutup.

PkiPathValidationException

• Kapan dilemparkan. Sebuah kegagalan mode-ketat dari validator jalur RFC 5280. Ini adalah basis non-final untuk subkelas yang lebih sempit (ChainLengthExceededException, UnsupportedExtensionException), sehingga penangan yang menangkap tipe ini juga menangkap yang itu melalui substitusi Liskov. Memperluas SecurityException.
• Bidang konteks. Tidak menimpa getContext() (mewarisi bawaan kosong). Membawa alasan terstruktur dalam properti array readonly publik yang dibekukan $reasons (daftar tak-kosong berisi string nama-aturan ditambah deskripsi).
• Pemulihan. Baca $reasons untuk mengidentifikasi aturan yang gagal, perbaiki rantai sertifikat, lalu validasi ulang. Tangkap tipe ini untuk menangani setiap kegagalan validasi-jalur secara seragam.

ChainLengthExceededException

• Kapan dilemparkan. Validator jalur diminta menelusuri rantai yang panjangnya melampaui plafon yang dikonfigurasi. Batas tersebut ditegakkan sebelum penguraian apa pun dimulai, sehingga pemasok jahat tidak dapat mendorong validator ke pekerjaan kuadratik atau menguras sumber daya dengan rantai sembarang yang dalam. Plafon bawaan 10 mengikuti profil PKIX-CMP (RFC 4210 §5.3.18); rantai dunia-nyata muat dalam 5 hingga 6 entri. Subkelas dari PkiPathValidationException.
• Bidang konteks. Mewarisi getContext() kosong; string alasan chain_length_exceeded: supplied=<n> cap=<n> diteruskan ke dalam $reasons induknya. Properti readonly publik: $supplied, $cap.
• Pemulihan. Suplai rantai dalam plafon, atau naikkan batas yang dikonfigurasi jika rantai yang sah dan lebih panjang memang diharapkan.

UnsupportedExtensionException

• Kapan dilemparkan. Validator jalur menjumpai ekstensi X.509 kritis yang penegakannya belum diimplementasikan. Sesuai RFC 5280 §4.2, sebuah ekstensi kritis yang tak dikenal harus gagal-tertutup; baik mode ketat maupun lunak gagal-tertutup di sini, karena melewatkan ekstensi kritis secara senyap akan menjadi regresi keamanan. Validator mencakup pembangunan rantai, pencocokan AKI/SKI, key usage, extended key usage, basic constraints, kedaluwarsa, dan verifikasi tanda tangan; segala hal lain yang kritis muncul di sini. Subkelas dari PkiPathValidationException.
• Bidang konteks. Mewarisi getContext() kosong; alasan terstruktur diteruskan ke dalam $reasons induknya. Properti readonly publik: $extensionOid (OID bertitik, misalnya 2.5.29.30 untuk name constraints), $extensionName, $clauseRef (penunjuk ke klausul RFC 5280 dan entri log deferred-items).
• Pemulihan. Dalam mode lunak, tangkap subkelas spesifik ini untuk jatuh kembali ke kebijakan yang lebih kasar tanpa menelan kegagalan validasi-jalur yang sebenarnya. Audit $extensionOid dan $clauseRef terhadap fixture PKI Anda untuk melihat ekstensi mana yang memblokir validasi.

RevocationCheckFailedException

• Kapan dilemparkan. Baik endpoint OCSP maupun certificate revocation list (CRL) habis tanpa putusan definitif: kegagalan transport OCSP atau respons cacat, serta kegagalan transport CRL atau CRL cacat, dengan kedua circuit breaker terbuka atau kedua cache hilang. Mode ketat memperlakukan ini sebagai gagal-tertutup; mode lunak menangkapnya dan memancarkan peringatan PSR-3 dengan revocation = null. Memperluas SecurityException.
• Bidang konteks. Tidak menimpa getContext() (mewarisi bawaan kosong). Membawa status dalam properti readonly publik $ocspState dan $crlState (masing-masing default ke unknown).
• Pemulihan. Pulihkan keterjangkauan ke sumber pencabutan, tunggu circuit breaker menutup, atau panaskan cache, lalu coba lagi. Jangan menekan ini untuk memperoleh artefak long-term-validation; pernyataan pencabutan adalah bagian dari tingkat tersebut.

Verifikasi tanda tangan OCSP (RFC 6960)

OcspSignatureInvalidException

• Kapan dilemparkan. Sebuah tanda tangan BasicOCSPResponse RFC 6960 §4.2.2.2 gagal verifikasi kriptografi terhadap sertifikat responder. Parser mendekode signatureAlgorithm (RSA-PSS, ECDSA, atau RSA-PKCS1v15) dan memverifikasi signature atas tbsResponseData; kegagalan apa pun memunculkan eksepsi bertipe ini sehingga pemanggil dapat membedakan respons yang valid secara struktural tetapi dirusak secara kriptografi dari respons malformed-DER. Non-final, sehingga paket di hilir dapat menerbitkan subkelas yang lebih spesifik. Memperluas SecurityException.
• Bidang konteks. Tidak menimpa getContext() (mewarisi bawaan kosong). Membawa tag kegagalan dalam properti readonly publik $reason (misalnya signature_mismatch, responder_cert_not_in_bundle, unsupported_signature_algorithm); detail teks-bebas dilipat ke dalam pesan.
• Pemulihan. Periksa $reason. Untuk responder_cert_not_in_bundle, suplai bundel trust anchor dan sertifikat responder yang benar. Untuk signature_mismatch, perlakukan respons sebagai tidak tepercaya. Lihat Kegagalan tanda tangan dan stempel waktu.

Stempel waktu (RFC 3161)

TsaException

• Kapan dilemparkan. Sebuah kegagalan dalam komunikasi time-stamp authority (TSA) RFC 3161 atau penguraian respons: TSA mengembalikan status kesalahan, permintaan HTTP gagal, atau respons ASN.1 tidak dapat diurai. Ini adalah basis dari hierarki fault TSA dan bersifat non-final sehingga kegagalan verifikasi dapat memperluasnya. Memperluas NextPdfException.
• Bidang konteks. Tidak menimpa getContext() (mewarisi bawaan kosong).
• Pemulihan. Tangkap TsaException untuk jalur fault TSA mana pun. Verifikasi keterjangkauan TSA dan bahwa endpoint mengembalikan respons RFC 3161 yang terbentuk dengan baik.

TsaTokenVerificationException

• Kapan dilemparkan. Verifikasi CMS atas TimeStampToken RFC 3161 gagal pada salah satu langkah verifikasi yang diwajibkan: pengikatan ESSCertIDv2 RFC 5816 §3, integritas signed-attributes RFC 5652 §11, kesegaran producedAt RFC 3161 §2.4.2, atau tanda tangan SignerInfo RFC 5652 §5.4. Gagal-tertutup, dengan diskriminator langkah bertipe sehingga pipeline audit dapat membedakan replay dari clock skew dari cert-mismatch tanpa men-grep pesan. Subkelas dari TsaException, sehingga penangan catch (TsaException) lawas tetap menyala.
• Bidang konteks. step (nilai Step pipeline yang gagal) dan message. Aksesor: getStep().
• Pemulihan. Dapat ditindaklanjuti oleh pengembang (sertifikat TSA salah konfigurasi atau toleransi skew) atau keamanan (dugaan MITM atau replay). Baca step untuk melokalisasi tahap yang gagal dan perbaiki masukan atau konfigurasi trust yang sesuai.

MalformedDerException

• Kapan dilemparkan. Sinyal internal bahwa sebuah penelusuran DER mengenai batas yang cacat atau terpotong, dimunculkan oleh walker tingkat-rendah di dalam verifier token TSA. Sinyal ini selalu ditangkap pada batas verify publik dan dibungkus ulang menjadi TsaTokenVerificationException yang membawa diskriminator langkah yang tepat; sinyal ini tidak pernah bocor ke kode pemanggil. Memperluas RuntimeException; ditandai @internal.
• Bidang konteks. Tidak ada.
• Pemulihan. Tidak menghadap-pemanggil. Tangani TsaTokenVerificationException yang membungkusnya sebagai gantinya.

Pendekodean ekstensi-sertifikat

Ini memperluas RuntimeException dan tidak memaparkan getContext(). Keduanya adalah dekoder gagal-tertutup.

NameConstraintsDecodeException

• Kapan dilemparkan. Dekoder name-constraints menjumpai elemen GeneralSubtree yang dapat-ditegakkan yang tidak dapat didekodenya dengan setia. RFC 5280 §4.2.1.10 mewajibkan pihak yang mengandalkan untuk memproses name constraint yang dapat-ditegakkan atau menolak sertifikat; mengonversi penghapusan-senyap sebelumnya menjadi kegagalan bertipe ini mencegah fail-open yang akan secara senyap memperluas himpunan nama yang diterima. Cakupannya terbatas pada bentuk nama yang dapat-ditegakkan (directoryName, dNSName, iPAddress, rfc822Name, uniformResourceIdentifier); bentuk yang tidak-dapat-ditegakkan tetap dapat diabaikan dan tidak pernah memunculkannya. Konstruktor yang dinamai: undecodableEnforceableBase(). Ditandai @internal.
• Bidang konteks. Tidak ada. String detail yang aman-log dibawa dalam pesan.
• Pemulihan. Penegak memunculkan alasan gagal-tertutup name_constraints: dan rantai ditolak. Selidiki pengkodean name-constraints sertifikat; jangan melonggarkan penegakan.

QcStatementsDecodeException

• Kapan dilemparkan. Ekstensi qcStatements cacat secara struktural: DER terpotong, tag salah, atau overflow panjang. Dekoder bersifat gagal-tertutup dan memunculkan alih-alih mengembalikan hasil parsial atau heuristik ketika tidak dapat menentukan dengan pasti apa yang dikatakan ekstensi tersebut. Ditandai @api.
• Bidang konteks. Tidak ada.
• Pemulihan. Tangkap secara eksplisit hanya jika Anda berniat menoleransi pengkodean yang cacat; jika tidak, perlakukan pernyataan qualified-certificate sertifikat sebagai tak-dapat-ditentukan dan tolak atau terbitkan ulang sertifikatnya.

Sesi PKCS#11

Pkcs11SessionException

• Kapan dilemparkan. Sebuah cacat manajemen-sesi PKCS#11 v3.1. Setiap konstruktor yang dinamai memetakan ke kelas cacat tertentu dan ke nilai-balik PKCS#11 CKR_*, dipaparkan melalui diskriminator $kind bertipe sehingga pemanggil bercabang pada string-enum yang stabil alih-alih pencocokan pesan yang rapuh. Konstruktor mencakup: cryptokiNotInitialized(), userNotLoggedIn(), userAlreadyLoggedIn(), operationNotInitialized(), operationActive(), mechanismNotAllowed(), tokenDisconnected(), concurrentSessionLimitExceeded(), sessionAlreadyClosed(), stateTransitionInvalid(), osLockingRequired(), loginTtlExpired(), dan signOperationTtlExpired(). Memperluas SecurityException.
• Bidang konteks. Tidak menimpa getContext() (mewarisi bawaan kosong). Membawa kind bertipe dalam properti readonly publik $kind, salah satu dari konstanta KIND_* (misalnya KIND_USER_NOT_LOGGED_IN, KIND_TOKEN_DISCONNECTED, KIND_LOGIN_TTL_EXPIRED). Pengenal slot dan sesi, mekanisme, dan nilai TTL muncul dalam pesan. PIN dan byte sertifikat tidak pernah disertakan.
• Pemulihan. Bercabanglah pada $kind. Untuk user_not_logged_in, masuk dengan PIN pengguna sebelum menginisialisasi operasi sign. Untuk token_disconnected, perlakukan semua sesi pada slot tersebut sebagai telantar. Untuk kind TTL, autentikasi ulang atau inisialisasi ulang operasi. Untuk mechanism_not_allowed, perluas allow-list mekanisme yang dikonfigurasi atau pilih mekanisme yang diizinkan.

Lihat juga

• Indeks referensi kesalahan
• Kegagalan tanda tangan dan stempel waktu
• Enkripsi dan izin
• Validasi PDF/A dan PDF/UA