معاينة التوقيع ما بعد الكمي — مرجع متعمّق

لمحة سريعة

هذه الصفحة هي المرجع على مستوى العقد لواجهة معاينة التوقيع ما بعد الكمي (⁨PQS⁩) في ⁨NextPDF Enterprise⁩. تغطّي ثلاثة رموز عامة: تعداد مجموعات المعاملات Pkcs11PqsAlgorithm، وبوابة العملية PqsPreviewFeature، وواصف PqsCapabilityStatus. كما توثّق بوابة البيئة NEXTPDF_FEATURE_PREVIEW_PQS_HSM.

الواجهة تجريبية ومُعطَّلة افتراضيًا. تتعرّف على معرِّفات خوارزميات ⁨ML-DSA⁩ (⁨FIPS 204⁩) و⁨SLH-DSA⁩ (⁨FIPS 205⁩) ومجموعات معاملاتها وأطوال توقيعاتها. التعرُّف ليس حُكم تحقُّق. لا يوجد مسار تحقُّق ما بعد كمي. لا يُقدَّم أي ادّعاء مطابقة أو تحقُّق ⁨FIPS⁩ أو ⁨AdES⁩، ولا يمكن لعَلَم المعاينة إنشاء أي منها. نقطة دخول التوقيع المستهلِكة، Pkcs11Signer::signPqs()، موصوفة في صفحة القدرة.

التوفّر والترخيص

تُشحَن هذه القدرة ضمن ⁨NextPDF Enterprise⁩ (nextpdf/enterprise) وتُفعَّل عبر مظروف ترخيص من فئة ⁨Enterprise⁩. النشر بدون ذلك الاستحقاق لا يُحمِّل فئات القدرة. قارن الإصدارات واحصل على ترخيص.

يُفعِّل الترخيص واجهة ⁨PKCS#11⁩ الخاصة بـ⁨Enterprise⁩ ككل. يبقى مسار ما بعد الكمي داخلها معاينةً بغضّ النظر عن فئة الترخيص. لا يزال يلزم اشتراكان اختياريان مستقلان: بوابة العملية الموثَّقة هنا وعَلَم المُنشئ لكل موقِّع على Pkcs11Signer.

واجهة ⁨API⁩ العامة

