Güvenlik: şifreleme, kripto politikası ve imzalama yüzeyi

Bir bakışta

Core güvenlik modülü belgeye 256 bit Advanced Encryption Standard (AES-256) şifrelemesi uygular, her algoritma seçimini bir kripto politikası sözleşmesi üzerinden yönlendirir ve dağıtım tarafından yönetilen anahtar yönetimi hizmeti için tümleştirme noktaları sunar. Etkili belge koruması; anahtar işleme biçimine, parola gücüne, belgeyi açan okuyucuya ve dağıtım ortamına bağlıdır. Bu sayfa bu sınırları açıkça belirtir.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

Güvenlik modülünün üç yüzeyi vardır. Şifreleme yüzeyi, AES-256 Standard güvenlik işleyicisini yapılandırmak için setEncryption() belge giriş noktasını kullanır. Kripto politikası geçidi, bir dağıtımın hangi karma, imza, şifre ve anahtar gücü kullanımına izin vereceğine karar vermek için CryptoPolicyInterface arabirimini kullanır. İmzalama yüzeyine burada değinilir, ancak ayrı olarak belgelenmiştir; bkz. İmzalama.

Şifreleme, ISO 32000-2:2020 §7.6 içinde tanımlandığı şekilde AES-256 kullanır. Varsayılan yol, AESV3 şifreleme filtresine sahip V=5 / R=6 Standard güvenlik işleyicisidir. Dosya anahtarı 32 bayttır (256 bit); bu, Federal Information Processing Standards (FIPS) 197 ile eşleşir. İsteğe bağlı yol, ISO/TS 32003:2023 V=6 / R=7 Galois/Counter Mode içinde AES-256 (AES-256-GCM) kimlik doğrulamalı şifreleme ekler. Ayrıntılı sayfa her iki yolu da belgeler: Şifreleme.

Kripto politikası geçidi, reddet veya izin ver mantığıyla çalışan bir yüklemdir. Core; herhangi bir imzalama, şifreleme veya karma adımından önce CryptoPolicyInterface arabirimine başvurur. Hiçbir politika ayarlanmamışsa Core her algoritmaya izin verir. Bu açık varsayılan üretim için değil, geliştirme için uygundur. Düzenlemeye tabi bir dağıtım açık bir politika ayarlamalıdır. Contracts / Security Policy sözleşme yüzeyini belgeler.

İzin bayrakları, en yaygın aşırı iddia kaynaklarından biridir; bu nedenle bu sayfa açık davranır. İzin bit maskesi, şifrelenmiş /Perms girdisinde ve /P değerinde saklanır. Uyumlu bir okuyucunun bu kısıtlamalara uyması beklenir. Şifreleme, bayrakları uygulamaz. Bitleri yok sayan bir işleyici, şifre çözme anahtarına sahip olduktan sonra içeriği yine de okuyabilir, kopyalayabilir veya değiştirebilir. Bu sınırı, izin bayraklarına güvenen her tarafa bildirin.

Anahtar yönetimi ve Public-Key Cryptography Standards #11 (PKCS#11) tümleştirmesi sözleşme noktalarıdır. Core, yerel anahtar yolunu sağlar. KeyMaterial değer nesnesi, uzunluğu denetlenmiş 256 bitlik bir anahtarı sarmalar ve dize ile hata ayıklama çıktılarında açığa çıkmaya direnir. Donanım güvenlik modülü (HSM)/PKCS#11 anahtar muhafaza yolu, aynı sözleşmelerin arkasında geçitlenen bir Enterprise yeteneğidir; bu sayfa tümleştirme noktasını adlandırır, ancak Enterprise uygulamasını belgelemez.

API yüzeyi

