Pemecahan masalah: kegagalan tanda tangan dan stempel waktu

Cakupan

Daftar entri ini mencakup kegagalan tanda tangan yang dilaporkan melalui NextPDF\Exception\SignatureException dan NextPDF\Security\Signature\Exception\SignatureLevelUnreachableException. Setiap entri menyebutkan metode factory atau kelas yang tepat agar Anda dapat memastikan penyebabnya dari pesan dan getContext(), bukan menebak-nebak.

Catatan istilah: mesin ini tidak menyertifikasi tanda tangan sebagai valid atau dokumen sebagai terlindungi. Mesin hanya melaporkan kegagalan yang terdeteksi. Perlakukan setiap solusi sebagai langkah untuk menghilangkan penyebab yang dilaporkan.

Entri: tingkat PAdES “B-LT” atau “B-LTA” tidak dapat dihasilkan

• Gejala. SignatureException dengan akhiran pesan nextpdf/enterprise package is required for B-LT/B-LTA signatures.
• Kemungkinan penyebab. Penyedia kapabilitas validasi jangka panjang tidak tersedia. B-LT dan B-LTA menyematkan materi pencabutan serta stempel waktu arsip, dan penyedia tersebut disertakan dalam nextpdf/enterprise.
• Bukti / diagnosis. Factory SignatureException::ltvCapabilityMissing() menghasilkan pesan ini persis. getContext() mengembalikan signature_level yang disetel ke tingkat yang Anda coba gunakan.
• Solusi.
  1. Pasang penyedia tersebut dengan menjalankan composer require nextpdf/enterprise.
  2. Jalankan kembali panggilan penandatanganan.
  3. Jika Anda tidak dapat memasang penyedia tersebut, minta B-B atau B-T sebagai gantinya, yang dapat dihasilkan oleh paket core.
• Terkait. Referensi eksepsi.

Entri: tingkat tanda tangan tidak dapat dicapai dan panggilan ditolak

• Gejala. SignatureLevelUnreachableException dengan pesan berbentuk PAdES level "<x>" is unreachable (highest achievable: "<y>").
• Kemungkinan penyebab. Tingkat kesesuaian yang diminta membutuhkan infrastruktur yang tidak tersedia saat penandatanganan, paling sering berupa otoritas stempel waktu untuk B-T dan yang lebih tinggi. Mesin bersifat gagal-tertutup: mesin tidak menurunkan tingkat secara diam-diam lalu mengeklaim tingkat yang lebih tinggi.
• Bukti / diagnosis. getContext() mengembalikan requestedLevel, highestAchievableLevel, dan reason. Bidang reason mengidentifikasi celah infrastruktur. Ini adalah perilaku gagal-tertutup bawaan yang diperkenalkan untuk mencegah dokumen mengeklaim tingkat yang tidak benar-benar dipenuhi.
• Solusi.
  1. Baca bidang reason untuk mengidentifikasi infrastruktur yang hilang.
  2. Sediakan komponen yang hilang. Misalnya, konfigurasikan otoritas stempel waktu, lalu jalankan kembali panggilan tersebut.
  3. Untuk secara sengaja menerima tingkat yang lebih rendah, teruskan allowDegradation: true ke PadesOrchestrator. Panggilan tersebut kemudian menghasilkan highestAchievableLevel dan melaporkan tingkat yang dihasilkannya.
• Terkait. Enkripsi dan izin.

Entri: klien otoritas stempel waktu diperlukan tetapi tidak ada

• Gejala. SignatureException dengan akhiran TSA client is required for level <x> but none was provided.
• Kemungkinan penyebab. Permintaan untuk B-T, B-LT, atau B-LTA membutuhkan klien otoritas stempel waktu, tetapi orkestrator tidak memilikinya.
• Bukti / diagnosis. Factory SignatureException::tsaRequired() menghasilkan pesan ini; getContext() membawa signature_level yang dicoba.
• Solusi.
  1. Konfigurasikan klien otoritas stempel waktu dan teruskan ke orkestrator.
  2. Jalankan kembali panggilan tersebut.
  3. Untuk menghasilkan tingkat yang tidak memerlukan stempel waktu, mintalah B-B.
• Terkait. Referensi eksepsi.

Entri: URL endpoint otoritas stempel waktu kosong

