Плагін Signer

Підписуйте PDF та Word документи видимим підписом та цифровою печаткою

Плагін Signer розміщує видимий підпис у документі і, за замовчуванням, запечатлює його цифровим підписом, який може перевірити PDF‑читач. Він підписує PDF та Word (.docx) файли. Видимий підпис завжди є PNG‑зображенням: намальованим, надрукованим або завантаженим підписувачем.

СередовищеКоли використовувати
DocumentSigner (C#)Ви підписуєте на сервері, без залучення браузера
Drop-in widget (doconutSigner.js)Ви хочете готовий екран завантаження, підпису та завантаження на вашій сторінці
HTTP endpoints (?sign=open|run|download)Ви створюєте власний інтерфейс підпису згідно задокументованого серверного контракту

Кожен підпис розташовується один раз, на одній сторінці. Ім'я підписувача, причина та місце можуть супроводжувати його.

Встановлення пакету

Встановіть останню стабільну версію плагіна Signer:

bash
dotnet add package Doconut.NET8.Signer

Щоб зафіксувати плагін на випуску, який описано в цій документації, передайте версію окремо:

bash
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: Windows та Linux на базі glibc для x64 (не Alpine та інші дистрибутиви на musl). У Linux встановіть бібліотеку налаштування шрифтів перед відкриттям першого документа:

bash
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():

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
});

Це все, що потрібно фасаду C#. Віджет та його HTTP‑кінцеві точки — окрема опція, AddSignerWidget() (див. Вбудований віджет).

Плагіну потрібна ліцензія, яка надає можливість Signer. Без неї AddDoconut() генерує виключення під час запуску, до того, як застосунок обробить запит:

text
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>().

csharp
using Doconut;
using Doconut.Core.Models.Signing;

public sealed class ContractSigning
{
    private readonly DocumentSigner _signer;

    public ContractSigning(DocumentSigner signer) => _signer = signer;

    public async Task<byte[]> SignAsync(Stream pdf, byte[] signaturePng, SigningCertificate certificate, CancellationToken ct)
    {
        var request = new SignRequest(
            new VisibleSignature(SignatureKind.Drawn, signaturePng),
            new SignaturePlacement(Page: 1, X: 0.58, Y: 0.80, W: 0.32, H: 0.12),
            SignerName: "Ada Lovelace",
            Reason: "I approve this document",
            Location: "London, UK");
        // Mode за замовчуванням Certified (видимий підпис + цифрова печатка); WordOutput за замовчуванням Pdf.

        SignResult result = await _signer.SignAsync(pdf, ".pdf", request, certificate, ct);
        using (result.Stream)
        using (var output = new MemoryStream())
        {
            await result.Stream.CopyToAsync(output, ct);
            return output.ToArray();
        }
    }
}

SignAsync приймає вихідний потік, його розширення (".pdf" або ".docx"), запит і сертифікат для цього виклику. Фасад не читає SignerWidgetOptions.SigningCertificate; це налаштування призначене для віджету. Передайте null під демо‑ліцензією або у Visual‑режимі.

SignResult містить підписаний документ як потік, що підтримує пошук, а також його Extension (".pdf" або ".docx"), щоб ви могли назвати файл. Ви керуєте потоком: звільніть його, коли закінчите.

Візуальний підпис лише накладає зображення і не потребує сертифіката:

csharp
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:

csharp
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 генерує виключення замість повернення, коли виклик не може бути успішним:

ВинятокПовідомленняКоли
InvalidOperationExceptionNo signing certificate configured.Режим Certified, платна ліцензія та не передано сертифікат
InvalidOperationExceptionThe signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd.Режим Certified з сертифікатом поза межами його терміну дії
ArgumentExceptionThe sign request is invalid: the visible signature needs PNG bytes and the placement must be a normalized rectangle on a 1-based page.Порожні байти PNG або розміщення, яке недійсне
NotSupportedExceptionThe signer supports PDF and Word (.docx) documents; got '{extension}'.Будь‑який інший тип джерела

Режими підпису, вивід Word та сертифікати

Режими підпису

SignRequest.Mode вибирає, чи підпис запечатаний.

РежимЩо він створюєСертифікатПеревіряється
SignatureMode.Certified (за замовчуванням)Видимий підпис плюс цифровий печаткаПотрібен за платною ліцензієюТак
SignatureMode.VisualТільки видимий підписНіколи не потрібенНі: це зображення

Використовуйте Certified, коли підпис має бути доведений: затвердження, контракти, будь‑що, що перевіряє верифікатор для ідентифікації та цілісності. Використовуйте Visual, коли потрібен лише вигляд підпису або немає сертифіката. Тимчасова ліцензія додає водяний знак до обох.

