افزونه Signer

امضای اسناد PDF و Word با یک امضای قابل مشاهده و مهر دیجیتال

افزونه Signer یک امضای قابل مشاهده روی سند قرار می‌دهد و به‌طور پیش‌فرض آن را با یک امضای دیجیتال مهر می‌کند که یک خواننده PDF می‌تواند آن را تأیید کند. این افزونه فایل‌های PDF و Word (.docx) را امضا می‌کند. امضای قابل مشاهده همیشه یک تصویر PNG است: کشیده‌شده، تایپ‌شده یا توسط امضاکننده بارگذاری شده.

سطحکی استفاده شود
DocumentSigner (C#)شما در سرور امضا می‌کنید، بدون درگیر شدن مرورگر
ویجت تعبیه‌شده (doconutSigner.js)می‌خواهید یک صفحه آماده بارگذاری، امضا و دانلود در صفحه خود داشته باشید
نقاط انتهایی HTTP (?sign=open|run|download)رابط کاربری امضای خود را بر پایه قرارداد مستند سرور می‌سازید

هر امضا یک‌بار، روی یک صفحه قرار می‌گیرد. نام امضاکننده، دلیل و مکان می‌توانند همراه آن حرکت کنند.

نصب بسته

آخرین نسخه پایدار افزونه Signer را نصب کنید:

bash
dotnet add package Doconut.NET6.Signer

برای قفل کردن افزونه به نسخه‌ای که این مستندات توصیف می‌کند، نسخه را به‌صورت جداگانه پاس دهید:

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

بسته Signer را با همان نسخه‌ای که Doconut.NET6 دارد نگه دارید. شناسه بسته Doconut.NET6.Signer است؛ .<version> فقط در نام فایل دانلود شده .nupkg ظاهر می‌شود.

فایل مجوز افزونه، Doconut.Viewer.Signer.lic، در همان پوشه‌ای که Doconut.Viewer.lic قرار دارد قرار می‌گیرد؛ همراه با مجوز نمایشگر خوانده می‌شود.

پلتفرم‌ها. افزونه در هر جایی که Doconut.NET6 اجرا می‌شود کار می‌کند: ویندوز و لینوکس مبتنی بر 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 آن یک گزینهٔ جداگانهٔ opt‑in هستند، 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 تنظیم می‌شود (امضای قابل مشاهده + مهر دیجیتال)؛ 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") تا بتوانید نام فایل را تعیین کنید. شما مالک جریان هستید: پس از اتمام آن را آزاد (dispose) کنید.

یک امضای Visual فقط تصویر را مهر می‌زند و نیازی به گواهی ندارد:

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 (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 پاس دهید. یا بایت‌ها یا مسیر را به‌همراه رمز عبور فراهم کنید:

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 بتوانند آن را حمل کنند.
  • رمز عبور صحیح.
  • درون پنجرهٔ اعتبار آن. گواهی منقضی‌شده یا هنوز معتبر نیست، برنامه را متوقف نمی‌کند: به‌عنوان هشدار در زمان راه‌اندازی لاگ می‌شود و امضاهای Certified تا جایگزین شدن رد می‌شوند. امضاهای بصری تحت تأثیر قرار نمی‌گیرند.
  • صادر شده برای امضای سند: استفاده از کلید با امضای دیجیتال یا عدم انکار، و استفادهٔ کلید گسترش‌یافته، اگر موجود باشد، که اجازهٔ امضای سند، حفاظت ایمیل یا احراز هویت مشتری را می‌دهد. گواهی‌ای که برای چیز دیگری صادر شده است، مانند گواهی سرور TLS، هنوز امضا می‌کند، اما به‌عنوان هشدار لاگ می‌شود و خوانندگان PDF امضا را علامت می‌زنند.
  • توکن‌های سخت‌افزاری، کارت‌های هوشمند، HSMها و فروشگاه گواهی ویندوز پشتیبانی نمی‌شوند. گواهی را همراه با کلید خصوصی و زنجیره‌اش به یک PFX استخراج کنید.

یک PFX از گواهی و کلید خصوصی آن ایجاد کنید با OpenSSL:

bash
openssl pkcs12 -export -out signing.pfx -inkey private.key -in certificate.crt
# رمز عبور صادراتی که از شما درخواست می‌شود SigningCertificate.Password است.

یک مورد را از فروشگاه گواهی ویندوز استخراج کنید: 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.

یک هشدار زمانی که منقضی شده، هنوز معتبر نیست، یا برای امضای سند صادر نشده باشد:

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.

آن خط آخر تحت هر مجوز یکسان است. تحت یک مجوز پرداختی گواهی نمایشی هرگز استفاده نمی‌شود: بدون گواهی، فقط امضاهای Visual کار می‌کنند.

لایهٔ C# در زمان راه‌اندازی بررسی نمی‌شود. گواهی‌ای که به SignAsync می‌سپارید هنگام امضا خوانده می‌شود، بنابراین مسیر یا رمز عبور اشتباه باعث شکست آن فراخوانی می‌شود.

ویجت Drop‑in

فعال‌سازی نقاط انتهایی

نقاط انتهایی ?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 یا یک عنصر می‌گیرد، اگر mount یافت نشود خطا می‌اندازد و یک handle برمی‌گرداند.

امضاکننده یک فایل 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گزینه امضای دیجیتال / فقط بصری را نشان می‌دهد. با 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یک بار، هنگام mount (دوباره در 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، یک قلم UI سیستمی، و یک قلم امضای خوشنویسی.

ساخت فرانت‌اند خودتان

ویجت یک کلاینت برای این قرارداد HTTP است. هر سه مسیر زیر مسیری که UseDoconut() سوار شده است (معمولاً /doconut) قرار دارند و تا زمانی که AddSignerWidget() فراخوانی شود، به 404 پاسخ می‌دهند. خطاها یک بدنهٔ 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.payloadیک PNG خالص base64، بدون پیشوند data:. باید یک PNG واقعی باشد و پس از رمزگشایی بزرگتر از MaxSignatureImageKb نباشد
placement.pageمبتنی بر ۱
placement.x / y / w / hنرمال‌سازی 0..1 از گوشهٔ بالا‑چپ، با x + w ≤ 1 و y + h ≤ 1
meta.signerName / reason / locationاختیاری. هر کدام برش می‌شوند، مقدار خالی حذف می‌شود، و هر کدام به ۲۵۶ کاراکتر محدود می‌شوند
wordOutputpdf (پیش‌فرض) یا docx؛ برای منابع PDF نادیده گرفته می‌شود. هر چیز دیگر به pdf تبدیل می‌شود
modecertified (پیش‌فرض) یا visual. هر چیز دیگر به certified تبدیل می‌شود

downloadName خروجی را دنبال می‌کند: <source>-signed.pdf یا <source>-signed.docx، و download Content-Type مطابقت را ارسال می‌کند.

منبع بارگذاری‌شده و نتیجهٔ امضا شده هر کدام به مدت ۳۰ دقیقه نگهداری می‌شوند. پس از آن، run و download به 404 پاسخ می‌دهند و فایل باید دوباره باز شود. همهٔ توکن‌ها GUID هستند.

مسیروضعیتزمانبدنه
any404ویجت فعال نیستفقط وضعیت
any405فعل اشتباه (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توکن موجود نیست یا GUID نیستInvalid token.
run404بارگذاری منقضی شده یا هرگز باز نشده استUpload expired — please re-open the file.
run400امضایی وجود ندارد یا قرارگیری نیستNo signature supplied. / No placement supplied.
run400بارگذاری base64 نیست، خالی است، بیش از حد بزرگ است یا PNG نیستSignature 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 سرو کنید، یا هر دو مسیر /doconut (مسیر میدل‌ویر و مسیر منابع) را تحت منبع UI خود به‌صورت reverse‑proxy کنید.

در محیط تولید

  1. پلاگین را نصب کنید در کنار بستهٔ هسته، با همان نسخه: dotnet add package Doconut.NET6.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) می‌پذیرد، تا جایی که می‌دانیم، با کلید خصوصی روی توکن سخت‌افزاری یا 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;                   // حداقل ۳۲ بایت، یکسان در هر گره
    // store.Ttl = TimeSpan.FromMinutes(30);   // مدت زمانی که یک بارگذاری نگه داشته می‌شود (پیش‌فرض)
});
  • یک سرور تک‌نقشه به چیزی نیاز ندارد: بدون این فراخوانی، فروشگاه در‑حافظه استفاده می‌شود.
  • بارگذاری‌ها و نتایج در حالت استراحت بر روی اشتراک رمزگذاری می‌شوند (AES‑256، encrypt‑then‑MAC)، و هر فایل به توکن خود متصل است، به‌طوری که یک توکن هرگز نمی‌تواند فایل توکن دیگر را بخواند.
  • FarmKey باید حداقل ۳۲ بایت باشد و در هر گره یکسان باشد. آن را از یک مخزن اسرار بارگذاری کنید؛ هرگز به‌صورت ثابت کدنویسی نکنید. ثبت‌نام یک ArgumentException را زمانی که RootPath موجود نیست یا FarmKey کوتاه‌تر از ۳۲ بایت است، پرتاب می‌کند.
  • 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 بر پایه یک است؛ 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 را برمی‌گرداند تا فراخوانی‌ها زنجیره‌ای شوند. یک 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()
خروجی دارای واترمارک استمجوز موقت است (دمو/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 داخل cap ارسال کنید
open پاسخ می‌دهد 413 File is too large.بارگذاری بیش از MaxUploadMb استدر AddSignerWidget MaxUploadMb را بالا ببرید؛ maxUploadMb ویجت فقط یک بررسی سمت کلاینت است
run یا download پاسخ می‌دهد 404 Upload expired — please re-open the file.پنجرهٔ ۳۰ دقیقه‌ای تمام شده است، یا یک گرهٔ وب‌فارم بارگذاری را نداردفایل را دوباره باز کنید؛ در یک فارم، AddDoconutDistributedWidgets را ثبت کنید
یک .docx امضا شده در برخی نمایشگرها امضا را نشان نمی‌دهدخروجی Word شامل امضای بستهٔ OOXML است که بسیاری از نمایشگرها نشان نمی‌دهندبه PDF امضا کنید، که پیش‌فرض است
خوانندگان PDF می‌گویند هویت امضاکننده ناشناخته استخواننده ریشهٔ گواهی را اعتماد نمی‌کند (گواهی دموی هرگز مورد اعتماد نیست)از گواهی‌ای از ریشه‌ای که خوانندگان شما به آن اعتماد دارند استفاده کنید
ویجت وقتی UI در منبع دیگری است شکست می‌خوردنقطه‌های انتهایی CORS ندارندUI را از همان منبع سرو کنید، یا مسیرهای Doconut را reverse-proxy کنید
تم اعمال نمی‌شودانتخابگر به عنصری داخل mount هدف می‌گیردمستقیم به خود mount هدف بگیرید: #host.dsw یا #host

آیا این صفحه مفید بود؟