Sözleşmeler / güvenlik ilkesi

Bir bakışta

Güvenlik ilkesi alanı, varsayılan olarak reddetme ilkesine dayanan üç sözleşme tanımlar: CryptoPolicyInterface algoritma ve anahtar seçimlerini denetler, HtmlSecurityPolicyInterface Hypertext Markup Language (HTML) özellik yüzeyini kısıtlar ve ExternalResourcePolicyInterface uzak kaynakların yüklenmesini yönetir. Her biri bir sözleşme olduğu için, çatallamaya gerek kalmadan daha katı bir dağıtım ilkesi sağlayabilirsiniz.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

CryptoPolicyInterface bir şifreleme geçididir. Core, herhangi bir imzalama, şifreleme veya karma adımından önce bunu çağırır. Denetim karmayı, imza nesne tanımlayıcısını (OID’yi), şifreleyiciyi ve anahtar gücünü kapsar. Sözleşme ayrıca minimum karmayı ve denetim günlüğü için bir ilke adını bildirir. Federal Information Processing Standards (FIPS) 140-3 veya eIDAS gibi bir kural kümesi uygulamak için bu sözleşmeyi kullanın. İmzalama ve şifreleme kodu değişmez. Hiçbir ilke ayarlanmadığında her algoritmaya izin verilir. Düzenlemeye tabi bir site açık bir ilke ayarlamalıdır.

HtmlSecurityPolicyInterface HTML ayrıştırma katmanında çalışır. İçerik herhangi bir işleyiciye ulaşmadan önce devreye girer. Bir etikete, bir özniteliğe, bir Cascading Style Sheets (CSS) özelliğine veya bir tek tip kaynak konumlayıcısı (URL) şemasına izin verilip verilmeyeceğine karar verir. Ayrıca giriş boyutunu ve iç içe yerleştirme derinliğini sınırlar. Boyut sınırlarını ve Content Security Policy (CSP) başlıklarını ayarlayan, işleyiciye özgü aktarım ilkeleriyle (Chrome, Cloudflare, Gotenberg) birlikte çalışır. HTML ilkesi, ayrıştırma katmanındaki saldırı yüzeyini azaltır. Çıkarılan bir etiket asla yerleşime ulaşmaz. Enjekte edilen bir öğe çıktıyı değiştiremez. Hiçbir ilke ayarlanmadığında varsayılan değer tüm özellik kümesine izin verir.

ExternalResourcePolicyInterface HTML işlem hattının harici bir yazı tipini, stil sayfasını veya görüntüyü getirip getiremeyeceğine karar verir. Ayrıca her getirme işlemi için sınırları belirler. Varsayılan duruşu tümünü reddetmektir. Siz etkinleştirene kadar her seçenek kapalıdır. Sözleşme, en az ayrıcalık ilkesini izler. Güvenilmeyen HTML, saldırganın denetimindeki bir URL’yi işaret edebilir. @font-face getirmelerini şemaya, boyuta ve glif sayısına göre denetler. @import ifadesini şemaya, derinliğe ve toplam boyuta göre denetler. background-image özelliğini bir şema listesi ve tam eşleşmeli bir etki alanı izin listesiyle denetler. Veri URI’sinin (Uniform Resource Identifier) boyutunu sınırlar. Ayrıca Scalable Vector Graphics (SVG) harici başvurularını denetler. Sözleşme, üretim ortamının bunları her zaman reddetmesi gerektiğini belirtir. Bunlar istek sahteciliğine ve betik enjeksiyonuna olanak tanır. Açık URL getirme işlemi, bir sunucu tarafı istek sahteciliği yoludur. Open Worldwide Application Security Project (OWASP) Top 10 2025 tarafından açıklandığı gibi, URL değiştirilerek erişim denetimi atlanır. Harici bileşen kaynağı, resmi kökenlerle ve güvenli aktarımla sınırlandırılmalıdır.

API yüzeyi

