תוסף חותם

חתום על מסמכי PDF ו‑Word עם חתימה נראית והחתמה דיגיטלית

תוסף החותם מציב חתימה נראית על מסמך ובברירת מחדל חותם אותו עם חתימה דיגיטלית שקריאת PDF יכולה לאמת. הוא חותם קבצי PDF ו‑Word (.docx). החתימה הנראית היא תמיד תמונת PNG: מצוירת, מוקלדת, או שהמשתמש מעלה אותה.

ממשקמתי להשתמש
DocumentSigner (C#)אתה חותם על השרת, ללא דפדפן מעורב
ווידג'ט משולב (doconutSigner.js)אתה רוצה מסך העלאה, חתימה והורדה מוכן לשימוש בדף שלך
נקודות קצה HTTP (?sign=open|run|download)אתה בונה ממשק חתימה משלך כנגד חוזה שרת מתועד

כל חתימה ממוקמת פעם אחת, בעמוד אחד. שם החותם, הסיבה והמיקום יכולים ללוות אותה.

התקנת החבילה

התקן את תוסף החותם היציב האחרון:

bash
dotnet add package Doconut.NET8.Signer

כדי לקבע את התוסף לגרסה שהדוקומנטציה מתארת, העבר את הגרסה בנפרד:

bash
dotnet add package Doconut.NET8.Signer --version 26.10.0

שמור את חבילת החותם באותה גרסה כמו Doconut.NET8. מזהה החבילה הוא Doconut.NET8.Signer; .<version> מופיע רק בשם הקובץ .nupkg שהורד.

קובץ הרישיון של התוסף, Doconut.Viewer.Signer.lic, נמצא באותו תיקייה כמו Doconut.Viewer.lic; הוא נקרא יחד עם רישיון הצופה.

פלטפורמות. התוסף פועל בכל מקום שבו Doconut.NET8 פועל: Windows ולינוקס מבוסס glibc על x64 (לא Alpine או הפצות אחרות מבוססות musl). בלינוקס, התקן את ספריית תצורת הגופנים לפני שהמסמך הראשון נפתח:

bash
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():

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
});

זה כל מה שהחזית של C# צריכה. הווידג'ט ונקודות הקצה HTTP שלו הם אפשרות נפרדת, AddSignerWidget() (ראה ווידג'ט משולב).

התוסף דורש רישיון שמעניק את היכולת Signer. ללא רישיון, AddDoconut() זורק שגיאה בעת ההפעלה, לפני שהאפליקציה מגישה בקשה:

text
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>().

csharp
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 (visible signature + digital seal); 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; ההגדרה הזאת מיועדת ל‑widget. העבר null תחת רישיון הדגמה, או במצב Visual.

SignResult מחזיק את המסמך החתום כזרם שניתן לחיפוש, בנוסף לExtension שלו (".pdf" או ".docx") כך שניתן לתת שם לקובץ. אתה הבעלים של הזרם: שחרר אותו כשסיימת.

חתימה ויזואלית מטביעת רק את התמונה ואינה דורשת אישור:

csharp
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:

csharp
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 זורק במקום להחזיר כאשר הקריאה אינה יכולה להצליח:

חריגההודעהמתי
InvalidOperationExceptionNo signing certificate configured.מצב Certified, רישיון בתשלום, ולא הועבר אישור
InvalidOperationExceptionThe signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd.מצב Certified עם אישור מחוץ לתקופת התוקף שלו
ArgumentExceptionThe sign request is invalid: the visible signature needs PNG bytes and the placement must be a normalized rectangle on a 1-based page.בתים ריקים של PNG, או מיקום שאינו תקף
NotSupportedExceptionThe 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. ספק או את הבייטים או נתיב, בנוסף לסיסמה:

csharp
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"],
        };
    });
});
csharp
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) בעת האתחול, וחתימות מוסמכות נדחות עד להחלפתה. חתימות ויזואליות אינן מושפעות.
  • הונפקה לחתימת מסמכים: שימוש במפתח עם חתימה דיגיטלית או אי‑הכחשה, ושימוש במפתח מורחב, אם קיים, המאפשר חתימת מסמכים, הגנת דוא״ל או אימות לקוח. תעודה שהונפקה למטרה אחרת, כגון תעודת שרת TLS, עדיין חותמת, אך היא נרשמת כהתראה והקוראים של PDF מסמנים את החתימה.
  • אסימוני חומרה, כרטיסים חכמים, HSMs וחנות התעודות של Windows אינם נתמכים. יצא את התעודה, עם המפתח הפרטי והשרשרת, ל‑PFX.

צור PFX מתעודה ומפתח פרטי עם OpenSSL:

bash
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 שוב עם המפתח הפרטי

אחרת המארח כותב שורה אחת ביומן כאשר הוא מתחיל. מידע כאשר התעודה מוכנה:

text
Doconut Signer: using certificate '{subject}' (valid until yyyy-MM-dd). Signatures are digitally sealed.

התראה (Warning) כאשר היא פגה, עדיין לא בתוקף, או לא הונפקה לחתימת מסמכים:

text
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.

ומידע כאשר לא הוגדרה תעודה:

text
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.

השורה האחרונה היא אותה עבור כל רישיון. ברישיון בתשלום תעודת ההדגמה לעולם לא משמשת: ללא תעודה, רק חתימות ויזואליות עובדות.

המעטפת של C# אינה נבדקת באתחול. התעודה שאתה מעביר ל‑SignAsync נקראת כאשר אתה חותם, ולכן נתיב או סיסמה שגויים יגרמו לכשל בקריאה.

וידג'ט משולב

הפעלת נקודות הקצה

נקודות הקצה של הוידג'ט ?sign=open|run|download הן כבויות כברירת מחדל. הפעל אותן ליד רישום התוסף:

csharp
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: ראה הגדרת Certificate; השאר אותו null עבור חתימה לדוגמה (עם סימן מים)
    });
});

AddSignerWidget() ללא ארגומנט מפעיל את הוידג'ט עם ברירות המחדל. הוא אינו מעניק חתימה בעצמו: הוא זקוק לAddPlugin<SignerPlugin>(), או שAddDoconut() זורק:

text
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). זהו קובץ יחיד, עצמאי וללא תלות:

html
<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.

אפשרויות

אפשרותסוגברירת מחדלהערות
basePathstring'/doconut'היכן נקודות הקצה של ?sign= ותמונות התצוגה המקדימה מוגשות
resPathstring'/doconut-res'שמורה; הוידג'ט כולל את ה‑CSS שלו
maxUploadMbnumber25בדיקה בצד הלקוח בלבד, ולכן קובץ גדול מדי נכשל מיידית. המגבלה בשרת היא MaxUploadMb בAddSignerWidget
maxSignatureKbnumber512מגבלה בצד הלקוח למצב Image. שמור אותה שווה למגבלת השרת MaxSignatureImageKb
previewWidthnumber560רוחב הפיקסלים של תצוגת העמוד
licenseUrlstring | nullnullהופך את הודעת סימן המים של ההדגמה לקישור ל‑URL זה
signatureModestring'certified'סוג החתימה הראשוני: 'certified' או 'visual'. כל ערך אחר הופך ל‑'certified'
showSignatureModeTogglebooleantrueמציג את האפשרות Digital signature / Visual only. עם false, הוידג'ט חותם עם signatureMode
wordOutputstring'pdf'פלט ראשוני למקורות .docx: 'pdf' או 'docx'. כל ערך אחר הופך ל‑'pdf'
showOutputFormatTogglebooleantrueמציג את האפשרות PDF / Word, רק למקורות .docx. עם false, הוידג'ט משתמש ב‑wordOutput
labelsobject{}עוקף כל תת‑קבוצה של המחרוזות באנגלית

הסתרת מתג אינה משביתת את הפונקציה; היא מקבעה את הערך. שני קונפיגורציות נפוצות:

javascript
// שני המתגים מוצגים, חתימה דיגיטלית כברירת המחדל: חותם מלא לשירות עצמי
Doconut.signer('#host', { basePath: '/doconut', licenseUrl: '/pricing' });
javascript
// חזותי בלבד, ללא מתג: חותמת פשוטה ללא הצעת חתימה דיגיטלית
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()מסיר את המאזינים, מרוקן את ההרכבה, וקופא את המופע
javascript
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'.

מפתחברירת מחדל באנגלית
dropPromptDrag & drop a PDF or Word file here
dropHintPDF or Word (.docx)
chooseFileChoose file
signatureHeadingYour signature
modeDraw / modeType / modeImageDraw / Type / Image
metaSummarySignature details (optional)
metaSignerName / metaReason / metaLocationSigner name / Reason / Location
signatureTypeSignature type
modeCertified / modeVisualDigital signature / Visual only
modeVisualNoteNo certificate — a visible mark only, not cryptographically verifiable.
outputFormatOutput format
outputPdf / outputWordPDF / Word (.docx)
signActionSign document
downloadDownload
demoNoticeDemo — signed with the Doconut demo certificate; output is watermarked.
signingNotEnabledSigning is not enabled on this server.
page / pages1 page / {n} pages

מפתחות נוספים מכסים את שלב ההצבה, את מסך השגיאה, את הטופס המקושר של הודעת ההדגמה (demoNoticePrefix, demoNoticeLink, demoNoticeSuffix) ואת ההודעות aria-live.

כאשר open או run משיבים 404 ללא שגיאת JSON, הווידג'ט מציג signingNotEnabled. שגיאת JSON מהשרת תמיד מנצחת, ולכן הודעות כגון העלאה שפג תוקפה נשארות גלויות.

עיצוב

הווידג'ט מוסיף את המחלקה dsw לאלמנט ההרכבה שלו וקורא את הצבעים, הרדיוס והגופנים שלו ממאפייני CSS מותאמים, כך שניתן לעצב אותו מבלי לגעת בפנים:

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, גופן ממשק מערכת, וגופן חתימה בכתב יד.

בניית חזית משלך

