العقود / سياسة الأمان

نظرة سريعة

يعرّف نطاق سياسة الأمان ثلاثة عقود تعتمد مبدأ المنع افتراضيًا: يتحكم CryptoPolicyInterface في خيارات الخوارزمية والمفتاح، ويقيّد HtmlSecurityPolicyInterface سطح ميزات لغة ترميز النص التشعبي (⁨HTML⁩)، ويتولى ExternalResourcePolicyInterface ضبط تحميل الموارد البعيدة. ولأن كلًّا منها عقد، يمكنك توفير سياسة نشر أكثر صرامة دون تفريع الشيفرة.

التثبيت

composer require nextpdf/core:^3

نظرة مفاهيمية عامة

يمثّل CryptoPolicyInterface بوابة التشفير. يستدعيه ⁨Core⁩ قبل أي خطوة توقيع أو تشفير أو تجزئة. يشمل الفحص التجزئة، ومعرّف كائن التوقيع (⁨OID⁩)، والشيفرة، وقوة المفتاح. كما يبلّغ العقد عن الحد الأدنى للتجزئة واسم السياسة المخصص لسجل التدقيق. استخدمه لتطبيق مجموعة قواعد مثل معايير المعالجة الفيدرالية للمعلومات (⁨FIPS⁩) 140-3 أو ⁨eIDAS.⁩ ولا تتغير شيفرة التوقيع والتشفير. عندما لا تُعيَّن أي سياسة، يُسمح بكل خوارزمية. يجب على الموقع الخاضع للتنظيم تعيين سياسة صريحة.

يعمل HtmlSecurityPolicyInterface في طبقة تحليل ⁨HTML.⁩ ويُنفَّذ قبل أن يصل المحتوى إلى أي محرّك عرض. يقرر ما إذا كان الوسم أو السمة أو خاصية صفحات الأنماط المتتالية (⁨CSS⁩) أو مخطط محدّد موقع الموارد الموحّد (⁨URL⁩) مسموحًا به. كما يحدّ من حجم الإدخال وعمق التداخل. يعمل مع سياسات النقل الخاصة بكل محرّك عرض ‏(⁨Chrome⁩ و⁨Cloudflare⁩ و⁨Gotenberg⁩)، التي تضبط حدود الحجم وترويسات سياسة أمان المحتوى (⁨CSP⁩). تقلّل سياسة ⁨HTML⁩ سطح الهجوم في طبقة التحليل. لا يصل الوسم المُزال أبدًا إلى التخطيط. ولا يمكن لعنصر محقون أن يغيّر المُخرَج. عندما لا تُعيَّن أي سياسة، يسمح الإعداد الافتراضي بمجموعة الميزات الكاملة.

يقرر ExternalResourcePolicyInterface ما إذا كان مسار ⁨HTML⁩ يجوز له جلب خط أو ورقة أنماط أو صورة خارجية. كما يضبط الحدود لكل عملية جلب. موقفه الافتراضي هو منع الكل. كل خيار مُعطَّل إلى أن تفعّله. يتّبع العقد مبدأ الامتياز الأدنى. قد يشير ⁨HTML⁩ غير الموثوق إلى عنوان ⁨URL⁩ يتحكم فيه المهاجم. يضبط بوابة عمليات جلب @font-face حسب المخطط والحجم وعدد المحارف. ويضبط بوابة @import حسب المخطط والعمق والحجم الإجمالي. ويضبط بوابة background-image عبر قائمة مخططات وقائمة سماح نطاقات بمطابقة تامة. يحدّ من حجم ⁨data-URI⁩ ‏(معرّف الموارد الموحّد). كما يضبط بوابة المراجع الخارجية للرسومات المتجهة القابلة للتحجيم (⁨SVG⁩). ينص العقد على أن بيئة الإنتاج يجب أن تمنعها دائمًا. فهي تتيح تزوير الطلبات وحقن البرامج النصية. ويُعد جلب عناوين ⁨URL⁩ المفتوحة مسارًا لتزوير الطلبات من جانب الخادم. يمكن تجاوز التحكم في الوصول بتغيير عنوان ⁨URL⁩، كما يصف ذلك مشروع أمان تطبيقات الويب العالمي المفتوح (⁨OWASP⁩) ⁨Top 10 2025.⁩ يجب أن يقتصر الحصول على المكونات الخارجية على المصادر الرسمية والنقل الآمن.

