Trait Core / HasSecurity

Sekilas pandang

HasSecurity adalah trait concern untuk proteksi dokumen. Gunakan trait ini untuk mengatur enkripsi AES-256, izin akses, tagged PDF, dan delegasi tanda tangan digital.

Pemasangan

composer require nextpdf/core:^3

Gambaran konseptual

trait HasSecurity berada di src/Core/Concerns/HasSecurity.php. Document menyertakannya. Trait ini menambahkan metode enkripsi, penandatanganan, PDF/A, dan tagged PDF pada facade.

Panggil setEncryption() untuk mengunci dokumen. Berikan kata sandi pengguna, kata sandi pemilik yang opsional, dan bitmask izin. Kata sandi pengguna digunakan untuk membuka dokumen. Kata sandi pemilik memberikan akses penuh. Jika kata sandi pemilik kosong, mesin menggunakan kembali kata sandi pengguna. Cipher bawaannya adalah AES-256.

Untuk menerapkan kontrol izin yang ketat, lakukan langkah berikut:

1. Pilih bit izin yang Anda izinkan.
2. Panggil setEncryption() sebelum Anda menambahkan halaman apa pun.
3. Tambahkan halaman dan konten.

Bit izin mengikuti ISO 32000-2:2020 Tabel 22. Bit 3 mengizinkan pencetakan. Bit 4 mengizinkan modifikasi konten. Bit 5 mengizinkan ekstraksi teks. Bit 6 mengizinkan perubahan anotasi dan formulir.

Penangan keamanan PDF menghitung kunci enkripsi berkas (ISO 32000-2:2020 §7.6.2). Kode V dalam kamus enkripsi memilih algoritmanya. Nilai V legasi yang lebih rendah ditandai sebagai usang di PDF 2.0. NextPDF menghasilkan penangan AES-256 modern. Pembaca PDF memverifikasi kata sandi yang diberikan terhadap entri U pada kamus (§7.6.4).

useAesGcm() mengaktifkan enkripsi massal AES-256-GCM (Galois/Counter Mode) ISO/TS 32003:2023. Mode ini dinonaktifkan secara default. Pemanggil yang sudah ada tetap menerima keluaran AES-256-CBC (Cipher Block Chaining) yang identik secara byte. Metode ini menolak dijalankan ketika mode PDF/A aktif. Metode ini juga menolak dijalankan ketika host tidak dapat menjalankan AES-GCM.

setSignature() mengonfigurasi tanda tangan PDF Advanced Electronic Signatures (PAdES). Berikan sertifikat, level tanda tangan, dan klien stempel waktu yang opsional. Penandatanganan harus dijalankan sebelum linearisasi. setEncryption() menerima kata sandi #[SensitiveParameter], sehingga nilainya tidak muncul dalam stack trace.

enableTaggedPdf() membangun pohon struktur untuk PDF/UA-2. Berikan tag bahasa BCP 47. Mode ketat memvalidasi tag di batas application programming interface (API). Tag yang tidak valid memicu InvalidConfigException. enablePdfA() mengaktifkan mode arsip PDF/A. enableLinearization() menghasilkan berkas terlinearisasi.

Permukaan API

Simbol	Jenis	Stabilitas	Sejak
setEncryption(string, string, int): static	metode	stabil	1.2.0
getEncryptor(): ?Aes256Encryptor	metode	stabil	1.2.0
useAesGcm(?bool): static	metode	stabil	1.4.0
setPublicKeyEncryption(...): static	metode	stabil	1.2.0
setSignature(CertificateInfo, SignatureLevel, ?TsaClient): static	metode	stabil	1.2.0
enablePdfA(?object): static	metode	stabil	1.2.0
enableTaggedPdf(string, ?ConformancePolicy): static	metode	stabil	1.0.0
setConformanceMode(ConformanceMode): static	metode	stabil	2.8.0
useDocumentMac(?bool): static	metode	stabil	1.4.0
enableLinearization(): static	metode	stabil	1.2.0

