استكشاف أخطاء التشفير وأعلام الأذونات وإصلاحها

النطاق والحدود

استخدم هذه المداخل لاستكشاف إخفاقات فك التشفير التي يطلقها المحرك عبر NextPDF\Exception\EncryptionException وNextPDF\Security\Exception\DecryptionFailedException، ولفهم حدود أعلام أذونات تنسيق ⁨PDF⁩.

ابدأ بالحدود لأنها تمنع أكثر المفاهيم الخاطئة شيوعًا: تسجّل أعلام أذونات ⁨PDF⁩ نية المؤلف في قاموس التشفير. ولا تُعدّ آلية تحكم في الوصول تفرضها هذه المكتبة. فبإمكان قارئ يتجاهل هذه الأعلام أن يطبع المحتوى أو ينسخه أو يعدّله رغم ذلك. تعامل مع الأعلام بوصفها طلبًا موجَّهًا إلى قارئ متعاون، لا بوصفها آلية إلزامية.

المُدخل: إخفاق عملية التشفير

• العَرَض. EncryptionException مع رسالة على الصيغة Encryption operation "<op>" failed using algorithm "<algorithm>".
• السبب المحتمل. تعذّر تنفيذ عملية التشفير، عادةً لأن امتداد ⁨OpenSSL⁩ مفقود أو غير مُهيّأ على نحو صحيح، أو لأن مادة المفتاح غير صالحة، أو لأن حجم متجه التهيئة (⁨IV⁩) غير صالح عند حدود التشفير.
• الدليل / التشخيص. يُرجع getContext() القيمتين algorithm وoperation. وتكون قيمة operation واحدة من encrypt أو decrypt أو key_derivation، بحيث يمكنك تحديد المرحلة التي أخفقت.
• الحل.
  1. تأكد من أن امتداد ⁨OpenSSL⁩ في ⁨PHP⁩ مثبَّت ومُحمَّل.
  2. استخدم الحقل operation لتحديد المرحلة التي أخفقت.
  3. في حالة key_derivation، تحقق من مدخلات كلمة المرور أو المفتاح.
  4. أعد تنفيذ الاستدعاء.
• ذو صلة. مرجع الاستثناءات.

المُدخل: إخفاق فك التشفير لسبب بنيوي

• العَرَض. DecryptionFailedException مع رسالة على الصيغة Decryption failed for "<algorithm>": <reason>.
• السبب المحتمل. تعذّرت معالجة النص المُشفَّر لسبب لا يتعلق بالعبث، مثل اقتطاع النص المُشفَّر، أو غياب متجه التهيئة (⁨IV⁩)، أو تمرير مفتاح خاطئ عند حدود واجهة برمجة التطبيقات (⁨API⁩). لم يُنفَّذ فحص السلامة لعدم توفر مادة كافية للتقييم.
• الدليل / التشخيص. يُرجع getContext() القيمتين algorithm وreason. يميّز توثيق المصدر DecryptionFailedException عن TamperedDataException: يعني هذا الاستثناء خطأ في التهيئة أو النقل، لا عبثًا. لا تعامله بوصفه حادثًا أمنيًا في حد ذاته.
• الحل.
  1. اقرأ reason لتحديد الخلل البنيوي، على سبيل المثال ciphertext shorter than IV+tag.
  2. تحقق من أن النص المُشفَّر نُقل دون اقتطاع.
  3. تأكد من أن المفتاح المُمرَّر عند الحدود هو المفتاح المستخدَم لتشفير المستند.
  4. أعد تنفيذ الاستدعاء.
• ذو صلة. إخفاقات التوقيع والطابع الزمني.

المُدخل: إطلاق استثناء “بيانات تم العبث بها”

• العَرَض. تتلقّى NextPDF\Security\Exception\TamperedDataException بدلًا من DecryptionFailedException.
• السبب المحتمل. جرى فحص السلامة لكنه أخفق. يختلف هذا عن إخفاق فك التشفير البنيوي: كانت هناك مادة كافية لتقييم السلامة، لكن التحقق من السلامة لم ينجح.
• الدليل / التشخيص. يميّز المصدر بين الصنفين: DecryptionFailedException بنيوي وليس حادثًا أمنيًا؛ بينما يشير TamperedDataException إلى فشل التحقق من المحتوى المُوثَّق.
• الحل.
  1. تعامل مع المدخل بوصفه غير موثوق؛ لا تستهلك المحتوى المُفكَّك تشفيره.
  2. أعد جلب المستند من مصدر موثوق.
  3. إذا استمر الإخفاق مع مصدر معروف بسلامته، فاستخرج getContext() لإعداد تقرير حادث.
