תוסף חותם
חתום על קבצי PDF ו-Word עם חתימה נראית וחותם דיגיטלי
ה‑plugin של Signer מציב חתימה נראית על מסמך ובברירת מחדל אוטם אותו עם חתימה דיגיטלית שמקרא PDF יכול לאמת. הוא חותם קבצי PDF ו‑Word (.docx). החתימה הנראית היא תמיד תמונת PNG: מצוירת, מוקלדת או שהועלתה על ידי החותם.
| ממשק | מתי להשתמש |
|---|---|
DocumentSigner (C#) | אתה חותם על השרת, ללא דפדפן מעורב |
וידג'ט משולב (doconutSigner.js) | אתה רוצה מסך העלאה, חתימה והורדה מוכן לשימוש בדף שלך |
נקודות קצה HTTP בDocImage.axd (?sign=open|run|download) | אתה בונה ממשק חתימה משלך נגד חוזה שרת מתועד |
כל חתימה ממוקמת פעם אחת, בעמוד אחד. שם החותם, הסיבה והמיקום יכולים ללוות אותה.
התקנת החבילה
Install-Package Doconut.NETFramework.Signerכדי לקבע את הפלאגין לגרסה שהדוקומנטציה מתארת:
Install-Package Doconut.NETFramework.Signer -Version 26.10.0שמור על חבילת Signer באותה גרסה כמו Doconut.NETFramework.
קובץ הרישיון של הפלאגין, Doconut.Viewer.Signer.lic, נמצא באותה תיקייה כמו Doconut.Viewer.lic; הוא נקרא יחד עם רישיון הצופה.
רישום הפלאגין
כמו כל פלאגין של Doconut, Signer נרשם עם AddPlugin<TPlugin>() ב-DoconutHost.Initialize, שנקרא מ-Application_Start:
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
});הוסף Doconut.DoconutHost.Shutdown() ל-Application_End כדי שהעבודה ברקע תפסיק בצורה נקייה כאשר מאגר האפליקציה מתחדש.
זהו כל מה שהפאסאד של C# צריך. הווידג'ט וה‑HTTP endpoints שלו הם אופציה נפרדת, AddSignerWidget() (ראה וידג'ט משולב).
הפלאגין דורש רישיון שמעניק את היכולת Signer. ללא רישיון, DoconutHost.Initialize זורק משגיאה מ-Application_Start:
The Signer plugin is registered via AddPlugin but no active license grants Signer. Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Signer.ב‑System.Web משמעות הדבר שכל בקשה מחזירה 500 ריק, והסיבה מופיעה רק ביומן אירועי Windows (מקור ASP.NET). הוא זורק עבור חוסר רישיון, קובץ TRIAL מיושן, רישיון ללא Signer, ורישיון בתשלום שנעשה בו שימוש מחוץ לחלון הגרסה שלו. רישיונות Demo/NFR זמניים מתקבלים. ראה הגדרת רישיון.
רישוי וסימן מים
| מצב רישיון | אתחול | חתימה מאושרת | חתימה ויזואלית |
|---|---|---|---|
רישיון בתשלום המעניק Signer, תעודה מוגדרת | מתחיל | אטום עם התעודה שלך, נקי (watermarked: false) | נקי |
רישיון בתשלום המעניק Signer, ללא תעודה | מתחיל | נדחה: No signing certificate configured. | נקי |
| רישיון בתשלום, תעודה שפגה תוקף או עדיין לא בתוקף | מתחיל | נדחה: The signing certificate expired on yyyy-MM-dd. | נקי |
| רישיון Demo/NFR זמני, פעיל או פג | מתחיל | אטום עם תעודת הדמו המובנית, מסומן במים (watermarked: true) | מסומן במים |
ללא רישיון, קובץ TRIAL מיושן, רישיון ללא Signer, או רישיון בתשלום מחוץ לחלון הגרסה שלו | Application_Start זורק; כל בקשה מחזירה 500 ריק | — | — |
הכלל זהה עבור הפאסאד של C# והווידג'ט: הפלט מסומן במים כאשר הרישיון אינו רישיון צופה בתשלום או שהוא זמני. תחת רישיון זמני הפלאגין תמיד חותם עם תעודת הדמו המובנית, וכל תעודה שאתה מגדיר אינה משמשת.
תעודת הדמו מייצרת חותם אמיתי, אך קוראי PDF אינם סומכים עליה. ניתן לבנות ולבדוק אינטגרציה מקצה לקצה ברישיון הערכה; כדי לקבל פלט נקי ואמין אתה צריך גם רישיון בתשלום וגם את תעודת החתימה שלך.
שימוש מ-C#
DocumentSigner נרשם על ידי DoconutHost.Initialize; יש לפתור אותו מ-DoconutHost.Services. הבנאי שלו פנימי, ולכן לעולם אל תnew אותו. פתירתו ללא AddPlugin<SignerPlugin>() גורמת לNo IDocumentSigner is registered. Add the signing plugin: options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>().
using Doconut;
using Doconut.Core.Models.Signing;
public sealed class ContractSigning
{
private readonly DocumentSigner _signer;
public ContractSigning(DocumentSigner signer) => _signer = signer;
public async Task<byte[]> SignAsync(Stream pdf, byte[] signaturePng, SigningCertificate certificate, CancellationToken ct)
{
var request = new SignRequest(
new VisibleSignature(SignatureKind.Drawn, signaturePng),
new SignaturePlacement(Page: 1, X: 0.58, Y: 0.80, W: 0.32, H: 0.12),
SignerName: "Ada Lovelace",
Reason: "I approve this document",
Location: "London, UK");
// Mode מוגדר כברירת מחדל ל-Certified (חתימה נראית + חותמת דיגיטלית); WordOutput מוגדר כברירת מחדל ל-Pdf.
SignResult result = await _signer.SignAsync(pdf, ".pdf", request, certificate, ct);
using (result.Stream)
using (var output = new MemoryStream())
{
await result.Stream.CopyToAsync(output, 81920, ct);
return output.ToArray();
}
}
}SignAsync מקבל את זרם המקור, את ההרחבה שלו (".pdf" או ".docx"), את הבקשה, ואת האישור לקריאה זו. הפאסאד אינו קורא את SignerWidgetOptions.SigningCertificate; ההגדרה הזאת מיועדת לווידג'ט. העבר את null תחת רישיון הדגמה, או במצב Visual.
SignResult מחזיק את המסמך החתום כזרם שניתן לחיפוש, בנוסף לExtension שלו (".pdf" או ".docx") כך שתוכל לתת שם לקובץ. אתה הבעלים של הזרם: נקה אותו כשסיימת.
במבקר MVC 5
הפוך את הפעולה לאסינכרונית וawait את החתימה. זה מוסיף חותמת Visual, שאינה דורשת אישור:
[HttpPost]
public async Task<ActionResult> Sign(HttpPostedFileBase file)
{
var signer = Doconut.DoconutHost.Services.GetRequiredService<DocumentSigner>();
byte[] signaturePng = System.IO.File.ReadAllBytes(Server.MapPath("~/App_Data/signature.png"));
var request = new SignRequest(
new VisibleSignature(SignatureKind.Image, signaturePng),
new SignaturePlacement(Page: 1, X: 0.58, Y: 0.80, W: 0.32, H: 0.12),
Mode: SignatureMode.Visual);
SignResult result = await signer.SignAsync(
file.InputStream, Path.GetExtension(file.FileName), request, ct: Response.ClientDisconnectedToken);
string contentType = result.Extension == ".pdf"
? "application/pdf"
: "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
return File(result.Stream, contentType, Path.GetFileNameWithoutExtension(file.FileName) + "-signed" + result.Extension);
}מקור Word נחתם ל-PDF אלא אם תבקש פלט Word. שם את התוצאה מ-result.Extension:
var signer = Doconut.DoconutHost.Services.GetRequiredService<DocumentSigner>();
byte[] signaturePng = File.ReadAllBytes(HostingEnvironment.MapPath("~/App_Data/signature.png"));
var request = new SignRequest(
new VisibleSignature(SignatureKind.Drawn, signaturePng),
new SignaturePlacement(Page: 1, X: 0.58, Y: 0.80, W: 0.32, H: 0.12),
WordOutput: WordOutput.Docx);
SignResult result = await signer.SignAsync(stream, ".docx", request, ct: ct);
string downloadName = "contract-signed" + result.Extension; // ".docx"SignAsync זורק במקום להחזיר כאשר הקריאה אינה מצליחה:
| חריגה | הודעה | מתי |
|---|---|---|
InvalidOperationException | No signing certificate configured. | מצב מוסמך, רישיון בתשלום, ולא נמסר אישור |
InvalidOperationException | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. | מצב מוסמך עם אישור מחוץ לתקופת התוקף שלו |
ArgumentException | The sign request is invalid: the visible signature needs PNG bytes and the placement must be a normalized rectangle on a 1-based page. | בייטים ריקים של PNG, או מיקום שאינו תקף |
NotSupportedException | The signer supports PDF and Word (.docx) documents; got '{extension}'. | כל סוג מקור אחר |
מצבי חתימה, פלט Word ותעודות
מצבי חתימה
SignRequest.Mode בוחר אם החתימה אטומה.
| מצב | מה הוא מייצר | תעודה | ניתן לאימות |
|---|---|---|---|
SignatureMode.Certified (ברירת מחדל) | החתימה הגלויה בתוספת חותמת דיגיטלית | נדרש ברישיון בתשלום | כן |
SignatureMode.Visual | רק החתימה הגלויה | אף פעם לא נדרש | לא: זהו תמונה |
השתמש ב-Certified כאשר החתימה חייבת להיות ניתנת להוכחה: אישורים, חוזים, כל דבר שהמאמת צריך לבדוק עבור זהות ושלמות. השתמש ב-Visual כאשר אתה זקוק רק למראה של חתימה, או שאין לך תעודה. רישיון זמני מוסיף סימן מים לשניהם.
חותמות PDF הן חתימות מנותקות PKCS#7 (adbe.pkcs7.detached) עם SHA-256, למפתחות RSA או ECDSA. הן נושאות את תעודות המנפיק שנמצאות ב‑PFX שלך, ולכן קורא שמאמין לשורש שלך יכול לבנות את השרשרת. חותמות מקוריות של Word הן חתימות חבילות OOXML ונושאות רק את תעודת החותם.
מסמכי Word
למקור מסוג .docx, SignRequest.WordOutput בוחר את הפלט. הוא מתעלם ממקורות PDF, שתמיד מייצרים PDF.
| פלט | מה קורה | תמיכת המאמת |
|---|---|---|
WordOutput.Pdf (ברירת מחדל) | המסמך מומר ל‑PDF, ואז נחתם ונאטם | רחבה: PDF חתום מאומת בכל מקום |
WordOutput.Docx | המסמך נשאר ב‑Word: תמונת החתימה מוכנסת לתוכו, בנוסף לחתימת חבילה OOXML | מוגבלת: לא כל מציג מציג חתימות חבילות OOXML |
הישאר עם PDF אלא אם הנמען צריך קובץ Word שניתן לעריכה ומקבל את תמיכת המאמת המוגבלת.
הגדרת תעודה
כדי לאטום עם הזהות שלך, ספק לתוסף קובץ PFX (PKCS#12) הכולל את המפתח הפרטי. עבור הווידג'ט, הגדר SignerWidgetOptions.SigningCertificate; עבור המעטפת ב‑C#, העבר את התעודה ל‑SignAsync. ספק או את הבייטים או נתיב, יחד עם הסיסמה. App_Data הוא מקום טוב לקובץ, מכיוון ש‑IIS אף פעם לא מגיש אותו:
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.SigningCertificate = new SigningCertificate
{
PfxBytes = File.ReadAllBytes(HostingEnvironment.MapPath("~/App_Data/signing.pfx")),
Password = System.Configuration.ConfigurationManager.AppSettings["DoconutSigner:Password"] ?? "",
};
});
});Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.SigningCertificate = new SigningCertificate
{
PfxPath = HostingEnvironment.MapPath("~/App_Data/signing.pfx"),
Password = System.Configuration.ConfigurationManager.AppSettings["DoconutSigner:Password"] ?? "",
};
});
});המאפיינים של SigningCertificate הם רק אתחול, ולכן C# 7.3 (ברירת המחדל לפרויקטים של .NET Framework) לא יכול להגדיר אותם. הגדר את <LangVersion> ל‑9.0 או גרסה מאוחרת יותר בקובץ הפרויקט.
התעודה מוחזקת בזיכרון בלבד. היא לעולם לא נרשמת, לא מוחזרת ללקוח, ולא נשמרת, והסיסמה לעולם לא מופיעה בהודעת שגיאה.
דרישות:
- חבילה PFX / PKCS#12 עם המפתח הפרטי שלה. קובץ שמכיל רק מפתח ציבורי (
.cer,.crt) אינו יכול לחתום. יצא את שרשרת המנפיק יחד איתו, כך שחותמות PDF יוכלו לשאת אותה. - הסיסמה הנכונה.
- בתוך חלון התוקף שלה. תעודה שפג תוקפה או שעדיין לא בתוקף לא עוצרת את האפליקציה, אך חתימות Certified נדחות עד להחלפתה. חתימות Visual אינן מושפעות.
- הונפקה לחתימת מסמכים: שימוש במפתח עם חתימה דיגיטלית או אי-ויתור, ושימוש במפתח מורחב, אם קיים, שמאפשר חתימת מסמכים, הגנת דוא"ל או אימות לקוח. תעודה שהונפקה למטרה אחרת, כגון תעודת שרת TLS, עדיין חותמת, אך קוראי PDF מסמנים את החתימה.
- אסימוני חומרה, כרטיסים חכמים, HSMs וחנות התעודות של Windows אינם נתמכים. יצא את התעודה, עם המפתח הפרטי והשרשרת, ל‑PFX.
צור PFX מתעודה ומפתח פרטי באמצעות OpenSSL:
openssl pkcs12 -export -out signing.pfx -inkey private.key -in certificate.crt
# הסיסמה לייצוא שאתה מתבקש להזין היא SigningCertificate.Password.יצא אחת מחנות התעודות של Windows: פתח את certmgr.msc ומצא את התעודה (הסמל שלה מציג מפתח כאשר המפתח הפרטי קיים). לחץ לחיצה ימנית, בחר כל המשימות → יצוא…, בחר כן, יצא את המפתח הפרטי, בחר Personal Information Exchange – PKCS #12 (.PFX), והגדר סיסמה.
בדיקות אתחול
כאשר הווידג'ט מופעל, האישור בSignerWidgetOptions.SigningCertificate נבדק פעם אחת, בתוך DoconutHost.Initialize, ולכן קובץ PFX שמוגדר באופן שגוי נכשל באתחול במקום בחתימה הראשונה. שלושה בעיות זורקות InvalidOperationException מApplication_Start, וכל בקשה משיבה 500 ריק; ההודעה נמצאת ביומן האירועים של Windows:
| הודעה | תיקון |
|---|---|
Doconut Signer: the certificate file was not found at '{path}'. | תקן את PfxPath; ודא שהקובץ מופץ וקריא על ידי חשבון בריכת האפליקציה |
Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx. | בדוק את הסיסמה; ודא שהקובץ הוא .pfx אמיתי, ולא .cer או .pem |
Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key. | ייצא את ה-PFX שוב עם המפתח הפרטי |
ב-ASP.NET Core המארח גם רושם שורה אחת באתחול שמציינת את האישור, או מזהיר שהוא פג תוקף או שלא הונפק לחתימה. DoconutHost אינו כותב שורה זו, ולכן ב-.NET Framework יש לבדוק אישור חדש על ידי חתימה על מסמך בדיקה במצב Certified.
החזית של C# אינה נבדקת באתחול. האישור שאתה מעביר לSignAsync נקרא כאשר אתה חותם, ולכן נתיב או סיסמה שגויים יגרמו לכשל בקריאה זו.
ווידג'ט Drop-in
אפשר את נקודות הקצה
נקודות הקצה של ?sign=open|run|download של הווידג'ט מוגשות על ידי DocImage.axd והן כבויות כברירת מחדל. אפשר אותן ליד רישום הפלאגין:
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.MaxUploadMb = 25; // ברירת המחדל
widget.MaxSignatureImageKb = 512; // ברירת המחדל
// widget.SigningCertificate: ראה את הגדרת Certificate; השאר אותו null עבור demo (watermarked) חתימה
});
});
// System.Web קורא את כל ההעלאה לפני ש-Doconut רואה זאת: שמור maxRequestLength (KB) ו
// maxAllowedContentLength (bytes) ב-Web.config מעל MaxUploadMb של widget.AddSignerWidget() ללא ארגומנט מאפשר את הווידג'ט עם ברירות המחדל. הוא אינו מעניק חתימה בעצמו: הוא זקוק לAddPlugin<SignerPlugin>(), או שDoconutHost.Initialize זורק:
AddSignerWidget() was called but the Signer plugin is not registered. Add options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>() (the widget needs it), or remove the AddSignerWidget() call.נקודות הקצה והסקריפט מוגשים על ידי המטפל והממודול הרשום בWeb.config:
<system.webServer>
<handlers>
<add name="DocImage" verb="GET,HEAD,POST" path="DocImage.axd" type="Doconut.DocImageHandler, Doconut" />
</handlers>
<modules>
<add name="DoconutResources" type="Doconut.DoconutResourceModule, Doconut" />
</modules>
</system.webServer>המודול מגיש את הסקריפט בין אם הווידג'ט מופעל ובין אם לא. ללא AddSignerWidget(), הווידג'ט נטען ומצייר את אזור ההפלה שלו, והבקשה הראשונה שלו משיבה 404: הווידג'ט אז מדווח Signing is not enabled on this server.
מגבלות העלאה
ASP.NET קורא את כל גוף הבקשה לפני שהDocImage.axd רץ. העלאה מעל MaxUploadMb אך מתחת למגבלות המארח מקבלת את ה-JSON של הווידג'ט 413 (File is too large.). העלאה מעל מגבלות המארח נדחית תחילה על ידי IIS, עם דף שגיאה שהווידג'ט אינו יכול לקרוא. שמור ששתי מגבלות המארח גבוהות מהתקרה של הווידג'ט:
<system.web>
<httpRuntime maxRequestLength="30720" /> <!-- KILOBYTES: 30 MB -->
</system.web>
<system.webServer>
<security>
<requestFiltering>
<requestLimits maxAllowedContentLength="31457280" /> <!-- BYTES: 30 MB -->
</requestFiltering>
</security>
</system.webServer>העלאה שנשלחת ללא Content-Length (בצורת chunked) שעולה על מגבלות המארח גם היא מקבלת את דף השגיאה של IIS; אין פתרון למקרה זה.
הטמע זאת
הסקריפט מוגש ב/doconut-res/js/doconutSigner.js. זהו קובץ יחיד, עצמאי וללא תלות. הפנה את basePath אל המטפל:
<div id="host"></div>
<script src="/doconut-res/js/doconutSigner.js"></script>
<script>
const handle = Doconut.signer('#host', { basePath: '/DocImage.axd' });
</script>Doconut.signer(selectorOrElement, options) מקבל בחירת CSS או אלמנט, זורק שגיאה אם ה‑mount לא נמצא, ומחזיר מצביע. ערך ברירת המחדל של הווידג'ט עבור basePath, /doconut, הוא נקודת הקצה של ASP.NET Core; בחבילה זו הוא חייב להיות '/DocImage.axd'.
החתם מעלה קובץ PDF או קובץ .docx, יוצר חתימה (צייר על קנבס, הקלד שם בגופן חתימה, או תמונה מקובץ PNG, JPG או GIF), גורר ומגדיל אותה על העמוד, חותם ומוריד את התוצאה. הווידג'ט תמיד שולח את החתימה כ‑PNG; תמונה שהועלתה מומרת בדפדפן ל‑PNG בגודל 520×160.
אפשרויות
| אפשרות | סוג | ברירת מחדל | הערות |
|---|---|---|---|
basePath | string | '/doconut' | היכן שמוגשים נקודות הקצה של ?sign= ותמונות התצוגה המקדימה. הגדר את '/DocImage.axd' בחבילה זו |
resPath | string | '/doconut-res' | שמורה; הווידג'ט כולל את ה‑CSS שלו |
maxUploadMb | number | 25 | בדיקה בצד הלקוח בלבד, ולכן קובץ גדול מדי נכשל מיידית. המגבלה בצד השרת היא MaxUploadMb ב‑AddSignerWidget |
maxSignatureKb | number | 512 | מגבלה בצד הלקוח למצב Image. שמור אותה שווה למגבלה של השרת MaxSignatureImageKb |
previewWidth | number | 560 | רוחב פיקסלים של תצוגת העמוד |
licenseUrl | string | null | null | הופך את ההודעה של סימן המים לדמו לקישור ל‑URL הזה |
signatureMode | string | 'certified' | סוג החתימה הראשוני: 'certified' או 'visual'. כל ערך אחר הופך ל‑'certified' |
showSignatureModeToggle | boolean | true | מציג את האפשרות חתימה דיגיטלית / חזותית בלבד. עם false, הווידג'ט חותם עם signatureMode |
wordOutput | string | 'pdf' | פלט ראשוני למקורות .docx: 'pdf' או 'docx'. כל ערך אחר הופך ל‑'pdf' |
showOutputFormatToggle | boolean | true | מציג את האפשרות PDF / Word, למקורות .docx בלבד. עם false, הווידג'ט משתמש ב‑wordOutput |
labels | object | {} | עוקף כל תת‑קבוצה של המחרוזות באנגלית |
הסתרת מתג אינה משביתת את הפונקציה; היא קובעת את הערך. שתי תצורות נפוצות:
// שני המתגים מוצגים, חתימה דיגיטלית כברירת מחדל: חותם שירות עצמי מלא.
Doconut.signer('#host', { basePath: '/DocImage.axd', licenseUrl: '/pricing' });// ויזואלי בלבד, ללא מתג: חותמת פשוטה ללא הצעת חתימה דיגיטלית.
Doconut.signer('#host', {
basePath: '/DocImage.axd',
signatureMode: 'visual',
showSignatureModeToggle: false
});קריאות חוזרות
| קריאה חוזרת | מתרחשת כאשר | תוכן |
|---|---|---|
onReady | פעם אחת, בעת ההרכבה (לא שוב ב‑reset()) | — |
onSourceLoaded | הקובץ נפתח ותצוגת המקדימה מוצגת | { file: { token, name, pages, ext } } |
onSigned | החתימה מצליחה | { downloadToken, downloadName, watermarked } |
onDownload | בכל לחיצה על הורדה | { downloadName, downloadToken } |
onError | שלב פתיחה, חתימה או הורדה נכשל, או שקובץ במצב Image גדול מדי | { message } |
קריאה חוזרת שמקפיצה נלכדת ונרשמת; היא לעולם לא משבשת את זרימת הווידג'ט.
מזהה פקודתי
| שיטה | התנהגות |
|---|---|
reset() | מחזיר למסך ההפלה ומנקה את הזרימה הנוכחית. לא מפעיל את onReady שוב. פעולה ריקה לאחר destroy() |
loadFile(file) | מתחיל את הזרימה עם File. פעולה ריקה אלא אם הווידג'ט נמצא במסך ההפלה; קרא ל‑reset() תחילה אם נדרש |
destroy() | מסיר את המאזינים, מרוקן את ה‑mount, וקופא את המופע |
const signerWidget = Doconut.signer('#host', {
basePath: '/DocImage.axd',
onSigned: (result) => console.log('signed', result.downloadName, result.watermarked),
onError: (error) => console.warn(error.message)
});
document.getElementById('start-over').addEventListener('click', () => signerWidget.reset());תוויות
לכל מחרוזת יש ברירת מחדל באנגלית; labels מציף כל תת‑קבוצה והשאר נשארים באנגלית. קטעים שמשתנים בזמן ריצה משתמשים ב{placeholders}, כגון uploading: 'Uploading {name}…' ו‑pages: '{n} pages'.
| מפתח | ברירת מחדל באנגלית |
|---|---|
dropPrompt | Drag & drop a PDF or Word file here |
dropHint | PDF or Word (.docx) |
chooseFile | Choose file |
signatureHeading | Your signature |
modeDraw / modeType / modeImage | Draw / Type / Image |
metaSummary | Signature details (optional) |
metaSignerName / metaReason / metaLocation | Signer name / Reason / Location |
signatureType | Signature type |
modeCertified / modeVisual | Digital signature / Visual only |
modeVisualNote | No certificate — a visible mark only, not cryptographically verifiable. |
outputFormat | Output format |
outputPdf / outputWord | PDF / Word (.docx) |
signAction | Sign document |
download | Download |
demoNotice | Demo — signed with the Doconut demo certificate; output is watermarked. |
signingNotEnabled | Signing is not enabled on this server. |
page / pages | 1 page / {n} pages |
מפתחות נוספים מכסים את שלב ההצבה, את מסך השגיאה, את הטופס המקושר של הודעת ההדגמה (demoNoticePrefix, demoNoticeLink, demoNoticeSuffix) ואת ההודעות של aria-live.
כאשר open או run משיבים 404 ללא שגיאת JSON, הווידג'ט מציג signingNotEnabled. שגיאת JSON מהשרת תמיד גוברת, ולכן הודעות כמו העלאה שפג תוקפה נשארות גלויות.
עריכת נושא
הווידג'ט מוסיף את המחלקה dsw לאלמנט ההרכבה שלו וקורא את הצבעים, הרדיוס והגופנים שלו ממאפייני CSS מותאמים, כך שניתן לעצב אותו מבלי לגעת בפנים שלו:
#host.dsw {
--dsw-accent: #b0522b; /* קישורים, פוקוס, מצב פעיל */
--dsw-bg: #fffaf3;
--dsw-fg: #3b2a1a;
--dsw-muted: #8a7a68;
--dsw-border: #e0cbb0;
--dsw-radius: 14px;
--dsw-font: Georgia, "Times New Roman", serif;
--dsw-signature-font: "Segoe Script", "Brush Script MT", cursive; /* מצב Type */
}ברירות מחדל: --dsw-accent: #2b6cb0, --dsw-bg: #ffffff, --dsw-fg: #1a202c, --dsw-muted: #718096, --dsw-border: #cbd5e0, --dsw-radius: 8px, גופן מערכת UI, וגופן חתימה קורסיבי.
בנה את הממשק הקדמי שלך
הווידג'ט הוא לקוח של חוזה HTTP זה בDocImage.axd. הנתיבים משיבים 404 עד שAddSignerWidget() נקרא. שגיאות נושאות גוף JSON, { "error": "..." }, למעט כאשר הטבלה מציינת "סטטוס בלבד". ערך בלתי מוכר של ?sign= משיב 400.
| נתיב | מטרה | תגובת הצלחה |
|---|---|---|
POST /DocImage.axd?sign=open (multipart, one file) | העלה קובץ PDF או .docx ופתח אותו לתצוגה מקדימה | 200 — { token, name, pages, ext } |
POST /DocImage.axd?sign=run (JSON body) | חתום על הקובץ שהועלה | 200 — { downloadToken, downloadName, watermarked } |
GET /DocImage.axd?sign=download&token=<downloadToken> | הזרם את הקובץ החתום | 200 — הקובץ, Content-Disposition: attachment, Cache-Control: no-store |
ext בתגובה של open כולל את הנקודה המקדימה (".docx"). תצוגת העמוד משתמשת בנתיב התמונה הסטנדרטי של הצופה, /DocImage.axd?token={token}&page={n}&thumb=1&width={px}; העמוד המוצג הופך לplacement.page.
גוף הrun:
{
"token": "GUID-from-open",
"signature": { "kind": "Drawn", "payload": "<base64 PNG, no data: prefix>" },
"placement": { "page": 1, "x": 0.58, "y": 0.80, "w": 0.32, "h": 0.12 },
"meta": { "signerName": "Ada Lovelace", "reason": "I approve", "location": "London, UK" },
"wordOutput": "pdf",
"mode": "certified"
}| שדה | הערות |
|---|---|
token | הטוקן מopen |
signature.kind | Drawn, Typed או Image, ללא תלות ברישיות; כל דבר אחר הופך לDrawn. רמז בלבד: המטען הוא תמיד PNG |
signature.payload | PNG בסיסי ב‑base64, ללא קידומת data:. הוא חייב להיות PNG אמיתי ולא גדול יותר מMaxSignatureImageKb לאחר פענוח |
placement.page | מתחיל מ‑1 |
placement.x / y / w / h | 0..1 מנורמל מהפינה העליונה‑שמאלית, עם x + w ≤ 1 ו‑y + h ≤ 1 |
meta.signerName / reason / location | אופציונלי. כל אחד נחתך, ערך ריק נזרק, וכל אחד נחתך ל‑256 תווים |
wordOutput | pdf (ברירת מחדל) או docx; מתעלמים ממקורות PDF. כל דבר אחר הופך לpdf |
mode | certified (ברירת מחדל) או visual. כל דבר אחר הופך לcertified |
downloadName עוקב אחרי הפלט: <source>-signed.pdf או <source>-signed.docx, ו‑download שולח את Content-Type המתאים.
המקור שהועלה והתוצאה החתומה נשמרים כל אחד 30 דקות. לאחר מכן, run ו‑download משיבים 404 והקובץ חייב להיפתח שוב. כל הטוקנים הם GUIDs.
| נתיב | סטטוס | מתי | גוף |
|---|---|---|---|
| כל | 404 | הווידג'ט אינו מופעל | סטטוס בלבד |
| כל | 405 | פעולה שגויה (open ו‑run צריכים POST, download צריך GET) | סטטוס בלבד |
open | 400 | לא העלאה מרובת חלקים | Expected a multipart file upload. |
open | 400 | אין קובץ, או קובץ ריק | No file uploaded. |
open | 400 | כל דבר שאינו .pdf או .docx | Signing supports PDF and Word (.docx) files only. |
open | 413 | ההעלאה חורגת מMaxUploadMb (אך לא מגבולות IIS) | File is too large. |
run | 400 | הגוף אינו JSON תקף, או ריק | Malformed request. / Empty request. |
run | 400 | הטוקן חסר או אינו GUID | Invalid token. |
run | 404 | ההעלאה פגה תוקף או מעולם לא נפתחה | Upload expired — please re-open the file. |
run | 400 | אין חתימה, או אין הצבה | No signature supplied. / No placement supplied. |
run | 400 | המטען אינו base64, ריק, גדול מדי, או אינו PNG | Signature image is not valid base64. / Signature image is empty. / Signature image is too large. / The signature image must be a PNG. |
run | 400 | ההצבה מחוץ לעמוד | The signature or its placement is invalid. |
run | 400 | מצב מוסמך, רישיון בתשלום ואין תעודה | No signing certificate configured. |
run | 400 | מצב מוסמך עם תעודה מחוץ לתקופת התוקף שלה | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. |
open, run | 500 | העיבוד נכשל | הודעה מסוננת |
download | 400 | הטוקן חסר או אינו GUID | סטטוס בלבד |
download | 404 | טוקן לא ידוע או פג תוקף | סטטוס בלבד |
סיבוב מלא עם fetch:
// file: הקובץ לחתימה; pngBase64: החתימה כ‑base64 PNG גלוי, ללא קידומת data:
// לדוגמה canvas.toDataURL('image/png').split(',')[1].
async function signFile(file, pngBase64) {
const base = '/DocImage.axd';
// 1. open: העלה את הקובץ
const form = new FormData();
form.append('file', file, file.name);
const opened = await (await fetch(base + '?sign=open', { method: 'POST', body: form })).json();
// 2. run: חתום עליו
const signed = await (await fetch(base + '?sign=run', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
token: opened.token,
signature: { kind: 'Drawn', payload: pngBase64 },
placement: { page: 1, x: 0.58, y: 0.80, w: 0.32, h: 0.12 },
meta: { signerName: 'Ada Lovelace', reason: 'I approve', location: 'London, UK' },
wordOutput: 'pdf',
mode: 'certified'
})
})).json();
// 3. download: הורד את הקובץ החתום
const blob = await (await fetch(base + '?sign=download&token=' + encodeURIComponent(signed.downloadToken))).blob();
const link = document.createElement('a');
link.href = URL.createObjectURL(blob);
link.download = signed.downloadName;
link.click();
URL.revokeObjectURL(link.href);
}הקצות הם same-origin: גרסה זו אינה תומכת ב‑CORS. הגש את UI והסקריפט של הווידג'ט מאותו מקור כמו היישום, או הפוך‑פרוקסי את DocImage.axd ו‑/doconut-res מתחת למקור של UI שלך.
בייצור
-
התקן את התוסף ליד חבילת הליבה, באותה גרסה:
Install-Package Doconut.NETFramework.Signer. -
הוסף את קובץ הרישיון. שים את
Doconut.Viewer.Signer.licבאותה תיקייה כמוDoconut.Viewer.lic. -
קבל את האישור שלך כ‑PFX עם המפתח הפרטי ושרשרת המנפיק, מרשות תעודות או מ‑PKI של הארגון שלך. כדי לנסות תחילה, השתמש ברישיון הדגמה (האישור המובנה עם סימן מים) או ב‑PFX חתום בעצמך.
-
קרא את האישור מההגדרות, כך ששינויו לעולם לא יצריך שינוי קוד:
xml<appSettings> <add key="DoconutSigner:PfxPath" value="~/App_Data/your-certificate.pfx" /> </appSettings>csharpvar settings = System.Configuration.ConfigurationManager.AppSettings; Doconut.DoconutHost.Initialize(options => { options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic"); options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>(); options.AddSignerWidget(widget => widget.SigningCertificate = new SigningCertificate { PfxPath = HostingEnvironment.MapPath(settings["DoconutSigner:PfxPath"]), Password = settings["DoconutSigner:Password"] ?? "", }); });שמור את
.pfxב‑App_Data, שבו IIS לעולם לא מגיש, ושמור את הסיסמה מחוץ ל‑Web.configרגיל: השתמש בחלק הגדרות מוצפן, או במאגר סודות שהפריסה שלך קוראת. -
חתום על מסמך בדיקה במצב Certified. אישור שפג תוקפו או שעדיין אינו בתוקף נדחה עם
The signing certificate expired on yyyy-MM-dd.(אוis not valid before), וקורא PDF מציג האם הוא סומך על החתימה.
אמון בקוראי PDF. קורא מציג את החתימה כתקפה כאשר הוא סומך על שורש האישור. עם ה‑PKI של הארגון שלך, זה תקף על כל מכונה שסומכת על השורש שלך, שבדרך כלל כל מכונה בתוך הארגון. אישורים ש‑Adobe סומכת עליהם בכל מכונה (רשימת האמון המאושרת של Adobe) ניתנים, ככל הידוע לנו, עם המפתח הפרטי על אסימון חומרה או HSM, שהתוסף הזה אינו יכול להשתמש בו: הוא חותם רק מ‑PFX. אמת עם ספק האישור שלך לפני שאתה סומך על סוג אמון זה.
חוות שרתים
הווידג'ט שומר כל העלאה ותוצאתה בזיכרון על השרת ששירת את open. מאחורי מאזן עומס ללא מושב דביק, בקשה מאוחרת של run, download או תצוגה מקדימה יכולה להגיע לשרת אחר ולא למצוא את ההעלאה. רשום את מאגר הווידג'ט המשותף והמוצפן דרך הארגומנט השני של DoconutHost.Initialize:
byte[] farmKey = Convert.FromBase64String(System.Configuration.ConfigurationManager.AppSettings["Doconut:FarmKey"]);
Doconut.DoconutHost.Initialize(
options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget();
},
services => services.AddDoconutDistributedWidgets(store =>
{
store.RootPath = @"\\fileshare\doconut"; // תיקייה שכל שרת יכול לקרוא ולכתוב
store.FarmKey = farmKey; // לפחות 32 בתים, זהה בכל שרת
// store.Ttl = TimeSpan.FromMinutes(30); // כמה זמן העלאה נשמרת (ברירת המחדל)
}));- שרת יחיד אינו צריך דבר: ללא קריאה זו משתמשים במאגר בזיכרון.
- העלאות ותוצאות מוצפנות במנוחה על השיתוף (AES-256, encrypt-then-MAC), וכל קובץ קשור לאסימון שלו, כך שאסימון אחד לעולם לא יכול לקרוא קובץ של אחר.
FarmKeyחייב להיות לפחות 32 בתים והזהה על כל שרת. טען אותו ממאגר סודות; אל תכתוב אותו בקוד. הרשמה זורקתArgumentExceptionכאשרRootPathחסר או כאשרFarmKeyקצר מ‑32 בתים.- הפנה את
RootPathלאותו מיקום משותף שהצופה המבוזר משתמש בו, ותן לכל שרת את אותו אישור חתימה.
רפרנס API
המחזית והאפשרויות של הווידג'ט נמצאות במרחב השמות Doconut; סוגי הבקשה והתוצאה נמצאים בDoconut.Core.Models.Signing. SignerPlugin נמצא בDoconut.Plugins.Signer.
DocumentSigner
public sealed class DocumentSigner
{
public Task<SignResult> SignAsync(
Stream source, string sourceExtension, SignRequest request,
SigningCertificate? cert = null, CancellationToken ct = default);
}מתקבל מDoconutHost.Services; הבנאי פנימי. sourceExtension הוא ".pdf" או ".docx". ברישיון בתשלום משתמשים בcert והפלט נקי; ברישיון זמני משתמשים בתעודת ההדגמה המובנית, cert מתעלמים ממנו, והפלט מסומן במים.
SignRequest
public sealed record SignRequest(
VisibleSignature Signature,
SignaturePlacement Placement,
string? SignerName = null,
string? Reason = null,
string? Location = null,
WordOutput WordOutput = WordOutput.Pdf,
SignatureMode Mode = SignatureMode.Certified)
{
public bool IsValid { get; } // Signature.IsValid && Placement.IsValid
}חתימה גלויה אחת המונחת פעם אחת, בנוסף למטא-נתוני החותם האופציונליים.
VisibleSignature and SignatureKind
public sealed record VisibleSignature(SignatureKind Kind, byte[] PngBytes)
{
public bool IsValid { get; } // PngBytes אינו ריק
}
public enum SignatureKind { Drawn, Typed, Image }PngBytes הוא PNG עבור כל סוג. חתימה מצוירת או מוקלדת היא שקופה; תמונה שהועלתה שומרת על השקיפות שלה, ולכן JPG אטום נשאר אטום. Kind הוא רק רמז.
SignaturePlacement
public readonly record struct SignaturePlacement(int Page, double X, double Y, double W, double H)
{
public bool IsValid { get; } // Page >= 1; X, Y >= 0; W, H > 0; X + W <= 1; Y + H <= 1
}Page הוא מבוסס על 1; X, Y, W ו-H הם 0..1 מנורמלים מהפינה העליונה-שמאלית.
SignatureMode and WordOutput
public enum SignatureMode { Certified, Visual } // Certified הוא ברירת המחדל
public enum WordOutput { Pdf, Docx } // Pdf הוא ברירת המחדל; מתעלם ממקורות PDFSignResult
public sealed record SignResult(Stream Stream, string Extension);המסמך החתום כזרם שניתן לחיפוש, והרחבה שלו עם הנקודה (".pdf" או ".docx").
SigningCertificate
public sealed class SigningCertificate
{
public byte[]? PfxBytes { get; init; }
public string? PfxPath { get; init; }
public string Password { get; init; } = "";
public bool HasMaterial { get; } // PfxBytes אינו ריק, או PfxPath אינו ריק
}הגדר את PfxBytes או את PfxPath, בנוסף לPassword. המגדירים הם רק init: הפרויקט דורש C# 9.0 או גרסה מאוחרת יותר.
SignerWidgetOptions
public sealed class SignerWidgetOptions
{
public int MaxUploadMb { get; set; } = 25;
public int MaxSignatureImageKb { get; set; } = 512;
public SigningCertificate? SigningCertificate { get; set; }
}הגדר דרך DoconutOptions.AddSignerWidget(Action<SignerWidgetOptions>? configure = null), שמחזיר את DoconutOptions כך שניתן לשרשר קריאות. SigningCertificate ריק משמעותו תעודת ההדגמה ברישיון זמני, וחתימות Visual רק ברישיון בתשלום.
פתרון בעיות
| סימן | סיבה | תיקון |
|---|---|---|
כל בקשה מחזירה 500 ריק לאחר הוספת התוסף; יומן האירועים מציג The Signer plugin is registered via AddPlugin but no active license grants Signer. | אין רישיון, קובץ TRIAL, רישיון ללא Signer, או רישיון בתשלום מחוץ לחלון הגרסה שלו | התקן רישיון שמעניק Signer, או הסר את AddPlugin<SignerPlugin>() |
יומן האירועים מציג AddSignerWidget() was called but the Signer plugin is not registered. | הווידג'ט מופעל ללא התוסף שלו | הוסף את options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>() |
יומן האירועים מציג Doconut Signer: the certificate file was not found at '{path}'. | PfxPath מצביע לקובץ חסר | תקן את הנתיב; פרוס את הקובץ במקום שהחשבון של בריכת האפליקציה יכול לקרוא ממנו |
יומן האירועים מציג Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx. | סיסמה שגויה, או קובץ שאינו PKCS#12 | בדוק את הסיסמה; השתמש ב.pfx אמיתי |
יומן האירועים מציג Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key. | הקובץ PFX יוצא ללא המפתח הפרטי שלו | ייצא אותו שוב עם המפתח הפרטי |
new SigningCertificate { … } אינו מתקמפל | הפרויקט משתמש ב‑C# 7.3, שאינו יכול להגדיר תכונות init-only | הגדר את <LangVersion> ל‑9.0 או גרסה מאוחרת יותר |
פתרון של DocumentSigner זורק No IDocumentSigner is registered. | SignerPlugin אינו רשום | הוסף את AddPlugin<SignerPlugin>() בDoconutHost.Initialize |
| הפלט מסומן במים | הרישיון הוא זמני (Demo/NFR) | השתמש ברישיון בתשלום שמעניק Signer |
run משיב 400 No signing certificate configured. | רישיון בתשלום, מצב Certified, ואין תעודה | הגדר את SigningCertificate, או חתום במצב Visual |
run משיב 400 The signing certificate expired on yyyy-MM-dd. | התעודה פג תוקף | החלף אותה; חתימות Visual ממשיכות לעבוד בינתיים |
הווידג'ט נטען אך מציג Signing is not enabled on this server. | לא נקרא AddSignerWidget(), או שbasePath אינו '/DocImage.axd' | קרא את AddSignerWidget(); הגדר את basePath: '/DocImage.axd' |
| העלאה גדולה מציגה דף שגיאת IIS במקום הודעת הווידג'ט | maxRequestLength / maxAllowedContentLength מתחת לMaxUploadMb | העלה את שני מגבלות המארח מעל MaxUploadMb |
run משיב 400 The signature image must be a PNG., Signature image is not valid base64. או Signature image is too large. | ממשק משתמש מותאם שלח URL מסוג data:, JPG, או יותר מ‑MaxSignatureImageKb | שלח PNG ב‑base64 גלוי בתוך המגבלה |
open משיב 413 File is too large. | ההעלאה חורגת מMaxUploadMb | העלה את MaxUploadMb בAddSignerWidget; הmaxUploadMb של הווידג'ט הוא רק בדיקת צד לקוח |
run או download משיבים 404 Upload expired — please re-open the file. | חלון של 30 דקות עבר, או שמשרת נוסף בחווה אינו מחזיק את ההעלאה | פתח את הקובץ שוב; בחווה, רשום את AddDoconutDistributedWidgets |
.docx חתום מציג ללא חתימה בכמה מציגים | פלט Word כולל חתימת חבילה של OOXML, שרבים מהמציגים אינם מציגים | חתום ל‑PDF, ברירת המחדל |
| קוראי PDF אומרים שהזהות של החותם אינה מוכרת | הקורא אינו סומך על השורש של התעודה (תעודת ההדגמה אף פעם אינה מהימנה) | השתמש בתעודה משורש שהקוראים שלך סומכים עליו |
| הווידג'ט נכשל כאשר הממשק נמצא במקור אחר | לנקודות הקצה אין תמיכה ב‑CORS | הגש את הממשק מאותו מקור, או הפוך‑פרוקסי לDocImage.axd ו‑/doconut-res |
| הנושא אינו מתבצע | הבוחר מכוון אל אלמנט בתוך ה‑mount | כוון אל ה‑mount עצמו: #host.dsw או #host |
הערות מסגרת
בהשוואה לחבילות ASP.NET Core, חבילה זו שונה רק באירוח; ה‑API, חוזה הקצה, סקריפט הווידג'ט וכללי הרישוי זהים.
- רישום הוא ב
Application_Start, דרךDoconutHost.Initialize, במקוםbuilder.Services.AddDoconut. שירותים כגוןAddDoconutDistributedWidgetsנכנסים בארגומנט השני שלו. - נקודות קצה מוגשות על ידי
DocImage.axdוהסקריפט על ידיDoconutResourceModule, שניהם רשומים בWeb.config, במקוםUseDoconut()וUseDoconutResources(). הווידג'ט צריךbasePath: '/DocImage.axd'. - כישלונות אתחול מופיעים כ
500ריק בכל בקשה, עם הסיבה ביומן אירועי Windows. - העלאות נקראות במלואן על ידי ASP.NET לפני ש-Doconut רואה אותן, ולכן מגבלות IIS חייבות להיות מעל
MaxUploadMb. - אין שורת יומן אתחול לגבי האישור: שלוש שגיאות האישור עדיין נזרקות, אך השורה שמציינת את האישור אינה נכתבת.
- C# 9.0 או מאוחר יותר נדרש כדי להגדיר את המאפיינים init‑only של
SigningCertificate. - Windows בלבד, כמו שאר חבילת .NET Framework.
האם דף זה היה מועיל?