Tür	Çeşit	Temel üyeler	Kararlılık	Sürümden beri
`CryptoPolicyInterface`	arabirim	`isHashAlgorithmAllowed()`, `isSignatureAlgorithmAllowed()`, `isEncryptionAlgorithmAllowed()`, `isKeyStrengthAllowed()`, `getPreferredHashAlgorithm()`, `getName()`	kararlı	1.9.0
`HtmlSecurityPolicyInterface`	arabirim	`isTagAllowed()`, `isAttributeAllowed()`, `isCssPropertyAllowed()`, `isUrlSchemeAllowed()`, `getMaxInputSize()`, `getMaxNestingDepth()`, `getName()`	kararlı	3.1.0
`ExternalResourcePolicyInterface`	arabirim	`isFontFaceAllowed()`, `getAllowedFontSchemes()`, `getMaxFontFileSize()`, `getMaxFontGlyphs()`, `isImportAllowed()`, `getMaxImportDepth()`, `isBackgroundImageAllowed()`, `getAllowedImageDomains()`, `getMaxDataUrlSize()`, `isSvgExternalReferenceAllowed()`	kararlı	4.0.0

ExternalResourcePolicyInterface tiplenmiş sınırlar döndürür: positive-int boyutları, int<1, 100> içe aktarma derinliği ve list<non-empty-string> şema ve etki alanı listeleri. Varsayılan uygulama her yeteneği reddeder.

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

<?php

declare(strict_types=1);

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

use NextPDF\Contracts\HtmlSecurityPolicyInterface;

/**
 * Decide whether a tag survives the policy.
 *
 * @param HtmlSecurityPolicyInterface $policy A core or custom policy.
 */
function tagSurvives(HtmlSecurityPolicyInterface $policy, string $tag): bool
{
    return $policy->isTagAllowed($tag);
}

İşlev yalnızca sözleşmeye bağlıdır. Hem kısıtlayıcı bir ilke hem de varsayılan ilke bu bağımlılığı karşılar.

Kod örneği — Üretim

<?php

declare(strict_types=1);

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

use NextPDF\Contracts\CryptoPolicyInterface;
use NextPDF\Contracts\ExternalResourcePolicyInterface;
use NextPDF\Contracts\HtmlSecurityPolicyInterface;
use Psr\Log\LoggerInterface;

final readonly class UntrustedHtmlGate
{
    public function __construct(
        private HtmlSecurityPolicyInterface $htmlPolicy,
        private ExternalResourcePolicyInterface $resourcePolicy,
        private CryptoPolicyInterface $cryptoPolicy,
        private LoggerInterface $logger,
    ) {}

    /**
     * Reject input that exceeds the configured limits before rendering.
     *
     * @param string $html Untrusted HTML markup.
     */
    public function assertAcceptable(string $html): void
    {
        $maxInput = $this->htmlPolicy->getMaxInputSize();

        if ($maxInput > 0 && \strlen($html) > $maxInput) {
            $this->logger->warning('HTML rejected: input over limit', [
                'policy' => $this->htmlPolicy->getName(),
                'limit' => $maxInput,
            ]);

            throw new \LengthException('HTML input exceeds policy limit.');
        }

        if ($this->resourcePolicy->isSvgExternalReferenceAllowed()) {
            $this->logger->error('Unsafe policy: SVG external references enabled.');

            throw new \LogicException('SVG external references must be denied in production.');
        }
    }
}

Geçit, giriş üst sınırını uygular ve işlem hattı çalışmadan önce güvensiz bir kaynak ilkesini reddeder. Denetim için ilke adını günlüğe kaydeder ve belirli bir özel durum fırlatır.

Uç durumlar ve tuzaklar

CryptoPolicyInterface hiçbir ilke ayarlanmadığında her algoritmaya izin verir. Bu açık varsayılan değer, bir üretim duruşu değil, geliştirme kolaylığıdır. Düzenlemeye tabi herhangi bir dağıtımda açık bir ilke ayarlayın.
HtmlSecurityPolicyInterface::getMaxInputSize() sınırsız değer için 0 döndürür. 0 değerini “tümünü reddet” olarak değil, “ilke sınırı yok” olarak değerlendirin. Ayrıca aktarım katmanında da bir üst sınır uygulayın.
ExternalResourcePolicyInterface varsayılan olarak tümünü reddeder. Bir şema listesi ayarlamadan @font-face veya background-image etkinleştirmek bir istek sahteciliği yüzeyi açar; izin listesini aynı anda tanımlayın.
Boş bir etki alanı izin listesi bırakılan getAllowedImageDomains(), arka plan görüntüleri etkinleştirildiğinde tüm etki alanlarına izin verildiği anlamına gelir. Boş bir liste reddetme kuralı değildir; açık etki alanları sağlayın.
isSvgExternalReferenceAllowed() üretimde false döndürmelidir. Sözleşme bunu belgeler; true döndüren bir ilke, bir yapılandırma seçimi değil, bir bulgudur.

Performans