PDF‑печатки — це відокремлені підписи PKCS#7 (adbe.pkcs7.detached) з SHA-256 для ключів RSA або ECDSA. Вони містять сертифікати видавця, знайдені у вашому PFX, тому читач, який довіряє вашому кореневому сертифікату, може побудувати ланцюжок. Печатки у форматі Word — це підписи пакетів OOXML і містять лише сертифікат підписувача.

Документи Word

Для .docx джерела, SignRequest.WordOutput вибирає вихід. Ігнорується для джерел PDF, які завжди створюють PDF.

ВихідЩо відбуваєтьсяПідтримка верифікатора
WordOutput.Pdf (за замовчуванням)Документ конвертується у PDF, потім підписується та запечатуєтьсяШирока: підписаний PDF перевіряється скрізь
WordOutput.DocxДокумент залишається у форматі Word: у ньому розміщується зображення підпису, плюс підпис пакету OOXMLОбмежена: не кожен переглядач показує підписи пакету OOXML

Залишайте PDF, якщо тільки одержувач не потребує редагованого файлу Word і не приймає обмежену підтримку верифікатора.

Налаштування сертифіката

Щоб запечатати власною ідентичністю, передайте плагіну файл PFX (PKCS#12), який містить приватний ключ. Для віджету встановіть SignerWidgetOptions.SigningCertificate; для фасаду C# передайте сертифікат у SignAsync. Надішліть або байти, або шлях, плюс пароль:

csharp
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"],
        };
    });
});
csharp
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 могли його нести.
  • Правильний пароль.
  • У межах його періоду дії. Термін дії закінчився або ще не настав — це не зупиняє застосунок: при запуску записується попередження, а сертифіковані підписи відхиляються, доки сертифікат не буде замінено. Візуальні підписи залишаються без змін.
  • Виданий для підпису документів: використання ключа з digital signature або non-repudiation, а також розширене використання ключа, якщо присутнє, що дозволяє підпис документів, захист електронної пошти або автентифікацію клієнта. Сертифікат, виданий для іншого, наприклад TLS‑серверний сертифікат, все одно підписує, але це реєструється як попередження, і PDF‑читачі позначають підпис.
  • Апарати апаратних токенів, смарт‑картки, HSM та сховище сертифікатів Windows не підтримуються. Експортуйте сертифікат разом із приватним ключем і ланцюжком у PFX.

Створіть PFX з сертифіката та його приватного ключа за допомогою OpenSSL:

bash
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 знову з приватним ключем

Інакше хост записує один рядок у журнал під час запуску. Інформація, коли сертифікат готовий:

text
Doconut Signer: using certificate '{subject}' (valid until yyyy-MM-dd). Signatures are digitally sealed.

Попередження, коли він прострочений, ще не дійсний або не виданий для підпису документів:

text
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.

Інформація, коли сертифікат не налаштовано:

text
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 віджета вимкнені за замовчуванням. Увімкніть їх поруч із реєстрацією плагіна:

csharp
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() викидає:

text
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). Це один самодостатній файл без залежностей:

html
<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.

Параметри

ПараметрТипЗа замовчуваннямПримітки
basePathstring'/doconut'Де розміщуються кінцеві точки ?sign= та попередні зображення
resPathstring'/doconut-res'Зарезервовано; віджет включає власний CSS
maxUploadMbnumber25Лише клієнтська перевірка, тому файл, що перевищує розмір, швидко відхиляється. Обмеження сервера — MaxUploadMb у AddSignerWidget
maxSignatureKbnumber512Клієнтське обмеження для режиму Image. Тримайте його рівним серверному MaxSignatureImageKb
previewWidthnumber560Піксельна ширина попереднього перегляду сторінки
licenseUrlstring | nullnullПеретворює повідомлення про демо‑водяний знак у посилання на цей URL
signatureModestring'certified'Початковий тип підпису: 'certified' або 'visual'. Будь-яке інше значення стає 'certified'
showSignatureModeTogglebooleantrueПоказує вибір Digital signature / Visual only. При включеному false, віджет підписує за допомогою signatureMode
wordOutputstring'pdf'Початковий вихід для джерел .docx: 'pdf' або 'docx'. Будь-яке інше значення стає 'pdf'
showOutputFormatTogglebooleantrueПоказує вибір PDF / Word, лише для джерел .docx. При включеному false, віджет використовує wordOutput
labelsobject{}Перезаписує будь-яку підмножину англійських рядків

Приховування перемикача не вимикає функцію; воно фіксує значення. Два поширені налаштування:

javascript
// Обидва перемикачі показані, цифровий підпис за замовчуванням: повний підписант самообслуговування
Doconut.signer('#host', { basePath: '/doconut', licenseUrl: '/pricing' });
javascript
// Лише візуально, без перемикача: простий штамп без цифрового підпису
Doconut.signer('#host', {
  basePath: '/doconut',
  signatureMode: 'visual',
  showSignatureModeToggle: false
});

