المقدمة والتحفيز

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

يُظهر هذا المقال كيفية استخدام GroupDocs.Signature for .NET مع Pkcs11Interop لتوقيع مستندات PDF باستخدام رموز الأجهزة. يجمع هذا النهج بين الراحة والالتزام: تتولى GroupDocs جميع حزم مستوى PDF (حقول التوقيع، حساب الاختصار، التضمين)، بينما تقوم الرّمز بتنفيذ التوقيع التشفيري الفعلي.

⚠️ إشعار تنفيذ مبكر
تم تقديم هذا الحل حاليًا كتنفيذ مبكر لاستخدام مفاتيح التوقيع الرقمي PKCS#11 مع GroupDocs.Signature.
بينما يتيح توقيع المستندات باستخدام رموز الأجهزة، نوصي بشدة بإجراء اختبارات إضافية في بيئتك الخاصة لضمان توافقه مع متطلبات الامتثال والأمان الخاصة بك.
نرحب جدًا بتعليقاتك، ونتائج الاختبار، واقتراحات التحسين.

التحدي: ربط PKCS#11 بتوقيع PDF

دمج رموز PKCS#11 في سير عمل توقيع المستندات يواجه عدة تحديات غير بسيطة:

  1. التعقيد منخفض المستوى – يتطلب API PKCS#11 (Cryptoki) إدارة الفتحات، الجلسات، المقابض، والسمات للعثور على المفتاح الخاص الصحيح.
  2. حزمة مستوى PDF – توقيع PDF أكثر من مجرد توقيع بايتات: يجب على المكتبة حساب اختبارات صحيحة على نطاقات بايت معينة، وتغليف التوقيعات في حاويات CMS/PKCS#7، وإدراج الطوابع الزمنية، وتضمين معلومات التحقق.
  3. اختلافات البائع – قد تتطلب الرموز/الوحدات المختلفة خريطة سمات مخصصة أو وسائط إضافية.
  4. الامتثال والقابلية للتدقيق – تحتاج الأنظمة الإنتاجية إلى معالجة PIN قوية، التحكم في دورة حياة الجلسة، استعادة الأخطاء، وتسجيل الأنشطة.

يعالج هذا المشروع العيني هذه القضايا من خلال دمج واجهة ICustomSignHash في GroupDocs.Signature مع Pkcs11Interop لتفويض التوقيع إلى الرّمز، مع ترك GroupDocs لتعامل مع بنية PDF.

ما يفعله المشروع العيني

  • يوضح توقيع مستندات PDF باستخدام رموز PKCS#11 (مفتاح USB، بطاقة ذكية، HSM).
  • يدعم العودة إلى مخزن شهادات Windows: إذا تم تثبيت شهادة على Windows، يمكن للشفرة استخدامها بدلاً من ذلك.
  • ينفذ توقيع تجزئة مخصص: تقوم GroupDocs بحساب الاختصار؛ الرّمز يوقع التجزئة فقط.
  • يبقي المفتاح الخاص على الجهاز طوال الوقت — لا يُصدَّر أبدًا.
  • ي encapsulates منطق الرّمز (الجلسة، البحث عن المفتاح، التوقيع) في Pkcs11DigitalSigner.cs.
  • يوفر منطق مساعد في Helpers.cs (مثلاً، بحث شهادة في مخزن Windows).
  • التكوين مركّز في Settings.cs.
  • يعمل كتنفيذ مرجعي يمكنك تكييفه مع بيئتك.
ربط PKCS#11 بتوقيع PDF

الإعداد والمتطلبات المسبقة

المتطلبات المسبقة

  • .NET 6.0 أو أعلى (أو .NET Framework 4.6.2)
  • مكتبة PKCS#11 صالحة (DLL) من بائع الرّمز الخاص بك
  • رّمز مادي (مفتاح USB، بطاقة ذكية، أو HSM) يحتوي على شهادة صالحة
  • GroupDocs.Signature for .NET (نسخة تجريبية أو مرخصة)
  • مكتبة Pkcs11Interop

التثبيت

git clone https://github.com/groupdocs-signature/esign-documents-with-pkcs11-using-groupdocs-signature-dotnet.git
cd esign-documents-with-pkcs11-using-groupdocs-signature-dotnet
dotnet restore