Bir ilke denetimi bir yüklem çağrısıdır; O(1) çalışır ve girişle orantılı bir maliyeti yoktur. Ayrıştırma sırasında ilkeye etiket başına, öznitelik başına, CSS özelliği başına ve URL başına başvurulur. Patolojik bir belge çağrı sayısını artırır, ancak her çağrı sabit zamanda kalır. 1500 ms duvar süresi ve 64 MB tepe değeri olan performance_budget değerinde baskın maliyet ilke değerlendirmesi değil, ayrıştırma ve işlemedir. Giriş boyutu ve iç içe yerleştirme derinliği üst sınırları, ayrıştırıcının kendi maliyetini sınırlar. Katı bir ilke, aşırı büyük veya çok derin iç içe yerleştirilmiş bir belgeyi yerleşimden önce reddederek en kötü durum performansını iyileştirir.

Güvenlik notları

Bu sözleşmeler motorun savunma sınırını oluşturur, bu nedenle tehdit modeli nettir. CryptoPolicyInterface herhangi bir işlemden önce zayıf karmaları ve kısa anahtarları engelleyerek algoritma düşürme riskini azaltır. HtmlSecurityPolicyInterface izin verilmeyen etiketleri, öznitelikleri ve CSS’yi işleyici çalışmadan önce ayrıştırma katmanında çıkararak Portable Document Format (PDF) çıktısını etkileyen siteler arası betik çalıştırmayı ve içerik enjeksiyonunu azaltır. ExternalResourcePolicyInterface varsayılan olarak tümünü reddederek ve her getirme işlemini şemaya, boyuta, derinliğe ve etki alanına göre sınırlayarak sunucu tarafı istek sahteciliğini, açma bombalarını ve birikimli boyut bombalarını azaltır. Giriş boyutu, iç içe yerleştirme derinliği, yazı tipi glifi ve içe aktarma derinliği üst sınırları, kaynak tükenmesini azaltır. Her ilke bir sözleşme olduğu için, motoru çatallamadan ortamı sertleştirebilirsiniz ve ilke adı denetim günlüğü için sunulur. Tüm HTML’yi, tüm URL’leri ve tüm yazı tipi ile görüntü baytlarını düşmanca kabul edin. Bu sayfa export_control_class: legal-review-required olarak işaretlenmiştir çünkü sözleşmeler şifreleme ilkesini yönetir; metin tüm normatif kaynakları yeniden ifade eder ve hiçbirini alıntılamaz.

Uygunluk

İddia	Standart	Madde	Kanıt
Kısıtlanmamış URL işleme, URL değişiklikleriyle erişim denetiminin atlanmasına olanak tanır; harici kaynak ilkesi, tümünü reddet varsayılanları ve tam eşleşmeli bir etki alanı izin listesiyle bu riski azaltır.	OWASP Top 10 2025	A01
Harici bileşen kaynağı, resmi kökenlerle ve güvenli aktarımla sınırlandırılmalıdır; ilke bunu şema izin listeleri aracılığıyla destekler.	OWASP Top 10 2025	Yazılım tedarik zinciri

Her iki nokta da OWASP kılavuzunu yeniden ifade eder. Sayfa, OWASP materyaline madde numarasıyla başvurur; motor metnini yeniden üretmez.

Ticari bağlam

Core, üç ilke sözleşmesini tanımlar ve sabitler. Geliştirme için izin verici varsayılanlar, tümünü reddet kaynak ilkesi için de katı varsayılanlar sunar. Enterprise sürümü, CryptoPolicyInterface’in arkasında bir FIPS 140-3 profili sunar; böylece düzenlemeye tabi bir dağıtım, imzalama veya şifreleme kodunu değiştirmeden doğrulanmış bir algoritma duruşu kazanır. Sözleşme yüzeyi sürümler arasında aynıdır. Fark, enjekte ettiğiniz ilke uygulamasıdır.

Ayrıca bakınız

Sözleşmeler: 41 genel arabirim (hizmet sağlayıcı arabirimi, SPI) — genel bakış ve kararlılık katmanları.
Sözleşmeler / İmzalama — imzalamaya uygulanan CryptoPolicyInterface.
Sözleşmeler / Belge — bu ilkelerin denetlediği writeHtml() ve image() giriş noktaları.
Güvenlik — şifreleme ilkesinin kısıtladığı şifreleme yüzeyi.
HTML — HTML ve kaynak ilkelerinin koruduğu ayrıştırma işlem hattı.
Denetim — ilke adının denetim günlüğüne kaydedilmesi.