أخطاء الأمان والتوقيع

لمحة سريعة

توثّق هذه الصفحة استثناءات مجال الأمان في شجرة فضاء الأسماء NextPDF\Security. ويذكر كل مدخل الفئة، ويبيّن متى تُطلَق، ويسرد الحقول التي يُرجعها getContext() الخاص بها، ويقدّم خطوة تعافٍ.

تمدّد معظم هذه الفئات SecurityException، التي تمدّد NextPdfException وتطبّق ContextAwareExceptionInterface. وهذا يعني أن getContext(): array يُرجع تشخيصات مُنظَّمة وخالية من الأسرار يمكنك توجيهها إلى خطوط أنابيب التسجيل أو مراقبة أداء التطبيق (⁨APM⁩). اعترض SecurityException لاقتناص كل إخفاق في مجال الأمان في كتلة واحدة؛ واعترض فئة فرعية محددة عندما تحتاج إلى حمولتها ذات النوع.

تمدّد بضع فئات في هذه الشجرة RuntimeException مباشرةً بدلًا من SecurityException. وهذه مُعلَّمة أدناه؛ فهي لا تكشف getContext()، ومعظمها مُوثَّق بوصفه إشارات تحكّم داخلية في التدفّق لا ينبغي أن تتوقّع اعتراضها في شفرة التطبيق.

اصطلاح حقل السياق

الجانب	السلوك
العقد الأساسي	يُرجع NextPdfException::getContext() القيمة []؛ وتتجاوزه الفئات الفرعية.
سلامة الأسرار	تُغفِل الرسائل والسياق مادة المفتاح الخام، والنص الصريح، وأرقام التعريف الشخصية (PINs)، وبايتات متجه التهيئة (IV). وتُظهَر المفاتيح فقط بوصفها سابقة بصمة.
SecurityException	أساس مُجرَّد؛ لا يحمل حقولًا خاصة به. وتُعرِّف الفئات الفرعية الحمولة.

النوع الأساسي

SecurityException

• متى يُطلَق. لا يُطلَق مباشرةً أبدًا؛ فهو الأساس المُجرَّد لمجال الأمان. وهو موجود حتى تستطيع كتلة catch (SecurityException $e) واحدة اقتناص إخفاقات سلامة التشفير المُصادَق عليه، ودفاعات إعادة استخدام الرقم المُستخدَم لمرة، وربط ⁨PDF/A⁩ بالتشفير، وأعطال إدارة المفاتيح، وإخفاقات ⁨PKI⁩.
• حقول السياق. لا حقول خاصة به. يرث الافتراضي الفارغ من NextPdfException؛ وتملأ الفئات الفرعية الحمولة.
• التعافي. اعترض الفئة الفرعية الفعلية للمعالجة القابلة للتنفيذ، أو SecurityException لتوجيه حوادث الأمن توجيهًا خشنًا.

أخطاء التشفير والتشفير المُصادَق عليه

تُطلق هذه أداة التشفير ⁨AES-GCM⁩ (وضع جالوا/العدّاد) وحارس ⁨PDF/A⁩. للإرشاد المُنطلِق من العَرَض، انظر التشفير والأذونات.

DecryptionFailedException

• متى يُطلَق. يُخفق فكّ تشفير مُصادَق عليه مع بيانات مرتبطة (⁨AEAD⁩) لسبب غير العبث: نصّ مُشفَّر مُقتطَع، أو متجه تهيئة مفقود، أو مفتاح خاطئ مُمرَّر عند حدّ واجهة ⁨API⁩، حيث لم تكن هناك مادة كافية لتشغيل فحص السلامة فعلًا. هذا خطأ إعداد أو نقل، لا حادث أمني.
• حقول السياق. algorithm (على سبيل المثال AES-256-GCM)، وreason (على سبيل المثال ciphertext shorter than IV+tag).
• التعافي. تحقّق من أن النصّ المُشفَّر ومتجه التهيئة والمفتاح كاملة ومُؤطَّرة بصورة صحيحة؛ ولا تعامل هذا بوصفه عبثًا. قابِله بـTamperedDataException.

TamperedDataException

• متى يُطلَق. يُخفق التحقق من وسم مصادقة ⁨AEAD⁩. يغطي الوسم النصّ المُشفَّر إضافةً إلى البيانات المُصادَق عليها المرتبطة (⁨AAD⁩)؛ فإذا عُدِّل أيٌّ منهما بعد التشفير، يُرجع openssl_decrypt() الأساسي القيمة false. ويتيح لك هذا النوع الفرعي المتميّز إظهار إنذار بدرجة حادث أمني بدلًا من خطأ تأطير.
• حقول السياق. algorithm، وciphertext_length (طول النصّ المُشفَّر المرفوض، باستثناء متجه التهيئة والوسم).
• التعافي. عامِله بوصفه عبثًا أو مفتاحًا/متجه تهيئة خاطئًا. لا تُعِد المحاولة عمياء؛ حقّق في مصدر النصّ المُشفَّر. وفق ⁨ISO/TS 32003:2023 §5.2⁩ و⁨NIST SP 800-38D §6.5⁩، يعني فشل فحص الوسم أن البيانات غير أصيلة.