Contoh kode — Mulai cepat

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Encrypted Document — Restricted Permissions');
$doc->setAuthor('NextPDF Example');

// Enable AES-256 encryption BEFORE adding any pages.
$doc->setEncryption(
    userPassword: 'demo',
    ownerPassword: 'admin',
    permissions: 4, // 4 = allow printing only
);

$doc->addPage();
$doc->setFont('helvetica', 'B', 20);
$doc->cell(0, 14, 'Encrypted PDF Document', newLine: true);

$doc->save(__DIR__ . '/output/22-protection.pdf');

Sumber: examples/22-protection.php.

Contoh kode — Produksi

Aktifkan AES-256-GCM, lalu terapkan tagged PDF untuk aksesibilitas.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Protected and Tagged');

$doc->setEncryption(userPassword: 'open-me', permissions: 4);
$doc->useAesGcm(true);
$doc->enableTaggedPdf('en');

$doc->addPage();
$doc->setFont('helvetica', '', 12);
$doc->cell(0, 10, 'AES-256-GCM encrypted and PDF/UA-2 tagged.', newLine: true);

$doc->save(__DIR__ . '/output/protected-tagged.pdf');

Sumber: disusun dari examples/22-protection.php dan examples/31-pdfua2-tagged.php.

Kasus tepi & jebakan

• Panggil setEncryption() sebelum addPage() yang pertama. Panggilan setelah itu tidak memengaruhi halaman yang sudah dihasilkan.
• useAesGcm(true) melempar eksepsi ketika mode PDF/A aktif. ISO 19005 melarang kunci trailer Encrypt.
• useAesGcm(true) melempar eksepsi ketika host tidak memiliki cipher AES-GCM. Pasang ext-sodium atau mutakhirkan OpenSSL.
• setSignature() tidak kompatibel dengan linearisasi. Konfigurasikan tanda tangan sebelum Anda mengaktifkan linearisasi.
• Jika kata sandi pemilik kosong, sistem menggunakan kembali kata sandi pengguna. Tetapkan kata sandi pemilik yang berbeda untuk kontrol akses yang sebenarnya.

Performa

Enkripsi menambahkan satu lintasan cipher pada setiap badan objek. AES-256-CBC dan AES-256-GCM keduanya berjalan dalam O(content bytes). Biayanya kecil dibandingkan proses tata letak. Anggaran halaman untuk mulai cepat kanonis adalah 1500 ms / 64 MB.

Catatan keamanan

Kata sandi pengguna dan kata sandi pemilik menggunakan atribut #[SensitiveParameter]. PHP menyamarkan nilainya dalam stack trace. Mesin tidak pernah mencatat nilai kata sandi. Bitmask izin diekspos pada model dokumen bagi penulis. Bitmask tidak dibaca ulang dari status cipher privat.

Residensi data & mitigasi PII

NextPDF berjalan dalam proses Anda. Core tidak melakukan panggilan jaringan untuk material kunci enkripsi atau penandatanganan. Kata sandi tetap berada dalam memori proses. Kata sandi tidak ditulis ke disk. Panggilan ke stempel waktu dan hardware security module (HSM) merupakan fitur Pro dan Enterprise. Fitur tersebut melakukan panggilan jaringan secara eksplisit. Core tidak melakukan panggilan tersebut.

Telemetri aman & pembersihan log

Core tidak mengirim telemetri secara default. Peringatan disalurkan melalui WarningCollector. Nilai kata sandi tidak pernah masuk ke pesan peringatan. Peringatan mengidentifikasi kunci konfigurasi, bukan nilai rahasianya. Jangan menambahkan kata sandi ke baris log kustom.

Model ancaman

