Keamanan dan operasional compat-legacy

Sekilas

Adaptor ini menggunakan model keamanan mesin NextPDF dan menambahkan beberapa pengetatan yang disengaja terhadap perilaku lama TCPDF 6.2.13. Halaman ini menjelaskan secara tepat apa yang tersedia dan apa yang tidak, tanpa klaim berlebihan. Bacalah bagian penandatanganan dengan saksama; cakupannya memang sengaja dibuat sempit.

Perilaku legacy yang diperketat

Adaptor mengubah tiga perilaku historis TCPDF 6.2.13 demi keamanan. Perilaku tersebut tidak dapat dikonfigurasi kembali ke bentuk yang tidak aman:

Perhatian	TCPDF 6.2.13 lama	Adaptor
Penanganan kesalahan	Error() memanggil die() dan menghentikan proses	Error() melempar RuntimeException; pemanggil dapat mengamati dan menangkap kegagalan tersebut tanpa mematikan proses secara diam-diam.
Eksekusi HTML	Sebuah celah pelarian dapat menjalankan PHP dari markup	Konstanta K_TCPDF_CALLS_IN_HTML ditetapkan ke false; markup tidak dapat memicu eksekusi PHP.
Keluaran langsung	Output() menulis langsung ke buffer keluaran yang aktif	Keluaran dirutekan melalui jembatan tujuan yang aman dan tidak mencemari buffer keluaran yang dikendalikan oleh pemanggil.

Perubahan penanganan kesalahan memastikan Anda dapat mengamati kegagalan, bukan kehilangan proses akibat penghentian. Open Worldwide Application Security Project (OWASP) Application Security Verification Standard (ASVS) 5.0 §16.5.3 menyatakan bahwa aplikasi harus gagal secara anggun dan aman serta mencegah kondisi fail-open. Perubahan yang melempar alih-alih menghentikan proses menerapkan prinsip tersebut. Pengetatan HTML menghapus saluran eksekusi kode. Perlakukan kode legacy yang bergantung pada perilaku lama sebagai cacat yang harus diperbaiki saat mengikuti /integrations/tcpdf-compat/migration/. Ringkasan klausa yang dijadikan acuan berada di citations pada front-matter halaman.

Enkripsi

Adaptor mengekspos SetProtection() milik TCPDF dan mendelegasikannya ke penangan keamanan standar mesin NextPDF.

• Penangan standar menggunakan AES-256. Parameter $mode lama diterima demi kompatibilitas tanda tangan metode dan diabaikan; tidak ada cara untuk memilih cipher yang lebih lemah melalui metode ini. Ketika mode ketat aktif, $mode non-standar akan melempar sehingga migrasi harus mengakuinya secara eksplisit (ditegaskan dalam tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php).
• Jika tidak ada kata sandi pemilik yang diberikan, adaptor menghasilkan kata sandi pemilik acak yang kuat secara kriptografis alih-alih menggunakan kembali kata sandi pengguna. Hal ini mencegah pemegang akses tingkat pengguna memperoleh kendali tingkat pemilik atas dokumen.
• Enkripsi berbasis sertifikat (kunci publik) tidak dilakukan melalui SetProtection(); adaptor mengabaikan parameter $pubkeys pada metode tersebut. Gunakan titik masuk enkripsi kunci publik modern yang diekspos pada adaptor (setPublicKeyEncryption()), yang mendelegasikan ke mesin.

Perilaku enkripsi mengikuti penangan keamanan standar yang dijelaskan dalam ISO 32000-2 §7. Klausa tersebut mendefinisikan entri kamus enkripsi dan penangan standar AES-256 yang digunakan mesin. Dokumentasi ini tidak mengeklaim bahwa keluaran “aman secara default” atau “antirusak”. Dokumentasi ini hanya menyatakan cipher yang digunakan dan perilaku kata sandi pemilik yang diimplementasikan oleh kode. Ringkasan klausa yang dijadikan acuan berada di citations pada front-matter halaman.

