التوقيع المدعوم بوحدة HSM

Spec: ISO 32000-2, §12.8 Spec: FIPS 140-3 Evidence: Standard-backed

لمحة سريعة

تنقل وحدة أمان الأجهزة (HSM) مفتاح التوقيع خارج عمليتك، وتضعه خلف جهاز يوقّع عند الطلب من دون أن يعيد المفتاح أبداً. تشرح هذه الصفحة وصلة PKCS#11 التي يوقّع عبرها NextPDF، وموضع حدّ المفتاح بدقّة، وأيّ أجزاء من النتيجة تقع على عاتق المحرّك لا على عاتق الجهاز أو على عاتقك.

لماذا يهم هذا

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

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

النسخة المختصرة

يعرّف معيار PKCS#11 كائن مفتاح موسوماً بأنه حسّاس وغير قابل للاستخراج. لا يمكن الكشف عن قيمته الخاصة كنص صريح خارج الرمز المميّز (token). Spec: PKCS#11, v3.1 §10.9
يبني NextPDF بنية توقيع PDF وحاوية CMS. يمرّر البايتات المراد توقيعها عبر وصلة PKCS#11 ويستقبل التوقيع عائداً. لا يعبر المفتاح تلك الوصلة أبداً.
الوصلة عقد مستقر. يفي بالعقد نفسه رمز مميّز لبطاقة ذكية، ووحدة ⁨HSM⁩ عبر ⁨USB⁩، ووحدة ⁨HSM⁩ شبكية، وخدمة ⁨KMS⁩ سحابية. لا تتغير شيفرة المحرّك فيما بينها.
⁨NextPDF⁩ برنامج محرّك توقيع. ضمان عتاد الجهاز، وحالة اعتماده، وسياسة رمز ⁨PIN⁩، والنشر ليست أموراً يشهد بها المحرّك. يستخدم الجهاز؛ لكنه لا يضمنه.

كيف يتعامل ⁨NextPDF⁩ مع الأمر

الوصلة، بدقّة

يفصل NextPDF تجميع التوقيع عن حساب قيمة التوقيع. التجميع مهمة المحرّك: وضع حقل التوقيع، وحجز مساحة في الملف، وحساب نطاق البايتات، وبناء CMS SignedData مع سماته الموقَّعة. Spec: ISO 32000-2, §12.8

أمّا حساب قيمة التوقيع فمُفوَّض. يعرّف المحرّك عقد مزوّد توقيع صغيراً: يستقبل تسلسل بايتات مبهماً (عملياً السمات الموقَّعة المرمّزة بترميز DER)، ويعيد بايتات (octets) التوقيع الخام. ذلك العقد هو الوصلة. تبقى معرفة PDF وCMS على جانب واحد، ويبقى المفتاح على الجانب الآخر. قد يحتفظ مزوّد التوقيع بذلك المفتاح داخل العملية لمفتاح برمجي محلي، أو في خدمة KMS سحابية، أو على رمز مميّز أجهزة عبر PKCS#11. شيفرة المحرّك فوق الوصلة متطابقة في كل حالة. لا يختلف إلا المزوّد القابع خلفها.

أين يقع الحدّ فعلاً

PKCS#11 — واجهة OASIS لرمز التشفير المميّز، المعروفة تاريخياً بـ “Cryptoki” — هي واجهة ⁨C⁩ القياسية لرموز الأجهزة المميّزة. يتحدّث مسار الأجهزة في ⁨NextPDF⁩ PKCS#11 (مباشرة، أو عبر جسر سطر أوامر OpenSSL لعمليات نشر المحرّك أو المزوّد عندما يتعذّر على الارتباط داخل العملية تحميل رمز مميّز).

