מבוא והנעה
כאשר מיישמים חתימות דיגיטליות במערכות ברמת ארגון,
הביטחון הוא בלתי מתפשר.
שמירת תעודה בקובץ PFX או P12 מקומי נוחה אך
חשופה לחילוץ או פגיעה במפתח הפרטי. בניגוד לכך,
אסימוני חומרה PKCS#11 (כגון תוספי USB, כרטיסים חכמים, ו‑HSM)
שומרים על המפתחות בתוך גבול עמיד בפני פגיעה, ומבטיחים שהם לעולם לא יעזבו
את המכשיר.
הפוסט הזה מדגים כיצד להשתמש ב-GroupDocs.Signature for .NET ביחד עם Pkcs11Interop כדי לחתום על מסמכי PDF באמצעות אסימוני חומרה. הגישה משלבת נוחות ועמידה בתקנות: GroupDocs מטפל בכל אריזת רמת ה‑PDF (שדות חתימה, חישוב תקציר, הטמעה), בעוד שהאסימון מבצע את החתימה הקריפטוגרפית בפועל.
⚠️ הודעה על יישום מוקדם
פתרון זה מסופק כיום כיישום מוקדם לשימוש בתוספי חתימה דיגיטלית PKCS#11 עם GroupDocs.Signature.
למרות שהוא מאפשר חתימת מסמכים עם אסימוני חומרה, אנו ממליצים בחום לבצע בדיקות נוספות בסביבתכם כדי לוודא שהוא עומד בדרישות האבטחה והציות שלכם.
נשמח לקבל משוב, תוצאות בדיקה והצעות לשיפור.
האתגר: חיבור PKCS#11 לחתימת PDF
שילוב אסימוני PKCS#11 בתהליכי חתימת מסמכים מציב מספר אתגרים לא‑trivial:
- מורכבות ברמת הנמוכה – ממשק ה‑PKCS#11 (Cryptoki) דורש ניהול של משבצות, סשנים, מזהים ותכונות כדי למצוא את המפתח הפרטי הנכון.
- אריזת רמת PDF – חתימת PDF היא יותר מסתם חתימת בתים: הספרייה חייבת לחשב תקצירים נכונים על פני טווחי בתים נבחרים, לעטוף חתימות במכולות CMS/PKCS#7, לכלול חותמות זמן, ולהטמיע מידע אימות.
- שונות ספקים – אסימונים/מודולי ספק שונים עשויים לדרוש מיפוי תכונות מותאם או שכבת ביניים נוספת.
- ציות וניתוח ביקורת – מערכות ייצור דורשות טיפול חזק ב‑PIN, שליטה במחזור חיי הסשן, התאוששות משגיאות, ותיעוד.
פרויקט הדוגמה הזה מתמודד עם האתגרים הללו על‑ידי שילוב ממשק ICustomSignHash ב‑GroupDocs.Signature עם Pkcs11Interop כדי להעביר את החתימה לאסימון, בעוד GroupDocs דואג למבנה ה‑PDF.
מה עושה פרויקט הדוגמה
- מדגים חתימת מסמכי PDF באמצעות אסימוני PKCS#11 (תוסף USB, כרטיס חכם, HSM).
- תומך בגיבוי מאגר תעודות Windows: אם תעודה מותקנת ב‑Windows, הקוד יכול להשתמש בה במקום.
- מיישם חתימת גיבוב מותאמת: GroupDocs מחשב את התקציר; האסימון חותם רק על הגיבוב.
- משאיר את המפתח הפרטי על החומרה בכל זמן — לעולם לא מיוצא.
- מקודד את לוגיקת האסימון (סשן, חיפוש מפתח, חתימה) ב‑
Pkcs11DigitalSigner.cs - מספק לוגיקה מסייעת ב‑
Helpers.cs(לדוגמה, חיפוש תעודה במאגר Windows). - תצורה מרוכזת ב‑
Settings.cs. - משמש כמימוש ייחוס שניתן להתאמה לסביבתכם.
הגדרה מוקדמת ודרישות
דרישות מוקדמות
- .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 או ב‑IDE המועדף, ודאו שכל התלויות נפתרו.
מבנה המאגר – ניתוח מעמיק
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 – מספק סקירה, אתגרים והוראות שימוש (שאלות אלו משלים הבלוג).
הסבר קוד והליכה דרךו
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 מוסמכים
בהודו, רבות מהחתימות האלקטרוניות המחייבות חוקית דורשות תעודות המאוחסנות בתוספי USB שמונפקים על‑ידי רשויות מוסמכות. הדוגמה מאפשרת לאפליקציות (למשל שערי מסמכים, פורטלים) לשלב ישירות עם תוספים כאלה. - תהליכי עבודה ארגוניים
במערכות פנימיות כגון ניהול חוזים או זרימות אישור, חתימה בחומרה מבטיחה שמשתמשים לא מורשים לא יוכלו לזייף חתימות על מסמכים. - חתימה משפטית / ציות
ממשלות ותעשיות מוסדרות רבות דורשות שהחתימות יגיעו ממפתחות הנשלטים בחומרה. אינטגרציה זו מסייעת לעמוד בדרישות ביקורת וציות קפדניות.
בעיות נפוצות ופתרון תקלות
- נתיב ספרייה שגוי → נתיב ה‑DLL של PKCS#11 חייב להתאים למודול של ספק האסימון שלכם (למשל
softhsm2.dll,cryptoki.dll). - נעילת PIN או כשל → הקלדת PIN שגויה מספר פעמים עלולה לנעול את האסימון; בדקו את מדיניות הספק.
- מפתח לא נמצא → ודאו שהנושא של התעודה שסופק נכון; האסימון חייב להכיל תעודה עם נושא תואם.
- חוסר במנהל התקן או שכבת ביניים → חלק מהאסימונים דורשים התקנת מנהלי ספק לפני ש‑Pkcs11Interop יוכל לתקשר.
- בעיות ריבוי תהליכים → פעולות PKCS#11 עשויות לא להיות בטוחות בריבוי תהליכים; השתמשו בהקשר single‑threaded אלא אם הספק תומך בריבוי.
- זמני קצוב או איפוס סשן → פעולות ארוכות עשויות לגרום לסשנים להיסגר או לפקוע; ודאו טיפול נכון בסשן וניקוי.
אבטחה ושיטות עבודה מומלצות
- לעולם אל תכתבו סודות ייצור בקוד (PINים, נתיבי ספרייה); השתמשו בתצורה מאובטחת או במערכת ניהול סודות.
- השתמשו ב‑PIN חזק והחליפו אותו לפי מדיניות.
- רשמו פעולות ושגיאות (בלי לחשוף PINים רגישים).
- הגבילו את מספר סשני האסימון והתנתקו מיד לאחר החתימה.
- אמתו את החתימה לאחר ביצועה (בדיקות שרשרת, חותמת זמן).
- בדקו במגוון סביבות וסוגי אסימונים (תוסף/כרטיס חכם/HSM).
צעדים הבאים ומשאבים
מוכנים לנסות? שיבטו את המאגר, עדכנו את המקומות המוחזקים, והפעלו את הדוגמה. נושאים שאולי תרצו לחקור בהמשך:
- חתימת גיבוב מותאמת (העברת חישוב גיבוב + חתימה לאסימון)
- חיתום זמן ו‑LTV / DSS
- חתימה איטרטיבית (מספר חתימות במסמך אחד)
- אינטגרציה עם שירותי HSM מרוחקים או מאגרי אסימונים בענן