Зворотні виклики

Зворотний викликКоли спрацьовуєДані
onReadyОдноразово, при монтуванні (не знову при reset())—
onSourceLoadedФайл відкрито і показано його попередній перегляд{ file: { token, name, pages, ext } }
onSignedПідпис успішний{ downloadToken, downloadName, watermarked }
onDownloadПри кожному натисканні Завантажити{ downloadName, downloadToken }
onErrorПомилка на кроці відкриття, підпису або завантаження, або файл у режимі Image занадто великий{ message }

Виключення, згенероване зворотним викликом, перехоплюється і записується в журнал; воно ніколи не порушує роботу віджета.

Імперативний обробник

МетодПоведінка
reset()Повертає до екрану скидання та очищає поточний процес. Не викликає onReady знову. Нічого не робить після destroy()
loadFile(file)Запускає процес з File. Нічого не робить, якщо віджет не знаходиться на екрані скидання; за потреби спочатку викличте reset()
destroy()Видаляє слухачі, очищає монтування та заморожує інстанцію
javascript
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'.

КлючАнглійське значення за замовчуванням
dropPromptDrag & drop a PDF or Word file here
dropHintPDF or Word (.docx)
chooseFileChoose file
signatureHeadingYour signature
modeDraw / modeType / modeImageDraw / Type / Image
metaSummarySignature details (optional)
metaSignerName / metaReason / metaLocationSigner name / Reason / Location
signatureTypeSignature type
modeCertified / modeVisualDigital signature / Visual only
modeVisualNoteNo certificate — a visible mark only, not cryptographically verifiable.
outputFormatOutput format
outputPdf / outputWordPDF / Word (.docx)
signActionSign document
downloadDownload
demoNoticeDemo — signed with the Doconut demo certificate; output is watermarked.
signingNotEnabledSigning is not enabled on this server.
page / pages1 page / {n} pages

Інші ключі охоплюють крок розміщення, екран помилки, пов’язану форму демо‑повідомлення (demoNoticePrefix, demoNoticeLink, demoNoticeSuffix) та оголошення aria-live.

Коли open або run відповідає 404 без JSON‑помилки, віджет показує signingNotEnabled. JSON‑помилка від сервера завжди переважає, тому повідомлення, наприклад про прострочене завантаження, залишаються видимими.

Темізація

Віджет додає клас dsw до свого елементу монтування та читає його кольори, радіус і шрифти з користувацьких властивостей CSS, тому ви можете оформити його без зміни внутрішньої структури:

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, один файл)Завантажити PDF або .docx і відкрити для попереднього перегляду200 — { token, name, pages, ext }
POST ?sign=run (JSON тіло)Підписати завантажений файл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:

json
{
  "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.kindDrawn, Typed або Image, без урахування регістру; будь‑що інше стає Drawn. Лише підказка: корисне навантаження завжди PNG
signature.payloadЧистий base64 PNG без префікса data:. Має бути справжнім PNG і не більшим за MaxSignatureImageKb після декодування
placement.page1‑базовий
placement.x / y / w / hНормалізований 0..1 від верхнього лівого кута, з x + w ≤ 1 та y + h ≤ 1
meta.signerName / reason / locationНеобов’язково. Кожен обрізається, порожнє значення відкидається, і кожен обрізається до 256 символів
wordOutputpdf (за замовчуванням) або docx; ігнорується для PDF‑джерел. Будь‑що інше стає pdf
modecertified (за замовчуванням) або visual. Будь‑що інше стає certified

downloadName слідує за виводом: <source>-signed.pdf або <source>-signed.docx, і download надсилає відповідний Content-Type.

Завантажене джерело та підписаний результат зберігаються кожен протягом 30 хвилин. Після цього run та download відповідають 404, і файл потрібно відкрити знову. Усі токени — це GUID.

МаршрутСтатусКолиТіло
будь‑який404Віджет не ввімкненолише статус
будь‑який405Неправильний метод (для open та run потрібен POST, download потребує GET)лише статус
open400Не multipart‑завантаженняExpected a multipart file upload.
open400Відсутній файл або порожнійNo file uploaded.
open400Будь‑що інше, крім .pdf або .docxSigning supports PDF and Word (.docx) files only.
open413Завантаження перевищує MaxUploadMbFile is too large.
run400Тіло не є коректним JSON або порожнєMalformed request. / Empty request.
run400Токен відсутній або не є GUIDInvalid token.
run404Завантаження прострочено або ніколи не відкривалосяUpload expired — please re-open the file.
run400Відсутній підпис або розміщенняNo signature supplied. / No placement supplied.
run400Навантаження не є base64, порожнє, занадто велике або не PNGSignature image is not valid base64. / Signature image is empty. / Signature image is too large. / The signature image must be a PNG.
run400Розміщення поза сторінкоюThe signature or its placement is invalid.
run400Сертифікований режим, платна ліцензія та відсутній сертифікатNo signing certificate configured.
run400Сертифікований режим з сертифікатом поза діапазоном його діїThe signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd.
open, run500Обробка не вдаласяОчищене повідомлення
download400Токен відсутній або не є GUIDлише статус
download404Невідомий або прострочений токенлише статус

Повний цикл з fetch:

javascript
// 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);
}

