الأمان والتشغيل في NextPDF Symfony

لمحة سريعة

تطبّق مساعدات الاستجابة مجموعة ثابتة من ترويسات الأمان. يتحقق كائن نقل بيانات الرسالة غير المتزامنة (⁨DTO⁩) من مسار الإخراج مرتين. التوقيع اختياري، ومع فئة ⁨Pro⁩ يظل مقصورًا على الملف الأساسي الموثّق هنا.

ترويسات أمان استجابة ⁨HTTP⁩

تطبّق NextPDF\Symfony\Http\PdfResponse مجموعة الترويسات نفسها على كل استجابة تنشئها: المضمَّنة، والتنزيل، وكلا المتغيّرين المتدفّقين. يتحقق الثابت المصدري من هذه الترويسات تحديدًا:

الترويسة	القيمة
`Cache-Control`	`private, max-age=0, must-revalidate`
`Pragma`	`public`
`X-Content-Type-Options`	`nosniff`
`X-Frame-Options`	`DENY`
`Content-Security-Policy`	`default-src 'none'`
`X-Robots-Tag`	`noindex, nofollow`
`Referrer-Policy`	`no-referrer`

تحدّ هذه الترويسات من استشفاف ⁨content-type⁩، والتأطير، والفهرسة، وتسريب المُحيل في المستندات المُنشأة. كما تضبط المتغيّرات المخزَّنة مؤقتًا Content-Type: application/pdf وContent-Length. أما المتغيّرات المتدفّقة فتضبط نوع المحتوى وتُسقِط Content-Length عمدًا حسب التصميم.

تثبّت الحزمة مجموعة الترويسات هذه. لإضافة ترويسات أو تغييرها، مثل جعل Cache-Control أكثر صرامةً للتنزيلات المُصادَق عليها، عدّل كائن Response المُعاد في المتحكّم لديك قبل إرجاعه.

معالجة ⁨Content-Disposition⁩ واسم الملف

تبني PdfResponse ترويسة Content-Disposition بأسلوب دفاعي. يتحقق PdfResponseTest من هذا السلوك:

يُنقّى اسم الملف؛ إذ تُزال فواصل المسار وتسلسلات الاجتياز، بحيث لا يستطيع اسم ملف مثل ../../../etc/passwd.pdf الإفلات.
يُضاف امتداد .pdf عند غيابه؛ ولا يُكرَّر امتداد موجود مسبقًا، بما في ذلك .PDF بأحرف كبيرة.
تُهرَّب علامات الاقتباس المزدوجة والشرطات المائلة العكسية بما يلائم صيغة السلسلة المقتبسة.
تتلقّى أسماء الملفات غير ⁨ASCII⁩ بديلًا احتياطيًّا بصيغة ⁨ASCII⁩ ومتغيّر filename*=UTF-8'' وفق ⁨RFC-5987⁩ (⁨Request for Comments 5987⁩).
يعود اسم الملف الفارغ إلى document.pdf.

مرّر اسم ملف متأثّرًا بالمستخدم فقط بعد فحص التفويض على مستوى تطبيقك. تُنقّي الحزمة الاسم لضمان سلامة الترويسة، لا للتحكّم في الوصول.

التحقق من مسار الإخراج بشكل غير متزامن

يتحقق NextPDF\Symfony\Message\GeneratePdfMessage من مسار الإخراج في مُنشئه. ويعيد NextPDF\Symfony\Message\GeneratePdfHandler التحقق منه وقت التنفيذ قبل الكتابة. يرفض الإنشاء:

مسارًا فارغًا، أو مسارًا يحتوي على بايت خالٍ؛
مخطّط مُغلِّف دفق مثل php://...؛
مقطع اجتياز .. يستخدم فاصل / أو \؛
مسارًا لا ينتهي بـ .pdf (غير حسّاس لحالة الأحرف)؛
builderClass عندما لا يكون اسم صنف صحيحًا نحويًّا.

يهمّ التحقق الثاني في المعالِج لأن الرسالة قد تبقى في طابور بين الإرسال والاستهلاك. لا يثق المعالِج بالمسار المُدرَج في الطابور، ويطبّق حارس المسار مرة أخرى قبل الحفظ. شغّل العمّال بحساب نظام ملفات ذي أدنى امتيازات، ومقصور على دليل الإخراج المقصود.

حدود تحليل البنّاء

يحلّل GeneratePdfHandler البنّائين من محدِّد خدمات وفق ⁨PHP Standard Recommendation 11⁩ (⁨PSR-11⁩) مفهرَس باسم الصنف، ويرفض أي شيء لا يطابق PdfBuilderInterface. وبما أن المحدِّد لا يكشف إلا البنّائين المُسجَّلين، فإن builderClass الذي يتحكّم فيه مهاجم عبر حمولة نقل مُلاعَب بها لا يمكنه إنشاء مثيل من صنف عشوائي. بموجب ⁨PSR-11⁩، عندما يبلّغ حاوٍ عن مُعرِّف بوصفه غائبًا، يفشل تحليله بدلًا من إعادة شيء غير متوقّع بصمت (⁨PSR-11⁩ §1.1.2). سجّل أصناف البنّائين الموثوقة فقط في المحدِّد.