سطح ⁨API⁩

النوع	الصنف	الأعضاء الرئيسيون	الاستقرار	منذ
CryptoPolicyInterface	واجهة	isHashAlgorithmAllowed(), isSignatureAlgorithmAllowed(), isEncryptionAlgorithmAllowed(), isKeyStrengthAllowed(), getPreferredHashAlgorithm(), getName()	مستقر	1.9.0
HtmlSecurityPolicyInterface	واجهة	isTagAllowed(), isAttributeAllowed(), isCssPropertyAllowed(), isUrlSchemeAllowed(), getMaxInputSize(), getMaxNestingDepth(), getName()	مستقر	3.1.0
ExternalResourcePolicyInterface	واجهة	isFontFaceAllowed(), getAllowedFontSchemes(), getMaxFontFileSize(), getMaxFontGlyphs(), isImportAllowed(), getMaxImportDepth(), isBackgroundImageAllowed(), getAllowedImageDomains(), getMaxDataUrlSize(), isSvgExternalReferenceAllowed()	مستقر	4.0.0

يعيد ExternalResourcePolicyInterface حدودًا محددة الأنواع: أحجام positive-int، وعمق استيراد int<1, 100>، وقوائم مخططات ونطاقات list<non-empty-string>. يمنع التنفيذ الافتراضي كل قدرة.

عينة شيفرة — بداية سريعة

examples/contracts/security-policy-quickstart.php

<?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);
}

تعتمد الدالة على العقد فقط. وتستوفيه كل من السياسة المقيِّدة والسياسة الافتراضية.

عينة شيفرة — الإنتاج

examples/contracts/security-policy-production.php

<?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.');
        }
    }
}

تفرض البوابة حد الإدخال وترفض أي سياسة موارد غير آمنة قبل تشغيل المسار. تسجّل اسم السياسة لأغراض التدقيق وتطلق استثناءً محددًا.

الحالات الحدية والمزالق

• يسمح CryptoPolicyInterface بكل خوارزمية عندما لا تُعيَّن أي سياسة. الإعداد الافتراضي المفتوح تسهيل للتطوير، وليس وضعًا للإنتاج. عيّن سياسة صريحة في أي نشر خاضع للتنظيم.
• تعيد HtmlSecurityPolicyInterface::getMaxInputSize() القيمة 0 للدلالة على عدم وجود حد. تعامل مع 0 على أنها “لا يوجد حد للسياسة”، وليس “رفض الكل”. طبّق حدًّا في طبقة النقل أيضًا.
• ExternalResourcePolicyInterface يمنع الكل افتراضيًا. يؤدي تمكين @font-face أو background-image دون تعيين قائمة مخططات إلى فتح سطح لتزوير الطلبات؛ عيّن قائمة السماح في الوقت نفسه.
• تعني قائمة سماح النطاقات الفارغة في getAllowedImageDomains() أن جميع النطاقات مسموح بها بمجرد تمكين صور الخلفية. القائمة الفارغة ليست قاعدة منع؛ وفّر نطاقات صريحة.
• يجب أن تعيد isSvgExternalReferenceAllowed() القيمة false في بيئة الإنتاج. يوثّق العقد ذلك؛ والسياسة التي تعيد true خلل مكتشَف، وليست خيار تهيئة.

الأداء

فحص السياسة استدعاء منطقي محمول: ⁨O⁩(1)، دون كلفة تتناسب مع الإدخال. تُستشار السياسة لكل وسم ولكل سمة ولكل خاصية ⁨CSS⁩ ولكل عنوان ⁨URL⁩ أثناء التحليل. يزيد المستند الشاذ عدد الاستدعاءات، لكن كل استدعاء يبقى ثابت الزمن. تهيمن المعالجة والتحليل والعرض على performance_budget البالغة 1500 ⁨ms⁩ للزمن الفعلي و64 ⁨MB⁩ للذروة، لا تقييم السياسة. يحدّ سقفا حجم الإدخال وعمق التداخل من كلفة المحلّل نفسه. تحسّن السياسة الصارمة أداء الحالة الأسوأ برفض مستند مفرط الحجم أو عميق التداخل قبل التخطيط.

