پلاگین امضاکننده
امضای اسناد PDF و Word با یک امضای قابل مشاهده و یک مهر دیجیتال
پلاگین Signer یک امضای قابل مشاهده بر روی سند قرار میدهد و بهصورت پیشفرض آن را با یک امضای دیجیتال مهر میزند که یک خواننده PDF میتواند آن را تأیید کند. این پلاگین فایلهای PDF و Word (.docx) را امضا میکند. امضای قابل مشاهده همیشه یک تصویر PNG است: کشیدهشده، تایپشده یا توسط امضاکننده بارگذاری شده.
| سطح | زمان استفاده |
|---|---|
DocumentSigner (C#) | شما در سرور امضا میکنید، بدون درگیر شدن مرورگر |
Drop-in widget (doconutSigner.js) | میخواهید یک صفحه بارگذاری، امضا و دانلود آماده در صفحه خود داشته باشید |
HTTP endpoints (?sign=open|run|download) | شما رابط کاربری امضای خود را بر پایه یک قرارداد سرور مستند میسازید |
هر امضا یک بار، بر روی یک صفحه قرار میگیرد. نام امضاکننده، دلیل و مکان میتوانند همراه آن انتقال یابند.
نصب بسته
پلاگین Signer پایدار آخرین نسخه را نصب کنید:
dotnet add package Doconut.NET8.Signerبرای قفل کردن پلاگین به نسخهای که این مستندات توصیف میکند، نسخه را بهصورت جداگانه پاس دهید:
dotnet add package Doconut.NET8.Signer --version 26.10.0پکیج Signer را با همان نسخهٔ Doconut.NET8 نگه دارید. شناسهٔ بسته Doconut.NET8.Signer است؛ .<version> فقط در نام فایل دانلود شدهٔ .nupkg ظاهر میشود.
فایل مجوز پلاگین، Doconut.Viewer.Signer.lic، در همان پوشهای که Doconut.Viewer.lic قرار دارد قرار میگیرد؛ همراه با مجوز ویور خوانده میشود.
پلتفرمها. پلاگین در هر جایی که Doconut.NET8 اجرا میشود اجرا میشود: ویندوز و لینوکس مبتنی بر glibc بر روی x64 (نه Alpine یا توزیعهای دیگر مبتنی بر musl). در لینوکس، قبل از باز شدن اولین سند کتابخانهٔ پیکربندی فونت را نصب کنید:
apt-get update && apt-get install -y libfontconfig1در توزیعهای RHEL، Fedora و مشابه، بسته fontconfig است. بدون آن، باز کردن سند با The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation. شکست میخورد.
ثبت پلاگین
مانند هر پلاگین Doconut، Signer با AddPlugin<TPlugin>() داخل AddDoconut() ثبت میشود:
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
});این تمام آنچه فاساد C# نیاز دارد است. ویجت و نقاط انتهایی HTTP آن یک انتخاب جداگانه، AddSignerWidget() است (به ویجت Drop‑in مراجعه کنید).
پلاگین به مجوزی نیاز دارد که قابلیت 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 را تحت یک لایسنس دمو یا در حالت تصویری پاس دهید.
SignResult سند امضا شده را بهعنوان یک جریان قابل جستجو نگه میدارد، بههمراه Extension آن (".pdf" یا ".docx") تا بتوانید نام فایل را تعیین کنید. شما مالک جریان هستید: هنگام اتمام آن را آزاد کنید.
یک امضای تصویری فقط تصویر را مهر میزند و نیازی به گواهی ندارد:
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. | حالت معتبر، لایسنس پولی و بدون گواهی پاس شده |
InvalidOperationException | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. | حالت معتبر با گواهی خارج از بازهٔ اعتبار |
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 | فقط امضای قابل مشاهده | هرگز لازم نیست | خیر: این یک تصویر است |
از معتبر استفاده کنید وقتی که امضا باید قابل اثبات باشد: تأییدها، قراردادها، هر چیزی که یک تأییدکننده برای بررسی هویت و یکپارچگی نیاز دارد. از تصویری استفاده کنید وقتی فقط به ظاهر امضا نیاز دارید یا گواهی ندارید. یک لایسنس موقت به هر دو واترمارک میزند.
مهرهای 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 را باز کنید و گواهی را پیدا کنید (آیکون آن زمانی که کلید خصوصی موجود باشد، یک کلید نشان میدهد). روی آن کلیک راست کنید، تمام وظایف → خروجی… را انتخاب کنید، بله، کلید خصوصی را صادر کنید را انتخاب کنید، تبادل اطلاعات شخصی – 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 راهاندازی؛ برای demo (watermarked) امضا آن را 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 | اعلان watermark دموی را به یک لینک به این URL تبدیل میکند |
signatureMode | string | 'certified' | نوع اولیه امضا: 'certified' یا 'visual'. هر مقدار دیگر به 'certified' تبدیل میشود |
showSignatureModeToggle | boolean | true | گزینه Digital signature / Visual only را نشان میدهد. با false، ویجت با signatureMode امضا میکند |
wordOutput | string | 'pdf' | خروجی اولیه برای منابع .docx: 'pdf' یا 'docx'. هر مقدار دیگر به 'pdf' تبدیل میشود |
showOutputFormatToggle | boolean | true | گزینه PDF / Word را نشان میدهد، فقط برای منابع .docx. با false، ویجت از wordOutput استفاده میکند |
labels | object | {} | هر زیرمجموعهای از رشتههای انگلیسی را بازنویسی میکند |
پنهان کردن یک سوئیچ ویژگی را غیرفعال نمیکند؛ مقدار را ثابت میکند. دو پیکربندی رایج:
// هر دو سوئیچ نشان داده میشوند، امضای دیجیتال بهصورت پیشفرض: یک امضاکننده کامل خودخدمت
Doconut.signer('#host', { basePath: '/doconut', licenseUrl: '/pricing' });// فقط بصری، بدون سوئیچ: یک مهر ساده بدون ارائه امضای دیجیتال
Doconut.signer('#host', {
basePath: '/doconut',
signatureMode: 'visual',
showSignatureModeToggle: false
});بازگشتها
| بازگشت | زمان اجرا | بار |
|---|---|---|
onReady | یکبار، هنگام 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 (چندبخشی، یک فایل) | یک PDF یا .docx را بارگذاری کنید و برای پیشنمایش باز کنید | 200 — { token, name, pages, ext } |
POST ?sign=run (بدنه JSON) | فایل بارگذاریشده را امضا کنید | 200 — { downloadToken, downloadName, watermarked } |
GET ?sign=download&token=<downloadToken> | فایل امضاشده را بهصورت جریان (stream) ارائه دهید | 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 هستند.
| مسیر | وضعیت | زمان | بدنه |
|---|---|---|---|
| هرکدام | 404 | ویجت فعال نیست | فقط وضعیت |
| هرکدام | 405 | فعل نادرست (open و run به POST نیاز دارند، download به GET نیاز دارد) | فقط وضعیت |
open | 400 | بارگذاری چندبخشی نیست | Expected a multipart file upload. |
open | 400 | فایل وجود ندارد یا خالی است | No file uploaded. |
open | 400 | هر چیزی به جز .pdf یا .docx | Signing supports PDF and Word (.docx) files only. |
open | 413 | بارگذاری از MaxUploadMb فراتر میرود | File is too large. |
run | 400 | بدنه JSON معتبر نیست یا خالی است | Malformed request. / Empty request. |
run | 400 | توکن موجود نیست یا GUID نیست | Invalid token. |
run | 404 | بارگذاری منقضی شده یا هرگز باز نشده است | Upload expired — please re-open the file. |
run | 400 | امضا وجود ندارد یا قرارگیری نیست | No signature supplied. / No placement supplied. |
run | 400 | بارگذاری base64 نیست، خالی است، خیلی بزرگ است یا PNG نیست | Signature image is not valid base64. / Signature image is empty. / Signature image is too large. / The signature image must be a PNG. |
run | 400 | قرارگیری خارج از صفحه است | The signature or its placement is invalid. |
run | 400 | حالت گواهیشده، لایسنس پرداختشده و بدون گواهی | No signing certificate configured. |
run | 400 | حالت گواهیشده با گواهی خارج از بازهٔ اعتبار | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. |
open، run | 500 | پردازش ناموفق بود | پیام پاکسازیشده |
download | 400 | توکن موجود نیست یا GUID نیست | فقط وضعیت |
download | 404 | توکن ناشناخته یا منقضی شده | فقط وضعیت |
یک مسیر کامل با fetch:
// file: فایل برای امضا; pngBase64: امضا به صورت یک PNG خالص base64، بدون پیشوند data:,
// به عنوان مثال canvas.toDataURL('image/png').split(',')[1].
async function signFile(file, pngBase64) {
const base = '/doconut';
// 1. open: بارگذاری فایل
const form = new FormData();
form.append('file', file, file.name);
const opened = await (await fetch(base + '?sign=open', { method: 'POST', body: form })).json();
// 2. run: امضا کردن
const signed = await (await fetch(base + '?sign=run', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
token: opened.token,
signature: { kind: 'Drawn', payload: pngBase64 },
placement: { page: 1, x: 0.58, y: 0.80, w: 0.32, h: 0.12 },
meta: { signerName: 'Ada Lovelace', reason: 'I approve', location: 'London, UK' },
wordOutput: 'pdf',
mode: 'certified'
})
})).json();
// 3. download: دریافت فایل امضا شده
const blob = await (await fetch(base + '?sign=download&token=' + encodeURIComponent(signed.downloadToken))).blob();
const link = document.createElement('a');
link.href = URL.createObjectURL(blob);
link.download = signed.downloadName;
link.click();
URL.revokeObjectURL(link.href);
}نقطههای انتهایی same-origin هستند: این نسخه پشتیبانی CORS ندارد. UI و اسکریپت ویجت را از همان منبع Doconut سرو کنید، یا هر دو مسیر /doconut را (مسیر میانیافزار و مسیر منابع) تحت منبع UI خود معکوس‑پروکسی کنید.
در محیط تولید
-
افزونه را در کنار بستهٔ هسته، با همان نسخه نصب کنید:
dotnet add package Doconut.NET8.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باید حداقل ۳۲ بایت باشد و در هر گره یکسان باشد. آن را از یک مخزن اسرار بارگذاری کنید؛ هرگز بهصورت ثابت کد نکنید. ثبتنام هنگام عدم وجودRootPathیا کوتاهتر بودنFarmKeyاز ۳۲ بایت، یکArgumentExceptionرا پرتاب میکند.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 تهی به معنی گواهی دموی تحت مجوز موقت است، و امضاهای بصری فقط تحت یک مجوز پرداختی.
عیبیابی
| علائم | دلیل | راهحل |
|---|---|---|
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. | گواهی منقضی شده است | آن را جایگزین کنید؛ امضاهای بصری در این میان کار میکنند |
| لاگ میگوید خروجی «از گواهی دموی داخلی استفاده میکند»، اما یک مجوز پرداختی امضاهای 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 است | در AddSignerWidget MaxUploadMb را افزایش دهید؛ maxUploadMb ویجت فقط یک بررسی سمت کلاینت است |
run یا download پاسخ میدهد 404 Upload expired — please re-open the file. | پنجرهٔ ۳۰ دقیقهای تمام شده است، یا یک گرهٔ وبفارم آپلود را ندارد | فایل را دوباره باز کنید؛ در یک فارم، AddDoconutDistributedWidgets را ثبت کنید |
یک .docx امضا شده در برخی نمایشگرها امضایی نشان نمیدهد | خروجی Word شامل امضای بستهٔ OOXML است، که بسیاری از نمایشگرها آن را نشان نمیدهند | به PDF امضا کنید، پیشفرض |
| خوانندگان PDF میگویند هویت امضا کننده ناشناخته است | خواننده ریشهٔ گواهی را اعتماد نمیکند (گواهی دموی هرگز مورد اعتماد نیست) | از یک گواهی از ریشهای که خوانندگان شما به آن اعتماد دارند استفاده کنید |
| ویجت وقتی UI در منبع دیگری است شکست میخورد | نقطههای انتهایی پشتیبانی CORS ندارند | UI را از همان منبع سرو کنید، یا مسیرهای Doconut را معکوس-پروکسی کنید |
| تم اعمال نمیشود | انتخابگر به عنصری داخل mount هدف میگیرد | مستقیم به خود mount هدف بگیرید: #host.dsw یا #host |
آیا این صفحه مفید بود؟