توقيع ⁨HSM⁩ — مرجع متعمّق

نظرة سريعة

هذه الصفحة هي المرجع المتعمّق لسطح توقيع ⁨HSM⁩ في ⁨NextPDF Enterprise⁩. تغطّي ثلاثة أنواع عامة. يوقّع ⁨NextPDF\Enterprise\Security\Signature\Hsm\Pkcs11Signer⁩ عبر رمز ⁨PKCS#11⁩ مميّز باستخدام امتداد ⁨ext-pkcs11⁩. ويوقّع ⁨NextPDF\Enterprise\Security\Signature\Hsm\OpenSslCliSigner⁩ عبر الملف الثنائي ⁨openssl⁩ في عملية فرعية، وذلك للمفاتيح المدعومة بموفّر أو بمحرّك التي لا يستطيع ⁨ext-openssl⁩ في ⁨PHP⁩ تحميلها. ويكشف ⁨NextPDF\Enterprise\Security\Signature\Hsm\Provider\HsmSignerProviderAdapter⁩ أيّاً من الصنفين الملموسين بوصفه ⁨SignerProviderInterface⁩ موحّداً. في كل مسار يبقى المفتاح الخاص داخل حدود الرمز المميّز؛ إذ يسلّم ⁨NextPDF⁩ البايتات المراد توقيعها ويستقبل التوقيع. ومسار ما بعد الكم (⁨signPqs⁩) هو معاينة: فهو معطّل افتراضياً، ولا يحمل أي ادعاء مطابقة، وليس له مسار تحقّق مدعوم في مدقّقات ⁨PDF⁩ الحالية. لا يحمل ⁨NextPDF⁩ أي شهادة اعتماد ولا يمنح أياً منها؛ فالدعم لا يساوي المطابقة، والمطابقة لا تساوي شهادة الاعتماد.

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

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

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

تقع الأنواع الثلاثة جميعها في ⁨NextPDF\Enterprise\Security\Signature\Hsm⁩؛ ويقع المُحوِّل في مساحة الأسماء الفرعية ⁨Provider⁩ التابعة له. ويُنفّذ كلا الموقِّعَين عقد ⁨NextPDF\Contracts\HsmSignerInterface⁩ في ⁨Core⁩.