Tür	Çeşit	Anahtar üyeler	Kararlılık	Şu sürümden beri
Document::setEncryption()	yöntem (ilgi alanı HasSecurity)	userPassword, ownerPassword, permissions	kararlı	1.0.0
Document::useAesGcm()	yöntem (ilgi alanı HasSecurity)	?bool $enabled — isteğe bağlı ISO/TS 32003 V=6/R=7	kararlı	2.18.0
Aes256Encryptor	sınıf	encrypt(), decrypt(), buildEncryptionDictionary(), verifyUserPassword(), verifyOwnerPassword(), validatePerms()	kararlı	1.0.0
Aes256GcmEncryptor	sınıf	encrypt(), decrypt(), encryptStream(), assertWithinSafetyBound(), invocationCount()	kararlı	2.18.0
KeyMaterial	final readonly sınıf	generate(), exposeKey(), fingerprint()	kararlı	2.18.0
CryptoPolicyInterface	arabirim	isHashAlgorithmAllowed(), isSignatureAlgorithmAllowed(), isEncryptionAlgorithmAllowed(), isKeyStrengthAllowed(), getPreferredHashAlgorithm(), getName()	kararlı	1.9.0
Config::withCryptoPolicy()	yöntem	CryptoPolicyInterface $policy	kararlı	1.9.0
CryptoCapabilities	final sınıf	hasAesGcm(), detectFipsMode(), assertFipsAvailableForProfile()	kararlı	2.0.0

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

examples/22-protection.php

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

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

// Call setEncryption() BEFORE addPage().
// Permission bit 3 (value 4) = printing allowed; all other operations denied.
$doc->setEncryption(
    userPassword: 'demo',
    ownerPassword: 'admin',
    permissions: 4,
);

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

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

Kullanıcı parolası belgeyi açar. Sahip parolası tam erişim sağlar. İzin bayrakları yalnızca uyumlu okuyucuları kısıtlar.

Kod örneği — üretim

examples/security/policy-gated-encryption.php

<?php

declare(strict_types=1);

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

use NextPDF\Contracts\CryptoPolicyInterface;
use NextPDF\Core\Document;
use Psr\Log\LoggerInterface;

final readonly class PolicyGatedEncryption
{
    public function __construct(
        private CryptoPolicyInterface $cryptoPolicy,
        private LoggerInterface $logger,
    ) {}

    /**
     * Encrypt only when the active policy permits AES-256-CBC.
     *
     * @param non-empty-string $userPassword  Opens the document.
     * @param non-empty-string $ownerPassword Grants full access.
     */
    public function protect(
        Document $doc,
        string $userPassword,
        string $ownerPassword,
        int $permissions,
    ): void {
        if (!$this->cryptoPolicy->isEncryptionAlgorithmAllowed('aes-256-cbc')) {
            $this->logger->error('Encryption refused by crypto policy', [
                'policy' => $this->cryptoPolicy->getName(),
            ]);

            throw new \RuntimeException('AES-256-CBC denied by the active crypto policy.');
        }

        $doc->setEncryption($userPassword, $ownerPassword, $permissions);

        $this->logger->info('Document encrypted', [
            'policy' => $this->cryptoPolicy->getName(),
            'algorithm' => 'aes-256-cbc',
        ]);
    }
}

Geçit, şifrelemeden önce politikaya başvurur, denetim izi için politika adını günlüğe kaydeder ve politika şifreyi reddettiğinde belirli bir özel durum oluşturur.

Sınır durumlar ve dikkat edilecek noktalar

• Mutlaka setEncryption() çağrısını önce, ardından addPage() çağrısını yapın. Daha sonra yapılan bir çağrı, yazıcının zaten çıktıya yazdığı içeriği geriye dönük olarak şifrelemez.
• PDF/A modu ve şifreleme birbirini dışlar. ISO 19005, her PDF/A türünde Encrypt fragman anahtarını yasaklar; bu nedenle bir PDF/A yöneticisi etkinken setEncryption() ve useAesGcm() özel durum oluşturur.
• Dahili olarak, setEncryption() içinde boş bir sahip parolası kullanıcı parolasına geri döner. Tek bir paylaşılan parola kullanan bir belge, kullanıcı parolasını tutan kişiye sahip düzeyinde erişim verir.
• Hiçbir politika eklenmediğinde, CryptoPolicyInterface her algoritmaya izin verir. Açık varsayılanı bir geliştirme kolaylığı olarak değerlendirin ve düzenlemeye tabi her dağıtımda açık bir politika ayarlayın.
• İzin bayrakları okuyucu için yol göstericidir. Bunları, kötü niyetli bir işleyicinin atlayamayacağı bir erişim denetimi olarak tanımlamayın.

Performans