examples/security-encryption.php

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
$pdf->AddPage();
$pdf->SetFont('helvetica', '', 12);
$pdf->Cell(0, 10, 'Encrypted document');

// User password set; owner password auto-generated (strong, random).
$pdf->SetProtection([], 'user-secret');

$pdf->Output(__DIR__ . '/encrypted.pdf', 'F');

Tanda tangan digital — pernyataan cakupan

Bacalah bagian ini secara harfiah. Bagian ini sengaja dibuat konservatif.

• Metode legacy TCPDF setSignature() dan addEmptySignatureAppearance() tidak diimplementasikan pada adaptor di mesin inti. Dalam mode default, keduanya tidak melakukan apa pun. Dalam mode ketat, keduanya melempar TcpdfNotImplementedException.
• Penandatanganan digital bukan kemampuan distribusi inti melalui adaptor ini. Dukungan tanda tangan baseline memerlukan edisi NextPDF komersial.
• Jika edisi komersial tersedia, adaptor mengekspos titik masuk tanda tangan modern (setSignatureV2()) yang mendelegasikan ke mesin. Profil defaultnya adalah profil baseline (B-B).
• Dokumentasi ini tidak membuat klaim bahwa edisi mana pun menghasilkan profil tanda tangan bertanda waktu, long-term-validation, atau arsip melalui adaptor ini. Secara khusus, dokumentasi ini tidak menegaskan perilaku B-T, B-LT, atau B-LTA. Spesifikasi baseline PDF Advanced Electronic Signatures (PAdES) §6.1 mendefinisikan empat tingkat baseline yang berbeda: B-B, B-T, B-LT, dan B-LTA. Masing-masing memiliki persyaratannya sendiri. B-B adalah tingkat baseline, sedangkan tingkat yang lebih tinggi (timestamp, long-term, arsip) merupakan profil terpisah yang lebih menuntut. Hanya baseline B-B yang berada dalam cakupan dokumentasi lapisan kompatibilitas ini. Tingkat yang lebih tinggi secara eksplisit berada di luar cakupan dan tidak diklaim untuk edisi mana pun di sini. Ringkasan klausa yang dijadikan acuan berada di citations pada front-matter halaman.
• Dokumentasi ini tidak membuat klaim tanda tangan “tersertifikasi”, “terjamin”, “sah secara hukum”, atau “eIDAS-qualified” di mana pun. Ketepatan penandatanganan, kebijakan trust-anchor, dan keabsahan hukum merupakan tanggung jawab edisi penandatangan dan Public Key Infrastructure (PKI) milik pemanggil, bukan tanggung jawab lapisan kompatibilitas ini.

Jika migrasi Anda memerlukan penandatanganan, perlakukan kebutuhan tersebut sebagai aliran kerja terpisah: adopsi application programming interface (API) tanda tangan modern pada edisi komersial dan validasi tanda tangan yang dihasilkan dengan verifikator independen. Jangan mengandalkan panggilan TCPDF setSignature(); di sini panggilan tersebut adalah no-op.

Metode lama setTimeStamp() diterima demi kompatibilitas tanda tangan metode dan memunculkan pemberitahuan; metode ini tidak menghasilkan tanda tangan bertanda waktu melalui adaptor ini.

PDF/A dan konformansi

Bendera pdfa pada konstruktor diterima demi kompatibilitas tanda tangan metode. Konformansi arsip PDF/A memerlukan edisi NextPDF komersial. Adaptor mengekspos enablePdfA(), yang mendelegasikan ke mesin, dan mesin mengembalikan kesalahan konfigurasi yang dapat ditindaklanjuti ketika edisi yang diperlukan tidak ada. Adaptor tidak diam-diam menghasilkan berkas yang tidak konforman sambil mengeklaim PDF/A.