افتح الحل في Visual Studio أو بيئة التطوير المفضلة لديك، وتأكد من حل جميع الاعتمادات.

هيكل المستودع التفصيلي

GroupDocs.Signature-for-.NET-PKCS11-Sample/
├── GroupDocs.Signature-for-.NET-PKCS11-Sample.csproj      # ملف المشروع
├── Program.cs                                             # نقطة الدخول وتدفق الاستخدام
├── Settings.cs                                            # تكوين PKCS#11 / الرّمز
├── Helpers.cs                                             # وظائف مساعدة (مخزن Windows، تصفية الشهادات)
├── Pkcs11DigitalSigner.cs                                 # يطبق ICustomSignHash عبر PKCS#11
└── README.md                                              # شرح وتعليمات الاستخدام
  • Program.cs – ينسق عملية التوقيع؛ يُظهر كل من تدفق الرّمز وتدفق شهادة Windows.
  • Settings.cs – يحتوي على ثوابت/نواقل لـ Pkcs11LibraryPath، TokenPin، و CertificateSubject.
  • Helpers.cs – يحتوي على شفرة للعثور على الشهادات في مخزن Windows وفقًا لاسم الموضوع (يُستخدم كخيار احتياطي).
  • Pkcs11DigitalSigner.cs – المنطق الأساسي: تحميل وحدة PKCS#11، فتح الجلسات، تحديد كائن المفتاح الخاص، توقيع الاختصار، وإرجاع X509Certificate2 أو تنفيذ رد الاتصال للتوقيع.
  • README.md – يقدم نظرة عامة، التحديات، وتعليمات الاستخدام (التي يكملها هذا المقال).

شرح الشفرة والمسار التفصيلي

Settings.cs

public static class Settings
{
    public const string Pkcs11LibraryPath = "<PKCS11_LIBRARY_PATH>";
    public const string TokenPin = "<TOKEN_PIN>";
    public const string CertificateSubject = "<CERT_SUBJECT>";
}

يفصل هذا ملف الإعدادات تفاصيل التكوين بحيث يمكن استبدالها بسهولة في بيئة النشر الخاصة بك.

Pkcs11DigitalSigner.cs — التدفق عالي المستوى

public class Pkcs11DigitalSigner : ICustomSignHash
{
    public byte[] SignHash(byte[] hash)
    {
        // يتم استدعاء هذه الطريقة من قبل GroupDocs.Signature عندما تحتاج الرّمز إلى توقيع تجزئة
        using (var pkcs11 = new Pkcs11(Settings.Pkcs11LibraryPath, AppType.SingleThreaded))
        {
            // تحميل الوحدة، فتح جلسة، تسجيل الدخول باستخدام PIN، العثور على المفتاح، وتنفيذ التوقيع
        }
    }

    public X509Certificate2 GetCertificateFromPkcs11()
    {
        // يجلب الشهادة العامة من الرّمز حتى يمكن تكوين خيارات التوقيع
    }
}
  • SignHash هي الطريقة المركزية: تستقبل التجزئة التي حسبتها GroupDocs، ثم تستخدم واجهات PKCS#11 لتوقيعها.
  • GetCertificateFromPkcs11 تستخرج الشهادة (مع المفتاح العام) المخزنة في الرّمز لضمان صحة بيانات التوقيع.

Program.cs — تدفق الاستخدام

class Program
{
    static void Main()
    {
        string inputFile = "sample.pdf";
        string outputFile = "signed.pdf";

        // (1) توقيع PKCS#11
        var tokenSigner = new Pkcs11DigitalSigner();
        var cert = tokenSigner.GetCertificateFromPkcs11();

        using (var signature = new Signature(inputFile))
        {
            var options = new DigitalSignOptions(cert)
            {
                Comments = "Signed with PKCS#11 token",
                SignTime = DateTime.Now,
                CustomSignHash = tokenSigner  // ربط التوقيع القائم على الرّمز
            };
            signature.Sign(outputFile, options);
        }

        // (2) خيار العودة إلى مخزن شهادة Windows (اختياري)
        // var storeCert = Helpers.GetCertificateFromWindowsStore(Settings.CertificateSubject);
        // using (var signature2 = new Signature(inputFile))
        // {
        //     var options2 = new DigitalSignOptions(storeCert) { ... };
        //     signature2.Sign("signed_store.pdf", options2);
        // }
    }
}