• Gejala. SignatureException dengan akhiran TSA endpoint URL is empty.
• Kemungkinan penyebab. Klien otoritas stempel waktu dibuat dengan URL endpoint kosong.
• Bukti / diagnosis. Factory SignatureException::tsaUrlEmpty() menghasilkan pesan ini. Ini merupakan cacat konfigurasi, bukan kegagalan jaringan.
• Solusi.
  1. Tetapkan URL endpoint yang tidak kosong pada klien otoritas stempel waktu, seperti https://timestamp.example.com/tsa.
  2. Jika tingkat yang diminta tidak memerlukan stempel waktu, hapus pengabelan klien otoritas stempel waktu tersebut.
  3. Jalankan kembali panggilan tersebut.
• Terkait. Referensi eksepsi.

Entri: placeholder tanda tangan tidak ada dalam buffer

• Gejala. SignatureException dengan akhiran no /Contents <…> field found in PDF buffer (signature placeholder missing).
• Kemungkinan penyebab. Tahap penandatanganan menerima buffer tanpa kontainer tanda tangan yang dicadangkan, sehingga tidak ada tempat untuk menulis tanda tangan.
• Bukti / diagnosis. Factory SignatureException::signatureContentsNotFound() menghasilkan pesan ini.
• Solusi.
  1. Pastikan bidang tanda tangan dan placeholder-nya ditulis sebelum tahap penandatanganan berjalan.
  2. Jalankan ulang alur pipa agar placeholder tersedia saat penandatanganan dimulai.
• Terkait. Referensi eksepsi.

Entri: status pencabutan tidak diketahui (responder OCSP menolak)

• Gejala. SignatureException dengan akhiran OCSP responder returned non-successful OCSPResponseStatus "<status>".
• Kemungkinan penyebab. Responder Online Certificate Status Protocol (OCSP) tidak mengembalikan status successful, sehingga tidak menghasilkan pernyataan pencabutan. Mesin mengikuti RFC 6960 §4.2.1, yang dikutipnya dalam kode sumber: badan respons yang terisi hanya diizinkan untuk status successful (0). Mesin menolak memperlakukan respons yang ditolak sebagai hasil positif yang tepercaya.
• Bukti / diagnosis. Factory SignatureException::nonSuccessfulOcspResponseStatus() menghasilkan pesan ini dan menyebutkan status yang dilaporkan, seperti tryLater atau internalError. Byte status yang dicadangkan atau tidak diketahui menghasilkan SignatureException::reservedOcspResponseStatus().
• Solusi.
  1. Identifikasi status dalam pesan tersebut. Untuk status sementara seperti tryLater, coba ambil data pencabutan lagi nanti.
  2. Untuk unauthorized atau malformedRequest, verifikasi URL permintaan OCSP dan sertifikat yang diharapkan oleh responder.
  3. Jangan menutupi kegagalan memperoleh artefak B-LT atau B-LTA; pernyataan pencabutan adalah bagian dari tingkat tersebut.
• Terkait. Referensi eksepsi.

Entri: entri rantai sertifikat gagal didekode

• Gejala. SignatureException dengan akhiran failed to base64-decode PEM body — input is not valid PEM.
• Kemungkinan penyebab. Salah satu entri rantai sertifikat bukan Privacy-Enhanced Mail (PEM) yang valid, biasanya karena terpotong, berisi karakter yang tidak semestinya, atau berisi blob biner Distinguished Encoding Rules (DER) di tempat yang seharusnya berupa PEM.
• Bukti / diagnosis. Factory SignatureException::pemDecodingFailed() menghasilkan pesan ini selama perakitan rantai.
• Solusi.
  1. Periksa setiap sertifikat dalam rantai untuk karakter yang tidak semestinya atau bagian yang terpotong.
  2. Ekspor ulang sertifikat yang terdampak dalam bentuk PEM.
  3. Jalankan kembali panggilan penandatanganan.
• Terkait. Enkripsi dan izin.

Entri: tipe kunci privat tidak cocok dengan algoritme

