Плагін Signer
Підписуйте PDF та Word документи видимим підписом та цифровою печаткою
Плагін Signer розміщує видимий підпис у документі і, за замовчуванням, запечатує його цифровим підписом, який може перевірити PDF‑читач. Він підписує PDF та Word (.docx) файли. Видимий підпис завжди є PNG‑зображенням: намальованим, надрукованим або завантаженим підписувачем.
| Поверхня | Використовуйте коли |
|---|---|
DocumentSigner (C#) | Ви підписуєте на сервері, без участі браузера |
Drop-in widget (doconutSigner.js) | Потрібен готовий екран завантаження, підпису та завантаження у вашій сторінці |
HTTP endpoints on DocImage.axd (?sign=open|run|download) | Ви створюєте власний інтерфейс підпису згідно задокументованого серверного контракту |
Кожен підпис розташовується один раз, на одній сторінці. Ім’я підписувача, причина та місце можуть супроводжувати його.
Встановити пакет
Install-Package Doconut.NETFramework.SignerЩоб закріпити плагін за випуском, який описує ця документація:
Install-Package Doconut.NETFramework.Signer -Version 26.10.0Тримайте пакет Signer тієї ж версії, що і Doconut.NETFramework.
Файл ліцензії плагіна, Doconut.Viewer.Signer.lic, розміщується у тій же папці, що і Doconut.Viewer.lic; його читає разом з ліцензією переглядача.
Зареєструвати плагін
Як і кожен Doconut‑плагін, Signer реєструється через AddPlugin<TPlugin>() у DoconutHost.Initialize, викликається з Application_Start:
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
});Додайте Doconut.DoconutHost.Shutdown() до Application_End, щоб фонові процеси зупинялися коректно під час перезапуску пулу додатків.
Це все, що потрібно фасаду C#. Віджет і його HTTP‑кінцеві точки — окремий опціональний модуль, AddSignerWidget() (див. Вбудований віджет).
Плагіну потрібна ліцензія, що надає можливість Signer. Без неї DoconutHost.Initialize генерує виключення у Application_Start:
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.У System.Web це означає, що кожен запит повертає порожній 500, а причина записується лише у журнал подій Windows (джерело ASP.NET). Виключення виникає через відсутність ліцензії, застарілий файл 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, або платна ліцензія поза її часовим вікном | Application_Start генерує виключення; кожен запит повертає порожній 500 | — | — |
Правило однакове для фасаду C# і віджета: вихідний файл має водяний знак, якщо ліцензія не є платною ліцензією переглядача або є тимчасовою. За тимчасової ліцензії плагін завжди підписує вбудованим демо‑сертифікатом, а будь‑який налаштований вами сертифікат не використовується.
Демо‑сертифікат створює справжню печатку, проте PDF‑читачі йому не довіряють. Інтеграцію можна побудувати і протестувати від початку до кінця на оцінній ліцензії; щоб отримати чистий, довірений результат, потрібна і платна ліцензія, і ваш власний сертифікат підпису.
Використання з C#
DocumentSigner зареєстровано DoconutHost.Initialize; отримайте його з DoconutHost.Services. Його конструктор є 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 defaults to Certified (видимий підпис + цифрова печатка); WordOutput defaults to Pdf.
SignResult result = await _signer.SignAsync(pdf, ".pdf", request, certificate, ct);
using (result.Stream)
using (var output = new MemoryStream())
{
await result.Stream.CopyToAsync(output, 81920, ct);
return output.ToArray();
}
}
}SignAsync приймає вихідний потік, його розширення (".pdf" або ".docx"), запит і сертифікат для цього виклику. Фасад не читає SignerWidgetOptions.SigningCertificate; це налаштування призначене для віджету. Передайте null під демо‑ліцензією або у Visual‑режимі.
SignResult містить підписаний документ як seekable‑потік, а також його Extension (".pdf" або ".docx"), щоб ви могли назвати файл. Ви володієте потоком: звільніть його, коли закінчите.
У контролері MVC 5
Зробіть дію асинхронною і await підпис. Цей ставить Visual‑підпис, який не потребує сертифіката:
[HttpPost]
public async Task<ActionResult> Sign(HttpPostedFileBase file)
{
var signer = Doconut.DoconutHost.Services.GetRequiredService<DocumentSigner>();
byte[] signaturePng = System.IO.File.ReadAllBytes(Server.MapPath("~/App_Data/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(
file.InputStream, Path.GetExtension(file.FileName), request, ct: Response.ClientDisconnectedToken);
string contentType = result.Extension == ".pdf"
? "application/pdf"
: "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
return File(result.Stream, contentType, Path.GetFileNameWithoutExtension(file.FileName) + "-signed" + result.Extension);
}Джерело Word підписується у PDF, якщо ви не запитуєте вивід у форматі Word. Назвіть результат з result.Extension:
var signer = Doconut.DoconutHost.Services.GetRequiredService<DocumentSigner>();
byte[] signaturePng = File.ReadAllBytes(HostingEnvironment.MapPath("~/App_Data/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 (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 (default) | Документ конвертується у PDF, потім підписується та запечатується | Широка: підписаний PDF перевіряється скрізь |
WordOutput.Docx | Документ залишається у Word: у ньому розміщується зображення підпису, плюс підпис пакету OOXML | Обмежена: не кожен переглядач показує підписи пакету OOXML |
Залишайте PDF, якщо тільки одержувач не потребує редагованого файлу Word і приймає обмежену підтримку перевіряючих.
Налаштування сертифіката
Щоб запечатати під своїм ідентифікатором, передайте плагіну файл PFX (PKCS#12), що містить приватний ключ. Для віджету встановіть SignerWidgetOptions.SigningCertificate; для фасаду C# передайте сертифікат у SignAsync. Надайте або байти, або шлях, плюс пароль. App_Data — хороше місце для файлу, бо IIS ніколи його не подає:
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.SigningCertificate = new SigningCertificate
{
PfxBytes = File.ReadAllBytes(HostingEnvironment.MapPath("~/App_Data/signing.pfx")),
Password = System.Configuration.ConfigurationManager.AppSettings["DoconutSigner:Password"] ?? "",
};
});
});Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.SigningCertificate = new SigningCertificate
{
PfxPath = HostingEnvironment.MapPath("~/App_Data/signing.pfx"),
Password = System.Configuration.ConfigurationManager.AppSettings["DoconutSigner:Password"] ?? "",
};
});
});Властивості SigningCertificate лише ініціалізуються, що C# 7.3 (за замовчуванням для проєктів .NET Framework) не може встановити. Встановіть <LangVersion> на 9.0 або новіший у файлі проєкту.
Сертифікат зберігається лише в пам’яті. Його ніколи не журналюють, не повертають клієнту і не зберігають, а пароль ніколи не з’являється в повідомленні про помилку.
Вимоги:
- Пакет PFX / PKCS#12 з приватним ключем. Файл лише з відкритим ключем (
.cer,.crt) не може підписувати. Експортуйте ланцюжок видавця разом з ним, щоб PDF‑штампи могли його нести. - Правильний пароль.
- У межах його періоду дії. Протермінований або ще недійсний сертифікат не зупиняє застосунок, проте підписи Certified відхиляються, доки його не замінять. Підписи Visual не змінюються.
- Виданий для підпису документів: використання ключа з digital signature або non-repudiation, а також розширене використання ключа, якщо воно присутнє, що дозволяє підписувати документи, захищати електронну пошту або автентифікувати клієнта. Сертифікат, виданий для іншого, наприклад TLS‑серверний сертифікат, все ще може підписувати, проте 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 перевіряється один раз, всередині DoconutHost.Initialize, тому неправильно налаштований PFX не проходить під час запуску, а не під час першого підпису. Три проблеми генерують InvalidOperationException з Application_Start, і кожен запит відповідає порожнім 500; повідомлення знаходиться у журналі подій Windows:
| Повідомлення | Виправлення |
|---|---|
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 ще раз з приватним ключем |
У ASP.NET Core хост також записує один рядок під час запуску, вказуючи сертифікат, або попереджуючи, що він прострочений або не виданий для підпису. DoconutHost не записує цей рядок, тому в .NET Framework перевірте новий сертифікат, підписавши тестовий документ у режимі Certified.
Фасад C# не перевіряється під час запуску. Сертифікат, який ви передаєте до SignAsync, читається під час підпису, тому неправильний шлях або пароль призводять до помилки цього виклику.
Вбудований віджет
Увімкнути кінцеві точки
Кінцеві точки ?sign=open|run|download віджета обслуговуються DocImage.axd і вимкнені за замовчуванням. Увімкніть їх поруч із реєстрацією плагіна:
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.MaxUploadMb = 25; // за замовчуванням
widget.MaxSignatureImageKb = 512; // за замовчуванням
// widget.SigningCertificate: дивіться налаштування Certificate; залиште null для демонстраційного (з водяним знаком) підпису
});
});
// System.Web читає весь завантажений файл перед тим, як Doconut його побачить: залиште maxRequestLength (KB) та
// maxAllowedContentLength (bytes) у Web.config вище MaxUploadMb віджета.AddSignerWidget() без аргументів увімкне віджет з параметрами за замовчуванням. Він сам по собі не надає підписування: потрібен AddPlugin<SignerPlugin>(), або DoconutHost.Initialize генерує виключення:
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.Кінцеві точки та скрипт обслуговуються обробником і модулем, зареєстрованим у Web.config:
<system.webServer>
<handlers>
<add name="DocImage" verb="GET,HEAD,POST" path="DocImage.axd" type="Doconut.DocImageHandler, Doconut" />
</handlers>
<modules>
<add name="DoconutResources" type="Doconut.DoconutResourceModule, Doconut" />
</modules>
</system.webServer>Модуль подає скрипт незалежно від того, чи увімкнено віджет. Без AddSignerWidget() віджет завантажується і малює свою зону падіння, і його перший запит відповідає 404: віджет тоді повідомляє Signing is not enabled on this server.
Обмеження завантаження
ASP.NET читає весь тіло запиту перед тим, як запускається DocImage.axd. Завантаження вище MaxUploadMb, але нижче обмежень хоста, отримує власний JSON віджета 413 (File is too large.). Завантаження вище обмежень хоста спочатку відхиляється IIS, з помилковою сторінкою, яку віджет не може прочитати. Тримайте обидва обмеження хоста вище за ліміт віджета:
<system.web>
<httpRuntime maxRequestLength="30720" /> <!-- КІЛОБАЙТИ: 30 MB -->
</system.web>
<system.webServer>
<security>
<requestFiltering>
<requestLimits maxAllowedContentLength="31457280" /> <!-- БАЙТИ: 30 MB -->
</requestFiltering>
</security>
</system.webServer>Завантаження, надіслане без Content-Length (chunked), яке перевищує обмеження хоста, також отримує сторінку помилки IIS; обхідного шляху для цього випадку немає.
Вбудуйте його
Скрипт роздається за адресою /doconut-res/js/doconutSigner.js. Це один самодостатній файл без залежностей. Вкажіть basePath на обробник:
<div id="host"></div>
<script src="/doconut-res/js/doconutSigner.js"></script>
<script>
const handle = Doconut.signer('#host', { basePath: '/DocImage.axd' });
</script>Doconut.signer(selectorOrElement, options) приймає CSS‑селектор або елемент, викидає помилку, якщо монтування не знайдено, і повертає дескриптор. Типовий basePath віджету, /doconut, — це кінцева точка ASP.NET Core; у цьому пакеті його має бути '/DocImage.axd'.
Підписувач завантажує PDF або файл .docx, створює підпис (Draw на полотні, Type ім'я у шрифті підпису або Image з PNG, JPG чи GIF), перетягує та змінює його розмір на сторінці, підписує і завантажує результат. Віджет завжди надсилає підпис у форматі PNG; завантажене зображення у браузері конвертується у PNG розміром 520×160.
Опції
| Опція | Тип | За замовчуванням | Примітки |
|---|---|---|---|
basePath | string | '/doconut' | Де роздаються кінцеві точки ?sign= та зображення попереднього перегляду. Встановіть '/DocImage.axd' у цьому пакеті |
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: '/DocImage.axd', licenseUrl: '/pricing' });// Тільки візуально, без перемикача: простий штамп без цифрового підпису.
Doconut.signer('#host', {
basePath: '/DocImage.axd',
signatureMode: 'visual',
showSignatureModeToggle: false
});Зворотні виклики
| Зворотний виклик | Викликається коли | Навантаження |
|---|---|---|
onReady | Одноразово, при монтуванні (не знову на reset()) | — |
onSourceLoaded | Файл відкрито і показано його попередній перегляд | { file: { token, name, pages, ext } } |
onSigned | Підпис успішний | { downloadToken, downloadName, watermarked } |
onDownload | При кожному натисканні Download | { downloadName, downloadToken } |
onError | Крок відкриття, підпису або завантаження не вдається, або файл у режимі Image занадто великий | { message } |
Зворотний виклик, який викидає виключення, перехоплюється і записується в журнал; він ніколи не порушує роботу віджету.
Імперативний дескриптор
| Метод | Поведінка |
|---|---|
reset() | Повертає до екрану перетягування та очищає поточний процес. Не викликає onReady знову. Нічого не робить після destroy() |
loadFile(file) | Запускає процес з File. Нічого не робить, якщо віджет не знаходиться на екрані перетягування; за потреби спочатку викличте reset() |
destroy() | Видаляє слухачі, очищає монтування та заморожує інстанс |
const signerWidget = Doconut.signer('#host', {
basePath: '/DocImage.axd',
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‑контракту на DocImage.axd. Маршрути відповідають 404, доки не буде викликано AddSignerWidget(). Помилки містять тіло JSON, { "error": "..." }, за винятком випадків, коли в таблиці зазначено «лише статус». Невідоме значення ?sign= відповідає 400.
| Маршрут | Призначення | Відповідь при успіху |
|---|---|---|
POST /DocImage.axd?sign=open (multipart, one file) | Завантажити PDF або .docx і відкрити його для попереднього перегляду | 200 — { token, name, pages, ext } |
POST /DocImage.axd?sign=run (JSON body) | Підписати завантажений файл | 200 — { downloadToken, downloadName, watermarked } |
GET /DocImage.axd?sign=download&token=<downloadToken> | Поток підписаного файлу | 200 — файл, Content-Disposition: attachment, Cache-Control: no-store |
ext у відповіді open включає початкову крапку (".docx"). Попередній перегляд сторінки використовує стандартний маршрут зображення переглядача, /DocImage.axd?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 (але не межі IIS) | 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: файл File для підпису; pngBase64: підпис у вигляді чистого base64 PNG, без префікса data:,
// наприклад canvas.toDataURL('image/png').split(',')[1].
async function signFile(file, pngBase64) {
const base = '/DocImage.axd';
// 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 та скрипт віджету з тієї ж схеми, хосту та порту, що й застосунок, або налаштуйте reverse‑proxy для DocImage.axd і /doconut-res під походженням вашого UI.
У продакшн
-
Встановіть плагін поруч із ядром пакету, тієї ж версії:
Install-Package Doconut.NETFramework.Signer. -
Додайте файл ліцензії. Помістіть
Doconut.Viewer.Signer.licу ту ж папку, що іDoconut.Viewer.lic. -
Отримайте ваш сертифікат у форматі PFX разом із приватним ключем та ланцюжком видавця, від центру сертифікації або власної PKI вашої організації. Щоб спочатку протестувати, використайте демонстраційну ліцензію (вбудований демонстраційний сертифікат з водяним знаком) або самопідписаний PFX.
-
Зчитайте сертифікат із конфігурації, щоб його зміна ніколи не вимагала змін у коді:
xml<appSettings> <add key="DoconutSigner:PfxPath" value="~/App_Data/your-certificate.pfx" /> </appSettings>csharpvar settings = System.Configuration.ConfigurationManager.AppSettings; Doconut.DoconutHost.Initialize(options => { options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic"); options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>(); options.AddSignerWidget(widget => widget.SigningCertificate = new SigningCertificate { PfxPath = HostingEnvironment.MapPath(settings["DoconutSigner:PfxPath"]), Password = settings["DoconutSigner:Password"] ?? "", }); });Зберігайте
.pfxуApp_Data, який IIS ніколи не подає, і тримайте пароль поза простимWeb.config: використовуйте зашифрований розділ конфігурації або сховище секретів, яке читає ваше розгортання. -
Підпишіть тестовий документ у режимі Certified. Сертифікат, який прострочений або ще не дійсний, відхиляється з
The signing certificate expired on yyyy-MM-dd.(абоis not valid before), і PDF‑читач показує, чи довіряє він підпису.
Довіра у PDF‑читачах. Читач показує підпис як дійсний, коли довіряє кореневому сертифікату. За допомогою PKI вашої організації це працює на кожному комп'ютері, який довіряє вашому кореневому сертифікату, зазвичай на всіх комп'ютерах всередині організації. Сертифікати, яким Adobe довіряє на будь‑якому комп'ютері (Adobe Approved Trust List), за нашими даними, випускаються з приватним ключем на апаратному токені або HSM, чого цей плагін не може використати: він підписує лише з PFX. Перевірте у вашого постачальника сертифікатів, перш ніж покладатися на такий тип довіри.
Веб‑ферми
Віджет зберігає кожне завантаження та його результат у пам'яті на сервері, який обслуговував open. За навантажувальником без sticky‑сесій, пізніше запит run, download або запит попереднього перегляду може потрапити на інший сервер і не знайти завантаження. Зареєструйте спільне зашифроване сховище віджету через другий аргумент DoconutHost.Initialize:
byte[] farmKey = Convert.FromBase64String(System.Configuration.ConfigurationManager.AppSettings["Doconut:FarmKey"]);
Doconut.DoconutHost.Initialize(
options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget();
},
services => 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);
}Отримується з DoconutHost.Services; конструктор є internal. 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
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. Встановлювачі лише ініціалізуються: проект потребує C# 9.0 або новішої версії.
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 означає демонстраційний сертифікат при тимчасовій ліцензії, а візуальні підписи лише при платній.
Усунення проблем
| Симптом | Причина | Виправлення |
|---|---|---|
Кожен запит повертає порожній 500 після додавання плагіна; журнал подій показує The Signer plugin is registered via AddPlugin but no active license grants Signer. | Відсутня ліцензія, файл TRIAL, ліцензія без Signer, або платна ліцензія поза її часовим вікном | Встановіть ліцензію, яка надає Signer, або видаліть AddPlugin<SignerPlugin>() |
Журнал подій показує AddSignerWidget() was called but the Signer plugin is not registered. | Віджет увімкнено без його плагіна | Додайте options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>() |
Журнал подій показує 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. | Неправильний пароль або файл не є PKCS#12 | Перевірте пароль; використайте справжній .pfx |
Журнал подій показує Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key. | PFX був експортований без приватного ключа | Експортуйте його знову з приватним ключем |
new SigningCertificate { … } не компілюється | Проект використовує C# 7.3, який не підтримує властивості лише ініціалізації | Встановіть <LangVersion> на 9.0 або новіше |
Розв'язання DocumentSigner викликає No IDocumentSigner is registered. | SignerPlugin не зареєстровано | Додайте AddPlugin<SignerPlugin>() у DoconutHost.Initialize |
| Вихідний файл має водяний знак | Ліцензія тимчасова (Demo/NFR) | Використайте платну ліцензію, яка надає Signer |
run відповідає 400 No signing certificate configured. | Платна ліцензія, режим Certified і відсутність сертифіката | Налаштуйте SigningCertificate, або підписуйте у візуальному режимі |
run відповідає 400 The signing certificate expired on yyyy-MM-dd. | Сертифікат застарілий | Замініть його; візуальні підписи продовжать працювати тим часом |
Віджет завантажується, але виводить Signing is not enabled on this server. | AddSignerWidget() не було викликано, або basePath не є '/DocImage.axd' | Викличте AddSignerWidget(); встановіть basePath: '/DocImage.axd' |
| Велике завантаження показує сторінку помилки IIS замість повідомлення віджета | maxRequestLength / maxAllowedContentLength нижчі за MaxUploadMb | Підвищте обидва обмеження хоста вище MaxUploadMb |
run відповідає 400 The signature image must be a PNG., Signature image is not valid base64. або Signature image is too large. | Користувацький інтерфейс надіслав URL у форматі data:, JPG або більше ніж MaxSignatureImageKb | Надішліть чистий base64 PNG у межах ліміту |
open відповідає 413 File is too large. | Завантаження перевищує MaxUploadMb | Підвищте MaxUploadMb у AddSignerWidget; maxUploadMb віджета — лише клієнтська перевірка |
run або download відповідає 404 Upload expired — please re-open the file. | 30‑хвилинне вікно минуло, або інший сервер у фермі не має завантаження | Відкрийте файл знову; у фермі зареєструйте AddDoconutDistributedWidgets |
Підписаний .docx не показує підпис у деяких переглядачах | Вихід Word містить підпис OOXML пакету, який багато переглядачів не відображають | Підписуйте у PDF, за замовчуванням |
| PDF‑читачі повідомляють, що особа підписувача невідома | Читач не довіряє кореневому сертифікату (демо‑сертифікат ніколи не довіряється) | Використайте сертифікат з коренем, якому довіряють ваші читачі |
| Віджет не працює, коли UI розташований на іншому походженні | Кінцеві точки не підтримують CORS | Обслуговуйте UI з того ж походження, або використайте reverse-proxy для DocImage.axd і /doconut-res |
| Тема не застосовується | Селектор націлений на елемент всередині mount | Спрямовуйте на сам mount: #host.dsw або #host |
Примітки до фреймворку
Порівняно з пакетами ASP.NET Core, цей пакет відрізняється лише хостингом; API, контракт кінцевої точки, скрипт віджету та правила ліцензування залишаються такими ж.
- Реєстрація знаходиться у
Application_Start, черезDoconutHost.Initialize, замістьbuilder.Services.AddDoconut. Сервіси, такі якAddDoconutDistributedWidgets, передаються у його другий аргумент. - Кінцеві точки обслуговуються
DocImage.axd, а скрипт —DoconutResourceModule, обидва зареєстровані уWeb.config, замістьUseDoconut()іUseDoconutResources(). Для віджету потрібенbasePath: '/DocImage.axd'. - Помилки запуску проявляються як порожній
500у кожному запиті, причину можна знайти у журналі подій Windows. - Завантаження повністю читаються ASP.NET до того, як Doconut їх бачить, тому обмеження IIS мають бути вище
MaxUploadMb. - Відсутній рядок журналу запуску щодо сертифіката: три помилки сертифіката все ще викидаються, але рядок з назвою сертифіката не записується.
- C# 9.0 або новіший потрібен для встановлення init‑only властивостей
SigningCertificate. - Лише Windows, як і решта пакету .NET Framework.
Чи була ця сторінка корисною?