Introduction & Motivation

כאשר מיישמים חתימות דיגיטליות במערכות ברמת ארגון, הביטחון הוא בלתי ניתן למשא ומתן.
אחסון תעודה בקובץ PFX או P12 מקומי נוח אך מחשף את המפתח הפרטי לחילוץ או פגיעה. בניגוד לכך, אסימוני חומרה PKCS#11 (כגון מתאמי USB, כרטיסי חכם, ו‑HSM) שומרים על המפתחות בתוך גבול עמיד בפני פגיעה, מה שמבטיח שהם לעולם אינם עוזבים את המכשיר.

הפוסט הזה מציג כיצד להשתמש ב‑GroupDocs.Signature for .NET ביחד עם Pkcs11Interop כדי לחתום על מסמכי PDF עם אסימוני חומרה. הגישה משלבת נוחות ועמידה בתקנות: GroupDocs מטפל בכל אריזת רמת ה‑PDF (שדות חתימה, חישוב דיגסט, הטמעה), בעוד שהאסימון מבצע את החתימה הקריפטוגרפית בפועל.

⚠️ הודעה על יישום מוקדם
הפתרון מסופק כיום כיישום מוקדם לשימוש במתאמי חתימה דיגיטלית PKCS#11 עם GroupDocs.Signature.
למרות שהוא מאפשר חתימת מסמכים עם אסימוני חומרה, אנו ממליצים בחום לבצע בדיקות נוספות בסביבה שלכם כדי לוודא שהפתרון עומד בדרישות האבטחה והציות שלכם.
נשמח מאוד לקבל את המשוב שלכם, תוצאות מבחן, ו הצעות לשיפורים.

The Challenge: Bridging PKCS#11 with PDF Signing

שילוב אסימוני PKCS#11 בתהליכי חתימת מסמכים מציב כמה אתגרים לא‑טריוויאליים:

  1. מורכבות ברמה נמוכה – ה‑API של PKCS#11 (Cryptoki) דורש ניהול של סלוטים, סשנים, מזהים, ותכונות כדי לאתר את המפתח הפרטי הנכון.
  2. אריזת PDF ברמה גבוהה – חתימת PDF היא יותר מחתימת בתים: הספרייה חייבת לחשב דיגסים נכונים על פני תחומי בתים נבחרים, לארוז חתימות במכלי CMS/PKCS#7, לכלול חותמות זמן, ולהטמיע מידע אימות.
  3. שונות בין ספקים – אסימוני/מודולי ספק שונים עשויים לדרוש מיפוי תכונות מותאם או שכבת ביניים נוספת.
  4. ציות ויכולת ביקורת – מערכות ייצור זקוקות לטיפול חזק ב‑PIN, שליטה במחזור חיי הסשן, התאוששות משגיאות, ויומן רישום.

דוגמת הפרויקט הזו מתמודדת עם האתגרים על‑ידי שילוב ממשק ICustomSignHash ב‑GroupDocs.Signature עם Pkcs11Interop כך שהחתימה מועברת לאסימון, ואילו GroupDocs מתמודדת עם מבנה ה‑PDF.

What the Sample Project Does

  • מציגה חתימת מסמכי PDF באמצעות אסימוני PKCS#11 (מתאם, כרטיס חכם, HSM).
  • תומכת בגיבוי מאגר תעודות Windows: אם תעודה מותקנת ב‑Windows, הקוד יכול להשתמש בה במקום.
  • מיישמת חתימת גיבוב מותאמת: GroupDocs מחשב את הדיגסט; האסימון חותם רק על הגיבוב.
  • משאירה את המפתח הפרטי בעל החומרה בכל עת — לעולם לא מיוצא.
  • מקוודת את לוגיקת האסימון (סשן, חיפוש מפתחות, חתימה) ב‑ Pkcs11DigitalSigner.cs
  • מספקת לוגיקה מסייעת ב‑Helpers.cs (למשל, חיפוש תעודות במאגר Windows).
  • הקונפיגורציה מרוכזת ב‑Settings.cs.
  • משמשת כהטמעה יחוסית אותה ניתן להתאים לסביבתכם.
חיבור PKCS#11 עם חתימת PDF

Setup & Prerequisites

Prerequisites

  • .NET 6.0 ומעלה (או .NET Framework 4.6.2)
  • ספריית PKCS#11 תקפה (DLL) מספק האסימון שלכם
  • אסימון חומרה (מתאם USB, כרטיס חכם, או HSM) עם תעודה תקפה
  • GroupDocs.Signature for .NET (גרסת ניסיון או רישיון)
  • ספריית Pkcs11Interop

Installation

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 או ב‑IDE המועדף, וודאו שכל התלויות נפתרו.