الرمز	المعاملات	السلوك الافتراضي	القيمة المُعادة	يرمي أو يفشل بـ	ملاحظات
Pkcs11PqsAlgorithm	تعداد مدعوم بسلسلة، 15 حالة	يُسمّي مجموعة معاملات واحدة من ⁨FIPS 204⁩ / ⁨FIPS 205⁩ لكل حالة	حالة تعداد	لا شيء عند الوصول إلى الحالة	قيم الحالات هي أسماء مجموعات المعاملات، مثل ML-DSA-65.
Pkcs11PqsAlgorithm::isMlDsa()	لا شيء	اختبار العائلة	bool	لا يرمي	true للحالات MlDsa44 وMlDsa65 وMlDsa87.
Pkcs11PqsAlgorithm::isSlhDsa()	لا شيء	نفي isMlDsa()	bool	لا يرمي	true لحالات ⁨SLH-DSA⁩ الاثنتي عشرة.
Pkcs11PqsAlgorithm::mechanismId()	لا شيء	يعيّن العائلة إلى معرِّف آلية ⁨PQ⁩ المرشَّح في ⁨PKCS#11 v3.1⁩	int	خطأ Error في ⁨PHP⁩ عندما يفتقر وقت التشغيل إلى ثوابت ⁨PQ⁩ المؤقتة الخاصة بـPkcs11	CKM_ML_DSA أو CKM_SLH_DSA؛ كلا المعرِّفين مؤقّت.
Pkcs11PqsAlgorithm::parameterSetId()	لا شيء	يعيّن الحالة إلى مُميِّز مجموعة معاملات ⁨OASIS⁩	int	خطأ Error في ⁨PHP⁩ عندما يفتقر وقت التشغيل إلى ثوابت ⁨PQ⁩ المؤقتة الخاصة بـPkcs11	قيم CKP_*؛ مؤقّتة.
Pkcs11PqsAlgorithm::signatureLength()	لا شيء	طول التوقيع بالبايت المفروض من ⁨FIPS⁩ للحالة	int (موجب)	لا يرمي	يستهلكه مسار التوقيع لرفض توقيع مُعاد بطول غير متوقَّع.
Pkcs11PqsAlgorithm::nistCategory()	لا شيء	فئة قوة أمان ⁨NIST⁩ المُدّعاة	int	لا يرمي	يُعيد 1 أو 2 أو 3 أو 5.
PqsPreviewFeature	تعداد مدعوم بسلسلة، حالة واحدة	حالة واحدة PREVIEW_PQS_HSM؛ ثابت ENV_PREVIEW_PQS_HSM	حالة تعداد	لا شيء عند الوصول إلى الحالة	بوابة المعاينة على مستوى العملية.
PqsPreviewFeature::isEnabled()	لا شيء	يقرأ getenv() مباشرةً؛ مقارنة صارمة مع السلسلة 1	bool	لا يرمي	المتغيّر الغائب أو أي قيمة أخرى، بما في ذلك 0 وtrue وyes، يُعدّ مُعطَّلًا.
PqsCapabilityStatus::__construct()	تسعة حقول ⁨readonly⁩ مُسمّاة	يبني نسخة واصف عشوائية	PqsCapabilityStatus	لا يرمي	current() هو المُنشئ القياسي.
PqsCapabilityStatus::current()	لا شيء	يبني الواصف للعملية المحيطة	PqsCapabilityStatus	لا يرمي	كل قيمة منطقية للادّعاء ثابتة؛ فقط hsmRoundtripPreviewEnabled يتغيّر مع البوابة.
PqsCapabilityStatus::summary()	لا شيء	نص حالة من سطر واحد	string	لا يرمي	الصياغة لا تحمل أي ادّعاء توفّر أو أرشفة أو تحقُّق.

enum Pkcs11PqsAlgorithm: string

case MlDsa44 = 'ML-DSA-44';
case MlDsa65 = 'ML-DSA-65';
case MlDsa87 = 'ML-DSA-87';

case SlhDsaSha2_128s = 'SLH-DSA-SHA2-128s';
case SlhDsaShake_128s = 'SLH-DSA-SHAKE-128s';
case SlhDsaSha2_128f = 'SLH-DSA-SHA2-128f';
case SlhDsaShake_128f = 'SLH-DSA-SHAKE-128f';

case SlhDsaSha2_192s = 'SLH-DSA-SHA2-192s';
case SlhDsaShake_192s = 'SLH-DSA-SHAKE-192s';
case SlhDsaSha2_192f = 'SLH-DSA-SHA2-192f';
case SlhDsaShake_192f = 'SLH-DSA-SHAKE-192f';

case SlhDsaSha2_256s = 'SLH-DSA-SHA2-256s';
case SlhDsaShake_256s = 'SLH-DSA-SHAKE-256s';
case SlhDsaSha2_256f = 'SLH-DSA-SHA2-256f';
case SlhDsaShake_256f = 'SLH-DSA-SHAKE-256f';

public function isMlDsa(): bool
public function isSlhDsa(): bool
public function mechanismId(): int
public function parameterSetId(): int
public function signatureLength(): int
public function nistCategory(): int

enum PqsPreviewFeature: string

case PREVIEW_PQS_HSM = 'preview_pqs_hsm';

public const string ENV_PREVIEW_PQS_HSM = 'NEXTPDF_FEATURE_PREVIEW_PQS_HSM';

public function isEnabled(): bool

final readonly class PqsCapabilityStatus

public const string MATURITY_PREVIEW_EXPERIMENTAL = 'preview-experimental';
public const string MECHANISM_STATUS_PROVISIONAL = 'provisional';

