افزونه Signer
امضای اسناد PDF و Word با یک امضای قابل مشاهده و مهر دیجیتال
افزونه Signer یک امضای قابل مشاهده روی سند قرار میدهد و بهطور پیشفرض آن را با یک امضای دیجیتال مهر میکند که یک خواننده PDF میتواند آن را تأیید کند. این افزونه فایلهای PDF و Word (.docx) را امضا میکند. امضای قابل مشاهده همیشه یک تصویر PNG است: کشیدهشده، تایپشده یا توسط امضاکننده بارگذاری شده.
| سطح | کی استفاده شود |
|---|---|
DocumentSigner (C#) | شما در سرور امضا میکنید، بدون درگیر شدن مرورگر |
ویجت تعبیهشده (doconutSigner.js) | میخواهید یک صفحه آماده بارگذاری، امضا و دانلود در صفحه خود داشته باشید |
نقاط انتهایی HTTP (?sign=open|run|download) | رابط کاربری امضای خود را بر پایه قرارداد مستند سرور میسازید |
هر امضا یکبار، روی یک صفحه قرار میگیرد. نام امضاکننده، دلیل و مکان میتوانند همراه آن حرکت کنند.
نصب بسته
آخرین نسخه پایدار افزونه Signer را نصب کنید:
dotnet add package Doconut.NET6.Signerبرای قفل کردن افزونه به نسخهای که این مستندات توصیف میکند، نسخه را بهصورت جداگانه پاس دهید:
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). در لینوکس، قبل از باز شدن اولین سند کتابخانه پیکربندی فونت را نصب کنید:
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 آن یک گزینهٔ جداگانهٔ opt‑in هستند، 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") تا بتوانید نام فایل را تعیین کنید. شما مالک جریان هستید: پس از اتمام آن را آزاد (dispose) کنید.
یک امضای 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 بتوانند آن را حمل کنند. - رمز عبور صحیح.
- درون پنجرهٔ اعتبار آن. گواهی منقضیشده یا هنوز معتبر نیست، برنامه را متوقف نمیکند: بهعنوان هشدار در زمان راهاندازی لاگ میشود و امضاهای Certified تا جایگزین شدن رد میشوند. امضاهای بصری تحت تأثیر قرار نمیگیرند.
- صادر شده برای امضای سند: استفاده از کلید با امضای دیجیتال یا عدم انکار، و استفادهٔ کلید گسترشیافته، اگر موجود باشد، که اجازهٔ امضای سند، حفاظت ایمیل یا احراز هویت مشتری را میدهد. گواهیای که برای چیز دیگری صادر شده است، مانند گواهی سرور TLS، هنوز امضا میکند، اما بهعنوان هشدار لاگ میشود و خوانندگان PDF امضا را علامت میزنند.
- توکنهای سختافزاری، کارتهای هوشمند، HSMها و فروشگاه گواهی ویندوز پشتیبانی نمیشوند. گواهی را همراه با کلید خصوصی و زنجیرهاش به یک PFX استخراج کنید.
یک PFX از گواهی و کلید خصوصی آن ایجاد کنید با OpenSSL:
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 را دوباره همراه با کلید خصوصی استخراج کنید |
در غیر این صورت میزبان یک خط به لاگ مینویسد وقتی شروع میکند. اطلاعات زمانی که گواهی آماده است:
Doconut Signer: using certificate '{subject}' (valid until yyyy-MM-dd). Signatures are digitally sealed.یک هشدار زمانی که منقضی شده، هنوز معتبر نیست، یا برای امضای سند صادر نشده باشد:
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.و اطلاعات زمانی که هیچ گواهیای پیکربندی نشده باشد:
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: به تنظیمات Certificate مراجعه کنید؛ برای امضای نمایشی (آبنشاندار) آن را 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 یا یک عنصر میگیرد، اگر mount یافت نشود خطا میاندازد و یک handle برمیگرداند.
امضاکننده یک فایل 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 | اعلان واترمارک دموی را به لینکی به این URL تبدیل میکند |
signatureMode | string | 'certified' | نوع امضای اولیه: 'certified' یا 'visual'. هر مقدار دیگر به 'certified' تبدیل میشود |
showSignatureModeToggle | boolean | true | گزینه امضای دیجیتال / فقط بصری را نشان میدهد. با false، ویجت با signatureMode امضا میکند |
wordOutput | string | 'pdf' | خروجی اولیه برای منابع .docx: 'pdf' یا 'docx'. هر مقدار دیگر به 'pdf' تبدیل میشود |
showOutputFormatToggle | boolean | true | گزینه PDF / Word را نشان میدهد، فقط برای منابع .docx. با false، ویجت از wordOutput استفاده میکند |
labels | object | {} | هر زیرمجموعهای از رشتههای انگلیسی را بازنویسی میکند |
پنهان کردن یک کلید، ویژگی را غیرفعال نمیکند؛ مقدار را ثابت میکند. دو پیکربندی رایج:
// هر دو سوئیچ نمایش داده میشوند، امضای دیجیتال بهصورت پیشفرض: یک امضاکننده کامل خودخدمات
Doconut.signer('#host', { basePath: '/doconut', licenseUrl: '/pricing' });// فقط بصری، بدون سوئیچ: یک مهر ساده بدون ارائه امضای دیجیتال
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() | شنوندهها را حذف میکند، سوارشده را خالی میکند و نمونه را منجمد میسازد. |
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) قرار دارند و تا زمانی که 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:
{
"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 | مبتنی بر ۱ |
placement.x / y / w / h | نرمالسازی 0..1 از گوشهٔ بالا‑چپ، با x + w ≤ 1 و y + h ≤ 1 |
meta.signerName / reason / location | اختیاری. هر کدام برش میشوند، مقدار خالی حذف میشود، و هر کدام به ۲۵۶ کاراکتر محدود میشوند |
wordOutput | pdf (پیشفرض) یا docx؛ برای منابع PDF نادیده گرفته میشود. هر چیز دیگر به pdf تبدیل میشود |
mode | certified (پیشفرض) یا visual. هر چیز دیگر به certified تبدیل میشود |
downloadName خروجی را دنبال میکند: <source>-signed.pdf یا <source>-signed.docx، و download Content-Type مطابقت را ارسال میکند.
منبع بارگذاریشده و نتیجهٔ امضا شده هر کدام به مدت ۳۰ دقیقه نگهداری میشوند. پس از آن، run و download به 404 پاسخ میدهند و فایل باید دوباره باز شود. همهٔ توکنها GUID هستند.
| مسیر | وضعیت | زمان | بدنه |
|---|---|---|---|
| any | 404 | ویجت فعال نیست | فقط وضعیت |
| any | 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 (مسیر میدلویر و مسیر منابع) را تحت منبع UI خود بهصورت reverse‑proxy کنید.
در محیط تولید
-
پلاگین را نصب کنید در کنار بستهٔ هسته، با همان نسخه:
dotnet add package Doconut.NET6.Signer. -
فایل مجوز را اضافه کنید.
Doconut.Viewer.Signer.licرا در همان پوشهای کهDoconut.Viewer.licقرار دارد بگذارید. -
گواهی خود را بهصورت PFX همراه با کلید خصوصی و زنجیرهٔ صادرکننده، از یک مرجع صدور گواهی یا زیرساخت PKI سازمان خود دریافت کنید. برای آزمایش ابتدا از یک مجوز نمایشی (گواهی نمایشی داخلی، با واترمارک) یا یک PFX خودامضا استفاده کنید.
-
گواهی را از تنظیمات بخوانید، بهطوری که تغییر آن نیازی به تغییر کد نداشته باشد:
json"DoconutSigner": { "PfxPath": "certs/your-certificate.pfx" }csharpvar 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) یا یک مخزن در محیط تولید. -
لاگ راهاندازی را بررسی کنید. باید
using certificate '{subject}' (valid until …). Signatures are digitally sealed.را بخواند؛ یک هشدار به این معناست که گواهی منقضی شده، هنوز معتبر نیست، یا برای امضای سند صادر نشده است.
اعتماد به خوانندگان PDF. یک خواننده امضا را بهعنوان معتبر نشان میدهد وقتی ریشهٔ گواهی را مورد اعتماد داشته باشد. با PKI سازمان شما، این برای هر ماشینی که ریشهٔ شما را میپذیرد صادق است، که معمولاً تمام ماشینهای داخل سازمان است. گواهیهایی که Adobe بر روی هر ماشینی (فهرست اعتماد تأیید شدهٔ Adobe) میپذیرد، تا جایی که میدانیم، با کلید خصوصی روی توکن سختافزاری یا 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; // حداقل ۳۲ بایت، یکسان در هر گره
// 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
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 بر پایه یک است؛ X، Y، W و H از گوشهٔ بالا‑چپ به صورت 0..1 نرمالسازی میشوند.
SignatureMode and WordOutput
public enum SignatureMode { Certified, Visual } // Certified پیشفرض است
public enum WordOutput { Pdf, Docx } // Pdf پیشفرض است؛ برای منابع PDF نادیده گرفته میشودSignResult
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 را برمیگرداند تا فراخوانیها زنجیرهای شوند. یک 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 |
آیا این صفحه مفید بود؟