Плагин Signer
Подписывайте PDF и Word документы с видимой подписью и цифровой печатью
Плагин Signer размещает видимую подпись в документе и по умолчанию запечатывает его цифровой подписью, которую может проверить PDF‑читалка. Он подписывает PDF и Word (.docx) файлы. Видимая подпись всегда представляет собой PNG‑изображение: нарисованное, набранное или загруженное подписантом.
| Интерфейс | Когда использовать |
|---|---|
DocumentSigner (C#) | Вы подписываете на сервере, без участия браузера |
Встроенный виджет (doconutSigner.js) | Вы хотите готовый экран загрузки, подписи и скачивания на своей странице |
HTTP‑конечные точки (?sign=open|run|download) | Вы создаёте собственный UI подписи, используя документированный серверный контракт |
Каждая подпись размещается один раз, на одной странице. Имя подписанта, причина и место могут перемещаться вместе с ней.
Установка пакета
Установите последнюю стабильную версию плагина 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; он читается вместе с лицензией просмотрщика.
Платформы. Плагин работает везде, где работает 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() и разрешается через внедрение зависимостей. Его конструктор внутренний, поэтому никогда не 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 хранит подписанный документ как перемещаемый (seekable) поток, а также его 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 (по умолчанию) | Видимая подпись плюс цифровая печать | Требуется при платной лицензии | Да |
SignatureMode.Visual | Только видимая подпись | Никогда не требуется | Нет: это изображение |
Используйте Certified, когда подпись должна быть доказуема: одобрения, контракты, всё, что проверяющему необходимо проверить для подтверждения личности и целостности. Используйте Visual, когда вам нужна только визуальная форма подписи или у вас нет сертификата. Временная лицензия ставит водяной знак на оба режима.
PDF‑печати представляют собой отделённые подписи PKCS#7 (adbe.pkcs7.detached) с SHA‑256 для ключей RSA или ECDSA. Они включают сертификаты издателя, найденные в вашем PFX, поэтому читатель, доверяющий вашему корню, может построить цепочку. Печати в формате Word‑native являются подписями пакетов 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. Укажите либо байты, либо путь, плюс пароль:
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.И Information, когда сертификат не настроен:
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: см. настройку Certificate; оставьте его 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, создаёт подпись (Рисовать на холсте, Вводить имя шрифтом подписи или Изображение из 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 | Показывает вариант Цифровая подпись / Только визуальная. При наличии false виджет подписывает с помощью signatureMode |
wordOutput | string | 'pdf' | Начальный вывод для источников .docx: 'pdf' или 'docx'. Любое другое значение становится 'pdf' |
showOutputFormatToggle | boolean | true | Показывает вариант PDF / Word, только для источников .docx. При наличии false виджет использует wordOutput |
labels | object | {} | Переопределяет любой набор английских строк |
Скрытие переключателя не отключает функцию; оно фиксирует значение. Две распространённые конфигурации:
// Оба переключателя отображаются, цифровая подпись по умолчанию: полноценный подписант самообслуживания
Doconut.signer('#host', { basePath: '/doconut', licenseUrl: '/pricing' });// Только визуальный, без переключателя: простой штамп без цифровой подписи
Doconut.signer('#host', {
basePath: '/doconut',
signatureMode: 'visual',
showSignatureModeToggle: false
});Обратные вызовы
| Обратный вызов | Срабатывает когда | Данные |
|---|---|---|
onReady | Один раз, при монтировании (больше не вызывается на reset()) | — |
onSourceLoaded | Файл открыт и его предварительный просмотр показан | { file: { token, name, pages, ext } } |
onSigned | Подписание успешно | { downloadToken, downloadName, watermarked } |
onDownload | При каждом нажатии кнопки «Скачать» | { downloadName, downloadToken } |
onError | Шаг открытия, подписи или загрузки не удался, либо файл в режиме Image слишком большой | { message } |
Обратный вызов, который бросает исключение, перехватывается и записывается в журнал; он никогда не нарушает поток работы виджета.
Императивный обработчик
| Метод | Поведение |
|---|---|
reset() | Возвращает к экрану сброса и очищает текущий поток. Не вызывает onReady повторно. Не делает ничего после destroy() |
loadFile(file) | Запускает поток с File. Не делает ничего, если виджет не находится на экране сброса; при необходимости сначала вызовите reset() |
destroy() | Удаляет слушатели, очищает монтировку и замораживает экземпляр |
const signerWidget = Doconut.signer('#host', {
basePath: '/doconut',
onSigned: (result) => console.log('signed', result.downloadName, result.watermarked),
onError: (error) => console.warn(error.message)
});
document.getElementById('start-over').addEventListener('click', () => signerWidget.reset());Метки
Каждая строка имеет английский вариант по умолчанию; labels переопределяет любую часть, а остальные остаются английскими. Фрагменты, меняющиеся во время выполнения, используют {placeholders}, такие как uploading: 'Uploading {name}…' и pages: '{n} pages'.
| Ключ | Английский вариант по умолчанию |
|---|---|
dropPrompt | Drag & drop a PDF or Word file here |
dropHint | PDF or Word (.docx) |
chooseFile | Choose file |
signatureHeading | Your signature |
modeDraw / modeType / modeImage | Draw / Type / Image |
metaSummary | Signature details (optional) |
metaSignerName / metaReason / metaLocation | Signer name / Reason / Location |
signatureType | Signature type |
modeCertified / modeVisual | Digital signature / Visual only |
modeVisualNote | No certificate — a visible mark only, not cryptographically verifiable. |
outputFormat | Output format |
outputPdf / outputWord | PDF / Word (.docx) |
signAction | Sign document |
download | Download |
demoNotice | Demo — signed with the Doconut demo certificate; output is watermarked. |
signingNotEnabled | Signing is not enabled on this server. |
page / pages | 1 page / {n} pages |
Дополнительные ключи охватывают шаг размещения, экран ошибки, связанную форму демонстрационного уведомления (demoNoticePrefix, demoNoticeLink, demoNoticeSuffix) и aria-live объявления.
Когда open или run отвечают 404 без JSON‑ошибки, виджет показывает signingNotEnabled. JSON‑ошибка от сервера всегда имеет приоритет, поэтому сообщения, такие как истёкшая загрузка, остаются видимыми.
Темизация
Виджет добавляет класс dsw к своему элементу монтирования и читает его цвета, радиус и шрифты из пользовательских CSS‑свойств, поэтому вы можете изменить тему без вмешательства во внутреннюю часть:
#host.dsw {
--dsw-accent: #b0522b; /* ссылки, фокус, активный режим */
--dsw-bg: #fffaf3;
--dsw-fg: #3b2a1a;
--dsw-muted: #8a7a68;
--dsw-border: #e0cbb0;
--dsw-radius: 14px;
--dsw-font: Georgia, "Times New Roman", serif;
--dsw-signature-font: "Segoe Script", "Brush Script MT", cursive; /* режим Type */
}Значения по умолчанию: --dsw-accent: #2b6cb0, --dsw-bg: #ffffff, --dsw-fg: #1a202c, --dsw-muted: #718096, --dsw-border: #cbd5e0, --dsw-radius: 8px, системный UI‑шрифт и курсивный шрифт подписи.
Создайте собственный фронтенд
Виджет является клиентом для этого HTTP‑контракта. Все три маршрута находятся под путём, где смонтирован UseDoconut() (обычно /doconut), и они отвечают 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 — the file, Content-Disposition: attachment, Cache-Control: no-store |
ext в ответе open включает ведущую точку (".docx"). Предпросмотр страницы использует стандартный маршрут изображения просмотрщика, {basePath}?token={token}&page={n}&thumb=1&width={px}; отображаемая страница становится placement.page.
Тело run:
{
"token": "GUID-from-open",
"signature": { "kind": "Drawn", "payload": "<base64 PNG, no data: prefix>" },
"placement": { "page": 1, "x": 0.58, "y": 0.80, "w": 0.32, "h": 0.12 },
"meta": { "signerName": "Ada Lovelace", "reason": "I approve", "location": "London, UK" },
"wordOutput": "pdf",
"mode": "certified"
}| Поле | Примечания |
|---|---|
token | Токен от open |
signature.kind | Drawn, Typed или Image, без учёта регистра; всё остальное становится Drawn. Только подсказка: полезная нагрузка всегда PNG |
signature.payload | Чистый PNG в base64 без префикса data:. Должен быть реальным PNG и не превышать MaxSignatureImageKb после декодирования |
placement.page | нумерация с 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.
| Маршрут | Статус | Когда | Тело |
|---|---|---|---|
| any | 404 | Виджет не включён | только статус |
| any | 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, либо обратным прокси направляйте оба пути /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);
}Получается через внедрение зависимостей; конструктор является 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.
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() бросает The Signer plugin is registered via AddPlugin but no active license grants Signer. | Нет лицензии, файл TRIAL, лицензия без Signer, или платная лицензия вне её версии | Установите лицензию, предоставляющую Signer, либо удалите AddPlugin<SignerPlugin>() |
AddDoconut() бросает AddSignerWidget() was called but the Signer plugin is not registered. | Виджет включён без своего плагина | Добавьте options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>() |
AddDoconut() бросает Doconut Signer: the certificate file was not found at '{path}'. | PfxPath указывает на отсутствующий файл | Исправьте путь; разместите файл там, где учётная запись приложения может его прочитать |
AddDoconut() бросает Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx. | Неправильный пароль или файл не является PKCS#12 | Проверьте пароль; используйте реальный .pfx |
AddDoconut() бросает Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key. | PFX был экспортирован без закрытого ключа | Экспортируйте его снова с закрытым ключом |
Разрешение DocumentSigner бросает No IDocumentSigner is registered. | SignerPlugin не зарегистрирован | Добавьте AddPlugin<SignerPlugin>() внутри AddDoconut() |
| Вывод имеет водяной знак | Лицензия временная (Demo/NFR) | Используйте платную лицензию, предоставляющую Signer |
run отвечает 400 No signing certificate configured. | Платная лицензия, режим Certified и отсутствие сертификата | Настройте SigningCertificate, либо подпишите в визуальном режиме |
run отвечает 400 The signing certificate expired on yyyy-MM-dd. | Сертификат просрочен | Замените его; визуальные подписи продолжают работать тем временем |
| Журнал сообщает, что вывод «использует встроенный демонстрационный сертификат», но платная лицензия отклоняет Certified подписи | Эта строка выводится, когда сертификат не настроен, независимо от лицензии | Настройте SigningCertificate |
Виджет загружается, но выводит Signing is not enabled on this server. | AddSignerWidget() не был вызван, или basePath не совпадает с местом, где смонтирован UseDoconut() | Вызовите AddSignerWidget(); исправьте basePath |
run отвечает 400 The signature image must be a PNG., Signature image is not valid base64. или Signature image is too large. | Пользовательский UI отправил URL data:, JPG или более чем MaxSignatureImageKb | Отправьте чистый PNG в base64 внутри лимита |
open отвечает 413 File is too large. | Загрузка превышает MaxUploadMb | Поднимите 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 |
Была ли эта страница полезной?