Плагин Signer
Подписывайте PDF и Word документы с видимой подписью и цифровой печатью
Плагин Signer размещает видимую подпись на документе и по умолчанию запечатывает его цифровой подписью, которую может проверить PDF‑читалка. Он подписывает PDF и Word (.docx) файлы. Видимая подпись всегда представляет собой PNG‑изображение: нарисованное, набранное или загруженное подписывающим.
| Интерфейс | Когда использовать |
|---|---|
DocumentSigner (C#) | Вы подписываете на сервере, без участия браузера |
Drop-in widget (doconutSigner.js) | Вам нужен готовый экран загрузки, подписи и скачивания на вашей странице |
HTTP endpoints on DocImage.axd (?sign=open|run|download) | Вы создаёте собственный UI подписи, опираясь на документированный серверный контракт |
Каждая подпись размещается один раз, на одной странице. Имя подписывающего, причина и место могут сопровождать её.
Установить пакет
Install-Package Doconut.NETFramework.SignerЧтобы привязать плагин к версии, описанной в этой документации:
Install-Package Doconut.NETFramework.Signer -Version 26.10.0Держите пакет Signer той же версии, что и Doconut.NETFramework.
Файл лицензии плагина, Doconut.Viewer.Signer.lic, помещается в ту же папку, что и Doconut.Viewer.lic; он читается вместе с лицензией просмотрщика.
Зарегистрировать плагин
Как и любой плагин Doconut, Signer регистрируется через AddPlugin<TPlugin>() в DoconutHost.Initialize, вызываемый из Application_Start:
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
});Добавьте Doconut.DoconutHost.Shutdown() в Application_End, чтобы фоновые задачи корректно останавливались при переработке пула приложений.
Это всё, что требуется фасаду C#. Виджет и его HTTP‑конечные точки — отдельный опциональный компонент, AddSignerWidget() (см. Встроенный виджет).
Плагину нужна лицензия, предоставляющая возможность Signer. Без неё DoconutHost.Initialize генерирует исключение из Application_Start:
The Signer plugin is registered via AddPlugin but no active license grants Signer. Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Signer.В System.Web это означает, что каждый запрос возвращает пустой 500, а причина отображается только в журнале событий Windows (источник ASP.NET). Исключение возникает при отсутствии лицензии, устаревшем файле TRIAL, лицензии без Signer и платной лицензии, использующейся вне её версии. Принимаются временные лицензии Demo/NFR. См. Настройка лицензии.
Лицензирование и водяной знак
| Состояние лицензии | Запуск | Сертифицированная подпись | Визуальная подпись |
|---|---|---|---|
Платная лицензия, предоставляющая Signer, сертификат настроен | Запускается | Запечатано вашим сертификатом, чисто (watermarked: false) | Чисто |
Платная лицензия, предоставляющая Signer, без сертификата | Запускается | Отказано: No signing certificate configured. | Чисто |
| Платная лицензия, сертификат истёк или ещё не действителен | Запускается | Отказано: The signing certificate expired on yyyy-MM-dd. | Чисто |
| Временная лицензия Demo/NFR, активна или истёкшая | Запускается | Запечатано встроенным демо‑сертификатом, с водяным знаком (watermarked: true) | С водяным знаком |
Отсутствует лицензия, устаревший файл TRIAL, лицензия без Signer, или платная лицензия вне её версии | Application_Start генерирует исключение; каждый запрос возвращает пустой 500 | — | — |
Правило одинаково для фасада C# и виджета: вывод имеет водяной знак, если лицензия не является платной лицензией просмотрщика или является временной. При временной лицензии плагин всегда подписывает встроенным демо‑сертификатом, а любой настроенный вами сертификат не используется.
Демо‑сертификат создает подлинную печать, но PDF‑читалки ему не доверяют. Интеграцию можно построить и протестировать полностью на оценочной лицензии; чтобы получить чистый, доверенный вывод, вам нужна как платная лицензия, так и ваш собственный сертификат подписи.
Использование из C#
DocumentSigner зарегистрирован DoconutHost.Initialize; получайте его из DoconutHost.Services. Его конструктор внутренний, поэтому никогда не 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, 81920, ct);
return output.ToArray();
}
}
}SignAsync принимает поток источника, его расширение (".pdf" или ".docx"), запрос и сертификат для этого вызова. Фасад не читает SignerWidgetOptions.SigningCertificate; эта настройка предназначена для виджета. Передайте null под демо‑лицензией или в режиме Visual.
SignResult хранит подписанный документ как перемещаемый поток, плюс его Extension (".pdf" или ".docx"), чтобы вы могли назвать файл. Вы владеете потоком: освободите его, когда закончите.
В контроллере MVC 5
Сделайте действие асинхронным и await сигнатуру. Это ставит визуальную подпись, которой не нужен сертификат:
[HttpPost]
public async Task<ActionResult> Sign(HttpPostedFileBase file)
{
var signer = Doconut.DoconutHost.Services.GetRequiredService<DocumentSigner>();
byte[] signaturePng = System.IO.File.ReadAllBytes(Server.MapPath("~/App_Data/signature.png"));
var request = new SignRequest(
new VisibleSignature(SignatureKind.Image, signaturePng),
new SignaturePlacement(Page: 1, X: 0.58, Y: 0.80, W: 0.32, H: 0.12),
Mode: SignatureMode.Visual);
SignResult result = await signer.SignAsync(
file.InputStream, Path.GetExtension(file.FileName), request, ct: Response.ClientDisconnectedToken);
string contentType = result.Extension == ".pdf"
? "application/pdf"
: "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
return File(result.Stream, contentType, Path.GetFileNameWithoutExtension(file.FileName) + "-signed" + result.Extension);
}Источник Word подписывается в PDF, если только вы не запросите вывод в Word. Назовите результат из result.Extension:
var signer = Doconut.DoconutHost.Services.GetRequiredService<DocumentSigner>();
byte[] signaturePng = File.ReadAllBytes(HostingEnvironment.MapPath("~/App_Data/signature.png"));
var request = new SignRequest(
new VisibleSignature(SignatureKind.Drawn, signaturePng),
new SignaturePlacement(Page: 1, X: 0.58, Y: 0.80, W: 0.32, H: 0.12),
WordOutput: WordOutput.Docx);
SignResult result = await signer.SignAsync(stream, ".docx", request, ct: ct);
string downloadName = "contract-signed" + result.Extension; // ".docx"SignAsync бросает исключение вместо возврата, когда вызов не может быть выполнен:
| Исключение | Сообщение | Когда |
|---|---|---|
InvalidOperationException | No signing certificate configured. | Режим 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, являются подписью пакета 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. Укажите либо байты, либо путь, плюс пароль. App_Data — хорошее место для файла, потому что IIS никогда его не обслуживает:
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.SigningCertificate = new SigningCertificate
{
PfxBytes = File.ReadAllBytes(HostingEnvironment.MapPath("~/App_Data/signing.pfx")),
Password = System.Configuration.ConfigurationManager.AppSettings["DoconutSigner:Password"] ?? "",
};
});
});Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.SigningCertificate = new SigningCertificate
{
PfxPath = HostingEnvironment.MapPath("~/App_Data/signing.pfx"),
Password = System.Configuration.ConfigurationManager.AppSettings["DoconutSigner:Password"] ?? "",
};
});
});Свойства SigningCertificate доступны только для инициализации, что C# 7.3 (по умолчанию для проектов .NET Framework) не может задать. Установите <LangVersion> в 9.0 или более позднюю версию в файле проекта.
Сертификат хранится только в памяти. Он никогда не логируется, не возвращается клиенту и не сохраняется, а пароль никогда не появляется в сообщении об ошибке.
Требования:
- Пакет PFX / PKCS#12 с закрытым ключом. Файл только с открытым ключом (
.cer,.crt) не может подписывать. Экспортируйте цепочку издателя вместе с ним, чтобы PDF‑печати могли её включать. - Правильный пароль.
- В пределах его периода действия. Истёкший или ещё не действующий сертификат не останавливает приложение, но подписи Certified отклоняются, пока он не будет заменён. Визуальные подписи не затронуты.
- Выдан для подписи документов: назначение ключа digital signature или non-repudiation, а также расширенное назначение, если присутствует, позволяющее подпись документов, защиту электронной почты или аутентификацию клиента. Сертификат, выданный для другого назначения, например TLS‑серверный сертификат, всё равно может подписывать, но PDF‑читалки помечают подпись.
- Аппаратные токены, смарт‑карты, HSM и хранилище сертификатов Windows не поддерживаются. Экспортируйте сертификат вместе с закрытым ключом и цепочкой в PFX.
Создайте PFX из сертификата и его закрытого ключа с помощью OpenSSL:
openssl pkcs12 -export -out signing.pfx -inkey private.key -in certificate.crt
# Пароль экспорта, который запрашивается, — SigningCertificate.Password.Экспортируйте из хранилища сертификатов Windows: откройте certmgr.msc и найдите сертификат (его значок показывает ключ, когда закрытый ключ присутствует). Щёлкните правой кнопкой, выберите Все задачи → Экспорт…, отметьте Да, экспортировать закрытый ключ, выберите Personal Information Exchange – PKCS #12 (.PFX) и задайте пароль.
Проверка запуска
Когда виджет включён, сертификат в SignerWidgetOptions.SigningCertificate проверяется один раз, внутри DoconutHost.Initialize, поэтому неправильно настроенный PFX приводит к ошибке при запуске, а не при первой подписи. Три проблемы вызывают InvalidOperationException из Application_Start, и каждый запрос затем отвечает пустым 500; сообщение находится в журнале событий Windows:
| Сообщение | Исправление |
|---|---|
Doconut Signer: the certificate file was not found at '{path}'. | Исправьте PfxPath; убедитесь, что файл развернут и доступен для чтения учётной записью пула приложений |
Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx. | Проверьте пароль; убедитесь, что файл является настоящим .pfx, а не .cer или .pem |
Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key. | Экспортируйте PFX снова с закрытым ключом |
В ASP.NET Core хост также записывает одну строку при запуске, указывая сертификат, или предупреждая, что он просрочен или не предназначен для подписи. DoconutHost не пишет эту строку, поэтому в .NET Framework проверьте новый сертификат, подписав тестовый документ в режиме Certified.
Фасад C# не проверяется при запуске. Сертификат, который вы передаёте в SignAsync, читается при подписи, поэтому неверный путь или пароль вызывают ошибку этого вызова.
Встраиваемый виджет
Включить конечные точки
Конечные точки ?sign=open|run|download виджета обслуживаются DocImage.axd и отключены по умолчанию. Включите их рядом с регистрацией плагина:
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.MaxUploadMb = 25; // по умолчанию
widget.MaxSignatureImageKb = 512; // по умолчанию
// widget.SigningCertificate: см. настройку сертификата; оставьте null для демонстрационной (с водяным знаком) подписи
});
});
// System.Web читает весь загрузочный файл до того, как Doconut его увидит: поддерживайте maxRequestLength (KB) и
// maxAllowedContentLength (bytes) в Web.config выше MaxUploadMb виджета.AddSignerWidget() без аргументов включает виджет с настройками по умолчанию. Он сам по себе не предоставляет возможность подписи: ему нужен AddPlugin<SignerPlugin>(), иначе DoconutHost.Initialize бросает:
AddSignerWidget() was called but the Signer plugin is not registered. Add options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>() (the widget needs it), or remove the AddSignerWidget() call.Конечные точки и скрипт обслуживаются обработчиком и модулем, зарегистрированным в Web.config:
<system.webServer>
<handlers>
<add name="DocImage" verb="GET,HEAD,POST" path="DocImage.axd" type="Doconut.DocImageHandler, Doconut" />
</handlers>
<modules>
<add name="DoconutResources" type="Doconut.DoconutResourceModule, Doconut" />
</modules>
</system.webServer>Модуль обслуживает скрипт независимо от того, включён ли виджет. Без AddSignerWidget() виджет загружается и рисует свою зону перетаскивания, и его первый запрос отвечает 404: затем виджет сообщает Signing is not enabled on this server.
Ограничения загрузки
ASP.NET читает всё тело запроса до того, как запускается DocImage.axd. Загрузка выше MaxUploadMb, но ниже ограничений хоста, получает собственный JSON виджета 413 (File is too large.). Загрузка выше ограничений хоста сначала отклоняется IIS, с страницой ошибки, которую виджет не может прочитать. Держите оба ограничения хоста выше предела виджета:
<system.web>
<httpRuntime maxRequestLength="30720" /> <!-- КИЛОБАЙТЫ: 30 MB -->
</system.web>
<system.webServer>
<security>
<requestFiltering>
<requestLimits maxAllowedContentLength="31457280" /> <!-- БАЙТЫ: 30 MB -->
</requestFiltering>
</security>
</system.webServer>Загрузка, отправленная без Content-Length (chunked), превышающая ограничения хоста, также получает страницу ошибки IIS; обходного решения для этого случая нет.
Встроить
Скрипт доступен по адресу /doconut-res/js/doconutSigner.js. Это один автономный файл без зависимостей. Укажите basePath на обработчик:
<div id="host"></div>
<script src="/doconut-res/js/doconutSigner.js"></script>
<script>
const handle = Doconut.signer('#host', { basePath: '/DocImage.axd' });
</script>Doconut.signer(selectorOrElement, options) принимает CSS‑селектор или элемент, бросает ошибку, если монтировка не найдена, и возвращает дескриптор. Значение по умолчанию для basePath, /doconut, — это конечная точка ASP.NET Core; в этом пакете оно должно быть '/DocImage.axd'.
Подписант загружает PDF или .docx файл, создаёт подпись (Draw на холсте, Type имя шрифтом подписи или Image из PNG, JPG или GIF), перетаскивает и изменяет её размер на странице, затем подписывает и скачивает результат. Виджет всегда отправляет подпись в формате PNG; загруженное изображение в браузере конвертируется в PNG размером 520×160.
Параметры
| Параметр | Тип | По умолчанию | Примечания |
|---|---|---|---|
basePath | string | '/doconut' | Где обслуживаются конечные точки ?sign= и изображения предварительного просмотра. Установите '/DocImage.axd' в этом пакете |
resPath | string | '/doconut-res' | Зарезервировано; виджет включает собственный CSS |
maxUploadMb | number | 25 | Только проверка на клиенте, поэтому слишком большой файл быстро отклоняется. Ограничение на сервере — MaxUploadMb в AddSignerWidget |
maxSignatureKb | number | 512 | Ограничение на клиенте для режима Image. Держите его равным серверному MaxSignatureImageKb |
previewWidth | number | 560 | Ширина превью страницы в пикселях |
licenseUrl | string | null | null | Преобразует уведомление демо‑водяного знака в ссылку на этот URL |
signatureMode | string | 'certified' | Начальный тип подписи: 'certified' или 'visual'. Любое другое значение становится 'certified' |
showSignatureModeToggle | boolean | true | Отображает выбор Digital signature / Visual only. При наличии false виджет подписывает с помощью signatureMode |
wordOutput | string | 'pdf' | Начальный вывод для источников .docx: 'pdf' или 'docx'. Любое другое значение становится 'pdf' |
showOutputFormatToggle | boolean | true | Отображает выбор PDF / Word, только для источников .docx. При наличии false виджет использует wordOutput |
labels | object | {} | Переопределяет любую часть английских строк |
Скрытие переключателя не отключает функцию; оно фиксирует значение. Две распространённые конфигурации:
// Оба переключателя отображаются, цифровая подпись включена по умолчанию: полноценный подписант самообслуживания.
Doconut.signer('#host', { basePath: '/DocImage.axd', licenseUrl: '/pricing' });// Только визуально, без переключателя: простой штамп без цифровой подписи.
Doconut.signer('#host', {
basePath: '/DocImage.axd',
signatureMode: 'visual',
showSignatureModeToggle: false
});Обратные вызовы
| Обратный вызов | Срабатывает когда | Данные |
|---|---|---|
onReady | Один раз, при монтировании (не повторяется при reset()) | — |
onSourceLoaded | Файл открыт и показан его превью | { file: { token, name, pages, ext } } |
onSigned | Подпись успешно выполнена | { downloadToken, downloadName, watermarked } |
onDownload | При каждом нажатии Download | { downloadName, downloadToken } |
onError | Шаг открытия, подписи или загрузки не удался, либо файл в режиме Image слишком большой | { message } |
Обработчик, который бросает исключение, перехватывается и записывается в журнал; он никогда не прерывает работу виджета.
Императивный дескриптор
| Метод | Поведение |
|---|---|
reset() | Возвращает к экрану загрузки и очищает текущий процесс. Не вызывает onReady повторно. Нет действия после destroy() |
loadFile(file) | Запускает процесс с помощью File. Нет действия, если виджет не находится на экране загрузки; при необходимости сначала вызовите reset() |
destroy() | Удаляет слушатели, очищает монтировку и замораживает экземпляр |
const signerWidget = Doconut.signer('#host', {
basePath: '/DocImage.axd',
onSigned: (result) => console.log('signed', result.downloadName, result.watermarked),
onError: (error) => console.warn(error.message)
});
document.getElementById('start-over').addEventListener('click', () => signerWidget.reset());Метки
Каждая строка имеет английский вариант по умолчанию; labels переопределяет любую часть, а остальные остаются на английском. Фрагменты, меняющиеся во время выполнения, используют {placeholders}, такие как uploading: 'Uploading {name}…' и pages: '{n} pages'.
| Ключ | Английский вариант |
|---|---|
dropPrompt | Drag & drop a PDF or Word file here |
dropHint | PDF or Word (.docx) |
chooseFile | Choose file |
signatureHeading | Your signature |
modeDraw / modeType / modeImage | Draw / Type / Image |
metaSummary | Signature details (optional) |
metaSignerName / metaReason / metaLocation | Signer name / Reason / Location |
signatureType | Signature type |
modeCertified / modeVisual | Digital signature / Visual only |
modeVisualNote | No certificate — a visible mark only, not cryptographically verifiable. |
outputFormat | Output format |
outputPdf / outputWord | PDF / Word (.docx) |
signAction | Sign document |
download | Download |
demoNotice | Demo — signed with the Doconut demo certificate; output is watermarked. |
signingNotEnabled | Signing is not enabled on this server. |
page / pages | 1 page / {n} pages |
Дальнейшие ключи охватывают шаг размещения, экран ошибки, связанную форму демонстрационного уведомления (demoNoticePrefix, demoNoticeLink, demoNoticeSuffix) и объявления aria-live.
Когда open или run отвечают 404 без JSON‑ошибки, виджет отображает signingNotEnabled. JSON‑ошибка от сервера всегда имеет приоритет, поэтому сообщения, такие как истёкшая загрузка, остаются видимыми.
Темизация
Виджет добавляет класс dsw к своему элементу монтирования и считывает цвета, радиусы и шрифты из пользовательских CSS‑свойств, поэтому вы можете менять тему без изменения внутренностей:
#host.dsw {
--dsw-accent: #b0522b; /* ссылки, фокус, активный режим */
--dsw-bg: #fffaf3;
--dsw-fg: #3b2a1a;
--dsw-muted: #8a7a68;
--dsw-border: #e0cbb0;
--dsw-radius: 14px;
--dsw-font: Georgia, "Times New Roman", serif;
--dsw-signature-font: "Segoe Script", "Brush Script MT", cursive; /* режим Type */
}Значения по умолчанию: --dsw-accent: #2b6cb0, --dsw-bg: #ffffff, --dsw-fg: #1a202c, --dsw-muted: #718096, --dsw-border: #cbd5e0, --dsw-radius: 8px, системный UI‑шрифт и курсивный шрифт подписи.
Создайте собственный фронтенд
Виджет является клиентом этого HTTP‑контракта на DocImage.axd. Маршруты отвечают 404, пока не будет вызвано AddSignerWidget(). Ошибки содержат тело JSON, { "error": "..." }, за исключением случаев, когда в таблице указано «только статус». Неизвестное значение ?sign= отвечает 400.
| Маршрут | Назначение | Ответ при успехе |
|---|---|---|
POST /DocImage.axd?sign=open (multipart, один файл) | Загрузить PDF или .docx и открыть его для предварительного просмотра | 200 — { token, name, pages, ext } |
POST /DocImage.axd?sign=run (JSON body) | Подписать загруженный файл | 200 — { downloadToken, downloadName, watermarked } |
GET /DocImage.axd?sign=download&token=<downloadToken> | Потоковый вывод подписанного файла | 200 — файл, Content-Disposition: attachment, Cache-Control: no-store |
ext в ответе open включает ведущую точку (".docx"). Предпросмотр страницы использует стандартный маршрут изображения просмотрщика, /DocImage.axd?token={token}&page={n}&thumb=1&width={px}; отображаемая страница становится placement.page.
Тело run:
{
"token": "GUID-from-open",
"signature": { "kind": "Drawn", "payload": "<base64 PNG, no data: prefix>" },
"placement": { "page": 1, "x": 0.58, "y": 0.80, "w": 0.32, "h": 0.12 },
"meta": { "signerName": "Ada Lovelace", "reason": "I approve", "location": "London, UK" },
"wordOutput": "pdf",
"mode": "certified"
}| Поле | Примечания |
|---|---|
token | Токен от open |
signature.kind | Drawn, Typed или Image, без учёта регистра; всё остальное превращается в Drawn. Только подсказка: полезная нагрузка всегда PNG |
signature.payload | Чистый 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 | Неправильный HTTP‑метод (open и run требуют POST, download требует GET) | только статус |
open | 400 | Не multipart‑загрузка | Expected a multipart file upload. |
open | 400 | Файл отсутствует или пустой | No file uploaded. |
open | 400 | Любое, кроме .pdf или .docx | Signing supports PDF and Word (.docx) files only. |
open | 413 | Загрузка превышает MaxUploadMb (но не пределы IIS) | File is too large. |
run | 400 | Тело не является корректным JSON или пусто | Malformed request. / Empty request. |
run | 400 | Токен отсутствует или не является GUID | Invalid token. |
run | 404 | Загрузка истекла или никогда не открывалась | Upload expired — please re-open the file. |
run | 400 | Отсутствует подпись или размещение | No signature supplied. / No placement supplied. |
run | 400 | Полезная нагрузка не в base64, пуста, слишком велика или не PNG | Signature image is not valid base64. / Signature image is empty. / Signature image is too large. / The signature image must be a PNG. |
run | 400 | Размещение находится за пределами страницы | The signature or its placement is invalid. |
run | 400 | Режим сертификации, платная лицензия и отсутствие сертификата | No signing certificate configured. |
run | 400 | Режим сертификации с сертификатом вне периода действия | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. |
open, run | 500 | Обработка не удалась | Очищенное сообщение |
download | 400 | Токен отсутствует или не является GUID | только статус |
download | 404 | Неизвестный или истёкший токен | только статус |
Полный цикл с fetch:
// file: файл для подписи; pngBase64: подпись в виде чистого base64 PNG, без префикса data:,
// например canvas.toDataURL('image/png').split(',')[1].
async function signFile(file, pngBase64) {
const base = '/DocImage.axd';
// 1. open: загрузить файл
const form = new FormData();
form.append('file', file, file.name);
const opened = await (await fetch(base + '?sign=open', { method: 'POST', body: form })).json();
// 2. run: подписать его
const signed = await (await fetch(base + '?sign=run', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
token: opened.token,
signature: { kind: 'Drawn', payload: pngBase64 },
placement: { page: 1, x: 0.58, y: 0.80, w: 0.32, h: 0.12 },
meta: { signerName: 'Ada Lovelace', reason: 'I approve', location: 'London, UK' },
wordOutput: 'pdf',
mode: 'certified'
})
})).json();
// 3. download: получить подписанный файл
const blob = await (await fetch(base + '?sign=download&token=' + encodeURIComponent(signed.downloadToken))).blob();
const link = document.createElement('a');
link.href = URL.createObjectURL(blob);
link.download = signed.downloadName;
link.click();
URL.revokeObjectURL(link.href);
}Эндпоинты имеют same-origin: эта версия не поддерживает CORS. Размещайте ваш UI и скрипт виджета с того же источника, что и приложение, или используйте reverse‑proxy DocImage.axd и /doconut-res под происхождением вашего UI.
В продакшн
-
Установите плагин рядом с основным пакетом, той же версии:
Install-Package Doconut.NETFramework.Signer. -
Добавьте файл лицензии. Поместите
Doconut.Viewer.Signer.licв ту же папку, что иDoconut.Viewer.lic. -
Получите ваш сертификат в формате PFX с закрытым ключом и цепочкой издателя, от удостоверяющего центра или собственного PKI организации. Чтобы сначала протестировать, используйте демо‑лицензию (встроенный демо‑сертификат с водяным знаком) или самоподписанный PFX.
-
Читайте сертификат из конфигурации, чтобы его изменение никогда не требовало изменения кода:
xml<appSettings> <add key="DoconutSigner:PfxPath" value="~/App_Data/your-certificate.pfx" /> </appSettings>csharpvar settings = System.Configuration.ConfigurationManager.AppSettings; Doconut.DoconutHost.Initialize(options => { options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic"); options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>(); options.AddSignerWidget(widget => widget.SigningCertificate = new SigningCertificate { PfxPath = HostingEnvironment.MapPath(settings["DoconutSigner:PfxPath"]), Password = settings["DoconutSigner:Password"] ?? "", }); });Храните
.pfxвApp_Data, который IIS никогда не обслуживает, и держите пароль вне простогоWeb.config: используйте зашифрованный раздел конфигурации или секретное хранилище, из которого читает ваше развертывание. -
Подпишите тестовый документ в режиме Certified. Сертификат, который истёк или ещё не действителен, отклоняется с
The signing certificate expired on yyyy-MM-dd.(илиis not valid before), а PDF‑ридер показывает, доверяет ли он подписи.
Доверие в PDF‑ридерах. Ридер отображает подпись как действительную, когда он доверяет корню сертификата. При PKI вашей организации это работает на каждом компьютере, который доверяет вашему корню, обычно на всех машинах внутри организации. Сертификаты, которым Adobe доверяет на любой машине (Adobe Approved Trust List), насколько нам известно, выдаются с закрытым ключом на аппаратном токене или HSM, что этот плагин использовать не может: он подписывает только из PFX. Подтвердите у поставщика сертификата, прежде чем полагаться на такой тип доверия.
Веб‑фермы
Виджет хранит каждую загрузку и её результат в памяти на сервере, который обслуживал open. За балансировщиком нагрузки без sticky‑сессий последующий запрос run, download или запрос предварительного просмотра может попасть на другой сервер и не найти загрузку. Зарегистрируйте совместное зашифрованное хранилище виджета через второй аргумент DoconutHost.Initialize:
byte[] farmKey = Convert.FromBase64String(System.Configuration.ConfigurationManager.AppSettings["Doconut:FarmKey"]);
Doconut.DoconutHost.Initialize(
options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget();
},
services => services.AddDoconutDistributedWidgets(store =>
{
store.RootPath = @"\\fileshare\doconut"; // папка, которую каждый сервер может читать и записывать
store.FarmKey = farmKey; // не менее 32 bytes, одинаково на каждом сервере
// store.Ttl = TimeSpan.FromMinutes(30); // как долго сохраняется загрузка (по умолчанию)
}));- Один сервер ничего не требует: без этого вызова используется хранилище в памяти.
- Загрузки и результаты зашифрованы в состоянии покоя на общем ресурсе (AES-256, encrypt-then-MAC), и каждый файл привязан к своему токену, поэтому один токен никогда не может прочитать файл другого.
FarmKeyдолжен быть не менее 32 байт и одинаковым на всех серверах. Загружайте его из секретного хранилища; никогда не хардкодьте. Регистрация бросаетArgumentException, когдаRootPathотсутствует илиFarmKeyкороче 32 байт.- Укажите
RootPathна то же общее расположение, которое использует распределённый просмотрщик, и предоставьте каждому серверу один и тот же сертификат подписи.
Справочник API
Фасад и параметры виджета находятся в пространстве имён Doconut; типы запросов и результатов находятся в Doconut.Core.Models.Signing. SignerPlugin находится в Doconut.Plugins.Signer.
DocumentSigner
public sealed class DocumentSigner
{
public Task<SignResult> SignAsync(
Stream source, string sourceExtension, SignRequest request,
SigningCertificate? cert = null, CancellationToken ct = default);
}Разрешено из DoconutHost.Services; конструктор является internal. sourceExtension — это ".pdf" или ".docx". При платной лицензии используется cert и вывод чистый; при временной лицензии используется встроенный демонстрационный сертификат, cert игнорируется, и вывод имеет водяной знак.
SignRequest
public sealed record SignRequest(
VisibleSignature Signature,
SignaturePlacement Placement,
string? SignerName = null,
string? Reason = null,
string? Location = null,
WordOutput WordOutput = WordOutput.Pdf,
SignatureMode Mode = SignatureMode.Certified)
{
public bool IsValid { get; } // Signature.IsValid && Placement.IsValid
}Одна видимая подпись размещается один раз, плюс необязательные метаданные подписанта.
VisibleSignature and SignatureKind
public sealed record VisibleSignature(SignatureKind Kind, byte[] PngBytes)
{
public bool IsValid { get; } // PngBytes не пустой
}
public enum SignatureKind { Drawn, Typed, Image }PngBytes — это PNG для каждого типа. Нарисованная или набранная подпись прозрачна; загруженное изображение сохраняет свою прозрачность, поэтому непрозрачный JPG остаётся непрозрачным. Kind служит лишь подсказкой.
SignaturePlacement
public readonly record struct SignaturePlacement(int Page, double X, double Y, double W, double H)
{
public bool IsValid { get; } // Page >= 1; X, Y >= 0; W, H > 0; X + W <= 1; Y + H <= 1
}Page начинается с 1; X, Y, W и H — это нормализованные 0..1 от верхнего левого угла.
SignatureMode and WordOutput
public enum SignatureMode { Certified, Visual } // Certified является значением по умолчанию
public enum WordOutput { Pdf, Docx } // Pdf является значением по умолчанию; игнорируется для PDF‑источниковSignResult
public sealed record SignResult(Stream Stream, string Extension);Подписанный документ в виде потока, поддерживающего поиск, и его расширение с точкой (".pdf" или ".docx").
SigningCertificate
public sealed class SigningCertificate
{
public byte[]? PfxBytes { get; init; }
public string? PfxPath { get; init; }
public string Password { get; init; } = "";
public bool HasMaterial { get; } // PfxBytes не пустой, либо PfxPath не пустой
}Установите либо PfxBytes, либо PfxPath, плюс Password. Сеттеры доступны только для инициализации: проект требует C# 9.0 или новее.
SignerWidgetOptions
public sealed class SignerWidgetOptions
{
public int MaxUploadMb { get; set; } = 25;
public int MaxSignatureImageKb { get; set; } = 512;
public SigningCertificate? SigningCertificate { get; set; }
}Устанавливается через DoconutOptions.AddSignerWidget(Action<SignerWidgetOptions>? configure = null), который возвращает DoconutOptions, позволяя цепочкой вызывать методы. Null SigningCertificate означает демонстрационный сертификат при временной лицензии, а визуальные подписи доступны только при платной лицензии.
Устранение неполадок
| Симптом | Причина | Решение |
|---|---|---|
Каждый запрос возвращает пустой 500 после добавления плагина; журнал событий показывает The Signer plugin is registered via AddPlugin but no active license grants Signer. | Отсутствует лицензия, файл TRIAL, лицензия без Signer, или платная лицензия вне её версии | Установите лицензию, предоставляющую Signer, или удалите AddPlugin<SignerPlugin>() |
Журнал событий показывает AddSignerWidget() was called but the Signer plugin is not registered. | Виджет включён без своего плагина | Добавьте options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>() |
Журнал событий показывает Doconut Signer: the certificate file was not found at '{path}'. | PfxPath указывает на отсутствующий файл | Исправьте путь; разместите файл там, где учётная запись пула приложений может его читать |
Журнал событий показывает Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx. | Неправильный пароль или файл не в формате PKCS#12 | Проверьте пароль; используйте настоящий .pfx |
Журнал событий показывает Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key. | PFX был экспортирован без закрытого ключа | Экспортируйте его снова с закрытым ключом |
new SigningCertificate { … } не компилируется | Проект использует C# 7.3, который не поддерживает свойства только для инициализации | Установите <LangVersion> на 9.0 или новее |
Разрешение DocumentSigner вызывает No IDocumentSigner is registered. | SignerPlugin не зарегистрирован | Добавьте AddPlugin<SignerPlugin>() в DoconutHost.Initialize |
| Вывод имеет водяной знак | Лицензия временная (Demo/NFR) | Используйте платную лицензию, предоставляющую Signer |
run отвечает 400 No signing certificate configured. | Платная лицензия, режим Certified и отсутствие сертификата | Настройте SigningCertificate, либо подпишите в визуальном режиме |
run отвечает 400 The signing certificate expired on yyyy-MM-dd. | Сертификат устарел | Замените его; визуальные подписи продолжают работать тем временем |
Виджет загружается, но показывает Signing is not enabled on this server. | AddSignerWidget() не был вызван, или basePath не является '/DocImage.axd' | Вызовите AddSignerWidget(); установите basePath: '/DocImage.axd' |
| Большая загрузка показывает страницу ошибки IIS вместо сообщения виджета | maxRequestLength / maxAllowedContentLength ниже MaxUploadMb | Увеличьте оба ограничения хоста выше MaxUploadMb |
run отвечает 400 The signature image must be a PNG., Signature image is not valid base64. или Signature image is too large. | Пользовательский 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 для DocImage.axd и /doconut-res |
| Тема не применяется | Селектор нацелен на элемент внутри монтирования | Нацелитесь непосредственно на монтирование: #host.dsw или #host |
Примечания к фреймворку
По сравнению с пакетами ASP.NET Core, этот пакет отличается только способом хостинга; API, контракт конечных точек, скрипт виджета и правила лицензирования остаются теми же.
- Регистрация находится в
Application_Start, черезDoconutHost.Initialize, вместоbuilder.Services.AddDoconut. Сервисы, такие какAddDoconutDistributedWidgets, передаются во втором аргументе. - Конечные точки обслуживаются
DocImage.axd, а скрипт —DoconutResourceModule, оба зарегистрированы вWeb.config, вместоUseDoconut()иUseDoconutResources(). Виджету требуетсяbasePath: '/DocImage.axd'. - Ошибки запуска проявляются как пустой
500при каждом запросе, причина записывается в журнал событий Windows. - Загрузки полностью считываются ASP.NET до того, как их видит Doconut, поэтому ограничения IIS должны быть выше
MaxUploadMb. - Отсутствует строка в журнале запуска о сертификате: три ошибки сертификата всё ещё выбрасываются, но строка с именем сертификата не записывается.
- C# 9.0 или новее требуется для установки init-only‑свойств
SigningCertificate. - Только Windows, как и остальные пакеты .NET Framework.
Была ли эта страница полезной?