وضع التوقيع الرقمي الاختياري

التوقيع الرقمي ليس جزءًا من الحزمة الأساسية. لا يُفعَّل إلا عندما يكون nextpdf/premium (الذي يثبّت فئة ⁨Pro⁩) موجودًا ويكتشف ممرّ المُصرِّف أصناف توقيع ⁨Pro.⁩ عند تثبيت الحزمة وفئة ⁨Pro⁩، يكون تكوين التوقيع المدعوم والموثّق هو الملف الأساسي ⁨B-B⁩.

تقبل عقدة التكوين signature.level قيمًا نصية إضافية لتوافق المخطّط عبر عائلة تكوين ⁨NextPDF.⁩ قدرة التوقيع المُسلَّمة والمدعومة في هذه الحزمة هي ⁨B-B.⁩ يغطّي توثيق ⁨NextPDF Premium⁩ ملفات التوقيع التي تتجاوز ⁨B-B⁩، ومتطلباتها، واعتباراتها التشغيلية. ولا تُوصَف هنا عن قصد.

ملاحظات تشغيلية لمسار التوقيع ⁨B-B⁩:

يُسجَّل المُوقِّع فقط عندما يكون signature.enabled صحيحًا ويكون signature.certificate مضبوطًا؛ وإلا يبقى القسم خاملًا.
قدّم الشهادة والمفتاح الخاص وكلمة المرور عبر أسرار ⁨Symfony⁩ أو متغيّرات البيئة. لا تودِعها في المستودع أبدًا.
اقصر أذونات قراءة مادة المفتاح على حساب التطبيق.

التسجيل الاختياري

يقبل سجلّا الخطوط والصور Psr\Log\LoggerInterface اختياريًّا مربوطًا بـ nullOnInvalid(). عند وجوده، يكون متعاوِنًا قابلًا للاستبدال بموجب عقد المُسجِّل وفق ⁨PHP Standard Recommendation 3⁩ (⁨PSR-3⁩) (⁨PSR-3⁩). احذف البيانات التي تُعرّف هوية المستخدم من أي سياق سجلّ تضيفه حول إنشاء المستندات؛ فالحزمة لا تسجّل محتوى المستند.

قائمة تحقق تعزيز الأمان التشغيلي

أبقِ ترويسات الاستجابة الثابتة؛ وأضف تخزينًا مؤقتًا أكثر صرامةً للتنزيلات المُصادَق عليها في المتحكّم.
افحص تفويض الطلب قبل إنشاء مستند أو إعادته؛ فالحزمة لا تنفّذ التحكّم في الوصول.
خزّن مادة مفتاح التوقيع في أسرار ⁨Symfony⁩ / متغيّرات البيئة بأذونات ملفات بأدنى الامتيازات.
شغّل عمّال ⁨Messenger⁩ بحساب بأدنى الامتيازات مع اقتصار صلاحية الكتابة على دليل الإخراج.
أبقِ ext-mbstring وext-zlib مُمكَّنَين (وإلا فستفشل الحزمة سريعًا).
ثبّت إصدارًا رئيسيًّا واحدًا من nextpdf/core في التطبيق لجعل إصدار المحرّك حتميًّا عبر عمليات النشر.

المطابقة

كل صف هو ادّعاء معياري مذكور في هذه الصفحة، ومثبّت إلى reference_id ست عشري كامل من 64 خانة من مجموعة منظمة تطوير المعايير (⁨SDO⁩) المُحكَمة. المصدر (بيان المجموعة، ونقل الاسترجاع) موجود في _sidecars/rag-citations.yaml.

المواصفة	البند	⁨reference_id⁩	الادّعاء
⁨PSR-11⁩	`psr_11_container#1.1.2.p5`		قيمة ⁨has⁩() الكاذبة تستلزم أن يطلق ⁨get⁩() استثناء ⁨NotFoundException⁩
⁨PSR-3⁩	`psr_3_logger#x3.p17`		متعاوِن مُسجِّل اختياري

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

التوقيع الرقمي متاح فقط عند تثبيت ⁨nextpdf/premium⁩ (⁨Pro⁩)؛ والملف المُسلَّم في هذه الحزمة هو الأساسي ⁨B-B.⁩ لا تتطلّب قدرة ⁨Pro⁩ الاختيارية هذه أي تغيير في الكود ضمن حزمة ⁨Core⁩ الموثّقة هنا. راجع </get-license/?intent=symfony-pro>.

انظر أيضًا

/⁨integrations/symfony/production-usage/⁩ — سلامة العمّال والتدفّق.
/⁨integrations/symfony/configuration/⁩ — جداول التوقيع و⁨tsa⁩ والخدمة.
/⁨integrations/symfony/troubleshooting/⁩ — تشخيص مشكلات التوقيع و⁨Messenger.⁩
/⁨integrations/symfony/integration/⁩ — مرجع التوصيل الشامل من البداية إلى النهاية.