NonceReuseException

• متى يُطلَق. يُطلَب من ⁨AES-GCM⁩ التشفير مرتين بزوج المفتاح ومتجه التهيئة نفسه. تدافع أداة التشفير بعدّاد رتيب لكل نسخة، وكدفاع في العمق، بمجموعة تجزئة في وقت التشغيل لكل زوج (بصمة مفتاح، متجه تهيئة) صادر. ولأن العدّاد يستبعد التصادمات ببنائه، فهذا الإطلاق مؤشر عيب حرج الأولوية يجب ألا يقع أبدًا في الإنتاج. تُشكِّل إعادة استخدام زوج مفتاح/متجه تهيئة خطر تدفّق المفاتيح كاملًا (⁨ISO/TS 32003:2023 §5.2 NOTE 2⁩؛ ⁨NIST SP 800-38D §8.3⁩).
• حقول السياق. key_fingerprint_prefix (أول 8 محارف سداسية عشرية من ⁨SHA-256(key)⁩)، وiv_length (دائمًا 12 لـ⁨ISO/TS 32003⁩)، وreason (hashset-collision أو counter-rollover، يميّز عيب إعادة هيكلة يُبطل العدّاد عن سلك التعثّر للعدّاد عند ⁨2^63⁩)، وiv_fixed_field_hex (الحقل الثابت لمتجه التهيئة، موجود فقط عند توفيره، مُبلَّغ تحت مفتاحه الخاص ولا يُوسَم خطأً بوصفه بصمة المفتاح أبدًا).
• التعافي. أجهِض فورًا ودوِّر المفتاح. أعِدّ تقرير عيب؛ فهذا يُشير إلى عيب في أداة التشفير، لا إلى مُدخَل مُستدعٍ سيئ.

GcmInvocationLimitExceededException

• متى يُطلَق. يُبلَغ عدّ استدعاءات اختياري لسلامة الاستعمال وفق ⁨NIST SP 800-38D §8.3⁩ لمفتاح ⁨AES-GCM⁩ مُعطى. وهذا خطّاف قياس عن بُعد للدفاع في العمق للمُستدعين الذين يريدون فرض الحدّ الموصى به في المواصفة (نحو ⁨2^32⁩ استدعاء لكل مفتاح) قبل الحدود البنيوية داخل أداة التشفير. وهو لا يُطلَق افتراضيًا؛ فمساعِد assertWithinSafetyBound() وحده هو الذي يُطلقه.
• حقول السياق. key_fingerprint_prefix، وinvocation_count (عدّ encrypt() الحالي، عند الحدّ أو فوقه)، وinvocation_limit (الحدّ الاختياري).
• التعافي. دوِّر مفتاح المستند (أنشئ أداة تشفير جديدة بمادة مفتاح جديدة) قبل أن يتوقّف احتمال التصادم والتزوير التراكمي عن كونه مُهمَلًا، أو وسّع سياسة المُستدعي لرفض استمرار الخدمة.

IncompatiblePdfAModeException

• متى يُطلَق. تُحاوَل عملية تشفير على مستند مُوسَّم بـ⁨PDF/A⁩. تمنع عائلة ⁨PDF/A⁩ (⁨PDF/A-2⁩ و⁨PDF/A-3⁩ و⁨PDF/A-4⁩) التشفير منعًا موحَّدًا: وفق ⁨ISO 19005 §6.1.3⁩ يجب ألا يكون المفتاح Encrypt موجودًا في المُذيَّل، وترث ⁨ISO 19005-4:2020⁩ في المُلحَقين ⁨A⁩ و⁨B⁩ هذا دون تعديل. ولا توجد تركيبة مسموح بها من ⁨PDF/A⁩ والتشفير.
• حقول السياق. pdfa_mode (على سبيل المثال pdfa4، pdfa3)، وencryption_operation (الاستدعاء المرفوض، على سبيل المثال useAesGcm).
• التعافي. لإنتاج مستند مُشفَّر، احذف استدعاء enablePdfA()؛ ولإنتاج مستند أرشيفي، احذف استدعاء التشفير. انظر التحقق من ⁨PDF⁩/A و ⁨PDF⁩/UA.

إنفاذ سياسة التشفير

CryptoPolicyViolationException