הווידג'ט הוא לקוח של חוזה HTTP זה. שלוש הנתיבים יושבים תחת הנתיב שבו UseDoconut() מותקן (בדרך כלל /doconut), והם משיבים 404 עד שAddSignerWidget() נקרא. שגיאות נושאות גוף JSON, { "error": "..." }, למעט כאשר הטבלה אומרת "רק סטטוס". ערך ?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:

json
{
  "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.kindDrawn, Typed או Image, ללא תלות ברישיות; כל דבר אחר הופך לDrawn. רמז בלבד: המטען הוא תמיד PNG
signature.payloadPNG 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 תווים
wordOutputpdf (ברירת מחדל) או docx; מתעלמים ממקורות PDF. כל דבר אחר הופך לpdf
modecertified (ברירת מחדל) או visual. כל דבר אחר הופך לcertified

downloadName עוקב אחרי הפלט: <source>-signed.pdf או <source>-signed.docx, ו‑download שולח את Content-Type המתאים.

המקור שהועלה והתוצאה החתומה נשמרים כל אחד למשך 30 דקות. לאחר מכן, run ו‑download משיבים 404 והקובץ חייב להיפתח שוב. כל הטוקנים הם GUIDs.

נתיבסטטוסמתיגוף
כל404הווידג'ט אינו מופעלרק סטטוס
כל405פועל שגוי (open ו‑run צריכים POST, download צריך GET)רק סטטוס
open400אינה העלאה מרובת חלקיםExpected a multipart file upload.
open400אין קובץ, או קובץ ריקNo file uploaded.
open400כל דבר שאינו .pdf או .docxSigning supports PDF and Word (.docx) files only.
open413ההעלאה חורגת מMaxUploadMbFile is too large.
run400הגוף אינו JSON תקף, או ריקMalformed request. / Empty request.
run400הטוקן חסר או אינו GUIDInvalid token.
run404ההעלאה פגה תוקף או מעולם לא נפתחהUpload expired — please re-open the file.
run400אין חתימה, או אין הצבהNo signature supplied. / No placement supplied.
run400המטען אינו base64, ריק, גדול מדי, או אינו PNGSignature image is not valid base64. / Signature image is empty. / Signature image is too large. / The signature image must be a PNG.
run400ההצבה מחוץ לעמודThe signature or its placement is invalid.
run400מצב מוסמך, רישיון בתשלום ואין תעודהNo signing certificate configured.
run400מצב מוסמך עם תעודה מחוץ לתקופת התוקףThe signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd.
open, run500העיבוד נכשלהודעה מסוננת
download400הטוקן חסר או אינו GUIDרק סטטוס
download404טוקן לא ידוע או פג תוקףרק סטטוס

סיבוב מלא עם fetch:

javascript
// 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, או לבצע reverse‑proxy לשני הנתיבים /doconut (נתיב האמצעי ונתיב המשאבים) תחת המקור של הממשק שלך.

בייצור

  1. התקן את התוסף לצד חבילת הליבה, באותה גרסה: dotnet add package Doconut.NET8.Signer.

  2. הוסף את קובץ הרישיון. שים את Doconut.Viewer.Signer.lic באותו תיקייה כמו Doconut.Viewer.lic.

  3. קבל את האישור שלך כ‑PFX עם המפתח הפרטי ושרשרת המנפיק, מרשות תעודות או מ‑PKI של הארגון שלך. כדי לנסות תחילה, השתמש ברישיון הדגמה (תעודת הדגמה מובנית, עם סימן מים) או ב‑PFX חתום עצמאית.

  4. קרא את האישור מההגדרות, כך ששינויו לעולם לא ידרוש שינוי קוד:

    json
    "DoconutSigner": { "PfxPath": "certs/your-certificate.pfx" }
    csharp
    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():

csharp
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

csharp
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

csharp
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

csharp
public sealed record VisibleSignature(SignatureKind Kind, byte[] PngBytes)
{
    public bool IsValid { get; }   // PngBytes אינו ריק
}

public enum SignatureKind { Drawn, Typed, Image }

PngBytes הוא PNG עבור כל סוג. חתימה מצוירת או מוקלדת היא שקופה; תמונה שהועלתה שומרת על השקיפות שהייתה לה, ולכן JPG אטום נשאר אטום. Kind הוא רק רמז.

SignaturePlacement

csharp
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

csharp
public enum SignatureMode { Certified, Visual }   // Certified הוא ברירת המחדל
public enum WordOutput { Pdf, Docx }              // Pdf הוא ברירת המחדל; מתעלם ממקורות PDF

SignResult

csharp
public sealed record SignResult(Stream Stream, string Extension);

המסמך החתום כזרם שניתן לחיפוש, והרחבה שלו עם הנקודה (".pdf" או ".docx").

SigningCertificate

csharp
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

csharp
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.ממשק משתמש מותאם שלח 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הגש את הממשק מאותו מקור, או הפוך‑פרוקסי לנתיבי Doconut
הנושא אינו מתיישםהבורר מכוון אל אלמנט בתוך ההרכבהכוון ישירות להרכבה: #host.dsw או #host

האם דף זה היה מועיל?