Plugin Signer
Assine documentos PDF e Word com uma assinatura visível e um selo digital
O plugin Signer coloca uma assinatura visível em um documento e, por padrão, o sela com uma assinatura digital que um leitor de PDF pode verificar. Ele assina arquivos PDF e Word (.docx). A assinatura visível é sempre uma imagem PNG: desenhada, digitada ou enviada pelo assinante.
| Superfície | Use quando |
|---|---|
DocumentSigner (C#) | Você assina no servidor, sem envolvimento do navegador |
Drop-in widget (doconutSigner.js) | Você quer uma tela pronta de upload, assinatura e download na sua página |
Pontos de extremidade HTTP em DocImage.axd (?sign=open|run|download) | Você cria sua própria interface de assinatura contra um contrato de servidor documentado |
Cada assinatura é colocada uma única vez, em uma página. O nome do assinante, o motivo e o local podem acompanhá‑la.
Instalar o pacote
Install-Package Doconut.NETFramework.SignerPara fixar o plugin na versão que esta documentação descreve:
Install-Package Doconut.NETFramework.Signer -Version 26.10.0Mantenha o pacote Signer na mesma versão que Doconut.NETFramework.
O arquivo de licença do plugin, Doconut.Viewer.Signer.lic, deve ficar na mesma pasta que Doconut.Viewer.lic; ele é lido junto com a licença do visualizador.
Registrar o plugin
Como todo plugin Doconut, o Signer registra‑se com AddPlugin<TPlugin>() em DoconutHost.Initialize, chamado a partir de Application_Start:
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
});Adicione Doconut.DoconutHost.Shutdown() a Application_End para que o trabalho em segundo plano pare corretamente quando o pool de aplicativos for reciclado.
Isso é tudo que a fachada C# precisa. O widget e seus pontos de extremidade HTTP são uma opção separada, AddSignerWidget() (veja Widget incorporado).
O plugin precisa de uma licença que conceda a capacidade Signer. Sem ela, DoconutHost.Initialize lança uma exceção a partir de 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.No System.Web isso significa que cada requisição responde com um 500 vazio, e o motivo está apenas no log de eventos do Windows (fonte ASP.NET). Ele lança exceção por falta de licença, um arquivo legado TRIAL, uma licença sem Signer, e uma licença paga usada fora da sua janela de versão. Licenças temporárias Demo/NFR são aceitas. Veja Configuração de Licença.
Licenciamento e marca d'água
| Estado da licença | Inicialização | Assinatura certificada | Assinatura visual |
|---|---|---|---|
Licença paga concedendo Signer, certificado configurado | Inicia | Selado com seu certificado, limpo (watermarked: false) | Limpo |
Licença paga concedendo Signer, sem certificado | Inicia | Recusado: No signing certificate configured. | Limpo |
| Licença paga, certificado expirado ou ainda não válido | Inicia | Recusado: The signing certificate expired on yyyy-MM-dd. | Limpo |
| Licença temporária Demo/NFR, ativa ou expirada | Inicia | Selado com o certificado demo incorporado, marca d'água (watermarked: true) | Com marca d'água |
Sem licença, um arquivo legado TRIAL, uma licença sem Signer, ou uma licença paga fora da sua janela de versão | Lança Application_Start; cada requisição responde um 500 vazio | — | — |
A regra é a mesma para a fachada C# e o widget: a saída recebe marca d'água quando a licença não é uma licença de visualizador paga ou é temporária. Sob uma licença temporária o plugin sempre assina com seu certificado demo incorporado, e qualquer certificado que você configure não é usado.
O certificado demo produz um selo genuíno, mas os leitores de PDF não o confiam. Uma integração pode ser construída e testada de ponta a ponta com uma licença de avaliação; para obter uma saída limpa e confiável você precisa tanto de uma licença paga quanto do seu próprio certificado de assinatura.
Uso em C#
DocumentSigner é registrado por DoconutHost.Initialize; resolva‑o a partir de DoconutHost.Services. Seu construtor é interno, portanto nunca o new. Resolver sem AddPlugin<SignerPlugin>() lança 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 tem como padrão Certified (assinatura visível + selo digital); WordOutput tem como padrão 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 recebe o fluxo de origem, sua extensão (".pdf" ou ".docx"), a requisição e o certificado para esta chamada. A fachada não lê SignerWidgetOptions.SigningCertificate; essa configuração é para o widget. Passe null sob uma licença demo, ou no modo Visual.
SignResult contém o documento assinado como um fluxo pesquisável, além de seu Extension (".pdf" ou ".docx") para que você possa nomear o arquivo. Você possui o fluxo: descarte‑o quando terminar.
Em um controlador MVC 5
Torne a ação assíncrona e await a assinatura. Esta adiciona uma assinatura Visual, que não requer certificado:
[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);
}Uma fonte Word é assinada para PDF a menos que você solicite saída Word. Nomeie o resultado a partir de 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 lança exceção em vez de retornar quando a chamada não pode ser bem‑sucedida:
| Exceção | Mensagem | Quando |
|---|---|---|
InvalidOperationException | No signing certificate configured. | Modo certificado, licença paga, e nenhum certificado fornecido |
InvalidOperationException | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. | Modo certificado com um certificado fora da sua janela de validade |
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. | Bytes PNG vazios, ou um posicionamento que não é válido |
NotSupportedException | The signer supports PDF and Word (.docx) documents; got '{extension}'. | Qualquer outro tipo de fonte |
Modos de assinatura, saída do Word e certificados
Modos de assinatura
SignRequest.Mode escolhe se a assinatura é selada.
| Modo | O que produz | Certificado | Verificável |
|---|---|---|---|
SignatureMode.Certified (padrão) | A assinatura visível mais um selo digital | Obrigatório sob licença paga | Sim |
SignatureMode.Visual | Apenas a assinatura visível | Nunca necessário | Não: é uma imagem |
Use Certified quando a assinatura deve ser comprovável: aprovações, contratos, qualquer coisa que um verificador precise checar para identidade e integridade. Use Visual quando você só precisa da aparência de uma assinatura, ou não tem certificado. Uma licença temporária marca ambas com marca d'água.
Selos PDF são assinaturas PKCS#7 destacadas (adbe.pkcs7.detached) com SHA-256, para chaves RSA ou ECDSA. Elas carregam os certificados do emissor encontrados no seu PFX, de modo que um leitor que confia na sua raiz pode construir a cadeia. Selos nativos do Word são assinaturas de pacote OOXML e carregam apenas o certificado do assinante.
Documentos Word
Para uma fonte .docx, SignRequest.WordOutput escolhe a saída. É ignorado para fontes PDF, que sempre produzem um PDF.
| Saída | O que acontece | Suporte do verificador |
|---|---|---|
WordOutput.Pdf (padrão) | O documento é convertido para PDF, então assinado e selado | Amplo: um PDF assinado verifica em qualquer lugar |
WordOutput.Docx | O documento permanece em Word: a imagem da assinatura é inserida nele, além de uma assinatura de pacote OOXML | Limitado: nem todo visualizador exibe assinaturas de pacote OOXML |
Mantenha PDF a menos que o destinatário precise de um arquivo Word editável e aceite o suporte limitado do verificador.
Configuração de certificado
Para selar com sua própria identidade, forneça ao plugin um arquivo PFX (PKCS#12) que inclua a chave privada. Para o widget, defina SignerWidgetOptions.SigningCertificate; para a fachada C#, passe o certificado para SignAsync. Forneça os bytes ou um caminho, além da senha. App_Data é um bom local para o arquivo, porque o IIS nunca o serve:
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"] ?? "",
};
});
});As propriedades de SigningCertificate são apenas init, o que o C# 7.3 (o padrão para projetos .NET Framework) não pode definir. Defina <LangVersion> para 9.0 ou posterior no arquivo de projeto.
O certificado é mantido apenas na memória. Nunca é registrado, retornado a um cliente, ou persistido, e a senha nunca aparece em uma mensagem de erro.
Requisitos:
- Um pacote PFX / PKCS#12 com sua chave privada. Um arquivo somente de chave pública (
.cer,.crt) não pode assinar. Exporte a cadeia do emissor com ele, para que os selos PDF possam carregá‑la. - A senha correta.
- Dentro da sua janela de validade. Um certificado expirado ou ainda não válido não interrompe o aplicativo, mas assinaturas Certified são recusadas até que seja substituído. Assinaturas Visual não são afetadas.
- Emitido para assinatura de documentos: um uso de chave com digital signature ou non-repudiation, e um uso estendido de chave, se presente, que permite assinatura de documentos, proteção de e‑mail ou autenticação de cliente. Um certificado emitido para outra finalidade, como um certificado de servidor TLS, ainda assina, mas leitores PDF sinalizam a assinatura.
- Tokens de hardware, smart cards, HSMs e o armazenamento de certificados do Windows não são suportados. Exporte o certificado, com sua chave privada e cadeia, para um PFX.
Crie um PFX a partir de um certificado e sua chave privada com OpenSSL:
openssl pkcs12 -export -out signing.pfx -inkey private.key -in certificate.crt
# A senha de exportação solicitada é SigningCertificate.Password.Exporte um do armazenamento de certificados do Windows: abra certmgr.msc e encontre o certificado (seu ícone mostra uma chave quando a chave privada está presente). Clique com o botão direito, escolha All Tasks → Export…, selecione Yes, export the private key, escolha Personal Information Exchange – PKCS #12 (.PFX) e defina uma senha.
Verificações de inicialização
Quando o widget está habilitado, o certificado em SignerWidgetOptions.SigningCertificate é verificado uma vez, dentro de DoconutHost.Initialize, de modo que um PFX mal configurado falha na inicialização em vez de na primeira assinatura. Três problemas lançam um InvalidOperationException de Application_Start, e cada requisição então responde com um 500 vazio; a mensagem está no log de eventos do Windows:
| Mensagem | Correção |
|---|---|
Doconut Signer: the certificate file was not found at '{path}'. | Corrija PfxPath; certifique‑se de que o arquivo está implantado e legível pela conta do pool de aplicativos |
Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx. | Verifique a senha; certifique‑se de que o arquivo é um .pfx real, não um .cer ou .pem |
Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key. | Exporte o PFX novamente com a chave privada |
No ASP.NET Core o host também registra uma linha na inicialização nomeando o certificado, ou avisando que ele está expirado ou não emitido para assinatura. DoconutHost não grava essa linha, portanto no .NET Framework verifique um novo certificado assinando um documento de teste no modo Certified.
A fachada C# não é verificada na inicialização. O certificado que você passa para SignAsync é lido quando você assina, de modo que um caminho ou senha incorretos falham nessa chamada.
Widget incorporado
Habilitar os endpoints
Os endpoints ?sign=open|run|download do widget são servidos por DocImage.axd e estão desativados por padrão. Habilite-os ao lado do registro do plugin:
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>();
options.AddSignerWidget(widget =>
{
widget.MaxUploadMb = 25; // o padrão
widget.MaxSignatureImageKb = 512; // o padrão
// widget.SigningCertificate: veja a configuração do Certificate; deixe null para assinatura de demonstração (com marca d'água)
});
});
// System.Web lê todo o upload antes que Doconut o veja: mantenha maxRequestLength (KB) e
// maxAllowedContentLength (bytes) em Web.config acima do MaxUploadMb do widget.AddSignerWidget() sem argumento habilita o widget com as configurações padrão. Ele não concede assinatura por si só: precisa de AddPlugin<SignerPlugin>(), ou DoconutHost.Initialize lança:
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.Os endpoints e o script são servidos pelo manipulador e pelo módulo registrado em 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>O módulo serve o script independentemente de o widget estar habilitado. Sem AddSignerWidget(), o widget carrega e desenha sua zona de arraste, e sua primeira requisição responde 404: o widget então relata Signing is not enabled on this server.
Limites de upload
ASP.NET lê todo o corpo da requisição antes que DocImage.axd seja executado. Um upload acima de MaxUploadMb mas abaixo dos limites do host obtém o JSON próprio do widget 413 (File is too large.). Um upload acima dos limites do host é rejeitado primeiro pelo IIS, com uma página de erro que o widget não consegue ler. Mantenha ambos os limites do host acima do limite do widget:
<system.web>
<httpRuntime maxRequestLength="30720" /> <!-- KILOBYTES: 30 MB -->
</system.web>
<system.webServer>
<security>
<requestFiltering>
<requestLimits maxAllowedContentLength="31457280" /> <!-- BYTES: 30 MB -->
</requestFiltering>
</security>
</system.webServer>Um upload enviado sem um Content-Length (chunked) que excede os limites do host também recebe a página de erro do IIS; não há solução alternativa para esse caso.
Incorporar
O script é servido em /doconut-res/js/doconutSigner.js. É um único arquivo autônomo, sem dependências. Aponte basePath para o manipulador:
<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) aceita um seletor CSS ou um elemento, lança erro se o ponto de montagem não for encontrado e retorna um manipulador. O basePath padrão do widget, /doconut, é o endpoint ASP.NET Core; neste pacote ele deve ser '/DocImage.axd'.
O assinante envia um PDF ou um arquivo .docx, cria uma assinatura (Draw em um canvas, Type um nome em uma fonte de assinatura, ou Image a partir de um PNG, JPG ou GIF), arrasta e redimensiona‑a na página, e assina e baixa o resultado. O widget sempre envia a assinatura como PNG; uma imagem enviada é convertida no navegador para PNG que se ajusta a 520×160.
Opções
| Opção | Tipo | Padrão | Observações |
|---|---|---|---|
basePath | string | '/doconut' | Onde os endpoints ?sign= e as imagens de pré‑visualização são servidos. Defina '/DocImage.axd' neste pacote |
resPath | string | '/doconut-res' | Reservado; o widget inclui seu próprio CSS |
maxUploadMb | number | 25 | Apenas verificação no cliente, portanto um arquivo muito grande falha rapidamente. O limite do servidor é MaxUploadMb em AddSignerWidget |
maxSignatureKb | number | 512 | Limite no cliente para o modo Imagem. Mantenha igual ao MaxSignatureImageKb do servidor |
previewWidth | number | 560 | Largura em pixels da pré‑visualização da página |
licenseUrl | string | null | null | Transforma o aviso de marca d'água da demonstração em um link para esta URL |
signatureMode | string | 'certified' | Tipo de assinatura inicial: 'certified' ou 'visual'. Qualquer outro valor torna‑se 'certified' |
showSignatureModeToggle | boolean | true | Exibe a opção Digital signature / Visual only. Com false, o widget assina com signatureMode |
wordOutput | string | 'pdf' | Saída inicial para fontes .docx: 'pdf' ou 'docx'. Qualquer outro valor torna‑se 'pdf' |
showOutputFormatToggle | boolean | true | Exibe a opção PDF / Word, apenas para fontes .docx. Com false, o widget usa wordOutput |
labels | object | {} | Sobrescreve qualquer subconjunto das strings em inglês |
Ocultar um alternador não desativa a funcionalidade; ele fixa o valor. Duas configurações comuns:
// Ambos os alternadores são exibidos, assinatura digital por padrão: um assinante completo de autoatendimento.
Doconut.signer('#host', { basePath: '/DocImage.axd', licenseUrl: '/pricing' });// Apenas visual, sem alternador: um selo simples sem assinatura digital oferecida.
Doconut.signer('#host', {
basePath: '/DocImage.axd',
signatureMode: 'visual',
showSignatureModeToggle: false
});Retornos de chamada
| Retorno | Dispara quando | Carga |
|---|---|---|
onReady | Uma vez, ao montar (não novamente em reset()) | — |
onSourceLoaded | O arquivo é aberto e sua pré‑visualização é mostrada | { file: { token, name, pages, ext } } |
onSigned | A assinatura tem sucesso | { downloadToken, downloadName, watermarked } |
onDownload | Em cada clique em Download | { downloadName, downloadToken } |
onError | Uma etapa de abrir, assinar ou baixar falha, ou um arquivo no modo Imagem é muito grande | { message } |
Um retorno de chamada que lança exceção é capturado e registrado; nunca interrompe o fluxo do widget.
Manipulador imperativo
| Método | Comportamento |
|---|---|
reset() | Retorna à tela de arraste e limpa o fluxo atual. Não dispara onReady novamente. Não faz nada após destroy() |
loadFile(file) | Inicia o fluxo com um File. Não faz nada a menos que o widget esteja na tela de arraste; chame reset() primeiro se necessário |
destroy() | Remove os ouvintes, esvazia o ponto de montagem e congela a instância |
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());Rótulos
Cada string tem um padrão em inglês; labels substitui qualquer subconjunto e o restante permanece em inglês. Fragmentos que mudam em tempo de execução usam {placeholders}, como uploading: 'Uploading {name}…' e pages: '{n} pages'.
| Chave | Padrão em inglês |
|---|---|
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 |
Outras chaves cobrem a etapa de posicionamento, a tela de erro, o formulário vinculado do aviso de demonstração (demoNoticePrefix, demoNoticeLink, demoNoticeSuffix) e os anúncios aria-live.
Quando open ou run respondem 404 sem erro JSON, o widget exibe signingNotEnabled. Um erro JSON do servidor sempre tem precedência, portanto mensagens como um upload expirado permanecem visíveis.
Tematização
O widget adiciona a classe dsw ao seu elemento de montagem e lê suas cores, raio e fontes das propriedades personalizadas CSS, para que você possa tematizá‑lo sem tocar em seus internos:
#host.dsw {
--dsw-accent: #b0522b; /* links, foco, modo ativo */
--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; /* o modo Type */
}Padrões: --dsw-accent: #2b6cb0, --dsw-bg: #ffffff, --dsw-fg: #1a202c, --dsw-muted: #718096, --dsw-border: #cbd5e0, --dsw-radius: 8px, uma fonte de interface do sistema e uma fonte cursiva para assinatura.
Construa seu próprio frontend
O widget é um cliente para este contrato HTTP em DocImage.axd. As rotas respondem 404 até que AddSignerWidget() seja chamado. Erros carregam um corpo JSON, { "error": "..." }, exceto onde a tabela indica “apenas status”. Um valor desconhecido de ?sign= responde 400.
| Rota | Propósito | Resposta de sucesso |
|---|---|---|
POST /DocImage.axd?sign=open (multipart, um arquivo) | Carregue um PDF ou .docx e abra‑o para visualização | 200 — { token, name, pages, ext } |
POST /DocImage.axd?sign=run (corpo JSON) | Assine o arquivo carregado | 200 — { downloadToken, downloadName, watermarked } |
GET /DocImage.axd?sign=download&token=<downloadToken> | Transmita o arquivo assinado | 200 — o arquivo, Content-Disposition: attachment, Cache-Control: no-store |
ext na resposta open inclui o ponto inicial (".docx"). A visualização da página usa a rota padrão de imagem do visualizador, /DocImage.axd?token={token}&page={n}&thumb=1&width={px}; a página exibida torna‑se placement.page.
O corpo 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"
}| Campo | Observações |
|---|---|
token | O token de open |
signature.kind | Drawn, Typed ou Image, sem diferenciação de maiúsculas/minúsculas; qualquer outro valor torna‑se Drawn. Apenas uma dica: a carga útil é sempre um PNG |
signature.payload | Um PNG base64 puro, sem prefixo data:. Deve ser um PNG real e não maior que MaxSignatureImageKb após decodificado |
placement.page | Baseado em 1 |
placement.x / y / w / h | Normalizado 0..1 a partir do canto superior esquerdo, com x + w ≤ 1 e y + h ≤ 1 |
meta.signerName / reason / location | Opcional. Cada um é aparado, um valor em branco é descartado, e cada um é truncado em 256 caracteres |
wordOutput | pdf (padrão) ou docx; ignorado para fontes PDF. Qualquer outro valor torna‑se pdf |
mode | certified (padrão) ou visual. Qualquer outro valor torna‑se certified |
downloadName segue a saída: <source>-signed.pdf ou <source>-signed.docx, e download envia o Content-Type correspondente.
A fonte carregada e o resultado assinado são mantidos cada um por 30 minutos. Depois disso, run e download respondem 404 e o arquivo deve ser aberto novamente. Todos os tokens são GUIDs.
| Rota | Status | Quando | Corpo |
|---|---|---|---|
| qualquer | 404 | O widget não está habilitado | apenas status |
| qualquer | 405 | Verbo errado (open e run precisam de POST, download precisa de GET) | apenas status |
open | 400 | Não é um upload multipart | Expected a multipart file upload. |
open | 400 | Nenhum arquivo, ou um vazio | No file uploaded. |
open | 400 | Qualquer coisa diferente de .pdf ou .docx | Signing supports PDF and Word (.docx) files only. |
open | 413 | O upload excede MaxUploadMb (mas não os limites do IIS) | File is too large. |
run | 400 | O corpo não é JSON válido, ou está vazio | Malformed request. / Empty request. |
run | 400 | O token está ausente ou não é um GUID | Invalid token. |
run | 404 | O upload expirou ou nunca foi aberto | Upload expired — please re-open the file. |
run | 400 | Sem assinatura, ou sem posicionamento | No signature supplied. / No placement supplied. |
run | 400 | A carga útil não é base64, está vazia, muito grande, ou não é um 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 | O posicionamento está fora da página | The signature or its placement is invalid. |
run | 400 | Modo certificado, licença paga e sem certificado | No signing certificate configured. |
run | 400 | Modo certificado com um certificado fora da janela de validade | The signing certificate expired on yyyy-MM-dd. / The signing certificate is not valid before yyyy-MM-dd. |
open, run | 500 | Processamento falhou | Uma mensagem sanitizada |
download | 400 | O token está ausente ou não é um GUID | apenas status |
download | 404 | Token desconhecido ou expirado | apenas status |
Um ciclo completo com fetch:
// file: o File para assinar; pngBase64: a assinatura como um PNG base64 puro, sem prefixo data:,
// por exemplo canvas.toDataURL('image/png').split(',')[1].
async function signFile(file, pngBase64) {
const base = '/DocImage.axd';
// 1. open: carregar o arquivo
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: assiná-lo
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: obter o arquivo assinado
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);
}Os endpoints são same-origin: esta versão não tem suporte a CORS. Sirva sua UI e o script do widget a partir da mesma origem da aplicação, ou faça reverse-proxy de DocImage.axd e /doconut-res sob a origem da sua UI.
Em produção
-
Instale o plugin ao lado do pacote core, na mesma versão:
Install-Package Doconut.NETFramework.Signer. -
Adicione o arquivo de licença. Coloque
Doconut.Viewer.Signer.licna mesma pasta queDoconut.Viewer.lic. -
Obtenha seu certificado como um PFX com sua chave privada e cadeia de emissor, de uma autoridade certificadora ou da PKI própria da sua organização. Para experimentar primeiro, use uma licença demo (o certificado demo embutido, com marca d'água) ou um PFX autoassinado.
-
Leia o certificado a partir da configuração, de modo que alterá‑lo nunca exija mudança de código:
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"] ?? "", }); });Mantenha o
.pfxemApp_Data, que o IIS nunca serve, e mantenha a senha fora de umWeb.configsimples: use uma seção de configuração criptografada, ou um repositório secreto que sua implantação lê. -
Assine um documento de teste no modo Certified. Um certificado que está expirado ou ainda não é válido é recusado com
The signing certificate expired on yyyy-MM-dd.(ouis not valid before), e um leitor de PDF mostra se ele confia na assinatura.
Confiança em leitores de PDF. Um leitor mostra a assinatura como válida quando confia na raiz do certificado. Com a PKI da sua organização, isso vale para cada máquina que confia na sua raiz, que normalmente são todas as máquinas dentro da organização. Certificados que a Adobe confia em qualquer máquina (a Adobe Approved Trust List) são, até onde sabemos, emitidos com a chave privada em um token de hardware ou HSM, o que este plugin não pode usar: ele assina apenas a partir de um PFX. Confirme com seu provedor de certificados antes de confiar nesse tipo de confiança.
Fazendas web
O widget mantém cada upload e seu resultado na memória no servidor que serviu open. Por trás de um balanceador de carga sem sessões persistentes, uma solicitação posterior de run, download ou de pré‑visualização pode alcançar outro servidor e não encontrar o upload. Registre o armazenamento compartilhado e criptografado do widget através do segundo argumento de 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"; // uma pasta que todo servidor pode ler e gravar
store.FarmKey = farmKey; // pelo menos 32 bytes, idêntico em todo servidor
// store.Ttl = TimeSpan.FromMinutes(30); // quanto tempo um upload é mantido (o padrão)
}));- Um único servidor não precisa de nada: sem esta chamada, o armazenamento em memória é usado.
- Uploads e resultados são criptografados em repouso no compartilhamento (AES-256, encrypt-then-MAC), e cada arquivo está vinculado ao seu token, de modo que um token nunca pode ler o arquivo de outro.
FarmKeydeve ter pelo menos 32 bytes e ser o mesmo em todos os servidores. Carregue-o de um repositório secreto; nunca o codifique diretamente. O registro lança umArgumentExceptionquandoRootPathestá ausente ouFarmKeytem menos de 32 bytes.- Aponte
RootPathpara o mesmo local compartilhado que o visualizador distribuído usa, e forneça a cada servidor o mesmo certificado de assinatura.
Referência da API
A fachada e as opções do widget estão no namespace Doconut; os tipos de solicitação e resultado estão em Doconut.Core.Models.Signing. SignerPlugin está em Doconut.Plugins.Signer.
AssinadorDeDocumento
public sealed class DocumentSigner
{
public Task<SignResult> SignAsync(
Stream source, string sourceExtension, SignRequest request,
SigningCertificate? cert = null, CancellationToken ct = default);
}Resolvido a partir de DoconutHost.Services; o construtor é interno. sourceExtension é ".pdf" ou ".docx". Sob uma licença paga, cert é usado e a saída é limpa; sob uma licença temporária, o certificado de demonstração embutido é usado, cert é ignorado, e a saída recebe marca d'água.
SolicitaçãoDeAssinatura
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
}Uma assinatura visível colocada uma vez, mais metadados opcionais do assinante.
AssinaturaVisível e TipoDeAssinatura
public sealed record VisibleSignature(SignatureKind Kind, byte[] PngBytes)
{
public bool IsValid { get; } // PngBytes não está vazio
}
public enum SignatureKind { Drawn, Typed, Image }PngBytes é um PNG para cada tipo. Uma assinatura desenhada ou digitada é transparente; uma imagem enviada mantém a transparência que tinha, portanto um JPG opaco permanece opaco. Kind é apenas uma dica.
PosicionamentoDeAssinatura
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 é baseado em 1; X, Y, W e H são 0..1 normalizados a partir do canto superior esquerdo.
ModoDeAssinatura e SaídaWord
public enum SignatureMode { Certified, Visual } // Certified é o padrão
public enum WordOutput { Pdf, Docx } // Pdf é o padrão; ignorado para fontes PDFResultadoDaAssinatura
public sealed record SignResult(Stream Stream, string Extension);O documento assinado como um fluxo buscável, e sua extensão com o ponto (".pdf" ou ".docx").
CertificadoDeAssinatura
public sealed class SigningCertificate
{
public byte[]? PfxBytes { get; init; }
public string? PfxPath { get; init; }
public string Password { get; init; } = "";
public bool HasMaterial { get; } // PfxBytes não está vazio, ou PfxPath não está em branco
}Defina ou PfxBytes ou PfxPath, além de Password. Os setters são apenas init: o projeto requer C# 9.0 ou posterior.
OpçõesDoWidgetDeAssinante
public sealed class SignerWidgetOptions
{
public int MaxUploadMb { get; set; } = 25;
public int MaxSignatureImageKb { get; set; } = 512;
public SigningCertificate? SigningCertificate { get; set; }
}Defina através de DoconutOptions.AddSignerWidget(Action<SignerWidgetOptions>? configure = null), que retorna o DoconutOptions para que as chamadas possam ser encadeadas. Um SigningCertificate nulo significa o certificado de demonstração sob uma licença temporária, e assinaturas Visuais somente sob uma licença paga.
Solução de Problemas
| Sintoma | Causa | Correção |
|---|---|---|
Todas as solicitações retornam um 500 vazio após adicionar o plugin; o log de eventos mostra The Signer plugin is registered via AddPlugin but no active license grants Signer. | Sem licença, um arquivo TRIAL, uma licença sem Signer, ou uma licença paga fora da sua janela de versão | Instale uma licença que conceda Signer, ou remova AddPlugin<SignerPlugin>() |
O log de eventos mostra AddSignerWidget() was called but the Signer plugin is not registered. | O widget está habilitado sem seu plugin | Adicione options.AddPlugin<Doconut.Plugins.Signer.SignerPlugin>() |
O log de eventos mostra Doconut Signer: the certificate file was not found at '{path}'. | PfxPath aponta para um arquivo ausente | Corrija o caminho; implante o arquivo onde a conta do pool de aplicativos possa lê-lo |
O log de eventos mostra Doconut Signer: the signing certificate could not be opened — the password is incorrect or the file is not a valid .pfx. | Senha errada, ou não é um arquivo PKCS#12 | Verifique a senha; use um verdadeiro .pfx |
O log de eventos mostra Doconut Signer: the signing certificate has no private key. Re-export the .pfx INCLUDING the private key. | O PFX foi exportado sem sua chave privada | Exporte novamente com a chave privada |
new SigningCertificate { … } não compila | O projeto usa C# 7.3, que não pode definir propriedades somente init | Defina <LangVersion> para 9.0 ou posterior |
Resolver DocumentSigner lança No IDocumentSigner is registered. | SignerPlugin não está registrado | Adicione AddPlugin<SignerPlugin>() em DoconutHost.Initialize |
| A saída tem marca d'água | A licença é temporária (Demo/NFR) | Use uma licença paga que conceda Signer |
run responde 400 No signing certificate configured. | Uma licença paga, modo Certificado, e sem certificado | Configure SigningCertificate, ou assine no modo Visual |
run responde 400 The signing certificate expired on yyyy-MM-dd. | O certificado está desatualizado | Substitua-o; assinaturas Visuais continuam funcionando enquanto isso |
O widget carrega mas diz Signing is not enabled on this server. | AddSignerWidget() não foi chamado, ou basePath não está '/DocImage.axd' | Chame AddSignerWidget(); defina basePath: '/DocImage.axd' |
| Um upload grande mostra uma página de erro IIS ao invés da mensagem do widget | maxRequestLength / maxAllowedContentLength estão abaixo de MaxUploadMb | Aumente ambos os limites de host acima de MaxUploadMb |
run responde 400 The signature image must be a PNG., Signature image is not valid base64. ou Signature image is too large. | Uma UI personalizada enviou uma URL data:, um JPG, ou mais de MaxSignatureImageKb | Envie um PNG base64 puro dentro do limite |
open responde 413 File is too large. | O upload excede MaxUploadMb | Aumente MaxUploadMb em AddSignerWidget; o maxUploadMb do widget é apenas uma verificação do lado do cliente |
run ou download responde 404 Upload expired — please re-open the file. | A janela de 30 minutos expirou, ou outro servidor na fazenda não tem o upload | Abra o arquivo novamente; em uma fazenda, registre AddDoconutDistributedWidgets |
Um .docx assinado não mostra assinatura em alguns visualizadores | A saída Word contém uma assinatura de pacote OOXML, que muitos visualizadores não exibem | Assine para PDF, o padrão |
| Leitores de PDF dizem que a identidade do assinante é desconhecida | O leitor não confia na raiz do certificado (o certificado de demonstração nunca é confiável) | Use um certificado de uma raiz que seus leitores confiem |
| O widget falha quando a UI está em outra origem | Os endpoints não têm suporte a CORS | Sirva a UI da mesma origem, ou faça reverse-proxy de DocImage.axd e /doconut-res |
| O tema não é aplicado | O seletor aponta para um elemento dentro da montagem | Aponte para a própria montagem: #host.dsw ou #host |
Notas do framework
Comparado aos pacotes ASP.NET Core, este pacote difere apenas na hospedagem; a API, o contrato de endpoint, o script do widget e as regras de licenciamento são os mesmos.
- Registro está em
Application_Start, através deDoconutHost.Initialize, em vez debuilder.Services.AddDoconut. Serviços comoAddDoconutDistributedWidgetsvão em seu segundo argumento. - Endpoints são servidos por
DocImage.axde o script porDoconutResourceModule, ambos registrados emWeb.config, em vez deUseDoconut()eUseDoconutResources(). O widget precisa debasePath: '/DocImage.axd'. - Falhas de inicialização aparecem como um
500vazio em cada requisição, com a razão no log de eventos do Windows. - Uploads são lidos completamente pelo ASP.NET antes que o Doconut os veja, portanto os limites do IIS devem estar acima de
MaxUploadMb. - Nenhuma linha de log de inicialização sobre o certificado: os três erros de certificado ainda são lançados, mas a linha que nomeia o certificado não é escrita.
- C# 9.0 ou posterior é necessário para definir as propriedades somente de inicialização de
SigningCertificate. - Somente Windows, como o resto do pacote .NET Framework.
Esta página foi útil?