Pemecahan masalah: enkripsi dan flag izin

Cakupan dan batasan

Gunakan entri ini untuk menelusuri kegagalan dekripsi yang dilemparkan mesin melalui NextPDF\Exception\EncryptionException dan NextPDF\Security\Exception\DecryptionFailedException, serta untuk memahami batasan flag izin Portable Document Format (PDF).

Mulailah dari batasannya, karena ini mencegah kesalahpahaman yang paling umum: flag izin PDF dalam kamus enkripsi mencatat maksud penulis. Flag ini bukan mekanisme kontrol akses yang ditegakkan oleh pustaka ini. Pembaca yang mengabaikan flag tersebut tetap dapat mencetak, menyalin, atau mengubah konten. Perlakukan flag tersebut sebagai permintaan kepada pembaca yang kooperatif, bukan sebagai mekanisme penegakan.

Entri: operasi enkripsi gagal

• Gejala. EncryptionException dengan pesan berbentuk Encryption operation "<op>" failed using algorithm "<algorithm>".
• Kemungkinan penyebab. Operasi sandi tidak dapat dijalankan, biasanya karena ekstensi OpenSSL tidak tersedia atau salah konfigurasi, materi kunci tidak valid, atau ukuran initialization vector (IV) tidak valid pada batas sandi.
• Bukti / diagnosis. getContext() mengembalikan algorithm dan operation. Nilai operation adalah salah satu dari encrypt, decrypt, atau key_derivation, sehingga Anda dapat mengidentifikasi tahap mana yang gagal.
• Penyelesaian.
  1. Pastikan ekstensi PHP OpenSSL telah terpasang dan dimuat.
  2. Gunakan bidang operation untuk menemukan tahap yang gagal.
  3. Untuk key_derivation, verifikasi masukan kata sandi atau kunci.
  4. Jalankan ulang pemanggilan tersebut.
• Terkait. Referensi exception.

Entri: dekripsi gagal karena alasan struktural

• Gejala. DecryptionFailedException dengan pesan berbentuk Decryption failed for "<algorithm>": <reason>.
• Kemungkinan penyebab. Ciphertext tidak dapat diproses bukan karena pengusikan, melainkan karena alasan seperti ciphertext yang terpotong, IV yang hilang, atau kunci yang keliru diberikan pada batas application programming interface (API). Pemeriksaan integritas tidak berjalan karena tidak ada cukup materi yang dapat dievaluasi.
• Bukti / diagnosis. getContext() mengembalikan algorithm dan reason. Dokumentasi sumber membedakan DecryptionFailedException dari TamperedDataException: exception ini berarti kesalahan konfigurasi atau transport, bukan pengusikan. Jangan memperlakukannya sebagai insiden keamanan dengan sendirinya.
• Penyelesaian.
  1. Baca reason untuk mengidentifikasi cacat struktural, misalnya ciphertext shorter than IV+tag.
  2. Verifikasi bahwa ciphertext ditransfer tanpa terpotong.
  3. Pastikan kunci yang diberikan pada batas adalah kunci yang digunakan untuk mengenkripsi dokumen.
  4. Jalankan ulang pemanggilan tersebut.
• Terkait. Kegagalan tanda tangan dan stempel waktu.

Entri: exception “tampered data” dilemparkan

• Gejala. Anda menerima NextPDF\Security\Exception\TamperedDataException alih-alih DecryptionFailedException.
• Kemungkinan penyebab. Pemeriksaan integritas berjalan dan gagal. Ini berbeda dari kegagalan dekripsi struktural: materi yang tersedia cukup untuk mengevaluasi integritas, dan integritas tidak terpenuhi.
• Bukti / diagnosis. Sumber membedakan kedua kelas tersebut: DecryptionFailedException bersifat struktural dan bukan insiden keamanan; TamperedDataException menunjukkan bahwa konten terautentikasi gagal diverifikasi.
• Penyelesaian.
  1. Perlakukan masukan sebagai tidak tepercaya; jangan gunakan konten yang telah didekripsi.
  2. Ambil ulang dokumen dari sumber yang tepercaya.
  3. Jika kegagalan tetap terjadi dengan sumber yang diketahui baik, tangkap getContext() untuk laporan insiden.