Repository Structure Deep Dive

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 או מימוש callback של החתימה.
  • README.md – מספק סקירה, אתגרים, והוראות שימוש (שאלו הבלוג משלים).

Code Explanation & Walkthrough

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 — High-Level Flow

public class Pkcs11DigitalSigner : ICustomSignHash
{
    public byte[] SignHash(byte[] hash)
    {
        // This method is invoked by GroupDocs.Signature when it needs the token to sign a hash
        using (var pkcs11 = new Pkcs11(Settings.Pkcs11LibraryPath, AppType.SingleThreaded))
        {
            // Load module, open session, login with PIN, find key and perform signing
        }
    }

    public X509Certificate2 GetCertificateFromPkcs11()
    {
        // Retrieves the public certificate from the token so the signing options can be configured
    }
}
  • SignHash הוא המתודה המרכזית: היא מקבלת את הדיגסט שחישב GroupDocs, ואז משתמשת בממשקי PKCS#11 כדי לחתום עליו.
  • GetCertificateFromPkcs11 מחזירה את התעודה הציבורית השמורה באסימון כדי שהמטאפדטה של החתימה יהיה מדויק.

Program.cs — Usage Flow

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

        // (1) PKCS#11 signing
        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  // link token-based signing
            };
            signature.Sign(outputFile, options);
        }

        // (2) Windows certificate store fallback (optional)
        // 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 כאשר האסימון אינו זמין.

Use Cases & Real-World Scenarios

  • USB Dongles עם תעודות רישום הודו (CA‑Issued)
    בהודו, רבות מהחתימות האלקטרוניות המחויבות מבחינה משפטית דורשות תעודות המאוחסנות במתאמי USB שהונפקו על‑ידי גורמי רישום מוסמכים. דוגמה זו מאפשרת לאפליקציות (למשל שערי מסמכים, פורטלים) להתחבר ישירות למתאמים כאלה.
  • זרימות עבודה ארגוניות למסמכים
    במערכות פנימיות כגון ניהול חוזים או תהליכי אישור, חתימה חומרתית מבטיחה שמשתמשים בלתי מורשים לא יוכלו לזייף חתימות.
  • חתימה רגולטורית / ציות
    ממשלות ותעשיות מפוקחות לעיתים קרובות דורשות שהחתימות יתבצעו ממפתחות השוכנים במכשירי חומרה. אינטגרציה זו מסייעת לעמוד בדרישות ביקורת וציות מחמירות.

Common Pitfalls & Troubleshooting

  • נתיב ספרייה שגוי → נתיב קובץ ה‑DLL של PKCS#11 צריך לקבל את מודול הספק שלכם (למשל softhsm2.dll, cryptoki.dll).
  • נעילה או כישלון PIN → הקלדה חוזרת של PIN שגוי עלולה לנעול את האסימון; בדקו את מדיניות הספק.
  • מפתח לא נמצא → וודאו שה‑subject של התעודה נכון; על האסימון להכיל את התעודה עם אותו subject.
  • חסרים מנהלי התקן או שכבת ביניים → חלק מהאסימונים דורשים התקנת מנהלי התקן של הספק לפני ש‑Pkcs11Interop יוכל לתקשר.
  • בעיות תת־תזרים → פעולות PKCS#11 לעיתים אינן בטוחות לשימוש מרובה תהליכים; השתמשו במצב חד‑תזרי אלא אם הספק מציין אחרת.
  • זמני קצוב או איפוס סשן → פעולות ארוכות עלולות לגרום לסשנים להיסגר; ודאו טיפול נכון בסשנים וניקוי משאבים.

Security & Best Practices

  • אל תכתבו סודות ייצור בקוד (PIN, נתיבי ספרייה); השתמשו בניהול קונפיגורציה מאובטח או במערכת ניהול סודות.
  • השתמשו ב‑PIN חזק והחליפו אותו לפי מדיניות.
  • תיעוד פעילות ושגיאות (בלי לרשום PINים רגישים).
  • הגבילו מספר סשנים של האסימון והתנתקו מיד לאחר החתימה.
  • אמתו את החתימה לאחר החתימה (בדיקת שרשרת, חותמת זמן).
  • בדקו במגוון סביבות וסוגי אסימונים (מתאם/כרטיס חכם/HSM).

Next Steps & Resources

מוכנים לנסות בעצמכם? שיבטו את הריפו, עדכו את המילוי, והריצו את הדוגמה. נושאים שאולי תרצו לחקור לאחר מכן:

  • חתימת גיבוב מותאמת (אחריות על חישוב הדיגסט והחתימה לאסימון)
  • חיתום זמן ו‑LTV / DSS
  • חתימה איטרטיבית (מספר חתימות באותו מסמך)
  • אינטגרציה עם שירותי HSM מרוחקים או חנות אסימוני ענן