تطبيق توقيع رقمي PAdES عبر NextPDF Connect (Pro)

لمحة سريعة

طبّق توقيعًا رقميًا أساسيًا من نوع ⁨PDF Advanced Electronic Signatures⁩ (⁨PAdES⁩) على ملف ⁨PDF⁩ عبر ⁨NextPDF Connect.⁩ استخدم sign_pdf، بعد التحقق منه مقابل موفّر أدوات ⁨Pro⁩: إذ يسجّل ذلك الموفّر new SignPdfTool()، واسم بروتوكوله هو sign_pdf. sign_pdf أداة من فئة ⁨Pro.⁩ عند الإقلاع، يفحص الخادم وجودها باستخدام class_exists() ولا يسجّلها إلا عند تثبيت حزمة ⁨Pro.⁩

تنتج الأداة افتراضيًا ⁨PAdES B-B⁩. ويمكنها إنتاج ⁨PAdES B-T⁩ (⁨B-B⁩ إضافةً إلى ⁨RFC 3161 signature-time-stamp⁩ واحدة) فقط عندما يكون المضيف قد ربط موفّر طوابع زمنية بالأداة؛ ولا يستطيع الطلب تحديد ⁨Time Stamp Authority⁩ (⁨TSA⁩). أمّا مستويات الأمد الطويل (⁨B-LT⁩، ⁨B-LTA⁩) ومواد التحقق الخاصة بها (⁨DSS⁩، ⁨VRI⁩، ⁨LTV⁩) فهي ليست جزءًا من هذه الأداة، وتقع خارج النطاق هنا.

تنبيه ⁨U-1.⁩ لا يؤكّد ⁨NextPDF⁩ أي اعتماد مستقل من نوع ⁨ETSI EN 319 142-1⁩ لـ ⁨PAdES B-T. EN 319 142-1⁩ ليست ضمن مجموعة التحقق المرجعية. جرى التحقق من متطلَّب ⁨B-T⁩ الخاص بـ signature-time-stamp مقابل ⁨ETSI EN 319 122-1⁩ §5.3 (أساس ⁨CAdES⁩ الذي تستورده ⁨EN 319 142-1/-2⁩ بالإشارة المرجعية)، إلى جانب ⁨RFC 3161⁩، ⁨RFC 5652⁩، ⁨RFC 5816⁩، و⁨ISO 32000-2⁩ §12.8. دعم ملف تعريف ⁨B-T⁩ ليس اعتماد مطابقة ولا إثباتًا للصحة القانونية؛ فذلك يقرّره مُحقِّق مستقل.

التثبيت

composer require nextpdf/server
composer require nextpdf/pro

اربط وسيط نقل، ثم تأكّد من وجود sign_pdf عبر diagnostic.capabilities. من أجل ⁨B-T⁩، يجب أن ينشئ المضيف الأداة مزوّدةً بموفّر طوابع زمنية. وبدونه، يفشل طلب pades_b_t: true بخطأ مُصنَّف بدلًا من الخفض الصامت.

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

يحسب sign_pdf ملخص النطاق البايتي للملف، مع استثناء العنصر النائب لقيمة التوقيع (⁨ISO 32000-2⁩ §12.8.1). ثم يكتب ⁨Cryptographic Message Syntax⁩ (⁨CMS⁩) ⁨SignedData⁩ بترميز ⁨Distinguished Encoding Rules⁩ (⁨DER⁩) في قاموس التوقيع Contents (⁨ISO 32000-2⁩ §12.8.1). الخوارزميات المدعومة هي ⁨RSA-SHA256⁩ (الافتراضية)، و⁨RSA⁩ + ⁨SHA-3⁩ (256/384/512)، و⁨Ed25519.⁩ بالنسبة إلى وسائط النقل غير السرّية من الطرف إلى الطرف، يمكنك اختياريًا تغليف حمولة private_key الواردة بغلاف ⁨AES-GCM⁩.

