Enterprise الإصدارالاستقرار: تجريبي

حالة قدرة معاينة التوقيع ما بعد الكمّي عبر HSM (PQS)

لمحة سريعة

حالة قدرة معاينة. اختيارية، مُعطَّلة افتراضيًا، بإغلاق آمن. هذه معاينة للتوقيع ما بعد الكمّي المُفوَّض إلى ⁨HSM⁩. وهي ليست متوفّرة عامًا، وليست متوافقة مع ⁨AdES⁩، وليست مُتحقَّقًا منها وفق ⁨FIPS⁩، ولا تقدّم أي ادّعاء اعتماد أو مطابقة. والمعاينة مُعطَّلة حتى تنضمّ؛ وعند الإيقاف، يُغلَق استدعاء التوقيع بأمان مع استثناء مُحدَّد النوع.

يكشف ⁨NextPDF Enterprise⁩ عن سطح توقيع ما بعد كمّي (⁨PQS⁩) تجريبي يُحرِّك توقيع ⁨ML-DSA⁩ (⁨FIPS 204⁩) و⁨SLH-DSA⁩ (⁨FIPS 205⁩) عبر رمز ⁨PKCS#11⁩ عتادي. والمسار هو Pkcs11Signer::signPqs()، مُبوَّبًا خلف انضمام صريح لكل موقِّع ($enablePostQuantum)، وبصورة منفصلة خلف عَلَم بيئة على مستوى العملية (NEXTPDF_FEATURE_PREVIEW_PQS_HSM). وكلاهما مُعطَّل افتراضيًا.

هذه الصفحة هي الحدّ الصادق. تذكر ما تفعله المعاينة — فهي تُفوِّض عملية توقيع ما بعد كمّي حقيقية إلى الرمز — وبالصدق نفسه، ما هي ليست عليه: ليست متوفّرة عامًا، ولا ⁨AdES⁩، ولا مُتحقَّقًا منها وفق ⁨FIPS⁩، ولا ادّعاء مطابقة مقابل ⁨FIPS⁩ أو ⁨OASIS⁩ أو ⁨ETSI⁩. والمعايير التي ستجعل توقيع ⁨PDF⁩ ما بعد كمّي قابلًا للتشغيل البيني للأرشفة طويلة الأمد لم تستقرّ بعد (راجع حدّ المعايير).

الإصدار والترخيص

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

ويبني على موقِّع الرمز العتادي ⁨PKCS#11⁩ في ⁨Enterprise⁩ — راجع توقيع HSM. ومسار توقيع ⁨PKCS#11⁩ الكلاسيكي (⁨RSA⁩ / ⁨ECDSA⁩) هو قدرة ⁨Enterprise⁩ المستقرّة المدعومة؛ أما مسار ما بعد الكمّي الموصوف هنا فمعاينة تجريبية مُرَكَّبة فوقه. ويتضمّن ⁨NextPDF Enterprise⁩ مجموعة ميزات ⁨Pro⁩.

حالة قدرة المعاينة

تُحرِّك المعاينة عملية توقيع حقيقية: عند التفعيل، يُرسِل signPqs() إلى آلية ⁨PKCS#11 v3.1⁩ ما بعد الكمّية المُرشَّحة على الرمز، ولا يغادر المفتاح الخاص حدّ الرمز قطّ، وتُفحَص البايتات المُعادة طوليًا مقابل طول التوقيع المُلزَم بـ ⁨FIPS⁩ لمجموعة المعاملات المختارة قبل قبولها.

وهي، في الوقت نفسه، معاينة وليست قدرة منتَج متوفّرة عامًا:

آلية ⁨PKCS#11⁩ ما بعد الكمّية ومعرّفات مجموعة المعاملات مؤقّتة — لم تُنهِ ⁨OASIS PKCS#11 v3.1⁩ سجلّ آلية ما بعد كمّية، فالقيم المستخدمة مُتتبَّعة كمؤقّتة وعلى مُشغِّلي ⁨HSM⁩ تأكيد أن بُرمجة ما بعد الكمّية في رمزهم تطابقها قبل التفعيل.
لا يوجد مسار تحقّق ما بعد كمّي في ⁨NextPDF⁩، ولا تُسجِّل أي مجموعة ⁨ETSI⁩ توقيعًا ما بعد كمّي لأرشفة ⁨AdES⁩ طويلة الأمد، فأي توقيع يُنتَج هنا ليس قابلًا للتشغيل البيني بعد وستَرفضه معظم عارضات ⁨PDF⁩ عند وقت التحقّق.
يُبلِغ واصف مرافق، PqsCapabilityStatus، عن هذه الحقائق في صورة قابلة للقراءة آليًا. وكل قيمة منطقية إيجابية للادّعاء — generallyAvailable وadesCompliant وverificationAvailable وconformanceClaimed — مُرمَّزة بصلابة على false وتبقى false حتى عند تفعيل عَلَم المعاينة، ولا يمكن لأي تهيئة أن تقلب واحدةً منها. (ويحمل أيضًا عَلَم recognitionOnly، مُرمَّزًا بصلابة على true، يُسجِّل أن تمييز الخوارزمية ليس أبدًا حُكم مطابقة؛ ولا يعني أن السطح لا يمكنه التوقيع — فالتوقيع يجري عبر signPqs() كما هو موصوف أعلاه.)