Кінцеві точки мають одного походження: ця версія не підтримує CORS. Розміщуйте ваш інтерфейс і скрипт віджету з того ж походження, що й Doconut, або використовуйте зворотний проксі для обох шляхів /doconut (шлях проміжного програмного забезпечення та шлях ресурсів) під вашим походженням інтерфейсу.

У продакшн

  1. Встановіть плагін поруч із ядром пакету, тієї ж версії: dotnet add package Doconut.NET8.Signer.

  2. Додайте файл ліцензії. Помістіть Doconut.Viewer.Signer.lic у ту ж папку, що і Doconut.Viewer.lic.

  3. Отримайте ваш сертифікат у форматі PFX з його приватним ключем та ланцюжком видавця, від центру сертифікації або власної PKI вашої організації. Щоб спочатку протестувати, використайте демо‑ліцензію (вбудований демо‑сертифікат з водяним знаком) або самопідписаний PFX.

  4. Зчитайте сертифікат з конфігурації, щоб його зміна ніколи не вимагала зміни коду:

    json
    "DoconutSigner": { "PfxPath": "certs/your-certificate.pfx" }
    csharp
    var 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) або сховище у продакшн.

  5. Перевірте журнал запуску. Він має містити using certificate '{subject}' (valid until …). Signatures are digitally sealed.. Попередження означає, що сертифікат прострочений, ще не дійсний або не виданий для підпису документів.

Довіра у PDF‑читачах. Читач показує підпис як дійсний, коли довіряє кореневому сертифікату. За допомогою PKI вашої організації це діє на кожному комп'ютері, який довіряє вашому кореневому сертифікату, зазвичай на всіх машинах всередині організації. Сертифікати, яким довіряє Adobe на будь‑якій машині (Adobe Approved Trust List), за нашими даними, випускаються з приватним ключем у апаратному токені або HSM, чого цей плагін не може використати: він підписує лише з PFX. Підтвердіть у постачальника вашого сертифікату перед тим, як покладатися на такий тип довіри.

Веб‑ферми

Віджет зберігає кожне завантаження та його результат у пам'яті на вузлі, який обслуговував open. За балансувальником навантаження без липких сесій, пізніший запит run, download або запит попереднього перегляду може потрапити на інший вузол і не знайти завантаження. Зареєструйте спільне, зашифроване сховище віджету один раз, після AddDoconut():

csharp
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

csharp
public sealed class DocumentSigner
{
    public Task<SignResult> SignAsync(
        Stream source, string sourceExtension, SignRequest request,
        SigningCertificate? cert = null, CancellationToken ct = default);
}

Отримується через впровадження залежностей; конструктор є internal. sourceExtension — це ".pdf" або ".docx". За платною ліцензією використовується cert і вихідний файл чистий; за тимчасовою ліцензією використовується вбудований демо‑сертифікат, cert ігнорується, і вихідний файл має водяний знак.

SignRequest

csharp
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

csharp
public sealed record VisibleSignature(SignatureKind Kind, byte[] PngBytes)
{
    public bool IsValid { get; }   // PngBytes не порожній
}

public enum SignatureKind { Drawn, Typed, Image }

PngBytes — це PNG для кожного типу. Намальований або надрукований підпис прозорий; завантажене зображення зберігає свою прозорість, тому непрозорий JPG залишається непрозорим. Kind — лише підказка.

SignaturePlacement

csharp
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

csharp
public enum SignatureMode { Certified, Visual }   // Certified є за замовчуванням
public enum WordOutput { Pdf, Docx }              // Pdf є за замовчуванням; ігнорується для PDF‑джерел

SignResult

csharp
public sealed record SignResult(Stream Stream, string Extension);

Підписаний документ у вигляді потоку, що підтримує переміщення, та його розширення з крапкою (".pdf" або ".docx").

SigningCertificate

csharp
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

csharp
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 був експортований без приватного ключаЕкспортуйте його знову з приватним ключем
Вирішення DocumentSigner викликає No IDocumentSigner is registered.SignerPlugin не зареєстрованоДодайте AddPlugin<SignerPlugin>() всередині AddDoconut()
Вихід має водяний знакЛіцензія тимчасова (Demo/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Надішліть чистий 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 для шляхів Doconut
Тема не застосовуєтьсяСелектор націлений на елемент всередині монтуНаціліться безпосередньо на монту: #host.dsw або #host

Чи була ця сторінка корисною?