Плагин Signer

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

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

ТипКогда использовать
DocumentSigner (C#)Вы подписываете на сервере, без участия браузера
Встроенный виджет (doconutSigner.js)Вам нужен готовый экран загрузки, подписи и скачивания на вашей странице
HTTP‑конечные точки (?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 под демо‑лицензией или в визуальном режиме.

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 (default)Видимая подпись плюс цифровая печатьТребуется при платной лицензииДа
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 (по умолчанию)Документ конвертируется в 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 могли её содержать.
  • Правильный пароль.
  • В пределах его периода действия. Истёкший или ещё не действующий сертификат не останавливает приложение: он регистрируется как Warning при запуске, и сертификатные подписи отклоняются, пока сертификат не заменят. Визуальные подписи остаются без изменений.
  • Выдан для подписи документов: использование ключа с digital signature или non-repudiation, а также расширенное назначение ключа, если присутствует, позволяющее подписывать документы, защищать электронную почту или аутентифицировать клиента. Сертификат, выданный для другого назначения, например TLS‑серверный сертификат, всё равно может подписывать, но это фиксируется как Warning, и 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.

Warning, когда он истёк, ещё не действителен или не выдан для подписи документов:

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.

И Information, когда сертификат не настроен:

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 для демонстрационной (watermarked) подписи
    });
});

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, создаёт подпись (Рисовать на холсте, Ввести имя шрифтом подписи или Изображение из 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, one file)Загрузить PDF или .docx и открыть для предварительного просмотра200 — { token, name, pages, ext }
POST ?sign=run (JSON body)Подписать загруженный файл200 — { downloadToken, downloadName, watermarked }
GET ?sign=download&token=<downloadToken>Передать подписанный файл в поток200 — файл, Content-Disposition: attachment, Cache-Control: no-store

ext в ответе open включает ведущую точку (".docx"). Предпросмотр страницы использует стандартный маршрут изображения просмотрщика, {basePath}?token={token}&page={n}&thumb=1&width={px}; отображаемая страница становится placement.page.

Тело run:

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Голый 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 символов.
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);
}

Конечные точки имеют same-origin: эта версия не поддерживает CORS. Размещайте ваш UI и скрипт виджета из того же источника, что и Doconut, или сделайте обратный прокси для обоих /doconut путей (путь посредника и путь ресурсов) под origin вашего UI.

В продакшн

  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. За балансировщиком нагрузки без sticky‑сессий последующий запрос 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);
}

Получается через внедрение зависимостей; конструктор внутренний. 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() бросает 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Отправьте чистый 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 с того же источника, либо используйте обратный прокси для путей Doconut
Тема не применяетсяСелектор нацелен на элемент внутри монтированияНацелитесь на само монтирование: #host.dsw или #host

Была ли эта страница полезной?