• Terkait. Kegagalan tanda tangan dan stempel waktu.

Entri: flag izin tidak menghentikan tindakan di hilir

• Gejala. Sebuah dokumen dibuat dengan flag izin yang disetel — misalnya, penyalinan atau pencetakan dilarang — tetapi pembaca tetap menyalin atau mencetak kontennya.
• Kemungkinan penyebab. Ini adalah batasan yang memang diharapkan, bukan cacat. Bilangan bulat izin yang diberikan ke pembangun kamus enkripsi core tidak diterapkan sebagai penegakan oleh pustaka ini. Flag tersebut adalah metadata yang bersifat anjuran; pembaca yang tidak mematuhinya tidak diblokir oleh NextPDF.
• Bukti / diagnosis. src/Security/Encryption/EncryptionDictionaryBuilder.php mendeklarasikan buildDict(int $permissions, string $fileId), dan mendokumentasikan parameter tersebut sebagai ignored; retained for forward compatibility. Metode tersebut diawali dengan unset($permissions, $fileId). Flag izin yang ditampilkan oleh src/Inspect/PdfPermissions.php adalah bidang inspeksi baca-saja, bukan lapisan penegakan.
• Penyelesaian.
  1. Jangan mengandalkan flag izin untuk menghentikan pencetakan, penyalinan, atau pengubahan. Flag tersebut tidak dapat ditegakkan oleh pustaka penghasil.
  2. Jika Anda harus membatasi akses, kendalikan distribusi berkasnya sendiri, atau terapkan sistem kontrol akses di luar PDF.
  3. Gunakan PdfPermissions hanya untuk melaporkan flag yang dideklarasikan oleh dokumen yang ada, bukan untuk menyatakan bahwa tindakan tersebut dicegah.
• Terkait. Kegagalan tanda tangan dan stempel waktu.

Entri: enkripsi ditolak di bawah PDF/A

• Gejala. NextPDF\Security\Exception\IncompatiblePdfAModeException ketika suatu build mengaktifkan PDF/A dan meminta enkripsi.
• Kemungkinan penyebab. Profil PDF/A melarang kunci Encrypt dalam trailer. Mesin menolak kombinasi tersebut dalam urutan pemanggilan mana pun.
• Bukti / diagnosis. Lihat entri PDF/A dan PDF/UA untuk klausul yang dikutip, bidang getContext(), dan pengujian jalur kegagalan.
• Penyelesaian.
  1. Putuskan apakah dokumen memerlukan konformansi arsip atau enkripsi.
  2. Hapus pemanggilan untuk properti yang tidak Anda perlukan.
  3. Jalankan ulang pipeline.
• Terkait. Validasi PDF/A dan PDF/UA.

Kasus tepi & jebakan

• DecryptionFailedException dan TamperedDataException berarti hal yang berbeda: kegagalan struktural versus integritas yang gagal. Lakukan percabangan berdasarkan kelas, bukan berdasarkan pesan.
• Pembangun kamus enkripsi core mengabaikan bilangan bulat izin; setiap build yang bergantung pada penegakan izin dari paket core dibangun di atas kesalahpahaman.
• PdfPermissions hanya diisi untuk dokumen terenkripsi pada kedalaman inspeksi penuh dan mencerminkan flag yang dideklarasikan. Bidang yang terisi tidak berarti tindakan tersebut dicegah.

Lihat juga

• Referensi exception
• Kegagalan tanda tangan dan stempel waktu
• Validasi PDF/A dan PDF/UA
• Indeks basis pengetahuan

Glosarium: flag izin · dekripsi terautentikasi