يُنشأ كائن المفتاح على الرمز المميّز بسمتين تعرّفان الحدّ. عندما يُوسَم المفتاح بأنه حسّاس، أو يُوسَم بأنه غير قابل للاستخراج، فإن سمات خاصة معيّنة لا يمكن الكشف عنها كنص صريح خارج الرمز المميّز. Spec: PKCS#11, v3.1 §10.9 عملية التوقيع نفسها استدعاء وحيد للرمز المميّز — C_SignInit ثم C_Sign — ينفّذه الجهاز. Spec: PKCS#11, v3.1 §5.10 النص الصريح الذي يعالجه NextPDF لعملية التوقيع هو البايتات المراد توقيعها. وما يعود هو التوقيع والشهادة. لا يكون المفتاح الخاص على أيّ من المسارين. ذلك هو الحدّ، والرمز المميّز هو الذي يفرضه، لا المكتبة.

Step 1 of 4: ISO 32000-2 §12.8 — signature dictionary, ByteRange, Contents
Step 2 of 4: RFC 5652 CMS SignedData — the signature container
Step 4 of 4: FIPS 140-3 / ISO/IEC 19790 cryptographic module assurance (device-level, deployment-dependent)

أين يرتكز توقيع PDF المدعوم بالأجهزة، بالترتيب: حامل PDF (ISO 32000-2 §12.8)، وحاوية CMS التي يحملها، وواجهة الرمز المميّز التي يوقّع عبرها NextPDF (PKCS#11)، ومعايير ضمان الوحدة التي تصف — لكنها لا تضمن بحدّ ذاتها — الجهاز الكامن خلفه.

رمز ⁨PIN⁩ واحد، إعادة استيثاق واحدة

يتيح PKCS#11 أن يتطلّب المفتاح إعادة استيثاق عند كل استخدام: عندما تكون السمة CKA_ALWAYS_AUTHENTICATE مضبوطة، يجب على المستخدم تقديم رمز PIN من جديد لـكل عملية تشفير، لا مرة واحدة لكل جلسة. Spec: PKCS#11, v3.1 §10.9 مسار PKCS#11 في NextPDF مكتوب لهذا الغرض. رمز ⁨PIN⁩ معامل حسّاس. لا يُسجَّل ولا يُسلسَل. عندما تُبلِغ جلسة عن تسجيل دخول قائم، يعيدها ⁨NextPDF⁩ إلى حالة نظيفة كي يحصل التوقيع التالي على فحص جديد لرمز ⁨PIN⁩. يهم هذا الرموز المميّزة من نمط ⁨PIV⁩ التي تطلب سياستها رمز ⁨PIN⁩ لكل توقيع. إنه سلوك محرّك يحترم سياسة الجهاز؛ ولا يخفّفها.

ماذا تقول الأدلّة

Evidence: Standard-backed خاصية كون المفتاح غير قابل للاستخراج ليست ادّعاءً من NextPDF. إنها جزء من نموذج PKCS#11: كائن مفتاح تكون فيه CKA_SENSITIVE صحيحة أو CKA_EXTRACTABLE خاطئة لا يكشف عن قيمته الخاصة كنص صريح خارج الرمز المميّز. Spec: PKCS#11, v3.1 §10.9 إسهام ⁨NextPDF⁩ هو أنه لا يحتاج تلك القيمة أبداً: فهو يوقّع عبر عملية C_Sign الخاصة بالرمز المميّز بدلاً من طلب مادة المفتاح.

Evidence: Standard-backed يرتكز جانب PDF إلى Spec: ISO 32000-2, §12.8 . ملخّص نطاق البايتات يُحسَب على الملف باستثناء قيمة التوقيع. قيمة التوقيع الموضوعة في مدخل Contents هي كائن CMS SignedData مرمّز بترميز DER لأجل توقيعات المفتاح العام. تنتج وحدة ⁨HSM⁩ بايتات التوقيع الأعمق وحدها. ويبني ⁨NextPDF⁩ كل شيء حولها ويكتبها في البنية التي يعرّفها المعيار.

Evidence: Standard-backed ضمان الجهاز موصوف بواسطة Spec: FIPS 140-3 ومعياره الأساس ISO/IEC 19790، اللذان يعرّفان أربعة مستويات أمان نوعية متصاعدة عبر أحد عشر مجال متطلبات — من مواصفة الخوارزمية إلى دليل العبث المادي. هذه المعايير تصف ما يجب أن تستوفيه الوحدة لتدّعي مستوى. إنها خاصية للجهاز واعتماده، لا لـ⁨NextPDF⁩، و— على حدّ تعبير ISO/IEC 19790 نفسه — المطابقة ليست بحدّ ذاتها كافية لـ ضمان أمان وحدة في نشر معيّن.

مثال عملي

الشكل أدناه توضيحي. يُظهر الوصلة، لا نشراً جاهزاً للنسخ واللصق. الفكرة هي أن المحرّك يتسلّم موقّعاً ولا يرى المفتاح أبداً: فاستدعاء sign() الخاص بالموقّع هو استدعاء داخل الجهاز.

<?php

declare(strict_types=1);

use NextPDF\Contracts\HsmSignerInterface;

/**
 * Sign a PDF where the private key lives on a PKCS#11 token.
 *
 * `$hsm` is a hardware-backed signer. Its sign() delegates to the token;
 * the key never enters this process. Everything that makes the bytes a
 * valid PDF signature — field, byte range, CMS SignedData — is built by
 * the engine around the value the device returns.
 *
 * Token wiring (library path, slot, PIN, key label) is deployment
 * configuration and is intentionally out of scope here: those values are
 * operator-owned secrets, not library inputs to hardcode.
 */
function signWithToken(
    string $pdfPath,
    HsmSignerInterface $hsm,
): string {
    // The engine asks the signer only for: the certificate (to embed in
    // the CMS) and a signature over the bytes it computes. It never asks
    // for, and the contract never exposes, the private key.
    $certificateDer = $hsm->getCertificateDer();
    $chainDer       = $hsm->getCertificateChainDer();

    // Pseudocode for the engine's own assembly step: build the signature
    // dictionary + CMS SignedData, then hand the signed-attributes bytes
    // to $hsm->sign(...) and place the returned octets in /Contents.
    return nextpdf_sign_pdf(
        pdfPath: $pdfPath,
        signer: $hsm,
        certificateDer: $certificateDer,
        chainDer: $chainDer,
    );
}

ملاحظتان صريحتان حول هذا الشكل. ارتباط PKCS#11 داخل العملية امتداد PHP منفصل لا تتضمّنه بنى PHP القياسية. يثبّت نشر الأجهزة هذا الامتداد ويتحقّق منه (أو يستخدم جسر سطر أوامر OpenSSL) كجزء من المنصّة، لا كخطوة لاحقة. ويجب أن تكون الخوارزمية المطلوبة من الجهاز خوارزمية يستطيع المفتاح أداءها فعلاً. يرفض المحرّك مبكراً عندما لا يوجد للخوارزمية المهيّأة تعيين للمزوّد المختار، بدلاً من الفشل في عمق استدعاء الرمز المميّز.

مفهوم خاطئ شائع

“استخدام وحدة HSM يعني أن التوقيع معتمَد وفق FIPS.”

لا. الخلط بين الاثنين هو الفخّ. وحدة HSM هي المكان الذي يعيش فيه المفتاح وتُجرى فيه العملية. اعتماد FIPS 140-3 / ISO/IEC 19790 خاصية قد يحملها الجهاز (أو تهيئة وحدة محدّدة)، ويقرّرها برنامج اعتماد — لا تمنحها مكتبة مستدعية، ولا يؤكّدها NextPDF نيابة عن جهاز. NextPDF متوافق مع التوقيع عبر جهاز PKCS#11 وقد جُرِّب مسار توقيعه مع رموز مميّزة ممثّلة للفئات. وأمّا كون نشر معيّن معتمداً على مستوى وحدة FIPS فيتوقّف كلياً على الأجهزة، وشهادتها، وكيفية تهيئتها وتشغيلها. استخدم الكلمة الدقيقة لما تملكه فعلاً.

الحدود والقيود

تصف هذه الصفحة الوصلة والمعايير التي ترتكز عليها. إنها ليست ضماناً للنشر، ويستحق الخط الفاصل أن يُذكر بوضوح:

مسؤولية المحرّك. بناء حقل التوقيع، وحجز مساحة، وحساب نطاق البايتات، وتجميع CMS SignedData، واستدعاء مزوّد التوقيع، وكتابة توقيع صحيح بنيوياً وفق Spec: ISO 32000-2, §12.8 . مسار الأجهزة في NextPDF مطابق لـ واجهة توقيع PKCS#11 لهذا الغرض.
مسؤولية الجهاز والمشغّل. مقاومة العبث في الأجهزة، وحالة اعتمادها وفق FIPS 140-3 / ISO/IEC 19790، وتوليد المفاتيح وحفظها، وسياسة رمز PIN، وتهيئة الفتحات، والبرنامج الثابت، والأمن المادي. لا يشهد المحرّك بأيّ شيء من ذلك.
“جُرِّب مع” ليس اعتماداً. امتلاك NextPDF مساراً مُتحقَّقاً منه مقابل فئات رموز مميّزة ممثّلة — أشكال البطاقة الذكية، وUSB، والشبكة، وKMS السحابية المبلوغة عبر عقد PKCS#11 نفسه — هو بيان توافق. إنه ليس اعتماداً، ولا عدّاً لوحدات معتمدة، ولا ادّعاءً بخصوص جهازك المحدّد. فئات الأجهزة أدناه أشكال تكامل عبر واجهة قياسية واحدة. عاملها على أنها “مواضع جُرِّبت فيها الوصلة”، لا كضمان لطراز لم تختبره بنفسك أبداً.
التوقيع ما بعد الكمّي تجريبي. حيث يكشف المحرّك التوقيع ما بعد الكمّي عبر رمز مميّز فهو اختياري، ومحوَّط، ومُتحقَّق منه مقابل نماذج وهمية لا مقابل برنامج ثابت لوحدة HSM ما بعد كمّية. كتالوجا حزم التشفير PAdES وAdES لا يعترفان بعدُ بتلك الحزم للأرشفة طويلة الأمد. لا تعامله على أنه جاهز للإنتاج.

HSM-backed signing via PKCS#11 — edition availability
Edition	Availability
Core	ليس في هذا الإصدار. يوفّر ⁨Core⁩ محرّك التوقيع و وصلة مزوّد التوقيع، مع مزوّد مفتاح برمجي محلي.
Pro	إدارة المفاتيح السحابية — التوقيع عبر مفاتيح ⁨KMS⁩ مُدارة — هي قدرة ⁨Pro⁩ موصوفة على مستوى السلوك فقط.
Enterprise	متاحة. توقيع رمز الأجهزة المميّز عبر واجهة PKCS#11 (وجسر سطر أوامر ⁨OpenSSL⁩ لعمليات نشر ⁨engine/provider⁩) هي قدرة ⁨Enterprise.⁩ التوافر بيان قدرة، لا اعتماد لأيّ جهاز أو نشر.

أشكال التكامل عبر واجهة واحدة

هذه أشكال جُرِّبت عليها وصلة PKCS#11. العمود يعني “كيف يبدو التكامل”، لا “قائمة أجهزة مُتحقَّق منها أو معتمدة أو معدودة”.

شكل التكامل	كيف يُبلَغ	حدّ المفتاح	الضمان خاصية لـ
بطاقة ذكية / رمز PIV مميّز	وحدة PKCS#11؛ رمز PIN لكل استخدام شائع	على البطاقة؛ غير قابل للاستخراج	البطاقة ومشغّلها
وحدة HSM عبر USB	وحدة PKCS#11	على الجهاز؛ غير قابل للاستخراج	الجهاز ومشغّله
وحدة HSM شبكية / جهاز	وحدة PKCS#11 إلى جهاز شبكي	على الجهاز؛ غير قابل للاستخراج	الجهاز وتهيئته والمشغّل
خدمة ⁨KMS⁩ سحابية	مزوّد مفاتيح مُدار (⁨Pro⁩)	في الخدمة السحابية؛ لا يُعاد أبداً	المزوّد السحابي وشهاداته
جسر مزوّد OpenSSL	PKCS#11 عبر جسر OpenSSL	على الرمز المميّز؛ غير قابل للاستخراج	الرمز المميّز ومشغّله

الأسئلة الشائعة المصغّرة

هل يدخل المفتاح عملية PHP يوماً؟ لا. بالنسبة إلى مفتاح PKCS#11 غير قابل للاستخراج، لا يمكن الكشف عن القيمة الخاصة كنص صريح خارج الرمز المميّز. يوقّع NextPDF عبر عملية الرمز المميّز ولا يرى إطلاقاً سوى البايتات المراد توقيعها والتوقيع العائد.

هل يختلف التوقيع المدعوم بوحدة HSM داخل ملف PDF؟ لا. بنية التوقيع هي CMS SignedData نفسها في المدخل نفسه Contents وعلى نطاق البايتات نفسه. تغيّر وحدة HSM مكان حدوث التوقيع، لا شكله على القرص.

هل يمكنني ادّعاء امتثال ⁨FIPS⁩ لأنني استخدمت وحدة ⁨HSM⁩ عبر ⁨NextPDF⁩؟ بحذر فقط. لا يؤكّد ⁨NextPDF⁩ شيئاً عن حالة ⁨FIPS⁩ لجهاز. أيّ ادّعاء من هذا القبيل يجب أن يأتي من اعتماد الجهاز نفسه وكيفية نشره، لا من حقيقة أن ⁨NextPDF⁩ استدعاه.

ماذا لو كان ارتباط PKCS#11 داخل العملية غير متاح؟ يُبلِغ المحرّك بأن توقيع الأجهزة غير متاح بدلاً من الرجوع بصمت إلى مفتاح برمجي. يوجد مسار جسر سطر أوامر OpenSSL لعمليات النشر عندما يتعذّر على الارتباط داخل العملية تحميل رمز مميّز.

مستندات ذات صلة

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

مسرد المصطلحات

وحدة ⁨HSM⁩ (وحدة أمان الأجهزة) — جهاز مُحصَّن يحتفظ بالمفاتيح وينفّذ عمليات التشفير بحيث لا تغادره مادة المفتاح أبداً.
PKCS#11 — معيار واجهة OASIS لرمز التشفير المميّز (المعروف تاريخياً بـ “Cryptoki”)؛ واجهة C التي يستخدمها NextPDF للتحدّث مع رموز الأجهزة المميّزة.
مفتاح غير قابل للاستخراج — كائن مفتاح PKCS#11 لا يمكن الكشف عن قيمته الخاصة كنص صريح خارج الرمز المميّز (CKA_SENSITIVE صحيحة أو CKA_EXTRACTABLE خاطئة).
الوصلة — حدّ مزوّد التوقيع في ⁨NextPDF⁩: بايتات مبهمة داخلاً، بايتات توقيع (⁨octets⁩) خارجاً. تقع معرفة ⁨PDF⁩ و⁨CMS⁩ فوقها؛ ويقع المفتاح خلفها.
CMS SignedData — بنية بناء جملة رسائل التشفير (RFC 5652) التي تحمل التوقيع والشهادات داخل ملف PDF.
FIPS 140-3 / ISO/IEC 19790 — معايير أمان وحدة التشفير التي تعرّف أربعة مستويات نوعية؛ خاصية لجهاز واعتماده، لا لمكتبة مستدعية.