Ancaman utama adalah injeksi string ke aliran konten melalui teks pengguna. Mesin meng-escape setiap string teks sebelum memasukkannya ke aliran. Peta escape mencakup batas literal-string dan hex-string PDF sesuai ISO 32000-2:2020 §7.3.4.2. Ancaman kedua adalah penulisan berkas parsial saat keluaran ditulis. HasOutput::save() menggunakan penulisan atomik. Pembaca melihat berkas lama atau berkas baru, tidak pernah berkas parsial. Ancaman ketiga adalah cipher yang lemah. NextPDF menghasilkan AES-256 dan menandai jalur RC4 legasi sebagai usang.

Perilaku mode FIPS

Config menerima CryptoPolicyInterface. Kebijakan Federal Information Processing Standards (FIPS) 140-3 dapat membatasi pemilihan cipher. Jika host tidak memiliki penyedia AES-GCM yang disetujui, useAesGcm(true) melempar eksepsi alih-alih beralih ke cadangan. Perilaku fail-closed ini menjaga dokumen tetap berada dalam kebijakan yang dikonfigurasi.

Konformitas

Klaim	Sumber	Klausul	reference_id
Penangan keamanan menghitung kunci enkripsi berkas; V memilih algoritmanya	ISO 32000-2:2020	§7.6.2
Kode V memilih algoritma enkripsi; nilai V legasi ditandai usang di PDF 2.0	ISO 32000-2:2020	§7.6.2
Kata sandi pengguna diverifikasi terhadap entri U	ISO 32000-2:2020	§7.6.4

Klausul diparafrasekan. Tidak ada teks normatif yang direproduksi.

Lihat juga

• /modules/core/core/document-facade/ — facade yang menyertakan trait ini; kebijakan fon strictPdf20FontEmbedding()
• /modules/core/core/ — Ikhtisar Core: enkripsi dan penandatanganan adalah ekstensi opt-in
• /modules/core/security/ — mesin enkripsi dan penandatanganan yang didelegasikan oleh HasSecurity
• /modules/core/core/has-output/ — HasOutput: penulisan atomik yang menutup jendela time-of-check to time-of-use (TOCTOU) keluaran
• /modules/core/contracts/ — CryptoPolicyInterface (kait kebijakan FIPS 140-3)
• /modules/core/exception/ — InvalidConfigException dan IncompatiblePdfAModeException dilempar di sini
• /modules/core/conformance/ — mode konformitas PDF/A dan PDF/UA yang dirujuk oleh enablePdfA()/enableTaggedPdf() <!— evidence: src/Core/Concerns/HasSecurity.php (trait HasSecurity @since 1.2.0; setEncryption(#[SensitiveParameter]string userPassword,#[SensitiveParameter]string ownerPassword=”,int permissions=-1):static — empty owner reuses user, surfaces encryptionPermissions on DocumentData, validateNoEncryption when pdfaManager set; getEncryptor():?Aes256Encryptor; useAesGcm(?bool=true) @since 1.4.0 — throws IncompatiblePdfAModeException when PDF/A active, InvalidConfigException when no AES-GCM, ISO/TS 32003:2023 §5.1/§5.2; setSignature(CertificateInfo,SignatureLevel=PAdES_B_B,?TsaClient) throws when linearize set; setPublicKeyEncryption ISO §7.6.5; enablePdfA; enableTaggedPdf(string=‘en’,?ConformancePolicy) @since 1.0.0 — Bcp47Validator strict gate throws InvalidConfigException, ISO 14289-2:2024 §8.4.4; setConformanceMode @since 2.8.0; useDocumentMac @since 1.4.0 ISO/TS 32004:2024; enableLinearization); src/Core/Document.php escapeTextForStream ISO §7.3.4.2; src/Core/Config.php cryptoPolicy CryptoPolicyInterface (FIPS 140-3); src/Core/Concerns/HasOutput.php atomic save; examples/22-protection.php (verbatim quick-start, Table 22 permission bits), examples/31-pdfua2-tagged.php; glossary FIPS 140-3/PAdES. RAG iso32000_2_sec7 §7.6.2 /fb39b318, §7.6.4 >