ملاحظات الأمان

تشكّل هذه العقود المحيط الدفاعي للمحرك، لذلك يكون نموذج التهديد صريحًا. يخفّف CryptoPolicyInterface من خفض مستوى الخوارزمية بحظر التجزئات الضعيفة والمفاتيح القصيرة قبل أي عملية. ويخفّف HtmlSecurityPolicyInterface من البرمجة العابرة للمواقع التي تؤثر في مُخرَج تنسيق المستندات المحمولة (⁨PDF⁩) وحقن المحتوى، وذلك بإزالة الوسوم والسمات و⁨CSS⁩ غير المسموح بها في طبقة التحليل قبل تشغيل محرّك العرض. ويخفّف ExternalResourcePolicyInterface من تزوير الطلبات من جانب الخادم، وقنابل فك الضغط، وقنابل الحجم التراكمي، من خلال جعل المنع الافتراضي للكل وتقييد كل عملية جلب حسب المخطط والحجم والعمق والنطاق. تخفّف سقوف حجم الإدخال وعمق التداخل ومحارف الخط وعمق الاستيراد من استنزاف الموارد. ولأن كل سياسة عقد، يمكنك تعزيز المحيط دون تفريع المحرك، ويُكشَف اسم السياسة لتسجيل التدقيق. تعامل مع كل ⁨HTML⁩ وكل عناوين ⁨URL⁩ وكل بايتات الخطوط والصور على أنها معادية. هذه الصفحة موسومة بـ export_control_class: legal-review-required لأن العقود تحكم سياسة التشفير؛ والنص يعيد صياغة جميع المصادر المعيارية ولا يقتبس أيًّا منها.

المطابقة

الادعاء	المعيار	البند	الدليل
تتيح معالجة عناوين ⁨URL⁩ دون قيود لتغييرات ⁨URL⁩ تجاوز التحكم في الوصول، وهو ما تخفّفه سياسة الموارد الخارجية بإعدادات منع الكل الافتراضية وقائمة سماح نطاقات بمطابقة تامة.	⁨OWASP Top 10 2025⁩	⁨A01⁩
يجب أن يقتصر الحصول على المكونات الخارجية على المصادر الرسمية والنقل الآمن، وهو ما تدعمه السياسة من خلال قوائم سماح المخططات.	⁨OWASP Top 10 2025⁩	سلسلة توريد البرمجيات

تعيد كلتا النقطتين صياغة إرشادات ⁨OWASP.⁩ تشير الصفحة إلى مواد ⁨OWASP⁩ حسب البند؛ ولا يعيد المحرك إنتاج نصها.

السياق التجاري

يعرّف ⁨Core⁩ عقود السياسة الثلاثة ويجمّدها. يُشحَن بإعدادات افتراضية متساهلة للتطوير، وبإعدادات افتراضية صارمة لسياسة موارد تمنع الكل. ويُشحَن إصدار ⁨Enterprise⁩ بملف تعريف ⁨FIPS 140-3⁩ خلف CryptoPolicyInterface، فيحصل النشر الخاضع للتنظيم على وضع خوارزمي مُتحقَّق منه دون تغيير شيفرة التوقيع أو التشفير. سطح العقد متطابق عبر الإصدارات. والفرق هو تنفيذ السياسة الذي تحقنه.

انظر أيضًا

• العقود: 41 واجهة عامة (واجهة موفّر الخدمة، ⁨SPI⁩) — نظرة عامة وفئات الاستقرار.
• العقود / التوقيع — CryptoPolicyInterface مُطبَّقًا على التوقيع.
• العقود / المستند — نقطتا الدخول writeHtml() وimage() اللتان تضبطهما هذه السياسات.
• الأمان — سطح التشفير الذي تقيّده سياسة التشفير.
• ⁨HTML⁩ — مسار التحليل الذي تحرسه سياستا ⁨HTML⁩ والموارد.
• التدقيق — تسجيل تدقيق اسم السياسة.