Keluaran selalu PDF 2.0 (ISO 32000-2). ISO 32000-2 §7.5.2 menetapkan bahwa penulis yang konforman mengidentifikasi versi dokumen sebagai 2.0 dan tidak menurunkannya ke versi yang lebih lama saat menyimpan. Oleh karena itu, setPDFVersion() tidak dapat digunakan untuk menargetkan versi yang lebih lama (lihat /integrations/tcpdf-compat/method-coverage/ §4). Ringkasan klausa yang dijadikan acuan berada di citations pada front-matter halaman.

Panduan operasional

• Tanpa penghentian proses. Karena Error() melempar alih-alih die(), bungkus titik masuk render dalam try/catch dan petakan kegagalan ke kontrak kesalahan aplikasi Anda. Jangan berasumsi bahwa render yang gagal akan mengakhiri permintaan.
• Keamanan buffer keluaran. Output() dengan S mengembalikan byte; dengan F menulis berkas; dengan E mengembalikan body Multipurpose Internet Mail Extensions (MIME) base64; dengan I/D keluaran dirutekan melalui jalur keluaran mesin. Utamakan S atau F pada worker dan penangan Hypertext Transfer Protocol (HTTP) agar Anda sendiri yang mengendalikan respons; lihat /integrations/tcpdf-compat/production-usage/.
• Mode ketat bukan pengaturan produksi. Batasi pada pekerjaan continuous integration (CI) atau audit. Eksepsi pada jalur render produksi lebih buruk daripada parameter yang diturunkan secara diam-diam.
• Pengelolaan konstanta. Definisikan konstanta PDF_* / K_* sebelum konstruksi adaptor pertama. Kedua bendera yang diperketat (K_TCPDF_CALLS_IN_HTML, K_TCPDF_THROW_EXCEPTION_ERROR) tidak dapat dilonggarkan; jangan mencoba melonggarkannya.
• Kata sandi pemilik acak. Jika Anda mengandalkan kata sandi pemilik yang deterministik, tetapkan secara eksplisit. Jika tidak, kata sandi acak yang kuat dihasilkan per dokumen dan tidak dapat dipulihkan.

Catatan model ancaman

• Untuk metode gambar, adaptor menolak jalur stream-wrapper sebelum pembacaan sistem berkas apa pun. Deteksi tipe gambar (TcpdfImages::getImageFileType) memperlakukan jalur scheme:// apa pun, termasuk phar://, php://, dan pembungkus aliran PHP lainnya, sebagai pembungkus dan melewati pemeriksaan file_get_contents / getimagesize, lalu kembali hanya ke inferensi berbasis ekstensi. Hal ini menutup vektor deserialisasi metadata phar pada target backport PHP 7.4; mesin sendiri menolak penyematan jalur wrapper tersebut.
• Adaptor tidak menambahkan validasi atau sanitasi jalur untuk jalur berkas yang diteruskan ke metode gambar atau keluaran selain yang dilakukan mesin. Perlakukan jalur dan URL yang disuplai pemanggil sebagai tidak tepercaya di batas aplikasi Anda.
• HTML yang diteruskan ke metode HTML dirender oleh mesin, bukan oleh parser HTML TCPDF. Saluran eksekusi PHP lama telah ditutup, tetapi Anda tetap harus memperlakukan HTML yang disuplai pemanggil sebagai masukan yang tidak tepercaya.
• Enkripsi melindungi kerahasiaan dokumen saat disimpan di bawah penangan standar. Enkripsi bukan pengganti keamanan transport atau kontrol akses dalam aplikasi Anda.

Lihat juga

• /integrations/tcpdf-compat/method-coverage/ — perilaku persis dari SetProtection(), setSignature()
• /integrations/tcpdf-compat/configuration/ — kedua bendera yang diperketat dan tidak dapat dikonfigurasi
• /integrations/tcpdf-compat/production-usage/ — worker, buffer, penanganan kegagalan
• docs/TCPDF_COVERAGE.md — matriks cakupan otoritatif
• NOTICE paket — pernyataan implementasi independen