setEncryption(), belge derlemesi sırasında yinelemeli bir anahtar türetme rutini (Algoritma 2.B, revizyon 6) çalıştırır. Maliyet sınırlıdır ve belge başına sabittir; sayfa sayısıyla ölçeklenmez. Nesne başına şifreleme, akış veya dize başına bir AES işlemi gerçekleştirir. İsteğe bağlı AES-256-GCM yolu, nesne başına 28 baytlık ek yük (12 baytlık başlatma vektörü (IV) artı 16 baytlık etiket) ekler ve büyük içeriği 16 MiB parçalar halinde akışla işler. Bu, akış geçişini belgelenmiş 64 MB tepe bellek değerinin altında tutar. 1500 ms duvar saati ve 64 MB tepe değerinden oluşan performance_budget değeri, şifrelemeden değil, belge işleme aşamasından kaynaklanır.

Güvenlik notları

Tehdit modeli açıktır. Kripto politikası geçidi; herhangi bir işlemden önce zayıf şifreleri, zayıf karmaları ve kısa anahtarları reddederek algoritma düşürmeyi azaltır. Motor, istenen bir ilkel öğe yokken sessizce daha zayıf bir ilkel öğeyle değiştirmez; operatörün harekete geçebilmesi için bir özel durum oluşturur. KeyMaterial, günlüğe kaydetme yoluyla anahtarın açığa çıkmasını azaltır: dize ve hata ayıklama biçimleri baytları gizler ve yalnızca tersine çevrilemez bir parmak izi gösterir. Şifreli metinde kurcalama yalnızca isteğe bağlı AES-256-GCM yolunda algılanır; bu yolda kimlik doğrulama etiketi doğrulanır ve bir uyuşmazlık, düz metin döndürmek yerine bir özel durum oluşturur. Varsayılan AES-256 Cipher Block Chaining (AES-256-CBC) yolu yalnızca gizliliği sağlar ve değişikliği kendi başına algılamaz. GCM yolunda IV yeniden kullanımı, NIST SP 800-38D §8 içindeki benzersiz IV gereksinimiyle tutarlı şekilde, monoton bir sayaç ve derinlemesine savunma amaçlı çakışma kümesiyle azaltılır.

Sınırlar da aynı ölçüde açıktır. AES-256 şifrelemesi, ISO 32000-2:2020 §7.6 içinde tanımlandığı şekilde uygulanır. Etkili koruma; parola gücüne, anahtar yönetimine, dağıtım ortamına ve belgeyi açan okuyucuya bağlıdır. Uyumlu okuyucular izin bayraklarına uyar, ancak şifreleme bunları uygulamaz. FIPS modu yoklaması, ana makine OpenSSL derlemesinin bir FIPS sağlayıcısı yükleyip yüklemediğini bildirir. Kitaplık, ana makine doğrulanmış bir modül sağladığında FIPS uyumlu bir modda çalışır; herhangi bir modülü sertifikalandırmaz. NIST SP 800-57 Part 1 §4, anahtar ömrünü ve kripto dönemini dağıtım sorumlulukları olarak çerçeveler. Core denetimleri sunar; dağıtım ise döndürme politikasını belirler.

Veri yerleşimi ve PII azaltımları

Şifreleme yüzeyi, içerdikleri kişisel olarak tanımlanabilir bilgiler (PII) dahil olmak üzere belge baytlarını ana makine dışına aktarmaz. Anahtar türetme, şifreleme ve şifre çözme işlem içinde çalışır. İsteğe bağlı GCM yolu, bellek içi bir IV çakışma kümesini anahtar baytlarıyla değil, tersine çevrilemez bir anahtar parmak iziyle anahtarlar. Güvenlik modülü diske hiçbir parola veya anahtar değeri yazmaz. Anahtarları harici bir anahtar yönetimi hizmeti üzerinden yönlendiren bir dağıtım, o hizmetin veri yerleşiminden sorumludur.

Güvenli telemetri ve günlük temizleme

KeyMaterial::__toString() ve __debugInfo(), gizlenmiş bir yer tutucu döndürür; böylece bir anahtar nesnesinin yanlışlıkla günlüğe kaydedilmesi, anahtar baytlarını değil, bir parmak izini gösterir. setEncryption() yöntemine geçirilen parolalar, bunları yığın izinden gizleyen #[\SensitiveParameter] özniteliğini taşır. Denetimler için, kripto işlemi tanımlayıcıları olarak CryptoPolicyInterface::getName() tarafından sağlanan politika adını ve 8 karakterlik anahtar parmak izini kullanın. Bu değerleri günlüğe kaydedin; anahtarı veya parolayı asla kaydetmeyin.

