Enkripsi (HasSecurity)

Trait HasSecurity pada Document menyediakan enkripsi AES-256 melalui engine Aes256Encryptor. TCPDF-Next secara eksklusif mengimplementasikan security handler PDF 2.0 (AESV3, Revision 6, V5) — RC4 dan AES-128 sengaja dihapus. Password dinormalisasi melalui SASLprep (RFC 4013) untuk penanganan Unicode yang benar, dan key derivation menggunakan Algorithm 2.B (iteratif SHA-256/384/512).

Referensi Cepat

Method	Deskripsi
setProtection()	Aktifkan enkripsi AES-256 dengan permission dan password

Mengaktifkan Enkripsi

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->setProtection(
        permissions: ['print', 'copy'],
        userPass: 'reader-password',
        ownerPass: 'owner-secret-password',
    )
    ->addPage()
    ->setFont('Helvetica', '', 12)
    ->cell(0, 10, 'PDF ini dienkripsi AES-256', newLine: true)
    ->save('encrypted.pdf');

setProtection() mengembalikan static, sehingga bisa di-chain dengan setiap method Document lainnya.

$pdf->setProtection(
    array  $permissions = [],   // Flag permission (lihat tabel di bawah)
    string $userPass    = '',   // Password diperlukan untuk membuka dokumen
    string $ownerPass   = '',   // Password untuk akses tidak terbatas
);

User Password vs Owner Password

• User password — pembaca harus memasukkan password ini untuk membuka dan melihat PDF. Jika kosong, dokumen terbuka tanpa prompt tetapi pembatasan permission tetap berlaku.
• Owner password — memberikan akses penuh ke dokumen, melewati semua pembatasan permission. Jika kosong, owner password acak 32-byte dihasilkan secara internal.

Kedua password dinormalisasi melalui SASLprep (RFC 4013) sebelum key derivation. Ini memastikan password Unicode seperti "Pässwörd" ditangani secara konsisten di semua PDF viewer.

Flag Permission

Berikan kombinasi apapun dari flag string ini dalam array $permissions:

Flag	Deskripsi
print	Izinkan pencetakan (resolusi rendah)
modify	Izinkan modifikasi konten
copy	Izinkan ekstraksi teks dan gambar
annotate	Izinkan penambahan anotasi
fill-forms	Izinkan pengisian field formulir
extract	Izinkan ekstraksi aksesibilitas
assemble	Izinkan penyisipan, rotasi, dan penghapusan halaman
print-highres	Izinkan pencetakan resolusi tinggi

Saat $permissions kosong, semua operasi dibatasi (owner password diperlukan untuk tindakan apapun).

Enkripsi Owner-Only

Untuk membatasi permission tanpa memerlukan password untuk membuka:

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->setProtection(
        permissions: ['print', 'fill-forms'],
        ownerPass: 'admin-password',
    )
    ->addPage()
    ->setFont('Helvetica', '', 12)
    ->cell(0, 10, 'Buka bebas, tapi hanya cetak dan isi formulir.', newLine: true)
    ->save('restricted.pdf');

Dokumen terbuka tanpa prompt password, tetapi modifikasi, penyalinan, dan anotasi diblokir kecuali owner password diberikan.

Arsitektur Keamanan

TCPDF-Next menerapkan standar enkripsi PDF terkuat secara eksklusif:

• Algoritma: AES-256-CBC (AESV3), Revision 6, V5
• Panjang key: 256 bit
• Tanpa legacy: RC4 dan AES-128 sengaja dihapus

Normalisasi Password SASLprep

Class SaslPrep (RFC 4013) menormalisasi password dengan normalisasi Unicode NFKC, menolak karakter yang dilarang, dan menerapkan constraint teks bidirectional. Ini memastikan hash identik terlepas dari platform atau metode input.

Key Derivation — Algorithm 2.B

ISO 32000-2 Algorithm 2.B menurunkan encryption key melalui hashing SHA-256/384/512 iteratif (hingga 64 round), memberikan ketahanan kuat terhadap serangan brute-force.

Inkompatibilitas PDF/A

Enkripsi tidak diizinkan dalam dokumen yang sesuai PDF/A. Jika Anda mencoba memanggil setProtection() pada dokumen yang mode PDF/A-nya diaktifkan, PdfAException dilempar:

use Yeeefang\TcpdfNext\Core\Document;

// Ini akan melempar PdfAException
$pdf = Document::create()
    ->setPdfA(true)
    ->setProtection(permissions: ['print'], ownerPass: 'secret');
// -> throws PdfAException: "Encryption is not allowed in PDF/A documents"

Jika Anda membutuhkan kepatuhan arsip dan kontrol akses sekaligus, pertimbangkan menggunakan tanda tangan digital dengan pembatasan permission sebagai gantinya.

Contoh Lengkap

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->setTitle('Confidential Report')
    ->setAuthor('Security Team')
    ->setProtection(
        permissions: ['print-highres', 'copy'],
        userPass: 'open-me',
        ownerPass: 'full-access-2026',
    )
    ->addPage()
    ->setFont('Helvetica', 'B', 18)
    ->cell(0, 15, 'Confidential Report', newLine: true)
    ->setFont('Helvetica', '', 12)
    ->multiCell(0, 6, 'Dokumen ini dilindungi dengan enkripsi AES-256. '
        . 'Pembaca dapat mencetak dan menyalin, tetapi tidak dapat memodifikasi atau menganotasi.')
    ->save('confidential-report.pdf');