• متى يُطلَق. ترفض سياسة تشفير مُهيّأة خوارزميةً أو قوة مفتاح أو شيفرة اختارتها عملية توقيع أو تشفير أو تجزئة في النواة. وهو حدّ الإخفاق الآمن لإنفاذ المطابقة (على سبيل المثال ⁨FIPS 140-2/3⁩، أو ⁨eIDAS⁩، أو سياسة مؤسسية مخصّصة) ويُطلقه CryptoPolicyEnforcer قبل إنتاج أي توقيع أو نصّ مُشفَّر، حتى لا تستطيع عملية مُنتهِكة للسياسة إصدار مُنتَج غير مُعتمَد أبدًا. متميّز عن إخفاق عملية ⁨OpenSSL⁩ ضيّق وعن إخفاق أداة التوقيع الأولية: فهذا رفض سياسي لطلب صحيح بخلاف ذلك. مُتوائم مع ⁨NIST SP 800-131A Rev. 2⁩ و⁨ISO/IEC 19790:2025 §7⁩.
• حقول السياق. policy (اسم السياسة، على سبيل المثال FIPS 140-3 Strict)، وcategory (hash أو signature أو encryption أو key-strength)، وitem (العنصر المرفوض، على سبيل المثال مُعرِّف كائن (OID)، أو اسم شيفرة، أو rsa/1024)، وreason.
• التعافي. اختر خوارزميةً أو طول مفتاح أو شيفرة تعتمدها السياسة المسماة، أو عدّل السياسة إن كنت تملكها. وجّه السياق المُنظَّم إلى دليل تشغيل المطابقة المُوثَّق.

إدارة المفاتيح

توجد فئتان متطابقتا الاسم. وتتشاركان جذر SecurityException فتقتنصهما كتلة catch (SecurityException $e) واحدة، لكنهما تحملان حمولتين متمايزتين. استورد بالاسم المؤهَّل بالكامل عندما تحتاج إلى شكل محدد.

KeyManagementException (دورة الحياة: NextPDF\Security\Exception)

• متى يُطلَق. تُخفق عملية إدارة مفاتيح قبل استهلاك المفتاح من قِبَل أداة توقيع أو تشفير أولية: إخفاقات تحليل مفتاح البريد مُعزَّز الخصوصية (⁨PEM⁩)، أو ⁨PKCS#12⁩، أو ⁨PKCS#11⁩؛ أو إخفاقات اشتقاق المفاتيح (⁨HKDF⁩، ⁨PBKDF2⁩، ⁨scrypt⁩)؛ أو رفض تغليف مفتاح ⁨AES⁩ (⁨RFC 3394⁩) على مفتاح تشفير مفاتيح خاطئ؛ أو وحدة أمان عتادية (⁨HSM⁩) تُرجع قواعد ترميز مميِّز (⁨DER⁩) مُشوَّهة؛ أو عدم تطابق طول بذرة ⁨Ed25519⁩.
• حقول السياق. operation (على سبيل المثال load_pem، kek_derive، key_wrap)، وkey_type (على سبيل المثال RSA، EC-P256، Ed25519، AES-256)، وreason. ولا تُضمَّن مادة المفتاح الخام أبدًا.
• التعافي. افحص العملية المسماة ونوع المفتاح، وأصلِح مادة المفتاح المصدر أو مُدخَل الاشتقاق، ثم أعد المحاولة.

KeyManagementException (مسار التوقيع: NextPDF\Security\Signature\Exception)

• متى يُطلَق. يصطدم مزوّد مُوقِّع بعطل في إدارة المفاتيح: إصدار المفتاح المطلوب غير معروف، أو مُعطَّل، أو مُجدوَل للإتلاف، أو يفتقر إلى إذن التوقيع، أو غير قابل للاستعمال بخلاف ذلك. وهذا ما يُطلقه RsaPssSigner وLocalKeySignerProvider عند إخفاقات المفتاح الحيّ. المُنشئات المسماة: unknownKeyVersion() وkeyVersionDisabled().
• حقول السياق. providerId، وkeyVersion، وreason. المُلتقِطات: providerId() وkeyVersion() وreason().
• التعافي. دوِّر المفتاح أو أعد منحه الأذونات، أو اختر إصدار مفتاح قابلًا للاستعمال، ثم أعد المحاولة. متميّز عن SignatureFailedException الذي يُشير إلى أن أداة التوقيع الأولية نفسها أخفقت.

التوقيع

للإرشاد المُنطلِق من العَرَض حول المستويات غير القابلة للبلوغ والقدرات المفقودة، انظر إخفاقات التوقيع والطابع الزمني.

SignatureFailedException (R4-13: NextPDF\Security\Exception)