لماذا يعمل بهذه الطريقة

يستطيع ⁨NextPDF⁩ بالفعل حساب توقيع ⁨ML-DSA⁩ أو ⁨SLH-DSA⁩ حقيقي عبر الرمز. ومع ذلك، تبقى كل قيمة منطقية للمطابقة مُرمَّزة بصلابة على false، خلف بوّابتين مُعطَّلتين افتراضيًا. فالتوقيع لا يساوي إلا القدرة على التحقّق منه لاحقًا. وبالنسبة لما بعد الكمّي لا يوجد مسار تحقّق، ولا مجموعة ⁨AdES⁩ مُسجَّلة لدى ⁨ETSI⁩، ولا جولة ⁨HSM⁩ مُتحقَّق منها وفق ⁨FIPS⁩ بعد. وشحن هذا كقدرة متوفّرة عامًا سيُصدِر توقيعات لا يمكن لأي عارض التحقّق منها ولا لأي أرشيف الوثوق بها. لذا يفصل التصميم إنتاج البايتات عن الادّعاء بأن لأحدٍ أن يعتمد عليها، ولا يمكن لأي عَلَم معاينة أن يُموِّه ذلك الخطّ.

خلفية التصميم: التحقّق طويل الأمد.

مجموعات معاملات الخوارزمية

ينتقي signPqs() الخوارزمية ومجموعة المعاملات عبر التعداد Pkcs11PqsAlgorithm. وتعيّن كل حالة مجموعة معاملات ⁨NIST⁩ إلى معرّف آلية/مجموعة معاملات ⁨PKCS#11⁩ مؤقّت وإلى طول بايتات التوقيع المُلزَم بـ ⁨FIPS⁩ المستخدم لفحص الطول دفاعًا في العمق.

⁨ML-DSA⁩ — ⁨FIPS 204⁩ (شبكي-وحدوي). ثلاث مجموعات معاملات، مُدَّعاة عند فئات قوّة أمان ⁨NIST⁩ المعروضة:

مجموعة المعاملات	فئة NIST	طول التوقيع (بايت)
`ML-DSA-44`	2	2420
`ML-DSA-65` (الافتراضي الموصى به)	3	3309
`ML-DSA-87`	5	4627

⁨SLH-DSA⁩ — ⁨FIPS 205⁩ (قائم على التجزئة عديم الحالة). اثنتا عشرة مجموعة معاملات، مُكوَّنة كـ SHA2 / SHAKE x 128 / 192 / 256 x صغير (s) / سريع (f). تُصغِّر متغيّرات s حجم التوقيع؛ وتُصغِّر متغيّرات f زمن التوقيع:

عائلة مجموعة المعاملات	فئة NIST	طول التوقيع (بايت)
`SLH-DSA-{SHA2,SHAKE}-128s`	1	7856
`SLH-DSA-{SHA2,SHAKE}-128f`	1	17088
`SLH-DSA-{SHA2,SHAKE}-192s`	3	16224
`SLH-DSA-{SHA2,SHAKE}-192f`	3	35664
`SLH-DSA-{SHA2,SHAKE}-256s`	5	29792
`SLH-DSA-{SHA2,SHAKE}-256f`	5	49856

تفعيل المعاينة

يجب أن تكون بوّابتان مستقلّتان مفتوحتين معًا. وكلاهما مُعطَّل افتراضيًا.