public function __construct(
    public bool $hsmRoundtripPreviewEnabled,
    public bool $generallyAvailable,
    public bool $adesCompliant,
    public bool $verificationAvailable,
    public bool $conformanceClaimed,
    public bool $recognitionOnly,
    public string $maturity,
    public string $mechanismIdStatus,
    public string $envGate,
)

public static function current(): self
public function summary(): string

عقد السلوك

• كتالوج مجموعات المعاملات. يُعدِّد NextPDF\Enterprise\Security\Signature\Hsm\Pkcs11PqsAlgorithm ثلاث مجموعات ⁨ML-DSA⁩ (⁨FIPS 204⁩) واثنتي عشرة مجموعة ⁨SLH-DSA⁩ (⁨FIPS 205 §11.p12⁩، ⁨Table 2⁩). تعيّن كل حالة إلى معرِّف آلية مؤقّت، ومُميِّز مجموعة معاملات، وطول توقيع بالبايت مفروض من ⁨FIPS⁩، وفئة ⁨NIST⁩ مُدّعاة.
• أطوال التوقيع. يُعيد signatureLength() القيم 2420 و3309 و4627 بايت للحالات MlDsa44 وMlDsa65 وMlDsa87، وفق ⁨FIPS 204 §4.p15⁩ (⁨Table 2⁩). تُعيد حالات ⁨SLH-DSA⁩ القيم 7856 و17088 و16224 و35664 و29792 و49856 بايت حسب المستوى والمتغيِّر، وفق ⁨FIPS 205 §11⁩ (⁨Table 2⁩). يرمي الموقِّع المستهلِك HsmOperationException عندما يكون للتوقيع المُعاد طول مختلف، بما يعكس انضباط رفض الأطوال في ⁨FIPS 204 §x34⁩.
• الفئات. يُعيد nistCategory() القيم 2 و3 و5 لحالات ⁨ML-DSA⁩، وفق ⁨FIPS 204 §4.p9⁩. تُعيد حالات ⁨SLH-DSA⁩ القيم 1 و3 و5 حسب مستوى معامل الأمان.
• بوابة العملية. PqsPreviewFeature::PREVIEW_PQS_HSM مُعطَّلة افتراضيًا. يُعيد isEnabled() القيمة true فقط عندما يساوي متغيّر البيئة NEXTPDF_FEATURE_PREVIEW_PQS_HSM السلسلة 1 تمامًا. القراءة مباشرة عند كل استدعاء؛ لا يُخزَّن شيء في الذاكرة.
• البوابات التكميلية. بوابة العملية منفصلة عن الاشتراك الاختياري في المُنشئ $enablePostQuantum لكل موقِّع على Pkcs11Signer. يفشل استدعاء التوقيع مغلقًا بدون الاشتراك الاختياري لكل موقِّع. توجد بوابة العملية كحدّ واحد قابل للتدقيق لأي سلوك ذهاب وإياب أو أرشفة مستقبلي.
• ثابت الصدق. يضبط NextPDF\Enterprise\Security\Signature\Hsm\PqsCapabilityStatus::current() القيم generallyAvailable وadesCompliant وverificationAvailable وconformanceClaimed على false، وrecognitionOnly على true ضبطًا مثبَّتًا في الشيفرة. لا يوجد إعداد أو خيار مُنشئ أو عَلَم بيئة يقلب أي ادّعاء إلى التفعيل. فقط hsmRoundtripPreviewEnabled يعكس البوابة.
• لا مسار تحقُّق. لا يملك ⁨NextPDF⁩ أي مسار تحقُّق ما بعد كمي. لا يُعدّ معرِّف خوارزمية مُتعرَّف عليه أو طول توقيع صحيح البنية حُكم قبول أبدًا.

الحالات الطرفية وأنماط الفشل