• Gejala. SignatureException dengan akhiran expected private key of type "<x>" for the configured algorithm but got "<y>".
• Kemungkinan penyebab. Kunci privat yang dimuat tidak cocok dengan algoritme tanda tangan yang dikonfigurasi, seperti kunci Rivest-Shamir-Adleman (RSA) dengan pilihan Elliptic Curve Digital Signature Algorithm (ECDSA).
• Bukti / diagnosis. Factory SignatureException::unexpectedKeyType() menghasilkan pesan ini dan menyebutkan kelas kunci yang diharapkan maupun yang sebenarnya.
• Solusi.
  1. Verifikasi bahwa pasangan sertifikat dan kunci cocok dengan algoritme yang Anda pilih.
  2. Sesuaikan pilihan algoritme dengan kunci, atau muat kunci yang cocok dengan algoritme.
  3. Jalankan kembali panggilan penandatanganan.
• Terkait. Referensi eksepsi.

Entri: kunci atau materi tanda tangan Ed25519 cacat format

• Gejala. SignatureException dengan akhiran yang menyebutkan ketidakcocokan panjang Ed25519 — misalnya Ed25519 signature length <n> ≠ expected 64 bytes, atau Ed25519 round-trip self-verify failed.
• Kemungkinan penyebab. Build kriptografi pada runtime mengembalikan materi kunci atau tanda tangan dengan panjang yang salah, atau tanda tangan yang baru dihasilkan gagal diverifikasi terhadap kunci publiknya sendiri. Mesin mengutip RFC 8032 §3.4 dalam kode sumber, yang menetapkan tanda tangan Ed25519 terpisah berukuran 64 byte. Mesin membatalkan operasi alih-alih menghasilkan materi yang tidak dapat diverifikasinya sendiri.
• Bukti / diagnosis. Factory yang relevan adalah SignatureException::ed25519SignatureMalformed(), ::ed25519RoundTripVerifyFailed(), ::ed25519KeyParseFailed(), ::ed25519SeedInvalid(), ::ed25519SecretKeyMalformed(), dan ::ed25519PublicKeyInvalid(). Masing-masing menyebutkan panjang yang teramati.
• Solusi.
  1. Pasang ulang ekstensi PHP libsodium; build yang dipangkas atau rusak adalah penyebab terdokumentasi dari materi dengan panjang yang salah.
  2. Pastikan kunci tersebut adalah kunci Ed25519 dan OpenSSL berversi 1.1.1 atau lebih baru.
  3. Jalankan kembali panggilan penandatanganan.
• Terkait. Referensi eksepsi.

Entri: kamus stempel waktu arsip tidak ditulis

• Gejala. SignatureException dengan akhiran no /Type /DocTimeStamp dictionary was emitted into the PDF buffer.
• Kemungkinan penyebab. Loop arsip B-LTA berjalan, tetapi kamus stempel waktu dokumen tidak pernah mencapai buffer. Artefak yang dihasilkan akan berupa B-LTA yang tertulis sebagian, sehingga mesin menolak mengembalikannya.
• Bukti / diagnosis. Factory SignatureException::documentTimestampNotEmitted() menghasilkan pesan ini. Kegagalan pascakondisi ini muncul saat finalisasi.
• Solusi.
  1. Anggap keluaran tersebut harus dibuang; jangan kirimkan artefak yang tidak utuh.
  2. Jalankan ulang alur pipa B-LTA dengan otoritas stempel waktu yang dapat dijangkau.
  3. Jika kegagalan berulang, tangkap getContext() dan eksepsi sebelumnya yang terangkai untuk laporan cacat.
• Terkait. Referensi eksepsi.

Kasus khusus & jebakan

• Semua factory ini menyetel cert_info ke subjek atau thumbprint hanya jika tersedia; cert_info yang kosong wajar terjadi untuk kegagalan kapabilitas dan konfigurasi.
• Permintaan B-LT atau B-LTA tanpa klien Hypertext Transfer Protocol (HTTP) yang dikonfigurasi memunculkan SignatureException::httpClientMissing(); pengambilan data pencabutan membutuhkan klien PHP Standards Recommendation (PSR)-18 yang diteruskan ke orkestrator.
• Sertifikat yang didukung oleh hardware security module (HSM) tanpa implementasi signer memunculkan SignatureException::hsmSignerMissing(); pasang signer pada sertifikat sebelum penandatanganan.

Lihat juga

• Referensi eksepsi
• Enkripsi dan izin
• Indeks basis pengetahuan

Glosarium: tingkat PAdES · pernyataan pencabutan