بوّابة العملية. اضبط NEXTPDF_FEATURE_PREVIEW_PQS_HSM=1 قبل إقلاع العملية (أو عبر putenv() قبل قراءة الحالة). ويُلزَم تطابق صارم مع السلسلة 1؛ وأي قيمة أخرى — بما في ذلك 0 أو true أو yes أو فارغة — تُعامَل على أنها مُعطَّلة.
انضمام لكل موقِّع. مرّر $enablePostQuantum: true إلى مُنشئ Pkcs11Signer.

use NextPDF\Enterprise\Security\Signature\Hsm\Pkcs11Signer;
use NextPDF\Enterprise\Security\Signature\Hsm\Pkcs11PqsAlgorithm;
use NextPDF\Enterprise\Security\Signature\Hsm\PqsCapabilityStatus;
use NextPDF\Enterprise\Security\Signature\Hsm\PqsPreviewFeature;

// 1. Open the process-level preview gate (default-off).
putenv(PqsPreviewFeature::ENV_PREVIEW_PQS_HSM . '=1');

// 2. The capability status is honest even with the gate open:
//    generallyAvailable / adesCompliant / verificationAvailable stay false.
$status = PqsCapabilityStatus::current();

// 3. Construct the PKCS#11 signer with the per-signer opt-in.
$signer = new Pkcs11Signer(
    libraryPath: '/usr/lib/softhsm/libsofthsm2.so',
    slotId: 0,
    pin: '1234',
    certLabel: 'my-pqc-signing-cert',
    enablePostQuantum: true,
);

// 4. Sign with a chosen parameter set. The returned bytes are length-checked
//    against Pkcs11PqsAlgorithm::signatureLength() before being accepted.
$signature = $signer->signPqs(
    data: $tbsBytes,
    algorithm: Pkcs11PqsAlgorithm::MlDsa65,
);

يُبلِغ isPostQuantumEnabled() عمّا إذا كان انضمام كل موقِّع قد ضُبِط، و PqsCapabilityStatus::current() يُبلِغ عن الحالة على مستوى العملية بالإضافة إلى القيم المنطقية الصادقة للادّعاء.

حدّ الإغلاق الآمن

السطح مُغلَق بأمان ويُبلِغ عن الإخفاقات عبر استثناءات مُسمّاة ومُحدَّدة النوع بدلًا من ارتداد صامت:

غياب الانضمام. إذا استُدعي signPqs() بينما $enablePostQuantum هو false، فإنه يطرح HsmOperationException. ولا يجري أي توقيع.
السياق أطول من اللازم. أي سلسلة ثمانيات سياق توقيع أطول من 255 بايتًا تطرح InvalidArgumentException (وفق حدّ سياق ⁨FIPS 204⁩ / ⁨FIPS 205⁩) قبل أي استدعاء للرمز.
غياب المفتاح. إذا لم يطابق أي مفتاح خاص التسمية المُهيّأة على الرمز، يطرح signPqs() استثناء HsmOperationException.
عدم تطابق الطول. إذا أعاد الرمز توقيعًا لا يساوي طوله بالبايت الطول المُلزَم بـ ⁨FIPS⁩ لمجموعة المعاملات، يطرح signPqs() HsmOperationException — فأي توقيع مُشوَّه (مبتور أو زائد الحجم) يُرفَض قبل أن يصل إلى ترميز ⁨CMS SignedData⁩.
خطأ الرمز. أي خطأ ⁨PKCS#11⁩ أساسي يُغلَّف في HsmOperationException.

ولا يُغيِّر عَلَم بيئة العملية شيئًا في هذا الحدّ: حتى مع تفعيل العَلَم، تبقى القيم المنطقية للقدرة false ويبقى مسار التوقيع مفحوصًا طوليًا ومُغلَقًا بأمان.

الحدّ الصادق

الادّعاءات التالية لا تُقدَّم لهذا السطح ويجب ألّا تظهر في أي وثائق أو واجهة مستخدم أو تسويق مُشتقّ منه:

“⁨GA⁩” / “⁨generally available⁩”.
“⁨AdES⁩” / “⁨PAdES-compliant⁩” — لا تُسجِّل أي مجموعة ⁨ETSI⁩ توقيعًا ما بعد كمّي للأرشفة طويلة الأمد.
“⁨FIPS-validated⁩” — لم تُؤسَّس أي جولة ⁨HSM⁩ ما بعد كمّية مُتحقَّق منها وفق ⁨FIPS-140-3⁩ لهذا المسار.
“⁨certified⁩” أو “⁨conformant⁩” مقابل ⁨FIPS⁩ أو ⁨OASIS PKCS#11 v3.1⁩ أو ⁨ETSI⁩.
“⁨production-ready⁩”.