الرمز	المعاملات	السلوك الافتراضي	القيمة المُعادة	يرمي أو يفشل بـ	ملاحظات
Pkcs11Signer::__construct()	string $libraryPath, int $slotId, string $pin, string $certLabel, ?string $keyLabel = null, array $chainDer = [], bool $enablePostQuantum = false, ?FipsSignatureEnforcer $fipsEnforcer = null	يفتح مكتبة المورّد، ويسجّل الدخول إلى الفتحة، ويحمّل الشهادة وبيانات خوارزمية المفتاح الوصفية من الرمز المميّز	—	⁨HsmOperationException⁩ عند غياب ⁨ext-pkcs11⁩ أو فشل الوصول إلى الرمز المميّز	يُخبَّأ مقبض وحدة واحد لكل مسار مكتبة في كل عملية تشغيل؛ ورمز ⁨PIN⁩ والأوسمة من نوع ⁨#[SensitiveParameter]⁩
Pkcs11Signer::sign()	string $data, string $algorithm = 'sha256WithRSAEncryption'	يوقّع على الرمز المميّز؛ ويُحوَّل خرج ⁨ECDSA⁩ الخام إلى ⁨DER⁩ بصيغة ⁨ECDSA-Sig-Value⁩	⁨string⁩ بايتات التوقيع الخام	⁨HsmOperationException⁩ (المفتاح غير موجود، فشل الرمز المميّز)؛ ⁨InvalidArgumentException⁩ (خوارزمية غير مُعيَّنة)؛ استثناءات بوابة ⁨FIPS⁩ قبل التوقيع عند توصيل مُنفِّذ	مجموعة خوارزميات مغلقة؛ انظر عقد السلوك
Pkcs11Signer::signPqs()	string $data, Pkcs11PqsAlgorithm $algorithm, string $context = '', bool $randomized = true	مرفوض ما لم يُضبط ⁨$enablePostQuantum⁩؛ ويُرسل آلية ⁨PKCS#11⁩ المؤقّتة لما بعد الكم	⁨string⁩ بايتات التوقيع الخام	⁨HsmOperationException⁩ (معطّل، فشل الرمز المميّز، عدم تطابق طول التوقيع)؛ ⁨InvalidArgumentException⁩ (سياق يتجاوز 255 بايتاً)	معاينة؛ لا ادعاء مطابقة؛ معرّفات الآلية مؤقّتة
Pkcs11Signer::isPostQuantumEnabled()	لا شيء	يبلّغ عن علم الاشتراك في المُنشئ	bool	لا شيء	—
Pkcs11Signer::getCertificateDer()	لا شيء	يعيد شهادة الموقِّع المقروءة من الرمز المميّز	⁨string⁩ (⁨DER⁩)	لا شيء	تُحمَّل مرة واحدة عند الإنشاء
Pkcs11Signer::getCertificateChainDer()	لا شيء	يعيد الشهادات الوسيطة المزوّدة عبر المُنشئ	⁨array<string>⁩ (⁨DER⁩)	لا شيء	يستثني شهادة الموقِّع
OpenSslCliSigner::__construct()	string $keyUri, string $certPath, string $pin, array $extraCertPaths = [], OpenSslCliBackend $backend = OpenSslCliBackend::Auto, string $opensslBinary = 'openssl', int $timeoutSeconds = 30, ?string $modulePath = null, ?string $configPath = null, bool $legacyPinDelivery = false, ?FipsSignatureEnforcer $fipsEnforcer = null	يتحقّق من ⁨proc_open⁩، ويفحص الملف الثنائي وإصداره، ويحلّ الخلفية، ويحمّل الشهادات	—	⁨HsmOperationException⁩ (⁨proc_open⁩ معطّل، ملف وحدة/إعداد/شهادة مفقود، فشل الملف الثنائي، لا خلفية)؛ ⁨InvalidArgumentException⁩ (⁨pin-value⁩ داخل ⁨$keyUri⁩)	يفضّل ⁨OpenSslCliBackend::Auto⁩ موفّر ⁨OpenSSL 3.x⁩، ثم المحرّك
OpenSslCliSigner::sign()	string $data, string $algorithm = 'sha256WithRSAEncryption'	يشغّل ⁨openssl dgst⁩ في عملية فرعية؛ وينتقل رمز ⁨PIN⁩ عبر ملف ⁨pin-source⁩ مؤقّت ⁨0600⁩ افتراضياً	⁨string⁩ بايتات التوقيع الخام	⁨HsmOperationException⁩ (انتهاء مهلة، رفض رمز ⁨PIN⁩، المفتاح غير موجود، فشل تحميل الوحدة، خرج فارغ، فشل ملف رمز ⁨PIN⁩)؛ ⁨InvalidArgumentException⁩ (خوارزمية غير مُعيَّنة)؛ استثناءات بوابة ⁨FIPS⁩ قبل التوقيع	تُقتل العملية الفرعية بعد ⁨$timeoutSeconds⁩؛ ويُحجب ⁨stderr⁩ قبل أن يصل إلى الرسائل
سطح مُوصِّلات OpenSslCliSigner	لا شيء	نتائج إنشاء للقراءة فقط	string / array<string> / OpenSslCliBackend	لا شيء	getCertificateDer, getCertificateChainDer, getPublicKeyAlgorithm, getCertificatePem, getResolvedBackend, getOpensslVersion
HsmSignerProviderAdapter::__construct()	HsmSignerInterface $hsm, string $providerId, SignatureAlgorithm $algorithm = SignatureAlgorithm::Pkcs1v15	يغلّف صنف ⁨HSM⁩ ملموساً بوصفه ⁨SignerProviderInterface⁩	—	لا شيء	أعراف معرّف الموفّر: ⁨pkcs11-{module-id}⁩، ⁨openssl-cli⁩
HsmSignerProviderAdapter::providerId()	لا شيء	يعيد المعرّف المزوّد عبر المُنشئ	non-empty-string	لا شيء	—
HsmSignerProviderAdapter::supportsAlgorithm()	SignatureAlgorithm $algo	يعيّن التعداد إلى اسم بنمط ⁨OpenSSL⁩، ثم يقاطع مجموعة سماح الخلفية	bool	لا شيء	يرفض الخوارزميات ذات التجزئة فقط؛ ومعرّفات ⁨openssl-engine⁩ لا تعلن عن شيء
HsmSignerProviderAdapter::sign()	string $data, ?string $keyVersion = null	يُرسل عبر الموقِّع المُغلَّف بالخوارزمية المُهيّأة	non-empty-string	⁨KeyManagementException⁩ (⁨$keyVersion⁩ غير خالٍ)؛ ⁨SignatureFailedException⁩ (خوارزمية غير قابلة للتعيين، فشل المُشغِّل، توقيع فارغ)	عقد ⁨SPI⁩ يفشل مغلقاً؛ وكل خطأ من المُشغِّل يظهر بنوع