• متى يُطلَق. تُخفق عملية توقيع تشفيري: تُرجع أداة توقيع ⁨RSA⁩ أو ⁨ECDSA⁩ أو ⁨Ed25519⁩ أولية القيمة false أو خرجًا بطول خاطئ؛ أو يستجيب رمز ⁨HSM⁩ أو ⁨PKCS#11⁩ مميَّز بحالة غير ناجحة؛ أو يُخفق تجميع SignedData لبنية رسالة التشفير (⁨CMS⁩) على شهادة أو سلسلة مُشوَّهة؛ أو يُخفق تحقق ⁨Ed25519⁩ الذاتي ذهابًا وإيابًا. ينبغي للشفرة الجديدة أن تُفضِّل هذا النوع الفرعي ⁨R4-13⁩ على استثناء التوقيع القديم المقترن بـ⁨PAdES⁩.
• حقول السياق. operation (على سبيل المثال sign، verify، build_cms)، وalgorithm (على سبيل المثال rsa-pkcs1v15-sha256، ed25519)، وreason. المُلتقِطات: getOperation() وgetAlgorithm() وgetReason().
• التعافي. اقرأ العملية والخوارزمية، وصحّح المُدخَل (المفتاح، أو سلسلة الشهادات، أو توفّر الخلفية)، ثم أعد المحاولة. مُتوائم مع وضعية معالجة المفاتيح بالإخفاق الآمن في ⁨ETSI EN 319 142-1⁩.

SignatureFailedException (SPI: NextPDF\Security\Signature\Exception)

• متى يُطلَق. لا يستطيع تنفيذ SignerProviderInterface إتمام عملية توقيع لأي سبب غير مُصنَّف بوصفه إدارة مفاتيح: خطأ مُشغِّل خلفية، أو مادة مفتاح مُشوَّهة، أو إدخال/إخراج ⁨HSM⁩ غير قابل للتعافي. وهذا هو الاقتناص الجامع لعقد التوقيع بالإخفاق الآمن، حيث يُطلق كل أداة أولية عند الإخفاق بدلًا من إرجاع null أو false أو سلسلة فارغة. المُنشئ المسمى: forProvider().
• حقول السياق. providerId، وreason. المُلتقِطات: providerId() وreason().
• التعافي. افحص مُعرِّف المزوّد والسبب، وأصلِح خلفية المزوّد أو مادة المفتاح، ثم أعد المحاولة. تفرّع بين KeyManagementException وهذا النوع لتفصل “المفتاح سيئ” عن “أخفقت الأداة الأولية”.

SignatureLevelUnreachableException

• متى يُطلَق. لا يمكن احترام مستوى مطابقة ⁨PAdES⁩ المطلوب تحت البنية التحتية الحالية لوقت التشغيل (غالبًا هيئة طابع زمني مفقودة لـ⁨B-T⁩ وما فوق) ولم يمنح المُستدعي إذنًا بالتدهور. والافتراضي هو الإخفاق الآمن: يرفض المحرك بدلًا من أن يُنتج بصمت مستوى أدنى مع الإعلان عن المستوى الأعلى، وهو ما كان سيمثّل تراجعًا بدرجة ⁨eIDAS⁩. مُتوائم مع ⁨ETSI EN 319 142-1 §6⁩. لاحظ أن هذه الفئة تمدّد NextPdfException مباشرةً (لا SecurityException).
• حقول السياق. requestedLevel، وhighestAchievableLevel، وreason. المُلتقِطات: requestedLevel() وhighestAchievableLevel() وreason().
• التعافي. اقرأ reason لتحديد البنية التحتية المفقودة ووفّرها (على سبيل المثال اضبط هيئة طابع زمني)، أو مرّر allowDegradation: true إلى PadesOrchestrator لقبول أعلى مستوى قابل للبلوغ عن قصد.

SignerProviderNotFoundException

• متى يُطلَق. يُطلَب من SignerProviderRegistry::get() مُعرِّف مزوّد غير مُسجَّل. يطبّق ⁨PSR⁩-11 NotFoundExceptionInterface، فيتوافق السجلّ مع عقد حاوية ⁨PSR⁩-11. المُنشئ المسمى: forId(). وتمدّد هذه الفئة RuntimeException ولا تكشف getContext().
• حقول السياق. لا شيء. ويظهر المُعرِّف غير المُسجَّل في الرسالة.
• التعافي. سجّل المزوّد تحت المُعرِّف المتوقَّع قبل طلبه، أو صحّح المُعرِّف الذي تُمرِّره إلى السجلّ.

التجزئة (⁨SHAKE256⁩)

تمدّد هذه RuntimeException ولا تكشف getContext(). و⁨SHAKE256⁩ هي دالة الخرج القابلة للتمديد من ⁨SHA-3⁩ التي تتطلبها بعض مسارات ⁨ISO/TS 32001⁩.

Shake256NotAvailableException