• ضبط متغيّر البوابة على 0 أو true أو yes أو on أو سلسلة فارغة يترك البوابة مُعطَّلة. السلسلة 1 بالضبط وحدها تُفعِّلها.
• تدخل تغييرات putenv() حيّز التنفيذ عند استدعاء isEnabled() التالي لأن القراءة مباشرة. تُلاحَظ فورًا أي بوابة تُبدَّل أثناء العملية.
• يحلّ mechanismId() وparameterSetId() الثوابت من مساحة أسماء امتداد Pkcs11. يفشل وقت التشغيل الذي لا يملك ثوابت امتداد ما بعد الكمي المؤقتة بخطأ Error في ⁨PHP⁩ (ثابت غير معرَّف) وقت الاستدعاء.
• معرِّفات الآلية ومجموعات المعاملات مؤقّتة. لم تُنهِ ⁨OASIS⁩ سجلّ ما بعد الكمي في ⁨PKCS#11 v3.1⁩. سيفشل الرمز المميَّز الذي يخصّص برنامجه الثابت معرِّفات مختلفة عند طبقة ⁨PKCS#11⁩؛ على المشغّلين تأكيد معرِّفات البرنامج الثابت قبل تفعيل المعاينة.
• سياق التوقيع الذي يقبله الموقِّع المستهلِك محدود بـ255 بايت، بما يطابق عقد إدخال التوقيع في ⁨FIPS 204⁩ (⁨§x43.p2⁩). يرمي السياق الأطول InvalidArgumentException قبل أي استدعاء للرمز المميَّز.
• PqsCapabilityStatus::__construct() عام، لذا يمكن لنسخة مبنية يدويًا أن تحمل قيمًا منطقية عشوائية. مثل هذه النسخة ليست سوى كائن قيمة. لا تغيّر أي سلوك توقيع. current() هو المُنشئ القياسي المثبَّت في الشيفرة.
• يتبع اختيار العشوائي مقابل الحتمي على الموقِّع المستهلِك دلالات ⁨FIPS 205 §x65.p7⁩: التوقيع المُحوَّط هو الافتراضي. يُتجاهَل العَلَم لـ⁨ML-DSA⁩، التي تُعشوِن دائمًا عبر ⁨nonce⁩ الخاص بها.

سلوك وضع ⁨FIPS⁩

⁨ML-DSA⁩ و⁨SLH-DSA⁩ خوارزميتان من ⁨FIPS 204⁩ و⁨FIPS 205⁩، لكن هذه المعاينة لا تحمل أي ادّعاء تحقُّق ⁨FIPS 140-3⁩. لم يُثبَت أي ذهاب وإياب ⁨HSM⁩ ما بعد كمي مُتحقَّق منه عبر ⁨FIPS⁩ لهذا المسار. مِلَفّ سياسة التشفير لوضع ⁨FIPS⁩ في ⁨Enterprise⁩، الموثَّق في المرجع المتعمّق للأمان، يبوِّب خوارزميات التوقيع الكلاسيكية؛ ولا يُدخِل واجهة ⁨PQS⁩ ضمن مجموعة مُتحقَّق منها. تفعيل وضع ⁨FIPS⁩ لا يجعل التوقيع ما بعد الكمي مُتحقَّقًا عبر ⁨FIPS⁩. لا تنشر المعاينة حيث يُطلَب توقيع مُتحقَّق منه عبر ⁨FIPS⁩.

المطابقة

الادّعاء	المعيار	البند
⁨ML-DSA-44/65/87⁩ تحمل فئات ⁨NIST⁩ مُدّعاة 2 و3 و5.	FIPS 204	§4.p9
أحجام توقيع ⁨ML-DSA⁩ هي 2420 و3309 و4627 بايت.	FIPS 204	§4.p15 (Table 2)
سلسلة بايتات سياق التوقيع محدودة بـ255 بايت.	FIPS 204	§x43.p2
يجب رفض توقيع أو مفتاح بطول خاطئ.	FIPS 204	§x34
اعتُمدت اثنتا عشرة مجموعة معاملات ⁨SLH-DSA⁩.	FIPS 205	§11.p12 (Table 2)
تتبع أحجام توقيع ⁨SLH-DSA⁩ الجدول ⁨Table 2⁩ (7856 بايت لـ⁨128s⁩).	FIPS 205	§11.p6
التوقيع المُحوَّط هو الافتراضي؛ يوجد متغيِّر حتمي.	FIPS 205	§x65.p7
كتالوج مجموعات ⁨CAdES/PAdES⁩ يصف ⁨RSA⁩ و⁨EC-DSA⁩ فقط.	ETSI TS 119 312 V1.5.1	§7.x7.p10 (Table A.1)
معرِّفات آلية ⁨PQ⁩ في ⁨PKCS#11⁩ مؤقّتة.	OASIS PKCS#11 v3.1	product-source grounded

