افزونه Signer
امضای PDF و اسناد Word با امضای قابل مشاهده و مهر دیجیتال
افزونه Signer یک امضای قابل مشاهده روی سند قرار میدهد و بهصورت پیشفرض آن را با یک امضای دیجیتال مهر میزند که یک خواننده PDF میتواند آن را تأیید کند. این افزونه فایلهای PDF و Word (.docx) را امضا میکند. امضای قابل مشاهده همیشه یک تصویر PNG است: کشیدهشده، تایپشده یا توسط امضاکننده بارگذاری شده.
| سطح | زمانی که استفاده میکنید |
|---|---|
DocumentSigner (C#) | شما روی سرور امضا میکنید و مرورگری درگیر نیست |
ویجت تعبیهشده (doconutSigner.js) | میخواهید یک صفحه آماده بارگذاری، امضا و دانلود در صفحه خود داشته باشید |
نقاط انتهایی HTTP (?sign=open|run|download) | میخواهید رابط کاربری امضای خود را بر پایه یک قرارداد سرور مستند بسازید |
هر امضا یکبار، بر روی یک صفحه قرار میگیرد. نام امضاکننده، دلیل و مکان میتوانند همراه آن حرکت کنند.
نصب بسته
نصب آخرین نسخه پایدار افزونه Signer:
dotnet add package Doconut.NETStandard.Signerبرای قفل کردن افزونه به نسخهای که این مستندات توصیف میکند، نسخه را بهصورت جداگانه پاس دهید:
dotnet add package Doconut.NETStandard.Signer --version 26.10.0بسته Signer را با همان نسخهی Doconut.NETStandard نگه دارید. شناسه بسته Doconut.NETStandard.Signer است؛ .<version> فقط در نام فایل دانلود شدهی .nupkg ظاهر میشود.
فایل مجوز افزونه، Doconut.Viewer.Signer.lic، در همان پوشهای که Doconut.Viewer.lic قرار دارد قرار میگیرد؛ همراه با مجوز نمایشگر خوانده میشود.
ثبت افزونه
مانند هر افزونه 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 تنظیم میشود (امضای قابل مشاهده \u002B مهر دیجیتال)؛ 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; // \u0022.docx\u0022SignAsync به جای بازگشت، هنگام عدم موفقیت فراخوانی استثنا میاندازد:
| استثنا | پیام | زمان |
|---|---|---|
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 (پیشفرض) | امضای قابل مشاهده بههمراه یک مهر دیجیتال | تحت یک لایسنس پرداختشده لازم است | بله |
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 تا جایگزینی آن رد میشوند. امضاهای Visual تحت تأثیر قرار نمیگیرند.
- صادر شده برای امضای سند: استفاده از کلید با امضای دیجیتال یا عدم انکار، و استفادهٔ کلید گسترشیافته، اگر موجود باشد، که اجازهٔ امضای سند، حفاظت ایمیل یا احراز هویت مشتری را میدهد. گواهینامهای که برای چیز دیگری صادر شده باشد، مانند گواهینامهٔ سرور TLS، هنوز امضا میکند، اما بهعنوان هشدار لاگ میشود و خوانندگان PDF امضا را پرچم میزنند.
- توکنهای سختافزاری، کارتهای هوشمند، HSMها و فروشگاه گواهینامه ویندوز پشتیبانی نمیشوند. گواهینامه را همراه با کلید خصوصی و زنجیرهاش به یک PFX صادر کنید.
یک PFX از گواهینامه و کلید خصوصی آن ایجاد کنید با OpenSSL:
openssl pkcs12 -export -out signing.pfx -inkey private.key -in certificate.crt
# رمز عبور صادراتی که از شما درخواست میشود SigningCertificate.Password است.از فروشگاه گواهینامه ویندوز یک مورد صادر کنید: certmgr.msc را باز کنید و گواهینامه را پیدا کنید (آیکون آن زمانی که کلید خصوصی موجود باشد، یک کلید نشان میدهد). روی آن کلیک راست کنید، همه وظایف → صدور… را انتخاب کنید، بله، کلید خصوصی را صادر کنید را برگزینید، 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: ببینید تنظیم گواهی؛ برای نمایشی (دارای واترمارک) آن را null بگذارید
});
});AddSignerWidget() بدون آرگومان، ویجت را با تنظیمات پیشفرض فعال میکند. این بهتنهایی امکان امضا را نمیدهد: به AddPlugin<SignerPlugin>() نیاز دارد، یا AddDoconut() خطا میاندازد:
AddSignerWidget() was called but the Signer plugin is not registered. Add options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>() (the widget needs it), or remove the AddSignerWidget() call.بدون AddSignerWidget()، هر درخواست ?sign= پاسخ 404 میدهد. اسکریپت همچنان سرو میشود، بنابراین ویجت بارگذاری میشود و ناحیهٔ رهاسازی خود را میکشد، سپس در اولین درخواست خود Signing is not enabled on this server. را گزارش میکند.
جاسازی آن
UseDoconutResources() اسکریپت را در {ResourcesPath}/js/doconutSigner.js سرو میکند (پیشفرض /doconut-res/js/doconutSigner.js). این یک فایل تک، خودکفا بدون وابستگیها است:
<div id="host"></div>
<script src="/doconut-res/js/doconutSigner.js"></script>
<script>
const handle = Doconut.signer('#host', { basePath: '/doconut' });
</script>Doconut.signer(selectorOrElement, options) یک سلکتور CSS یا یک عنصر را میگیرد، اگر نقطه نصب پیدا نشود خطا میاندازد و یک دستگیره برمیگرداند.
امضاکننده یک فایل PDF یا فایل .docx بارگذاری میکند، یک امضا میسازد (Draw روی یک بوم، Type یک نام با فونت امضا، یا Image از یک PNG، JPG یا GIF)، آن را به صفحه میکشاند و اندازهاش را تغییر میدهد، سپس امضا میکند و نتیجه را دانلود میکند. ویجت همیشه امضا را بهصورت PNG ارسال میکند؛ تصویر بارگذاریشده در مرورگر به PNG تبدیل میشود که با ابعاد 520×160 سازگار است.
گزینهها
| گزینه | نوع | پیشفرض | یادداشتها |
|---|---|---|---|
basePath | string | '/doconut' | جایی که نقاط انتهایی ?sign= و تصاویر پیشنمایش سرو میشوند |
resPath | string | '/doconut-res' | رزرو شده؛ ویجت CSS خود را بستهبندی میکند |
maxUploadMb | number | 25 | فقط بررسی سمت کلاینت؛ بنابراین فایل بزرگتری سریعاً ناموفق میشود. حداکثر سرور MaxUploadMb در AddSignerWidget است |
maxSignatureKb | number | 512 | حداکثر سمت کلاینت برای حالت Image. آن را برابر با MaxSignatureImageKb سرور نگه دارید |
previewWidth | number | 560 | عرض پیکسل پیشنمایش صفحه |
licenseUrl | string | null | null | اعلان watermark دمو را به لینکی به این 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 | یک بار، هنگام سوار شدن (دوباره در reset() رخ نمیدهد) | — |
onSourceLoaded | فایل باز میشود و پیشنمایش آن نشان داده میشود | { file: { token, name, pages, ext } } |
onSigned | امضا موفق میشود | { downloadToken, downloadName, watermarked } |
onDownload | در هر کلیک دانلود | { downloadName, downloadToken } |
onError | یک مرحله باز کردن، امضا یا دانلود ناموفق میشود، یا فایل حالت تصویر بیش از حد بزرگ است | { 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 ندارد. UI و اسکریپت ویجت را از همان مبدا Doconut سرو کنید، یا هر دو مسیر /doconut (مسیر میانی و مسیر منابع) را تحت مبدا UI خود معکوس‑پروکسی کنید.
در محیط تولید
-
پلاگین را نصب کنید در کنار بستهٔ هسته، با همان نسخه:
dotnet add package Doconut.NETStandard.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 قرار دارد.
امضاکننده سند
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 نادیده گرفته میشود، و خروجی دارای واترمارک است.
درخواست امضا
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
}یک امضای قابل مشاهده یک بار قرار میگیرد، بهاضافهٔ فرادادهٔ اختیاری امضاکننده.
امضای قابل مشاهده و نوع امضا
public sealed record VisibleSignature(SignatureKind Kind, byte[] PngBytes)
{
public bool IsValid { get; } // PngBytes خالی نیست
}
public enum SignatureKind { Drawn, Typed, Image }PngBytes برای هر نوع یک PNG است. یک امضای کشیدهشده یا تایپشده شفاف است؛ یک تصویر بارگذاریشده شفافیت خود را حفظ میکند، بنابراین یک JPG مات همانطور که هست باقی میماند. Kind فقط یک نکته است.
مکانگذاری امضا
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 نرمالسازی میشوند.
حالت امضا و خروجی Word
public enum SignatureMode { Certified, Visual } // Certified پیشفرض است
public enum WordOutput { Pdf, Docx } // Pdf پیشفرض است; برای منابع PDF نادیده گرفته میشودنتیجهامضا
public sealed record SignResult(Stream Stream, string Extension);سند امضا شده بهصورت یک جریان قابل جستجو، و پسوند آن با نقطه (".pdf" یا ".docx").
گواهیامضا
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.
گزینههای ویجت امضاکننده
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 تهی به معنای گواهی دموی تحت مجوز موقت است، و امضاهای بصری فقط تحت یک مجوز پرداختشده فعال هستند.
عیبیابی
| علائم | دلیل | راهحل |
|---|---|---|
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 ثبت نشده است | درون AddDoconut() ، AddPlugin<SignerPlugin>() را اضافه کنید |
| خروجی دارای واترمارک است | مجوز موقت است (دمو/NFR) | از یک مجوز پرداختشده که Signer را اعطا میکند استفاده کنید |
run پاسخ میدهد 400 No signing certificate configured. | یک مجوز پرداختشده، حالت Certified، و بدون گواهی | SigningCertificate را پیکربندی کنید، یا در حالت Visual امضا کنید |
run پاسخ میدهد 400 The signing certificate expired on yyyy-MM-dd. | گواهی منقضی شده است | آن را تعویض کنید؛ امضاهای Visual در این بین کار میکنند |
| لاگ میگوید خروجی "از گواهی دموی داخلی استفاده میکند"، اما یک مجوز پرداختشده از امضاهای Certified جلوگیری میکند | این خط هر زمان که گواهی پیکربندی نشده باشد، صرفنظر از نوع مجوز، نوشته میشود | SigningCertificate را پیکربندی کنید |
ویجت بارگذاری میشود اما میگوید Signing is not enabled on this server. | AddSignerWidget() فراخوانی نشده است، یا basePath با جایی که UseDoconut() سوار شده است مطابقت ندارد | AddSignerWidget() را فراخوانی کنید؛ basePath را اصلاح کنید |
run پاسخ میدهد 400 The signature image must be a PNG.، Signature image is not valid base64. یا Signature image is too large. | یک UI سفارشی یک URL data:، یک JPG، یا بیش از MaxSignatureImageKb ارسال کرده است | یک PNG خالص base64 را درون محدودیت بفرستید |
open پاسخ میدهد 413 File is too large. | آپلود از MaxUploadMb فراتر میرود | MaxUploadMb را در AddSignerWidget بالا ببرید؛ maxUploadMb ویجت فقط یک بررسی سمت کلاینت است |
run یا download پاسخ میدهد 404 Upload expired — please re-open the file. | پنجرهٔ ۳۰ دقیقهای تمام شده است، یا یک گرهٔ وبفارم آپلود را ندارد | فایل را دوباره باز کنید؛ در یک فارم، AddDoconutDistributedWidgets را ثبت کنید |
یک .docx امضا شده در برخی نمایشگرها امضایی نشان نمیدهد | خروجی Word دارای امضای بسته OOXML است که بسیاری از نمایشگرها آن را نشان نمیدهند | به PDF امضا کنید، پیشفرض |
| خوانندگان PDF میگویند هویت امضاکننده ناشناخته است | خواننده ریشهٔ گواهی را اعتماد نمیکند (گواهی دموی هرگز مورد اعتماد نیست) | از گواهیای که از ریشهای که خوانندگان شما به آن اعتماد دارند استفاده کنید |
| ویجت هنگام اینکه UI در منبع دیگری باشد، شکست میخورد | نقطههای انتهایی پشتیبانی CORS ندارند | UI را از همان منبع سرو کنید، یا مسیرهای Doconut را بهصورت reverse‑proxy کنید |
| تم اعمال نمیشود | سلکتور به عنصری داخل mount هدف میگیرد | مستقیم به mount هدف بگیرید: #host.dsw یا #host |
آیا این صفحه مفید بود؟