• متى يُطلَق. وقت التجزئة، عندما لا يستطيع المزوّد المُختار تلبية الطلب. المُنشئات المسماة: noBackend() (لا توجد خلفية ⁨SHAKE256⁩ عاملة على هذا المضيف، عبر كل المراتب المُجرَّبة) وffiCallFailed() (استدعاء ⁨OpenSSL⁩ ⁨EVP⁩ مربوط بـ⁨FFI⁩ أرجع حالة غير ناجحة، على سبيل المثال من بناء ⁨libcrypto⁩ مُجرَّد).
• حقول السياق. لا شيء. وتذكر الرسالة المراتب المُجرَّبة أو الرمز المُخفِق.
• التعافي. ثبّت ext-ffi مع وجود ⁨OpenSSL 3.x⁩، أو رقِّ إلى بناء ⁨PHP⁩ يكشف shake256 في hash_algos(). ولم يُشحَن احتياط ⁨Keccak⁩ في فضاء المستخدم عن قصد.

Shake256ProviderNotAvailableException

• متى يُطلَق. من مُنشئ مزوّد ⁨SHAKE256⁩ عندما يُخفق مَجَسّ القدرة، فلا يمكن إنشاء المزوّد. وهي إشارة تحكّم في التدفّق: يلتقطها سجلّ المزوّدين، ويُسجِّل وسم المرتبة، ويُجرِّب المرتبة التالية. ولا ينبغي أن تفلت أبدًا إلى شفرة التطبيق. المُنشئ المسمى: forTier().
• حقول السياق. لا شيء. وتذكر الرسالة المرتبة والسبب.
• التعافي. ليست قابلة للتنفيذ من قِبَل المُستدعي مباشرةً؛ فإذا استُنفدت سلسلة المراتب كاملةً، يُظهِر السجلّ بدلًا من ذلك Shake256NotAvailableException::noBackend()، الذي يحمل الإصلاح الموجَّه للمُشغِّل.

سلامة رمز مصادقة رسالة المستند (⁨ISO/TS⁩ 32004)

تغطي هذه رمز مصادقة الرسالة (⁨MAC⁩) على مستوى المستند وفق ⁨ISO/TS 32004⁩، المُخزَّن تحت /AuthCode. وكلاهما يمدّد NextPdfException ويتجاوز getContext().

DocumentMacTokenException

• متى يُطلَق. بإخفاق آمن، من قارئ رمز ⁨MAC⁩، عندما يكون رمز ⁨MAC⁩ لـ⁨CMS⁩ AuthenticatedData مُشوَّهًا بنيويًا أو يُصرّح بخوارزمية خارج المجموعة المُتفَق عليها في ⁨ISO/TS 32004⁩. المُنشئات المسماة: malformed() وalgorithmMismatch(). مُعلَّم بـ@internal.
• حقول السياق. status (قيمة DocumentMacVerificationStatus، إمّا MalformedToken أو AlgorithmMismatch). الخاصية العامة للقراءة فقط: $status.
• التعافي. عامِل المستند بوصفه غير مُتحقَّق منه. يعني الرمز المُشوَّه أو الخوارزمية الخارجة عن المجموعة المُتفَق عليها أن ⁨MAC⁩ لا يستطيع إرساء ثقة؛ لا تمضِ كما لو أن المحتوى محميّ.

DocumentMacVerificationException

• متى يُطلَق. بإخفاق آمن، عندما لا يستطيع التحقق من ⁨MAC⁩ على مستوى المستند بلوغ حالة موثوقة: /AuthCode مفقود أو مُشوَّه، أو خوارزمية خارج المجموعة المُتفَق عليها، أو إخفاق فكّ التغليف، أو عدم تطابق ⁨MAC⁩ (عبث). يُرجع verify() للمُتحقِّق نتيجةً صريحة للتفرّع؛ وهذا هو نظيره في تدفّق الاستثناءات الذي يُطلقه assertVerified() حتى لا تستطيع شفرة “ثِق بالمحتوى” أن تتجاوز مستندًا غير مُتحقَّق منه. المُنشئ المسمى: fromResult().
• حقول السياق. status (قيمة DocumentMacVerificationStatus). الخاصية العامة للقراءة فقط: $status.
• التعافي. لا تثق بمحتوى المستند. افحص status للتمييز بين عبث (عدم تطابق ⁨MAC⁩) ومشكلة إعداد (/AuthCode مفقود أو مُشوَّه، أو عدم تطابق خوارزمية).

التحقق من مسار ⁨PKI⁩ (⁨RFC 5280⁩)

تغطي هذه التحقق من مسار التصديق وفق ⁨RFC 5280⁩. والنوع الأساسي وفئاته الفرعية تُخفق بأمان.

PkiPathValidationException