public function __construct(private readonly string $libraryPath, private readonly int $slotId, #[SensitiveParameter] private readonly string $pin, #[SensitiveParameter] private readonly string $certLabel, #[SensitiveParameter] private readonly ?string $keyLabel = null, array $chainDer = [], private readonly bool $enablePostQuantum = false, ?FipsSignatureEnforcer $fipsEnforcer = null)
public function sign(string $data, string $algorithm = 'sha256WithRSAEncryption'): string
public function signPqs(string $data, Pkcs11PqsAlgorithm $algorithm, string $context = '', bool $randomized = true): string
public function isPostQuantumEnabled(): bool
public function getCertificateDer(): string
public function getCertificateChainDer(): array

public function __construct(private string $keyUri, string $certPath, #[SensitiveParameter] private string $pin, array $extraCertPaths = [], private OpenSslCliBackend $backend = OpenSslCliBackend::Auto, private string $opensslBinary = 'openssl', private int $timeoutSeconds = 30, private ?string $modulePath = null, private ?string $configPath = null, private bool $legacyPinDelivery = false, private ?FipsSignatureEnforcer $fipsEnforcer = null)
public function sign(string $data, string $algorithm = 'sha256WithRSAEncryption'): string
public function getCertificateDer(): string
public function getCertificateChainDer(): array
public function getPublicKeyAlgorithm(): string
public function getCertificatePem(): string
public function getResolvedBackend(): OpenSslCliBackend
public function getOpensslVersion(): string

public function __construct(private HsmSignerInterface $hsm, private string $providerId, private SignatureAlgorithm $algorithm = SignatureAlgorithm::Pkcs1v15)
public function providerId(): string
public function supportsAlgorithm(SignatureAlgorithm $algo): bool
public function sign(string $data, ?string $keyVersion = null): string

عقد السلوك

• عهدة المفاتيح. لا يغادر المفتاح الخاص حدود الرمز المميّز أبداً. يفوّض ⁨Pkcs11Signer⁩ العملية إلى الرمز المميّز؛ بينما يمرّر ⁨OpenSslCliSigner⁩ مرجعاً للمفتاح — وهو ⁨URI⁩ من نوع ⁨PKCS#11⁩ — إلى العملية الفرعية ⁨openssl⁩. ولا يستطيع أيٌّ من الموقِّعَين تصدير المفتاح.
• الجلسة وتسجيل الدخول. يخبّئ ⁨Pkcs11Signer⁩ مقبضاً واحداً لوحدة ⁨PKCS#11⁩ لكل مسار مكتبة في كل عملية تشغيل، لأن واجهة الرمز المميّز يجب تهيئتها مرة واحدة بالضبط في كل عملية تشغيل. وتفتح كل عملية جلسةً وتسجّل الدخول برمز ⁨PIN⁩؛ ويصادق تسجيل الدخول على المستخدم قبل أي استخدام للمفتاح الخاص (⁨PKCS#11 v3.1 §5.6.8⁩). وعندما تبلّغ الفتحة عن وجود تسجيل دخول قائم، يسجّل الموقِّع الخروج ثم يعيد تسجيل الدخول، بحيث تحصل الرموز المميّزة التي تطلب رمز ⁨PIN⁩ جديداً لكل عملية عليه.
• مجموعة الخوارزميات (مغلقة). يقبل كلا الموقِّعَين حصراً: ⁨sha256WithRSAEncryption⁩ و⁨sha384WithRSAEncryption⁩ و⁨sha512WithRSAEncryption⁩؛ ⁨RSASSA-PSS⁩ و⁨RSASSA-PSS-SHA256⁩ و⁨RSASSA-PSS-SHA384⁩ و⁨RSASSA-PSS-SHA512⁩؛ ⁨ecdsa-with-SHA256⁩ و⁨ecdsa-with-SHA384⁩ و⁨ecdsa-with-SHA512⁩. ويقبل ⁨Pkcs11Signer⁩ إضافةً ⁨ecdsa-raw⁩. وأي معرّف آخر يرمي ⁨InvalidArgumentException⁩ — إذ لا يُوقَّع أبداً بأي خوارزمية بديلة.
• ربط ملح PSS. في كل صيغة من ⁨PSS⁩ يساوي طولُ الملح طولَ الملخّص — 32 أو 48 أو 64 بايتاً — وتطابق معاملات التجزئة و⁨MGF⁩ الملخّصَ المختار. يتّبع ذلك بنية معامِلات آلية ⁨PSS⁩، حيث يكون طول الملح عادةً هو طول تجزئة الرسالة (⁨PKCS#11 v3.1 §6.1.9⁩). ويطبّق كلا الموقِّعَين الاقتران نفسه، بحيث يكون أي إعداد صالح على خلفية واحدة صالحاً على الأخرى.
• تحويل ECDSA. يُعيد الرمز المميّز توقيع ⁨ECDSA⁩ بوصفه تسلسلاً خاماً مبطّناً بالأصفار لـ⁨r⁩ و⁨s⁩ (⁨PKCS#11 v3.1 §6.3.1⁩). ويحوّل ⁨Pkcs11Signer::sign()⁩ ذلك الخرج إلى صيغة ⁨ECDSA-Sig-Value⁩ المُرمَّزة بـ⁨DER⁩ التي تتوقّعها مدقّقات ⁨PDF⁩ و⁨OpenSSL⁩. ولا يتعامل المُستدعي أبداً مع الصيغة الخام.
• تسليم رمز PIN (مسار CLI). في الوضع الافتراضي الآمن، يُكتب رمز ⁨PIN⁩ إلى ملف مؤقّت يُنشأ حصراً بأذونات للمالك فقط، ويُشار إليه عبر السمة ⁨pin-source⁩ في ⁨URI⁩ الخاص بـ⁨PKCS#11⁩، ويُحذف بعد خروج العملية الفرعية. ولا يوضع رمز ⁨PIN⁩ في سطر الأوامر ولا يُصدَّر إلى بيئة العملية الفرعية في هذا الوضع. ومع ⁨$legacyPinDelivery = true⁩، يُضمَّن رمز ⁨PIN⁩ بوصفه ⁨pin-value⁩ في ⁨URI⁩، وهو ما يمكن ملاحظته في سطر أوامر العملية؛ وهذا الوضع اختياري بالاشتراك فقط.
• انضباط العملية الفرعية. يُطلق ⁨OpenSslCliSigner⁩ الملف الثنائي بمصفوفة وسائط — دون أي استيفاء صَدَفة — ويفرض ⁨$timeoutSeconds⁩، ويقتل العملية الفرعية عند انتهاء المهلة، ويصنّف ⁨stderr⁩ إلى أخطاء ذات أنواع. وتُحجب الأسرار من ⁨stderr⁩ قبل اقتباسه في رسالة استثناء.
• دلالات المُحوِّل. لا يملك رمز ⁨HSM⁩ المميّز أي مفهوم لإصدار مفتاح مُدار؛ فالمفتاح على الرمز المميّز هو الإصدار. ولذلك يرفض ⁨HsmSignerProviderAdapter::sign()⁩ أي ⁨$keyVersion⁩ غير خالٍ مع ⁨KeyManagementException⁩ بدلاً من تجاهله. ويقاطع ⁨supportsAlgorithm()⁩ تعيينَ التعداد مع المجموعة المقبولة للخلفية المُغلَّفة، بحيث لا يعلن المُحوِّل أبداً عن آلية سترفضها الخلفية عند وقت التوقيع. ويرمي التوقيعُ الفارغ من المُشغِّل ⁨SignatureFailedException⁩.
• معاينة ما بعد الكم. إن ⁨signPqs()⁩ محكوم خلف علم المُنشئ ⁨$enablePostQuantum⁩ ويرفض العمل بغير ذلك. وسلسلة السياق محدودة بـ255 بايتاً، بما يطابق حدّ سياق ⁨ML-DSA⁩ (⁨FIPS 204⁩). ويجب أن يطابق التوقيع المُعاد طولَ البايتات الدقيق لمجموعة معامِلات ⁨Pkcs11PqsAlgorithm⁩ المختارة، وإلا فشل الاستدعاء. وتتبع معرّفات الآلية امتداداً مؤقّتاً لما بعد الكم في ⁨PKCS#11⁩، وهي ليست نهائية. ولا تعترف ملامح ⁨PAdES⁩ بمجموعات ما بعد الكم، وترفض معظم مدقّقات ⁨PDF⁩ مثل هذه التواقيع، ولا يوفّر ⁨NextPDF⁩ أي مسار تحقّق لها. ولا يُدّعى أي مطابقة.

الحالات الحدّية وأنماط الأعطال

• إنشاء ⁨Pkcs11Signer⁩ دون ⁨ext-pkcs11⁩ يرمي ⁨HsmOperationException⁩ فوراً؛ فالامتداد ليس مضمَّناً في توزيعات ⁨PHP⁩ القياسية.
• أي وسم لشهادة أو لمفتاح خاص لا يطابق أي كائن على الرمز المميّز يرمي ⁨HsmOperationException⁩ مسمّياً صنف الكائن المفقود. وقد يختلف وسم المفتاح اختلافاً مشروعاً عن وسم الشهادة على بعض الرموز المميّزة.
• قد تؤدّي محاولات تسجيل الدخول الفاشلة المتكرّرة إلى قفل رمز ⁨PIN⁩ عند الرمز المميّز؛ والرمز المميّز هو من يفرض تلك السياسة، لا ⁨NextPDF⁩. وتحصل الرموز المميّزة التي تتطلّب مفاتيحها المصادقة عند كل استخدام على تسجيل دخول جديد عبر مسار تسجيل الخروج وإعادة المحاولة (⁨PKCS#11 v3.1⁩، دلالات المصادقة الدائمة).
• يرفض ⁨OpenSslCliSigner⁩ أي ⁨$keyUri⁩ يحتوي أصلاً على ⁨pin-value⁩ عند الإنشاء، بفشلٍ مغلق، لأن ذلك التسليم سيتجاوز مسار رمز ⁨PIN⁩ الآمن.
• على ⁨Windows⁩، يفشل وضع ملف رمز ⁨PIN⁩ الآمن فشلاً مغلقاً مع ⁨HsmOperationException⁩: إذ لا تستطيع بتات أذونات الملف تقييد منح القراءة عبر ⁨ACL⁩ هناك، فيرفض الموقِّع ترك رمز ⁨PIN⁩ بنصّ صريح على ⁨ACL⁩ الخاص بالدليل المؤقّت. وتسليم رمز ⁨PIN⁩ القديم هو البديل الموثَّق والاختياري بالاشتراك لمضيفات ⁨Windows⁩ الموثوقة.
• يتطلّب الاكتشاف التلقائي للخلفية ⁨OpenSSL 3.x⁩ لمسار الموفّر؛ ولا يُحلّ ⁨LibreSSL⁩ أبداً إلى الموفّر. وعندما لا ينجح فحص موفّر ولا محرّك، يفشل الإنشاء مع ⁨HsmOperationException⁩ بدلاً من تأجيل الفشل إلى وقت التوقيع.
• أي عملية فرعية تتجاوز ⁨$timeoutSeconds⁩ تُنهى ويُبلَّغ عنها بوصفها انتهاء مهلة؛ وأي عملية فرعية تخرج بسلاسة بخرج فارغ يُبلَّغ عنها بوصفها عطل توقيع فارغ. ولا يمكن لأيٍّ من الحالتين إنتاج مستند موقَّع جزئياً.
• يُرفض أي توقيع لما بعد الكم لا يطابق طولُ بايتاته مجموعةَ المعامِلات المختارة قبل أن يصل إلى ترميز ⁨CMS⁩.
• لا يعلن ⁨HsmSignerProviderAdapter⁩ المزوّد بمعرّف الموفّر المتقاعد ⁨openssl-engine⁩ عن أي خوارزميات، بحيث يفشل الإعداد القديم عند اختيار الموفّر بدلاً من وقت التوقيع.

سلوك وضع ⁨FIPS⁩

يقبل كلا الموقِّعَين ⁨FipsSignatureEnforcer⁩ اختيارياً. وعند توصيل واحد، يكون وضع ⁨FIPS⁩ نشطاً لذلك الموقِّع: إذ يرفض ⁨sign()⁩ خوارزمية توقيع غير مسموح بها أو مفتاحاً دون الحد الأدنى قبل حدوث أي توقيع على الرمز المميّز أو في عملية فرعية. وتتّبع الحدود الدنيا جدولَ توليد التواقيع — إذ لا يُسمح بمقاييس ⁨RSA⁩ دون 2048 بت ولا برُتب ⁨ECDSA⁩ دون 224 بت (⁨NIST SP 800-131A Rev.2 §3 Table 2⁩). ومن دون مُنفِّذ، يبقى السلوك دون تغيير. وتغطّي البوابة مسار ⁨sign()⁩ الكلاسيكي فقط؛ أما ⁨signPqs()⁩ فيحكمه علم المعاينة الخاص به. وهذه ادعاءات قدرة بشأن شِفرة ⁨NextPDF⁩: فتحقّق ⁨FIPS 140-3⁩ يرتبط بوحدة تشفير عبر ⁨CMVP⁩، وهي في هذا النشر ⁨HSM⁩ الخاص بالمشغّل أو موفّره — ⁨NextPDF⁩ ليس وحدة مُتحقَّقاً منها، ولا يحمل أي شهادة اعتماد، ولا يمنح أياً منها.

المطابقة

الادعاء	المعيار	البند
يصادق تسجيل الدخول على المستخدم لدى الرمز المميّز قبل عمليات المفتاح الخاص؛ ورمز ⁨PIN⁩ الخاطئ يمنع الوصول.	PKCS#11 v3.1	§5.6.8
مفاتيح المصادقة الدائمة تحتاج تسجيل دخول جديداً لكل استخدام؛ وقد تؤدّي إعادة المصادقة الفاشلة المتكرّرة إلى قفل رمز ⁨PIN⁩.	PKCS#11 v3.1	CKA_ALWAYS_AUTHENTICATE re-authentication
توقيع ⁨ECDSA⁩ من الرمز المميّز هو تسلسل ⁨r‖s⁩ الخام؛ ويحوّله الموقِّع إلى ⁨DER⁩ من أجل قابلية التشغيل البيني مع ⁨PDF⁩.	PKCS#11 v3.1	§6.3.1
معامِلات ⁨PSS⁩ تربط التجزئة و⁨MGF⁩ وطول الملح؛ ويضبط الموقِّعان الملح مساوياً لطول الملخّص.	PKCS#11 v3.1	§6.1.9
تمنع بوابة ⁨FIPS⁩ توليد التواقيع بـ⁨RSA⁩ دون 2048 بت أو رتبة ⁨ECDSA⁩ دون 224 بت.	NIST SP 800-131A Rev.2	§3 Table 2
سلسلة سياق ما بعد الكم محدودة بـ255 بايتاً.	FIPS 204	HashML-DSA context handling
تحقّق ⁨FIPS 140-3⁩ يرتبط بوحدات التشفير عبر ⁨CMVP⁩.	FIPS 140-3	CMVP program scope

جميع البنود مُعاد صياغتها؛ ولا يُستنسخ أي نص معياري. لا يقدّم ⁨NextPDF⁩ أي ادعاء اعتماد. ويوائم الموقِّعان سلوكهما مع البنود المُستشهد بها بوصفه قدرة. وما إذا كان توقيع مُنتَج يتحقّق هو قرار المُتحقِّق مقابل مراسي الثقة لديه؛ وأمان المفتاح يعتمد على الرمز المميّز و⁨HSM⁩ والمشغّل — لا على ⁨NextPDF⁩ وحده.

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

• تتّبع آلية تسليم رمز ⁨PIN⁩ عُرف ⁨pin-source⁩ في ⁨URI⁩ الخاص بـ⁨PKCS#11⁩ (⁨RFC 7512⁩)؛ وذلك الـ⁨RFC⁩ خارج المجموعة المُستشهد بها، لذا فإن السلوك أعلاه مؤسَّس من مصدر المنتج، لا من استشهاد بمواصفة.

• تأكّد من أن بيئة التشغيل تحمّل ⁨ext-pkcs11⁩ قبل إنشاء ⁨Pkcs11Signer⁩؛ فالإنشاء يفشل سريعاً عند غياب الامتداد. ويحتاج موقِّع ⁨CLI⁩ إلى تمكين ⁨proc_open⁩ وإلى ملف ⁨openssl⁩ ثنائي مثبَّت به موفّر أو محرّك ⁨PKCS#11⁩.

• إن رمز ⁨PIN⁩ ووسم الشهادة ووسم المفتاح من نوع ⁨#[SensitiveParameter]⁩، لذا تُستبعد من تتبّعات المكدّس. وفّر رمز ⁨PIN⁩ من مدير أسرار؛ ولا تكتبه أبداً في الشِفرة المصدرية، أو في إعداد مُودَع في التحكّم بالإصدارات، أو في السجلّات.

• الإنشاء هو الخطوة الباهظة في كلا الموقِّعَين: إذ يسجّل مسار ⁨PKCS#11⁩ الدخول ويقرأ الشهادة، ويفحص مسار ⁨CLI⁩ الملف الثنائي والخلفية. أنشئ مرة واحدة وأعد استخدام النسخة؛ فتخبئة الوحدة لكل مكتبة تجعل الإنشاء المتكرّر مقابل المكتبة نفسها آمناً.

• غلّف موقِّعاً في ⁨HsmSignerProviderAdapter⁩ عندما يعمل المُستدعي عبر ⁨SignerProviderInterface⁩. ومرّر معرّف الموفّر القياسي للصنف المُغلَّف — ⁨pkcs11-{module-id}⁩ أو ⁨openssl-cli⁩ — لكي تستخدم فحوص القدرة مجموعةَ السماح الصحيحة للخلفية.

• قبل تمكين معاينة ما بعد الكم، تحقّق من معرّفات آلية البرنامج الثابت للرمز المميّز مقابل القيم المؤقّتة التي يسجّلها ⁨NextPDF⁩؛ فأي عدم تطابق يفشل عند وقت التوقيع. ولا تمكّن المعاينة لخرج ⁨PAdES⁩ الإنتاجي.

• توجد ⁨getResolvedBackend()⁩ و⁨getOpensslVersion()⁩ لتسجيل الأدلّة؛ فاحفظهما مع أدلّة التوقيع عندما يتطلّب برنامج الامتثال لديك قابلية إعادة الإنتاج.

اطّلع أيضاً

• توقيع وحدة أمان العتاد (⁨PKCS#11⁩) — صفحة الإمكانية مع خطوات الإعداد والتهيئة والتحقّق.
• الأمان — مرجع متعمّق — سطح أمان ⁨Enterprise⁩ المُجمَّع.
• التوقيع — مرجع متعمّق — مُنتِج ⁨PAdES B-LT / B-LTA⁩ طويل الأمد.
• ⁨FIPS 140⁩ — مرجع متعمّق — سياسة التشفير، وحزمة الاختبارات الذاتية، وبوابة ⁨FipsSignatureEnforcer⁩.
• معاينة ⁨PQC⁩ — مرجع متعمّق — سطح معاينة ما بعد الكم وحدوده.
• الأمان / التوقيع (⁨Core⁩) — موقِّع ⁨CMS⁩ في ⁨Core⁩ وعقود التوقيع.

حدود النشر

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