Плагін Signer
Підписуйте 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.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; його читає разом із ліцензією переглядача.
Platforms. Плагін працює там, де працює Doconut.NET6: Windows та Linux на базі glibc (x64, не Alpine та інші дистрибутиви на musl). У Linux перед першим відкриттям документа встановіть бібліотеку налаштування шрифтів:
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() (див. Вбудований віджет).
Плагіну потрібна ліцензія, що надає можливість 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() і отримується через впровадження залежностей. Його конструктор internal, тому ніколи не 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. | Режим 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 могли його містити. - Правильний пароль.
- В межах його періоду дії. Протермінований або ще недійсний сертифікат не зупиняє застосунок: він реєструється як Warning під час запуску, а сертифіковані підписи відхиляються, доки його не замінять. Візуальні підписи залишаються без змін.
- Випущений для підпису документів: використання ключа з digital signature або non-repudiation, та розширене використання ключа, якщо присутнє, яке дозволяє підпис документів, захист електронної пошти або автентифікацію клієнта. Сертифікат, випущений для іншого, наприклад TLS‑серверний сертифікат, все ще підписує, але це реєструється як Warning, і читачі PDF позначають підпис.
- Апарати апаратних токенів, смарт‑картки, HSM та сховище сертифікатів Windows не підтримуються. Експортуйте сертифікат разом з його приватним ключем і ланцюжком у PFX.
Створіть PFX з сертифіката та його приватного ключа за допомогою OpenSSL:
openssl pkcs12 -export -out signing.pfx -inkey private.key -in certificate.crt
# Пароль експорту, який запитується, — це SigningCertificate.Password.Експортуйте його зі сховища сертифікатів Windows: відкрийте certmgr.msc і знайдіть сертифікат (його іконка показує ключ, коли присутній приватний ключ). Клацніть правою кнопкою, виберіть All Tasks → Export…, оберіть Yes, export the private key, виберіть Personal Information Exchange – PKCS #12 (.PFX) і встановіть пароль.
Перевірки під час запуску
Коли віджет увімкнено, сертифікат у SignerWidgetOptions.SigningCertificate перевіряється один раз, всередині AddDoconut(), тому неправильно налаштований PFX викликає помилку під час запуску, а не під час першого підпису. Три проблеми генерують InvalidOperationException:
| Повідомлення | Виправлення |
|---|---|
Doconut Signer: the certificate file was not found at '{path}'. | Виправте PfxPath; переконайтеся, що файл розгорнуто і доступний для облікового запису застосунку |
Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx. | Перевірте пароль; переконайтеся, що файл є справжнім .pfx, а не .cer або .pem |
Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key. | Експортуйте PFX знову з приватним ключем |
Інакше хост записує один рядок у журнал під час запуску. Інформація, коли сертифікат готовий:
Doconut Signer: using certificate '{subject}' (valid until yyyy-MM-dd). Signatures are digitally sealed.Попередження (Warning), коли він протермінований, ще недійсний або не випущений для підпису документів:
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.Останній рядок однаковий для будь-якої ліцензії. У платній ліцензії демонстраційний сертифікат ніколи не використовується: без сертифіката працюють лише візуальні підписи.
Фасад C# не перевіряється під час запуску. Сертифікат, який ви передаєте у SignAsync, читається під час підпису, тому неправильний шлях або пароль викликає помилку цього виклику.
Вбудований віджет
Увімкнути кінцеві точки
Кінцеві точки ?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 | Перетворює повідомлення про демо‑водяний знак у посилання на цей 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 | Одноразово, при монтуванні (не знову на reset()) | — |
onSourceLoaded | Файл відкрито і показано його попередній перегляд | { file: { token, name, pages, ext } } |
onSigned | Підписання успішне | { downloadToken, downloadName, watermarked } |
onDownload | При кожному натисканні Download | { downloadName, downloadToken } |
onError | Крок відкриття, підписання або завантаження не вдається, або файл у режимі Image занадто великий | { message } |
Зворотний виклик, який викидає помилку, ловиться і записується в журнал; він ніколи не порушує роботу віджету.
Імперативний обробник
| Метод | Поведінка |
|---|---|
reset() | Повертає до екрану drop і очищає поточний потік. Не викликає onReady знову. Нічого не робить після destroy() |
loadFile(file) | Запускає потік з File. Нічого не робить, якщо віджет не знаходиться на своєму екрану drop; за потреби спочатку викличте reset() |
destroy() | Видаляє слухачі, очищає mount і заморожує інстанцію |
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 до свого елементу mount і читає його кольори, радіус та шрифти з 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), і вони відповідають 404, доки не буде викликано AddSignerWidget(). Помилки містять тіло JSON, { "error": "..." }, за винятком випадків, коли в таблиці зазначено «лише статус». Невідоме значення ?sign= відповідає 400.
| Маршрут | Призначення | Відповідь при успіху |
|---|---|---|
POST ?sign=open (multipart, one file) | Завантажте PDF або .docx і відкрийте його для попереднього перегляду | 200 — { token, name, pages, ext } |
POST ?sign=run (JSON body) | Підпишіть завантажений файл | 200 — { downloadToken, downloadName, watermarked } |
GET ?sign=download&token=<downloadToken> | Транслюйте підписаний файл | 200 — файл, Content-Disposition: attachment, Cache-Control: no-store |
ext у відповіді open включає початкову крапку (".docx"). Попередній перегляд сторінки використовує стандартний маршрут зображення переглядача, {basePath}?token={token}&page={n}&thumb=1&width={px}; показана сторінка стає placement.page.
Тіло run:
{
"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 | Чистий base64 PNG без префікса data:. Має бути справжнім PNG і не більшим за MaxSignatureImageKb після декодування |
placement.page | Нумерація з 1 |
placement.x / y / w / h | Нормалізований 0..1 від верхнього‑лівого кута, з x + w ≤ 1 та y + h ≤ 1 |
meta.signerName / reason / location | Необов’язковий. Кожен обрізається, порожнє значення відкидається, і кожен обрізається до 256 символів |
wordOutput | pdf (за замовчуванням) або docx; ігнорується для PDF‑джерел. Будь‑що інше перетворюється на pdf |
mode | certified (за замовчуванням) або visual. Будь‑що інше перетворюється на certified |
downloadName слідує за виводом: <source>-signed.pdf або <source>-signed.docx, і download надсилає відповідний Content-Type.
Завантажене джерело та підписаний результат зберігаються кожен протягом 30 хвилин. Після цього run та download відповідають 404, і файл потрібно відкрити знову. Усі токени — це GUID.
| Маршрут | Статус | Коли | Тіло |
|---|---|---|---|
| будь‑який | 404 | Віджет не ввімкнено | лише статус |
| будь‑який | 405 | Неправильний метод (для open та run потрібен POST, для download потрібен GET) | лише статус |
open | 400 | Не multipart‑завантаження | 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: підпис у вигляді чистого base64 PNG, без префікса 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, або виконуйте reverse-proxy обох /doconut шляхів (шлях проміжного програмного забезпечення та шлях ресурсів) під походженням вашого UI.
У продакшн
-
Встановіть плагін поруч із ядром пакету, тієї ж версії:
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 Approved Trust List), за нашими даними, видаються з приватним ключем на апаратному токені або HSM, що цей плагін не може використовувати: він підписує лише з PFX. Підтвердіть у постачальника вашого сертифікату перед тим, як покладатися на такий тип довіри.
Веб‑ферми
Віджет зберігає кожне завантаження та його результат у пам'яті на вузлі, який обслуговував open. За навантажувальником без sticky‑сесій, пізніший запит run, download або запит попереднього перегляду може потрапити на інший вузол і не знайти завантаження. Зареєструйте спільне, зашифроване сховище віджета один раз, після AddDoconut():
byte[] farmKey = Convert.FromBase64String(builder.Configuration["Doconut:FarmKey"]);
builder.Services.AddDoconutDistributedWidgets(store =>
{
store.RootPath = @"\\fileshare\doconut"; // тека, яку кожен вузол може читати і записувати
store.FarmKey = farmKey; // принаймні 32 байти, ідентичні на кожному вузлі
// store.Ttl = TimeSpan.FromMinutes(30); // як довго зберігається завантаження (за замовчуванням)
});- Один сервер нічого не потребує: без цього виклику використовується сховище в пам'яті.
- Завантаження та результати зашифровані у спільному сховищі (AES-256, encrypt-then-MAC), і кожен файл прив'язаний до свого токена, тому один токен ніколи не може прочитати файл іншого.
FarmKeyмає бути щонайменше 32 байти і однаковим на всіх вузлах. Завантажуйте його з секретного сховища; ніколи не вбудовуйте його в код. Реєстрація генеруєArgumentException, колиRootPathвідсутній абоFarmKeyкоротший за 32 байти.- Вкажіть
RootPathна те саме спільне розташування, яке використовує розподілений переглядач, і надайте кожному вузлу один і той же сертифікат підпису.
Довідник API
Фасад та параметри віджета знаходяться у просторі імен Doconut; типи запитів і результатів – у Doconut.Core.Models.Signing. SignerPlugin розташований у Doconut.Plugins.Signer.
DocumentSigner – ПідписувачДокументу
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 нумерується з 1; X, Y, W і H – це нормалізовані 0..1 від верхнього лівого кута.
SignatureMode and WordOutput – РежимПідпису та WordВивід
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, що дозволяє ланцюжити виклики. Null SigningCertificate означає демо‑сертифікат при тимчасовій ліцензії, а візуальні підписи доступні лише при платній ліцензії.
Усунення проблем
| Симптом | Причина | Виправлення |
|---|---|---|
AddDoconut() throws The Signer plugin is registered via AddPlugin but no active license grants Signer. | Відсутня ліцензія, файл TRIAL, ліцензія без Signer або платна ліцензія поза її часовим вікном | Встановіть ліцензію, що надає Signer, або видаліть AddPlugin<SignerPlugin>() |
AddDoconut() throws AddSignerWidget() was called but the Signer plugin is not registered. | Віджет увімкнено без його плагіна | Додайте options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>() |
AddDoconut() throws Doconut Signer: the certificate file was not found at '{path}'. | PfxPath вказує на відсутній файл | Виправте шлях; розгорніть файл у місці, де обліковий запис програми може його читати |
AddDoconut() throws 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() throws Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key. | PFX був експортований без приватного ключа | Експортуйте його знову з приватним ключем |
Resolving DocumentSigner throws No IDocumentSigner is registered. | SignerPlugin не зареєстровано | Додайте AddPlugin<SignerPlugin>() всередині AddDoconut() |
| Вихід має водяний знак | Ліцензія тимчасова (Demo/NFR) | Використайте платну ліцензію, що надає Signer |
run answers 400 No signing certificate configured. | Платна ліцензія, режим Certified і відсутній сертифікат | Налаштуйте SigningCertificate, або підписуйте у Visual режимі |
run answers 400 The signing certificate expired on yyyy-MM-dd. | Сертифікат застарілий | Замініть його; візуальні підписи продовжують працювати тим часом |
| У журналі зазначено, що вихід "використовує вбудований демо‑сертифікат", проте платна ліцензія відхиляє Certified підписи | Цей рядок записується завжди, коли сертифікат не налаштований, незалежно від ліцензії | Налаштуйте SigningCertificate |
Віджет завантажується, але виводить Signing is not enabled on this server. | AddSignerWidget() не був викликаний, або basePath не відповідає тому, де змонтовано UseDoconut() | Викличте AddSignerWidget(); виправте basePath |
run answers 400 The signature image must be a PNG., Signature image is not valid base64. or Signature image is too large. | Користувацький інтерфейс надіслав URL у форматі data:, JPG або більше ніж MaxSignatureImageKb | Надішліть чистий base64 PNG у межах ліміту |
open answers 413 File is too large. | Завантаження перевищує MaxUploadMb | Збільшіть MaxUploadMb у AddSignerWidget; maxUploadMb віджета — лише клієнтська перевірка |
run or download answers 404 Upload expired — please re-open the file. | 30‑хвилинне вікно минуло, або вузол веб‑ферми не має завантаження | Відкрийте файл знову; у фермі зареєструйте AddDoconutDistributedWidgets |
Підписаний .docx не відображає підпис у деяких переглядачах | Вихід Word містить підпис пакету OOXML, який багато переглядачів не відображають | Підписуйте у PDF, за замовчуванням |
| PDF‑читачі повідомляють, що особа підписувача невідома | Читач не довіряє кореневому сертифікату (демо‑сертифікат ніколи не довіряється) | Використайте сертифікат від кореня, якому довіряють ваші читачі |
| Віджет не працює, коли інтерфейс UI розташований на іншому походженні | Кінцеві точки не підтримують CORS | Обслуговуйте UI з того ж походження, або використайте reverse‑proxy для шляхів Doconut |
| Тема не застосовується | Селектор націлений на елемент всередині монту | Націліться безпосередньо на монту: #host.dsw або #host |
Чи була ця сторінка корисною?