• متى يُطلَق. إخفاق وضع صارم من مُتحقِّق مسار ⁨RFC 5280⁩. وهو الأساس غير النهائي لفئات فرعية أضيق (ChainLengthExceededException وUnsupportedExtensionException)، فالمُعالِجات التي تعترض هذا النوع تعترض تلك أيضًا عبر استبدال ليسكوف. يمدّد SecurityException.
• حقول السياق. لا يتجاوز getContext() (يرث الافتراضي الفارغ). ويحمل الأسباب المُنظَّمة في خاصية المصفوفة العامة المُجمَّدة للقراءة فقط $reasons (قائمة غير فارغة من سلاسل اسم القاعدة إضافةً إلى الوصف).
• التعافي. اقرأ $reasons لتحديد القاعدة المُخفِقة، وأصلِح سلسلة الشهادات، وأعد التحقق. اعترض هذا النوع لمعالجة أي إخفاق تحقق مسار معالجةً موحَّدة.

ChainLengthExceededException

• متى يُطلَق. يُطلَب من مُتحقِّق المسار السير في سلسلة يتجاوز طولها السقف المُهيّأ. ويُفرَض الحدّ قبل بدء أي تحليل، فلا يستطيع مزوّد خبيث دفع المُتحقِّق إلى عمل تربيعي أو استنزاف الموارد بسلسلة عميقة عشوائيًا. والسقف الافتراضي البالغ 10 يتبع ملف تعريف ⁨PKIX-CMP⁩ (⁨RFC 4210 §5.3.18⁩)؛ وتتسع السلاسل في العالم الواقعي في 5 إلى 6 مداخل. فئة فرعية من PkiPathValidationException.
• حقول السياق. يرث getContext() الفارغ؛ وتُمرَّر سلسلة السبب chain_length_exceeded: supplied=<n> cap=<n> إلى $reasons للأب. الخصائص العامة للقراءة فقط: $supplied، و$cap.
• التعافي. وفّر سلسلة ضمن السقف، أو ارفع الحدّ المُهيّأ إن كانت سلسلة أطول مشروعة متوقَّعة.

UnsupportedExtensionException

• متى يُطلَق. يلاقي مُتحقِّق المسار امتداد ⁨X.509⁩ حرجًا لم يُنفَّذ إنفاذه بعد. وفق ⁨RFC 5280 §4.2⁩، يجب أن يُخفق امتداد حرج غير مُتعرَّف عليه بأمان؛ ويُخفق الوضعان الصارم والمتساهل بأمان هنا، لأن تخطّي امتداد حرج بصمت كان سيمثّل تراجعًا أمنيًا. يغطي المُتحقِّق بناء السلسلة، ومطابقة ⁨AKI/SKI⁩، واستخدام المفتاح، واستخدام المفتاح المُوسَّع، والقيود الأساسية، وانتهاء الصلاحية، والتحقق من التوقيع؛ وأي شيء حرج آخر يُظهَر هنا. فئة فرعية من PkiPathValidationException.
• حقول السياق. يرث getContext() الفارغ؛ وتُمرَّر الأسباب المُنظَّمة إلى $reasons للأب. الخصائص العامة للقراءة فقط: $extensionOid (مُعرِّف كائن منقّط، على سبيل المثال 2.5.29.30 لقيود الأسماء)، و$extensionName، و$clauseRef (مؤشر إلى بند ⁨RFC 5280⁩ ومدخل سجلّ العناصر المؤجَّلة).
• التعافي. في الوضع المتساهل، اعترض هذه الفئة الفرعية تحديدًا للسقوط احتياطيًا إلى سياسة أخشن دون ابتلاع إخفاقات تحقق مسار حقيقية. دقّق $extensionOid و$clauseRef مقابل تثبيتات ⁨PKI⁩ لديك لمعرفة أي امتداد يحجب التحقق.

RevocationCheckFailedException

• متى يُطلَق. تُستنفد نقطتا نهاية ⁨OCSP⁩ وقائمة إبطال الشهادات (⁨CRL⁩) دون حُكم قاطع: إخفاق نقل ⁨OCSP⁩ أو استجابة مُشوَّهة، وإخفاق نقل ⁨CRL⁩ أو ⁨CRL⁩ مُشوَّهة، مع فتح كلا قاطعي الدارة أو فقدان كلا المخزنين. يعامل الوضع الصارم هذا بوصفه إخفاقًا آمنًا؛ ويلتقطه الوضع المتساهل ويُصدر تحذير ⁨PSR⁩-3 مع revocation = null. يمدّد SecurityException.
• حقول السياق. لا يتجاوز getContext() (يرث الافتراضي الفارغ). ويحمل الحالة في الخاصيتين العامتين للقراءة فقط $ocspState و$crlState (وقيمة كلٍّ منهما الافتراضية unknown).
• التعافي. استعِد قابلية الوصول إلى مصدر إلغاء، أو انتظر إغلاق قاطعي الدارة، أو سخّن المخزن، ثم أعد المحاولة. لا تكبت هذا للحصول على مُنتَج تحقق طويل الأمد؛ فتأكيد الإلغاء جزء من ذلك المستوى.