نقاط رئيسية:

  • تُعيّن خاصية CustomSignHash في DigitalSignOptions إلى tokenSigner، مما يسمح لـ GroupDocs بتفويض توقيع التجزئة الفعلي إلى الرّمز.
  • يُظهر التدفق الاحتياطي (المعلق) كيفية التحول إلى شهادة مخزن Windows عندما لا يتوافر الرّمز المادي.

حالات الاستخدام والسيناريوهات الواقعية

  • الولايات الهندية ومفاتيح USB الصادرة عن CA
    في الهند، تتطلب العديد من التواقيع الإلكترونية الملزمة قانونيًا شهادات مخزنة في مفاتيح USB صادرة عن هيئات معتمدة. يتيح هذا المثال للتطبيقات (مثل بوابات الوثائق، البوابات) الاندماج مباشرة مع هذه المفاتيح.
  • سير عمل المستندات المؤسسية
    للأنظمة الداخلية مثل إدارة العقود أو إجراءات الموافقة، يضمن التوقيع المادي عدم قدرة المستخدمين غير المصرح لهم على تزوير توقيع المستندات.
  • التوقيع وفقًا للمتطلبات القانونية/الامتثال
    تتطلب الحكومات والقطاعات الخاضعة للتنظيم أن تكون التواقيع صادرة من مفاتيح خاضعة لسيطرة الأجهزة. يساعد هذا التكامل على تلبية متطلبات التدقيق والامتثال الصارمة.

الأخطاء الشائعة واستكشاف المشكلات

  • مسار المكتبة غير صحيح → يجب أن يتطابق مسار DLL الخاص بـ PKCS#11 مع وحدة البائع (مثل softhsm2.dll، cryptoki.dll).
  • قفل أو فشل PIN → قد تؤدي محاولات PIN الخاطئة المتكررة إلى قفل الرّمز؛ راجع سياسات البائع.
  • المفتاح غير موجود → تأكد من صحة اسم موضوع الشهادة المُدخل؛ يجب أن يحتوي الرّمز على شهادة مطابقة للموضوع.
  • السائق أو الطبقة الوسيطة مفقودة → بعض الرموز تتطلب تثبيت سائق البائع قبل أن يتمكن Pkcs11Interop من التواصل.
  • مشكلات الخيوط → قد لا تكون عمليات PKCS#11 آمنة متعددة الخيوط؛ استخدم السياق أحادي الخيط ما لم يدعم البائع تعدد الخيوط.
  • مهلات أو إعادة تعيين الجلسة → قد تتسبب العمليات الطويلة في إغلاق الجلسات أو انتهاء مهلةها؛ احرص على إدارة الجلسات والتنظيف بشكل صحيح.

الأمان وأفضل الممارسات

  • لا تقم أبدًا بترميز الأسرار الإنتاجية (PINs، مسارات المكتبة)؛ استخدم تكوينًا آمنًا أو إدارة أسرار.
  • استخدم PINs قوية وغيّرها وفقًا للسياسة المتاحة.
  • سجّل العمليات والأخطاء (بدون تسجيل PINs الحساسة).
  • حدِّد عدد جلسات الرّمز وسجِّل الخروج فور الانتهاء من التوقيع.
  • تحقق من صحة التوقيع بعد التوقيع (فحوصات السلسلة، الطوابع الزمنية).
  • اختبر عبر بيئات وأنواع رموز مختلفة (مفتاح/بطاقة ذكية/HSM).

الخطوات التالية والموارد

هل أنت مستعد لتجربتها بنفسك؟ استنسخ المستودع، حدِّث القيم النائبة، وشغّل العينة.
المواضيع التي قد ترغب في استكشافها لاحقًا:

  • توقيع تجزئة مخصص (تفويض التجزئة + التوقيع إلى الرّمز)
  • الطابع الزمني و LTV / DSS
  • التوقيع التكراري (تعدد التواقيع في مستند واحد)
  • الاندماج مع خدمات HSM عن بُعد أو مخازن الرموز السحابية

روابط خارجية