ما هو السطح بصدق: معاينة اختيارية مُعطَّلة افتراضيًا بإغلاق آمن للتوقيع ما بعد الكمّي المُفوَّض إلى ⁨HSM⁩ تُحرِّك ⁨ML-DSA⁩ / ⁨SLH-DSA⁩ عبر رمز ⁨PKCS#11⁩ وتفحص النتيجة طوليًا. وما هو ليس عليه: قدرة توقيع متوفّرة عامًا، أو متوافقة مع ⁨AdES⁩، أو مُتحقَّقًا منها وفق ⁨FIPS⁩، أو معتمَدة.

حدّ المعايير

تُديم المعاييرَ المعنيّة هيئاتٌ خارجية، ولا تتّخذ المعاينة أي موقف من المطابقة لأيٍّ منها:

تتبع مجموعات معاملات الخوارزمية وأطوال التوقيع ⁨FIPS 204⁩ (⁨ML-DSA⁩) و⁨FIPS 205⁩ (⁨SLH-DSA⁩).
تتبع معرّفات آلية الرمز ⁨OASIS PKCS#11⁩؛ وسجلّ آلية ما بعد الكمّية في ⁨PKCS#11 v3.1⁩ ليس مُنهًى بعد، فيستخدم ⁨NextPDF⁩ معرّفات مؤقّتة.
وملفات الأرشفة طويلة الأمد لتوقيع ⁨PDF⁩ هي ⁨ETSI EN 319 142-2⁩ (ملفات ⁨PAdES⁩ المُمتدّة، المبنيّة على ⁨CMS⁩ SignerInfo) وكتالوج المجموعات التعموية ⁨ETSI TS 119 312⁩، اللذان يُوصِّفان حاليًا ⁨RSA⁩ و⁨ECDSA⁩ فقط — لا تُسجَّل أي مجموعة ما بعد كمّية لـ ⁨CAdES/PAdES⁩. فأي توقيع ⁨PDF⁩ ما بعد كمّي يُنتَج اليوم ليس بعد متوافقًا مع ⁨AdES⁩ للأرشفة.

ولا يُعاد إنتاج أي نص معياري في هذه الصفحة.

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

المعاينة ليست ضابط أمان. ووجود توقيع ما بعد كمّي يُنتجه هذا المسار لا يُثبِت صلاحية ⁨AdES⁩، ولا يعني مفتاحًا موثوقًا، وليس قابلًا للتحقّق من ⁨NextPDF⁩ (لا يوجد مسار تحقّق ما بعد كمّي). لا تعتمد على هذه المعاينة لضمان التوقيع، ولا تنشرها حيث يُطلَب توقيع متوافق مع ⁨AdES⁩ أو مُتحقَّق منه وفق ⁨FIPS⁩. أبقِ كلتا البوّابتين مُعطَّلتين في الإنتاج حتى تستقرّ المعايير.

سطح الـ ⁨API⁩

الرمز	الدور
`Pkcs11Signer::signPqs()`	توقيع ما بعد كمّي مُفوَّض إلى ⁨HSM⁩، اختياري بإغلاق آمن عبر ⁨PKCS#11⁩. يطرح `HsmOperationException` عند التعطيل، أو غياب المفتاح، أو عدم تطابق طول التوقيع.
`Pkcs11Signer::isPostQuantumEnabled()`	ما إذا كان انضمام كل موقِّع `$enablePostQuantum` قد ضُبِط.
`Pkcs11PqsAlgorithm`	تعداد مجموعات معاملات ⁨ML-DSA⁩ (⁨FIPS 204⁩) و⁨SLH-DSA⁩ (⁨FIPS 205⁩)؛ يعيّن كلًّا منها إلى معرّف آلية مؤقّت وطول التوقيع المُلزَم بـ ⁨FIPS⁩.
`PqsPreviewFeature`	بوّابة بيئة على مستوى العملية مُعطَّلة افتراضيًا (`NEXTPDF_FEATURE_PREVIEW_PQS_HSM`).
`PqsCapabilityStatus`	حالة صادقة قابلة للقراءة آليًا: كل قيمة منطقية إيجابية للادّعاء (متوفّر عام، ⁨AdES⁩، تحقّق، مطابقة) مُرمَّزة بصلابة على `false` بصرف النظر عن عَلَم المعاينة.
`HsmOperationException`	الاستثناء المُحدَّد النوع المطروح في مسارات الإغلاق الآمن.

حدّ النشر

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