التحقق من توقيع ⁨OCSP⁩ (⁨RFC 6960⁩)

OcspSignatureInvalidException

• متى يُطلَق. يُخفق توقيع ⁨RFC 6960 §4.2.2.2⁩ BasicOCSPResponse في التحقق التشفيري مقابل شهادة المُجيب. يفكّ المُحلِّل ترميز signatureAlgorithm (⁨RSA-PSS⁩ أو ⁨ECDSA⁩ أو ⁨RSA-PKCS1v15⁩) ويتحقق من signature على tbsResponseData؛ وأي إخفاق يُطلق هذا الاستثناء ذا النوع حتى يستطيع المُستدعون التمييز بين استجابة صحيحة بنيويًا لكن مُتلاعَب بها تشفيريًا واستجابة مُشوَّهة الـ⁨DER⁩. غير نهائي، فتستطيع الحزم اللاحقة نشر فئات فرعية أكثر تحديدًا. يمدّد SecurityException.
• حقول السياق. لا يتجاوز getContext() (يرث الافتراضي الفارغ). ويحمل وسم الإخفاق في الخاصية العامة للقراءة فقط $reason (على سبيل المثال signature_mismatch، responder_cert_not_in_bundle، unsupported_signature_algorithm)؛ ويُطوى detail الحرّ في الرسالة.
• التعافي. افحص $reason. بالنسبة إلى responder_cert_not_in_bundle، وفّر حزمة مرساة الثقة الصحيحة وشهادة المُجيب. وبالنسبة إلى signature_mismatch، عامِل الاستجابة بوصفها غير موثوقة. انظر إخفاقات التوقيع والطابع الزمني.

الطوابع الزمنية (⁨RFC 3161⁩)

TsaException

• متى يُطلَق. إخفاق في اتصال هيئة الطابع الزمني (⁨TSA⁩) وفق ⁨RFC 3161⁩ أو في تحليل الاستجابة: تُرجع ⁨TSA⁩ حالة خطأ، أو يُخفق طلب ⁨HTTP⁩، أو لا يمكن تحليل استجابة ⁨ASN.1⁩. وهو أساس هرم أعطال ⁨TSA⁩ وغير نهائي حتى تستطيع إخفاقات التحقق تمديده. يمدّد NextPdfException.
• حقول السياق. لا يتجاوز getContext() (يرث الافتراضي الفارغ).
• التعافي. اعترض TsaException لأي مسار عطل ⁨TSA⁩. تحقّق من قابلية وصول ⁨TSA⁩ ومن أن نقطة النهاية تُرجع استجابة ⁨RFC 3161⁩ سليمة الشكل.

TsaTokenVerificationException

• متى يُطلَق. يُخفق تحقق ⁨CMS⁩ من TimeStampToken لـ⁨RFC 3161⁩ في أيٍّ من خطوات التحقق المُلزَمة: ربط ⁨RFC 5816 §3⁩ ⁨ESSCertIDv2⁩، أو سلامة السمات المُوقَّعة وفق ⁨RFC 5652 §11⁩، أو حداثة producedAt وفق ⁨RFC 3161 §2.4.2⁩، أو توقيع SignerInfo وفق ⁨RFC 5652 §5.4⁩. بإخفاق آمن، مع مُميِّز خطوة ذي نوع حتى تستطيع خطوط أنابيب التدقيق التمييز بين إعادة التشغيل وانحراف الساعة وعدم تطابق الشهادة دون فحص الرسائل. فئة فرعية من TsaException، فتبقى مُعالِجات catch (TsaException) القديمة تُطلَق.
• حقول السياق. step (قيمة Step للخطوة المُخفِقة) وmessage. المُلتقِط: getStep().
• التعافي. قابل للتنفيذ من قِبَل مطوِّر (شهادة ⁨TSA⁩ سيئة الإعداد أو تساهل انحراف) أو من قِبَل الأمن (اشتباه في اعتراض الوسيط أو إعادة تشغيل). اقرأ step لتحديد المرحلة المُخفِقة وأصلِح المُدخَل المُقابِل أو إعداد الثقة.

MalformedDerException

• متى يُطلَق. إشارة داخلية بأن سير ⁨DER⁩ اصطدم بحدّ مُشوَّه أو مُقتطَع، تُطلقها السائرات منخفضة المستوى داخل مُتحقِّق رمز ⁨TSA⁩. وتُلتقَط دائمًا عند حدّ التحقق العام وتُعاد لفّها في TsaTokenVerificationException يحمل مُميِّز الخطوة الصحيح؛ ولا تتسرّب أبدًا إلى شفرة المُستدعي. تمدّد RuntimeException؛ مُعلَّمة بـ@internal.
• حقول السياق. لا شيء.
• التعافي. ليست موجَّهة للمُستدعي. عالِج TsaTokenVerificationException الملفوف بدلًا منها.