ترقية ⁨B-T⁩. مع pades_b_t: true و موفّر طوابع زمنية مربوط من المضيف، يُرقَّى التوقيع إلى ⁨PAdES B-T⁩: تُرسَل تجزئة النطاق البايتي إلى ⁨TSA⁩ ويُضمَّن ⁨TimeStampToken⁩ (⁨ISO 32000-2⁩ §12.8.5). ⁨B-T⁩ هو ⁨B-B⁩ نفسه مضافًا إليه ⁨RFC 3161 signature-time-stamp⁩ واحدة محمولة كسمة غير موقَّعة على ⁨CMS SignerInfo⁩ (⁨RFC 5652⁩ §5.3). السمات غير الموقَّعة غير مشمولة بالتوقيع، لذا يبقى ملخص ⁨B-B⁩ الموقَّع وصحّته دون تغيير (⁨RFC 5652⁩ §5.3). قيمة السمة هي ⁨SignatureTimeStampToken⁩ (⁨ETSI EN 319 122-1⁩ §5.3). ⁨B-T⁩ لا يضيف قاموس ⁨Document Security Store⁩ (⁨DSS⁩) ولا ⁨Validation Related Information⁩ (⁨VRI⁩)، ولا مواد تحقق، ولا حلقة طابع زمني أرشيفي. تلك هي دلتا ⁨B-LT/B-LTA⁩ الخاصة بـ ⁨Enterprise⁩، وتقع خارج نطاق هذه الأداة.

تنبيه ⁨U-1⁩ (مُكرَّر عند ادّعاء ⁨B-T⁩). دعم ⁨B-T⁩ هنا ليس اعتماد مطابقة ⁨EN 319 142-1⁩ ولا إثباتًا للصحة القانونية؛ فذلك يقرّره مُحقِّق مستقل. ⁨EN 319 142-1⁩ ليست ضمن مجموعة التحقق المرجعية. يستند ⁨B-T⁩ إلى ⁨ETSI EN 319 122-1⁩ §5.3، و⁨RFC 3161⁩، و⁨RFC 5652⁩، و⁨RFC 5816⁩، و ⁨ISO 32000-2⁩ §12.8.

يُظهِر التدفق أدناه مسار ⁨TSA⁩ المُبوَّب على المضيف (لا يمكن للطلب أن يحدّد ⁨TSA⁩) وفرع ⁨B-T⁩ الذي يفشل بإغلاق آمن (لا خفض صامت أبدًا).

Diagram

سطح واجهة برمجة التطبيقات

الأداة	الفئة	الدور	فئة المخاطر
create_pdf، add_text	⁨Core⁩	بناء المحتوى	آمن / تحذير
sign_pdf	⁨Pro⁩	تطبيق ⁨PAdES B-B⁩ (أو ⁨B-T⁩ المُبوَّب على المضيف)	يتطلب موافقة
output_pdf	⁨Core⁩	عرض ملف ⁨PDF⁩ وإرجاعه	تتطلب موافقة / مراجعة (⁨base64⁩)

أسماء الأدوات هي أسماء البروتوكول في السجلّ. يُعدّ كتالوج الأدوات الكتالوج المرجعي. تتوقف الأدوات المتاحة على الفئة المُثبَّتة، وأدوات مستوى الأمد الطويل غير موجودة في ⁨Pro.⁩

نموذج برمجي — بداية سريعة

