תוסף חותם
חתום על מסמכי PDF ו‑Word עם חתימה נראית וחותם דיגיטלי
תוסף החותם מציב חתימה נראית על מסמך ובברירת מחדל חותם אותו בחתימה דיגיטלית שמקרא PDF יכול לאמת. הוא חותם קבצי PDF ו‑Word (.docx). החתימה הנראית היא תמיד תמונת PNG: מצוירת, מוקלדת, או שהמחתים מעלה.
| ממשק | מתי להשתמש |
|---|---|
DocumentSigner (C#) | אתה חותם על השרת, ללא דפדפן |
Drop-in widget (doconutSigner.js) | אתה רוצה מסך העלאה, חתימה והורדה מוכן לשימוש בדף שלך |
HTTP endpoints (?sign=open|run|download) | אתה בונה ממשק חתימה משלך כנגד חוזה שרת מתועד |
כל חתימה מוצבת פעם אחת, בעמוד אחד. שם החותם, הסיבה והמיקום יכולים ללוות אותה.
התקנת החבילה
התקן את תוסף החותם היציב האחרון:
dotnet add package Doconut.NET6.Signerכדי לנעוץ את התוסף לגרסה שהמסמך מתאר, העבר את הגרסה בנפרד:
dotnet add package Doconut.NET6.Signer --version 26.10.0שמור על חבילת החותם באותה גרסה כמו Doconut.NET6. מזהה החבילה הוא Doconut.NET6.Signer; .<version> מופיע רק בשם הקובץ .nupkg שהורד.
קובץ הרישיון של התוסף, Doconut.Viewer.Signer.lic, נמצא באותו תיקייה כמו Doconut.Viewer.lic; הוא נקרא יחד עם רישיון הצופה.
פלטפורמות. התוסף פועל בכל מקום שבו Doconut.NET6 פועל: Windows ולינוקס מבוסס glibc על x64 (לא Alpine או הפצות אחרות מבוססות musl). בלינוקס, התקן את ספריית תצורת הגופנים לפני שהמסמך הראשון נפתח:
apt-get update && apt-get install -y libfontconfig1ב‑RHEL, Fedora והפצות דומות החבילה היא fontconfig. ללא זאת, פתיחת מסמך נכשלת עם The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation.
רישום התוסף
כמו כל תוסף Doconut, Signer נרשם עם AddPlugin<TPlugin>() בתוך AddDoconut():
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
});זה כל מה שהחזית של C# צריכה. הווידג'ט והקצוות HTTP שלו הם אפשרות נפרדת, AddSignerWidget() (ראה ווידג'ט משולב).
התוסף דורש רישיון שמעניק את היכולת Signer. ללא רישיון, AddDoconut() זורק שגיאה בעת ההפעלה, לפני שהאפליקציה מגישה בקשה:
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.הוא זורק שגיאה כאשר אין רישיון, קובץ 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, או רישיון בתשלום מחוץ לתקופת הגרסה שלו | AddDoconut() זורק | — | — |
הכלל זהה לחזית C# ולווידג'ט: הפלט מסומן במים כאשר הרישיון אינו רישיון צופה בתשלום או שהוא זמני. תחת רישיון זמני התוסף תמיד חותם עם תעודת הדמו המובנית שלו, וכל תעודה שאתה מגדיר אינה משומשת.
תעודת הדמו מייצרת חותם אמיתי, אך קוראי PDF אינם סומכים עליה. ניתן לבנות אינטגרציה ולבדוק אותה מקצה לקצה ברישיון הערכה; כדי לקבל פלט נקי ואמין אתה צריך גם רישיון בתשלום וגם את תעודת החתימה שלך.
שימוש מ‑C#
DocumentSigner נרשם על‑ידי AddDoconut() ונפתר מהזרקת תלויות. הבנאי שלו פנימי, ולכן לעולם אל ת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, ct);
return output.ToArray();
}
}
}SignAsync מקבל את זרם המקור, את ההרחבה שלו (".pdf" או ".docx"), את הבקשה, ואת התעודה לקריאה זו. הממשק אינו קורא את SignerWidgetOptions.SigningCertificate; ההגדרה הזאת היא עבור הווידג'ט. העבר את null תחת רישיון הדגמה, או במצב Visual.
SignResult מחזיק את המסמך החתום כזרם שניתן לחיפוש, בנוסף לExtension שלו (".pdf" או ".docx") כך שניתן לתת שם לקובץ. אתה הבעלים של הזרם: שחרר אותו כשסיימת.
חתימה Visual חותמת רק את התמונה ואינה דורשת תעודה:
var signer = app.Services.GetRequiredService<DocumentSigner>();
byte[] signaturePng = File.ReadAllBytes("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(stream, ".pdf", request, ct: ct);מקור Word נחתם ל‑PDF אלא אם אתה מבקש פלט Word. תן שם לתוצאה מresult.Extension:
var signer = app.Services.GetRequiredService<DocumentSigner>();
byte[] signaturePng = File.ReadAllBytes("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. | מצב Certified, רישיון בתשלום, ולא הועברה תעודה |
InvalidOperationException | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. | מצב Certified עם תעודה מחוץ לחלון התוקף שלה |
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 (default) | החתימה הגלויה בתוספת חותמת דיגיטלית | נדרש ברישיון בתשלום | כן |
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. ספק או את הבייטים או נתיב, בנוסף לסיסמה:
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.SigningCertificate = new SigningCertificate
{
PfxBytes = File.ReadAllBytes("/secure/signing.pfx"),
Password = builder.Configuration["Signing:PfxPassword"],
};
});
});builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.SigningCertificate = new SigningCertificate
{
PfxPath = "/secure/signing.pfx",
Password = builder.Configuration["Signing:PfxPassword"],
};
});
});התעודה מוחזקת רק בזיכרון. היא אף פעם לא נרשמת, לא מוחזרת ללקוח, ולא נשמרת, והסיסמה אף פעם לא מופיעה בשורת יומן או בהודעת שגיאה.
דרישות:
- חבילה PFX / PKCS#12 עם המפתח הפרטי שלה. קובץ שמכיל רק מפתח ציבורי (
.cer,.crt) אינו יכול לחתום. ייצא את שרשרת המנפיק יחד איתו, כך שהחתימות ב‑PDF יוכלו לשאת אותה. - הסיסמה הנכונה.
- בתוך חלון התוקף שלה. תעודה שפג תוקפה או שטרם בתוקף אינה עוצרת את האפליקציה: היא נרשמת כהתראה (Warning) בעת ההפעלה, וחתימות 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 ומצא את התעודה (הסמל שלה מציג מפתח כאשר המפתח הפרטי קיים). לחץ לחיצה ימנית, בחר All Tasks → Export…, בחר Yes, export the private key, בחר Personal Information Exchange – PKCS #12 (.PFX), וקבע סיסמה.
בדיקות אתחול
כאשר הווידג'ט מופעל, התעודה ב‑SignerWidgetOptions.SigningCertificate נבדקת פעם אחת, בתוך AddDoconut(), כך ש‑PFX שמוגדר באופן שגוי נכשל באתחול במקום בחתימה הראשונה. שלוש בעיות משליכות InvalidOperationException:
| הודעה | תיקון |
|---|---|
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 שוב עם המפתח הפרטי |
אחרת המארח כותב שורה אחת ליומן כאשר הוא מתחיל. מידע כאשר התעודה מוכנה:
Doconut Signer: using certificate '{subject}' (valid until yyyy-MM-dd). Signatures are digitally sealed.התראה (Warning) כאשר היא פג תוקף, עדיין לא בתוקף, או לא הונפקה לחתימת מסמכים:
Doconut Signer: the signing certificate '{subject}' expired on yyyy-MM-dd. Certified signatures will be refused until it is replaced.
Doconut Signer: the signing certificate '{subject}' is not valid before yyyy-MM-dd. Certified signatures will be refused until then.
Doconut Signer: the signing certificate '{subject}' is not issued for document signing (its key usage excludes it). PDF readers will flag these signatures.ו‑Information כאשר אין תעודה מוגדרת:
Doconut Signer: no signing certificate configured — output uses the built-in demo certificate and is watermarked. Set SignerWidgetOptions.SigningCertificate to sign with your own certificate.השורה האחרונה היא זהה תחת כל הרישיון. תחת רישיון בתשלום תעודת ההדגמה אינה משמשת אף פעם: ללא תעודה, רק חתימות Visual עובדות.
המעטפת ב‑C# אינה נבדקת באתחול. התעודה שאתה מעביר ל‑SignAsync נקראת כאשר אתה חותם, ולכן נתיב או סיסמה שגויים יגרמו לכשל בקריאה זו.
וידג'ט Drop-in
הפעלת הקצוות
קצות ?sign=open|run|download של הווידג'ט כבויים כברירת מחדל. הפעל אותם ליד רישום הפלאגין:
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.MaxUploadMb = 25; // ברירת המחדל
widget.MaxSignatureImageKb = 512; // ברירת המחדל
// widget.SigningCertificate: ראה הגדרת תעודה; השאר אותו null עבור חתימה לדוגמה (עם סימן מים)
});
});AddSignerWidget() ללא ארגומנט מפעיל את הווידג'ט עם ברירות המחדל. הוא אינו מעניק חתימה בעצמו: הוא זקוק לAddPlugin<SignerPlugin>(), או שAddDoconut() זורק:
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.בלי AddSignerWidget(), כל בקשת ?sign= מחזירה 404. הסקריפט עצמו עדיין נשלח, ולכן הווידג'ט נטען ומצייר את אזור ההפלה שלו, ואז מדווח Signing is not enabled on this server. בבקשה הראשונה שלו.
הטמע אותו
UseDoconutResources() מספק את הסקריפט ב{ResourcesPath}/js/doconutSigner.js (ברירת מחדל /doconut-res/js/doconutSigner.js). זהו קובץ יחיד, עצמאי וללא תלות:
<div id="host"></div>
<script src="/doconut-res/js/doconutSigner.js"></script>
<script>
const handle = Doconut.signer('#host', { basePath: '/doconut' });
</script>Doconut.signer(selectorOrElement, options) מקבל בורר CSS או אלמנט, זורק אם המיקום לא נמצא, ומחזיר ידית.
החתם מעלה קובץ PDF או קובץ .docx, בונה חתימה (Draw על קנבס, Type שם בגופן חתימה, או Image מקובץ PNG, JPG או GIF), גורר ומשנה את גודלה על העמוד, וחותם ומוריד את התוצאה. הווידג'ט תמיד שולח את החתימה כ‑PNG; תמונה שהועלתה מומרת בדפדפן ל‑PNG שמתאימה לגודל 520×160.
אפשרויות
| אפשרות | סוג | ברירת מחדל | הערות |
|---|---|---|---|
basePath | string | '/doconut' | היכן קצות ?sign= ותמונות התצוגה המקדימה מוגשים |
resPath | string | '/doconut-res' | שמורה; הווידג'ט כולל את ה‑CSS שלו |
maxUploadMb | number | 25 | בדיקה בצד הלקוח בלבד, ולכן קובץ גדול מדי נכשל מיידית. המגבלה בשרת היא MaxUploadMb בAddSignerWidget |
maxSignatureKb | number | 512 | מגבלה בצד הלקוח למצב Image. שמור אותה שווה למגבלת השרת MaxSignatureImageKb |
previewWidth | number | 560 | רוחב פיקסלים של תצוגת העמוד |
licenseUrl | string | null | null | הופך את הודעת סימן המים של ההדגמה לקישור לכתובת זו |
signatureMode | string | 'certified' | סוג חתימה ראשוני: 'certified' או 'visual'. כל ערך אחר הופך ל'certified' |
showSignatureModeToggle | boolean | true | מציג את האפשרות Digital signature / Visual only. עם false, הווידג'ט חותם עם signatureMode |
wordOutput | string | 'pdf' | פלט ראשוני למקורות .docx: 'pdf' או 'docx'. כל ערך אחר הופך ל'pdf' |
showOutputFormatToggle | boolean | true | מציג את האפשרות PDF / Word, למקורות .docx בלבד. עם false, הווידג'ט משתמש בwordOutput |
labels | object | {} | עוקף כל תת‑קבוצה של המחרוזות באנגלית |
הסתרת מתג אינה משביתת את הפונקציה; היא מקבעת את הערך. שתי תצורות נפוצות:
// שני המתגים מוצגים, חתימה דיגיטלית כברירת המחדל: חותם מלא לשירות עצמי
Doconut.signer('#host', { basePath: '/doconut', licenseUrl: '/pricing' });// ויזואלי בלבד, ללא מתג: חותמת פשוטה ללא הצעת חתימה דיגיטלית
Doconut.signer('#host', {
basePath: '/doconut',
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() | מסיר את המאזינים, מרוקן את ההרכבה, וקופא את המופע |
const signerWidget = Doconut.signer('#host', {
basePath: '/doconut',
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 זה. כל שלוש הנתיבים נמצאים תחת הנתיב שבו UseDoconut() מותקן (בדרך כלל /doconut), והם משיבים 404 עד שAddSignerWidget() נקרא. שגיאות נושאות גוף JSON, { "error": "..." }, למעט כאשר הטבלה אומרת "status only". ערך בלתי מוכר של ?sign= משיב 400.
| נתיב | מטרה | תגובה מוצלחת |
|---|---|---|
POST ?sign=open (multipart, one file) | העלה קובץ PDF או .docx ופתח אותו לתצוגה מקדימה | 200 — { token, name, pages, ext } |
POST ?sign=run (JSON body) | חתום על הקובץ שהועלה | 200 — { downloadToken, downloadName, watermarked } |
GET ?sign=download&token=<downloadToken> | הזרם את הקובץ החתום | 200 — הקובץ, Content-Disposition: attachment, Cache-Control: no-store |
ext בתגובה של open כולל את הנקודה המקדימה (".docx"). תצוגת העמוד משתמשת בנתיב התמונה של הצופה הסטנדרטי, {basePath}?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 | 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: החתימה כ‑PNG base64 גלוי, ללא קידומת data:
// למשל canvas.toDataURL('image/png').split(',')[1].
async function signFile(file, pngBase64) {
const base = '/doconut';
// 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. הגש את ממשק המשתמש והסקריפט של הווידג'ט מאותו מקור כמו Doconut, או הפוך‑פרוקסי את שני הנתיבים /doconut (נתיב האמצעי ונתיב המשאבים) תחת המקור של ממשק המשתמש שלך.
בייצור
-
התקנת התוסף ליד חבילת הליבה, באותה גרסה:
dotnet add package Doconut.NET6.Signer. -
הוספת קובץ הרישיון. שים
Doconut.Viewer.Signer.licבאותה תיקייה כמוDoconut.Viewer.lic. -
קבל את האישור שלך כ‑PFX עם המפתח הפרטי ושרשרת המנפיק, מרשות תעודות או מ‑PKI של הארגון שלך. כדי לנסות תחילה, השתמש ברישיון הדגמה (תעודת ההדגמה המובנית, עם סימן מים) או ב‑PFX חתום עצמאית.
-
קרא את האישור מההגדרות, כך ששינוי שלו לעולם לא יצריך שינוי קוד:
json"DoconutSigner": { "PfxPath": "certs/your-certificate.pfx" }
var signerSettings = builder.Configuration.GetSection("DoconutSigner");
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget => widget.SigningCertificate = new SigningCertificate
{
PfxPath = Path.Combine(builder.Environment.ContentRootPath, signerSettings["PfxPath"]),
Password = signerSettings["Password"] ?? "",
});
});שמור את .pfx מחוץ לwwwroot, ושמור את הסיסמה מחוץ לappsettings.json: סודות משתמש בפיתוח (dotnet user-secrets set "DoconutSigner:Password" "<password>"), משתנה סביבתי (DoconutSigner__Password) או מאגר בייצור.
5. בדוק את יומן האתחול. הוא צריך להכיל using certificate '{subject}' (valid until …). Signatures are digitally sealed. אזהרה, אחרת המשמעות היא שהאישור פג תוקף, עדיין לא תקף, או שלא הונפק לחתימת מסמכים.
אמון בקוראי PDF. קורא מציג את החתימה כתקפה כאשר הוא סומך על שורש האישור. עם ה‑PKI של הארגון שלך, זה נכון על כל מכונה שסומכת על השורש שלך, שבדרך כלל כל המחשבים בתוך הארגון. תעודות שה‑Adobe סומך עליהן בכל מכונה (Adobe Approved Trust List) הן, ככל הידוע לנו, הונפקו עם המפתח הפרטי על טוקן חומרה או HSM, שהפלאג‑אין הזה אינו יכול להשתמש בו: הוא חותם רק מ‑PFX. אשר עם ספק האישור שלך לפני שאתה סומך על סוג אמון זה.
חוות רשת
הווידג'ט שומר כל העלאה ותוצאתה בזיכרון על הצומת ששירתה את open. מאחורי מאזן עומס ללא מושביות, בקשה מאוחרת יותר של run, download או תצוגה מקדימה יכולה להגיע לצומת אחר ולא למצוא את ההעלאה. רשום את מאגר הווידג'ט המשותף והמוצפן פעם אחת, אחרי AddDoconut():
byte[] farmKey = Convert.FromBase64String(builder.Configuration["Doconut:FarmKey"]);
builder.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);
}מתקבל מהזרקת תלות; הבנאי פנימי. 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 (מצב חתימה ופלט Word)
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.
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 כך שניתן לשרשר קריאות. ערך null ב-SigningCertificate משמעותו תעודת ההדגמה ברישיון זמני, וחתימות Visual רק ברישיון בתשלום.
פתרון בעיות
| תסמין | סיבה | פתרון |
|---|---|---|
AddDoconut() זורק The Signer plugin is registered via AddPlugin but no active license grants Signer. | אין רישיון, קובץ TRIAL, רישיון ללא Signer, או רישיון בתשלום מחוץ לחלון הגרסה שלו | התקן רישיון שמעניק Signer, או הסר את AddPlugin<SignerPlugin>() |
AddDoconut() זורק AddSignerWidget() was called but the Signer plugin is not registered. | הווידג'ט מופעל ללא התוסף שלו | הוסף options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>() |
AddDoconut() זורק Doconut Signer: the certificate file was not found at '{path}'. | PfxPath מצביע לקובץ חסר | תקן את הנתיב; פרוס את הקובץ במקום שבו חשבון האפליקציה יכול לקרוא אותו |
AddDoconut() זורק Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx. | סיסמה שגויה, או קובץ שאינו PKCS#12 | בדוק את הסיסמה; השתמש ב-.pfx אמיתי |
AddDoconut() זורק Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key. | ה-PFX יוצא ללא המפתח הפרטי | ייצא אותו שוב עם המפתח הפרטי |
פתרון של DocumentSigner זורק No IDocumentSigner is registered. | SignerPlugin אינו רשום | הוסף AddPlugin<SignerPlugin>() בתוך AddDoconut() |
| הפלט מסומן במים | הרישיון זמני (Demo/NFR) | השתמש ברישיון בתשלום שמעניק Signer |
run משיב 400 No signing certificate configured. | רישיון בתשלום, מצב Certified, ואין תעודה | הגדר את SigningCertificate, או חתום במצב Visual |
run משיב 400 The signing certificate expired on yyyy-MM-dd. | התעודה אינה בתוקף | החלף אותה; חתימות Visual ממשיכות לעבוד בינתיים |
| היומן אומר שהפלט "משתמש בתעודת ההדגמה המובנית", אך רישיון בתשלום מסרב לחתימות Certified | שורה זו נכתבת תמיד כאשר לא הוגדרה תעודה, לא משנה איזה רישיון | הגדר את SigningCertificate |
הווידג'ט נטען אך מציג Signing is not enabled on this server. | AddSignerWidget() לא נקרא, או שהbasePath אינו תואם למיקום שבו UseDoconut() מותקן | קרא AddSignerWidget(); תקן את basePath |
run משיב 400 The signature image must be a PNG., Signature image is not valid base64. או Signature image is too large. | UI מותאם שלח 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 דקות עבר, או שמחשב ברשת (web‑farm) אינו מכיל את ההעלאה | פתח את הקובץ שוב; בחווה, רשום את AddDoconutDistributedWidgets |
.docx חתום מציג ללא חתימה בכמה מציגים | פלט Word נושא חתימת חבילה של OOXML, שרבים מהמציגים אינם מציגים | חתום ל‑PDF, ברירת המחדל |
| קוראי PDF אומרים שהזהות של החותם אינה ידועה | הקורא אינו סומך על השורש של התעודה (תעודת ההדגמה לעולם אינה מהימנה) | השתמש בתעודה משורש שהקוראים שלך סומכים עליו |
| הווידג'ט נכשל כאשר הממשק נמצא במקור אחר | לנקודות הקצה אין תמיכת CORS | הגש את הממשק מאותו מקור, או הפוך‑פרוקסי לנתיבי Doconut |
| הנושא אינו מתיישם | הבוחר מכוון אל אלמנט בתוך ההרכבה | כוון ישירות אל ההרכבה: #host.dsw או #host |
האם דף זה היה מועיל?