فكّ ترميز امتداد الشهادة

تمدّد هذه RuntimeException ولا تكشف getContext(). وكلاهما مُفكِّك ترميز يُخفق بأمان.

NameConstraintsDecodeException

• متى يُطلَق. يلاقي مُفكِّك ترميز قيود الأسماء عنصر GeneralSubtree قابلًا للإنفاذ لا يستطيع فكّ ترميزه بأمانة. يتطلب ⁨RFC 5280 §4.2.1.10⁩ من الطرف المُعتمِد معالجة قيد اسم قابل للإنفاذ أو رفض الشهادة؛ وتحويل الإسقاط الصامت السابق إلى هذا الإخفاق ذي النوع يمنع إخفاقًا منفتحًا كان سيُوسِّع بصمت مجموعة الأسماء المقبولة. والنطاق محصور بأشكال الأسماء القابلة للإنفاذ (directoryName وdNSName وiPAddress وrfc822Name وuniformResourceIdentifier)؛ وتبقى الأشكال غير القابلة للإنفاذ قابلةً للتجاهل ولا تُطلقه أبدًا. المُنشئ المسمى: undecodableEnforceableBase(). مُعلَّم بـ@internal.
• حقول السياق. لا شيء. وتُحمَل سلسلة تفصيل آمنة للسجلّ في الرسالة.
• التعافي. يُظهِر المُنفِّذ سببًا بإخفاق آمن name_constraints: وتُرفض السلسلة. حقّق في ترميز قيود أسماء الشهادة؛ لا تُرخِّ الإنفاذ.

QcStatementsDecodeException

• متى يُطلَق. امتداد qcStatements مُشوَّه بنيويًا: ⁨DER⁩ مُقتطَع، أو وسم خاطئ، أو فيض طول. ومُفكِّك الترميز يُخفق بأمان ويُطلق بدلًا من إرجاع نتيجة جزئية أو استدلالية حين لا يستطيع تحديد ما يقوله الامتداد بيقين. مُعلَّم بـ@api.
• حقول السياق. لا شيء.
• التعافي. اعترضه صراحةً فقط إن كنت تنوي التسامح مع ترميز مُشوَّه؛ وإلّا فعامِل بيانات الشهادة المؤهَّلة بوصفها غير قابلة للتحديد وارفض الشهادة أو أعد إصدارها.

جلسات ⁨PKCS⁩#11

Pkcs11SessionException

• متى يُطلَق. عيب في إدارة جلسة ⁨PKCS#11 v3.1⁩. ويُربط كل مُنشئ مسمى بفئة عيب محددة وبقيمة عودة ⁨PKCS#11⁩ CKR_*، مكشوفًا عبر مُميِّز $kind ذي النوع حتى يتفرّع المُستدعون على سلسلة تعداد ثابتة بدلًا من مطابقة رسائل هشّة. وتشمل المُنشئات: cryptokiNotInitialized()، وuserNotLoggedIn()، وuserAlreadyLoggedIn()، وoperationNotInitialized()، وoperationActive()، وmechanismNotAllowed()، وtokenDisconnected()، وconcurrentSessionLimitExceeded()، وsessionAlreadyClosed()، وstateTransitionInvalid()، وosLockingRequired()، وloginTtlExpired()، وsignOperationTtlExpired(). يمدّد SecurityException.
• حقول السياق. لا يتجاوز getContext() (يرث الافتراضي الفارغ). ويحمل النوع ذا النوع في الخاصية العامة للقراءة فقط $kind، إحدى ثوابت KIND_* (على سبيل المثال KIND_USER_NOT_LOGGED_IN، KIND_TOKEN_DISCONNECTED، KIND_LOGIN_TTL_EXPIRED). وتظهر مُعرِّفات الخانة والجلسة، والآلية، وقيم ⁨TTL⁩ في الرسالة. ولا تُضمَّن أرقام التعريف الشخصية وبايتات الشهادة أبدًا.
• التعافي. بدّل على $kind. بالنسبة إلى user_not_logged_in، سجّل الدخول برقم التعريف الشخصي للمستخدم قبل تهيئة عملية توقيع. وبالنسبة إلى token_disconnected، عامِل كل الجلسات على الخانة بوصفها مهجورة. وبالنسبة إلى أنواع ⁨TTL⁩، أعد المصادقة أو أعد تهيئة العملية. وبالنسبة إلى mechanism_not_allowed، وسّع قائمة سماح الآليات المُهيّأة أو اختر آلية مسموحًا بها.

انظر أيضًا

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