Tehdit modeli

Tehdit	Core içindeki azaltım	Artık sınır
Algoritma düşürme / zayıf şifre ile değiştirme	Kripto politikası geçidi; sessiz düşürme yok (UnsupportedAlgorithmException oluşturur)	Yalnızca bir politika eklendiğinde etkili
Günlükler aracılığıyla anahtar açığa çıkması	KeyMaterial gizleme; #[\SensitiveParameter] parolalarda	Çağıran taraf exposeKey() sonucunu bir günlükleyiciye geçirirse bunu etkisiz kılar
Şifreli metinde kurcalama	İsteğe bağlı yolda GCM etiket doğrulaması	Varsayılan CBC yolu yalnızca gizliliği sağlar
IV yeniden kullanımı (GCM)	Monoton sayaç ve çakışma kümesi; taşmayı reddeder	—
İzin bayrağı atlatma	Yok; bayraklar yol göstericidir	Uyumsuz bir okuyucu bayrakları yok sayar
Zayıf bir parolaya kaba kuvvet saldırısı	SASLprep ve yinelemeli anahtar türetme maliyeti artırır	Zayıf bir parola, başlıca risk olmaya devam eder

FIPS modu davranışı

Core, FIPS doğrulamalı bir şifreleme modülü değildir ve FIPS sertifikalı değildir. CryptoCapabilities::detectFipsMode(), en iyi çaba ilkesine dayalı bir çalışma zamanı yoklamasıdır: önce operatör geçersiz kılmasını, ardından OpenSSL sağlayıcı listesini, ardından eski FIPS modu çağrısını okur ve etkin, yok veya belirsiz olarak bildirir. assertFipsAvailableForProfile(), bir FIPS sağlayıcısını kanıtlayamayan bir ana makinede bir FIPS profili seçildiğinde kapalı duruma geçerek başarısız olur. Kitaplık, FIPS doğrulamalı bir sağlayıcı yüklemiş bir ana makine OpenSSL derlemesine karşı yapılandırıldığında FIPS uyumlu bir modda çalışır. Doğrulanmış, sertifikalı bir FIPS duruşu bir Enterprise konusudur; Enterprise belgelerine bakın.

Uyumluluk

İddia	Standart	Madde	Kanıt
GCM yolu, standardın benzersizlik gereksinimiyle tutarlı şekilde, her IV değerini bir çağrı için benzersiz tutar.	NIST SP 800-38D	§8.2.1
Core, anahtar ömrü ve kripto dönemi için denetimler sunar; politikanın sahibi dağıtımdır.	NIST SP 800-57 Part 1 Rev. 5	§4
AES dosya anahtarı 256 bittir; bu, standardın anahtar uzunluğuyla eşleşir.	FIPS 197	§4.2.1
Belirteç üzerinde anahtar oluşturma, harici bir anahtar deposu için tümleştirme noktasıdır.	OASIS PKCS#11 v3.1	C_GenerateKey

ISO 32000-2:2020 §7.6, Standard güvenlik işleyicisinin normatif temelidir. Metni lisansla kısıtlanmıştır ve burada hiçbir zaman alıntılanmadan yorumlanarak verilmiştir; bu sayfa maddeye numarayla atıfta bulunur. Yukarıdaki her nokta, atıfta bulunulan standarttan yorumlanmıştır.

Ticari bağlam

Core, kripto politikası sözleşmesini tanımlar ve dondurur, AES-256 şifreleme yolunu sağlar ve yerel anahtar yüzeyi sunar. Enterprise sürümü, aynı CryptoPolicyInterface arkasında bir HSM/PKCS#11 anahtar muhafaza yolu ve bir FIPS modu kripto politikası profili sağlar. Sözleşme yüzeyi sürümler arasında aynıdır; dağıtım, farklı bir politika uygulaması ve anahtar muhafaza arka ucu ekler.

Ayrıca bakın

• Security / Encryption — AES-256 ve AES-256-GCM için ayrıntılı başvuru.
• Contracts / Security Policy — kripto politikası ve kaynak politikası sözleşmeleri.
• Security / Signing — PDF Advanced Electronic Signatures (PAdES), Cryptographic Message Syntax (CMS) ve zaman damgaları.
• Audit — politika adı ve işlem denetim günlüğü.
• Conformance — şifreleme ile PDF/A etkileşimi.