• ذو صلة. إخفاقات التوقيع والطابع الزمني.

المُدخل: أعلام الأذونات لا تمنع إجراءً لاحقًا

• العَرَض. أُنتِج مستند بأعلام أذونات مضبوطة — على سبيل المثال، النسخ أو الطباعة غير مسموح بهما — ومع ذلك لا يزال قارئ ما ينسخ المحتوى أو يطبعه.
• السبب المحتمل. هذا حد متوقع، وليس عيبًا. قيمة الأذونات العددية المُمرَّرة إلى باني قاموس التشفير في ⁨Core⁩ لا تفرضها هذه المكتبة. الأعلام بيانات وصفية إرشادية؛ والقارئ الذي لا يحترمها لا يحجبه ⁨NextPDF.⁩
• الدليل / التشخيص. يُصرّح src/Security/Encryption/EncryptionDictionaryBuilder.php بالدالة buildDict(int $permissions, string $fileId)، ويوثّق المعامِل بأنه ignored; retained for forward compatibility. تبدأ الدالة بـ unset($permissions, $fileId). أعلام الأذونات التي يكشفها src/Inspect/PdfPermissions.php هي حقول فحص للقراءة فقط، وليست طبقة فرض.
• الحل.
  1. لا تعتمد على أعلام الأذونات لإيقاف الطباعة أو النسخ أو التعديل. إذ لا تستطيع مكتبة تُنتج المستندات فرضها.
  2. عندما يلزم تقييد الوصول، تحكّم في توزيع الملف نفسه، أو طبّق نظام تحكم في الوصول خارج ⁨PDF.⁩
  3. استخدم PdfPermissions للإبلاغ فقط عن الأعلام التي يصرّح بها مستند قائم، لا لتأكيد أن تلك الإجراءات ممنوعة.
• ذو صلة. إخفاقات التوقيع والطابع الزمني.

المُدخل: رفض التشفير في إطار ⁨PDF/A⁩

• العَرَض. NextPDF\Security\Exception\IncompatiblePdfAModeException عندما يُفعِّل بناءٌ ما ⁨PDF/A⁩ ويطلب التشفير.
• السبب المحتمل. يحظر ملف تعريف ⁨PDF/A⁩ مفتاح Encrypt في المُذيَّل. يرفض المحرك هذا المزيج أيًا كان ترتيب الاستدعاءين.
• الدليل / التشخيص. راجع مُدخل ⁨PDF/A⁩ و⁨PDF/UA⁩ للاطلاع على البند المُستشهَد به، وحقول getContext()، واختبار مسار الإخفاق.
• الحل.
  1. قرّر ما إذا كان المستند يحتاج إلى مطابقة متطلبات الأرشفة أو إلى التشفير.
  2. أزل الاستدعاء الخاص بالخاصية التي لا تحتاج إليها.
  3. أعد تشغيل خط المعالجة.
• ذو صلة. التحقق من ⁨PDF/A⁩ و⁨PDF/UA⁩.

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

• DecryptionFailedException وTamperedDataException يعنيان أمرين مختلفين: إخفاق بنيوي مقابل إخفاق في السلامة. تفرّع بناءً على الصنف، لا على الرسالة.
• يتجاهل باني قاموس التشفير في ⁨Core⁩ قيمة الأذونات العددية؛ وأي بناء يعتمد على فرض الأذونات من حزمة ⁨Core⁩ مبنيٌّ على مفهوم خاطئ.
• لا تُملأ بيانات PdfPermissions إلا للمستندات المشفَّرة عند عمق الفحص الكامل، وتعكس الأعلام المُصرَّح بها. ووجود حقل مملوء لا يعني أن الإجراء ممنوع.

انظر أيضًا

• مرجع الاستثناءات
• إخفاقات التوقيع والطابع الزمني
• التحقق من ⁨PDF/A⁩ و⁨PDF/UA⁩
• فهرس قاعدة المعرفة

المسرد: أعلام الأذونات · فك التشفير المُوثَّق