Bir PDF'yi şifreleyin ve izinlerini kısıtlayın

Bir bakışta

Bu tarif, bir belgeyi Advanced Encryption Standard (AES)-256 standart güvenlik işleyicisiyle şifreler. Kullanıcı parolası (açmak için gereklidir), sahip parolası (tam erişim) ve işlemleri kısıtlayan bir izin bit maskesi belirlersiniz. Bu izinleri okuyucu işbirliğine dayalı sınırlar olarak değerlendirin: şifreleme gizlilik sağlar, bütünlük sağlamaz ve izin bitlerine yalnızca işbirliği yapan yazılımlar uyar. Bu tarif examples/22-protection.php dosyasını temel alır.

Güven sınırı (bunu her izin iddiasıyla birlikte aklınızda tutun). PDF şifrelemesi içerik gizliliğini parolaya sahip olmayan taraflara karşı korur (ISO 32000-2 §7.6). Ancak korumadığı şey bütünlüğüdür: değişikliği algılamaz ya da engellemez. İzin P girişi, işaretsiz 32 bitlik bir bayrak kümesidir ve uyumlu okuyuculardan kısıtlamalara uymalarını ister; bu bir erişim denetimi değildir. Uyumlu olmayan bir araç ya da sahip parolasıyla kullanılan herhangi bir araç, izin verilmeyen her işlemi gerçekleştirebilir. Şifrelenmiş bir PDF’yi “güvenli”, “kurcalamaya karşı korumalı” ya da “kopyalamaya karşı korumalı” olarak tanımlamayın.

Kurulum

composer require nextpdf/core:^3

PHP openssl uzantısını etkinleştirin. AES-256 şifreleyici, parola ve anahtar türetme için bu uzantıyı kullanır.

Kavramsal genel bakış

Şifreleme sözlüğündeki V/R kodları, standart güvenlik işleyicisini seçer (ISO 32000-2 §7.6). NextPDF’nin Aes256Encryptor sınıfı, AESV3 şifreleme filtresini güvenlik işleyicisi revizyon 6 düzeyinde uygular (V=5/R=6). Rastgele bir 256 bitlik dosya şifreleme anahtarı, tuzlanmış yinelemeli karma anahtar türetme (Algoritma 2.B) ve rastgele bir başlatma vektörüyle nesne başına AES-256-CBC şifrelemesi kullanır. Cipher Block Chaining (CBC), bir gizlilik kipidir (NIST SP 800-38A). Başlatma vektörleri öngörülemez olmalıdır.

Başlatma vektörü her nesne ve her çalıştırma için yeniden oluşturulur; bu nedenle ham baytlar çalıştırmalar arasında farklılık gösterir. Bu yüzden yeniden üretilebilirlik profili structural olur. İki çalıştırmayı karşılaştırmadan önce test düzeneği, şifreleme başlatma vektörünü, nesne sırasını ve fragman /ID girişini kanonikleştirir. Bu profil, şifrelemeyi atlayan bir tarifin profilinden daha katıdır.

İzin bit maskesi, P girişini belirler. Bit 3 yazdırma izni verir, bit 6 ise annotation/form-fill izni verir. Bu değer, belgelenmiş işaretsiz 32 bitlik niceliktir.

API yüzeyi

NextPDF\Core\Concerns\HasSecurity (Document içine trait olarak dahil edilmiştir):