1. create_pdf ← بناء المحتوى باستخدام add_text.
2. sign_pdf مع certificate (⁨PEM⁩)، وprivate_key (⁨PKCS⁩#8 ⁨PEM⁩)، وsigner_name وreason وalgorithm الاختيارية. احذف pades_b_t (أو اضبطه على false) للحصول على ⁨B-B.⁩
3. output_pdf.

تُرجِع الأداة غلاف النتيجة هذا:

{
  "pdf": "<base64 of the signed PDF>",
  "signature_count": 1,
  "is_complete": true,
  "algorithm": "RSA_SHA256",
  "oid": "<algorithm OID>",
  "digest": "<digest algorithm>",
  "level": "PAdES-B-B",
  "timestamped": false
}

للحصول على توقيع ⁨B-T⁩ مُبوَّب على المضيف، أرسِل pades_b_t: true؛ ستصبح قيمة level هي "PAdES-B-T"، وستصبح timestamped هي true.

نموذج برمجي — إنتاجي

اجعل التوقيع عملية المحتوى الأخيرة. أي add_text/add_image بعد sign_pdf يُبطِل التوقيع. على وسيط نقل غير سرّي، غلّف private_key داخل غلاف ⁨AES-GCM⁩ transport_encryption (قيمة عشوائية بطول 12 بايت؛ مفتاح بطول 16/24/32 بايت). تحقّق من أن level في النتيجة يطابق طلبك. طلب pades_b_t: true مقابل أداة بلا موفّر يفشل صراحةً. عالِج ذلك الخطأ، ولا تُعِد المحاولة بصمت كـ ⁨B-B.⁩

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

• عدم تطابق الشهادة/المفتاح. ترفض الأداة الطلب بخطأ واضح؛ يجب أن يطابق المفتاح الخاص المفتاح العام للشهادة.
• شهادة ⁨PEM⁩ مُشوَّهة / منتهية الصلاحية. ترفض الأداة الطلب؛ فهي لا توقّع افتراضيًا بشهادة غير قابلة للتحليل أو منتهية الصلاحية.
• محتوى بعد التوقيع. ترفض الأداة الطلب — اجعل التوقيع آخر خطوة.
• طُلِب ⁨B-T⁩ بلا موفّر. تُرجِع الأداة خطأً مُصنَّفًا: التوقيع لا يُنتَج ولا يُخفَّض بصمت إلى ⁨B-B.⁩
• شهادة موقَّعة ذاتيًا. يُطبَّق التوقيع، لكن القارئات تُظهِر ثقة غير معروفة. هذا متوقَّع، وليس عيبًا في الأداة.
• غياب ⁨Pro.⁩ مع ⁨Core⁩ فقط، لا يسجّل الخادم sign_pdf.

الأداء

يضيف التوقيع بناء ⁨CMS⁩، ومن أجل ⁨B-T⁩ يضيف جولة ذهاب وإياب واحدة مع ⁨TSA⁩؛ وتغطي الميزانية كليهما. ملف التعريف هو semantic: رمز ⁨RFC 3161⁩ غير قابل للتكرار بطبيعته، وملخص النطاق البايتي في §12.8.1 يستثني قيمة التوقيع. استخدم فقط مقارنة تعتمد على ⁨AST⁩ + بيانات وصف التوقيع.

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

يوفّر التوقيع سلامة المستند والمصادقة عليه نسبةً إلى مفتاح التوقيع. وهو بذاته لا يجعل المستند “آمنًا” أو “صالحًا قانونيًا”، ولا يضمن عدم الإنكار. تتوقف تلك النتائج على الشهادة، ومرتكز الثقة الخاص بها، وعهدة المفتاح، وسياسة المُحقِّق، وكلها خارج هذه الأداة. تشفير حمولة المفتاح بغلاف ⁨AES-GCM⁩ يحمي السرّية أثناء النقل، لا السلامة. تعامل مع المفتاح الخاص بوصفه سرًّا، وفضّل غلاف تشفير النقل على أي قناة غير سرّية.

المطابقة

العبارة	المواصفة	البند	⁨reference_id⁩
يغطّي ملخص النطاق البايتي الملف ويستثني قيمة التوقيع.	⁨ISO 32000-2⁩	§12.8.1
Contents يحتوي على ⁨CMS SignedData⁩ بترميز ⁨DER.⁩	⁨ISO 32000-2⁩	§12.8.1
من أجل الطابع الزمني، تذهب تجزئة النطاق البايتي إلى ⁨TSA⁩ ويوضَع الرمز في Contents.	⁨ISO 32000-2⁩	§12.8.5
الطابع الزمني في ⁨B-T⁩ سمة غير موقَّعة على ⁨SignerInfo.⁩	⁨RFC 5652⁩	§5.3
السمات غير الموقَّعة لا تُغيِّر ⁨digest/validity.⁩ لتوقيع ⁨B-B⁩ الموقَّع.	⁨RFC 5652⁩	§5.3
قيمة ⁨signature-time-stamp⁩ هي ⁨SignatureTimeStampToken.⁩	⁨ETSI EN 319 122-1⁩	§5.3

يُنتِج ⁨NextPDF⁩ بنية التوقيع. وهو لا يؤكّد أن أي توقيع ناتج مطابق أو صالح قانونيًا؛ يقرّر ذلك مُحقِّق مستقل. لا تُنتِج هذه الأداة ⁨B-LT/B-LTA.⁩

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

sign_pdf أداة من فئة ⁨Pro.⁩ يسجّلها الخادم فقط عندما تُحلّ حزمة ⁨Pro⁩ عند إقلاع الخادم. مستويات الأمد الطويل في ⁨PAdES⁩ (⁨B-LT⁩، ⁨B-LTA⁩) ومواد التحقق الخاصة بها (⁨DSS⁩، ⁨VRI⁩، ⁨LTV⁩) هي حصرية لـ ⁨Enterprise⁩ ولا تكشفها هذه الأداة ولا هذه الوصفة.

إقامة البيانات وتخفيف مخاطر المعلومات الشخصية

تمرّ الشهادة والمفتاح الخاص عبر الطلب. استخدم غلاف ⁨AES-GCM⁩ transport_encryption على أي قناة ليست سرّية من الطرف إلى الطرف. يُعدّ ملف ⁨PDF⁩ الموقَّع وهوية الموقِّع (signer_name، reason) محتوى مستنديًا، فاحتفظ بهما ضمن حدود إقامة بياناتك. يتحمّل المُكامِل مسؤولية الإقامة على مستوى النشر.

القياس عن بُعد الآمن وتنظيف السجلّات

لا تسجّل أبدًا حمولة private_key، ولا ⁨key/nonce⁩ في ⁨AES-GCM⁩، ولا رمز التأكيد. سجّل الخوارزمية وlevel الناتج وsignature_count، لا مادة المفتاح. لا تُصدِر الأداة بايتات المفتاح في نتيجتها.

نموذج التهديد

التهديدات المعتبَرة: كشف المفتاح أثناء النقل (يخفّفه غلاف ⁨AES-GCM⁩ وموفّر ⁨TSA⁩ الذي يحقنه المضيف وغير القابل للضبط من الطلب)؛ ومُستدعٍ ⁨MCP⁩ يوجّه الطابع الزمني إلى نقطة نهاية عشوائية (يُمنَع لأن الموفّر يحقنه المضيف، ولا يضبطه الطلب)؛ والعبث بعد التوقيع (يكشف ملخص النطاق البايتي التعديل). يوثّق نموذج التهديد التهديدات المعتبَرة وإجراءات تخفيفها؛ وهو لا يؤكّد غياب الثغرات.

سلوك وضع ⁨FIPS⁩

اختيار الخوارزمية (⁨RSA-SHA256⁩، ⁨RSA⁩ + ⁨SHA-3⁩، ⁨Ed25519⁩) مدفوع بالطلب. يوفّر ⁨OpenSSL⁩ الخاص بالمضيف الأوّليّات التشفيرية. في نشر مُقيَّد بـ ⁨FIPS⁩، قيّد الخوارزميات في طبقة السياسة واعتمد على وحدة المضيف المُعتمَدة. لا تؤكّد هذه الأداة بذاتها اعتماد ⁨Federal Information Processing Standards⁩ (⁨FIPS⁩).

توافر وسائط النقل

وسيط النقل	متاح	ملاحظات
⁨MCP⁩ (⁨stdio⁩)	نعم (⁨Pro⁩)	استخدم غلاف مفتاح ⁨AES-GCM⁩ على ⁨stdio.⁩
⁨REST⁩	نعم (⁨Pro⁩)	فضّل ⁨TLS⁩ إضافةً إلى غلاف المفتاح.
⁨gRPC⁩	نعم (⁨Pro⁩)	فضّل ⁨TLS⁩ إضافةً إلى غلاف المفتاح.

فئة مخاطر ⁨HITL⁩

يقع sign_pdf ضمن فئة تتطلب موافقة لأنه عملية تدميرية لا رجعة فيها؛ وتُعلِن الأداة تلميحًا تدميريًا. تنطبق بوابة التأكيد كما تنطبق على أي أداة تتطلب موافقة. يتطلب output_pdf إلى ملف موافقة أيضًا؛ أما وضع ⁨base64⁩ فللمراجعة (فئات مخاطر ⁨HITL⁩).

غلاف ⁨JSON⁩ لبوابة التأكيد

sign_pdf بدون رمز صالح يُرجِع غلاف التحدّي:

{
  "allowed": false,
  "challenge": "⚠️ CONFIRMATION REQUIRED\n\nOperation: sign_pdf\nDescription: <tool description>\n\nTo proceed, call sign_pdf again with parameter _confirmation_token: \"confirm_<single-use-hex>\"\nExpires in 300 seconds.",
  "token": "confirm_<single-use-hex>"
}

استدعِ الأداة مجددًا مع ضبط _confirmation_token على الرمز ← { "allowed": true }. التدفق الكامل: ⁨output-approval⁩.

انظر أيضًا

• استخراج محتوى نصّي
• فحص إمكانية الوصول
• فئات مخاطر ⁨HITL⁩
• كتالوج الأدوات