جميع البنود مُعاد صياغتها. لا يُعيد ⁨NextPDF⁩ إنتاج النص المعياري. لا يملك ⁨NextPDF⁩ أي شهادة ولا يمنح أيًّا. العبارات أعلاه هي عبارات محاذاة بنيوية حول المعرِّفات والأطوال والحدود. إنها ليست نتائج اختبار مطابقة، ولا شهادات طرف ثالث، ولا ادّعاء مطابقة لـ⁨FIPS⁩ أو ⁨OASIS⁩ أو ⁨ETSI⁩. يُرمِّز PqsCapabilityStatus هذا الموقف في الشيفرة: conformanceClaimed هو false، وadesCompliant هو false، وverificationAvailable هو false، في كل إعداد. التوقيع الذي تنتجه هذه المعاينة ليس متوافقًا مع ⁨AdES⁩ للأرشفة طويلة الأمد، ومعظم عارضات ⁨PDF⁩ ترفضه وقت التحقُّق.

ملاحظات التطوير

• سجلّ آليات ما بعد الكمي في ⁨OASIS PKCS#11⁩ غير مُنهَى؛ معرِّفات CKM_ML_DSA / CKM_SLH_DSA وثوابت مجموعات المعاملات المستخدَمة هنا مؤقّتة ومُستندة إلى مصدر المنتج، وليست استشهادًا بمواصفة.

• المرحلة الحالية هي جاهزية مُختبَرة بمحاكاة. لم يُتحقَّق بعد من أي ذهاب وإياب ⁨HSM⁩ ببرنامج ثابت ما بعد كمي حقيقي.

• أبقِ كلتا البوابتين مُعطَّلتين في الإنتاج. لا تضيف المعاينة أي قدرة إنتاجية يفتقر إليها مسار ⁨PKCS#11⁩ الكلاسيكي القائم على ⁨RSA/ECDSA⁩.

• قبل أي تقييم بأجهزة حقيقية، أكِّد معرِّفات الآلية ومجموعات المعاملات لبرنامج الرمز المميَّز الثابت مقابل القيم المؤقتة. يفشل عدم التطابق عند طبقة ⁨PKCS#11⁩، لا داخل ⁨NextPDF⁩.

• عامِل PqsCapabilityStatus::current() كمصدر الحقيقة الوحيد عند إظهار حالة ⁨PQS⁩ في الأدوات أو واجهة المستخدم. لا تُعِد ذكر قيمها المنطقية يدويًا.

• مخرجات summary() آمنة للسجلّات ونقاط نهاية الحالة؛ صيغتها لا تحمل أي ادّعاء توفّر أو تحقُّق.

اطّلع أيضًا

• معاينة توقيع ⁨HSM⁩ ما بعد الكمي (PQS) — صفحة القدرة
• الأمان — مرجع متعمّق (⁨HSM⁩، ⁨PKCS#11⁩، وضع ⁨FIPS⁩)
• التوقيع — مرجع متعمّق
• إعداد توقيع ⁨HSM⁩
• الأمان / التوقيع (⁨Core⁩)

حدود النشر

توثّق هذه الصفحة السلوك القابل للملاحظة خارجيًا وواجهة ⁨API⁩ العامة المدعومة فقط. مسارات مساحات الأسماء الداخلية، وفئات المساعدة، وجداول الآليات، وأسماء ملفات كتيّبات التشغيل، وبادئات التذاكر خارج النطاق.