setEncryption(#[SensitiveParameter] string $userPassword, #[SensitiveParameter] string $ownerPassword = '', int $permissions = -1): static — AES-256 standart güvenlik işleyicisi şifrelemesini yapılandırır. permissions = -1, tüm izinleri verir. ownerPassword boş olduğunda, kullanıcı parolası sahip parolası olarak yeniden kullanılır. addPage() çağrısından önce çağırın.
getEncryptor(): ?Aes256Encryptor — yapılandırılmış şifreleyici ya da null.
useAesGcm(?bool $enabled = true): static — ISO/TS 32003 AES-256-GCM kullanımını etkinleştirir; ana makinedeki OpenSSL/libsodium bu şifreleme yöntemini sağlamıyorsa istisna fırlatır.

Her iki parola parametresi de #[SensitiveParameter] ile işaretlenmiştir; bu sayede PHP bunları yığın izlerinden gizler.

İzin bitleri (P girişi, yaygın kullanımda düşük bitler 3-6):

Bit	Değer	İşlem
3	4	Belgeyi yazdır
4	8	Belge içeriğini değiştir
5	16	Metni ve grafikleri kopyala / çıkar
6	32	Ek açıklama ekle ya da değiştir ve form alanlarını doldur

Kod örneği — hızlı başlangıç

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Confidential Memo');

// Grant printing only (bit 3 = 4). MUST run before addPage().
$doc->setEncryption(
    userPassword: 'open-me',
    ownerPassword: 'owner-secret',
    permissions: 4,
);

$doc->addPage();
$doc->setFont('helvetica', '', 12);
$doc->cell(0, 10, 'Encrypted with AES-256; printing allowed only.', newLine: true);

$doc->save(__DIR__ . '/confidential.pdf');
echo "Wrote confidential.pdf\n";

Kod örneği — üretim

Aşağıdaki tam örnek, examples/22-protection.php dosyasını temel alır ve test düzeneği için NEXTPDF_COOKBOOK_OUTPUT hedefine yazar.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$userPassword  = 'demo';
$ownerPassword = 'admin';

// Grant ONLY printing (bit 3 = 4); deny copy/modify/annotate.
$permissions = 4;

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

// setEncryption() MUST be called before addPage().
$doc->setEncryption(
    userPassword: $userPassword,
    ownerPassword: $ownerPassword,
    permissions: $permissions,
);

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

$doc->setFont('helvetica', '', 11);
$doc->multiCell(0, 7, 'This document is protected with AES-256 encryption '
    . '(standard security handler, revision 6). The user password is required '
    . 'to open it; the owner password grants full access. The permission '
    . 'bits below are honoured by conforming readers only.');
$doc->ln(5);

$permissionTable = [
    ['Bit 3 (4)',  'Printing',                  'ALLOWED'],
    ['Bit 4 (8)',  'Content modification',      'DENIED'],
    ['Bit 5 (16)', 'Text copying / extraction', 'DENIED'],
    ['Bit 6 (32)', 'Annotations / form fields', 'DENIED'],
];
$doc->setFont('helvetica', 'B', 10);
$doc->cell(30, 7, 'Flag');
$doc->cell(60, 7, 'Operation');
$doc->cell(0, 7, 'Status', newLine: true);
foreach ($permissionTable as [$bit, $operation, $status]) {
    $doc->setFont('courier', '', 9);
    $doc->cell(30, 7, $bit);
    $doc->setFont('helvetica', '', 10);
    $doc->cell(60, 7, $operation);
    $doc->setFont('helvetica', 'B', 10);
    $doc->cell(0, 7, $status, newLine: true);
}

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT');
$doc->save($out !== false ? $out : __DIR__ . '/encrypted.pdf');

echo "Wrote encrypted PDF (AES-256, printing only)\n";

Beklenen çıktı:

Wrote encrypted PDF (AES-256, printing only)

Dosyayı açtığınızda okuyucu bir parola ister. Kullanıcı parolası, dosyayı kısıtlı izin kümesiyle açar. Sahip parolası, dosyayı tam erişimle açar.

Uç durumlar & tuzaklar

Çağrı sırası. setEncryption() çağrısının addPage() çağrısından sonra yapılması, daha önceki içeriği geriye dönük olarak şifrelemez. Önce şifrelemeyi yapılandırın; motor, her nesne gövdesini yazıldığı sırada şifreler.
Sahip parolasının varsayılanı. Boş bir sahip parolası, motorun kullanıcı parolasını sahip parolası olarak yeniden kullanmasına neden olur. Bu durumda fiilen ayrıcalıklı ayrı bir rol kalmaz. İki rolün farklı olması gerektiğinde ayrı parolalar belirleyin.
İzin anlamları yol göstericidir. Bitlere yalnızca uyumlu okuyucular uyar. Bunlar kriptografik olarak zorunlu kılınmaz: uyumlu olmayan bir araç ya da sahip parolasıyla kullanılan herhangi bir araç kısıtlanmış işlemleri gerçekleştirebilir. İzinleri, işbirliği yapan yazılıma yönelik bir ilke sinyali olarak değerlendirin; kararlı bir karşı tarafa dayanabilecek bir erişim denetimi olarak asla görmeyin.
Bütünlük garantisi yok. Şifreleme gizlilik sağlar, bütünlük sağlamaz. Parolaya sahip olmayan bir saldırgan içeriği okuyamaz, ancak biçimin kendisi kurcalamayı algılamaz. Bütünlük koruması; dijital imza ya da ISO/TS 32004 belge MAC’i gibi ayrı bir mekanizma gerektirir.
PDF/A çakışması. PDF/A, Encrypt fragman anahtarını yasaklar. Bir PDF/A belgesinde setEncryption() çağrılması, hangi sırada olursa olsun bir uyumsuzluk istisnası fırlatır.
AES-256-GCM kullanımı. useAesGcm(), ana makinedeki OpenSSL ya da libsodium bu desteği sağladığında ISO/TS 32003 GCM toplu şifrelemesini seçer. Aksi takdirde InvalidConfigException fırlatır. Aynı nedenle PDF/A ile uyumsuzdur.
Açık anahtarlı şifreleme henüz bağlanmamıştır. setPublicKeyEncryption(), API yüzeyini dondurur, ancak yazıcı bağlantısı tamamlanana kadar save() istisna fırlatır (bilinen bir kusur). Bunu Core üzerinde üretimde kullanmayın.

Performans

Anahtar türetme, Algoritma 2.B’nin yinelenen karmasını belge başına bir kez çalıştırır. Nesne başına AES-256-CBC maliyeti, nesne gövdesinin boyutuyla doğrusal olarak artar. Tipik belgelerde maliyet, 1500 ms / 64 MB bütçesinin rahatça içinde kalır. Çok büyük belgelerde, nesne başına AES işleme maliyeti oluşur. AES-NI ile Galois/Counter Mode (GCM), bunu destekleyen ana makinelerde daha hızlıdır.

Güvenlik notları

Yalnızca gizlilik. Güven sınırını yineliyoruz: şifreleme, içeriği parolaya sahip olmayan taraflara karşı korur. Dosyanın değiştirilmediğini kanıtlamaz ve izin bitleri okuyucu işbirliğine dayalıdır.
Parola gücü sizin sorumluluğunuzdadır. İşleyici, ancak parolalar kadar güçlüdür. Birisi dosyayı bir kez ele geçirdiğinde, zayıf bir kullanıcı parolası çevrimdışı olarak kaba kuvvetle kırılabilir; biçim, denemeleri hız sınırlamasıyla kısıtlayamaz.
Sahip parolası birincil bir anahtardır. Sahip parolasına sahip olan herkes her kısıtlamayı atlar. Bunu bir root kimlik bilgisi gibi değerlendirin; belgeyle birlikte asla göndermeyin ve günlüğe kaydetmeyin.
#[SensitiveParameter], derinlemesine savunmadır. Parolaları PHP yığın izlerinden gizler, ancak yine de bunları kendi günlüklerinize, istisna mesajlarınıza ve çökme raporlarınıza sokmamalısınız.

Veri yerleşimi & PII azaltımları

Kütüphane, şifrelemeyi işlem içinde gerçekleştirir. Belgeyi ya da parolaları hiçbir yere iletmez. Motor, kaydettiğiniz şifrelenmiş çıktı dışında diske hiçbir parola, anahtar ya da belge baytı yazmaz. Çıktı dosyasının nerede bulunduğu ve parolaların nasıl saklandığı, entegratörün sorumluluğundaki dağıtım konularıdır. Kütüphane, hiçbir yerleşim garantisi vermez. Düz metin belge kişisel veri içeriyorsa, bu veri yalnızca en zayıf parola ve yukarıdaki işbirliği yapan okuyucu uyarısının izin verdiği ölçüde korunur. Şifreleme, belgeye koyduğunuz kişisel olarak tanımlanabilir bilgileri (PII) en aza indirmenin yerini tutmaz.

Güvenli telemetri & günlük temizleme

Şifreleme bir EncryptionAppliedEvent yayar; bu olay yalnızca algoritma adını (AES-256) ve print/copy/modify işlemlerine izin verilip verilmediğini özetleyen üç boole değerini taşır — olaya hiçbir zaman parola, anahtar, tuz ya da başlatma vektörü yerleştirilmez (src/Event/Security/EncryptionAppliedEvent.php). OpenTelemetry yolu, span özniteliklerini parolaları ve dosya yollarını koşulsuz reddeden bir izin listesi temizleyicisinden (src/Telemetry/AttributeSanitizer.php) geçirir; yalnızca skaler değerlere sahip izin listesindeki anahtarlar korunur. Kendi entegrasyon kodunuzda span’lere, günlüklere ya da istisna mesajlarına parola ya da anahtar materyali eklemeyin. #[SensitiveParameter] işaretleri yığın izlerini korur, ancak sizin oluşturduğunuz dizeleri korumaz.

Tehdit modeli

Kapsam içinde: şifrelenmiş dosyayı elde eden, ancak parolaları elde edemeyen bir saldırgan. İçeriği, parola gücüne bağlı olarak okuyamaz ve dosya düz metin sızdırmaz. Kapsam dışında: kullanıcı ya da sahip parolasına sahip bir saldırgan; izin bitlerini yok sayan uyumlu olmayan bir okuyucu; zayıf bir parolanın çevrimdışı kaba kuvvetle kırılması; kurcalama algılama (şifreleme gizlilik sağlar, bütünlük sağlamaz); ana makinedeki OpenSSL yapısındaki yan kanallar; ve tamamen entegratörün sorumluluğunda olan anahtar saklama. Bu tehditlerin belgelenmesi, güvenlik açıklarının bulunmadığını ileri sürmez.

FIPS kipi davranışı

Kriptografik temel öğeleri ana makinedeki OpenSSL yapısı sağlar; dolayısıyla FIPS durumu bir kütüphane ayarı değil, bir ana makine özelliğidir. CryptoCapabilities::detectFipsMode(), üç durumlu bir FipsModeDetection döndürür (src/Security/FipsModeDetection.php): FIPS_ACTIVE, FIPS_ABSENT ya da INDETERMINATE. PHP openssl uzantısı, OpenSSL 3 sağlayıcı modeli için herhangi bir bağlama sunmaz; bu nedenle algılama en iyi çaba düzeyindedir. INDETERMINATE, “FIPS kanıtlanmadı” (güvenli tarafta kalacak şekilde kapalı kabul edilir) olarak değerlendirilir ve operatörün eyleme geçebileceği telemetride ayırt edilebilir. NextPDF, FIPS 140 doğrulaması iddiasında bulunmaz; FIPS doğrulamalı bir OpenSSL üzerinde çalıştırmak operatörün sorumluluğundadır ve algılama sonucu yol göstericidir.

Uygunluk

Bildirim	Standart	Madde
Şifreleme sözlüğü `V` kodu, şifreleme algoritmasını seçer.	ISO 32000-2	§7.6
AESV3 şifreleme filtresi yöntemi, `CFM` girişiyle adlandırılır.	ISO 32000-2	§7.6
İzin `P` girişi, işaretsiz 32 bitlik bir erişim izni niceliğidir.	ISO 32000-2	§7.6
İzin biti 3, yazdırmayı denetler.	ISO 32000-2	§7.6
İzin biti 6, ek açıklama / form doldurmayı denetler.	ISO 32000-2	§7.6
Şifreleme, içeriği yetkisiz erişime karşı korur (gizlilik).	ISO 32000-2	§7.6
Revizyon 6 anahtar türetme, tuzlanmış yinelemeli karma kullanır (Algoritma 2.B).	ISO 32000-2	§7.6
CBC, bir gizlilik kipidir (bütünlük kipi değil).	NIST SP 800-38A	§6.2
CBC başlatma vektörleri öngörülemez olmalıdır.	NIST SP 800-38A	Ek. C

NextPDF, alıntılanan maddeleri uygular. Genel bir ISO 32000-2 uygunluğu, FIPS 140 doğrulaması ya da herhangi bir yasal ya da sözleşmeye dayalı gizlilik garantisi ileri sürmez. “Standart güvenlik işleyicisi desteği”, dağıtımınızda bir güvenlik sertifikası değildir. Bu, kütüphanenin dışındaki parola saklama ve doğrulayıcı politikasına bağlıdır.